Add a tested PyTorch shape lesson

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+logo.png filter=lfs diff=lfs merge=lfs -text

DESIGN.md

@@ -0,0 +1,39 @@
+# Design and acceptance notes
+
+This is an interactive educational page, not an installation landing page.
+The design uses the existing tensorViz white background, dark green mark and
+system fonts. The canonical supplied logo is copied unchanged and never redrawn.
+The [Hugging Face configuration reference](https://huggingface.co/docs/hub/spaces-config-reference)
+supports a `thumbnail` URL for social sharing. The README points that field at
+the immutable public copy of the supplied logo; the lesson loads its local copy.
+
+## Surface and controls
+
+- Header: supplied logo, `tensorViz / shape lab`, runnable-example link.
+- Introduction: one problem statement and an explicit arithmetic-only boundary.
+- Main lesson: batch/height/width inputs, three spatial presets and three
+  classifier choices alongside an ordered shape trace. Mismatch/success uses
+  both text and restrained color. Linear weight/transposed dimensions are explicit.
+- Reshape counterexample: compare original feature-map rows with the inferred
+  first dimension. Distinguish changed batch, impossible reshape and redundant
+  reshape when the width already matches.
+- Conclusion: preserve batch, declare the intended input contract, and separate
+  shape compatibility from numerical correctness. Optional public source and
+  recorded-model links are available without an embedded remote page.
+
+Main content is at most 1,040 pixels wide inside a 1,136-pixel outer container.
+Below 760 pixels, controls precede results. Below 390 pixels, shape labels and
+values stack. Interactive targets have native labels and keyboard focus styles;
+validation/results use status announcements. No animation or external fonts.
+
+## Rendered acceptance
+
+The design follows the existing brand directly; no generated concept is used.
+Automated arithmetic checks do not establish rendered acceptance.
+
+Check the actual page on desktop and at 320-pixel width before publication:
+logo proportions, legible controls/shapes, no horizontal
+overflow, all presets/modes/reset, empty and invalid fields, keyboard focus,
+long error wrapping and the optional links. The exact example must begin with
+`(2x512 and 128x5)`, and the unsafe reshape must show two images becoming eight
+rows. Record observed results separately from arithmetic tests.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tensorViz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,12 +1,91 @@
 ---
-title: Pytorch Shape Lab
-emoji: 🐠
-colorFrom: blue
-colorTo: purple
+title: PyTorch Shape Lab
+emoji: 🧮
+colorFrom: green
+colorTo: gray
 sdk: static
+app_file: index.html
 pinned: false
 license: mit
-short_description: Follow PyTorch shapes and fix a flatten-to-Linear mismatch.
+short_description: Follow a CNN's shapes without losing the batch dimension.
+thumbnail: https://raw.githubusercontent.com/tensorviz-org/tensorviz-examples/6e5cdcfc8ec3ab39c0bb1264bf534210ae5c1981/assets/tensorviz-logo-white.png
+tags:
+  - pytorch
+  - education
+  - tensor-shapes
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# PyTorch shape lab
+
+A small interactive lesson by **tensorViz**. Change the batch and image size,
+follow a fixed convolution/pooling stack, and find a mismatch at `Linear`.
+Compare a correctly sized fixed head with an explicit architecture change using
+adaptive average pooling. See how `reshape(-1, 128)` can silently change the
+number of samples.
+
+**This is shape arithmetic, not model execution.** The browser runs no Python,
+inference, training or tensorViz backend. Compatible shapes do not establish
+prediction quality or numerical equivalence. The lesson code has no tracking,
+third-party script, iframe, runtime fetch or account requirement. External
+resources load only when the reader follows a link. This describes the lesson
+code, not the hosting platform's ordinary request handling or platform analytics.
+
+The original executable example is
+[available with its checks and explanation](https://github.com/tensorviz-org/tensorviz-examples/blob/1baecebf25ff1067a9112bde382c0a398fb99747/examples/shape-mismatch/README.md).
+The static arithmetic was independently checked against actual CPU PyTorch
+operations; see [validation](VALIDATION.md).
+
+## Run locally
+
+No package installation or build is needed. Serve this folder using an existing
+Python installation:
+
+```sh
+python3 -m http.server 4177 --bind 127.0.0.1
+```
+
+Open `http://127.0.0.1:4177`. ES modules need an HTTP server; opening `index.html`
+as a local `file:` URL is not the supported preview path.
+
+## Lesson boundaries
+
+- The fixed feature stack is `Conv2d(3, 8, kernel_size=3, padding=1)`, `ReLU`,
+  `MaxPool2d(2)`, then `Flatten(start_dim=1)`.
+- Inputs are NCHW with three channels. This teaching UI accepts batch 1–64 and
+  integer height/width 2–256. These UI bounds are not a general PyTorch limit.
+- Pooling uses the default stride of two, padding zero and `ceil_mode=False`.
+  Odd spatial dimensions round down.
+- The original head expects 128 features. A 16 × 16 image yields 512. A fixed
+  512-feature head fits that example, but not every other input size.
+- The optional adaptive pool reduces each of the eight spatial channels to one
+  value and uses an eight-feature head. That changes computation and parameters;
+  it is not an interchangeable pretrained checkpoint repair.
+- The unsafe reshape demonstration uses the original feature map before any
+  adaptive pool and the original 128-feature head.
+
+For real model exploration, [tensorViz's recorded browser examples](https://tensorviz.dev/explore/)
+are an optional next step. Capturing your own PyTorch model requires the separate
+tensorViz extension and your model environment. This repository contains only
+the lesson, not extension implementation.
+
+## Validate changes
+
+Use existing Node.js and a Python environment with PyTorch installed. Nothing in
+the checks downloads dependencies or enables telemetry.
+
+```sh
+node --test shape-math.test.mjs
+python verify_pytorch.py
+```
+
+`verify_pytorch.py` also invokes Node.js to compare the JavaScript results with
+PyTorch. Visual and accessibility acceptance remain separate from these checks.
+The intended layout and review cases are in [design notes](DESIGN.md).
+
+## License and attribution
+
+Original lesson code and documentation are [MIT licensed](LICENSE), including
+the small test model derived from the public tensorViz example linked above.
+PyTorch is a separate dependency under its own license. The supplied tensorViz
+logo identifies the project; this license does not grant trademark rights.
+The extension and its dependencies retain their own licenses.

VALIDATION.md

@@ -0,0 +1,68 @@
+# Validation
+
+This page models a fixed CPU-compatible PyTorch example. It does not execute
+Python in the browser or provide a general-purpose shape inference engine.
+
+The JavaScript tests cover the canonical mismatch, batch-preserving fixed head,
+non-square inputs, floor pooling for odd dimensions, adaptive-pooling dimensions,
+unsafe reshape, and invalid input rejection. The separate Python check invokes
+actual PyTorch Conv2d, ReLU, MaxPool2d, Flatten, Linear and AdaptiveAvgPool2d,
+then compares their shapes and errors with the JavaScript calculator for 21 cases.
+For successful paths it also compares full-batch and per-image outputs.
+
+## Executed checks — October 11, 2026
+
+Environment: Node.js **26.5.0**, Python **3.12.14**, PyTorch **2.7.1**, CPU.
+No dependencies were downloaded or installed for this check.
+
+- **5 JavaScript tests passed**, zero failures and zero skips.
+- **21 actual PyTorch comparisons passed**: all three heads for batch/image
+  combinations `(1,16,16)`, `(2,16,16)`, `(5,16,16)`, `(2,16,20)`,
+  `(3,17,19)`, `(2,8,8)` and `(1,3,3)`.
+- Successful paths preserved the number of samples, and full-batch outputs
+  matched concatenated per-image outputs (`atol=1e-6`, `rtol=1e-5`).
+- JavaScript syntax checks passed for both application modules.
+
+Representative observations:
+
+| Input NCHW | Flatten before optional adaptive pool | Original 128 head | Fixed 512 head | Adaptive pool + 8 head |
+| --- | --- | --- | --- | --- |
+| `[2,3,16,16]` | `[2,512]` | Exact error `(2x512 and 128x5)` | `[2,5]` | `[2,5]` |
+| `[2,3,16,20]` | `[2,640]` | Mismatch | Exact error `(2x640 and 512x5)` | `[2,5]` |
+| `[3,3,17,19]` | `[3,576]` | Mismatch | Mismatch | `[3,5]` |
+| `[2,3,8,8]` | `[2,128]` | `[2,5]` | Mismatch | `[2,5]` |
+| `[1,3,3,3]` | `[1,8]` | Mismatch | Mismatch | `[1,5]` |
+
+For the default input, `reshape(-1,128)` changes `[2,512]` to `[8,128]` and
+produces `[8,5]` through the original head. The operation runs but does not
+preserve one output row per image. Odd-sized pooling and impossible/redundant
+reshape cases were also checked against PyTorch.
+
+Browser rendering and interaction acceptance are not established by these tests.
+No model accuracy, checkpoint compatibility or extension capture result is
+claimed by this standalone lesson.
+
+## Browser QA — October 11, 2026
+
+A separate in-app browser pass checked the locally served lesson at **1280 × 720**
+and **390 × 844**. It verified these interactions:
+
+- The default input displays `512 ≠ 128` at the original classifier.
+- Choosing the 512-feature head produces the calculated output `[2,5]`.
+- Changing the image to 16 × 20 produces `640 ≠ 512` with that fixed head.
+- Adding adaptive pooling produces `[2,5]` and shows the explicit warning that
+  the architecture and computation change.
+- A 17 × 19 image pools to spatial size 8 × 9.
+- Batch zero shows the validation message; Reset restores the starting lesson.
+
+The 390-pixel-wide page had readable text and no horizontal overflow. A full-page
+mobile screenshot was saved as `tensorviz-shape-lab-mobile-2026-10-11.png`.
+No lesson-origin console errors were observed. These results cover the two
+listed viewports; 320-pixel rendering and hosted Hugging Face behavior were not
+established by this local pass.
+
+A source review also confirmed the visible arithmetic-only notice, batch-preserving
+flatten, explicit adaptive-pooling semantics, unsafe-reshape sample-count warning,
+and distinction between this lesson and actual tensorViz model capture. The code
+adds no runtime fetch or tracking, and the footer limits its claim to calculations
+staying in the reader's browser.

app.mjs

@@ -0,0 +1,82 @@
+import { inspectShapes } from './shape-math.mjs';
+
+const byId = (id) => document.getElementById(id);
+const shape = (dimensions) => `[${dimensions.join(', ')}]`;
+const text = (id, value) => { byId(id).textContent = value; };
+const form = byId('shape-form');
+
+function render() {
+  const result = inspectShapes({
+    batch: byId('batch').valueAsNumber,
+    height: byId('height').valueAsNumber,
+    width: byId('width').valueAsNumber,
+    mode: form.elements.mode.value,
+  });
+  byId('invalid').hidden = result.valid;
+  byId('calculation').hidden = !result.valid;
+  byId('reshape-result').hidden = !result.valid;
+  if (!result.valid) { text('invalid', result.message); return; }
+
+  const r = result;
+  text('shape-input', shape(r.input));
+  text('shape-conv', shape(r.conv));
+  text('shape-pool', shape(r.pool));
+  text('shape-flat', shape(r.flattened));
+  byId('adaptive-row').hidden = !r.adaptive;
+  if (r.adaptive) text('shape-adaptive', shape(r.adaptive));
+  const linearName = byId('linear-name');
+  linearName.replaceChildren(document.createTextNode(`Linear(${r.inFeatures}, 5)`));
+  const small = document.createElement('small');
+  small.textContent = `Expects ${r.inFeatures} features per image`;
+  linearName.append(small);
+  text('shape-output', r.output ? shape(r.output) : `${r.features} ≠ ${r.inFeatures}`);
+  byId('linear-row').className = r.matches ? 'match' : 'mismatch';
+  byId('verdict').className = `verdict ${r.matches ? 'match' : 'mismatch'}`;
+  text('verdict-title', r.matches ? `The widths match. Batch stays ${r.batch}.` : `${r.features} features arrived. The head expects ${r.inFeatures}.`);
+  text('feature-math', r.adaptive
+    ? '8 channels × 1 height × 1 width = 8 features per image after adaptive pooling.'
+    : `8 channels × ${r.pool[2]} height × ${r.pool[3]} width = ${r.features} features per image.`);
+  text('matrix-left', shape(r.flattened));
+  text('matrix-right', shape([r.inFeatures, 5]));
+  text('matrix-answer', r.output ? `= ${shape(r.output)}` : 'incompatible');
+  text('weight-shape', shape(r.weight));
+  byId('error-message').hidden = r.matches;
+  text('error-message', r.error ?? '');
+  const notes = {
+    broken: r.matches
+      ? 'This input produces exactly 128 features per image. Try 16 × 16: the same fixed head will no longer fit.'
+      : 'The fixed head expects 128 features per image. Match the head to the intended input contract; changing the batch does not change this width.',
+    fixed: r.matches
+      ? '512 fits the 16 × 16 example. Try a wider image: changing the input can break a fixed-width head again.'
+      : '512 is fixed for the original 16 × 16 example. This input has a different feature width. A successful earlier capture does not cover every input.',
+    pooled: 'Adaptive pooling averages each spatial channel to one value, so this head receives 8 features. This changes the architecture and the classifier weights; it is not the same computation as the fixed-width model.',
+  };
+  text('mode-note', notes[r.mode]);
+  text('reshape-before', shape([r.batch, r.originalFeatures]));
+  const unsafe = r.unsafeReshape;
+  text('reshape-after', unsafe.possible ? shape(unsafe.shape) : 'cannot reshape');
+  const warning = byId('reshape-warning');
+  warning.replaceChildren();
+  const strong = document.createElement('strong');
+  strong.textContent = !unsafe.possible
+    ? `${unsafe.elements} elements cannot fill rows of 128.`
+    : unsafe.preservesBatch
+      ? `The feature width was already 128.`
+      : `${r.batch} ${r.batch === 1 ? 'image became' : 'images became'} ${unsafe.shape[0]} ${unsafe.shape[0] === 1 ? 'row' : 'rows'}.`;
+  warning.append(strong, document.createTextNode(!unsafe.possible
+    ? ' This reshape would fail before Linear. Use a batch-preserving flatten and inspect the feature width.'
+    : unsafe.preservesBatch
+      ? ' This reshape is redundant here. It does not repair a mismatch or make other image sizes safe.'
+      : ` Linear can now return ${shape(unsafe.output)}, but that is not one prediction per image.`));
+}
+
+form.addEventListener('input', render);
+form.addEventListener('change', render);
+form.addEventListener('submit', (event) => event.preventDefault());
+document.querySelectorAll('[data-height]').forEach((button) => button.addEventListener('click', () => {
+  byId('height').value = button.dataset.height;
+  byId('width').value = button.dataset.width;
+  render();
+}));
+byId('reset').addEventListener('click', () => { form.reset(); render(); });
+render();

index.html

@@ -1,19 +1,104 @@
 <!doctype html>
-<html>
-	<head>
-		<meta charset="utf-8" />
-		<meta name="viewport" content="width=device-width" />
-		<title>My static Space</title>
-		<link rel="stylesheet" href="style.css" />
-	</head>
-	<body>
-		<div class="card">
-			<h1>Welcome to your static Space!</h1>
-			<p>You can modify this app directly by editing <i>index.html</i> in the Files and versions tab.</p>
-			<p>
-				Also don't forget to check the
-				<a href="https://huggingface.co/docs/hub/spaces" target="_blank">Spaces documentation</a>.
-			</p>
-		</div>
-	</body>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="description" content="An interactive PyTorch shape-arithmetic lesson: follow a small CNN, find a Linear mismatch, and see why a reshape can change your batch.">
+  <meta name="theme-color" content="#ffffff">
+  <title>PyTorch shape lab · tensorViz</title>
+  <link rel="icon" href="logo.png">
+  <link rel="stylesheet" href="styles.css">
+</head>
+<body>
+  <a class="skip-link" href="#lab">Skip to the lesson</a>
+  <main>
+    <header class="brand">
+      <img src="logo.png" width="34" height="34" alt="tensorViz logo">
+      <span>tensorViz <span class="brand-separator">/</span> <span class="brand-label">shape lab</span></span>
+      <a href="https://github.com/tensorviz-org/tensorviz-examples/blob/1baecebf25ff1067a9112bde382c0a398fb99747/examples/shape-mismatch/README.md">Runnable example</a>
+    </header>
+
+    <section class="intro" aria-labelledby="page-title">
+      <h1 id="page-title">Your batch is fine.<br>Check the features.</h1>
+      <p>A small image model reaches <code>Linear</code> with the wrong width.
+        Change the input, follow the shapes, and find the contract that broke.</p>
+      <p class="boundary">Shape arithmetic only. This page does not run Python, a model or inference.</p>
+    </section>
+
+    <section id="lab" class="lab" aria-labelledby="lab-title">
+      <div class="controls">
+        <h2 id="lab-title">Try an input</h2>
+        <p class="section-note">NCHW · 3 input channels</p>
+        <form id="shape-form" novalidate>
+          <div class="dimensions">
+            <label for="batch">Batch <input id="batch" name="batch" type="number" min="1" max="64" step="1" value="2" inputmode="numeric" aria-describedby="input-bounds"></label>
+            <label for="height">Height <input id="height" name="height" type="number" min="2" max="256" step="1" value="16" inputmode="numeric" aria-describedby="input-bounds"></label>
+            <label for="width">Width <input id="width" name="width" type="number" min="2" max="256" step="1" value="16" inputmode="numeric" aria-describedby="input-bounds"></label>
+          </div>
+          <p id="input-bounds" class="field-help">Batch 1–64. Height and width 2–256.</p>
+          <div class="presets" aria-label="Example image sizes">
+            <button type="button" data-height="16" data-width="16">16 × 16</button>
+            <button type="button" data-height="16" data-width="20">16 × 20</button>
+            <button type="button" data-height="17" data-width="19">17 × 19</button>
+          </div>
+          <fieldset>
+            <legend>Choose the classifier</legend>
+            <label class="mode"><input type="radio" name="mode" value="broken" checked><span>Original head<strong>Linear(128, 5)</strong></span></label>
+            <label class="mode"><input type="radio" name="mode" value="fixed"><span>Match the 16 × 16 input<strong>Linear(512, 5)</strong></span></label>
+            <label class="mode"><input type="radio" name="mode" value="pooled"><span>Add adaptive average pooling<strong>Pool to 1 × 1 → Linear(8, 5)</strong></span></label>
+          </fieldset>
+        </form>
+        <button id="reset" type="button" class="reset">Reset lesson</button>
+      </div>
+
+      <div class="results" aria-label="Calculated tensor shapes">
+        <div id="invalid" class="invalid" role="status" hidden></div>
+        <div id="calculation">
+          <ol class="flow" aria-label="Shape at each layer">
+            <li><div><span class="step">01</span><span>Input</span></div><output id="shape-input">[2, 3, 16, 16]</output></li>
+            <li><div><span class="step">02</span><span>Conv2d + ReLU<small>3 → 8 channels · kernel 3 · padding 1</small></span></div><output id="shape-conv">[2, 8, 16, 16]</output></li>
+            <li><div><span class="step">03</span><span>MaxPool2d(2)<small>Spatial sizes round down</small></span></div><output id="shape-pool">[2, 8, 8, 8]</output></li>
+            <li id="adaptive-row" hidden><div><span class="step">+</span><span>AdaptiveAvgPool2d((1, 1))<small>New architecture: average each channel</small></span></div><output id="shape-adaptive"></output></li>
+            <li><div><span class="step">04</span><span>Flatten(start_dim=1)<small>Keep the first dimension: batch</small></span></div><output id="shape-flat">[2, 512]</output></li>
+            <li id="linear-row" class="mismatch"><div><span class="step">05</span><span id="linear-name">Linear(128, 5)<small>Expects 128 features per image</small></span></div><output id="shape-output">512 ≠ 128</output></li>
+          </ol>
+
+          <section id="verdict" class="verdict mismatch" aria-live="polite" aria-atomic="true">
+            <h3 id="verdict-title">512 features arrived. The head expects 128.</h3>
+            <p id="feature-math">8 channels × 8 height × 8 width = 512 features per image.</p>
+            <p class="matrix"><span id="matrix-left">[2, 512]</span><span aria-label="multiplied by">×</span><span id="matrix-right">[128, 5]</span><span id="matrix-answer">incompatible</span></p>
+            <p class="matrix-note">Linear stores its weight as <code id="weight-shape">[5, 128]</code> and multiplies by its transpose.</p>
+            <code id="error-message" class="error">mat1 and mat2 shapes cannot be multiplied (2x512 and 128x5)</code>
+          </section>
+          <p id="mode-note" class="mode-note">Change the head to 512 to match this 16 × 16 example. Then try a wider image: the fixed width is a contract, not a universal fix.</p>
+        </div>
+      </div>
+    </section>
+
+    <section class="reshape-section" aria-labelledby="reshape-title">
+      <div>
+        <h2 id="reshape-title">A reshape can hide the error.</h2>
+        <p>On the original feature map, <code>reshape(-1, 128)</code> asks PyTorch to infer a new first dimension. That dimension may no longer count your images.</p>
+        <p class="field-help">This comparison uses the feature map before any optional adaptive pooling.</p>
+      </div>
+      <div id="reshape-result" class="reshape-result" aria-live="polite">
+        <p class="reshape-flow"><code id="reshape-before">[2, 512]</code><span>→ reshape →</span><code id="reshape-after">[8, 128]</code></p>
+        <p id="reshape-warning"><strong>2 images became 8 rows.</strong> Linear can now return [8, 5], but that is not one prediction per image.</p>
+      </div>
+    </section>
+
+    <section class="takeaway" aria-labelledby="takeaway-title">
+      <h2 id="takeaway-title">Make the contract explicit.</h2>
+      <p>Use <code>Flatten(start_dim=1)</code> to preserve the batch. Match the classifier width to the feature extractor and intended input size. Adaptive pooling is another design choice: it changes the computation and needs a different classifier.</p>
+      <p>Matching shapes only makes these operations compatible. It does not establish prediction quality or numerical equivalence.</p>
+      <div class="resource-links">
+        <a href="https://github.com/tensorviz-org/tensorviz-examples/blob/1baecebf25ff1067a9112bde382c0a398fb99747/examples/shape-mismatch/README.md">Read and run the PyTorch example</a>
+        <a href="https://tensorviz.dev/explore/">Explore recorded models in tensorViz</a>
+      </div>
+    </section>
+    <footer>Made by tensorViz with AI assistance. Original lesson code is MIT licensed. Calculations stay in your browser.</footer>
+    <noscript><p class="invalid">Enable JavaScript to change the inputs. The displayed default example shows a batch of two 16 × 16 images failing at Linear(128, 5).</p></noscript>
+  </main>
+  <script type="module" src="app.mjs"></script>
+</body>
 </html>

shape-math.mjs

@@ -0,0 +1,43 @@
+export const MODES = Object.freeze({ broken: 128, fixed: 512, pooled: 8 });
+
+// This lesson has a fixed Conv2d/ReLU/MaxPool2d stack, not a general shape engine.
+export function inspectShapes({ batch, height, width, mode = 'broken' }) {
+  const values = { batch, height, width };
+  for (const [name, value] of Object.entries(values)) {
+    const min = name === 'batch' ? 1 : 2;
+    const max = name === 'batch' ? 64 : 256;
+    if (!Number.isInteger(value) || value < min || value > max) {
+      return { valid: false, message: `${name === 'batch' ? 'Batch size' : name === 'height' ? 'Height' : 'Width'} must be a whole number from ${min} to ${max}.` };
+    }
+  }
+  if (!Object.hasOwn(MODES, mode)) return { valid: false, message: 'Choose one of the three classifier heads.' };
+
+  const pooledHeight = Math.floor(height / 2);
+  const pooledWidth = Math.floor(width / 2);
+  const originalFeatures = 8 * pooledHeight * pooledWidth;
+  const features = mode === 'pooled' ? 8 : originalFeatures;
+  const inFeatures = MODES[mode];
+  const matches = features === inFeatures;
+  const reshapedBatch = batch * originalFeatures / 128;
+  const canReshape = Number.isInteger(reshapedBatch);
+  return {
+    valid: true,
+    batch, height, width, mode,
+    input: [batch, 3, height, width],
+    conv: [batch, 8, height, width],
+    pool: [batch, 8, pooledHeight, pooledWidth],
+    adaptive: mode === 'pooled' ? [batch, 8, 1, 1] : null,
+    flattened: [batch, features],
+    weight: [5, inFeatures],
+    output: matches ? [batch, 5] : null,
+    features, originalFeatures, inFeatures, matches,
+    error: matches ? null : `mat1 and mat2 shapes cannot be multiplied (${batch}x${features} and ${inFeatures}x5)`,
+    unsafeReshape: {
+      possible: canReshape,
+      shape: canReshape ? [reshapedBatch, 128] : null,
+      output: canReshape ? [reshapedBatch, 5] : null,
+      preservesBatch: canReshape && reshapedBatch === batch,
+      elements: batch * originalFeatures,
+    },
+  };
+}

shape-math.test.mjs

@@ -0,0 +1,45 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { inspectShapes } from './shape-math.mjs';
+
+test('the canonical mismatch keeps two images and locates the feature error', () => {
+  const r = inspectShapes({ batch: 2, height: 16, width: 16 });
+  assert.deepEqual(r.flattened, [2, 512]);
+  assert.deepEqual(r.weight, [5, 128]);
+  assert.equal(r.error, 'mat1 and mat2 shapes cannot be multiplied (2x512 and 128x5)');
+  assert.equal(r.output, null);
+});
+
+test('a fixed-width repair preserves batch but does not promise arbitrary inputs', () => {
+  for (const batch of [1, 2, 5]) {
+    assert.deepEqual(inspectShapes({ batch, height: 16, width: 16, mode: 'fixed' }).output, [batch, 5]);
+  }
+  assert.equal(inspectShapes({ batch: 2, height: 16, width: 20, mode: 'fixed' }).matches, false);
+});
+
+test('odd dimensions use floor pooling and the explicit adaptive stage changes the head', () => {
+  const r = inspectShapes({ batch: 3, height: 17, width: 19, mode: 'pooled' });
+  assert.deepEqual(r.pool, [3, 8, 8, 9]);
+  assert.deepEqual(r.adaptive, [3, 8, 1, 1]);
+  assert.deepEqual(r.flattened, [3, 8]);
+  assert.deepEqual(r.output, [3, 5]);
+});
+
+test('making Linear run by reshape must not be mistaken for preserving samples', () => {
+  const r = inspectShapes({ batch: 2, height: 16, width: 16 });
+  assert.deepEqual(r.unsafeReshape.shape, [8, 128]);
+  assert.deepEqual(r.unsafeReshape.output, [8, 5]);
+  assert.equal(r.unsafeReshape.preservesBatch, false);
+  assert.equal(inspectShapes({ batch: 1, height: 3, width: 3 }).unsafeReshape.possible, false);
+  assert.equal(inspectShapes({ batch: 2, height: 8, width: 8 }).unsafeReshape.preservesBatch, true);
+});
+
+test('invalid inputs are rejected instead of showing stale or impossible shapes', () => {
+  const base = { batch: 2, height: 16, width: 16 };
+  for (const [name, value] of [['batch', 0], ['batch', 65], ['height', 1], ['width', 257], ['width', 2.5], ['height', NaN], ['batch', Infinity], ['mode', 'other']]) {
+    const r = inspectShapes({ ...base, [name]: value });
+    assert.equal(r.valid, false, `${name}=${value}`);
+    assert.ok(r.message);
+    assert.equal(r.flattened, undefined);
+  }
+});

styles.css

@@ -0,0 +1,108 @@
+:root {
+  color-scheme: light;
+  --ink: #1b2520;
+  --muted: #5f6e65;
+  --line: #dce4de;
+  --green: #176047;
+  --green-light: #edf6f0;
+  --red: #a1392a;
+  --red-light: #fff3ee;
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  color: var(--ink);
+  background: #ffffff;
+}
+* { box-sizing: border-box; }
+body { margin: 0; }
+main { max-width: 1136px; padding: 28px 48px 24px; margin: auto; }
+a { color: var(--green); text-underline-offset: 4px; text-decoration-thickness: 1px; }
+a:hover { text-decoration-thickness: 2px; }
+button, input { font: inherit; }
+button { cursor: pointer; }
+button:focus-visible, input:focus-visible, a:focus-visible { outline: 3px solid #76aa90; outline-offset: 4px; }
+[hidden] { display: none !important; }
+code, output { font-family: ui-monospace, SFMono-Regular, Consolas, monospace; }
+code { font-size: .9em; }
+.brand { display: flex; gap: 12px; align-items: center; font-size: 18px; font-weight: 650; }
+.brand img { object-fit: contain; flex: 0 0 auto; }
+.brand-separator { color: #a4b0a8; margin: 0 8px; font-weight: 400; }
+.brand-label { font-weight: 450; }
+.brand a { margin-left: auto; font-size: 13px; font-weight: 500; }
+.intro { padding: 58px 0 32px; max-width: 730px; }
+h1 { font-size: clamp(32px, 4.5vw, 50px); line-height: 1.06; letter-spacing: -.045em; margin: 0 0 20px; font-weight: 650; }
+p { font-size: 16px; line-height: 1.6; margin: 0 0 12px; }
+.intro > p { max-width: 650px; color: var(--muted); }
+.intro .boundary { font-size: 12px; color: var(--muted); margin-top: 18px; }
+.lab { display: grid; grid-template-columns: 285px minmax(0, 1fr); border-block: 1px solid var(--line); }
+.controls { padding: 28px 26px 28px 0; border-right: 1px solid var(--line); }
+h2 { font-size: 21px; letter-spacing: -.025em; line-height: 1.25; margin: 0 0 9px; font-weight: 630; }
+.section-note, .field-help { font-size: 12px; color: var(--muted); }
+.section-note { margin-bottom: 21px; }
+.dimensions { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 10px; }
+.dimensions label { font-size: 12px; font-weight: 600; }
+.dimensions input { display: block; margin-top: 8px; width: 100%; border: 1px solid #b8c7bd; border-radius: 7px; background: #fff; padding: 10px 8px; font-size: 19px; color: var(--ink); }
+.field-help { margin-top: 8px; line-height: 1.5; }
+.presets { display: flex; gap: 6px; margin: 16px 0 29px; flex-wrap: wrap; }
+.presets button { font-size: 11px; padding: 7px 9px; background: white; border: 1px solid var(--line); border-radius: 5px; color: var(--muted); }
+.presets button:hover { border-color: var(--green); color: var(--green); }
+fieldset { border: 0; padding: 0; margin: 0; }
+legend { font-size: 12px; font-weight: 650; margin-bottom: 10px; }
+.mode { display: flex; align-items: flex-start; gap: 9px; padding: 12px 7px; border-bottom: 1px solid var(--line); font-size: 12px; line-height: 1.4; cursor: pointer; }
+.mode:has(input:checked) { background: var(--green-light); border-color: transparent; border-radius: 6px; }
+.mode input { accent-color: var(--green); margin: 2px 0 0; flex: 0 0 auto; }
+.mode strong { display: block; font-family: ui-monospace, SFMono-Regular, Consolas, monospace; font-size: 11px; font-weight: 500; margin-top: 5px; color: var(--muted); }
+.reset { border: 0; background: none; padding: 0; color: var(--muted); text-decoration: underline; text-underline-offset: 4px; margin-top: 22px; font-size: 12px; }
+.results { padding: 19px 0 26px 30px; min-width: 0; }
+.flow { list-style: none; padding: 0; margin: 0; }
+.flow li { display: flex; align-items: center; justify-content: space-between; gap: 16px; padding: 13px 0; border-bottom: 1px solid var(--line); font-size: 13px; }
+.flow li > div { display: flex; gap: 11px; align-items: baseline; }
+.step { color: #89988e; font-size: 10px; font-family: ui-monospace, SFMono-Regular, Consolas, monospace; }
+.flow small { display: block; color: var(--muted); font-size: 11px; line-height: 1.5; margin-top: 3px; }
+.flow output { font-size: 12px; white-space: nowrap; }
+.flow .mismatch output { color: var(--red); font-weight: 600; }
+.flow .match output { color: var(--green); font-weight: 600; }
+.verdict { padding: 18px 20px; margin-top: 20px; border-radius: 8px; }
+.verdict.mismatch { background: var(--red-light); }
+.verdict.match { background: var(--green-light); }
+h3 { margin: 0 0 8px; font-size: 16px; line-height: 1.4; font-weight: 650; }
+.verdict p { font-size: 12px; line-height: 1.55; }
+.matrix { display: flex; gap: 10px; align-items: center; flex-wrap: wrap; padding: 11px 0 2px; font-family: ui-monospace, SFMono-Regular, Consolas, monospace; }
+.matrix span:nth-child(1), .matrix span:nth-child(3) { font-size: 20px; letter-spacing: -.04em; }
+.matrix span:last-child { font-size: 11px; color: var(--muted); }
+.matrix-note { color: var(--muted); margin-top: 5px; }
+.error { display: block; font-size: 11px; line-height: 1.6; color: var(--red); overflow-wrap: anywhere; margin-top: 10px; }
+.mode-note { font-size: 12px; color: var(--muted); margin: 14px 0 0; }
+.invalid { padding: 18px; border-left: 3px solid var(--red); background: var(--red-light); color: var(--red); font-size: 14px; }
+.reshape-section { display: grid; grid-template-columns: 1fr 1fr; gap: 44px; padding: 38px 0; border-bottom: 1px solid var(--line); }
+.reshape-section p, .takeaway p { font-size: 14px; color: var(--muted); }
+.reshape-section .field-help { font-size: 11px; }
+.reshape-result { align-self: center; background: #f5f7f5; padding: 22px; border-radius: 8px; }
+.reshape-result p { font-size: 13px; }
+.reshape-result strong { color: var(--ink); }
+.reshape-flow { display: flex; flex-wrap: wrap; align-items: center; gap: 10px; }
+.reshape-flow code { font-size: 20px; color: var(--ink); }
+.reshape-flow span { font-size: 11px; }
+.takeaway { max-width: 800px; padding: 32px 0 28px; }
+.resource-links { display: flex; flex-wrap: wrap; gap: 12px 28px; margin-top: 22px; font-size: 13px; }
+footer { border-top: 1px solid var(--line); padding-top: 17px; color: var(--muted); font-size: 11px; line-height: 1.6; }
+.skip-link { position: absolute; left: 12px; top: -100px; background: #fff; padding: 10px; z-index: 1; }
+.skip-link:focus { top: 10px; }
+@media (max-width: 760px) {
+  main { padding: 22px 24px; }
+  .brand a { display: none; }
+  .intro { padding-top: 40px; }
+  .lab { grid-template-columns: 1fr; }
+  .controls { border-right: 0; border-bottom: 1px solid var(--line); padding-right: 0; }
+  .dimensions { max-width: 380px; }
+  .presets { margin-bottom: 24px; }
+  .results { padding-left: 0; padding-top: 12px; }
+  .reshape-section { grid-template-columns: 1fr; gap: 10px; padding: 30px 0; }
+}
+@media (max-width: 390px) {
+  main { padding: 18px 18px; }
+  .brand { font-size: 16px; }
+  .brand-separator { margin: 0 4px; }
+  h1 { font-size: 32px; }
+  .flow li { align-items: flex-start; flex-direction: column; gap: 7px; }
+  .flow output { padding-left: 25px; }
+  .verdict { padding: 16px; }
+}

verify_pytorch.py

@@ -0,0 +1,90 @@
+"""Compare the teaching arithmetic with real CPU operations; no downloads or UI.
+
+Model derived from the MIT tensorViz shape-mismatch example, commit
+1baecebf25ff1067a9112bde382c0a398fb99747. See README for the public source.
+"""
+
+import json
+import platform
+from pathlib import Path
+import subprocess
+
+import torch
+from torch import nn
+
+
+ROOT = Path(__file__).resolve().parent
+CASES = [
+    {"batch": batch, "height": height, "width": width, "mode": mode}
+    for batch, height, width in [
+        (1, 16, 16), (2, 16, 16), (5, 16, 16),
+        (2, 16, 20), (3, 17, 19), (2, 8, 8), (1, 3, 3),
+    ]
+    for mode in ["broken", "fixed", "pooled"]
+]
+NODE_SCRIPT = """
+import { inspectShapes } from './shape-math.mjs';
+let text = '';
+for await (const chunk of process.stdin) text += chunk;
+console.log(JSON.stringify(JSON.parse(text).map(inspectShapes)));
+"""
+
+
+def main():
+    actual_js = json.loads(subprocess.check_output(
+        ["node", "--input-type=module", "-e", NODE_SCRIPT],
+        input=json.dumps(CASES), text=True, cwd=ROOT,
+    ))
+    torch.manual_seed(0)
+    checked = []
+    with torch.inference_mode():
+        for case, result in zip(CASES, actual_js, strict=True):
+            b, h, w = case["batch"], case["height"], case["width"]
+            x = torch.randn(b, 3, h, w, device="cpu")
+            features = nn.Sequential(nn.Conv2d(3, 8, 3, padding=1), nn.ReLU(), nn.MaxPool2d(2)).eval()
+            conv = features[:2](x)
+            pooled = features[2](conv)
+            original_flat = nn.Flatten(start_dim=1)(pooled)
+            assert list(x.shape) == result["input"]
+            assert list(conv.shape) == result["conv"]
+            assert list(pooled.shape) == result["pool"]
+            assert original_flat.shape[0] == b, "Flatten must keep the sample count"
+            stage = nn.AdaptiveAvgPool2d((1, 1))(pooled) if case["mode"] == "pooled" else pooled
+            if case["mode"] == "pooled":
+                assert list(stage.shape) == result["adaptive"]
+            flat = nn.Flatten(start_dim=1)(stage)
+            assert list(flat.shape) == result["flattened"]
+            head = nn.Linear({"broken": 128, "fixed": 512, "pooled": 8}[case["mode"]], 5).eval()
+            assert list(head.weight.shape) == result["weight"]
+            try:
+                out = head(flat)
+            except RuntimeError as exc:
+                assert not result["matches"]
+                assert str(exc) == result["error"]
+            else:
+                assert result["matches"]
+                assert list(out.shape) == result["output"] == [b, 5]
+                # A batch-preserving path must give one independently computed row per image.
+                per_image = []
+                for image in x.split(1):
+                    value = features(image)
+                    if case["mode"] == "pooled":
+                        value = nn.AdaptiveAvgPool2d((1, 1))(value)
+                    per_image.append(head(value.flatten(1)))
+                torch.testing.assert_close(out, torch.cat(per_image), atol=1e-6, rtol=1e-5)
+            try:
+                unsafe = original_flat.reshape(-1, 128)
+            except RuntimeError:
+                assert not result["unsafeReshape"]["possible"]
+            else:
+                expected = result["unsafeReshape"]
+                assert list(unsafe.shape) == expected["shape"]
+                unsafe_out = nn.Linear(128, 5)(unsafe)
+                assert list(unsafe_out.shape) == expected["output"]
+                assert (unsafe.shape[0] == b) == expected["preservesBatch"]
+            checked.append({**case, "flattened": result["flattened"], "output": result["output"], "error": result["error"]})
+    print(json.dumps({"python": platform.python_version(), "torch": torch.__version__, "device": "cpu", "cases_passed": len(checked), "cases": checked}, indent=2))
+
+
+if __name__ == "__main__":
+    main()