From 5b0b30dcce3927f9ea2f39918a313a055acde142 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Fri, 2 Oct 2026 14:57:08 -0400
Subject: [PATCH 01/17] fix(studio): ISP time estimate ~5 s/panel, not ~20 s
 (#244)

The Program set confirm said ~8 min for a 20-panel arena; the batch on
rig5-mr (2026-09-30) took ~2 min: ~4.4 s program + reboot and ~1 s
verify + STOP per panel. Use 5 s + 1 s for the estimate and fix the
"~20 s" in the dialog and the Flash / Program set tooltips.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 arena_studio.html | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/arena_studio.html b/arena_studio.html
index 0cd898fb..8c00d0d7 100644
--- a/arena_studio.html
+++ b/arena_studio.html
@@ -3243,7 +3243,7 @@ <h2 id="modalTitle">Import error</h2>
             <button class="pill" data-cmd="cfwinfo" title="GET_FIRMWARE_INFO 0xE3 — version footer of the image on the SD">Info</button></div>
           <div class="crow"><span class="lbl">single</span>
             <input id="cFwAddr" type="number" min="1" value="1" style="width:56px" title="panel address (1-based)">
-            <button class="pill danger" data-cmd="cfwflash" title="Program one panel from /firmware/panel.bin over SPI ISP (0xC8) — ~20 s, do NOT power off">Flash</button>
+            <button class="pill danger" data-cmd="cfwflash" title="Program one panel from /firmware/panel.bin over SPI ISP (0xC8) — ~5 s, do NOT power off">Flash</button>
             <button class="pill" data-cmd="cfwverify" title="CRC the panel's running app flash vs the SD footer (0xC9)">Verify</button></div>
           <div class="crow"><span class="lbl">fleet</span>
             <button class="pill" data-cmd="cinv" title="GET_PANEL_INVENTORY 0xD1 — which panels answered at boot and the firmware fingerprint (CRC-32) each one runs; reads it again now (firmware with feature bit 0 only)">Inventory</button>
@@ -3253,7 +3253,7 @@ <h2 id="modalTitle">Import error</h2>
             <input id="cIspRange" type="text" value="1-20" style="width:86px" title="Panels to program: a range/list like 1-20 or 1,3,5-8">
             <label title="Verify each panel's CRC (0xC9) right after flashing; the report marks verified vs flashed-only"><input type="checkbox" id="cIspVerify" checked> verify each</label>
             <label id="cIspShowWrap" title="Blink a progress map on the arena between panels (done bright · pending dim · failed checker); the final map stays lit. The display must be stopped DURING each flash (firmware), so it blinks rather than persists. 20-panel arenas only."><input type="checkbox" id="cIspShow" checked> show on arena</label>
-            <button class="pill danger" data-cmd="cispbatch" id="cIspBtn" title="Flash /firmware/panel.bin to every panel in the set over SPI ISP (0xC8), retrying once on failure. ~20 s/panel — do NOT power off.">⚡ Program set</button>
+            <button class="pill danger" data-cmd="cispbatch" id="cIspBtn" title="Flash /firmware/panel.bin to every panel in the set over SPI ISP (0xC8), retrying once on failure. ~5 s/panel — do NOT power off.">⚡ Program set</button>
             <button class="pill" data-cmd="cispstop" id="cIspStopBtn" disabled title="Stop the batch after the current panel finishes">Stop</button>
             <button class="pill" data-cmd="cispcopy" id="cIspCopyBtn" style="display:none" title="Copy the batch report as plain text">Copy report</button>
             <span class="dim" id="cIspStatus"></span></div>
@@ -8659,9 +8659,10 @@ <h2 id="modalTitle">Import error</h2>
             'Upload a .bin first (Choose…), or click OK to try anyway.')) return;
     }
     const verify = $('cIspVerify').checked;
-    const est = Math.ceil((panels.length * (20 + (verify ? 2 : 0))) / 60);
+    // Bench 2026-09-30 (#244): ~4.4 s program + reboot, ~1 s verify + STOP per panel.
+    const est = Math.ceil((panels.length * (5 + (verify ? 1 : 0))) / 60);
     if (!confirm('Program ' + panels.length + ' panel(s) [' + fmtRange(panels) + '] from /firmware/panel.bin?\n' +
-        'Each panel is reflashed over SPI and reboots (~20 s). Do NOT power off mid-flash.\n' +
+        'Each panel is reflashed over SPI and reboots (~5 s). Do NOT power off mid-flash.\n' +
         'Estimated time ~' + est + ' min.')) return;
 
     isp.running = true;

From 4d258b035a002c4623acb1997d80161c5bd04730 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Tue, 6 Oct 2026 14:58:19 -0400
Subject: [PATCH 02/17] fix(pattern-designer): degrees per pixel uses the full
 circle on partial arenas

getDegreesPerPixel() divided 360 deg by the INSTALLED pixel columns instead of the
full circumference. On G4 3x12of18 (the IAS talk arena) that gave 1.875 deg/px
instead of 1.25, so the px<->deg helper labels were wrong and a spatial period typed
in pixels generated the wrong grating (24 px came out as 45 deg, 36 frames). A step
size typed in degrees was off the same way. G6 3x12of18 (1.5 -> 1.0 deg/px) and
G6 2x8of10 (2.25 -> 1.8) had the same bug; full arenas were already right.

The generator already used the full circle (arenaCoordinates numCircle = num_cols).
The pitch now lives in one shared place, PatternGenerator.getDegreesPerPixel(), and
getArenaDimensions() reports circleCols / azimuthPixels, which the three spherical
generators also read, so the editor and generator cannot drift apart again.
Also fixes the Animate tab's frame-shift hint on partial arenas ("360 deg = 192 px"
-> "240 deg = 192 px"), and cache-busts generator.js because the editor's init now
calls the new helper.

tests/test-pattern-degrees-per-pixel.js runs the editor's own conversion functions
(extracted from pattern_editor.html) for every standard config, plus end-to-end
gratings typed in px and deg; it failed 15 checks before the fix.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 js/pattern-editor/tools/generator.js    |  25 ++-
 pattern_editor.html                     |  22 +-
 tests/test-pattern-degrees-per-pixel.js | 255 ++++++++++++++++++++++++
 3 files changed, 289 insertions(+), 13 deletions(-)
 create mode 100644 tests/test-pattern-degrees-per-pixel.js

diff --git a/js/pattern-editor/tools/generator.js b/js/pattern-editor/tools/generator.js
index aaf6e1c9..d518e3f8 100644
--- a/js/pattern-editor/tools/generator.js
+++ b/js/pattern-editor/tools/generator.js
@@ -98,7 +98,8 @@ const PatternGenerator = {
     /**
      * Calculate arena dimensions
      * @param {Object} arena - Arena configuration
-     * @returns {Object} Dimensions {rows, cols, pixelRows, pixelCols, panelSize}
+     * @returns {Object} Dimensions {rows, cols, installedCols, circleCols, pixelRows,
+     *   pixelCols, azimuthPixels, panelSize}
      */
     getArenaDimensions(arena) {
         const generation = arena.generation || arena.arena?.generation;
@@ -107,6 +108,9 @@ const PatternGenerator = {
         // For partial arenas, use columns_installed length instead of num_cols
         const columnsInstalled = arena.columns_installed || arena.arena?.columns_installed;
         const installedCols = columnsInstalled?.length || numCols;
+        // Panels in the full 360° circle (Pcircle): sets the angular pitch, which a
+        // partial arena shares with the full one
+        const circleCols = arena.numCircle || arena.num_cols_full || arena.Pcircle || numCols;
 
         const specs = this.getPanelSpecs(generation);
         const panelSize = specs.pixels_per_panel;
@@ -116,12 +120,25 @@ const PatternGenerator = {
             rows: numRows,
             cols: numCols, // Total arena slots (for geometry calculations)
             installedCols, // Actual installed columns (for pattern dimensions)
+            circleCols,
             pixelRows: numRows * panelSize,
             pixelCols: installedCols * panelSize, // Use installed columns for pattern width
+            azimuthPixels: circleCols * panelSize, // Pixels around the full circle
             panelSize
         };
     },
 
+    /**
+     * Azimuthal pitch in degrees per pixel: 360° over the FULL circle's pixels, never the
+     * installed ones. G4 3×12of18 = 360 / (18 × 16) = 1.25°/px. The spherical generators
+     * use the same pitch (arenaCoordinates numCircle), so px↔° conversions must use this.
+     * @param {Object} arena - Arena configuration (generator, config.arena or config form)
+     * @returns {number} Degrees per pixel
+     */
+    getDegreesPerPixel(arena) {
+        return 360 / this.getArenaDimensions(arena).azimuthPixels;
+    },
+
     /**
      * Create an empty frame (all zeros)
      * @param {number} pixelRows - Number of pixel rows
@@ -359,7 +376,7 @@ const PatternGenerator = {
         // Determine number of columns for full circle (Pcircle)
         // For partial arenas, numCircle is the FULL arena size (for correct angular spacing)
         // but numCols should be the installed columns (for pattern dimensions)
-        const numCircle = arena.numCircle || arena.num_cols_full || arena.Pcircle || cols;
+        const numCircle = dims.circleCols;
 
         // Generate arena coordinates
         // numCols = installed columns (pattern dimension)
@@ -578,7 +595,7 @@ const PatternGenerator = {
         const { pixelRows, pixelCols, generation, rows, cols, installedCols, panelSize } = dims;
 
         // Determine number of columns for full circle (Pcircle)
-        const numCircle = arena.numCircle || arena.num_cols_full || arena.Pcircle || cols;
+        const numCircle = dims.circleCols;
 
         // Generate arena coordinates for projection
         const arenaConfig = {
@@ -862,7 +879,7 @@ const PatternGenerator = {
         const { pixelRows, pixelCols, generation, rows, cols, installedCols, panelSize } = dims;
 
         // Determine number of columns for full circle (Pcircle)
-        const numCircle = arena.numCircle || arena.num_cols_full || arena.Pcircle || cols;
+        const numCircle = dims.circleCols;
 
         // Generate arena coordinates
         const arenaConfig = {
diff --git a/pattern_editor.html b/pattern_editor.html
index 9ce1aa12..e1385c5f 100644
--- a/pattern_editor.html
+++ b/pattern_editor.html
@@ -26,7 +26,9 @@
     </script>
     <script src="js/pat-encoder.js"></script>
     <script src="js/arena-geometry.js"></script>
-    <script src="js/pattern-editor/tools/generator.js"></script>
+    <!-- ?v= busts a cached copy: initializeApp() calls PatternGenerator.getDegreesPerPixel
+         (added 2026-10-06), so a stale generator.js would abort the editor's init -->
+    <script src="js/pattern-editor/tools/generator.js?v=1006-partial-cols"></script>
     <!-- course pipeline: GitHub request builders for "push to course repo"
          (classic dual-export module — same file Arena Studio uses) -->
     <script src="js/studio-github.js"></script>
@@ -4016,12 +4018,10 @@ <h3 class="modal-title">Save to Repo</h3>
          */
         function getDegreesPerPixel() {
             if (!state.arena.config) return 1.8;  // Default for G6 2x10
-            const config = state.arena.config.arena;
-            const specs = PANEL_SPECS[config.generation];
-            // Use columns_installed for partial arenas, fallback to num_cols for full arenas
-            const installedCols = config.columns_installed?.length || config.num_cols;
-            const pixelCols = installedCols * specs.pixels_per_panel;
-            return 360 / pixelCols;
+            // Full circumference (num_cols), never the installed columns: a partial arena keeps
+            // the full arena's pitch (G4 3x12of18 = 360 / (18 x 16) = 1.25 deg/px), the same
+            // pitch the generator uses. Shared helper so the two can't drift apart.
+            return PatternGenerator.getDegreesPerPixel(state.arena.config.arena);
         }
 
         /**
@@ -6239,9 +6239,13 @@ <h3 class="modal-title">Save to Repo</h3>
             let defaultFrames;
             let hint;
             if (direction.startsWith('h-')) {
-                // Horizontal motion: full 360° loop
+                // Horizontal motion: one full wrap of the pattern width (360° on a full
+                // arena; a partial arena's installed span, e.g. 240° on G4 3x12of18)
                 defaultFrames = pixelCols;
-                hint = `(360° = ${pixelCols} px)`;
+                const degrees = state.arena.config
+                    ? Math.round(pixelCols * getDegreesPerPixel())
+                    : 360;
+                hint = `(${degrees}° = ${pixelCols} px)`;
             } else {
                 // Vertical motion: full vertical traverse
                 defaultFrames = pixelRows;
diff --git a/tests/test-pattern-degrees-per-pixel.js b/tests/test-pattern-degrees-per-pixel.js
new file mode 100644
index 00000000..e5a36281
--- /dev/null
+++ b/tests/test-pattern-degrees-per-pixel.js
@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Pattern Designer degrees-per-pixel regression (partial arenas).
+ *
+ * A partial arena keeps the FULL arena's pixel pitch: G4 3×12of18 has 12 of 18 columns
+ * installed, 16 px per panel, so its pitch is 360° / (18 × 16) = 1.25°/px, not
+ * 360° / (12 × 16) = 1.875°/px. The pattern generator already uses the full circle
+ * (`numCircle = num_cols`); the editor's px↔° conversions must use the same pitch, or a
+ * spatial period typed in pixels generates the wrong grating (24 px came out as 45°).
+ *
+ * The editor's helpers live inside pattern_editor.html's module script, so this test
+ * extracts them by name and runs them against a stub `state`, together with the real
+ * PatternGenerator and arena configs.
+ */
+const fs = require('fs');
+const path = require('path');
+const vm = require('vm');
+
+const ROOT = path.join(__dirname, '..');
+const { STANDARD_CONFIGS, PANEL_SPECS } = require('../js/arena-configs.js');
+global.PANEL_SPECS = PANEL_SPECS;
+const PatternGenerator = require('../js/pattern-editor/tools/generator.js');
+
+const html = fs.readFileSync(path.join(ROOT, 'pattern_editor.html'), 'utf8');
+
+let checks = 0;
+let failures = 0;
+
+function check(name, condition, detail) {
+    checks++;
+    if (condition) {
+        console.log(`  PASS  ${name}`);
+        return;
+    }
+    failures++;
+    console.log(`  FAIL  ${name}${detail ? ` — ${detail}` : ''}`);
+}
+
+function near(a, b, tol = 1e-9) {
+    return Number.isFinite(a) && Math.abs(a - b) <= tol;
+}
+
+/** Source of `function name(...) {...}` in the editor, by brace matching. */
+function extractFunction(name) {
+    const start = html.indexOf(`function ${name}(`);
+    if (start < 0) throw new Error(`pattern_editor.html: function ${name} not found`);
+    const open = html.indexOf('{', start);
+    let depth = 0;
+    for (let i = open; i < html.length; i++) {
+        if (html[i] === '{') depth++;
+        else if (html[i] === '}' && --depth === 0) return html.slice(start, i + 1);
+    }
+    throw new Error(`pattern_editor.html: unbalanced braces in ${name}`);
+}
+
+const EDITOR_FUNCTIONS = [
+    'getDegreesPerPixel',
+    'convertSpatialFreqToRadians',
+    'convertStepSizeToPixels',
+    'convertStepSizeToRadians'
+];
+
+/** The editor's conversion helpers, bound to a stub state for one arena config. */
+function editorFor(configName) {
+    const sandbox = {
+        PANEL_SPECS,
+        PatternGenerator,
+        Math,
+        state: { arena: { config: configName ? STANDARD_CONFIGS[configName] : null } }
+    };
+    vm.createContext(sandbox);
+    vm.runInContext(EDITOR_FUNCTIONS.map(extractFunction).join('\n'), sandbox);
+    return sandbox;
+}
+
+function arenaFor(configName) {
+    const a = STANDARD_CONFIGS[configName].arena;
+    // Same object the editor's handleGenerate builds.
+    return {
+        generation: a.generation,
+        rows: a.num_rows,
+        cols: a.num_cols,
+        columns_installed: a.columns_installed
+    };
+}
+
+/** Expected pitch: full circumference = num_cols × pixels_per_panel around 360°. */
+function expectedDegPerPx(configName) {
+    const a = STANDARD_CONFIGS[configName].arena;
+    return 360 / (a.num_cols * PANEL_SPECS[a.generation].pixels_per_panel);
+}
+
+console.log('\n=== editor getDegreesPerPixel: full circumference, every standard config ===');
+const PINNED = {
+    G4_3x12of18: 1.25, // 18 × 16 = 288 px around (12 installed)
+    G6_3x12of18: 1.0, // 18 × 20 = 360 px around (12 installed)
+    G6_2x8of10: 1.8, // 10 × 20 = 200 px around (8 installed)
+    G6_2x10: 1.8,
+    G6_3x10: 1.8,
+    G6_4x10: 1.8,
+    G6_3x16_full: 1.125,
+    G4_3x12: 1.875,
+    G4_4x12: 1.875,
+    G41_2x12_cw: 1.875,
+    G3_3x24: 1.875,
+    G3_4x12: 3.75
+};
+for (const name of Object.keys(STANDARD_CONFIGS)) {
+    const got = editorFor(name).getDegreesPerPixel();
+    const want = PINNED[name] ?? expectedDegPerPx(name);
+    check(`${name}: ${want}°/px`, near(got, want), `got ${got}`);
+    check(
+        `${name}: pinned value = 360 / (num_cols × px/panel)`,
+        near(want, expectedDegPerPx(name))
+    );
+}
+check(
+    'no arena selected: G6 2×10 default 1.8°/px',
+    near(editorFor(null).getDegreesPerPixel(), 1.8)
+);
+
+console.log('\n=== shared helper: PatternGenerator.getDegreesPerPixel ===');
+check(
+    'PatternGenerator.getDegreesPerPixel exists',
+    typeof PatternGenerator.getDegreesPerPixel === 'function'
+);
+if (typeof PatternGenerator.getDegreesPerPixel === 'function') {
+    for (const name of Object.keys(STANDARD_CONFIGS)) {
+        const cfg = STANDARD_CONFIGS[name];
+        check(
+            `${name}: generator arena object`,
+            near(PatternGenerator.getDegreesPerPixel(arenaFor(name)), expectedDegPerPx(name))
+        );
+        check(
+            `${name}: raw config.arena (num_cols form)`,
+            near(PatternGenerator.getDegreesPerPixel(cfg.arena), expectedDegPerPx(name))
+        );
+        check(
+            `${name}: whole config ({arena: …} form)`,
+            near(PatternGenerator.getDegreesPerPixel(cfg), expectedDegPerPx(name))
+        );
+    }
+    const dims = PatternGenerator.getArenaDimensions(arenaFor('G4_3x12of18'));
+    check('G4 12of18 dims: pattern is 192 px wide (installed)', dims.pixelCols === 192);
+    check('G4 12of18 dims: 288 azimuth px (full circle)', dims.azimuthPixels === 288);
+    check('G4 12of18 dims: circleCols = 18', dims.circleCols === 18);
+}
+
+console.log('\n=== px ↔ ° conversions on G4 3×12of18 (1.25°/px) ===');
+{
+    const ed = editorFor('G4_3x12of18');
+    const rad = Math.PI / 180;
+    check('24 px period = 30°', near(ed.convertSpatialFreqToRadians(24, 'px'), 30 * rad));
+    check('30° period = 30°', near(ed.convertSpatialFreqToRadians(30, 'deg'), 30 * rad));
+    check('1.25° step = 1 px', near(ed.convertStepSizeToPixels(1.25, 'deg'), 1));
+    check('1 px step = 1 px', near(ed.convertStepSizeToPixels(1, 'px'), 1));
+    check('1 px step = 1.25° (radians)', near(ed.convertStepSizeToRadians(1, 'px'), 1.25 * rad));
+}
+
+console.log('\n=== end to end: a period typed in px generates that period ===');
+/**
+ * Generate a rotation grating the way handleGenerate does and measure it: frame count
+ * (= one period at a 1 px step) and the bright-run length along the middle row.
+ */
+function generateGrating(configName, spatialValue, spatialUnit, stepValue, stepUnit) {
+    const ed = editorFor(configName);
+    return PatternGenerator.generateSphericalGrating(
+        {
+            high: 15,
+            low: 0,
+            gsMode: 2,
+            stretch: 1,
+            spatFreq: ed.convertSpatialFreqToRadians(spatialValue, spatialUnit),
+            motionType: 'rotation',
+            waveform: 'square',
+            dutyCycle: 50,
+            stepSize: ed.convertStepSizeToPixels(stepValue, stepUnit),
+            aaSamples: 1,
+            arenaModel: 'smooth',
+            phaseShift: 0,
+            poleCoord: [0, -Math.PI / 2]
+        },
+        arenaFor(configName)
+    );
+}
+
+function runLengths(pattern) {
+    const row = Math.floor(pattern.pixelRows / 2);
+    const f = pattern.frames[0];
+    const vals = [];
+    for (let c = 0; c < pattern.pixelCols; c++) vals.push(f[row * pattern.pixelCols + c] > 0);
+    const runs = [];
+    let len = 1;
+    for (let c = 1; c < vals.length; c++) {
+        if (vals[c] === vals[c - 1]) len++;
+        else {
+            runs.push(len);
+            len = 1;
+        }
+    }
+    runs.push(len);
+    return runs.slice(1, -1); // interior runs only (the edges may be clipped)
+}
+
+const CASES = [
+    // [config, value, unit, expected period px]
+    ['G4_3x12of18', 24, 'px', 24],
+    ['G4_3x12of18', 30, 'deg', 24],
+    ['G6_3x12of18', 30, 'px', 30],
+    ['G6_3x12of18', 30, 'deg', 30],
+    ['G6_2x8of10', 20, 'px', 20],
+    ['G6_2x8of10', 36, 'deg', 20],
+    ['G6_2x10', 20, 'px', 20],
+    ['G4_4x12', 24, 'px', 24]
+];
+for (const [name, value, unit, period] of CASES) {
+    const pattern = generateGrating(name, value, unit, 1, 'px');
+    const runs = runLengths(pattern);
+    check(
+        `${name}: ${value} ${unit} period → ${period} frames at a 1 px step`,
+        pattern.numFrames === period,
+        `got ${pattern.numFrames}`
+    );
+    check(
+        `${name}: ${value} ${unit} period → ${period / 2}-px bars`,
+        runs.length > 0 && runs.every((r) => r === period / 2),
+        `runs ${JSON.stringify(runs)}`
+    );
+}
+{
+    const pattern = generateGrating('G4_3x12of18', 30, 'deg', 1.25, 'deg');
+    check(
+        'G4_3x12of18: 1.25° step on a 30° period → 24 frames',
+        pattern.numFrames === 24,
+        `got ${pattern.numFrames}`
+    );
+}
+
+console.log('\n=== editor wiring ===');
+check(
+    'pattern_editor.html cache-busts generator.js (init calls the new helper)',
+    /<script src="js\/pattern-editor\/tools\/generator\.js\?v=[^"]+"><\/script>/.test(html)
+);
+check(
+    'getDegreesPerPixel delegates to the shared PatternGenerator helper',
+    /PatternGenerator\.getDegreesPerPixel\(/.test(extractFunction('getDegreesPerPixel'))
+);
+
+console.log(`\n${checks - failures}/${checks} checks passed`);
+if (failures > 0) {
+    console.log(`${failures} FAILED`);
+    process.exit(1);
+}

From 9b851e6ca73a204e1ef4b0b4e59ee26ac07bdd8b Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Tue, 6 Oct 2026 14:58:27 -0400
Subject: [PATCH 03/17] fix(3d-viewer): partial arenas show each PAT panel on
 its installed column

A partial arena's PAT stores only the installed columns, in columns_installed order
(block k = physical column columns_installed[k], the icon generator's convention).
ThreeViewer looked pixels up by the PHYSICAL column instead. Harmless when the
installed columns start at 0 (G4/G6 3x12of18), but on G6 2x8of10 (columns 1-8)
the whole pattern showed one panel to the side, pattern panel 1 never appeared, and
physical column 8 read block 0 of the next pixel row (the lookup wrapped at the full
circle, past the 160-px pattern width).

_getPatternColumnMap() maps physical column -> block from the CONFIGURED columns
(never the preview-visible set, so the CSHL 8/18 gap still doesn't shift the address
map); each LED ref carries patternCol; the lookup wraps inside the pattern width.
Shared by the Pattern Designer and the replay viewer, so the cache token moves to
1006-partial-cols in both (and the tests that pin it).

tests/test-three-viewer-partial-columns.js loads the viewer with Three.js stubbed and
checks every LED of every standard config reads its own block and row; against main's
viewer it fails only on G6_2x8of10 (column 1 showed block 2).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 arena_replay_viewer.html                     |   4 +-
 js/arena-replay-viewer.js                    |   2 +-
 js/pattern-editor/viewers/three-viewer.js    |  45 +++++-
 pattern_editor.html                          |   2 +-
 tests/test-arena-replay-viewer-protocol.js   |   4 +-
 tests/test-three-viewer-led-glow.js          |   8 +-
 tests/test-three-viewer-partial-columns.js   | 148 +++++++++++++++++++
 tests/test-three-viewer-preview-omissions.js |  18 ++-
 8 files changed, 213 insertions(+), 18 deletions(-)
 create mode 100644 tests/test-three-viewer-partial-columns.js

diff --git a/arena_replay_viewer.html b/arena_replay_viewer.html
index dd6e7b08..71c28ec3 100644
--- a/arena_replay_viewer.html
+++ b/arena_replay_viewer.html
@@ -505,8 +505,8 @@
             <span class="orbit-hint">Drag to orbit · scroll to zoom · “Fly” for a close-up</span>
         </footer>
 
-        <script src="js/arena-replay-viewer-protocol.js?v=0713-solid-ball"></script>
+        <script src="js/arena-replay-viewer-protocol.js?v=1006-partial-cols"></script>
         <script src="js/fly-gait.js?v=20260926-gait"></script>
-        <script type="module" src="js/arena-replay-viewer.js?v=0713-solid-ball"></script>
+        <script type="module" src="js/arena-replay-viewer.js?v=1006-partial-cols"></script>
     </body>
 </html>
diff --git a/js/arena-replay-viewer.js b/js/arena-replay-viewer.js
index ebcd7118..58ca252e 100644
--- a/js/arena-replay-viewer.js
+++ b/js/arena-replay-viewer.js
@@ -1,6 +1,6 @@
 import * as THREE from 'https://cdn.jsdelivr.net/npm/three@0.182.0/build/three.module.js';
 import PatParser from './pat-parser.js';
-import ThreeViewer from './pattern-editor/viewers/three-viewer.js?v=0713-solid-ball';
+import ThreeViewer from './pattern-editor/viewers/three-viewer.js?v=1006-partial-cols';
 import { PANEL_SPECS, STANDARD_CONFIGS, getArenaName, getConfig } from './arena-configs.js';
 
 const Protocol = window.ArenaReplayViewerProtocol;
diff --git a/js/pattern-editor/viewers/three-viewer.js b/js/pattern-editor/viewers/three-viewer.js
index 49f41b3f..cfd2bf37 100644
--- a/js/pattern-editor/viewers/three-viewer.js
+++ b/js/pattern-editor/viewers/three-viewer.js
@@ -631,6 +631,18 @@ class ThreeViewer {
         }
     }
 
+    /**
+     * Map each installed physical column to its panel block in the PAT. A partial arena's
+     * pattern stores only the installed columns, in columns_installed order, so block k is
+     * physical column columns_installed[k] (G6_2x8of10: column 1 is block 0). Full arenas
+     * map identically. Built from the CONFIGURED columns, never the preview-visible set, so
+     * the CSHL rear-panel omission does not shift the PAT address map.
+     * @returns {Map<number, number>} physical column index -> pattern panel block
+     */
+    _getPatternColumnMap() {
+        return new Map([...this._getInstalledColumnsSet()].map((col, block) => [col, block]));
+    }
+
     /**
      * Return columns rendered by the preview. Panels 8 and 18 are a physical
      * CSHL omission that is deliberately absent from the rig/config registry.
@@ -721,6 +733,7 @@ class ThreeViewer {
         // Note: Three.js uses right-handed coords but top-down view has +Z toward viewer,
         // so we negate Z to match MATLAB's top-down appearance
         const visibleColumns = this._getVisibleColumnsSet();
+        const patternColumns = this._getPatternColumnMap();
 
         for (let col = 0; col < numCols; col++) {
             // Skip config-level omissions and the visual-only CSHL panels 8/18 rear gap.
@@ -747,7 +760,8 @@ class ThreeViewer {
                 numRows,
                 col,
                 numCols,
-                columnOrder
+                columnOrder,
+                patternColumns.get(col)
             );
             columnGroup.position.set(x, 0, z);
             columnGroup.userData.columnIndex = col;
@@ -885,7 +899,18 @@ class ThreeViewer {
         this.controls.update();
     }
 
-    _createColumn(specs, width, height, depth, angle, numRows, colIndex, numCols, columnOrder) {
+    _createColumn(
+        specs,
+        width,
+        height,
+        depth,
+        angle,
+        numRows,
+        colIndex,
+        numCols,
+        columnOrder,
+        patternCol = colIndex
+    ) {
         const group = new THREE.Group();
 
         // Apply rotation to face center (matches standalone viewer exactly)
@@ -1023,6 +1048,7 @@ class ThreeViewer {
                     this.ledMeshes.push({
                         mesh: rect,
                         colIndex: colIndex,
+                        patternCol: patternCol,
                         px: px,
                         py: py,
                         totalPixelsH: totalPixelsH,
@@ -1078,6 +1104,7 @@ class ThreeViewer {
                     this.ledMeshes.push({
                         mesh: led,
                         colIndex: colIndex,
+                        patternCol: patternCol,
                         px: px,
                         py: py,
                         totalPixelsH: totalPixelsH,
@@ -1185,7 +1212,10 @@ class ThreeViewer {
     }
 
     _getLEDBrightness(ledRef) {
-        const { px, py, colIndex, totalPixelsH, numCols, columnOrder } = ledRef;
+        const { px, py, colIndex, totalPixelsH, columnOrder } = ledRef;
+        // The LED's panel block in the PAT (see _getPatternColumnMap); refs built without
+        // one fall back to the physical column, which is the same on full arenas.
+        const patternCol = ledRef.patternCol ?? colIndex;
         const pattern = this.state.pattern;
 
         if (!pattern || !pattern.frames || pattern.frames.length === 0) {
@@ -1196,7 +1226,9 @@ class ThreeViewer {
         if (!frame) return 0.0;
 
         const pixelsPerPanel = totalPixelsH;
-        const totalAzimuthPixels = numCols * totalPixelsH;
+        // Wrap within the pattern's own width: a partial arena's PAT holds only the
+        // installed columns, so wrapping at the full circle would spill into the next row.
+        const patternWidth = pattern.pixelCols;
 
         // For CCW mode, mirror the pixel index within each panel
         // to ensure grating tiles correctly when columns are placed clockwise
@@ -1205,8 +1237,9 @@ class ThreeViewer {
         // Calculate global X with phase offset support
         const phaseOffset = this.state.phaseOffset || 0;
         const globalX =
-            (colIndex * pixelsPerPanel + effectivePx + phaseOffset + totalAzimuthPixels) %
-            totalAzimuthPixels;
+            (((patternCol * pixelsPerPanel + effectivePx + phaseOffset) % patternWidth) +
+                patternWidth) %
+            patternWidth;
         const globalY = py;
 
         // Row-major index: row * numCols + col
diff --git a/pattern_editor.html b/pattern_editor.html
index e1385c5f..09534c85 100644
--- a/pattern_editor.html
+++ b/pattern_editor.html
@@ -2565,7 +2565,7 @@ <h3 class="modal-title">Save to Repo</h3>
 
     <script type="module">
         import PatParser from './js/pat-parser.js';
-        import ThreeViewer from './js/pattern-editor/viewers/three-viewer.js?v=0713-solid-ball';
+        import ThreeViewer from './js/pattern-editor/viewers/three-viewer.js?v=1006-partial-cols';
         import MercatorViewer from './js/pattern-editor/viewers/mercator-viewer.js?v=0218';
         import MollweideViewer from './js/pattern-editor/viewers/mollweide-viewer.js?v=0218';
         import { combinePatterns } from './js/pattern-editor/tools/combiner.js';
diff --git a/tests/test-arena-replay-viewer-protocol.js b/tests/test-arena-replay-viewer-protocol.js
index 6a60a490..879a63a7 100644
--- a/tests/test-arena-replay-viewer-protocol.js
+++ b/tests/test-arena-replay-viewer-protocol.js
@@ -331,8 +331,8 @@ check(
 );
 check(
     'popup cache-busts the camera projection helper with its entry module',
-    html.includes('arena-replay-viewer-protocol.js?v=0713-solid-ball') &&
-        html.includes('arena-replay-viewer.js?v=0713-solid-ball')
+    html.includes('arena-replay-viewer-protocol.js?v=1006-partial-cols') &&
+        html.includes('arena-replay-viewer.js?v=1006-partial-cols')
 );
 check(
     'popup loads the walking model (classic) before the viewer module',
diff --git a/tests/test-three-viewer-led-glow.js b/tests/test-three-viewer-led-glow.js
index a3046e0f..6d7c35f5 100644
--- a/tests/test-three-viewer-led-glow.js
+++ b/tests/test-three-viewer-led-glow.js
@@ -139,6 +139,8 @@ check(
 );
 
 console.log('\n=== shared consumer cache boundaries ===');
+// Revisions at or after the glow layer (0713-solid-ball; 1006-partial-cols builds on it).
+const GLOW_REVISION = /glow|0713|1006-partial-cols/i;
 const patternImport = patternEditor.match(
     /from\s+['"]\.\/js\/pattern-editor\/viewers\/three-viewer\.js\?([^'"]+)['"]/
 );
@@ -150,15 +152,15 @@ const replayEntry = replayHtml.match(
 );
 check(
     'Pattern Editor cache-busts the shared ThreeViewer revision',
-    Boolean(patternImport && /glow|0713/i.test(patternImport[1]))
+    Boolean(patternImport && GLOW_REVISION.test(patternImport[1]))
 );
 check(
     'Replay imports the same cache-busted shared ThreeViewer',
-    Boolean(replayImport && /glow|0713/i.test(replayImport[1]))
+    Boolean(replayImport && GLOW_REVISION.test(replayImport[1]))
 );
 check(
     'Replay HTML cache-busts its module import edge',
-    Boolean(replayEntry && /glow|0713/i.test(replayEntry[1]))
+    Boolean(replayEntry && GLOW_REVISION.test(replayEntry[1]))
 );
 
 console.log(`\n${checks - failures} / ${checks} checks passed`);
diff --git a/tests/test-three-viewer-partial-columns.js b/tests/test-three-viewer-partial-columns.js
new file mode 100644
index 00000000..da7cf8d8
--- /dev/null
+++ b/tests/test-three-viewer-partial-columns.js
@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * ThreeViewer PAT lookup on partial arenas.
+ *
+ * A partial arena's PAT stores only the installed columns, in columns_installed order:
+ * pattern panel block k is physical column columns_installed[k] (the icon generator's
+ * convention). The 3D viewer used the PHYSICAL column as the block, so G6_2x8of10
+ * (columns 1–8) showed the pattern one panel to the side, and physical column 8 read
+ * block 0 of the NEXT pixel row.
+ *
+ * three-viewer.js imports Three.js from a CDN, so it is loaded here with those imports
+ * stubbed out; the methods under test never touch THREE.
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { pathToFileURL } = require('url');
+
+const ROOT = path.join(__dirname, '..');
+const { STANDARD_CONFIGS, PANEL_SPECS } = require('../js/arena-configs.js');
+
+let checks = 0;
+let failures = 0;
+
+function check(name, condition, detail) {
+    checks++;
+    if (condition) {
+        console.log(`  PASS  ${name}`);
+        return;
+    }
+    failures++;
+    console.log(`  FAIL  ${name}${detail ? ` — ${detail}` : ''}`);
+}
+
+async function loadThreeViewer() {
+    const src = fs.readFileSync(
+        path.join(ROOT, 'js', 'pattern-editor', 'viewers', 'three-viewer.js'),
+        'utf8'
+    );
+    const stubbed = src.replace(
+        /^import[\s\S]*?CSS2DRenderer\.js';\n/m,
+        'const THREE = {};\nconst OrbitControls = null;\n' +
+            'const CSS2DRenderer = null;\nconst CSS2DObject = null;\n'
+    );
+    if (stubbed === src) throw new Error('three-viewer.js: Three.js import block not found');
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'three-viewer-'));
+    const file = path.join(dir, 'three-viewer.mjs');
+    fs.writeFileSync(file, stubbed);
+    try {
+        return (await import(pathToFileURL(file).href)).default;
+    } finally {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+}
+
+/** A viewer instance with just the state the PAT lookup reads. */
+function viewerFor(ThreeViewer, configName, pattern) {
+    const viewer = Object.create(ThreeViewer.prototype);
+    viewer.arenaConfig = STANDARD_CONFIGS[configName];
+    viewer.state = { pattern, currentFrame: 0, phaseOffset: 0 };
+    return viewer;
+}
+
+/**
+ * A PAT-sized frame whose every pixel encodes where it came from:
+ * value = (row % 2) * 100 + block + 1, so a wrong block OR a row spill is visible.
+ */
+function labelledPattern(arena) {
+    const ppp = PANEL_SPECS[arena.generation].pixels_per_panel;
+    const blocks = arena.columns_installed ? arena.columns_installed.length : arena.num_cols;
+    const pixelCols = blocks * ppp;
+    const pixelRows = arena.num_rows * ppp;
+    const frame = new Uint8Array(pixelCols * pixelRows);
+    for (let r = 0; r < pixelRows; r++) {
+        for (let c = 0; c < pixelCols; c++) {
+            frame[r * pixelCols + c] = (r % 2) * 100 + Math.floor(c / ppp) + 1;
+        }
+    }
+    return { frames: [frame], pixelCols, pixelRows, gsMode: 16, numFrames: 1 };
+}
+
+(async () => {
+    const ThreeViewer = await loadThreeViewer();
+
+    console.log('\n=== physical column -> PAT panel block ===');
+    {
+        const map = viewerFor(ThreeViewer, 'G6_2x8of10', null)._getPatternColumnMap();
+        check('G6_2x8of10: physical column 1 is block 0', map.get(1) === 0);
+        check('G6_2x8of10: physical column 8 is block 7', map.get(8) === 7);
+        check('G6_2x8of10: the gap columns 0 and 9 have no block', !map.has(0) && !map.has(9));
+        const g4 = viewerFor(ThreeViewer, 'G4_3x12of18', null)._getPatternColumnMap();
+        check(
+            'G4_3x12of18: columns 0..11 map to blocks 0..11',
+            [...Array(12).keys()].every((c) => g4.get(c) === c) && g4.size === 12
+        );
+        const full = viewerFor(ThreeViewer, 'G6_2x10', null)._getPatternColumnMap();
+        check(
+            'G6_2x10 (full; CSHL gap is preview-only): identity over all 10 columns',
+            [...Array(10).keys()].every((c) => full.get(c) === c) && full.size === 10
+        );
+    }
+
+    console.log('\n=== every LED reads its own block and row, every standard config ===');
+    for (const name of Object.keys(STANDARD_CONFIGS)) {
+        const arena = STANDARD_CONFIGS[name].arena;
+        const ppp = PANEL_SPECS[arena.generation].pixels_per_panel;
+        const pattern = labelledPattern(arena);
+        const viewer = viewerFor(ThreeViewer, name, pattern);
+        const installed = arena.columns_installed || [...Array(arena.num_cols).keys()];
+        const bad = [];
+        for (const col of viewer._getVisibleColumnsSet()) {
+            const block = installed.indexOf(col);
+            for (const px of [0, ppp - 1]) {
+                for (const py of [0, pattern.pixelRows - 1]) {
+                    const ledRef = {
+                        colIndex: col,
+                        patternCol: viewer._getPatternColumnMap().get(col),
+                        px,
+                        py,
+                        totalPixelsH: ppp,
+                        numCols: arena.num_cols,
+                        numRows: arena.num_rows,
+                        columnOrder: arena.column_order || 'cw'
+                    };
+                    const got = Math.round(viewer._getLEDBrightness(ledRef) * 15);
+                    const want = (py % 2) * 100 + block + 1;
+                    if (got !== want) bad.push(`col ${col} px ${px} py ${py}: ${got} != ${want}`);
+                }
+            }
+        }
+        check(
+            `${name}: LEDs show their own panel block`,
+            bad.length === 0,
+            bad.slice(0, 3).join('; ')
+        );
+    }
+
+    console.log(`\n${checks - failures}/${checks} checks passed`);
+    if (failures > 0) {
+        console.log(`${failures} FAILED`);
+        process.exit(1);
+    }
+})().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});
diff --git a/tests/test-three-viewer-preview-omissions.js b/tests/test-three-viewer-preview-omissions.js
index a3cbb2c7..abea2912 100644
--- a/tests/test-three-viewer-preview-omissions.js
+++ b/tests/test-three-viewer-preview-omissions.js
@@ -116,9 +116,21 @@ check(
         /totalLEDs\s*=\s*totalPanels/.test(stats)
 );
 const brightness = methodSlice('_getLEDBrightness', '_brightnessToColor');
+const patternColumnMap = methodSlice('_getPatternColumnMap', '_getVisibleColumnsSet');
 check(
-    'PAT lookup keeps original configured colIndex positions',
-    /colIndex\s*\*\s*pixelsPerPanel\s*\+\s*effectivePx/.test(brightness)
+    'PAT lookup indexes by the pattern column block of each physical column',
+    /patternCol\s*\*\s*pixelsPerPanel\s*\+\s*effectivePx/.test(brightness) &&
+        /patternColumns\.get\(col\)/.test(buildArena)
+);
+check(
+    'pattern column blocks come from the configured columns, not the preview-visible set',
+    /this\._getInstalledColumnsSet\(\)/.test(patternColumnMap) &&
+        !/_getVisibleColumnsSet/.test(patternColumnMap)
+);
+check(
+    'PAT lookup wraps inside the pattern width (no spill into the next row)',
+    /patternWidth\s*=\s*pattern\.pixelCols/.test(brightness) &&
+        !/totalAzimuthPixels/.test(brightness)
 );
 check(
     'the G6_2x10 registry remains a full logical arena',
@@ -140,7 +152,7 @@ const replayToken = cacheToken(replayModule, /three-viewer\.js\?v=([^'"]+)['"]/i
 const replayEntryToken = cacheToken(replayHtml, /arena-replay-viewer\.js\?v=([^'"]+)['"]/i);
 check(
     'Pattern Designer and replay import the same preview-gap revision',
-    patternToken === '0713-solid-ball' && replayToken === patternToken,
+    patternToken === '1006-partial-cols' && replayToken === patternToken,
     `${patternToken} / ${replayToken}`
 );
 check(

From c2a83f2acc1ec96511a49b0400b40cf74a4345f0 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Tue, 6 Oct 2026 15:31:56 -0400
Subject: [PATCH 04/17] fix(icons): pattern thumbnails were mirrored
 top-to-bottom

renderCylindricalIconToCanvas drew math angles (y up) straight onto the canvas (y down),
so every icon was the 3D "Top Down" view mirrored: the gap (behind the fly) at the TOP and
the columns running counter-clockwise. TESTING.md always expected the gap at the bottom.
Angles are now negated at the drawing step (toCanvas), so icons match the 3D viewer and
MATLAB design_arena: south at the bottom, column 0 at the south boundary, columns clockwise
from above. The misleading "row 0 = top of arena" comment is corrected (row 0 is the
bottom; it maps to the inner ring, as in a perspective view from above).

Shared by the Studio, Console and Pattern Designer thumbnails. No export changes.
tests/test-icon-orientation.js records the canvas arcs and checks column 1 and 2 of every
standard config against the 3D viewer's placement; the old code failed 21 of 27 checks
(G6 2x10 column 1 drawn at -18 deg instead of -162 deg).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 TESTING.md                     |  17 ++--
 js/icon-generator.js           |  39 ++++----
 tests/test-icon-orientation.js | 163 +++++++++++++++++++++++++++++++++
 3 files changed, 193 insertions(+), 26 deletions(-)
 create mode 100644 tests/test-icon-orientation.js

diff --git a/TESTING.md b/TESTING.md
index 1b1ec2ac..7b7d87f2 100644
--- a/TESTING.md
+++ b/TESTING.md
@@ -71,15 +71,14 @@
 
 ## Arena Orientation Notes
 
-Current column mapping (column_order='cw'):
-- Column 0 starts at south (-90°)
-- Columns increase counter-clockwise (angles decrease)
-- For partial arena test: columns 0 and 9 are missing
-
-Expected orientation for partial arenas:
-- Gap should appear at bottom (south) for R/L symmetry
-- Currently gap appears bottom-right
-- May need further adjustment to column_order or angle_offset
+The icon is the same top-down picture as the 3D viewer's "Top Down" view and MATLAB
+`design_arena` (fixed 2026-10-06, LAB-295; before that the icon was mirrored top-to-bottom):
+- South (behind the fly) is at the bottom, the front at the top.
+- Column 0 starts at the south boundary; with column_order='cw' the columns run clockwise
+  seen from above (behind → fly's left → front → right).
+- On a partial arena the gap sits at the bottom, centered (e.g. G6_2x8of10: columns 0 and 9
+  missing, pattern column 1 lights physical column 1 at the lower-left of the gap).
+- `tests/test-icon-orientation.js` checks this against the 3D viewer for every standard config.
 
 ## Validation Summary
 
diff --git a/js/icon-generator.js b/js/icon-generator.js
index b6cce58d..ab450b7b 100644
--- a/js/icon-generator.js
+++ b/js/icon-generator.js
@@ -259,9 +259,13 @@ function renderCylindricalIconToCanvas(frameData, patternData, arenaConfig, opts
     const patternRowPixels = patternData.rows;
     const installedColumnCount = columnsInstalled.length;
 
-    // Base offset: -90° to start at south (-PI/2)
-    // In canvas: 0° = right (East), -90° = down (South), angles go counter-clockwise
-    const BASE_OFFSET_RAD = -Math.PI / 2;
+    // Angles below are MATH angles (0 = east, +90° = north, counter-clockwise positive), the
+    // same top-down convention as the 3D viewer and MATLAB design_arena: south (behind the fly)
+    // at the bottom, columns running clockwise from c0. The canvas y axis points DOWN, so a
+    // canvas angle is the negated math angle (toCanvas); drawing math angles directly mirrored
+    // the icon top-to-bottom (gap at the top, columns counter-clockwise).
+    const BASE_OFFSET_RAD = -Math.PI / 2; // south
+    const toCanvas = (mathAngle) => -mathAngle;
     const alpha = (2 * Math.PI) / numCols; // angle per column (full arena)
 
     // Arena-specific angular offset (e.g., for aligning gap position)
@@ -272,11 +276,10 @@ function renderCylindricalIconToCanvas(frameData, patternData, arenaConfig, opts
         const colIdx = columnsInstalled[installedIdx]; // Physical column position
 
         // Calculate angular position for this column based on column_order
-        // CW: c0 spans from South boundary leftward (counter-clockwise), columns continue CCW
-        // CCW: c0 spans from South boundary rightward (clockwise), columns continue CW
+        // CW: c0 starts at the south boundary and columns continue clockwise seen from above
+        // (behind → fly's left → front → right). CCW: the mirror image.
         let colStartAngle, colEndAngle;
         if (columnOrder === 'cw') {
-            // Column 0 left edge at South, right edge at South - alpha
             colStartAngle = BASE_OFFSET_RAD - colIdx * alpha + angleOffsetRad;
             colEndAngle = BASE_OFFSET_RAD - (colIdx + 1) * alpha + angleOffsetRad;
         } else {
@@ -292,12 +295,12 @@ function renderCylindricalIconToCanvas(frameData, patternData, arenaConfig, opts
         for (let rowIdx = 0; rowIdx < numRows; rowIdx++) {
             // Render each pixel in this panel
             for (let py = 0; py < pixelsPerPanel; py++) {
-                // Calculate vertical pixel index (0 = top row, top pixel)
+                // Pattern row index (row 0 = bottom of the arena, the .pat convention)
                 const verticalPixelIdx = rowIdx * pixelsPerPanel + py;
 
-                // Map vertical position to radius:
-                // Row 0 (top of arena) → inner edge of ring (center)
-                // Row N (bottom of arena) → outer edge of ring
+                // Map vertical position to radius, as in a perspective view from above:
+                // row 0 (bottom, farther from the viewer) → inner edge of the ring,
+                // top row (nearer the viewer) → outer edge
                 const verticalFraction = verticalPixelIdx / totalVerticalPixels;
                 const pixelInnerRadius = innerRadius + verticalFraction * radiusRange;
                 const pixelOuterRadius =
@@ -323,13 +326,15 @@ function renderCylindricalIconToCanvas(frameData, patternData, arenaConfig, opts
                           )
                         : brightnessToRGB(brightness, patternData.grayscaleMode);
 
-                    // Calculate angular position for this pixel
-                    const pixelAngle =
-                        colStartAngle + (px / pixelsPerPanel) * (colEndAngle - colStartAngle);
+                    // Calculate angular position for this pixel (canvas angles)
+                    const pixelAngle = toCanvas(
+                        colStartAngle + (px / pixelsPerPanel) * (colEndAngle - colStartAngle)
+                    );
 
                     // Calculate next pixel angle for width
-                    const nextPixelAngle =
-                        colStartAngle + ((px + 1) / pixelsPerPanel) * (colEndAngle - colStartAngle);
+                    const nextPixelAngle = toCanvas(
+                        colStartAngle + ((px + 1) / pixelsPerPanel) * (colEndAngle - colStartAngle)
+                    );
 
                     // Ensure we always draw the shorter arc by using min/max
                     const minAngle = Math.min(pixelAngle, nextPixelAngle);
@@ -371,9 +376,9 @@ function renderCylindricalIconToCanvas(frameData, patternData, arenaConfig, opts
             if (isCurrentInstalled !== isNextInstalled) {
                 let angle;
                 if (columnOrder === 'cw') {
-                    angle = BASE_OFFSET_RAD - (colIdx + 1) * alpha + angleOffsetRad;
+                    angle = toCanvas(BASE_OFFSET_RAD - (colIdx + 1) * alpha + angleOffsetRad);
                 } else {
-                    angle = BASE_OFFSET_RAD + (colIdx + 1) * alpha + angleOffsetRad;
+                    angle = toCanvas(BASE_OFFSET_RAD + (colIdx + 1) * alpha + angleOffsetRad);
                 }
 
                 // Draw radial line at boundary
diff --git a/tests/test-icon-orientation.js b/tests/test-icon-orientation.js
new file mode 100644
index 00000000..8e288a45
--- /dev/null
+++ b/tests/test-icon-orientation.js
@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Pattern icon orientation: the cylindrical thumbnail (js/icon-generator.js) must be the same
+ * top-down picture as the 3D viewer's "Top Down" view and MATLAB design_arena: south (behind
+ * the fly) at the bottom, front at the top, columns running clockwise from c0.
+ *
+ * The canvas y axis points down, so math angles drawn directly mirrored the icon top-to-bottom
+ * (gap at the top, columns counter-clockwise). This test stubs a 2D canvas, records every arc,
+ * and checks where the lit pattern blocks land for every standard config, against the 3D
+ * viewer's column placement (three-viewer.js _buildArena).
+ */
+const path = require('path');
+const { pathToFileURL } = require('url');
+
+const ROOT = path.join(__dirname, '..');
+const { STANDARD_CONFIGS, PANEL_SPECS } = require('../js/arena-configs.js');
+globalThis.PANEL_SPECS = PANEL_SPECS;
+
+let checks = 0;
+let failures = 0;
+
+function check(name, condition, detail) {
+    checks++;
+    if (condition) {
+        console.log(`  PASS  ${name}`);
+        return;
+    }
+    failures++;
+    console.log(`  FAIL  ${name}${detail ? ` — ${detail}` : ''}`);
+}
+
+/** A canvas stub whose 2D context records each filled path's style and first arc. */
+function recordingCanvas() {
+    const paths = [];
+    let current = null;
+    const ctx = {
+        fillStyle: '',
+        strokeStyle: '',
+        lineWidth: 1,
+        scale() {},
+        fillRect() {},
+        beginPath() {
+            current = { arcs: [] };
+        },
+        arc(x, y, r, a0, a1) {
+            if (current) current.arcs.push({ r, a0, a1 });
+        },
+        closePath() {},
+        fill() {
+            if (current) paths.push({ style: ctx.fillStyle, arcs: current.arcs });
+        },
+        moveTo() {},
+        lineTo() {},
+        stroke() {}
+    };
+    return {
+        paths,
+        canvas: { width: 0, height: 0, getContext: () => ctx, toDataURL: () => 'data:' }
+    };
+}
+
+const deg = (r) => (r * 180) / Math.PI;
+const wrap = (a) => ((((a + 180) % 360) + 360) % 360) - 180;
+
+/** Fly-centric azimuth of a canvas angle: 0 = up (front), + = right (the fly's right). */
+function azimuthOfCanvasAngle(theta) {
+    return wrap(deg(Math.atan2(Math.cos(theta), -Math.sin(theta))));
+}
+
+/** Circular mean of the arc midpoints of the paths drawn in `style`. */
+function meanAzimuth(paths, style) {
+    let sx = 0;
+    let sy = 0;
+    for (const p of paths) {
+        if (p.style !== style || p.arcs.length === 0) continue;
+        const mid = (p.arcs[0].a0 + p.arcs[0].a1) / 2;
+        sx += Math.cos(mid);
+        sy += Math.sin(mid);
+    }
+    return azimuthOfCanvasAngle(Math.atan2(sy, sx));
+}
+
+/** The 3D viewer's column-centre azimuth (three-viewer.js _buildArena; north = front). */
+function viewerAzimuth(arena, col) {
+    const alpha = 360 / arena.num_cols;
+    const off = arena.angle_offset_deg || 0;
+    const angle =
+        arena.column_order === 'ccw'
+            ? -90 + alpha / 2 + col * alpha + off
+            : -90 - alpha / 2 - col * alpha + off;
+    return wrap(90 - angle);
+}
+
+(async () => {
+    const icons = await import(pathToFileURL(path.join(ROOT, 'js', 'icon-generator.js')).href);
+
+    console.log('\n=== icon column placement matches the 3D top-down view ===');
+    for (const [name, cfg] of Object.entries(STANDARD_CONFIGS)) {
+        const arena = cfg.arena;
+        const ppp = PANEL_SPECS[arena.generation].pixels_per_panel;
+        const installed = arena.columns_installed || [...Array(arena.num_cols).keys()];
+        const W = installed.length * ppp;
+        const H = arena.num_rows * ppp;
+        const frame = new Uint8Array(W * H);
+        // block 0 at full brightness, block 1 at half, the rest dark
+        for (let r = 0; r < H; r++) {
+            for (let c = 0; c < ppp; c++) frame[r * W + c] = 15;
+            for (let c = ppp; c < 2 * ppp; c++) frame[r * W + c] = 7;
+        }
+        const rec = recordingCanvas();
+        globalThis.document = { createElement: () => rec.canvas };
+        icons.generatePatternIcon(
+            { frames: [frame], pixelRows: H, pixelCols: W, gs_val: 16 },
+            arena,
+            {
+                width: 200,
+                height: 200,
+                supersample: 1
+            }
+        );
+        const styles = [...new Set(rec.paths.map((p) => p.style))];
+        // block 0 / block 1 are the two lit fill styles, brightest first (green channel)
+        const green = (s) => Number((/rgb\(\s*\d+,\s*(\d+)/.exec(s) || [])[1] || 0);
+        const lit = styles.filter((s) => green(s) > 0).sort((a, b) => green(b) - green(a));
+        const az0 = lit[0] ? meanAzimuth(rec.paths, lit[0]) : NaN;
+        const az1 = lit[1] ? meanAzimuth(rec.paths, lit[1]) : NaN;
+        const want0 = viewerAzimuth(arena, installed[0]);
+        const want1 = viewerAzimuth(arena, installed[1]);
+        check(
+            `${name}: column 1 at ${want0.toFixed(0)}° (3D viewer)`,
+            Math.abs(wrap(az0 - want0)) < 1,
+            `icon puts it at ${az0.toFixed(1)}°`
+        );
+        check(
+            `${name}: column 2 follows clockwise, at ${want1.toFixed(0)}°`,
+            Math.abs(wrap(az1 - want1)) < 1,
+            `icon puts it at ${az1.toFixed(1)}°`
+        );
+    }
+
+    console.log('\n=== partial arenas: the gap is behind the fly (bottom of the icon) ===');
+    for (const name of ['G6_2x8of10', 'G6_3x12of18', 'G4_3x12of18']) {
+        const arena = STANDARD_CONFIGS[name].arena;
+        const installed = arena.columns_installed;
+        const first = viewerAzimuth(arena, installed[0]);
+        const last = viewerAzimuth(arena, installed[installed.length - 1]);
+        check(
+            `${name}: installed span is symmetric about the front (${first.toFixed(0)}° … ${last.toFixed(0)}°)`,
+            Math.abs(first + last) < 1e-9 && first < 0
+        );
+    }
+
+    console.log(`\n${checks - failures}/${checks} checks passed`);
+    if (failures > 0) {
+        console.log(`${failures} FAILED`);
+        process.exit(1);
+    }
+})().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

From e440507998895fcb364094f69ae3dd17566cf4f6 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Tue, 6 Oct 2026 15:31:56 -0400
Subject: [PATCH 05/17] feat(pattern-designer): 2D view shows physical panel
 numbers and an azimuth axis

Panel numbers: the 2D overlay labelled pattern blocks as if they were physical columns and
looped over every num_cols (drawing labels past the right edge on partial arenas). It now
labels each block with its physical panel through physicalPanelNumber() (block k =
columns_installed[k], G6 row-major / older generations column-major), the same numbers as
the 3D overlay: on G6 2x8of10 the first pattern panel reads 2/12, not 1/11.

Azimuth axis: a degree scale under the 2D grid (its own canvas, so edit-mode hit-testing
and captures are unchanged), in pattern coordinates: 0 deg = straight ahead at the middle,
negative to the fly's left; same values as the Mollweide view and the generator. Ticks
pick 15/30/45/60/90 deg to keep labels apart (G4 3x12of18: -120..+120 every 30 deg).

CLAUDE.md gains the three partial-arena rules (full-circle pitch, block k =
columns_installed[k], 0 deg = middle of the pattern) and points at LAB-296 for hardware.
tests/test-pattern-2d-view.js runs the extracted helpers against every standard config,
the 3D overlay's numbering and the Mollweide longitudes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CLAUDE.md                     |   9 ++
 pattern_editor.html           | 111 +++++++++++++++++--
 tests/test-pattern-2d-view.js | 199 ++++++++++++++++++++++++++++++++++
 3 files changed, 309 insertions(+), 10 deletions(-)
 create mode 100644 tests/test-pattern-2d-view.js

diff --git a/CLAUDE.md b/CLAUDE.md
index 24d2f417..b3e9e309 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -643,6 +643,15 @@ localStorage) — no auth UI of its own. Repo layout: free-standing patterns in
   exists-check overwrite confirm.
 - Classic deps added for this: `js/pattern-set.js`, `js/studio-url-state.js` (both
   dual-export; same files the Studio loads).
+- **Partial arenas (LAB-295) — three rules every view and helper follows.** (1) Angular pitch is
+  the FULL circle: `PatternGenerator.getDegreesPerPixel(arena)` = 360 / (num_cols × px/panel)
+  (G4_3x12of18 = 1.25°/px), never the installed width; the generators read the same
+  `getArenaDimensions().circleCols`. (2) A partial PAT stores only the installed columns, in
+  order: pattern block k = physical column `columns_installed[k]` (G6_2x8of10: block 0 = column 1
+  = panels 2/12) — ThreeViewer `_getPatternColumnMap()`, the 2D `physicalPanelNumber()`, the icon.
+  (3) 0° = straight ahead = the middle of the pattern (MATLAB `arena_coordinates`, Mollweide, the 2D
+  azimuth axis). The icon draws math angles negated on the canvas (`toCanvas`; y points down).
+  Hardware does NOT play partial G6 patterns yet (firmware ignores the panel mask) — LAB-296.
 - **Multi-color G6 panels (v0.12, LAB-228) — color is a PANEL property, not a generation.**
   `js/panel-color.js` (classic dual-export, also read as `globalThis.PanelColor` by the ES-module
   viewers) is the ONLY place color logic lives: the layouts table (`g6-green` default,
diff --git a/pattern_editor.html b/pattern_editor.html
index 09534c85..88b29f9b 100644
--- a/pattern_editor.html
+++ b/pattern_editor.html
@@ -2577,6 +2577,9 @@ <h3 class="modal-title">Save to Repo</h3>
         // ============================================
         // State Management
         // ============================================
+        // Height (CSS px) of the 2D view's azimuth axis strip (drawAzimuthAxis)
+        const AZIMUTH_AXIS_HEIGHT = 20;
+
         const state = {
             pattern: null,          // Current loaded/generated pattern
             combinePatternA: null,  // Pattern A for combining (saved separately)
@@ -6785,8 +6788,9 @@ <h2>No Pattern Loaded</h2>
 
             // Calculate pixel size to fit in viewer
             const headerSize = state.editor.editMode ? 24 : 0;
+            const axisSize = state.arena.config ? AZIMUTH_AXIS_HEIGHT : 0;
             const maxWidth = container.clientWidth - 40 - headerSize;
-            const maxHeight = container.clientHeight - 40 - headerSize;
+            const maxHeight = container.clientHeight - 40 - headerSize - axisSize;
             const pixelSize = Math.max(1, Math.min(
                 Math.floor(maxWidth / pixelCols),
                 Math.floor(maxHeight / pixelRows)
@@ -6920,9 +6924,11 @@ <h2>No Pattern Loaded</h2>
 
             // Draw panel numbers
             if (state.editor.showPanelNumbers && state.arena.config) {
-                const pixelsPerPanel = PANEL_SPECS[state.arena.config.arena.generation].pixels_per_panel;
-                const panelCols = state.arena.config.arena.num_cols;
-                const panelRows = state.arena.config.arena.num_rows;
+                const arena = state.arena.config.arena;
+                const pixelsPerPanel = PANEL_SPECS[arena.generation].pixels_per_panel;
+                // The pattern's own panel blocks (installed columns only on a partial arena)
+                const panelCols = Math.round(pixelCols / pixelsPerPanel);
+                const panelRows = Math.round(pixelRows / pixelsPerPanel);
 
                 // Calculate font size based on panel size in pixels
                 const panelPixelWidth = pixelsPerPanel * pixelSize;
@@ -6933,20 +6939,105 @@ <h2>No Pattern Loaded</h2>
                 ctx.textAlign = 'center';
                 ctx.textBaseline = 'middle';
 
-                // G6: match the arena's own panel map — ROW-major, 1-based
-                // (firmware panel_index = row * numCols + col; row 0 = bottom,
-                // so 1..numCols run along the BOTTOM row). Bench-verified
-                // 2026-07-05. Other generations keep column-major numbering.
-                const g6RowMajor = state.arena.config.arena.generation === 'G6';
+                // Physical panel numbers, matching the arena's own panel map and the 3D
+                // overlay (physicalPanelNumber: G6 row-major, partial arenas offset by
+                // columns_installed)
                 for (let pc = 0; pc < panelCols; pc++) {
                     for (let pr = 0; pr < panelRows; pr++) {
                         const centerX = (pc + 0.5) * pixelsPerPanel * pixelSize;
                         const centerY = (panelRows - pr - 0.5) * pixelsPerPanel * pixelSize;
-                        const n = g6RowMajor ? pr * panelCols + pc + 1 : pc * panelRows + pr + 1;
+                        const n = physicalPanelNumber(arena, pc, pr);
                         ctx.fillText(n.toString(), centerX, centerY);
                     }
                 }
             }
+
+            drawAzimuthAxis(canvas, pixelCols, pixelSize);
+        }
+
+        // ============================================
+        // 2D view: physical panel numbers + azimuth axis
+        // ============================================
+
+        /**
+         * Physical panel number (1-based) of pattern panel block `block` in panel row `row`
+         * (0 = bottom). A partial PAT stores only the installed columns, in columns_installed
+         * order, so block k sits on physical column columns_installed[k] (G6_2x8of10: block 0
+         * is column 1 = panels 2 / 12), the same map the 3D viewer uses. G6 numbers panels
+         * row-major (firmware panel_index = row * num_cols + col, row 0 = bottom,
+         * bench-verified 2026-07-05); older generations column-major.
+         */
+        function physicalPanelNumber(arena, block, row) {
+            const installed = arena.columns_installed
+                ? [...new Set(arena.columns_installed.map((p) => p % arena.num_cols))]
+                : null;
+            const col = installed ? installed[block] : block;
+            return arena.generation === 'G6'
+                ? row * arena.num_cols + col + 1
+                : col * arena.num_rows + row + 1;
+        }
+
+        /**
+         * Azimuth ticks for the 2D view in pattern coordinates (the generator's and the
+         * Mollweide view's): 0 deg = straight ahead at the middle of the pattern, negative to
+         * the fly's left. The step is the smallest of 15/30/45/60/90 deg that keeps ticks at
+         * least minSpacingPx pattern pixels apart. Returns [{deg, x}], x in pattern pixels
+         * from the left edge.
+         */
+        function azimuthTicks(pixelCols, degPerPx, minSpacingPx) {
+            const half = (pixelCols * degPerPx) / 2;
+            const step = [15, 30, 45, 60, 90].find((s) => s / degPerPx >= minSpacingPx) || 90;
+            const ticks = [];
+            for (let d = -Math.floor(half / step + 1e-9) * step; d <= half + 1e-9; d += step) {
+                ticks.push({ deg: d, x: d / degPerPx + pixelCols / 2 });
+            }
+            return ticks;
+        }
+
+        /** Degree ticks under the 2D grid (its own canvas, so edit-mode clicks are unaffected). */
+        function drawAzimuthAxis(gridCanvas, pixelCols, pixelSize) {
+            let axis = document.getElementById('gridAzimuthAxis');
+            if (!state.arena.config) {
+                if (axis) axis.remove();
+                return;
+            }
+            if (!axis) {
+                axis = document.createElement('canvas');
+                axis.id = 'gridAzimuthAxis';
+                axis.style.display = 'block';
+                axis.style.marginLeft = '1px'; // the grid canvas has a 1 px border
+                axis.title = "Azimuth from straight ahead (0°): negative = fly's left, positive = right. Same coordinates as the Mollweide view and the pattern generator.";
+                gridCanvas.after(axis);
+            }
+            axis.width = gridCanvas.width;
+            axis.height = AZIMUTH_AXIS_HEIGHT;
+            const actx = axis.getContext('2d');
+            const css = getComputedStyle(document.documentElement);
+            const dim = css.getPropertyValue('--text-dim').trim() || '#8b949e';
+            const accent = css.getPropertyValue('--accent').trim() || '#00e676';
+            actx.clearRect(0, 0, axis.width, axis.height);
+            actx.font = '10px "IBM Plex Mono", monospace';
+            actx.textAlign = 'center';
+            actx.textBaseline = 'top';
+            actx.lineWidth = 1;
+            let lastLabelRight = -Infinity;
+            for (const t of azimuthTicks(pixelCols, getDegreesPerPixel(), 60 / pixelSize)) {
+                const x = Math.round(t.x * pixelSize) + 0.5;
+                const color = t.deg === 0 ? accent : dim;
+                actx.strokeStyle = color;
+                actx.fillStyle = color;
+                actx.beginPath();
+                actx.moveTo(x, 0);
+                actx.lineTo(x, 5);
+                actx.stroke();
+                const label = (t.deg > 0 ? '+' : t.deg < 0 ? '−' : '') + Math.abs(t.deg) + '°';
+                const w = actx.measureText(label).width;
+                // edge labels are pulled inside the canvas; skip any that would overlap
+                const lx = Math.min(Math.max(x, w / 2 + 1), axis.width - w / 2 - 1);
+                if (lx - w / 2 < lastLabelRight + 4) continue;
+                actx.fillText(label, lx, 7);
+                lastLabelRight = lx + w / 2;
+            }
         }
 
         // ============================================
diff --git a/tests/test-pattern-2d-view.js b/tests/test-pattern-2d-view.js
new file mode 100644
index 00000000..3ae4da0a
--- /dev/null
+++ b/tests/test-pattern-2d-view.js
@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Pattern Designer 2D view on partial arenas: physical panel numbers and the azimuth axis.
+ *
+ * - Panel numbers must name the PHYSICAL panel, the same as the 3D overlay: a partial PAT
+ *   stores only the installed columns, so pattern block k sits on columns_installed[k]
+ *   (G6_2x8of10: block 0 = column 1 = panels 2 / 12, not 1 / 11).
+ * - The azimuth axis uses pattern coordinates (generator, Mollweide view): 0° at the middle of
+ *   the pattern = straight ahead, negative to the fly's left.
+ *
+ * physicalPanelNumber / azimuthTicks / getDegreesPerPixel are extracted from
+ * pattern_editor.html and run against the real arena configs and ArenaGeometry.
+ */
+const fs = require('fs');
+const path = require('path');
+const vm = require('vm');
+
+const ROOT = path.join(__dirname, '..');
+const { STANDARD_CONFIGS, PANEL_SPECS } = require('../js/arena-configs.js');
+global.PANEL_SPECS = PANEL_SPECS;
+const PatternGenerator = require('../js/pattern-editor/tools/generator.js');
+const AG = require('../js/arena-geometry.js');
+
+const html = fs.readFileSync(path.join(ROOT, 'pattern_editor.html'), 'utf8');
+const viewer = fs.readFileSync(
+    path.join(ROOT, 'js', 'pattern-editor', 'viewers', 'three-viewer.js'),
+    'utf8'
+);
+
+let checks = 0;
+let failures = 0;
+
+function check(name, condition, detail) {
+    checks++;
+    if (condition) {
+        console.log(`  PASS  ${name}`);
+        return;
+    }
+    failures++;
+    console.log(`  FAIL  ${name}${detail ? ` — ${detail}` : ''}`);
+}
+
+function extractFunction(name) {
+    const start = html.indexOf(`function ${name}(`);
+    if (start < 0) throw new Error(`pattern_editor.html: function ${name} not found`);
+    const open = html.indexOf('{', start);
+    let depth = 0;
+    for (let i = open; i < html.length; i++) {
+        if (html[i] === '{') depth++;
+        else if (html[i] === '}' && --depth === 0) return html.slice(start, i + 1);
+    }
+    throw new Error(`pattern_editor.html: unbalanced braces in ${name}`);
+}
+
+function editorFor(configName) {
+    const sandbox = {
+        PANEL_SPECS,
+        PatternGenerator,
+        Math,
+        state: { arena: { config: configName ? STANDARD_CONFIGS[configName] : null } }
+    };
+    vm.createContext(sandbox);
+    vm.runInContext(
+        ['physicalPanelNumber', 'azimuthTicks', 'getDegreesPerPixel']
+            .map(extractFunction)
+            .join('\n'),
+        sandbox
+    );
+    return sandbox;
+}
+
+/** The 3D overlay's numbering for a PHYSICAL column (three-viewer.js _createColumn labels). */
+function viewerPanelNumber(arena, physCol, row) {
+    return arena.generation === 'G6'
+        ? row * arena.num_cols + physCol + 1
+        : physCol * arena.num_rows + row + 1;
+}
+
+console.log('\n=== 2D panel numbers name the physical panel (same as the 3D overlay) ===');
+check(
+    '3D overlay numbering is still row-major for G6 / column-major otherwise',
+    /row \* numCols \+ colIndex \+ 1/.test(viewer) && /colIndex \* numRows \+ row \+ 1/.test(viewer)
+);
+{
+    const ed = editorFor(null);
+    const a = STANDARD_CONFIGS.G6_2x8of10.arena;
+    check(
+        'G6_2x8of10: first pattern panel, bottom row = panel 2',
+        ed.physicalPanelNumber(a, 0, 0) === 2
+    );
+    check(
+        'G6_2x8of10: first pattern panel, top row = panel 12',
+        ed.physicalPanelNumber(a, 0, 1) === 12
+    );
+    check(
+        'G6_2x8of10: last pattern panel, bottom row = panel 9',
+        ed.physicalPanelNumber(a, 7, 0) === 9
+    );
+    const full = STANDARD_CONFIGS.G6_2x10.arena;
+    check(
+        'G6_2x10: first panel bottom/top = 1 / 11',
+        ed.physicalPanelNumber(full, 0, 0) === 1 && ed.physicalPanelNumber(full, 0, 1) === 11
+    );
+    const g4 = STANDARD_CONFIGS.G4_3x12of18.arena;
+    check(
+        'G4_3x12of18 (column-major): first column = panels 1, 2, 3',
+        [0, 1, 2].every((r) => ed.physicalPanelNumber(g4, 0, r) === r + 1)
+    );
+}
+for (const [name, cfg] of Object.entries(STANDARD_CONFIGS)) {
+    const a = cfg.arena;
+    const ed = editorFor(name);
+    const installed = a.columns_installed || [...Array(a.num_cols).keys()];
+    const bad = [];
+    installed.forEach((physCol, block) => {
+        for (let row = 0; row < a.num_rows; row++) {
+            const got = ed.physicalPanelNumber(a, block, row);
+            const want = viewerPanelNumber(a, physCol, row);
+            if (got !== want) bad.push(`block ${block} row ${row}: ${got} != ${want}`);
+        }
+    });
+    check(
+        `${name}: every 2D panel number equals the 3D overlay's`,
+        bad.length === 0,
+        bad.slice(0, 3).join('; ')
+    );
+}
+
+console.log('\n=== azimuth axis: 0° at the middle, same coordinates as the Mollweide view ===');
+const SPANS = { G4_3x12of18: 120, G6_3x12of18: 120, G6_2x8of10: 144, G6_2x10: 180, G4_4x12: 180 };
+for (const [name, cfg] of Object.entries(STANDARD_CONFIGS)) {
+    const a = cfg.arena;
+    const ed = editorFor(name);
+    const ppp = PANEL_SPECS[a.generation].pixels_per_panel;
+    const installed = a.columns_installed || [...Array(a.num_cols).keys()];
+    const W = installed.length * ppp;
+    const dpp = ed.getDegreesPerPixel();
+    const ticks = ed.azimuthTicks(W, dpp, 10);
+    const zero = ticks.find((t) => t.deg === 0);
+    check(`${name}: 0° tick at the middle of the pattern`, zero && Math.abs(zero.x - W / 2) < 1e-9);
+    check(
+        `${name}: ticks stay inside the pattern`,
+        ticks.every((t) => t.x >= -1e-9 && t.x <= W + 1e-9)
+    );
+    if (SPANS[name] !== undefined) {
+        check(
+            `${name}: pattern spans ±${SPANS[name]}°`,
+            Math.abs((W * dpp) / 2 - SPANS[name]) < 1e-9
+        );
+    }
+    // Mollweide/projection longitude of pixel-column centres (projection-viewer.js)
+    const co = AG.arenaCoordinates({
+        panelSize: ppp,
+        numCols: installed.length,
+        numRows: a.num_rows,
+        numCircle: a.num_cols,
+        model: 'smooth'
+    });
+    const phi = AG.cart2sphere(co.x, co.y, co.z).phi[Math.floor(co.rows / 2)];
+    const bad = [];
+    for (const c of [0, Math.floor(W / 3), W - 1]) {
+        const tickAz = (c + 0.5 - W / 2) * dpp; // the axis's azimuth at this column centre
+        const lon = (phi[c] * 180) / Math.PI;
+        if (Math.abs(tickAz - lon) > 0.01)
+            bad.push(`col ${c}: axis ${tickAz.toFixed(2)} vs Mollweide ${lon.toFixed(2)}`);
+    }
+    check(`${name}: axis azimuth = Mollweide longitude`, bad.length === 0, bad.join('; '));
+}
+{
+    const ed = editorFor('G4_3x12of18');
+    const deg = ed.azimuthTicks(192, 1.25, 20).map((t) => t.deg);
+    check(
+        'G4_3x12of18 ticks (≥20 px apart): −120 … +120 every 30°',
+        JSON.stringify(deg) === JSON.stringify([-120, -90, -60, -30, 0, 30, 60, 90, 120]),
+        JSON.stringify(deg)
+    );
+}
+
+console.log('\n=== wiring ===');
+check(
+    'the 2D overlay labels panels through physicalPanelNumber',
+    /physicalPanelNumber\(arena, pc, pr\)/.test(extractFunction('renderGridViewer'))
+);
+check(
+    'the 2D view draws the azimuth axis',
+    /drawAzimuthAxis\(canvas, pixelCols, pixelSize\)/.test(extractFunction('renderGridViewer'))
+);
+check(
+    'the axis is its own canvas (edit-mode hit-testing reads gridCanvas only)',
+    /axis\.id = 'gridAzimuthAxis'/.test(extractFunction('drawAzimuthAxis'))
+);
+
+console.log(`\n${checks - failures}/${checks} checks passed`);
+if (failures > 0) {
+    console.log(`${failures} FAILED`);
+    process.exit(1);
+}

From 3d5da0e0ebff4fbd7b95b6a332cfcf46e6a08ee5 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Tue, 6 Oct 2026 16:31:27 -0400
Subject: [PATCH 06/17] feat(pattern-designer): short, SD-safe filenames with a
 compact ON/OFF color code

Color variants of one grating used to share a name (the filename carried only the layout
tag), and re-saves stacked tags (_4c_rir). Names now:
- record the ON/OFF choice used to GENERATE the frames, stamped at generate time:
  PanelColor.filenameColorCode -> '_4c-B' (ON blue), '_4c-B-G' (ON blue, OFF green),
  '_4c-VB', '_4c-F80A' (custom levels, one hex digit per channel); nothing extra for the
  default (ON all / OFF dark), so default names are unchanged apart from the words below;
- normalize the layout tag on save (PanelColor.stripColorTag): replaced, never stacked;
- use short words: grat/star/edge/sine/offon/anim, rot/exp/trans, Ndot, _img, comb,
  hcw/hccw/vup/vdown.

The controller keeps pattern names in a 64-byte buffer: <= 63 characters, plain ASCII,
and <= 58 so a same-name re-upload (stored as X001_<name>) keeps its .pat. Nothing in the
Designer checked this. js/pattern-set.js gains the shared rule (checkSdFilename,
sanitizeSdFilename, fitSdFilename; both tools load it), and the Designer fits every saved
and renamed name (fitPatternFilename: cleans characters, shortens only the descriptive
middle, keeps the arena prefix and the color tag; the rename prompt says what it changed).
The longest name Generate can produce is now 54 characters with the worst-case tag.

Helpers are typeof-guarded, so a stale cached panel-color.js / pattern-set.js only means
the old naming until a refresh.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../pattern-designer-color-panels.md          |  9 +-
 js/panel-color.js                             | 77 ++++++++++++++++
 js/pattern-set.js                             | 72 +++++++++++++++
 pattern_editor.html                           | 81 +++++++++++++----
 tests/test-panel-color.js                     | 87 +++++++++++++++++++
 5 files changed, 308 insertions(+), 18 deletions(-)

diff --git a/docs/development/pattern-designer-color-panels.md b/docs/development/pattern-designer-color-panels.md
index 69b9e102..a0c79f89 100644
--- a/docs/development/pattern-designer-color-panels.md
+++ b/docs/development/pattern-designer-color-panels.md
@@ -34,8 +34,13 @@ not know or care. Consequences that everything in the Designer relies on:
 - **A pure single color lights only 100 of the 400 LEDs per panel** (a 10×10 lattice at 2-px
   pitch). The renderers show exactly that; a 1-px bar in a pure color blinks as it moves, as it
   would on the hardware.
-- **The `.pat` carries no color tag** (header is full). The Designer appends `_4c` / `_rir` to
-  generated filenames; the proper tag (MANIFEST + repo metadata) is LAB-229.
+- **The `.pat` carries no color tag** (header is full). The Designer names it instead: the
+  layout tag (`_4c`, `_rir`, `_rir1`) plus, when the generation used a non-default ON/OFF choice,
+  a compact code from `PanelColor.filenameColorCode` — one letter per channel (V B G Y R I),
+  `A` = all, one hex digit per channel for custom levels: `_4c-B` (ON blue), `_4c-B-G` (ON blue,
+  OFF green), `_4c-F80A` (custom). The code is stamped at GENERATE time (the choice applies to
+  those frames); save only normalizes the layout tag (`stripColorTag`: replaced, never stacked).
+  The proper tag (MANIFEST + repo metadata) is still LAB-229.
 
 ## The one bench-decided constant: `ROW_PARITY_FLIP`
 
diff --git a/js/panel-color.js b/js/panel-color.js
index d8820447..bbc424bb 100644
--- a/js/panel-color.js
+++ b/js/panel-color.js
@@ -332,6 +332,80 @@
         return l ? l.tag : '';
     }
 
+    // One letter per channel for filename codes (V B G Y R I — unique by construction).
+    function channelLetter(id) {
+        return String(id).charAt(0).toUpperCase();
+    }
+
+    // Compact code for one ON/OFF color choice ({preset, levels}) on a layout:
+    //   'all' → 'A'; one channel → its letter; 'dark' → '' (OFF only);
+    //   'custom' → the letters of the channels at full level when every level is 0 or 15
+    //   ('A' if all are full, '0' if none), else one hex digit per channel in layout order.
+    function choiceCode(layout, choice) {
+        var preset = choice && choice.preset;
+        if (!preset || preset === 'dark') return '';
+        if (preset === 'all') return 'A';
+        if (preset !== 'custom') return CHANNELS[preset] ? channelLetter(preset) : '';
+        var levels = layout.channels.map(function (ch) {
+            var v = choice.levels && choice.levels[ch.id];
+            v = v === undefined ? 15 : Math.round(Number(v)); // the custom editor's default
+            return Math.max(0, Math.min(15, Number.isFinite(v) ? v : 0));
+        });
+        var binary = levels.every(function (v) {
+            return v === 0 || v === 15;
+        });
+        if (!binary) {
+            return levels
+                .map(function (v) {
+                    return v.toString(16).toUpperCase();
+                })
+                .join('');
+        }
+        var on = layout.channels.filter(function (ch, i) {
+            return levels[i] === 15;
+        });
+        if (on.length === layout.channels.length) return 'A';
+        if (on.length === 0) return '0';
+        return on
+            .map(function (ch) {
+                return channelLetter(ch.id);
+            })
+            .join('');
+    }
+
+    // Filename code for the ON/OFF choice used to GENERATE a pattern, appended after the
+    // layout tag: '' for mono layouts and for the default (ON all, OFF dark), else
+    // '-<ON>' or '-<ON>-<OFF>'. Four-color: ON blue → '-B'; ON blue, OFF green → '-B-G';
+    // custom V15 B8 G0 Y10 → '-F80A'. At most 13 characters with the tag ('_4c-F80A-0404').
+    function filenameColorCode(key, onChoice, offChoice) {
+        var l = getLayout(key);
+        if (!l || l.mono) return '';
+        var on = choiceCode(l, onChoice) || 'A';
+        var off = choiceCode(l, offChoice);
+        if (on === 'A' && !off) return '';
+        return '-' + on + (off ? '-' + off : '');
+    }
+
+    // Remove every trailing layout tag (+ its color code) from a base name (no '.pat'), so a
+    // re-save or a layout change replaces the tag instead of stacking '_4c_rir'.
+    var TAG_RE = new RegExp(
+        '(?:' +
+            LAYOUT_DEFS.map(function (d) {
+                return d[2];
+            })
+                .filter(Boolean)
+                .sort(function (a, b) {
+                    return b.length - a.length;
+                })
+                .join('|') +
+            ')(?:-[0-9A-Z]+){0,2}$'
+    );
+    function stripColorTag(base) {
+        var s = String(base == null ? '' : base);
+        while (TAG_RE.test(s)) s = s.replace(TAG_RE, '');
+        return s;
+    }
+
     var PanelColor = {
         ROW_PARITY_FLIP: ROW_PARITY_FLIP,
         DEFAULT_LAYOUT: DEFAULT_LAYOUT,
@@ -345,6 +419,9 @@
         describeLayout: describeLayout,
         legendText: legendText,
         filenameTag: filenameTag,
+        filenameColorCode: filenameColorCode,
+        stripColorTag: stripColorTag,
+        channelLetter: channelLetter,
         bankAt: bankAt,
         cellOrigin: cellOrigin,
         channelAt: channelAt,
diff --git a/js/pattern-set.js b/js/pattern-set.js
index 06b7a79b..cb66e8c4 100644
--- a/js/pattern-set.js
+++ b/js/pattern-set.js
@@ -424,6 +424,73 @@
         return out;
     }
 
+    // ---- SD-card filenames (controller limits) -------------------------------------
+    // The controller keeps pattern names in a 64-byte buffer (incl. NUL): at most 63 chars,
+    // and SET_PATTERN_FILENAME 0x83 refuses longer. A same-name re-upload is stored as
+    // X001_<name> (5 more chars, truncated to 63) — past 58 that cuts off '.pat' and the file
+    // drops out of the listing. Names travel as one byte per char, so only plain ASCII
+    // filename characters are safe. Firmware: SdManager.cpp renamePattern / scan.
+    var SD_NAME_MAX = 63;
+    var SD_NAME_SAFE = 58;
+    var SD_NAME_CHARS = /^[A-Za-z0-9._-]+$/;
+
+    /**
+     * Check a pattern filename (with .pat) against the controller's SD rules.
+     * @returns {{ok:boolean, level:'ok'|'warn'|'error', problems:string[]}}
+     *   error = the controller cannot store it; warn = fine once, breaks on a re-upload.
+     */
+    function checkSdFilename(name) {
+        var n = String(name == null ? '' : name);
+        var errors = [];
+        var warnings = [];
+        if (!/\.pat$/i.test(n)) errors.push('must end in .pat');
+        if (!SD_NAME_CHARS.test(n)) errors.push('use only letters, digits, "_", "-" and "."');
+        if (n.charAt(0) === '.') errors.push('must not start with "."');
+        if (n.length > SD_NAME_MAX) {
+            errors.push(n.length + ' characters; the controller allows ' + SD_NAME_MAX);
+        } else if (n.length > SD_NAME_SAFE) {
+            warnings.push(
+                n.length +
+                    ' characters; keep it to ' +
+                    SD_NAME_SAFE +
+                    ' so a re-upload (stored as X001_…) keeps its .pat'
+            );
+        }
+        var problems = errors.concat(warnings);
+        return {
+            ok: problems.length === 0,
+            level: errors.length ? 'error' : warnings.length ? 'warn' : 'ok',
+            problems: problems
+        };
+    }
+
+    /** Replace characters the SD path can't carry with '_' (keeps the .pat extension). */
+    function sanitizeSdFilename(name) {
+        var base = String(name == null ? '' : name).replace(/\.pat$/i, '');
+        base = base
+            .replace(/[^A-Za-z0-9._-]+/g, '_')
+            .replace(/_+/g, '_')
+            .replace(/^[._]+|_+$/g, '');
+        return (base || 'pattern') + '.pat';
+    }
+
+    /**
+     * Build a safe SD filename from prefix + middle + suffix (+ '.pat'), shortening only the
+     * descriptive middle so the arena prefix and the color tag always survive. Characters
+     * are sanitized first. Result length <= SD_NAME_SAFE whenever prefix + suffix allow it.
+     */
+    function fitSdFilename(prefix, middle, suffix) {
+        var clean = function (x) {
+            return String(x == null ? '' : x).replace(/[^A-Za-z0-9._-]+/g, '_');
+        };
+        var p = clean(prefix);
+        var m = clean(middle).replace(/_+/g, '_');
+        var sfx = clean(suffix);
+        var room = SD_NAME_SAFE - '.pat'.length - p.length - sfx.length;
+        if (m.length > room) m = m.slice(0, Math.max(0, room)).replace(/[._-]+$/, '');
+        return sanitizeSdFilename(p + m + sfx);
+    }
+
     var PatternSet = {
         TOOL: TOOL,
         MANIFEST_VERSION: MANIFEST_VERSION,
@@ -438,6 +505,11 @@
         assignIndices: assignIndices,
         // helpers
         sanitizeName: sanitizeName,
+        SD_NAME_MAX: SD_NAME_MAX,
+        SD_NAME_SAFE: SD_NAME_SAFE,
+        checkSdFilename: checkSdFilename,
+        sanitizeSdFilename: sanitizeSdFilename,
+        fitSdFilename: fitSdFilename,
         summarizePattern: summarizePattern,
         validateGeometry: validateGeometry,
         reencodeForDuty: reencodeForDuty,
diff --git a/pattern_editor.html b/pattern_editor.html
index 88b29f9b..94330d65 100644
--- a/pattern_editor.html
+++ b/pattern_editor.html
@@ -2877,6 +2877,12 @@ <h3 class="modal-title">Save to Repo</h3>
                         }
                     }
 
+                    const fitted = fitPatternFilename(finalName);
+                    if (fitted.problems.length) {
+                        alert('Adjusted for the arena SD card (' + fitted.problems.join('; ') + '):\n\n' + fitted.name);
+                        finalName = fitted.name;
+                    }
+
                     state.filename = finalName;
                     state.isDirty = true;
                     updateStatus();
@@ -3543,7 +3549,11 @@ <h3 class="modal-title">Save to Repo</h3>
                 arena_id: configName ? getArenaId(gen, configName) : 0,
                 observer_id: 0
             };
-            const filename = withColorTag(addArenaPrefix(state.filename || 'pattern.pat'));
+            const fitted = fitPatternFilename(withColorTag(addArenaPrefix(state.filename || 'pattern.pat')));
+            if (fitted.problems.length) {
+                console.info('Pattern filename adjusted for the arena SD card (' + fitted.problems.join('; ') + '): ' + fitted.name);
+            }
+            const filename = fitted.name;
             return { patternData, filename };
         }
 
@@ -4297,7 +4307,7 @@ <h3 class="modal-title">Save to Repo</h3>
 
                         // Generate filename
                         const freqStr = spatialFreqUnit === 'px' ? `${spatialFreqValue}px` : `${spatialFreqValue}deg`;
-                        filename = `grating_${motionType}_${freqStr}_${params.dutyCycle}pct.pat`;
+                        filename = `grat_${motionAbbrev(motionType)}_${freqStr}_${params.dutyCycle}pct.pat`;
                         break;
                     }
 
@@ -4328,7 +4338,7 @@ <h3 class="modal-title">Save to Repo</h3>
 
                         // Generate filename
                         const freqStr = spatialFreqUnit === 'px' ? `${spatialFreqValue}px` : `${spatialFreqValue}deg`;
-                        filename = `sine_${motionType}_${freqStr}.pat`;
+                        filename = `sine_${motionAbbrev(motionType)}_${freqStr}.pat`;
                         break;
                     }
 
@@ -4360,7 +4370,7 @@ <h3 class="modal-title">Save to Repo</h3>
                         params.poleCoord = [poleAzimuthStar * Math.PI / 180, poleElevationStar * Math.PI / 180];
 
                         pattern = PatternGenerator.generateStarfield(params, arena);
-                        filename = `starfield_${motionTypeStar}_${params.dotCount}dots_${params.numFrames}f.pat`;
+                        filename = `star_${motionAbbrev(motionTypeStar)}_${params.dotCount}dot_${params.numFrames}f.pat`;
                         break;
                     }
 
@@ -4393,13 +4403,13 @@ <h3 class="modal-title">Save to Repo</h3>
 
                         pattern = PatternGenerator.generateEdge(params, arena);
                         const freqStrEdge = spatialFreqUnitEdge === 'px' ? `${spatialFreqValueEdge}px` : `${spatialFreqValueEdge}deg`;
-                        filename = `edge_${motionTypeEdge}_${freqStrEdge}_${params.numFrames}f.pat`;
+                        filename = `edge_${motionAbbrev(motionTypeEdge)}_${freqStrEdge}_${params.numFrames}f.pat`;
                         break;
                     }
 
                     case 'off-on':
                         pattern = PatternGenerator.generateOffOn(params, arena);
-                        filename = `off_on_${highLevel}.pat`;
+                        filename = `offon_${highLevel}.pat`;
                         break;
 
                     default:
@@ -4429,7 +4439,12 @@ <h3 class="modal-title">Save to Repo</h3>
                     for (const f of pattern.frames) {
                         PanelColor.applyOnOffColor(f, pattern.pixelRows, pattern.pixelCols, pattern.gs_val, state.panel.layoutKey, onW, offW, hi, lo);
                     }
-                    filename = withColorTag(filename);
+                    // Name the ON/OFF choice used for THIS generation (_4c-B-G …); later chip
+                    // changes don't apply to these frames, so the code is stamped here, not at save.
+                    const colorCode = PanelColor.filenameColorCode
+                        ? PanelColor.filenameColorCode(state.panel.layoutKey, state.onColor, state.offColor)
+                        : '';
+                    filename = withColorTag(filename, colorCode);
                 }
 
                 // Convert to state.pattern format
@@ -5485,14 +5500,48 @@ <h3 class="modal-title">Save to Repo</h3>
             renderOnColorCustom();
         }
 
-        // Filename tag for color layouts (`_4c`, `_rir`), inserted before `.pat`. Applied at SAVE
-        // time in buildPatternDataForSave so every path — generate, combine, tray reload, image
-        // import — carries it; idempotent, and a no-op for the green layout.
-        function withColorTag(filename) {
+        // Filename tag for color layouts (`_4c`, `_rir`) + the generation's ON/OFF color code
+        // (`_4c-B-G`, PanelColor.filenameColorCode), inserted before `.pat`. Generation passes
+        // the code; SAVE (buildPatternDataForSave) passes none, so every path — combine, tray
+        // reload, image import — carries the layout tag and keeps a code already there. Any
+        // other layout's tag is replaced, never stacked (`_4c_rir`). No-op for green.
+        function withColorTag(filename, code) {
             const tag = PanelColor.filenameTag(state.panel.layoutKey);
             if (!tag || !filename) return filename;
             const base = filename.replace(/\.pat$/i, '');
-            return base.endsWith(tag) ? base + '.pat' : base + tag + '.pat';
+            const own = base.match(new RegExp(tag.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '((?:-[0-9A-Z]+){0,2})$'));
+            const keep = code !== undefined ? code : own ? own[1] : '';
+            const stripped = PanelColor.stripColorTag
+                ? PanelColor.stripColorTag(base)
+                : own ? base.slice(0, base.length - own[0].length) : base;
+            return stripped + tag + keep + '.pat';
+        }
+
+        // Motion types in generated filenames (names stay short: the controller keeps 63
+        // characters and 58 survive a re-upload — PatternSet.checkSdFilename).
+        const MOTION_ABBREV = { rotation: 'rot', expansion: 'exp', translation: 'trans' };
+        function motionAbbrev(motion) {
+            return MOTION_ABBREV[motion] || motion;
+        }
+
+        /**
+         * Make a filename safe for the arena's SD card: plain ASCII, <= 58 characters. Only the
+         * descriptive middle is shortened; the arena prefix and the color tag are kept.
+         * Returns {name, problems} (problems = what the original name broke, for the UI).
+         */
+        function fitPatternFilename(filename) {
+            if (!window.PatternSet || !PatternSet.checkSdFilename || !PatternSet.fitSdFilename) {
+                return { name: filename, problems: [] };
+            }
+            const chk = PatternSet.checkSdFilename(filename);
+            if (chk.ok) return { name: filename, problems: [] };
+            let base = filename.replace(/\.pat$/i, '');
+            const arena = findArenaPrefix(base);
+            const prefix = arena ? base.slice(0, arena.length + 1) : '';
+            base = base.slice(prefix.length);
+            const core = PanelColor.stripColorTag ? PanelColor.stripColorTag(base) : base;
+            const suffix = base.slice(core.length);
+            return { name: PatternSet.fitSdFilename(prefix, core, suffix), problems: chk.problems };
         }
 
         function updatePanelLayoutHint() {
@@ -5967,7 +6016,7 @@ <h3 class="modal-title">Save to Repo</h3>
                     case 'mask': modeSuffix = 'mask'; break;
                     case 'split-h': modeSuffix = `splitH${options.splitPosition || 50}`; break;
                     case 'split-v': modeSuffix = `splitV${options.splitPosition || 50}`; break;
-                    default: modeSuffix = 'combined';
+                    default: modeSuffix = 'comb';
                 }
                 state.filename = `${nameA}_${nameB}_${modeSuffix}.pat`;
 
@@ -6021,7 +6070,7 @@ <h3 class="modal-title">Save to Repo</h3>
                 // Generate suggested filename
                 const imageInfo = ImageConverter.getImageInfo();
                 const baseName = imageInfo?.name?.replace(/\.[^.]+$/, '') || 'image';
-                state.filename = `${baseName}_frame.pat`;
+                state.filename = `${baseName}_img.pat`;
 
                 // Lock arena config after generating pattern
                 lockArenaConfig();
@@ -6324,7 +6373,7 @@ <h3 class="modal-title">Save to Repo</h3>
             };
 
             // Generate filename based on motion type
-            const dirLabel = direction.replace('-', '_');
+            const dirLabel = direction.replace('-', ''); // hcw · hccw · vup · vdown
             state.filename = `${baseEntry.name}_${dirLabel}_${totalFrames}f.pat`;
             state.isDirty = true;
             state.editor.currentFrame = 0;
@@ -6643,7 +6692,7 @@ <h3 class="modal-title">Save to Repo</h3>
                 stretchValues: new Array(frames.length).fill(getStretchByte(generation))
             };
 
-            state.filename = `animation_${frames.length}f.pat`;
+            state.filename = `anim_${frames.length}f.pat`;
             state.isDirty = true;
             state.editor.currentFrame = 0;
 
diff --git a/tests/test-panel-color.js b/tests/test-panel-color.js
index 19184366..2843d34e 100644
--- a/tests/test-panel-color.js
+++ b/tests/test-panel-color.js
@@ -450,5 +450,92 @@ check(
     /panelLayout/.test(icon) && /globalThis\.PanelColor/.test(icon)
 );
 
+console.log('\n=== filename color code (ON/OFF choice) + tag normalization ===');
+{
+    const code = (key, on, off) => PC.filenameColorCode(key, on, off);
+    const ALL = { preset: 'all' };
+    const DARK = { preset: 'dark' };
+    check('mono layout → no code', code('g6-green', { preset: 'blue' }, ALL) === '');
+    check(
+        'default ON all / OFF dark → no code (names unchanged)',
+        code('four-color', ALL, DARK) === ''
+    );
+    check('ON blue → -B', code('four-color', { preset: 'blue' }, DARK) === '-B');
+    check(
+        'ON blue, OFF green → -B-G',
+        code('four-color', { preset: 'blue' }, { preset: 'green' }) === '-B-G'
+    );
+    check('ON all, OFF yellow → -A-Y', code('four-color', ALL, { preset: 'yellow' }) === '-A-Y');
+    check(
+        'custom full/zero levels → channel letters (-VB)',
+        code(
+            'four-color',
+            { preset: 'custom', levels: { violet: 15, blue: 15, green: 0, yellow: 0 } },
+            DARK
+        ) === '-VB'
+    );
+    check(
+        'custom with intermediate levels → one hex digit per channel (-F80A)',
+        code(
+            'four-color',
+            { preset: 'custom', levels: { violet: 15, blue: 8, green: 0, yellow: 10 } },
+            DARK
+        ) === '-F80A'
+    );
+    check(
+        'custom all full → A; untouched levels default to 15',
+        code('four-color', { preset: 'custom', levels: {} }, DARK) === ''
+    );
+    check(
+        'custom all zero → 0',
+        code(
+            'four-color',
+            { preset: 'custom', levels: { violet: 0, blue: 0, green: 0, yellow: 0 } },
+            DARK
+        ) === '-0'
+    );
+    check(
+        'red-IR: ON IR, OFF red → -I-R',
+        code('red-ir-v0.4r2', { preset: 'ir' }, { preset: 'red' }) === '-I-R'
+    );
+    const worst =
+        PC.filenameTag('four-color') +
+        code(
+            'four-color',
+            { preset: 'custom', levels: { violet: 15, blue: 8, green: 0, yellow: 10 } },
+            { preset: 'custom', levels: { violet: 0, blue: 4, green: 0, yellow: 4 } }
+        );
+    check(
+        'worst-case tag + code is 13 characters',
+        worst === '_4c-F80A-0404' && worst.length === 13,
+        worst
+    );
+    for (const key of PC.layoutKeys()) {
+        const letters = PC.getLayout(key).channels.map((c) => PC.channelLetter(c.id));
+        check(
+            `${key}: channel letters are unique (${letters.join('')})`,
+            new Set(letters).size === letters.length
+        );
+    }
+    const strip = PC.stripColorTag;
+    check(
+        'strip: stacked tags (_4c_rir) all removed',
+        strip('G6_2x10_grat_rot_20px_50pct_4c_rir') === 'G6_2x10_grat_rot_20px_50pct'
+    );
+    check(
+        'strip: tag + two-part code',
+        strip('x_4c-B-G') === 'x' && strip('x_4c-F80A-0404') === 'x'
+    );
+    check('strip: _rir1 is not left as "1"', strip('x_rir1-R') === 'x');
+    check(
+        'strip: a word that merely starts like a tag stays (grat_4cats)',
+        strip('grat_4cats') === 'grat_4cats'
+    );
+    check(
+        'strip: untagged name unchanged',
+        strip('G6_2x10_grat_rot_20px_50pct') === 'G6_2x10_grat_rot_20px_50pct'
+    );
+}
+
 console.log(`\n${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

From 4c1705523d8d1cd7b99c07a9353110e11545460e Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Tue, 6 Oct 2026 16:31:28 -0400
Subject: [PATCH 07/17] fix(studio): check pattern names before uploading, flag
 X001_ re-uploads, 0x85 label

- sdUploadOne runs PatternSet.checkSdFilename BEFORE sending the bytes: a name the
  controller can't store (non-ASCII, > 63 chars, no .pat) fails at once instead of after
  the whole upload (which left the data on the card as pattern.temp), and is not retried.
  59-63 characters log a warning (a re-upload would lose .pat).
- An upload never overwrites: the firmware stores a same-name re-upload as X001_<name>.
  sdLogicalName now strips that prefix, so the copy shows as a DUPLICATE of the original
  (onSdListing warns; protocols refuse to guess) instead of a separate pattern while the
  picker kept playing the old file. The upload also warns up front when the name is
  already on the card.
- The upload opcode is SET_PATTERN_FILE 0x85; the Studio's error text ("write rejected"),
  tooltips and comments said 0x8D, which the firmware doesn't have (also fixed in the
  Console comment and CLAUDE.md's quiesce list).

CLAUDE.md records the filename rule. tests/test-sd-filenames.js covers the shared rule,
the Designer's names (every arena prefix + worst-case tag <= 58), withColorTag /
fitPatternFilename, sdLogicalName and the upload order.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CLAUDE.md                  |   9 +-
 arena_console.html         |   2 +-
 arena_studio.html          |  37 ++++--
 tests/test-sd-filenames.js | 251 +++++++++++++++++++++++++++++++++++++
 4 files changed, 287 insertions(+), 12 deletions(-)
 create mode 100644 tests/test-sd-filenames.js

diff --git a/CLAUDE.md b/CLAUDE.md
index b3e9e309..0b7f02ba 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -252,7 +252,7 @@ fix flows to every page automatically; two hand-written HTML pages never will.
   rig, source), the top-bar chips, and the Run-view sequence. `dirty` means
   "text ≠ last load/save" (`savedText` baseline), NOT a snapshot-captured flag.
 - **Display quiesce:** firmware refuses SD-write + ISP commands
-  (0x8D/0xE0/0x8A/0xC8/0xC9) unless the display is stopped (`CE_DISPLAY_ACTIVE`,
+  (0x85/0xE0/0x8A/0xC8/0xC9) unless the display is stopped (`CE_DISPLAY_ACTIVE`,
   status 10). Any new handler for a guarded op must `await quiesceDisplay()`
   first. STOP also blanks panels (they latch frames) — a persistent on-arena
   display during ISP is impossible on current firmware; progress maps blink.
@@ -643,6 +643,13 @@ localStorage) — no auth UI of its own. Repo layout: free-standing patterns in
   exists-check overwrite confirm.
 - Classic deps added for this: `js/pattern-set.js`, `js/studio-url-state.js` (both
   dual-export; same files the Studio loads).
+- **Pattern filenames must fit the controller's SD rules** (`PatternSet.checkSdFilename`, js/pattern-set.js):
+  plain ASCII `[A-Za-z0-9._-]`, ends `.pat`, ≤ 63 characters (firmware 64-byte buffer), and keep
+  ≤ 58 — a same-name re-upload is stored as `X001_<name>` and past 58 that cuts off `.pat`. The
+  Designer keeps generated names short (`grat`/`star`/`edge`/`sine`/`offon`/`anim`, `rot`/`exp`/
+  `trans`) and fits every saved/renamed name (`fitPatternFilename`: shortens the middle, keeps the
+  arena prefix + color tag); the Studio refuses a bad name BEFORE sending bytes (`sdUploadOne`)
+  and `sdLogicalName` strips `X001_`, so a re-upload shows as a duplicate. Upload opcode = 0x85.
 - **Partial arenas (LAB-295) — three rules every view and helper follows.** (1) Angular pitch is
   the FULL circle: `PatternGenerator.getDegreesPerPixel(arena)` = 360 / (num_cols × px/panel)
   (G4_3x12of18 = 1.25°/px), never the installed width; the generators read the same
diff --git a/arena_console.html b/arena_console.html
index c38720c1..033490f2 100644
--- a/arena_console.html
+++ b/arena_console.html
@@ -2867,7 +2867,7 @@
             let ispReportText = ''; // last run's plain-text report (Copy report)
             const ispSleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
-            // The firmware refuses ISP + SD-write commands (0xC8/0xC9/0xE0/0x8D/0x8A)
+            // The firmware refuses ISP + SD-write commands (0xC8/0xC9/0xE0/0x85/0x8A)
             // unless the display is stopped (state ALL_OFF → CE_DISPLAY_ACTIVE with
             // "Stop display before flashing a panel" otherwise). STOP_DISPLAY also
             // BLANKS the panels — they hold their last frame, so the firmware pushes
diff --git a/arena_studio.html b/arena_studio.html
index 0cd898fb..9e12badc 100644
--- a/arena_studio.html
+++ b/arena_studio.html
@@ -3075,7 +3075,7 @@ <h2 id="modalTitle">Import error</h2>
       <div class="stage" id="cStage">
 
         <section class="panel open" data-panel="patterns">
-          <div class="panel-h"><span class="panel-title" title="GET_FILE_COUNT 0x80 · names 0x82 · read 0x84 · delete 0x86 · write 0x8D · rename 0x83 · ZIP 0x8A · purge 0x8F">Patterns</span><span class="spacer"></span><span class="panel-x" data-close="patterns" role="button" title="Collapse to the rail">✕</span></div>
+          <div class="panel-h"><span class="panel-title" title="GET_FILE_COUNT 0x80 · names 0x82 · read 0x84 · delete 0x86 · write 0x85 · rename 0x83 · ZIP 0x8A · purge 0x8F">Patterns</span><span class="spacer"></span><span class="panel-x" data-close="patterns" role="button" title="Collapse to the rail">✕</span></div>
           <div class="panel-b">
             <div class="pat2col">
               <div class="pat-left">
@@ -3090,7 +3090,7 @@ <h2 id="modalTitle">Import error</h2>
               <button class="pill" data-cmd="csdlist" title="GET_FILE_COUNT 0x80 + names">Refresh</button>
               <button class="pill" data-cmd="cpatinfo" title="Re-query pattern info (GET_PATTERN_INFO 0x88) for the selected pattern">↻ info</button>
               <div class="cmenu" data-cmenu id="sdUploadMenu">
-                <button class="cmenu-btn" title="Upload pattern(s) to the SD card — a single .pat or a whole pattern set, from a local file/folder, this site's library, or the course repo (SET_PATTERN_FILE 0x8D + rename 0x83)">Add ▾</button>
+                <button class="cmenu-btn" title="Upload pattern(s) to the SD card — a single .pat or a whole pattern set, from a local file/folder, this site's library, or the course repo (SET_PATTERN_FILE 0x85 + rename 0x83)">Add ▾</button>
                 <div class="cmenu-pop">
                   <div class="cmenu-sep">Single pattern (.pat)</div>
                   <button class="cmenu-item" data-cmd="csdup_local_file" title="Pick one .pat file from this computer and upload it">From local file…</button>
@@ -4376,7 +4376,7 @@ <h2 id="modalTitle">Import error</h2>
     const SAFE_BLOCKED_CMDS = new Set([
         // add / delete patterns (SD + on-arena writes)
         'csdpurge', 'csdarchive', 'cloadfile', 'crawsend', 'cispcopy',
-        // upload patterns to the SD card (all six Add ▾ sources → SET_PATTERN_FILE 0x8D)
+        // upload patterns to the SD card (all six Add ▾ sources → SET_PATTERN_FILE 0x85)
         'csdup_local_file', 'csdup_local_folder', 'csdup_lib_file',
         'csdup_lib_folder', 'csdup_repo_file', 'csdup_repo_folder',
         // program panels / firmware
@@ -5851,7 +5851,7 @@ <h2 id="modalTitle">Import error</h2>
     }
     Studio.clearConsoleAutoStop = clearAutoStop; // Run-path pre-emption (module block)
 
-    // The firmware refuses SD-write + ISP commands (0x8D/0xE0/0x8A/0x8F/0xC8/0xC9)
+    // The firmware refuses SD-write + ISP commands (0x85/0xE0/0x8A/0x8F/0xC8/0xC9)
     // unless the display is stopped (state ALL_OFF — CE_DISPLAY_ACTIVE with
     // "Stop display before …" otherwise). STOP_DISPLAY also BLANKS the panels
     // (they latch their last frame, so the controller pushes a dark frame).
@@ -6519,12 +6519,17 @@ <h2 id="modalTitle">Import error</h2>
             finally { e.target.disabled = false; }
         }
     });
-    // One SD .pat write: SET_PATTERN_FILE 0x8D upload + SET_PATTERN_FILENAME
+    // One SD .pat write: SET_PATTERN_FILE 0x85 upload + SET_PATTERN_FILENAME
     // 0x83 rename (both must succeed). Quiet path (session.send) — the batch
-    // wrapper owns the status line + per-file error log.
+    // wrapper owns the status line + per-file error log. The name is checked
+    // FIRST (PatternSet.checkSdFilename: ASCII, <= 63 chars), so a name the
+    // controller can't store fails in a moment instead of after the whole upload
+    // (which left it on the card as pattern.temp).
     async function sdUploadOne(name, bytes) {
+        const chk = window.PatternSet && PatternSet.checkSdFilename ? PatternSet.checkSdFilename(name) : null;
+        if (chk && chk.level === 'error') return { ok: false, retry: false, error: 'bad name — ' + chk.problems.join('; ') };
         const up = await session.send(Wire.encodeSetPatternFile(0, bytes), { timeoutMs: 120000, expectedCmd: Wire.OPCODES.SET_PATTERN_FILE });
-        if (!((Wire.decodeResponse(up) || {}).ok)) return { ok: false, error: 'write rejected (0x8D)' };
+        if (!((Wire.decodeResponse(up) || {}).ok)) return { ok: false, error: 'write rejected (0x85)' };
         const rn = await session.send(Wire.encodeSetPatternFilename(0, name), { timeoutMs: 10000, expectedCmd: Wire.OPCODES.SET_PATTERN_FILENAME });
         if (Wire.decodeSetPatternFilenameResponse(rn) == null) return { ok: false, error: 'rename failed (0x83)' };
         return { ok: true };
@@ -6538,7 +6543,7 @@ <h2 id="modalTitle">Import error</h2>
         const tag = srcLabel ? ' (' + srcLabel + ')' : '';
         if (!files.length) { $('cSdUpStatus').textContent = 'nothing to upload' + tag; return { done: 0, failed: 0 }; }
         if (!connected()) { clog('SD upload: connect first', 'err'); return { done: 0, failed: 0 }; }
-        await quiesceDisplay(); // 0x8D requires the display stopped
+        await quiesceDisplay(); // 0x85 requires the display stopped
         // Breathing room between writes: the controller commits each .pat to the
         // SD (FAT + long-filename entry) before it's ready for the next; back-to-
         // back writes of a LARGE file could be dropped while it's still busy
@@ -6554,11 +6559,18 @@ <h2 id="modalTitle">Import error</h2>
             const pos = (i + 1) + '/' + files.length;
             const kb = (f.bytes.length / 1024).toFixed(1) + ' KB';
             $('cSdUpStatus').textContent = 'uploading ' + pos + tag + ' — ' + f.name + '…';
+            // An upload never overwrites: a name already on the card is stored as
+            // X001_<name>, and protocols can't tell the copies apart. Say so up front.
+            const onCard = Studio.patternSet && Studio.patternSet.patterns && Studio.sdLogicalName
+                ? Studio.patternSet.patterns[Studio.sdLogicalName(f.name)] : null;
+            if (onCard) clog('⚠ "' + f.name + '" is already on the SD card — this copy will be stored as X001_… next to it; delete the old one to replace it', 'warn');
+            const nameChk = window.PatternSet && PatternSet.checkSdFilename ? PatternSet.checkSdFilename(f.name) : null;
+            if (nameChk && nameChk.level === 'warn') clog('⚠ ' + f.name + ': ' + nameChk.problems.join('; '), 'warn');
             let r = null;
             try {
                 r = await sdUploadOne(f.name, f.bytes);
             } catch (e) { r = { ok: false, error: (e && e.message ? e.message : String(e)) }; }
-            if (!r.ok) {
+            if (!r.ok && r.retry !== false) {
                 // One retry after a longer settle — rescues a large file dropped
                 // while the controller was still committing the previous one.
                 clog('SD … ' + pos + '  ' + f.name + ' — ' + r.error + '; retrying in ' + (RETRY_GAP_MS / 1000) + 's…', 'warn');
@@ -7991,9 +8003,14 @@ <h2 id="modalTitle">Import error</h2>
 // name for name↔SD reconciliation: drop a leading index prefix and the .pat
 // extension. Robust to one card holding several protocols' sets (each set's
 // 1-based prefixes collide globally, but the names stay unique + resolvable).
+// The logical pattern name of an SD filename: no .pat, no NNN_ index prefix, and no
+// X001_ prefix — the controller's rename for a same-name re-upload (SdManager.cpp
+// renamePattern, X%03u_), so a re-upload shows up as a DUPLICATE of the original
+// (onSdListing warns; protocols refuse to guess) instead of a separate pattern.
 function sdLogicalName(fn) {
     return String(fn == null ? '' : fn)
         .replace(/\.pat$/i, '')
+        .replace(/^X\d{3}_/, '')
         .replace(/^\d+[_-]/, '');
 }
 Studio.sdLogicalName = sdLogicalName;
@@ -11038,7 +11055,7 @@ <h2 id="modalTitle">Import error</h2>
 // ---- Upload ▾: library / course-repo pattern-set sources --------------------
 // The Console SD "Upload ▾" menu's library/repo items land here. Both browse a
 // PROTOCOL, resolve its colocated _patterns/ set via the GitHub Contents API,
-// then hand {name, bytes} files to Studio.sdUploadFiles (classic shell → 0x8D/
+// then hand {name, bytes} files to Studio.sdUploadFiles (classic shell → 0x85/
 // 0x83). source ∈ 'library' | 'repo'; mode ∈ 'file' (pick one) | 'folder' (all).
 // Library origin = the canonical public tools repo (GH_OWNER/GH_REPO); repo
 // origin = the signed-in course repo. Both need a token — headers() has no anon
diff --git a/tests/test-sd-filenames.js b/tests/test-sd-filenames.js
new file mode 100644
index 00000000..482826b7
--- /dev/null
+++ b/tests/test-sd-filenames.js
@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Pattern filenames vs the controller's SD rules, end to end:
+ *   - js/pattern-set.js checkSdFilename / sanitizeSdFilename / fitSdFilename (the shared rule:
+ *     ASCII, <= 63 characters, <= 58 so a same-name re-upload — stored as X001_<name> —
+ *     keeps its .pat);
+ *   - the Pattern Designer's generated names (short words + the compact color code) stay
+ *     within 58 for every arena prefix, and withColorTag / fitPatternFilename normalize them;
+ *   - the Studio checks the name BEFORE uploading the bytes, doesn't retry a bad name, and
+ *     treats the X001_ prefix as a duplicate of the original (sdLogicalName).
+ * Editor/Studio functions are extracted from the HTML and run in a sandbox.
+ */
+const fs = require('fs');
+const path = require('path');
+const vm = require('vm');
+
+const ROOT = path.join(__dirname, '..');
+const PS = require('../js/pattern-set.js');
+const PC = require('../js/panel-color.js');
+const { STANDARD_CONFIGS } = require('../js/arena-configs.js');
+
+const designer = fs.readFileSync(path.join(ROOT, 'pattern_editor.html'), 'utf8');
+const studio = fs.readFileSync(path.join(ROOT, 'arena_studio.html'), 'utf8');
+
+let checks = 0;
+let failures = 0;
+
+function check(name, condition, detail) {
+    checks++;
+    if (condition) {
+        console.log(`  PASS  ${name}`);
+        return;
+    }
+    failures++;
+    console.log(`  FAIL  ${name}${detail ? ` — ${detail}` : ''}`);
+}
+
+function extract(src, name, file) {
+    const start = src.indexOf(`function ${name}(`);
+    if (start < 0) throw new Error(`${file}: function ${name} not found`);
+    const open = src.indexOf('{', start);
+    let depth = 0;
+    for (let i = open; i < src.length; i++) {
+        if (src[i] === '{') depth++;
+        else if (src[i] === '}' && --depth === 0) return src.slice(start, i + 1);
+    }
+    throw new Error(`${file}: unbalanced braces in ${name}`);
+}
+
+console.log('\n=== shared rule: js/pattern-set.js ===');
+{
+    check('SD_NAME_MAX = 63 (64-byte firmware buffer incl. NUL)', PS.SD_NAME_MAX === 63);
+    check('SD_NAME_SAFE = 58 (room for the X001_ re-upload prefix)', PS.SD_NAME_SAFE === 58);
+    const lvl = (n) => PS.checkSdFilename(n).level;
+    check('a Designer name is ok', lvl('G6_2x10_grat_rot_20px_50pct_4c-B-G.pat') === 'ok');
+    check('58 characters is ok', lvl('a'.repeat(54) + '.pat') === 'ok');
+    check('59 characters warns', lvl('a'.repeat(55) + '.pat') === 'warn');
+    check('63 characters warns', lvl('a'.repeat(59) + '.pat') === 'warn');
+    check('64 characters is an error', lvl('a'.repeat(60) + '.pat') === 'error');
+    check('non-ASCII (°) is an error', lvl('grat_30°.pat') === 'error');
+    check('a space is an error', lvl('my grating.pat') === 'error');
+    check('missing .pat is an error', lvl('foo.bin') === 'error');
+    check('a leading dot is an error (the firmware hides it)', lvl('.hidden.pat') === 'error');
+    check('decimals are fine', lvl('G6_2x10_grat_rot_22.5deg_50pct.pat') === 'ok');
+    check(
+        'sanitize: spaces and symbols become _',
+        PS.sanitizeSdFilename('my grating → 30°.pat') === 'my_grating_30.pat'
+    );
+    const fit = PS.fitSdFilename(
+        'G6_3x16_full_',
+        'star_trans_1000dot_1000f_with_a_long_note',
+        '_4c-F80A-0404'
+    );
+    check('fit: shortens the middle to at most 58', fit.length <= 58 && fit.length >= 50, fit);
+    check(
+        'fit: keeps the arena prefix and the color tag',
+        fit.startsWith('G6_3x16_full_star_trans') && fit.endsWith('_4c-F80A-0404.pat'),
+        fit
+    );
+    check('fit: the result passes the check', PS.checkSdFilename(fit).level === 'ok');
+    check(
+        'fit: a short name is unchanged',
+        PS.fitSdFilename('G6_2x10_', 'grat_rot_20px', '_4c') === 'G6_2x10_grat_rot_20px_4c.pat'
+    );
+}
+
+console.log('\n=== Pattern Designer: generated names ===');
+function designerFor(layoutKey, configName) {
+    const sandbox = {
+        PanelColor: PC,
+        PatternSet: PS,
+        STANDARD_CONFIGS,
+        console,
+        state: { panel: { layoutKey }, arena: { configName } }
+    };
+    sandbox.window = sandbox;
+    vm.createContext(sandbox);
+    vm.runInContext(
+        ['withColorTag', 'motionAbbrev', 'fitPatternFilename', 'findArenaPrefix', 'addArenaPrefix']
+            .map((n) => extract(designer, n, 'pattern_editor.html'))
+            .join('\n') +
+            '\nconst MOTION_ABBREV = { rotation: "rot", expansion: "exp", translation: "trans" };',
+        sandbox
+    );
+    return sandbox;
+}
+{
+    const templates = designer.match(/filename = `[^`]*\.pat`/g) || [];
+    check(
+        'generated templates use the short words (grat/star/offon/anim, motionAbbrev)',
+        templates.some((t) => t.includes('`grat_${motionAbbrev(')) &&
+            templates.some((t) => t.includes('`star_${motionAbbrev(')) &&
+            templates.some((t) => t.includes('`offon_')) &&
+            /`anim_\$\{frames\.length\}f\.pat`/.test(designer) &&
+            !/`(grating|starfield|off_on|animation)_/.test(designer),
+        templates.join(' | ')
+    );
+    const d = designerFor('four-color', 'G6_2x10');
+    check('motionAbbrev: translation → trans', d.motionAbbrev('translation') === 'trans');
+    check(
+        'motionAbbrev: rotation → rot, expansion → exp',
+        d.motionAbbrev('rotation') === 'rot' && d.motionAbbrev('expansion') === 'exp'
+    );
+    check(
+        'withColorTag: generation stamps the code',
+        d.withColorTag('grat_rot_20px_50pct.pat', '-B-G') === 'grat_rot_20px_50pct_4c-B-G.pat'
+    );
+    check(
+        'withColorTag: save keeps the code',
+        d.withColorTag('G6_2x10_grat_rot_20px_50pct_4c-B-G.pat') ===
+            'G6_2x10_grat_rot_20px_50pct_4c-B-G.pat'
+    );
+    check(
+        'withColorTag: replaces another layout tag (no _rir_4c)',
+        d.withColorTag('x_rir-I.pat') === 'x_4c.pat'
+    );
+    check(
+        'withColorTag: unstacks old _4c_rir names',
+        d.withColorTag('x_4c_rir.pat') === 'x_4c.pat'
+    );
+    check(
+        'withColorTag: default choice adds just the layout tag',
+        d.withColorTag('x.pat', '') === 'x_4c.pat'
+    );
+    const green = designerFor('g6-green', 'G6_2x10');
+    check(
+        'withColorTag: green layout leaves names alone',
+        green.withColorTag('x_4c-B.pat') === 'x_4c-B.pat'
+    );
+
+    // Worst cases the Generate tab can produce today, for every arena prefix + longest tag
+    const longest = [
+        'star_trans_1000dot_1000f.pat',
+        'grat_trans_22.5deg_50pct.pat',
+        'edge_trans_22.5deg_100f.pat',
+        'sine_trans_22.5deg.pat'
+    ];
+    const worstCode = '-F80A-0404';
+    let worstLen = 0;
+    let worstName = '';
+    for (const config of Object.keys(STANDARD_CONFIGS)) {
+        const ed = designerFor('four-color', config);
+        for (const n of longest) {
+            const name = ed.withColorTag(ed.addArenaPrefix(n), worstCode);
+            if (name.length > worstLen) {
+                worstLen = name.length;
+                worstName = name;
+            }
+        }
+    }
+    check(`longest generated name fits in 58 (${worstLen}: ${worstName})`, worstLen <= 58);
+    const ed = designerFor('four-color', 'G6_3x16_full');
+    const long = ed.fitPatternFilename(
+        'G6_3x16_full_star_trans_1000dot_1000f_my_extra_long_note_here_4c-F80A-0404.pat'
+    );
+    check(
+        'fitPatternFilename: shortens a long name to at most 58',
+        long.name.length <= 58 && long.name.length >= 50,
+        long.name
+    );
+    check(
+        'fitPatternFilename: keeps prefix + color tag and reports why',
+        long.name.startsWith('G6_3x16_full_') &&
+            long.name.endsWith('_4c-F80A-0404.pat') &&
+            long.problems.length > 0,
+        long.name
+    );
+    const bad = ed.fitPatternFilename('G6_3x16_full_my grating 30°.pat');
+    check(
+        'fitPatternFilename: cleans characters',
+        bad.name === 'G6_3x16_full_my_grating_30.pat',
+        bad.name
+    );
+    const ok = ed.fitPatternFilename('G6_2x10_grat_rot_20px_50pct_4c-B.pat');
+    check(
+        'fitPatternFilename: a good name passes untouched',
+        ok.name === 'G6_2x10_grat_rot_20px_50pct_4c-B.pat' && ok.problems.length === 0
+    );
+    check(
+        'save path runs fitPatternFilename',
+        /fitPatternFilename\(withColorTag\(addArenaPrefix\(/.test(
+            extract(designer, 'buildPatternDataForSave', 'pattern_editor.html')
+        )
+    );
+}
+
+console.log('\n=== Studio: upload order + X001_ duplicates ===');
+{
+    const sb = {};
+    vm.createContext(sb);
+    vm.runInContext(extract(studio, 'sdLogicalName', 'arena_studio.html'), sb);
+    check('sdLogicalName: plain', sb.sdLogicalName('grat_rot.pat') === 'grat_rot');
+    check('sdLogicalName: NNN_ index prefix', sb.sdLogicalName('003_grat_rot.pat') === 'grat_rot');
+    check(
+        'sdLogicalName: X001_ re-upload = the original',
+        sb.sdLogicalName('X001_grat_rot.pat') === 'grat_rot'
+    );
+    check(
+        'sdLogicalName: X002_ of an indexed name',
+        sb.sdLogicalName('X002_003_grat_rot.pat') === 'grat_rot'
+    );
+    check(
+        'sdLogicalName: a name that merely starts with X stays',
+        sb.sdLogicalName('Xmas_tree.pat') === 'Xmas_tree'
+    );
+
+    const up = extract(studio, 'sdUploadOne', 'arena_studio.html');
+    const iCheck = up.indexOf('checkSdFilename');
+    const iSend = up.indexOf('encodeSetPatternFile(');
+    check('sdUploadOne checks the name before sending any bytes', iCheck > 0 && iCheck < iSend);
+    check(
+        'a bad name is not retried',
+        /retry: false/.test(up) && /r\.retry !== false/.test(studio)
+    );
+    check(
+        'upload warns when the name is already on the card',
+        /is already on the SD card/.test(studio)
+    );
+    check(
+        'the upload opcode is labelled 0x85 (no stale 0x8D)',
+        !/0x8D/.test(studio) && /write rejected \(0x85\)/.test(studio)
+    );
+}
+
+console.log(`\n${checks - failures}/${checks} checks passed`);
+if (failures > 0) {
+    console.log(`${failures} FAILED`);
+    process.exit(1);
+}

From 84daa996a134e35566a4e903a01c2a8ad6381836 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Tue, 6 Oct 2026 18:53:37 -0400
Subject: [PATCH 08/17] =?UTF-8?q?fix:=20rc1=20review=20=E2=80=94=20SD=20na?=
 =?UTF-8?q?me=20rule=20matches=20the=20card,=20cache=20tokens,=20partial-G?=
 =?UTF-8?q?6=20warning?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

From the adversarial review of candidate 2026-10-06 rc1 (Claude + Codex):
- The shared SD name rule (PatternSet.checkSdFilename) refused anything outside
  [A-Za-z0-9._-], so the Studio blocked uploads that worked before: spaces and
  parentheses are legal FAT long-name characters (e.g. a browser's "… (1).pat").
  It now errors only on what the card can't store (non-printable/non-ASCII, \ / : * ? " < > |,
  > 63 chars, no .pat, leading "."); the Designer still writes tidy names
  (SD_TIDY_CHARS) and says so when it changes one.
- Cache tokens (?v=1006-partial-cols) on every consumer of the changed shared modules:
  icon-generator.js (Designer, Studio, Console, v3 designer, icon tool), pattern-set.js
  (Designer, Studio, Console, v3 designer), panel-color.js (Designer) — so the fixes reach
  browsers holding an old copy. Pinned in tests.
- Partial-G6 warning (never blocks): current firmware ignores the panel mask and rejects
  any grid other than its own at load. The Designer says so once per session when a
  partial-G6 pattern is saved; the Studio upload warns when the session rig is a partial
  arena, when a file carries a partial panel mask, or when its grid differs from the rig's
  (PatternSet.g6HeaderGrid / g6PlaybackWarning; Studio.rigArena()).
- 2D panel numbers: a block past the installed list labels its own number, never NaN.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 arena_console.html            |   4 +-
 arena_studio.html             |  22 ++++++-
 experiment_designer_v3.html   |   4 +-
 icon_generator.html           |   2 +-
 js/pattern-set.js             |  85 +++++++++++++++++++++++--
 pattern_editor.html           |  38 ++++++++---
 tests/test-panel-color.js     |   2 +-
 tests/test-pattern-2d-view.js |   4 ++
 tests/test-sd-filenames.js    | 115 +++++++++++++++++++++++++++++++++-
 9 files changed, 253 insertions(+), 23 deletions(-)

diff --git a/arena_console.html b/arena_console.html
index 033490f2..84796dae 100644
--- a/arena_console.html
+++ b/arena_console.html
@@ -1577,7 +1577,7 @@
              (window.PatternSet / window.PatPreview); the import-only modules
              (pat-parser, arena-configs, icon-generator) load in the deferred module
              block at the end of <body>. -->
-        <script src="js/pattern-set.js"></script>
+        <script src="js/pattern-set.js?v=1006-partial-cols"></script>
         <script src="js/pat-preview.js"></script>
         <script>
             'use strict';
@@ -3602,7 +3602,7 @@
         <script type="module">
             import PatParser from './js/pat-parser.js';
             import { getConfig } from './js/arena-configs.js'; // also sets window.PANEL_SPECS
-            import { generatePatternIcon } from './js/icon-generator.js';
+            import { generatePatternIcon } from './js/icon-generator.js?v=1006-partial-cols';
 
             const PS = window.PatternSet;
             const PP = window.PatPreview;
diff --git a/arena_studio.html b/arena_studio.html
index 9e12badc..a23880d2 100644
--- a/arena_studio.html
+++ b/arena_studio.html
@@ -3368,7 +3368,7 @@ <h2 id="modalTitle">Import error</h2>
 <script src="js/fictrac-bridge-client.js?v=20260926-cl-start"></script>
 <script src="js/arena-session.js"></script>
 <script src="js/pat-encoder.js"></script>
-<script src="js/pattern-set.js"></script>
+<script src="js/pattern-set.js?v=1006-partial-cols"></script>
 <script src="js/pat-preview.js"></script>
 <script src="js/bin-classifier.js"></script>
 <script src="https://cdnjs.cloudflare.com/ajax/libs/jszip/3.10.1/jszip.min.js"></script> <!-- Pattern Set ZIP export -->
@@ -6554,6 +6554,13 @@ <h2 id="modalTitle">Import error</h2>
         let done = 0, failed = 0;
         const uploaded = [];
         clog('SD upload: ' + files.length + ' file(s)' + tag + '…', 'info');
+        // G6 playback: warn (never block) when the controller would reject a pattern at load
+        // — the rig is a partial arena, or the file's grid differs from the rig's.
+        const PS = window.PatternSet;
+        const rigArena = Studio.rigArena ? Studio.rigArena() : null;
+        if (PS && PS.isPartialG6Arena && PS.isPartialG6Arena(rigArena)) {
+            clog('⚠ the session rig (' + Studio.currentRig.arenaConfig + ') is a partial arena: ' + PS.PARTIAL_G6_NOTE, 'warn');
+        }
         for (let i = 0; i < files.length; i++) {
             const f = files[i];
             const pos = (i + 1) + '/' + files.length;
@@ -6566,6 +6573,8 @@ <h2 id="modalTitle">Import error</h2>
             if (onCard) clog('⚠ "' + f.name + '" is already on the SD card — this copy will be stored as X001_… next to it; delete the old one to replace it', 'warn');
             const nameChk = window.PatternSet && PatternSet.checkSdFilename ? PatternSet.checkSdFilename(f.name) : null;
             if (nameChk && nameChk.level === 'warn') clog('⚠ ' + f.name + ': ' + nameChk.problems.join('; '), 'warn');
+            const playWarn = PS && PS.g6PlaybackWarning ? PS.g6PlaybackWarning(f.bytes, rigArena) : null;
+            if (playWarn) clog('⚠ ' + f.name + ': ' + playWarn, 'warn');
             let r = null;
             try {
                 r = await sdUploadOne(f.name, f.bytes);
@@ -7303,7 +7312,7 @@ <h2 id="modalTitle">Import error</h2>
 } from './js/v3-import.js';
 import { getConfig } from './js/arena-configs.js'; // side effect: sets window.PANEL_SPECS
 import PatParser from './js/pat-parser.js';
-import { generatePatternIcon } from './js/icon-generator.js';
+import { generatePatternIcon } from './js/icon-generator.js?v=1006-partial-cols';
 import * as YAML from 'yaml'; // vendored build has NAMED exports only (no default)
 
 const Studio = window.Studio;
@@ -7998,7 +8007,7 @@ <h2 id="modalTitle">Import error</h2>
 }
 // The card stores pattern files as `NNN_<name>.pat` — the zero-padded index
 // pins the firmware's SD-scan order (== pattern_ID) and the >8.3 name forces a
-// FAT long-filename entry (js/pattern-set.js:242). Protocols, though, reference
+// FAT long-filename entry (js/pattern-set.js assignIndices). Protocols, though, reference
 // the LOGICAL name (`all_on`). Normalize a raw SD filename to that logical
 // name for name↔SD reconciliation: drop a leading index prefix and the .pat
 // extension. Robust to one card holding several protocols' sets (each set's
@@ -9662,6 +9671,13 @@ <h2 id="modalTitle">Import error</h2>
 // arena's azimuth pixels (num_cols × pixels_per_panel — 200 on a 10-column G6 ⇒ 1.8). A
 // PATTERN property really (1 px per frame), which every shipped closed-loop pattern has; a
 // startClosedLoop `deg_per_frame` overrides it for exotic patterns. NOT 360 / frame_count.
+// The session rig's config.arena ({generation, num_rows, num_cols, columns_installed, …}) or
+// null — for classic-shell code that has no getConfig (the SD upload's G6 playback warning).
+Studio.rigArena = function () {
+    const name = Studio.currentRig && Studio.currentRig.arenaConfig;
+    const cfg = name ? getConfig(name) : null;
+    return (cfg && cfg.arena) || null;
+};
 Studio.rigDegPerFrame = function () {
     const name = Studio.currentRig && Studio.currentRig.arenaConfig;
     const cfg = name ? getConfig(name) : null;
diff --git a/experiment_designer_v3.html b/experiment_designer_v3.html
index 98a8d8d2..5fd3c395 100644
--- a/experiment_designer_v3.html
+++ b/experiment_designer_v3.html
@@ -1621,7 +1621,7 @@ <h2 id="modalTitle">Import error</h2>
          arena-configs.js, and icon-generator.js have bare exports, so the module
          below imports those. JSZip (CDN, pinned) powers the bundle ZIP export. -->
     <script src="js/pat-encoder.js"></script>
-    <script src="js/pattern-set.js"></script>
+    <script src="js/pattern-set.js?v=1006-partial-cols"></script>
     <script src="js/pat-preview.js"></script>
     <script src="https://cdnjs.cloudflare.com/ajax/libs/jszip/3.10.1/jszip.min.js"></script>
 
@@ -1705,7 +1705,7 @@ <h2 id="modalTitle">Import error</h2>
         // LAB-96 — animated pattern preview: one cylindrical icon per sampled frame.
         // arena-configs (imported above) sets window.PANEL_SPECS, which icon-generator
         // reads at call time.
-        import { generatePatternIcon } from './js/icon-generator.js';
+        import { generatePatternIcon } from './js/icon-generator.js?v=1006-partial-cols';
 
         // ═══════════════════════════════════════════════════════════════
         // State
diff --git a/icon_generator.html b/icon_generator.html
index f7f0387f..fe7413a8 100644
--- a/icon_generator.html
+++ b/icon_generator.html
@@ -10,7 +10,7 @@
         // Cache-busting: v4 adds GIF generation support
         import { STANDARD_CONFIGS, PANEL_SPECS, getConfig, getConfigsByGeneration } from './js/arena-configs.js?v=4';
         import PatParser from './js/pat-parser.js?v=4';
-        import { generatePatternIcon, generateMotionIcon, generatePatternGIF } from './js/icon-generator.js?v=4';
+        import { generatePatternIcon, generateMotionIcon, generatePatternGIF } from './js/icon-generator.js?v=1006-partial-cols';
 
         // Make available globally for inline script
         window.STANDARD_CONFIGS = STANDARD_CONFIGS;
diff --git a/js/pattern-set.js b/js/pattern-set.js
index cb66e8c4..05c635e8 100644
--- a/js/pattern-set.js
+++ b/js/pattern-set.js
@@ -428,11 +428,16 @@
     // The controller keeps pattern names in a 64-byte buffer (incl. NUL): at most 63 chars,
     // and SET_PATTERN_FILENAME 0x83 refuses longer. A same-name re-upload is stored as
     // X001_<name> (5 more chars, truncated to 63) — past 58 that cuts off '.pat' and the file
-    // drops out of the listing. Names travel as one byte per char, so only plain ASCII
-    // filename characters are safe. Firmware: SdManager.cpp renamePattern / scan.
+    // drops out of the listing. Names travel as one byte per char, so the name must be
+    // printable ASCII; FAT long names also forbid \ / : * ? " < > |. Spaces and parentheses
+    // are legal (and common: a browser's "… (1).pat" download). The Designer still writes
+    // tidy names ([A-Za-z0-9._-], SD_TIDY_CHARS) — that is style, not a controller rule.
+    // Firmware: SdManager.cpp renamePattern / scan.
     var SD_NAME_MAX = 63;
     var SD_NAME_SAFE = 58;
-    var SD_NAME_CHARS = /^[A-Za-z0-9._-]+$/;
+    var SD_NAME_CHARS = /^[\x20-\x7e]+$/;
+    var SD_NAME_FORBIDDEN = /[\\/:*?"<>|]/;
+    var SD_TIDY_CHARS = /^[A-Za-z0-9._-]+$/;
 
     /**
      * Check a pattern filename (with .pat) against the controller's SD rules.
@@ -444,7 +449,8 @@
         var errors = [];
         var warnings = [];
         if (!/\.pat$/i.test(n)) errors.push('must end in .pat');
-        if (!SD_NAME_CHARS.test(n)) errors.push('use only letters, digits, "_", "-" and "."');
+        if (!SD_NAME_CHARS.test(n)) errors.push('use plain ASCII characters only');
+        if (SD_NAME_FORBIDDEN.test(n)) errors.push('must not contain \\ / : * ? " < > |');
         if (n.charAt(0) === '.') errors.push('must not start with "."');
         if (n.length > SD_NAME_MAX) {
             errors.push(n.length + ' characters; the controller allows ' + SD_NAME_MAX);
@@ -491,6 +497,72 @@
         return sanitizeSdFilename(p + m + sfx);
     }
 
+    // ---- G6 playback on the session rig ----------------------------------------------
+    // Current arena firmware compiles in one dense panel grid and ignores the G6 panel mask,
+    // so a partial-arena pattern (or any grid that differs from the controller's) is rejected
+    // at load (CE_ARENA_MISMATCH, "TRIAL_PARAMS: load failed"). Warn — never block.
+    var PARTIAL_G6_NOTE =
+        "current arena firmware can't play partial-arena G6 patterns yet; the controller " +
+        'rejects them when loading. Until it can, use a full-grid pattern with the missing ' +
+        'columns left blank.';
+
+    /** {rows, cols, maskPanels} from a G6 .pat header, or null when it isn't one. */
+    function g6HeaderGrid(bytes) {
+        var u8;
+        try {
+            u8 = new Uint8Array(toArrayBuffer(bytes));
+        } catch (_) {
+            return null;
+        }
+        // 'G6PT'
+        if (
+            u8.length < 18 ||
+            u8[0] !== 0x47 ||
+            u8[1] !== 0x36 ||
+            u8[2] !== 0x50 ||
+            u8[3] !== 0x54
+        ) {
+            return null;
+        }
+        var mask = 0;
+        for (var i = 11; i <= 16; i++) {
+            for (var v = u8[i]; v; v >>= 1) mask += v & 1;
+        }
+        return { rows: u8[8], cols: u8[9], maskPanels: mask };
+    }
+
+    /** True for a G6 arena config with missing columns (G6_2x8of10, G6_3x12of18 …). */
+    function isPartialG6Arena(arena) {
+        return !!(arena && arena.generation === 'G6' && arena.columns_installed);
+    }
+
+    /**
+     * Why a G6 .pat won't play, judged from its own header and (when it is a FULL G6 arena)
+     * the session rig's config.arena; null when nothing is wrong or it isn't a G6 pattern.
+     * A partial session rig is reported once per batch by the caller (isPartialG6Arena).
+     */
+    function g6PlaybackWarning(bytes, arena) {
+        var g = g6HeaderGrid(bytes);
+        if (!g) return null;
+        if (g.maskPanels < g.rows * g.cols)
+            return 'partial-arena pattern (panel mask): ' + PARTIAL_G6_NOTE;
+        if (arena && arena.generation === 'G6' && !arena.columns_installed) {
+            if (g.rows !== arena.num_rows || g.cols !== arena.num_cols) {
+                return (
+                    g.rows +
+                    '×' +
+                    g.cols +
+                    ' panels, but the session rig is ' +
+                    arena.num_rows +
+                    '×' +
+                    arena.num_cols +
+                    ' — the controller will reject it when loading'
+                );
+            }
+        }
+        return null;
+    }
+
     var PatternSet = {
         TOOL: TOOL,
         MANIFEST_VERSION: MANIFEST_VERSION,
@@ -510,6 +582,11 @@
         checkSdFilename: checkSdFilename,
         sanitizeSdFilename: sanitizeSdFilename,
         fitSdFilename: fitSdFilename,
+        SD_TIDY_CHARS: SD_TIDY_CHARS,
+        PARTIAL_G6_NOTE: PARTIAL_G6_NOTE,
+        g6HeaderGrid: g6HeaderGrid,
+        isPartialG6Arena: isPartialG6Arena,
+        g6PlaybackWarning: g6PlaybackWarning,
         summarizePattern: summarizePattern,
         validateGeometry: validateGeometry,
         reencodeForDuty: reencodeForDuty,
diff --git a/pattern_editor.html b/pattern_editor.html
index 94330d65..e8d7579b 100644
--- a/pattern_editor.html
+++ b/pattern_editor.html
@@ -36,10 +36,10 @@
          (?repo= / ?arena= URL state) — same classic dual-export modules the
          Studio loads, so behavior matches across the two tools -->
     <script src="js/build-channel.js"></script> <!-- release tier: Production / Next / local -->
-    <script src="js/pattern-set.js"></script>
+    <script src="js/pattern-set.js?v=1006-partial-cols"></script>
     <!-- multi-color G6 panels: bank mosaic + ON-color weights (LAB-228); classic dual-export,
          also read as globalThis.PanelColor by the ES-module viewers -->
-    <script src="js/panel-color.js"></script>
+    <script src="js/panel-color.js?v=1006-partial-cols"></script>
     <script src="js/studio-url-state.js"></script>
     <style>
         * { margin: 0; padding: 0; box-sizing: border-box; }
@@ -2569,7 +2569,7 @@ <h3 class="modal-title">Save to Repo</h3>
         import MercatorViewer from './js/pattern-editor/viewers/mercator-viewer.js?v=0218';
         import MollweideViewer from './js/pattern-editor/viewers/mollweide-viewer.js?v=0218';
         import { combinePatterns } from './js/pattern-editor/tools/combiner.js';
-        import { generatePatternIcon } from './js/icon-generator.js';
+        import { generatePatternIcon } from './js/icon-generator.js?v=1006-partial-cols';
         import ImageConverter from './js/pattern-editor/tools/image-converter.js';
         // Classic dual-export module loaded above (also read by the viewers as globalThis.PanelColor)
         const PanelColor = window.PanelColor;
@@ -3549,6 +3549,7 @@ <h3 class="modal-title">Save to Repo</h3>
                 arena_id: configName ? getArenaId(gen, configName) : 0,
                 observer_id: 0
             };
+            warnPartialG6Once();
             const fitted = fitPatternFilename(withColorTag(addArenaPrefix(state.filename || 'pattern.pat')));
             if (fitted.problems.length) {
                 console.info('Pattern filename adjusted for the arena SD card (' + fitted.problems.join('; ') + '): ' + fitted.name);
@@ -5517,6 +5518,22 @@ <h3 class="modal-title">Save to Repo</h3>
             return stripped + tag + keep + '.pat';
         }
 
+        // Partial-arena G6 patterns preview correctly but current firmware can't play them
+        // (it ignores the panel mask) — say so once per session when one is saved. Warn only.
+        let partialG6Warned = false;
+        function warnPartialG6Once() {
+            const arena = state.arena.config && state.arena.config.arena;
+            const partial = window.PatternSet && PatternSet.isPartialG6Arena
+                ? PatternSet.isPartialG6Arena(arena)
+                : !!(arena && arena.generation === 'G6' && arena.columns_installed);
+            if (!partial || partialG6Warned) return;
+            partialG6Warned = true;
+            const note = (window.PatternSet && PatternSet.PARTIAL_G6_NOTE) ||
+                "current arena firmware can't play partial-arena G6 patterns yet.";
+            alert('Heads-up: ' + state.arena.configName + ' is a partial arena. ' +
+                note.charAt(0).toUpperCase() + note.slice(1));
+        }
+
         // Motion types in generated filenames (names stay short: the controller keeps 63
         // characters and 58 survive a re-upload — PatternSet.checkSdFilename).
         const MOTION_ABBREV = { rotation: 'rot', expansion: 'exp', translation: 'trans' };
@@ -5525,23 +5542,26 @@ <h3 class="modal-title">Save to Repo</h3>
         }
 
         /**
-         * Make a filename safe for the arena's SD card: plain ASCII, <= 58 characters. Only the
-         * descriptive middle is shortened; the arena prefix and the color tag are kept.
-         * Returns {name, problems} (problems = what the original name broke, for the UI).
+         * Make a filename safe for the arena's SD card (<= 58 characters, PatternSet rules) and
+         * tidy ([A-Za-z0-9._-]: the Designer's naming style, though the card also takes spaces).
+         * Only the descriptive middle is shortened; the arena prefix and the color tag are kept.
+         * Returns {name, problems} (problems = what was changed and why, for the UI).
          */
         function fitPatternFilename(filename) {
             if (!window.PatternSet || !PatternSet.checkSdFilename || !PatternSet.fitSdFilename) {
                 return { name: filename, problems: [] };
             }
             const chk = PatternSet.checkSdFilename(filename);
-            if (chk.ok) return { name: filename, problems: [] };
+            const tidy = !PatternSet.SD_TIDY_CHARS || PatternSet.SD_TIDY_CHARS.test(filename);
+            if (chk.ok && tidy) return { name: filename, problems: [] };
             let base = filename.replace(/\.pat$/i, '');
             const arena = findArenaPrefix(base);
             const prefix = arena ? base.slice(0, arena.length + 1) : '';
             base = base.slice(prefix.length);
             const core = PanelColor.stripColorTag ? PanelColor.stripColorTag(base) : base;
             const suffix = base.slice(core.length);
-            return { name: PatternSet.fitSdFilename(prefix, core, suffix), problems: chk.problems };
+            const problems = tidy ? chk.problems : ['spaces and symbols become "_"'].concat(chk.problems);
+            return { name: PatternSet.fitSdFilename(prefix, core, suffix), problems };
         }
 
         function updatePanelLayoutHint() {
@@ -7020,7 +7040,7 @@ <h2>No Pattern Loaded</h2>
             const installed = arena.columns_installed
                 ? [...new Set(arena.columns_installed.map((p) => p % arena.num_cols))]
                 : null;
-            const col = installed ? installed[block] : block;
+            const col = installed && installed[block] !== undefined ? installed[block] : block;
             return arena.generation === 'G6'
                 ? row * arena.num_cols + col + 1
                 : col * arena.num_rows + row + 1;
diff --git a/tests/test-panel-color.js b/tests/test-panel-color.js
index 2843d34e..fa5063b6 100644
--- a/tests/test-panel-color.js
+++ b/tests/test-panel-color.js
@@ -421,7 +421,7 @@ const src = fs.readFileSync(path.join(ROOT, 'js/panel-color.js'), 'utf8');
 check('panel-color.js has no bare ES export (classic-script safe)', !/^export /m.test(src));
 check(
     'pattern_editor.html loads js/panel-color.js as a classic script',
-    /<script src="js\/panel-color\.js">/.test(html)
+    /<script src="js\/panel-color\.js(\?v=[^"]+)?">/.test(html)
 );
 check(
     'pattern_editor.html renders pixels through PanelColor.pixelCss',
diff --git a/tests/test-pattern-2d-view.js b/tests/test-pattern-2d-view.js
index 3ae4da0a..1eeba1a0 100644
--- a/tests/test-pattern-2d-view.js
+++ b/tests/test-pattern-2d-view.js
@@ -104,6 +104,10 @@ check(
         ed.physicalPanelNumber(full, 0, 0) === 1 && ed.physicalPanelNumber(full, 0, 1) === 11
     );
     const g4 = STANDARD_CONFIGS.G4_3x12of18.arena;
+    check(
+        'a block past the installed list labels its own number, never NaN',
+        ed.physicalPanelNumber(a, 9, 0) === 10
+    );
     check(
         'G4_3x12of18 (column-major): first column = panels 1, 2, 3',
         [0, 1, 2].every((r) => ed.physicalPanelNumber(g4, 0, r) === r + 1)
diff --git a/tests/test-sd-filenames.js b/tests/test-sd-filenames.js
index 482826b7..247e0998 100644
--- a/tests/test-sd-filenames.js
+++ b/tests/test-sd-filenames.js
@@ -60,7 +60,16 @@ console.log('\n=== shared rule: js/pattern-set.js ===');
     check('63 characters warns', lvl('a'.repeat(59) + '.pat') === 'warn');
     check('64 characters is an error', lvl('a'.repeat(60) + '.pat') === 'error');
     check('non-ASCII (°) is an error', lvl('grat_30°.pat') === 'error');
-    check('a space is an error', lvl('my grating.pat') === 'error');
+    check('a space is fine on the card (FAT long names)', lvl('my grating.pat') === 'ok');
+    check(
+        'a browser duplicate "… (1).pat" is fine',
+        lvl('G6_2x10_grating_rotation_200px_94pct (1).pat') === 'ok'
+    );
+    check(
+        'FAT-forbidden characters are errors',
+        ['a:b.pat', 'x?.pat', 'a/b.pat', 'q"t.pat', 'p|q.pat'].every((n) => lvl(n) === 'error')
+    );
+    check('control characters are errors', lvl('tab\there.pat') === 'error');
     check('missing .pat is an error', lvl('foo.bin') === 'error');
     check('a leading dot is an error (the firmware hides it)', lvl('.hidden.pat') === 'error');
     check('decimals are fine', lvl('G6_2x10_grat_rot_22.5deg_50pct.pat') === 'ok');
@@ -187,6 +196,12 @@ function designerFor(layoutKey, configName) {
             long.problems.length > 0,
         long.name
     );
+    const spaced = ed.fitPatternFilename('G6_2x10_Frame 1_h_cw_200f.pat');
+    check(
+        'fitPatternFilename: the Designer still tidies spaces (style, though the card accepts them)',
+        spaced.name === 'G6_2x10_Frame_1_h_cw_200f.pat' && spaced.problems.length === 1,
+        JSON.stringify(spaced)
+    );
     const bad = ed.fitPatternFilename('G6_3x16_full_my grating 30°.pat');
     check(
         'fitPatternFilename: cleans characters',
@@ -206,6 +221,92 @@ function designerFor(layoutKey, configName) {
     );
 }
 
+console.log('\n=== G6 playback warning (partial arenas / grid mismatch) ===');
+{
+    global.PANEL_SPECS = require('../js/arena-configs.js').PANEL_SPECS;
+    const PatEncoder = require('../js/pat-encoder.js');
+    const pat = (rows, cols) => {
+        const W = cols * 20;
+        const H = rows * 20;
+        return new Uint8Array(
+            PatEncoder.encode({
+                generation: 'G6',
+                gs_val: 2,
+                numFrames: 1,
+                rowCount: rows,
+                colCount: cols,
+                pixelRows: H,
+                pixelCols: W,
+                frames: [new Uint8Array(W * H)],
+                stretchValues: [128]
+            })
+        );
+    };
+    const full = STANDARD_CONFIGS.G6_2x10.arena;
+    const partial = STANDARD_CONFIGS.G6_2x8of10.arena;
+    const g = PS.g6HeaderGrid(pat(2, 10));
+    check(
+        'header grid: 2×10, 20 panels in the mask',
+        g && g.rows === 2 && g.cols === 10 && g.maskPanels === 20,
+        JSON.stringify(g)
+    );
+    check('a non-G6 buffer is not read', PS.g6HeaderGrid(new Uint8Array(32)) === null);
+    check(
+        '2×10 pattern on a 2×10 rig: no warning',
+        PS.g6PlaybackWarning(pat(2, 10), full) === null
+    );
+    check(
+        'web-encoded 2×8 (partial) pattern on a 2×10 rig: warned (the controller rejects it)',
+        /2×8 panels, but the session rig is 2×10/.test(PS.g6PlaybackWarning(pat(2, 8), full) || '')
+    );
+    const masked = pat(2, 10);
+    masked[11] &= 0xfe; // clear panel 0 (the MATLAB writer's partial-arena mask)
+    check(
+        'a masked (MATLAB-style partial) pattern: warned',
+        /partial-arena pattern/.test(PS.g6PlaybackWarning(masked, null) || '')
+    );
+    check(
+        'partial rig detection',
+        PS.isPartialG6Arena(partial) && !PS.isPartialG6Arena(full) && !PS.isPartialG6Arena(null)
+    );
+    check(
+        'no rig known: only the file itself is judged',
+        PS.g6PlaybackWarning(pat(2, 8), null) === null
+    );
+}
+
+console.log('\n=== cache tokens on the changed shared modules ===');
+{
+    const pages = {
+        'pattern_editor.html': designer,
+        'arena_studio.html': studio,
+        'arena_console.html': fs.readFileSync(path.join(ROOT, 'arena_console.html'), 'utf8'),
+        'experiment_designer_v3.html': fs.readFileSync(
+            path.join(ROOT, 'experiment_designer_v3.html'),
+            'utf8'
+        ),
+        'icon_generator.html': fs.readFileSync(path.join(ROOT, 'icon_generator.html'), 'utf8')
+    };
+    for (const [page, src] of Object.entries(pages)) {
+        const icon = src.match(/from '\.\/js\/icon-generator\.js(\?v=[^']+)?'/);
+        check(
+            `${page}: icon-generator.js import is cache-busted`,
+            !!(icon && icon[1]),
+            icon ? icon[0] : 'no import'
+        );
+        if (page !== 'icon_generator.html') {
+            check(
+                `${page}: pattern-set.js is cache-busted`,
+                /<script src="js\/pattern-set\.js\?v=[^"]+"><\/script>/.test(src)
+            );
+        }
+    }
+    check(
+        'pattern_editor.html: panel-color.js is cache-busted',
+        /<script src="js\/panel-color\.js\?v=[^"]+"><\/script>/.test(designer)
+    );
+}
+
 console.log('\n=== Studio: upload order + X001_ duplicates ===');
 {
     const sb = {};
@@ -238,6 +339,18 @@ console.log('\n=== Studio: upload order + X001_ duplicates ===');
         'upload warns when the name is already on the card',
         /is already on the SD card/.test(studio)
     );
+    check(
+        'upload warns when the controller would reject a G6 pattern (partial rig / grid mismatch)',
+        /PS\.g6PlaybackWarning\(f\.bytes, rigArena\)/.test(studio) &&
+            /Studio\.rigArena = function/.test(studio)
+    );
+    check(
+        'the Designer warns once when saving a partial-G6 pattern',
+        /function warnPartialG6Once\(/.test(designer) &&
+            /warnPartialG6Once\(\);/.test(
+                extract(designer, 'buildPatternDataForSave', 'pattern_editor.html')
+            )
+    );
     check(
         'the upload opcode is labelled 0x85 (no stale 0x8D)',
         !/0x8D/.test(studio) && /write rejected \(0x85\)/.test(studio)

From 546d9c625678ab48858f2c6eba8da44450b2f997 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Wed, 7 Oct 2026 12:26:14 -0400
Subject: [PATCH 09/17] fix(link): first command after Connect no longer waits
 ~60 s behind the thumbnail download (LAB-298)

Bench 2026-10-07 (rig cshl_g6_2x10_ball, 24 patterns on the card): the first
TRIAL_PARAMS after Connect was acknowledged 57 s late. The SD listing auto-picks
pattern 1 and the picker thumbnail downloaded the whole file (0x84). With
Chrome's default 255-byte Web Serial read buffer the body arrived 901 bytes
short, and the one-at-a-time link waited out the read's 60 s timeout with the
GET_PATTERN_INFO sweep and the user's command queued behind it. Firmware ruled
out from Python (listing + 24x 0x88 in 48 ms, 81 KB download in 6 ms).

- arena-link.js: open the port with a 1 MiB bufferSize; a background lane
  (`{ background: true }`) that waits while any foreground send is queued; a
  bulk body fails after idleTimeoutMs (5 s) without a byte instead of waiting
  out timeoutMs.
- Studio: the GET_PATTERN_INFO sweep (cardPatternInfo, also caches file size)
  and the picker thumbnail fetch use the background lane; a card-only
  thumbnail downloads only when PatPreview.liveFetchVerdict allows it (size
  known, <= 1 MiB, no run). Frame counts for the closed-loop resolver (#201)
  are still filled for every pattern. Tooltip explains a thumbnail refused
  while the display runs (status 10).
- Tests: link buffer/stall/lanes, liveFetchVerdict, Studio call sites.

Verified on hardware: first TRIAL_PARAMS ack 2 ms (was 57,013 ms); 81 KB
thumbnail download 7 ms; 24 frame counts done 197 ms after Connect.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CLAUDE.md                          |   1 +
 arena_studio.html                  |  93 ++++++++++++----
 js/arena-link.js                   | 154 ++++++++++++++++++++------
 js/arena-session.js                |  10 +-
 js/pat-preview.js                  |  23 ++++
 tests/test-arena-link.js           | 170 ++++++++++++++++++++++++++++-
 tests/test-pat-preview.js          |  29 +++++
 tests/test-studio-link-priority.js |  83 ++++++++++++++
 8 files changed, 500 insertions(+), 63 deletions(-)
 create mode 100644 tests/test-studio-link-priority.js

diff --git a/CLAUDE.md b/CLAUDE.md
index 24d2f417..ca5b2ddb 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -163,6 +163,7 @@ Some JavaScript modules are shared between multiple tools and must support diffe
 **Arena Session — the single connection broker** (`js/arena-session.js`, Stage A of the Arena Studio unification):
 - Owns ONE `ArenaLink` + ONE `ArenaRunner` per page and multicasts the link callbacks (`log`/`error`/`disconnect`) to subscribers via `on(event, fn)`. Run mechanism: `runTrial` / `runSequence` / `stop` / `running`; lifecycle: `connect` / `disconnect` / `connected` / `send`. Page-wide singleton via `ArenaSession.shared()`.
 - **Must stay a classic `<script src>` module** (window-global + CommonJS dual-export, **no bare ES `export`**), loaded AFTER `arena-wire-g6.js` / `arena-link.js` / `arena-runner-g6.js` and BEFORE any `<script type="module">` that reads `window.ArenaSession`. This keeps Connect/STOP/run-state alive even if a stale ES-module import fails (the catastrophic-cache gotcha) — never move connection ownership into the module block.
+- **Link lanes + read buffer (`js/arena-link.js`, 2026-10-07):** the port opens with a 1 MiB `bufferSize` (Chrome's 255-byte default loses bulk bytes or ends in "Break received" on macOS), and sends have two FIFO lanes: `{ background: true }` waits while any foreground send is queued. Connect-time sweeps and prefetches (GET_PATTERN_INFO frame counts, picker thumbnails) MUST use the background lane. Nothing on the wire is preempted, so a background bulk read must stay small (thumbnails: `PatPreview.liveFetchVerdict`, ≤ 1 MiB). A bulk body fails after `idleTimeoutMs` (5 s) without a byte instead of waiting out `timeoutMs`. Tests: `tests/test-arena-link.js`, `tests/test-studio-link-priority.js`.
 - Both `arena_console.html` and `experiment_designer_v3.html` use `window.ArenaSession.shared()` instead of constructing their own `ArenaLink` (the console uses only connect/send/events; the designer uses the run mechanism). On involuntary disconnect the broker calls `runner.abort()` (public, added to `arena-runner-g6.js`) — falling back to the legacy private `_clear()` to tolerate a stale-cache runner. Tests: `tests/test-arena-session.js` (`pixi run test` runs the full suite; run a single file with `pixi run node tests/test-arena-session.js`).
 
 **Pat-Parser Dual Export Pattern** (`js/pat-parser.js`):
diff --git a/arena_studio.html b/arena_studio.html
index 0cd898fb..04879d4a 100644
--- a/arena_studio.html
+++ b/arena_studio.html
@@ -7899,24 +7899,32 @@ <h2 id="modalTitle">Import error</h2>
 Studio.patternSet = null;
 const webPreviewBySdName = new Map(); // filename → () => Promise<ArrayBuffer>
 const repoSharedPreviewKeys = new Set(); // sources currently wired from course-repo patterns/
-// In-memory sources first (logical-name tolerant via webBytesForName). `idx`
-// (1-based SD index) is the fallback path: a pattern already on the card
-// from a prior session has no cached source above, so fetch it live via 0x84
-// — the controller's GET_PATTERN_FILE handler is chunked/non-blocking with a
-// bounded stall recovery (issue #16), so this is safe on fixed firmware (an
-// older controller can still wedge the link here). Same call the SD table's
-// Download button already makes.
-function patByteSource(sd, idx) {
-    const f = Studio.webBytesForName(sd);
+// In-memory sources first (logical-name tolerant via webBytesForName). The
+// fallback for a pattern already on the card from a prior session is a live
+// 0x84 fetch of the WHOLE file (the controller has no ranged read), gated by
+// PatPreview.liveFetchVerdict: size known from GET_PATTERN_INFO and ≤ 1 MiB, no
+// run active. It goes in the link's BACKGROUND lane, so a user command never
+// queues behind it (bench 2026-10-07: the connect-time auto-pick's fetch of
+// pattern 1 lost bytes and held the link for its 60 s timeout; TRIAL_PARAMS
+// waited 57 s). Resolves the ArrayBuffer, or null when no source is allowed;
+// `refusal` (optional out-param) gets the verdict reason.
+async function patByteSource(p, refusal) {
+    const f = Studio.webBytesForName(p.sd_name);
     if (f) return f();
-    if (!Studio.session || !Studio.session.connected || idx == null) {
-        return Promise.reject(new Error('no local copy of ' + sd));
+    const s = Studio.session;
+    const card = s && s.connected && p.index != null ? await cardPatternInfo(p).catch(() => null) : null;
+    const v = PP && typeof PP.liveFetchVerdict === 'function' // a stale cached pat-preview.js lacks it
+        ? PP.liveFetchVerdict(card, { connected: !!(s && s.connected) && p.index != null, running: !!(s && s.running) })
+        : { ok: false, reason: 'unknown-size' };
+    if (!v.ok) {
+        if (refusal) Object.assign(refusal, v, { fileSize: card && card.fileSize });
+        return null;
     }
-    return Studio.session
-        .sendBulkRead(Wire.encodeGetPatternFile(idx), { timeoutMs: 60000 })
-        .then((u8) => u8.buffer);
+    const u8 = await s.sendBulkRead(Wire.encodeGetPatternFile(p.index), { timeoutMs: 10000, background: true });
+    return u8.buffer;
 }
 let patPreviewCache = {};
+let patThumbSeq = 0; // renderPatThumb: only the newest pick draws (its fetch may finish late)
 
 // Autoplay a multi-frame pattern preview as a lightweight looping GIF: cycle the
 // sampled frames on an interval that SELF-CLEARS once the img leaves the DOM (a
@@ -8182,11 +8190,22 @@ <h2 id="modalTitle">Import error</h2>
     host.title = src || canFetchLive
         ? 'Pattern preview (multi-frame patterns animate automatically)'
         : 'No preview — connect to the controller for a live thumbnail, or upload the set / open its course-repo protocol';
+    const seq = ++patThumbSeq;
     try {
         let sampled = patPreviewCache[name];
         if (!sampled) {
             if (!src && !canFetchLive) return;
-            const ab = await patByteSource(p.sd_name, p.index);
+            const refusal = {};
+            const ab = await patByteSource(p, refusal);
+            if (seq !== patThumbSeq) return; // a newer pick owns the thumbnail
+            if (!ab) {
+                host.title = refusal.reason === 'too-large'
+                    ? 'No preview — ' + (refusal.fileSize / 1048576).toFixed(1) + ' MB on the card is too large to fetch over USB for a thumbnail; upload the set or open its course-repo protocol to preview it'
+                    : refusal.reason === 'running'
+                        ? 'No preview while a run is active'
+                        : 'No preview — the controller did not report this pattern’s size';
+                return;
+            }
             const parsed = PatParser.parsePatFile(ab);
             sampled = PP.samplePreviewFrames(parsed, arenaForConfig(m.arenaConfig), {
                 renderIcon: generatePatternIcon,
@@ -8198,13 +8217,20 @@ <h2 id="modalTitle">Import error</h2>
             // count — the closed-loop resolver reads this (patternFramesByName).
             p.preview = { frames: parsed.numFrames };
         }
+        if (seq !== patThumbSeq) return;
         if (!sampled.frames || !sampled.frames.length) return;
         const img = document.createElement('img');
         img.src = sampled.frames[sampled.staticIndex || 0];
         img.alt = name;
         host.appendChild(img);
         if (sampled.frames.length > 1) Studio.startPatAutoplay(img, sampled.frames, sampled.staticIndex || 0);
-    } catch (e) { /* preview is best-effort */ }
+    } catch (e) {
+        // Best-effort. The controller refuses 0x84 while a pattern is displaying
+        // (status 10, CE_DISPLAY_ACTIVE); nothing is cached, so the next pick after STOP retries.
+        if (seq === patThumbSeq && /status=10\b/.test((e && e.message) || '')) {
+            host.title = 'No preview while the display is running — stop it, then pick the pattern again to load its thumbnail';
+        }
+    }
 }
 // Register just-uploaded pattern bytes as picker preview sources, keyed by the
 // on-card filename (== the name we rename to via 0x83). Called by the classic
@@ -8319,12 +8345,32 @@ <h2 id="modalTitle">Import error</h2>
     Studio.updateRunGate(); // the missing-pattern preflight tracks the SD listing
     fillPatternFramesFromCard(m); // frame counts via GET_PATTERN_INFO (the closed-loop index modulus)
 };
-// Frame counts for every card pattern from GET_PATTERN_INFO 0x88 (a header read, ~ms each),
-// filled right after the listing so `patternFramesByName` — which the closed-loop resolver
-// pushes to the bridge as the heading→index modulus — is correct for patterns whose preview
-// was never rendered (an 8 MB pattern is never fetched for a thumbnail; the bridge then used
-// its default of 200 and wrapped the index — bench 2026-09-13, #201). Sequential, single-flight,
-// abandons on a new listing, a disconnect or a run (a run owns the link).
+// GET_PATTERN_INFO 0x88 for one card pattern (a header read, ~2 ms), cached on the listing
+// entry as p.card = { frames, fileSize }; also fills p.preview.frames, the closed-loop modulus.
+// Background lane: it never delays a user command. Null when unknown (old fw, read failed).
+function cardPatternInfo(p) {
+    if (p.card) return Promise.resolve(p.card);
+    if (p.cardReq) return p.cardReq; // the thumbnail and the sweep can ask at once
+    const W = window.ArenaWireG6;
+    const s = Studio.session;
+    if (!W || !W.encodeGetPatternInfo || !s || !s.connected || p.index == null) return Promise.resolve(null);
+    p.cardReq = s.send(W.encodeGetPatternInfo(p.index), { timeoutMs: 1500, silent: true, background: true })
+        .then((resp) => {
+            const info = W.decodePatternInfo(resp);
+            if (!info || !(info.frameCount > 0)) return null;
+            p.card = { frames: info.frameCount, fileSize: info.fileSize };
+            p.preview = Object.assign(p.preview || {}, { frames: info.frameCount });
+            return p.card;
+        })
+        .finally(() => { p.cardReq = null; });
+    return p.cardReq;
+}
+// Frame counts for every card pattern from GET_PATTERN_INFO 0x88, filled right after the
+// listing so `patternFramesByName` — which the closed-loop resolver pushes to the bridge as
+// the heading→index modulus — is correct for patterns whose preview was never rendered (a
+// large pattern is never fetched for a thumbnail; the bridge then used its default of 200
+// and wrapped the index — bench 2026-09-13, #201). Sequential in the link's background lane
+// (a user command goes first), abandons on a new listing, a disconnect or a run.
 let patFramesGen = 0;
 async function fillPatternFramesFromCard(m) {
     const gen = ++patFramesGen;
@@ -8335,8 +8381,7 @@ <h2 id="modalTitle">Import error</h2>
     for (const p of todo) {
         if (gen !== patFramesGen || !Studio.session.connected || Studio.session.running) return;
         try {
-            const info = W.decodePatternInfo(await Studio.session.send(W.encodeGetPatternInfo(p.index), { timeoutMs: 1500, silent: true }));
-            if (info && info.frameCount > 0) { p.preview = Object.assign(p.preview || {}, { frames: info.frameCount }); n++; }
+            if (await cardPatternInfo(p)) n++;
         } catch (_) { /* best effort: the preview path can still fill it later */ }
     }
     if (n && gen === patFramesGen) (Studio.clog || Studio.rawLog || function () {})('pattern frame counts read from the card for ' + n + ' pattern' + (n === 1 ? '' : 's') + ' (GET_PATTERN_INFO)', 'dim');
diff --git a/js/arena-link.js b/js/arena-link.js
index 4f47b5d8..7a2a88e6 100644
--- a/js/arena-link.js
+++ b/js/arena-link.js
@@ -29,6 +29,11 @@
  *   oldest pending await regardless of echo (fine for its one-shot button UI,
  *   too loose for the shared substrate the runner will build on).
  *
+ * Two lanes: a send with `{ background: true }` (connect-time sweeps, thumbnail
+ *   fetches) waits while any foreground send is queued, so a user command never
+ *   queues behind a sweep. FIFO within each lane. Nothing on the wire is
+ *   preempted: a request already in flight (a bulk read included) finishes first.
+ *
  * Gotchas (from the reference README — all still apply):
  *   - Web Serial is Chromium-only (Chrome / Edge / Opera / Brave / Arc) on a
  *     desktop OS. Firefox and Safari do NOT implement navigator.serial — gate
@@ -40,6 +45,11 @@
  *     115200 is a conventional placeholder.
  *   - Only one process can hold the port. Close pio device monitor / dwfpy /
  *     other terminals before connecting.
+ *   - open() asks for a 1 MiB read buffer (`bufferSize`). Chrome's default is
+ *     255 bytes, and with it a fast bulk stream (0x84 file / 0x8A archive) loses
+ *     bytes or ends in "Break received" on macOS: bench 2026-10-07, an 81 KB
+ *     pattern arrived 901 bytes short and the read waited out its timeout.
+ *     With 1 MiB the same file arrives complete in ~9 ms.
  *   - DEBUG_SERIAL firmware builds interleave diagnostic text on the same pipe;
  *     a stray byte is treated as a frame length and can stall the parser behind
  *     a bogus length. The single-flight timeout (which flushes the rx buffer) is
@@ -58,6 +68,8 @@ const ArenaLink = (function () {
 
     const DEFAULT_BAUD_RATE = 115200; // ignored by USB CDC; conventional placeholder
     const DEFAULT_TIMEOUT_MS = 500; // controller replies in well under 1 ms
+    const DEFAULT_BUFFER_SIZE = 1 << 20; // Web Serial read buffer (Chrome default 255 B loses bulk bytes)
+    const DEFAULT_BULK_IDLE_MS = 5000; // a bulk body that stops arriving for this long has lost bytes
     const HEX_LOG_LIMIT = 32; // truncate longer payloads in the trace log
 
     const hex = (bytes) =>
@@ -127,10 +139,12 @@ const ArenaLink = (function () {
             this._inflight = null;
             // Active bulk-read state (set while receiving raw bytes for 0x84). When
             // non-null, _consumeIncoming routes bytes here instead of frame-parsing.
-            // Shape: { remaining, chunks, resolve, reject, timer }
+            // Shape: { remaining, total, chunks, resolve, reject, timer, deadline, idleMs }
             this._bulkRead = null;
-            // Serializes concurrent send() callers into one-at-a-time requests.
-            this._sendQueue = Promise.resolve();
+            // Serializes concurrent send() callers into one-at-a-time requests:
+            // two FIFO lanes, the foreground one always served first (see _pump).
+            this._lanes = { fg: [], bg: [] };
+            this._busy = false;
 
             // Bind so add/removeEventListener share one reference.
             this._handleSerialDisconnect = this._handleSerialDisconnect.bind(this);
@@ -177,6 +191,7 @@ const ArenaLink = (function () {
          * Open the selected port and start the background reader.
          * @param {object} [opts]
          * @param {number} [opts.baudRate=115200]
+         * @param {number} [opts.bufferSize=1048576] Web Serial read buffer, bytes
          */
         async open(opts) {
             this._assertSupported();
@@ -186,7 +201,8 @@ const ArenaLink = (function () {
             if (this._connected) return;
 
             const baudRate = (opts && opts.baudRate) || DEFAULT_BAUD_RATE;
-            await this._port.open({ baudRate });
+            const bufferSize = (opts && opts.bufferSize) || DEFAULT_BUFFER_SIZE;
+            await this._port.open({ baudRate, bufferSize });
             // Remember the USB identity (VID/PID — all Web Serial exposes) so
             // reconnect() can find this device among the granted ports after a
             // firmware reset re-enumerates it.
@@ -316,19 +332,66 @@ const ArenaLink = (function () {
          * @param {number} [opts.expectedCmd] response echo_cmd to correlate on;
          *   defaults to bytes[1]. A stream frame ([0x32, len_lo, len_hi, ...])
          *   carries its opcode at byte 0 (byte 1 is a length), so pass 0x32.
+         * @param {boolean} [opts.background=false] queue in the background lane:
+         *   sent only when no foreground send is waiting (sweeps, prefetches).
          * @returns {Promise<Uint8Array>}
          */
         send(bytes, opts) {
-            // Chain onto the queue so only one request is in flight at a time.
-            // `run` fires whether the previous send resolved or rejected.
-            const run = () => this._sendOne(bytes, opts);
-            const result = this._sendQueue.then(run, run);
-            // Keep the queue tail from rejecting so the next send still chains.
-            this._sendQueue = result.then(
-                () => {},
-                () => {}
+            return this._enqueue(() => this._sendOne(bytes, opts), opts);
+        }
+
+        /**
+         * Requests not yet settled: { foreground, background } still queued and
+         * whether one is on the wire (`inFlight`). For diagnostics and tests.
+         */
+        get pending() {
+            return {
+                foreground: this._lanes.fg.length,
+                background: this._lanes.bg.length,
+                inFlight: this._busy
+            };
+        }
+
+        // Queue `run` (a () => Promise) in its lane; resolves/rejects with it.
+        _enqueue(run, opts) {
+            const lane = opts && opts.background ? this._lanes.bg : this._lanes.fg;
+            return new Promise((resolve, reject) => {
+                lane.push({ run, resolve, reject });
+                this._pump();
+            });
+        }
+
+        // Start the next queued request when none is in flight: foreground lane
+        // first, so a user command waits for at most the one request on the wire.
+        _pump() {
+            if (this._busy) return;
+            const job = this._lanes.fg.shift() || this._lanes.bg.shift();
+            if (!job) return;
+            this._busy = true;
+            // Settle the caller first and start the next request a microtask later,
+            // so a caller sees its reply before anything else goes on the wire (the
+            // order the old single promise chain gave).
+            const next = () =>
+                Promise.resolve().then(() => {
+                    this._busy = false;
+                    this._pump();
+                });
+            let p;
+            try {
+                p = Promise.resolve(job.run());
+            } catch (err) {
+                p = Promise.reject(err);
+            }
+            p.then(
+                (v) => {
+                    job.resolve(v);
+                    next();
+                },
+                (err) => {
+                    job.reject(err);
+                    next();
+                }
             );
-            return result;
         }
 
         /**
@@ -342,21 +405,19 @@ const ArenaLink = (function () {
          * @param {Uint8Array|number[]} bytes request frame
          * @param {object} [opts]
          * @param {number} [opts.timeoutMs=30000] applies to both header and data phases
+         * @param {number} [opts.idleTimeoutMs=5000] data phase: reject when no byte
+         *   arrives for this long (the stream lost bytes) instead of waiting out timeoutMs
+         * @param {boolean} [opts.background=false] queue in the background lane (see send)
          * @returns {Promise<Uint8Array>}
          */
         sendBulkRead(bytes, opts) {
-            const run = () => this._sendOneBulkRead(bytes, opts);
-            const result = this._sendQueue.then(run, run);
-            this._sendQueue = result.then(
-                () => {},
-                () => {}
-            );
-            return result;
+            return this._enqueue(() => this._sendOneBulkRead(bytes, opts), opts);
         }
 
         async _sendOneBulkRead(bytes, opts) {
             if (!this._writer) throw new Error('ArenaLink.sendBulkRead: not connected');
             const timeoutMs = (opts && opts.timeoutMs) || 30000;
+            const idleMs = (opts && opts.idleTimeoutMs) || DEFAULT_BULK_IDLE_MS;
             const payload = bytes instanceof Uint8Array ? bytes : Uint8Array.from(bytes);
             const expectedCmd = opts && opts.expectedCmd != null ? opts.expectedCmd : payload[1];
 
@@ -376,7 +437,7 @@ const ArenaLink = (function () {
                     resolve,
                     reject,
                     timer: null,
-                    bulkInit: { timeoutMs, dataResolve, dataReject }
+                    bulkInit: { timeoutMs, idleMs, dataResolve, dataReject }
                 };
                 entry.timer = setTimeout(() => {
                     if (this._inflight !== entry) return;
@@ -417,6 +478,7 @@ const ArenaLink = (function () {
             const take = Math.min(chunk.length, br.remaining);
             if (take > 0) br.chunks.push(chunk.slice(0, take));
             br.remaining -= take;
+            if (br.remaining > 0 && take > 0) this._armBulkTimer(br); // still arriving
             if (br.remaining <= 0) {
                 clearTimeout(br.timer);
                 this._bulkRead = null;
@@ -433,6 +495,37 @@ const ArenaLink = (function () {
             return take;
         }
 
+        // (Re)start the bulk body's timer: fire after `idleMs` without a byte
+        // (bytes were lost — fail fast, the queue behind it is waiting) or at the
+        // overall deadline, whichever comes first. Called on every chunk.
+        _armBulkTimer(br) {
+            clearTimeout(br.timer);
+            const left = Math.max(0, br.deadline - Date.now());
+            const stalled = left > br.idleMs;
+            br.timer = setTimeout(
+                () => {
+                    if (this._bulkRead !== br) return;
+                    this._bulkRead = null;
+                    this._rxBuf = new Uint8Array(0); // a partial body must not be read as frames
+                    const got = br.total - br.remaining;
+                    br.reject(
+                        new Error(
+                            stalled
+                                ? 'bulk-read data stalled: got ' +
+                                      got +
+                                      '/' +
+                                      br.total +
+                                      ' bytes, none for ' +
+                                      br.idleMs +
+                                      ' ms'
+                                : 'bulk-read data timeout: got ' + got + '/' + br.total + ' bytes'
+                        )
+                    );
+                },
+                stalled ? br.idleMs : left
+            );
+        }
+
         async _sendOne(bytes, opts) {
             if (!this._writer) throw new Error('ArenaLink.send: not connected');
             const timeoutMs = (opts && opts.timeoutMs) || DEFAULT_TIMEOUT_MS;
@@ -651,27 +744,20 @@ const ArenaLink = (function () {
                         entry.resolve(frame);
                         continue;
                     }
-                    // Set up bulk drain.
+                    // Set up bulk drain: overall deadline timeoutMs from now, and
+                    // an idle limit re-armed on every chunk (_armBulkTimer).
                     const bi = entry.bulkInit;
-                    const bulkTimer = setTimeout(() => {
-                        if (this._bulkRead) {
-                            const got = sz - this._bulkRead.remaining;
-                            this._bulkRead = null;
-                            bi.dataReject(
-                                new Error(
-                                    'bulk-read data timeout: got ' + got + '/' + sz + ' bytes'
-                                )
-                            );
-                        }
-                    }, bi.timeoutMs);
                     this._bulkRead = {
                         remaining: sz,
                         total: sz,
                         chunks: [],
                         resolve: bi.dataResolve,
                         reject: bi.dataReject,
-                        timer: bulkTimer
+                        timer: null,
+                        deadline: Date.now() + bi.timeoutMs,
+                        idleMs: bi.idleMs || DEFAULT_BULK_IDLE_MS
                     };
+                    this._armBulkTimer(this._bulkRead);
                     // Drain any file bytes that already arrived with the header frame.
                     const leftover = this._rxBuf;
                     this._rxBuf = new Uint8Array(0);
diff --git a/js/arena-session.js b/js/arena-session.js
index e20ad252..eb5f8e3a 100644
--- a/js/arena-session.js
+++ b/js/arena-session.js
@@ -345,9 +345,11 @@
          * ArenaWireG6.decodeResponse; do NOT slice). Queues FIFO behind any
          * in-flight send.
          * @param {Uint8Array|number[]} bytes
-         * @param {object} [opts] {expectedCmd?, timeoutMs?, silent?} — pass expectedCmd:0x32 for
-         *        STREAM_FRAME; `silent: true` skips the bridge command log (for meta traffic
-         *        such as the telemetry drain's 0xA9 requests, whose payload IS the log).
+         * @param {object} [opts] {expectedCmd?, timeoutMs?, silent?, background?} — pass
+         *        expectedCmd:0x32 for STREAM_FRAME; `silent: true` skips the bridge command
+         *        log (for meta traffic such as the telemetry drain's 0xA9 requests, whose
+         *        payload IS the log); `background: true` queues behind every foreground
+         *        send (connect-time sweeps, prefetches — see ArenaLink "Two lanes").
          * @returns {Promise<Uint8Array>}
          */
         send(bytes, opts) {
@@ -419,7 +421,7 @@
          * Bulk-read variant: send a request, then stream response chunks until
          * the controller signals EOF. See ArenaLink.sendBulkRead for details.
          * @param {Uint8Array|number[]} bytes
-         * @param {object} [opts] {timeoutMs?}
+         * @param {object} [opts] {timeoutMs?, idleTimeoutMs?, background?}
          * @returns {Promise<Uint8Array>}
          */
         sendBulkRead(bytes, opts) {
diff --git a/js/pat-preview.js b/js/pat-preview.js
index b1e9b6ad..41059fed 100644
--- a/js/pat-preview.js
+++ b/js/pat-preview.js
@@ -21,6 +21,27 @@
 
     var DEFAULT_MAX = 10;
     var DEFAULT_SIZE = 72;
+    // Largest card-only pattern a thumbnail may download over USB. The controller can
+    // only send the WHOLE file (GET_PATTERN_FILE 0x84, no ranged read), and nothing else
+    // can use the link while it streams (~10 MB/s), so a bigger file gets no thumbnail.
+    var LIVE_FETCH_MAX_BYTES = 1 << 20;
+
+    /**
+     * May a thumbnail download a card-only pattern over USB right now?
+     * @param info  GET_PATTERN_INFO decode for it ({ fileSize, … }) or null when unknown.
+     * @param state { connected, running } — a run owns the link.
+     * @returns { ok, reason } — reason ∈ 'offline' | 'running' | 'unknown-size' | 'too-large'.
+     */
+    function liveFetchVerdict(info, state) {
+        if (!state || !state.connected) return { ok: false, reason: 'offline' };
+        if (state.running) return { ok: false, reason: 'running' };
+        var size = info && info.fileSize;
+        if (typeof size !== 'number' || !isFinite(size) || size <= 0) {
+            return { ok: false, reason: 'unknown-size' };
+        }
+        if (size > LIVE_FETCH_MAX_BYTES) return { ok: false, reason: 'too-large' };
+        return { ok: true, reason: null };
+    }
 
     /**
      * Pick up to `max` evenly-spaced frame indices from a [0, numFrames) range.
@@ -139,6 +160,8 @@
     var PatPreview = {
         DEFAULT_MAX: DEFAULT_MAX,
         DEFAULT_SIZE: DEFAULT_SIZE,
+        LIVE_FETCH_MAX_BYTES: LIVE_FETCH_MAX_BYTES,
+        liveFetchVerdict: liveFetchVerdict,
         pickFrameIndices: pickFrameIndices,
         renderFlatFrame: renderFlatFrame,
         samplePreviewFrames: samplePreviewFrames
diff --git a/tests/test-arena-link.js b/tests/test-arena-link.js
index f59843e9..c47089b2 100644
--- a/tests/test-arena-link.js
+++ b/tests/test-arena-link.js
@@ -117,8 +117,9 @@ class FakePort {
         this.opened = false;
         this.closed = false;
     }
-    async open() {
+    async open(opts) {
         this.opened = true;
+        this.openOpts = opts;
     }
     async close() {
         this.closed = true;
@@ -175,6 +176,19 @@ const REQ_SPI = '01 c6';
 const RESP_INFO = Uint8Array.from([0x04, 0x00, 0xc2, 0x02, 0x11]); // echo 0xC2
 const RESP_SPI = Uint8Array.from([0x04, 0x00, 0xc6, 0x14, 0x00]); // echo 0xC6
 
+// GET_PATTERN_FILE (0x84) header frame [10, status 0, 0x84, size u64 LE] + a body.
+function fileHeader(size) {
+    const h = new Uint8Array(11);
+    h[0] = 10;
+    h[2] = 0x84;
+    h[3] = size & 0xff;
+    h[4] = (size >> 8) & 0xff;
+    h[5] = (size >> 16) & 0xff;
+    h[6] = (size >>> 24) & 0xff;
+    return h;
+}
+const fileBody = (n) => Uint8Array.from({ length: n }, (_, i) => i & 0xff);
+
 async function main() {
     console.log('=== feature detection ===');
     delete global.navigator;
@@ -361,6 +375,160 @@ async function main() {
         await link.close();
     }
 
+    console.log(
+        '\n=== open(): 1 MiB Web Serial read buffer (Chrome default 255 B loses bulk bytes) ==='
+    );
+    {
+        const { link, reader, port } = setup();
+        await link.connect();
+        checkBool(
+            'default bufferSize is 1 MiB',
+            port.openOpts && port.openOpts.bufferSize === 1 << 20,
+            JSON.stringify(port.openOpts)
+        );
+        checkBool('baudRate still passed', port.openOpts && port.openOpts.baudRate === 115200);
+        reader.cancel();
+        await link.close();
+    }
+    {
+        const { link, reader, port } = setup();
+        await link.connect({ bufferSize: 4096 });
+        checkBool('bufferSize override honored', port.openOpts.bufferSize === 4096);
+        reader.cancel();
+        await link.close();
+    }
+
+    console.log('\n=== bulk read (0x84): body across chunks, stall detection ===');
+    {
+        const { link, reader } = setup();
+        await link.connect();
+        const p = link.sendBulkRead(Wire.encodeGetPatternFile(1), { timeoutMs: 2000 });
+        await flush();
+        const body = fileBody(600);
+        const first = new Uint8Array(11 + 100);
+        first.set(fileHeader(600), 0);
+        first.set(body.subarray(0, 100), 11);
+        reader.push(first); // header + the first body bytes in one chunk
+        reader.push(body.subarray(100, 400));
+        reader.push(body.subarray(400));
+        const data = await p;
+        checkBool('bulk body reassembled', data.length === 600 && data[599] === body[599]);
+        reader.cancel();
+        await link.close();
+    }
+    {
+        // Bench 2026-10-07: the body arrived ~1 KB short and the read waited out its
+        // full timeout while every later command queued behind it.
+        const { link, reader } = setup();
+        await link.connect();
+        const t0 = Date.now();
+        const p = link.sendBulkRead(Wire.encodeGetPatternFile(1), {
+            timeoutMs: 5000,
+            idleTimeoutMs: 40
+        });
+        await flush();
+        reader.push(fileHeader(1000));
+        reader.push(fileBody(700)); // 300 bytes never come
+        await checkRejects('short body rejects as stalled', p, /stalled: got 700\/1000 bytes/);
+        checkBool('rejected at the idle limit, not the 5 s timeout', Date.now() - t0 < 1000);
+        // The queue is free again: the next command goes out and resolves.
+        const q = link.send(Wire.encodeGetControllerInfo());
+        await flush();
+        reader.push(RESP_INFO);
+        checkBytes('next command works after a stalled bulk read', await q, '04 00 c2 02 11');
+        reader.cancel();
+        await link.close();
+    }
+    {
+        // A slow but steady stream that outlasts the idle limit still completes.
+        const { link, reader } = setup();
+        await link.connect();
+        const p = link.sendBulkRead(Wire.encodeGetPatternFile(1), {
+            timeoutMs: 5000,
+            idleTimeoutMs: 40
+        });
+        await flush();
+        reader.push(fileHeader(500));
+        for (let i = 0; i < 5; i++) {
+            await flush(25); // 5 × 25 ms > the 40 ms idle limit in total
+            reader.push(fileBody(100));
+        }
+        const data = await p.catch((e) => e);
+        checkBool('steady slow body completes', data instanceof Uint8Array && data.length === 500);
+        reader.cancel();
+        await link.close();
+    }
+
+    console.log('\n=== background lane: user commands go first ===');
+    {
+        const { link, reader, writer } = setup();
+        await link.connect();
+        const order = [];
+        const b1 = link.send(Wire.encodeGetPatternInfo(1), { background: true });
+        const b2 = link.send(Wire.encodeGetPatternInfo(2), { background: true });
+        const b3 = link.send(Wire.encodeGetPatternInfo(3), { background: true });
+        await flush();
+        checkBool('background request goes out when idle', writer.writes.length === 1);
+        checkBool(
+            'two background requests wait',
+            link.pending.background === 2 && link.pending.inFlight,
+            JSON.stringify(link.pending)
+        );
+        const fg = link.send(Wire.encodeGetSpiClock()); // the user's command
+        const reply88 = (i) => [0x0e, 0x00, 0x88, i, 0, 2, 2, 10, 0, 0, 0, 0, 0, 0, 0];
+        reader.push(reply88(1)); // finishes the in-flight background request
+        await b1;
+        await flush();
+        checkBytes('the user command jumps the background queue', writer.writes[1], REQ_SPI);
+        reader.push(RESP_SPI);
+        await fg;
+        await flush();
+        reader.push(reply88(2));
+        await b2;
+        await flush();
+        reader.push(reply88(3));
+        await b3;
+        writer.writes.forEach((w) => order.push(w[1].toString(16) + (w[2] ? ':' + w[2] : '')));
+        checkBool(
+            'then the background lane resumes in order',
+            order.join(' ') === '88:1 c6 88:2 88:3',
+            order.join(' ')
+        );
+        reader.cancel();
+        await link.close();
+    }
+    {
+        // A failed background request does not stall the queue.
+        const { link, reader } = setup();
+        await link.connect();
+        const b = link.send(Wire.encodeGetPatternInfo(1), { background: true, timeoutMs: 20 });
+        const f = link.send(Wire.encodeGetControllerInfo());
+        await checkRejects('background request times out', b, /timeout/);
+        await flush();
+        reader.push(RESP_INFO);
+        checkBytes('queued foreground request still runs', await f, '04 00 c2 02 11');
+        reader.cancel();
+        await link.close();
+    }
+    {
+        // Callers see their reply before the next queued request is written.
+        const { link, reader, writer } = setup();
+        await link.connect();
+        let writesAtResolve = -1;
+        const p1 = link.send(Wire.encodeGetControllerInfo()).then(() => {
+            writesAtResolve = writer.writes.length;
+        });
+        const p2 = link.send(Wire.encodeGetSpiClock()).catch(() => {}); // close() rejects it
+        await flush();
+        reader.push(RESP_INFO);
+        await p1;
+        checkBool('next request not yet written when the caller resumes', writesAtResolve === 1);
+        reader.push(RESP_SPI);
+        await p2;
+        reader.cancel();
+        await link.close();
+    }
+
     console.log('\n=== reconnect(): granted-port reopen without a gesture (fw #50 recovery) ===');
     {
         // Same port still valid (no re-enumeration): reopen it.
diff --git a/tests/test-pat-preview.js b/tests/test-pat-preview.js
index 0107c532..eecd7e88 100644
--- a/tests/test-pat-preview.js
+++ b/tests/test-pat-preview.js
@@ -129,6 +129,35 @@ checkBool(
     PP.renderFlatFrame(new Uint8Array(10), 2, 5, 2, 64) === null
 );
 
+// ── 5. liveFetchVerdict: when a thumbnail may download a card-only pattern ────────
+// The controller sends only whole files (0x84) and nothing else can use the link
+// meanwhile, so: size must be known and ≤ 1 MiB, connected, no run active.
+console.log('\n=== liveFetchVerdict ===');
+const idle = { connected: true, running: false };
+check('LIVE_FETCH_MAX_BYTES is 1 MiB', PP.LIVE_FETCH_MAX_BYTES, 1 << 20);
+check(
+    '81 KB color grating (bench pattern 1) → ok',
+    PP.liveFetchVerdict({ fileSize: 81338 }, idle),
+    {
+        ok: true,
+        reason: null
+    }
+);
+check('exactly the cap → ok', PP.liveFetchVerdict({ fileSize: 1 << 20 }, idle).ok, true);
+check('8 MB pattern → too-large', PP.liveFetchVerdict({ fileSize: 8e6 }, idle).reason, 'too-large');
+check('size unknown → refused', PP.liveFetchVerdict(null, idle).reason, 'unknown-size');
+check('size 0 → refused', PP.liveFetchVerdict({ fileSize: 0 }, idle).reason, 'unknown-size');
+check(
+    'run active → refused (a run owns the link)',
+    PP.liveFetchVerdict({ fileSize: 1000 }, { connected: true, running: true }).reason,
+    'running'
+);
+check(
+    'not connected → offline',
+    PP.liveFetchVerdict({ fileSize: 1000 }, { connected: false }).reason,
+    'offline'
+);
+
 console.log('\n=== Summary ===');
 console.log(`${totalChecks - failures} / ${totalChecks} checks passed`);
 process.exit(failures === 0 ? 0 : 1);
diff --git a/tests/test-studio-link-priority.js b/tests/test-studio-link-priority.js
new file mode 100644
index 00000000..8474486d
--- /dev/null
+++ b/tests/test-studio-link-priority.js
@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * Arena Studio connect-time traffic must never queue ahead of a user command.
+ *
+ * Bench 2026-10-07 (rig cshl_g6_2x10_ball, 24 patterns on the card): the first
+ * TRIAL_PARAMS after Connect was acknowledged 57 s late. The SD listing auto-picks
+ * pattern 1 and the picker thumbnail downloaded the whole file (0x84); with
+ * Chrome's default 255-byte Web Serial buffer the body arrived 901 bytes short,
+ * and the single-flight link waited out the read's 60 s timeout with the
+ * GET_PATTERN_INFO sweep and the user's command queued behind it.
+ *
+ * The transport half (1 MiB bufferSize, bulk stall timeout, background lane) is
+ * tested in tests/test-arena-link.js; this file pins the Studio call sites to it.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const studio = fs.readFileSync(path.join(__dirname, '..', 'arena_studio.html'), 'utf8');
+
+let totalChecks = 0;
+let failures = 0;
+function check(name, ok, detail) {
+    totalChecks++;
+    console.log(`  ${ok ? 'PASS' : 'FAIL'}  ${name}${!ok && detail ? ' — ' + detail : ''}`);
+    if (!ok) failures++;
+}
+// Source of a top-level function in the module block, up to the next top-level one.
+function fnBody(signature) {
+    const a = studio.indexOf(signature);
+    if (a < 0) return '';
+    const b = studio
+        .slice(a + signature.length)
+        .search(/\n(?:async )?function |\nlet |\nconst |\nStudio\./);
+    return b < 0 ? studio.slice(a) : studio.slice(a, a + signature.length + b);
+}
+
+console.log('=== GET_PATTERN_INFO sweep (closed-loop frame counts, #201) ===');
+const info = fnBody('function cardPatternInfo(p)');
+check('cardPatternInfo found', info.length > 0);
+check(
+    '0x88 goes in the background lane',
+    /encodeGetPatternInfo\(p\.index\)[^)]*background: true/.test(info)
+);
+check(
+    'caches frames + file size on the entry',
+    /p\.card = \{ frames: info\.frameCount, fileSize: info\.fileSize \}/.test(info)
+);
+check(
+    'keeps preview.frames, the closed-loop modulus',
+    /p\.preview = Object\.assign\(p\.preview \|\| \{\}, \{ frames: info\.frameCount \}\)/.test(info)
+);
+const sweep = fnBody('async function fillPatternFramesFromCard(m)');
+check('sweep found', sweep.length > 0);
+check('sweep reads through cardPatternInfo', /await cardPatternInfo\(p\)/.test(sweep));
+check('sweep sends no foreground 0x88 of its own', !/session\.send\(/.test(sweep));
+check('sweep still stops for a run', /Studio\.session\.running\) return/.test(sweep));
+
+console.log('\n=== picker thumbnail live fetch ===');
+const src = fnBody('async function patByteSource(p, refusal)');
+check('patByteSource found', src.length > 0);
+check('in-memory sources first', /Studio\.webBytesForName\(p\.sd_name\)/.test(src));
+check(
+    'gated by PatPreview.liveFetchVerdict (size known, ≤ 1 MiB, no run)',
+    /PP\.liveFetchVerdict\(card,/.test(src)
+);
+check(
+    '0x84 goes in the background lane',
+    /encodeGetPatternFile\(p\.index\), \{[^}]*background: true/.test(src)
+);
+check('no 60 s thumbnail fetch', !/timeoutMs: 60000/.test(src));
+const thumb = fnBody('async function renderPatThumb(name)');
+check('renderPatThumb found', thumb.length > 0);
+check('only the newest pick draws', (thumb.match(/seq !== patThumbSeq/g) || []).length >= 2);
+check(
+    'no other live 0x84 fetch in the picker/preview code',
+    (studio.match(/sendBulkRead\(Wire\.encodeGetPatternFile\(/g) || []).length === 2,
+    'expected exactly patByteSource + the SD table Download button'
+);
+
+console.log(`\n=== Summary ===\n${totalChecks - failures} / ${totalChecks} checks passed`);
+process.exit(failures > 0 ? 1 : 0);

From 564fecdd1dce8cbfd1148b2cc5bcf653cb7a20bb Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Mon, 12 Oct 2026 16:17:41 -0400
Subject: [PATCH 10/17] =?UTF-8?q?feat(studio):=20Console=20=E2=86=92=20Qwi?=
 =?UTF-8?q?ic=20=E2=80=94=20scan,=20identify=20and=20test=20the=20Qwiic=20?=
 =?UTF-8?q?peripherals=20(LAB-214,=20Studio=20v0.96)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- js/arena-wire-g6.js: GET_I2C_SCAN 0xB0 / I2C_TRANSFER 0xB1 encoders + decoders
  (status text, "No Qwiic jack" detection) with golden tests.
- js/qwiic-drivers.js (new): host register maps ported from the firmware repo's
  tests/qwiic_sensors.py + qwiic_peripherals.py — SHT4x (two-leg read, CRC),
  LSM6DSOX (tilt, latched bump: LIR + INT_CLR_ON_READ + INT1 routing), TSL2591,
  VEML7700, AS7343 (releases the bus while integrating), PCA9685 (ALLCALL off,
  servo pulse), PCA9548; an async bus mutex; all-call shadow decided from MODE1;
  the KINDS registry is the one place to add or drop a part.
- js/studio-qwiic.js (new): rig `peripherals:` parser (tolerant, warnings), the
  scan-vs-YAML check in both directions (declared-but-missing = error,
  attached-but-undeclared = warning), setup, chip, "Copy as rig YAML".
- arena_studio.html: one Console "Qwiic" window (Scan → device dropdown → one
  device's readout in display units; bump check; servo go-to-position), a
  connect-time setup scan and a top-bar chip. Every I2C command is gated on the
  0xC2 qwiic_i2c feature bit: controllers without the jack are never sent any.
  Test only — nothing is written to run logs (that is PR 2).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 arena_studio.html                             |  684 ++++++++-
 .../development/arena-studio-release-notes.md |    7 +
 js/arena-wire-g6.js                           |   92 ++
 js/qwiic-drivers.js                           | 1230 +++++++++++++++++
 js/studio-qwiic.js                            |  608 ++++++++
 tests/test-arena-wire-g6.js                   |   83 ++
 tests/test-qwiic-drivers.js                   |  555 ++++++++
 tests/test-studio-analog-in.js                |    2 +-
 tests/test-studio-qwiic.js                    |  520 +++++++
 tests/test-studio-shell.js                    |    2 +-
 10 files changed, 3775 insertions(+), 8 deletions(-)
 create mode 100644 js/qwiic-drivers.js
 create mode 100644 js/studio-qwiic.js
 create mode 100644 tests/test-qwiic-drivers.js
 create mode 100644 tests/test-studio-qwiic.js

diff --git a/arena_studio.html b/arena_studio.html
index 0cd898fb..9bdec4b7 100644
--- a/arena_studio.html
+++ b/arena_studio.html
@@ -213,6 +213,13 @@
   .rig-tag{font-size:11px;color:var(--dim);border:1px solid var(--border);border-radius:20px;padding:2px 8px;white-space:nowrap;cursor:pointer;max-width:220px;overflow:hidden;text-overflow:ellipsis}
   .rig-tag:hover{border-color:var(--accent);color:var(--text)}
   .chip.rig-mismatch{color:var(--warn);border-color:var(--warn);background:color-mix(in srgb,var(--warn) 8%,transparent);cursor:help}
+  /* Qwiic chip (LAB-214): shown only on controllers with the I2C bridge; click → Console → Qwiic */
+  .chip.qwiic-chip{cursor:pointer}
+  body:not(.hasproto) .chip.qwiic-chip{display:inline-block} /* bench state, not protocol state: shown with no protocol loaded (inline display:none still hides it) */
+  .chip.qw-ok{color:var(--accent);border-color:var(--accent);background:color-mix(in srgb,var(--accent) 8%,transparent)}
+  .chip.qw-warn{color:var(--warn);border-color:var(--warn);background:color-mix(in srgb,var(--warn) 8%,transparent)}
+  .chip.qw-err{color:var(--danger);border-color:var(--danger);background:color-mix(in srgb,var(--danger) 8%,transparent)}
+  .chip.qw-off{color:var(--dim);border-color:var(--border)}
   .doc-name{font-family:var(--head);font-weight:700;font-size:12.5px;white-space:nowrap}
   .chip{font-family:var(--mono);font-size:11px;font-weight:600;border-radius:20px;padding:2px 8px;border:1px solid;white-space:nowrap}
   .chip.saved{color:var(--accent);border-color:var(--accent);background:color-mix(in srgb,var(--accent) 8%,transparent)}
@@ -2229,6 +2236,21 @@
   .console-view .ai-range{font-size:10px;color:var(--dim);min-width:130px}
   .console-view #cAiChart{display:block;width:100%;max-width:460px;height:90px;border:1px solid var(--border);border-radius:4px;background:var(--chart-bg)}
   .console-view .ai-table{font-size:10.5px;border-collapse:collapse}
+  /* Qwiic panel (LAB-214): scan table, one-device readout grid, AS7343 spectrum bars */
+  .console-view .qw-table td,.console-view .qw-table th{padding:2px 8px 2px 0;text-align:left;vertical-align:top}
+  .console-view .qw-flags{font-size:11px;line-height:1.5}
+  .console-view .qw-out{display:block}
+  .console-view .qw-title{font-family:var(--head);font-size:12px;margin-bottom:4px}
+  .console-view .qw-grid{display:grid;grid-template-columns:max-content max-content;gap:2px 14px;align-items:baseline}
+  .console-view .qw-l{color:var(--dim);font-size:11px}
+  .console-view .qw-v{font-family:var(--head);font-size:15px;color:var(--text)}
+  .console-view .qw-bars{grid-column:1 / -1;display:flex;gap:3px;align-items:flex-end;height:74px;margin-top:4px}
+  .console-view .qw-bar{display:flex;flex-direction:column;align-items:center;justify-content:flex-end;height:100%;width:26px}
+  .console-view .qw-bar i{display:block;width:16px;background:var(--accent);opacity:.85;border-radius:2px 2px 0 0}
+  .console-view .qw-bar span{font-size:9px;color:var(--dim);margin-top:2px}
+  .qw-ok-t{color:var(--accent)}
+  .qw-warn-t{color:var(--warn)}
+  .qw-err-t{color:var(--danger)}
   .console-view .ai-table td,.console-view .ai-table th{padding:1px 10px 1px 0;text-align:right;color:var(--text);font-family:var(--mono)}
   .console-view .ai-table th{color:var(--dim);font-weight:normal}
   .console-view .ai-table td.bad{color:var(--danger-text)}
@@ -2254,6 +2276,7 @@
     .console-view .stage>.panel[data-panel="fw"]{order:7}
     .console-view .stage>.panel[data-panel="ai"]{order:8}
     .console-view .stage>.panel[data-panel="fictrac"]{order:9}
+    .console-view .stage>.panel[data-panel="qwiic"]{order:10}
   }
   /* Outer panel box: soft near-white 1.5px edge so panels stay distinct on a
      dark monitor in a lit room (grey var(--border) washed out). Internal
@@ -2356,6 +2379,7 @@
   <span class="rig-tag" id="rigTag" role="button" tabindex="0" title="Bench rig — click to see or change it in ⚙ Settings">rig —</span>
   <span class="chip rig-mismatch" id="rigMismatch" style="display:none" title="Session (bench) rig differs from the loaded protocol's rig: field — the bench geometry wins for Console/stream operations; the protocol still runs with its own rig. Unlock the rig selector in ⚙ Settings to reconcile, or load a matching protocol.">⚠ bench ≠ protocol</span>
   <span class="chip rig-mismatch" id="benchMacChip" style="display:none" title="The connected controller's MAC (0xC2) does not match the course roster's entry for this bench id — the wrong bench id would namespace saves/run-logs under another bench. See instructor.">⚠ bench ≠ roster</span>
+  <span class="chip qwiic-chip qw-off" id="qwiicChip" style="display:none" role="button" tabindex="0" title="Qwiic peripherals: the connect-time scan compared with the rig YAML. Click: open Console → Qwiic">Qwiic</span>
   <!-- v6 top-bar diet: device line hidden (arena+fw now on the status-dot
        hover); still written by updateDeviceLine so nothing depends on absence. -->
   <span class="arena" id="deviceLine" hidden><b>—</b></span>
@@ -3068,6 +3092,7 @@ <h2 id="modalTitle">Import error</h2>
         <div class="rail-btn sel" data-panel="test" role="checkbox" tabindex="0" aria-checked="true" title="Test figures + one-off frames">Test display<span class="sub">GS16</span></div>
         <div class="rail-btn" data-panel="io" role="checkbox" tabindex="0" aria-checked="false" title="Analog / digital BNCs on the controller">I/O<span class="sub" id="cIoSum">AO – · DIO –</span></div>
         <div class="rail-btn" data-panel="ai" role="checkbox" tabindex="0" aria-checked="false" title="Live readout of both 'Analog In (±10V)' BNCs — preview at up to 10 Hz, min/max, strip chart, and the Analog Out → Analog In loopback self-test">Analog In<span class="sub" id="cAiSum">AI1 – · AI2 –</span></div>
+        <div class="rail-btn" data-panel="qwiic" role="checkbox" tabindex="0" aria-checked="false" title="Qwiic / STEMMA QT jack — scan the I2C bus, pick one device, see its readings; servo go-to-position. Test only (nothing logged).">Qwiic<span class="sub" id="cQwSum">—</span></div>
         <div class="rail-btn sel" data-panel="led" role="checkbox" tabindex="0" aria-checked="true" title="Stimulus LED — set brightness % or turn off (BuckPuck on Analog Out)">LED<span class="sub">BuckPuck</span></div>
         <div class="rail-btn" data-panel="fw" role="checkbox" tabindex="0" aria-checked="false" title="Program the panels’ firmware">Panel firmware<span class="sub" id="cFwSum">flash · verify</span></div>
         <div class="rail-btn sel" data-panel="fictrac" role="checkbox" tabindex="0" aria-checked="true" title="Closed loop from the FicTrac bridge">FicTrac<span class="sub" id="cFtSum">ws · idle</span></div>
@@ -3220,6 +3245,47 @@ <h2 id="modalTitle">Import error</h2>
           </div>
         </section>
 
+        <section class="panel" data-panel="qwiic">
+          <div class="panel-h"><span class="panel-title" title="GET_I2C_SCAN 0xB0 · I2C_TRANSFER 0xB1 — the Qwiic / STEMMA QT jack (arena_12-18 J2, 0xC2 feature bit 1). All sensor logic is host-side (js/qwiic-drivers.js). Explore/test only: nothing in this panel is written to run logs.">Qwiic</span><span class="spacer"></span><span class="dim" id="cQwStatus" title="Panel state — reads pause by themselves while a run is active or the link is down">connect to scan</span><span class="panel-x" data-close="qwiic" role="button" title="Collapse to the rail (live readout keeps its state)">✕</span></div>
+          <div class="panel-b">
+          <div class="crow"><span class="lbl" title="The I2C bus behind the Qwiic jack">bus</span>
+            <button class="pill" data-cmd="cqwscan" title="Scan the Qwiic bus (GET_I2C_SCAN 0xB0), map any PCA9548 mux, identify every supported part and compare with the session rig's peripherals: list. Refused during a run — the scan stalls the controller ~10 ms.">Scan</button>
+            <button class="pill" id="cQwYaml" data-cmd="cqwyaml" disabled title="Copy a rig YAML peripherals: snippet for what the scan found (only the undeclared devices when the rig already declares some) — paste it into configs/rigs/&lt;rig&gt;.yaml">Copy as rig YAML</button>
+            <span class="dim" id="cQwScanSum" title="Addresses that ACKed the last scan"></span></div>
+          <div class="crow qw-flags" id="cQwFlags" style="display:none"></div>
+          <div class="crow" id="cQwTableRow" style="display:none"><table class="ai-table qw-table" id="cQwTable"></table></div>
+          <div class="crow"><span class="lbl" title="One device at a time">device</span>
+            <select id="cQwDev" disabled title="Devices found and identified by the last scan — pick one to see its readings"><option value="">— scan first —</option></select>
+            <button class="pill" data-cmd="cqwread" title="Read the selected device once (configures it first if needed)">Read</button>
+            <button class="pill" id="cQwLive" data-cmd="cqwlive" aria-pressed="false" title="Start / stop a live readout of the selected device at the chosen rate; pauses by itself during a run">Live</button>
+            <label title="Live readout rate (Console preview only)">rate <select id="cQwRate"><option value="1">1 Hz</option><option value="2">2 Hz</option><option value="0.5">0.5 Hz</option></select></label>
+            <button class="pill" id="cQwCsv" data-cmd="cqwcsv" disabled title="Download the readings collected in this session for the selected device as CSV (a Console scratch file — not a run log)">Download CSV</button></div>
+          <div class="crow" id="cQwOpts" style="display:none"></div>
+          <div class="crow qw-out" id="cQwOut"><span class="dim">Scan to list the devices on the Qwiic jack</span></div>
+          <div class="crow" id="cQwBump" style="display:none"><span class="lbl" title="LSM6DSOX wake-up detector as a latched 'bumped since last check' flag">bump</span>
+            <label title="Wake-up threshold in g: 0.05–2 (resolution 31 mg at ±2 g)">threshold <input id="cQwBumpG" type="number" min="0.05" max="2" step="0.05" value="0.25" style="width:58px"> g</label>
+            <button class="pill" data-cmd="cqwbumparm" title="Arm the latched bump flag (LIR + INT_CLR_ON_READ + INT1 routing) at this threshold">Arm</button>
+            <button class="pill" data-cmd="cqwbumpcheck" title="Read the bump flag — this CLEARS the latch (it is read-to-clear). Disabled during runs: the run's trial logger owns it.">Check (clears)</button>
+            <span class="dim" id="cQwBumpOut"></span> <span class="dim" id="cQwBumpNote"></span></div>
+          <div id="cQwServo" style="display:none">
+            <div class="crow"><span class="lbl" title="PCA9685 servo driver (e.g. SparkFun Servo pHAT)">servo</span>
+              <select id="cQwSvCh" title="PWM channel 0–15 (named channels come from the rig YAML channels:)"></select>
+              <input id="cQwSvUs" type="range" min="1000" max="2000" step="10" value="1500" style="width:140px" title="Pulse width in µs — releasing the slider moves the servo">
+              <input id="cQwSvNum" type="number" min="1000" max="2000" step="10" value="1500" style="width:64px" title="Pulse width in µs (clamped to the channel's limits)"><span class="dim">µs</span>
+              <span class="dim" id="cQwSvLim" title="Allowed pulse range for this channel">1000–2000 µs</span>
+              <label title="Widen the range to 500–2500 µs (asks first — many servos stall at their end stops)"><input type="checkbox" id="cQwSvWide"> wide</label></div>
+            <div class="crow"><span class="lbl"></span>
+              <button class="pill" data-cmd="cqwsvgo" title="Move the selected channel to the pulse width above (configures 50 Hz PWM on first use) and read the count back">Go</button>
+              <button class="pill" data-cmd="cqwsvcenter" title="Move to the middle of the channel's range (1500 µs by default)">Center</button>
+              <button class="pill" data-cmd="cqwsvrelease" title="Release the selected channel (full OFF — the servo goes limp, no holding torque)">Release</button>
+              <button class="pill" data-cmd="cqwsvalloff" title="Release all 16 channels">All off</button>
+              <span class="dim" id="cQwSvOut"></span></div>
+            <div class="crow"><span class="dim" style="font-size:10.5px">Power: the servo rail and the PCA9685 logic come from the board's own supply (the Servo pHAT's USB-C), never the Qwiic 3.3 V. Unpowered, the board is simply absent from the scan.</span></div>
+          </div>
+          <div class="crow" style="margin-bottom:0"><span class="dim" style="font-size:10.5px">Test only — readings here are not written to run logs. Declare devices in the rig YAML (peripherals:) for run logging; Copy as rig YAML gives you the entries.</span></div>
+          </div>
+        </section>
+
         <section class="panel open" data-panel="led">
           <div class="panel-h"><span class="panel-title" title="Stimulus LED via the BuckPuck driver on the 'Analog Out (0-5V)' BNC (0xA0). Power % maps to control voltage (mV); OFF = 5000 mV dark.">LED</span><span class="spacer"></span><span class="panel-x" data-close="led" role="button" title="Collapse to the rail">✕</span></div>
           <div class="panel-b">
@@ -3344,7 +3410,7 @@ <h2 id="modalTitle">Import error</h2>
 </div>
 
 <footer id="footer">
-  <span class="foot-left">Arena Studio v0.94 | 2026-09-30 07:22 ET · <a href="https://github.com/reiserlab/webDisplayTools" target="_blank" rel="noopener" title="webDisplayTools on GitHub: source, issues, and release notes (docs/development/arena-studio-release-notes.md)">GitHub</a></span>
+  <span class="foot-left">Arena Studio v0.96 | 2026-10-12 16:08 ET · <a href="https://github.com/reiserlab/webDisplayTools" target="_blank" rel="noopener" title="webDisplayTools on GitHub: source, issues, and release notes (docs/development/arena-studio-release-notes.md)">GitHub</a></span>
   <!-- Course-repo quick-links: open protocols / logs / patterns in a new tab.
        Hrefs built from the configured repo + bench id (updateGhQuickLinks). -->
   <span id="ghQuickLinks" title="Open the course repo on GitHub (new tab)">
@@ -3359,9 +3425,11 @@ <h2 id="modalTitle">Import error</h2>
 <!-- ============================================================ -->
 <!-- (1) CLASSIC SUBSTRATE — window globals, dodges ES-import gotcha -->
 <!-- ============================================================ -->
-<script src="js/arena-wire-g6.js"></script>
+<script src="js/arena-wire-g6.js?v=20261012-qwiic"></script> <!-- ?v=: the Qwiic panel needs the 0xB0/0xB1 encoders -->
 <script src="js/studio-analog-in.js"></script>
 <script src="js/studio-panel-inventory.js"></script>
+<script src="js/qwiic-drivers.js"></script>
+<script src="js/studio-qwiic.js"></script>
 <script src="js/arena-link.js"></script>
 <script src="js/arena-runner-g6.js?v=20260926-cl-start"></script> <!-- ?v= forces a fresh load: a cached runner/client silently runs the old closed-loop start -->
 <script src="js/run-log.js"></script>
@@ -5988,6 +6056,564 @@ <h2 id="modalTitle">Import error</h2>
         const rateSel = $('cAiRate');
         if (rateSel) rateSel.addEventListener('change', aiStartTicker);
     }
+    // ---- Qwiic panel: discover + test the STEMMA QT / Qwiic peripherals (LAB-214) ----
+    // ONE window: Scan → device dropdown → one device's readout at a time. Explore
+    // only: nothing here is written to run logs (declare devices in the rig YAML for
+    // that). Every transfer goes through the ONE page-wide QwiicDrivers bus
+    // (Studio.qwiicBus) so its mutex orders whole sequences against every other I2C
+    // user; session.send directly with silent:true (no per-transfer Console/bridge
+    // logging — state changes and errors are logged). Scan only at setup (connect,
+    // this button): GET_I2C_SCAN stalls the controller ~10 ms, so it is refused
+    // while a run is active.
+    const QD = window.QwiicDrivers;
+    const SQ = window.StudioQwiic;
+    const qw = {
+        bus: null,
+        discovery: null,
+        check: null,
+        declared: { list: [], warnings: [] },
+        configured: {}, // locKey → options applied by this panel / setup
+        selKey: null,
+        live: false,
+        liveTimer: null,
+        inFlight: false,
+        errStreak: 0,
+        rows: {}, // locKey → [{t, values}] for Download CSV
+        busy: false
+    };
+    function qwBus() {
+        if (!QD) return null;
+        if (!qw.bus) qw.bus = QD.createBus((b, o) => session.send(b, o), { sendOpts: { silent: true } });
+        return qw.bus;
+    }
+    Studio.qwiicBus = qwBus;
+    const qwHas = () => Array.isArray(Studio.features) && Studio.features.includes('qwiic_i2c');
+    const qwHex = (a) => '0x' + a.toString(16).toUpperCase().padStart(2, '0');
+    const qwEsc = (t) => String(t).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
+    function qwGate(what) {
+        if (!QD || !SQ) return { ok: false, reason: 'Qwiic modules failed to load (hard refresh)' };
+        if (!session || !session.connected) return { ok: false, reason: 'connect to scan' };
+        if (!Array.isArray(Studio.features)) return { ok: false, reason: 'controller features not known yet' };
+        if (!qwHas()) return { ok: false, reason: 'no Qwiic I2C bridge on this controller (0xC2 feature bit 1 clear — arena_12-18 boards only)' };
+        if (session.running) return { ok: false, reason: what === 'scan' ? 'refused — a run is active (the scan stalls the controller ~10 ms)' : 'paused — run active' };
+        if (Studio._activePostmortem) return { ok: false, reason: 'paused — post-mortem owns the link' };
+        return { ok: true };
+    }
+    function qwSetStatus(t) {
+        const el = $('cQwStatus');
+        if (el) el.textContent = t;
+    }
+    function qwItem(key) {
+        return qw.discovery && qw.discovery.devices.find((d) => d.key === key);
+    }
+    function qwDeclFor(item) {
+        const e = qw.check && qw.check.entries.find((x) => x.item && x.item.key === item.key);
+        return e ? e.decl : null;
+    }
+    function qwIsUndeclared(item) {
+        return !!(qw.check && qw.check.undeclared.some((u) => u.key === item.key));
+    }
+    function qwRenderChip() {
+        const st = Studio.qwiic || { available: false };
+        const chip = SQ ? SQ.chipState(st) : { text: 'Qwiic —', level: 'off', title: '' };
+        const el = $('qwiicChip');
+        if (el) {
+            const show = !!(session && session.connected && st.available) || (st.declared && st.declared.length && session && session.connected);
+            el.style.display = show ? '' : 'none';
+            el.textContent = chip.text;
+            el.title = chip.title + '\nClick: open Console → Qwiic';
+            el.className = 'chip qwiic-chip qw-' + chip.level;
+        }
+        const sum = $('cQwSum');
+        if (sum) sum.textContent = st.available ? chip.text.replace(/^Qwiic:? ?/, '') || '—' : '—';
+        if (sum) sum.className = 'sub' + (chip.level === 'err' ? ' qw-err-t' : chip.level === 'warn' ? ' qw-warn-t' : '');
+    }
+    function qwRenderTable() {
+        const row = $('cQwTableRow');
+        const tbl = $('cQwTable');
+        const flags = $('cQwFlags');
+        const d = qw.discovery;
+        if (!row || !tbl) return;
+        if (!d || d.error) {
+            row.style.display = 'none';
+            if (flags) flags.style.display = 'none';
+            return;
+        }
+        const statusByKey = {};
+        (qw.check ? qw.check.entries : []).forEach((e) => { if (e.item) statusByKey[e.item.key] = e; });
+        let html = '<tr><th title="7-bit I2C address">addr</th><th>part</th><th title="root bus, or the PCA9548 mux channel it sits behind">where</th><th>identify</th><th title="Compared with the session rig YAML peripherals: list">rig YAML</th></tr>';
+        for (const it of d.devices) {
+            const e = statusByKey[it.key];
+            let yaml = '';
+            if (it.shadow) yaml = '<span class="dim">— (not a device)</span>';
+            else if (e) yaml = e.status === 'ok' ? '<span class="qw-ok-t">declared: ' + qwEsc(e.decl.name) + '</span>' : '<span class="qw-err-t">' + qwEsc(e.status.replace('_', ' ')) + '</span>';
+            else if (qwIsUndeclared(it)) yaml = '<span class="qw-warn-t" title="Attached but not in the rig YAML — Copy as rig YAML to declare it">⚠ undeclared</span>';
+            const id = it.ident ? (it.ident.ok ? '<span class="qw-ok-t">OK</span> ' : '<span class="qw-err-t">FAIL</span> ') + qwEsc(it.ident.detail) : it.wiringError ? '<span class="qw-err-t">wiring error</span>' : '<span class="dim">no driver</span>';
+            html += '<tr><td>' + qwHex(it.dev.addr) + '</td><td>' + qwEsc(it.label) + '</td><td>' + qwEsc(it.where) + '</td><td>' + id + '</td><td>' + yaml + '</td></tr>';
+        }
+        for (const e of qw.check ? qw.check.entries : []) {
+            if (e.item) continue;
+            html += '<tr><td>' + qwHex(e.decl.address) + '</td><td>' + qwEsc(QD.KINDS[e.decl.kind].label) + '</td><td>' + (e.decl.mux ? 'mux ' + qwHex(e.decl.mux.address) + ' ch' + e.decl.mux.channel : 'root') + '</td><td class="dim">—</td><td><span class="qw-err-t">✕ missing: ' + qwEsc(e.decl.name) + '</span></td></tr>';
+        }
+        tbl.innerHTML = html;
+        row.style.display = '';
+        if (flags) {
+            const msgs = [];
+            for (const e of qw.check ? qw.check.entries : []) if (e.status !== 'ok') msgs.push('<span class="qw-err-t">✕ ' + qwEsc(e.detail) + '</span>');
+            const und = qw.check ? qw.check.undeclared.filter((u) => !u.mux) : [];
+            if (und.length) msgs.push('<span class="qw-warn-t">⚠ ' + und.length + ' attached device' + (und.length === 1 ? ' is' : 's are') + ' not in the rig YAML (' + und.map((u) => qwEsc(u.label) + ' ' + qwHex(u.dev.addr)).join(', ') + ') — <a href="#" data-qw-yaml="undeclared">copy their rig YAML</a></span>');
+            (qw.declared.warnings || []).forEach((w) => msgs.push('<span class="qw-warn-t">rig YAML: ' + qwEsc(w) + '</span>'));
+            flags.innerHTML = msgs.join('<br>');
+            flags.style.display = msgs.length ? '' : 'none';
+        }
+    }
+    function qwRenderDropdown() {
+        const sel = $('cQwDev');
+        if (!sel) return;
+        const items = qw.discovery && !qw.discovery.error ? qw.discovery.devices.filter((it) => it.kind && it.ident && it.ident.ok) : [];
+        sel.innerHTML = '';
+        if (!items.length) {
+            sel.innerHTML = '<option value="">' + (qw.discovery ? '— no supported device found —' : '— scan first —') + '</option>';
+            sel.disabled = true;
+            qw.selKey = null;
+            qwRenderDevice();
+            return;
+        }
+        for (const it of items) {
+            const decl = qwDeclFor(it);
+            const o = document.createElement('option');
+            o.value = it.key;
+            o.textContent = SQ.deviceLabel(it, decl && decl.name) + (qwIsUndeclared(it) ? '  ⚠ undeclared' : '');
+            sel.appendChild(o);
+        }
+        sel.disabled = false;
+        if (!items.some((it) => it.key === qw.selKey)) qw.selKey = items[0].key;
+        sel.value = qw.selKey;
+        qwRenderDevice();
+    }
+    // fromDom=false: the defaults (rig config, else the KINDS default) — used while the
+    // option selects still belong to the PREVIOUS device.
+    function qwOptionValues(item, fromDom) {
+        const K = QD.KINDS[item.kind];
+        const decl = qwDeclFor(item);
+        const out = {};
+        for (const [k, spec] of Object.entries(K.options || {})) {
+            const el = fromDom === false ? null : document.querySelector('#cQwOpts [data-qw-opt="' + k + '"]');
+            const raw = el ? el.value : decl && decl.config[k] !== undefined ? decl.config[k] : spec.default;
+            out[k] = typeof spec.default === 'number' ? Number(raw) : raw;
+        }
+        if (decl && item.kind === 'pca9685' && decl.config.freq_hz) out.freq_hz = decl.config.freq_hz;
+        return out;
+    }
+    // Readout area for the selected device, laid out from its KINDS display fields.
+    function qwRenderDevice() {
+        const out = $('cQwOut');
+        const opts = $('cQwOpts');
+        const bump = $('cQwBump');
+        const servo = $('cQwServo');
+        const item = qw.selKey && qwItem(qw.selKey);
+        const kindOf = item && QD.KINDS[item.kind];
+        ['cqwread', 'cqwlive'].forEach((c) => {
+            const b = document.querySelector('[data-cmd=' + JSON.stringify(c) + ']');
+            if (b) b.disabled = !kindOf || kindOf.role === 'actuator';
+        });
+        const csv = $('cQwCsv');
+        if (csv) csv.disabled = !item || !(qw.rows[item.key] || []).length;
+        if (!out) return;
+        if (!kindOf) {
+            out.innerHTML = '<span class="dim">' + (qw.discovery ? 'pick a device' : 'Scan to list the devices on the Qwiic jack') + '</span>';
+            if (opts) opts.innerHTML = '';
+            if (bump) bump.style.display = 'none';
+            if (servo) servo.style.display = 'none';
+            return;
+        }
+        const decl = qwDeclFor(item);
+        if (opts) {
+            const cur = qw.configured[item.key] || qwOptionValues(item, false);
+            opts.innerHTML = Object.entries(kindOf.options || {}).map(([k, spec]) =>
+                '<label title="' + qwEsc(kindOf.label + ' ' + spec.label + ' — applied on the next read (re-configures the part)') + '">' + qwEsc(spec.label) + ' <select data-qw-opt="' + k + '">' +
+                spec.values.map((v) => '<option value="' + v + '"' + (String(v) === String(cur[k]) ? ' selected' : '') + '>' + v + '</option>').join('') + '</select></label>'
+            ).join(' ');
+            if (opts.innerHTML) opts.insertAdjacentHTML('afterbegin', '<span class="lbl" title="Sensor settings (from the rig YAML config: when declared)">settings</span>');
+            opts.style.display = opts.innerHTML ? '' : 'none';
+        }
+        out.innerHTML = '<div class="qw-title">' + qwEsc(kindOf.title) + (decl ? ' <span class="dim">· rig: ' + qwEsc(decl.name) + '</span>' : qwIsUndeclared(item) ? ' <span class="qw-warn-t">· ⚠ not in the rig YAML</span>' : '') + '</div>' +
+            '<div class="qw-grid" id="cQwGrid">' + kindOf.display.map((f) =>
+                f.fmt === 'bars' ? '<div class="qw-bars" data-qw-key="' + f.key + '" title="Raw counts per channel (no vendor calibration)"></div>'
+                    : '<span class="qw-l">' + qwEsc(f.label) + '</span><span class="qw-v" data-qw-key="' + f.key + '">—</span>'
+            ).join('') + '</div>';
+        if (bump) bump.style.display = kindOf.hasBump ? '' : 'none';
+        if (servo) {
+            servo.style.display = item.kind === 'pca9685' ? '' : 'none';
+            if (item.kind === 'pca9685') qwRenderServoChannels(decl);
+        }
+        qwUpdateRunGates();
+        // Actuators have no Read button: show their state (PCA9685 MODE1/prescale) on select.
+        if (kindOf.role === 'actuator') qwReadOnce({ quiet: true }).catch(() => {});
+    }
+    function qwRenderReading(item, r) {
+        const K = QD.KINDS[item.kind];
+        for (const f of K.display) {
+            const el = document.querySelector('#cQwGrid [data-qw-key="' + f.key + '"]');
+            if (!el) continue;
+            if (f.fmt === 'bars') {
+                const vals = r[f.key] || {};
+                const max = Math.max(1, ...Object.values(vals));
+                el.innerHTML = Object.entries(vals).map(([ch, v]) =>
+                    '<div class="qw-bar" title="' + qwEsc(ch + ': ' + v + ' counts') + '"><i style="height:' + Math.max(2, (100 * v) / max).toFixed(0) + '%"></i><span>' + qwEsc(ch.split('_')[1] || ch) + '</span></div>'
+                ).join('');
+                continue;
+            }
+            el.textContent = SQ.formatField(f, r);
+            el.classList.toggle('qw-err-t', (f.fmt === 'flag' && !!r[f.key]) || (f.fmt === 'okfail' && !r[f.key]));
+        }
+    }
+    async function qwEnsureConfigured(item) {
+        const K = QD.KINDS[item.kind];
+        const want = qwOptionValues(item);
+        const have = qw.configured[item.key];
+        if (have && JSON.stringify(have) === JSON.stringify(want)) return;
+        const decl = qwDeclFor(item);
+        const cfg = Object.assign({}, decl ? decl.config : {}, want);
+        await QD.withDevice(qwBus(), item.dev, () => K.setup(item.driver, cfg, { armBump: false }));
+        qw.configured[item.key] = want;
+        clog('qwiic: ' + K.label + ' ' + qwHex(item.dev.addr) + ' configured' + (Object.keys(want).length ? ' (' + Object.entries(want).map(([k, v]) => k + ' ' + v).join(', ') + ')' : ''), 'info');
+    }
+    async function qwReadOnce(opts) {
+        const quiet = opts && opts.quiet;
+        const g = qwGate('read');
+        const item = qw.selKey && qwItem(qw.selKey);
+        if (!g.ok || !item) {
+            if (!quiet) clog('qwiic: ' + (g.ok ? 'pick a device first' : g.reason), 'err');
+            return null;
+        }
+        const K = QD.KINDS[item.kind];
+        // Actuators are only configured by an explicit servo action (configure wakes the PWM).
+        if (K.role !== 'actuator') await qwEnsureConfigured(item);
+        const r = await K.read(qwBus(), item.dev, item.driver);
+        if (qw.selKey !== item.key) return r; // selection changed while reading
+        qwRenderReading(item, r);
+        if (!K.columns.length) return r; // actuator state: shown, not collected
+        const rows = (qw.rows[item.key] = qw.rows[item.key] || []);
+        rows.push({ t: new Date().toISOString(), values: K.values(r) });
+        if (rows.length > 36000) rows.shift(); // 10 h at 1 Hz
+        const csv = $('cQwCsv');
+        if (csv) csv.disabled = false;
+        if (!quiet) clog('qwiic: ' + K.label + ' ' + K.display.filter((f) => !f.fmt).map((f) => f.label + ' ' + SQ.formatField(f, r)).join(' · '), 'rx');
+        return r;
+    }
+    function qwStopLive(reason) {
+        if (qw.liveTimer) { clearInterval(qw.liveTimer); qw.liveTimer = null; }
+        const was = qw.live;
+        qw.live = false;
+        const b = $('cQwLive');
+        if (b) { b.setAttribute('aria-pressed', 'false'); b.textContent = 'Live'; }
+        if (was && reason) clog('qwiic: live readout stopped — ' + reason, reason.startsWith('error') ? 'err' : 'info');
+    }
+    function qwStartLive() {
+        const hz = Number(($('cQwRate') || {}).value) || 1;
+        qwStopLive();
+        qw.live = true;
+        qw.errStreak = 0;
+        const b = $('cQwLive');
+        if (b) { b.setAttribute('aria-pressed', 'true'); b.textContent = 'Live ●'; }
+        clog('qwiic: live readout at ' + hz + ' Hz', 'info');
+        const tick = async () => {
+            if (qw.inFlight) return; // single-flight
+            const g = qwGate('read');
+            if (!g.ok) { qwSetStatus(g.reason); return; }
+            if (!$('cQwGrid')) return;
+            qw.inFlight = true;
+            try {
+                await qwReadOnce({ quiet: true });
+                qw.errStreak = 0;
+                qwSetStatus('live · ' + hz + ' Hz');
+            } catch (e) {
+                qw.errStreak++;
+                qwSetStatus('error: ' + e.message);
+                if (qw.errStreak >= 3) qwStopLive('error: ' + e.message);
+            } finally {
+                qw.inFlight = false;
+            }
+        };
+        qw.liveTimer = setInterval(tick, Math.round(1000 / hz));
+        tick();
+    }
+    // Scan (setup only) → identify → compare with the rig YAML in BOTH directions.
+    async function qwScan(opts) {
+        const setup = !!(opts && opts.setup);
+        const g = qwGate('scan');
+        if (!g.ok) {
+            qwSetStatus(g.reason);
+            if (!setup) clog('qwiic: ' + g.reason, 'err');
+            return null;
+        }
+        if (qw.busy) return null;
+        qw.busy = true;
+        qwStopLive();
+        qwSetStatus('scanning…');
+        try {
+            const decl = Studio.fetchRigPeripherals ? await Studio.fetchRigPeripherals() : { list: [], warnings: [] };
+            qw.declared = decl || { list: [], warnings: [] };
+            const d = await SQ.discover(qwBus());
+            qw.discovery = d;
+            qw.configured = {};
+            if (d.error) {
+                qw.check = null;
+                Studio.qwiic = { available: true, declared: qw.declared.list, discovery: d, check: null, at: d.at };
+                const msg = d.error.name === 'NoQwiicJack' ? 'this firmware variant has no Qwiic jack' : d.error.message;
+                qwSetStatus('scan failed: ' + msg);
+                clog('qwiic: scan failed — ' + msg, 'err');
+                return null;
+            }
+            qw.check = SQ.checkAgainstScan(qw.declared.list, d);
+            Studio.qwiic = { available: true, declared: qw.declared.list, discovery: d, check: qw.check, at: d.at };
+            const n = qw.check.counts;
+            qwSetStatus(n.devices + ' device' + (n.devices === 1 ? '' : 's') + (n.declared ? ' · ' + n.ok + '/' + n.declared + ' declared present' : ''));
+            const sum = $('cQwScanSum');
+            if (sum) sum.textContent = 'scan: ' + (d.scan.length ? d.scan.map(qwHex).join(' ') : 'nothing ACKed — check the cable, the boards\' power LEDs and the jack');
+            clog('qwiic: ' + (setup ? 'setup ' : '') + 'scan — ' + (d.scan.length ? d.scan.map(qwHex).join(' ') : 'no devices') + (d.shadow ? ' (0x70 = the PCA9685 all-call address, not a mux)' : ''), 'info');
+            qw.declared.warnings.forEach((w) => clog('qwiic: rig YAML: ' + w, 'warn'));
+            qw.check.entries.filter((e) => e.status !== 'ok').forEach((e) => clog('qwiic: ' + e.detail, 'err'));
+            qw.check.undeclared.filter((u) => !u.mux).forEach((u) => clog('qwiic: ' + u.label + ' ' + qwHex(u.dev.addr) + ' @ ' + u.where + ' is attached but not in the rig YAML — Console → Qwiic → Copy as rig YAML', 'warn'));
+            d.devices.filter((it) => it.wiringError).forEach((it) => clog('qwiic: ' + it.label, 'err'));
+            const yamlBtn = $('cQwYaml');
+            if (yamlBtn) yamlBtn.disabled = !d.devices.some((it) => it.kind);
+            qwRenderTable();
+            qwRenderDropdown();
+            return qw.check;
+        } catch (e) {
+            qwSetStatus('error: ' + e.message);
+            clog('qwiic: scan error — ' + e.message, 'err');
+            return null;
+        } finally {
+            qw.busy = false;
+            qwRenderChip();
+        }
+    }
+    // Connect-time setup (initFromController): scan whenever the bridge exists —
+    // even with nothing declared, so an attached-but-undeclared device is flagged —
+    // then configure the declared parts that are present. Never retried.
+    Studio.qwiicSetup = async function () {
+        if (Studio.ensureCapabilities) { try { await Studio.ensureCapabilities(); } catch (_) { /* gate below */ } }
+        let decl = { list: [], warnings: [] };
+        try { if (Studio.fetchRigPeripherals) decl = await Studio.fetchRigPeripherals(); } catch (_) { /* no rig */ }
+        if (!qwHas()) {
+            Studio.qwiic = { available: false, reason: 'no Qwiic I2C bridge on this controller', declared: decl.list };
+            if (decl.list.length) clog('qwiic: the rig YAML declares ' + decl.list.length + ' Qwiic peripheral(s) but this controller has no Qwiic I2C bridge (0xC2 feature bit 1 clear) — they will not be read', 'warn');
+            qwSetStatus('no Qwiic I2C bridge on this controller');
+            qwRenderChip();
+            qwUpdateRunGates();
+            return Studio.qwiic;
+        }
+        const check = await qwScan({ setup: true });
+        if (check && check.entries.some((e) => e.status === 'ok')) {
+            const res = await SQ.applySetup(qwBus(), check, { armBump: false });
+            for (const e of check.entries) {
+                if (res.applied[e.decl.name] && e.item) qw.configured[e.item.key] = qwOptionValuesFor(e);
+            }
+            Studio.qwiic.applied = res.applied;
+            const names = Object.keys(res.applied);
+            if (names.length) clog('qwiic: configured ' + names.map((nm) => nm + ' (' + check.entries.find((e) => e.decl.name === nm).decl.kind + ')').join(', '), 'info');
+            res.errors.forEach((er) => clog('qwiic: setup of ' + er.name + ' failed — ' + er.message, 'err'));
+        }
+        return Studio.qwiic;
+    };
+    // Options the setup applied, in the shape qwOptionValues() compares against.
+    function qwOptionValuesFor(entry) {
+        const K = QD.KINDS[entry.decl.kind];
+        const out = {};
+        for (const [k, spec] of Object.entries(K.options || {})) {
+            const v = entry.decl.config[k] !== undefined ? entry.decl.config[k] : spec.default;
+            out[k] = typeof spec.default === 'number' ? Number(v) : v;
+        }
+        if (entry.decl.kind === 'pca9685' && entry.decl.config.freq_hz) out.freq_hz = entry.decl.config.freq_hz;
+        return out;
+    }
+    // Rig changed: re-compare the last scan with the new YAML (no rescan — setup only).
+    Studio.qwiicRecheck = async function () {
+        if (!qw.discovery || qw.discovery.error || !SQ) return;
+        try { qw.declared = Studio.fetchRigPeripherals ? await Studio.fetchRigPeripherals() : { list: [], warnings: [] }; } catch (_) { return; }
+        qw.check = SQ.checkAgainstScan(qw.declared.list, qw.discovery);
+        Studio.qwiic = Object.assign({}, Studio.qwiic, { declared: qw.declared.list, check: qw.check });
+        qwRenderTable();
+        qwRenderDropdown();
+        qwRenderChip();
+    };
+    Studio.qwiicReset = function () {
+        qwStopLive();
+        qw.discovery = null;
+        qw.check = null;
+        qw.configured = {};
+        qw.selKey = null;
+        Studio.qwiic = null;
+        qwSetStatus('connect to scan');
+        const sum = $('cQwScanSum');
+        if (sum) sum.textContent = '';
+        qwRenderTable();
+        qwRenderDropdown();
+        qwRenderChip();
+    };
+    // Bump check + servo are disabled while a run owns the link / the bump latch.
+    function qwUpdateRunGates() {
+        const running = !!(session && session.running);
+        document.querySelectorAll('#cQwBump button, #cQwServo button, #cQwServo input, [data-cmd="cqwscan"]').forEach((el) => {
+            el.disabled = running || !(session && session.connected) || !qwHas();
+        });
+        const note = $('cQwBumpNote');
+        if (note) note.textContent = running ? 'a run owns the bump latch — checks are off until it ends' : '';
+    }
+    Studio.qwiicUpdateRunGates = qwUpdateRunGates;
+    if (session) session.on('runstatus', () => qwUpdateRunGates());
+    async function qwBumpArm() {
+        const g = qwGate('read');
+        const item = qw.selKey && qwItem(qw.selKey);
+        if (!g.ok || !item || item.kind !== 'lsm6dsox') { clog('qwiic: ' + (g.ok ? 'select the LSM6DSOX first' : g.reason), 'err'); return; }
+        const th = Math.max(0.05, Math.min(2, Number(($('cQwBumpG') || {}).value) || 0.25));
+        await qwEnsureConfigured(item);
+        const ths = await QD.withDevice(qwBus(), item.dev, () => item.driver.armBump(th));
+        $('cQwBumpOut').textContent = 'armed at ' + th + ' g (' + ths + ' LSB)';
+        clog('qwiic: LSM6DSOX bump latch armed at ' + th + ' g — "Check" reads AND clears it', 'info');
+    }
+    async function qwBumpCheck() {
+        const g = qwGate('read');
+        const item = qw.selKey && qwItem(qw.selKey);
+        if (!g.ok || !item || item.kind !== 'lsm6dsox') { clog('qwiic: ' + (g.ok ? 'select the LSM6DSOX first' : g.reason), 'err'); return; }
+        const b = await QD.withDevice(qwBus(), item.dev, () => item.driver.bumpFlag());
+        const out = $('cQwBumpOut');
+        if (out) { out.textContent = b.bumped ? 'BUMPED [' + b.axes + '] — latch cleared' : 'no bump since the last check'; out.classList.toggle('qw-err-t', b.bumped); }
+        clog('qwiic: bump check — ' + (b.bumped ? 'BUMPED [' + b.axes + '] (latch cleared)' : 'no bump'), b.bumped ? 'warn' : 'info');
+    }
+    // ---- servo (PCA9685): minimal go-to-position ----
+    function qwServoSpec() {
+        const item = qw.selKey && qwItem(qw.selKey);
+        const decl = item && qwDeclFor(item);
+        const ch = Number(($('cQwSvCh') || {}).value) || 0;
+        const named = decl && Object.values(decl.channels || {}).find((c) => c.channel === ch);
+        const wide = !!($('cQwSvWide') || {}).checked;
+        const lim = wide ? SQ.SERVO_US_LIMITS : named || SQ.SERVO_US_DEFAULT;
+        return { item, ch, min: lim.min_us, max: lim.max_us };
+    }
+    function qwRenderServoChannels(decl) {
+        const sel = $('cQwSvCh');
+        if (!sel) return;
+        const names = {};
+        Object.entries((decl && decl.channels) || {}).forEach(([nm, c]) => (names[c.channel] = nm));
+        const keep = sel.value;
+        sel.innerHTML = '';
+        for (let c = 0; c < 16; c++) {
+            const o = document.createElement('option');
+            o.value = String(c);
+            o.textContent = 'ch' + c + (names[c] ? ' · ' + names[c] : '');
+            sel.appendChild(o);
+        }
+        const firstNamed = Object.keys(names)[0];
+        sel.value = keep && Number(keep) < 16 ? keep : firstNamed !== undefined ? firstNamed : '0';
+        qwServoLimits();
+    }
+    function qwServoLimits() {
+        const s = qwServoSpec();
+        const sl = $('cQwSvUs');
+        const nb = $('cQwSvNum');
+        [sl, nb].forEach((el) => {
+            if (!el) return;
+            el.min = s.min;
+            el.max = s.max;
+            if (Number(el.value) < s.min || Number(el.value) > s.max) el.value = Math.round((s.min + s.max) / 2);
+        });
+        const lim = $('cQwSvLim');
+        if (lim) lim.textContent = s.min + '–' + s.max + ' µs';
+    }
+    async function qwServo(action) {
+        const g = qwGate('read');
+        const s = qwServoSpec();
+        if (!g.ok || !s.item || s.item.kind !== 'pca9685') { clog('qwiic: ' + (g.ok ? 'select the PCA9685 first' : g.reason), 'err'); return; }
+        const drv = s.item.driver;
+        await qwEnsureConfigured(s.item);
+        const out = $('cQwSvOut');
+        if (action === 'release') {
+            await QD.withDevice(qwBus(), s.item.dev, () => drv.setOff(s.ch));
+            if (out) out.textContent = 'ch' + s.ch + ' released (full OFF — no holding torque)';
+            clog('qwiic: servo ch' + s.ch + ' released', 'info');
+            return;
+        }
+        if (action === 'alloff') {
+            await QD.withDevice(qwBus(), s.item.dev, () => drv.allOff());
+            if (out) out.textContent = 'all 16 channels released';
+            clog('qwiic: servo — all channels released', 'info');
+            return;
+        }
+        let us = action === 'center' ? Math.round((s.min + s.max) / 2) : Number(($('cQwSvNum') || {}).value);
+        us = Math.max(s.min, Math.min(s.max, us || 1500));
+        const off = await QD.withDevice(qwBus(), s.item.dev, async () => {
+            const o = await drv.setPulseUs(s.ch, us);
+            const rb = await drv.readCounts(s.ch);
+            if (rb[1] !== o) throw new Error('read-back OFF ' + rb[1] + ' ≠ ' + o);
+            return o;
+        });
+        $('cQwSvUs').value = us;
+        $('cQwSvNum').value = us;
+        qwReadOnce({ quiet: true }).catch(() => {}); // refresh the PWM / oscillator readout
+        if (out) out.textContent = 'ch' + s.ch + ' → ' + us + ' µs (OFF count ' + off + ' @ ' + drv.freqHz.toFixed(2) + ' Hz, read back ✓)';
+        clog('qwiic: servo ch' + s.ch + ' → ' + us + ' µs (count ' + off + ')', 'info');
+    }
+    async function qwCopyYaml(which) {
+        if (!qw.discovery || qw.discovery.error) { clog('qwiic: scan first', 'err'); return; }
+        const only = which === 'undeclared' || (qw.declared.list.length && qw.check && qw.check.undeclared.length) ? qw.check.undeclared : null;
+        const text = SQ.toRigYaml(qw.discovery, only ? { only } : {});
+        const body = only ? text.replace(/^peripherals:\n/, '') : text;
+        try {
+            await navigator.clipboard.writeText(body);
+            clog('qwiic: rig YAML ' + (only ? 'entries for the ' + only.length + ' undeclared device(s)' : 'peripherals: block') + ' copied — paste it into the rig file (configs/rigs/<rig>.yaml)', 'info');
+        } catch (_) {
+            window.prompt('Copy this rig YAML:', body);
+        }
+    }
+    function qwDownloadCsv() {
+        const item = qw.selKey && qwItem(qw.selKey);
+        const rows = item && qw.rows[item.key];
+        if (!rows || !rows.length) { clog('qwiic: nothing read yet for this device', 'err'); return; }
+        const K = QD.KINDS[item.kind];
+        const lines = ['time,' + K.columns.join(',')];
+        rows.forEach((r) => lines.push(r.t + ',' + K.columns.map((c) => (r.values[c] == null ? '' : r.values[c])).join(',')));
+        const stamp = new Date().toISOString().replace(/[:]/g, '-').slice(0, 19);
+        downloadBlob(new TextEncoder().encode(lines.join('\n') + '\n'), 'qwiic_' + item.kind + '_' + item.dev.addr.toString(16) + '_' + stamp + '.csv', 'text/csv');
+        clog('qwiic: ' + rows.length + ' reading(s) saved as CSV (Console only — not a run log)', 'info');
+    }
+    (function qwWire() {
+        const sel = $('cQwDev');
+        if (sel) sel.addEventListener('change', () => { qwStopLive('device changed'); qw.selKey = sel.value || null; qwRenderDevice(); });
+        const rate = $('cQwRate');
+        if (rate) rate.addEventListener('change', () => { if (qw.live) qwStartLive(); });
+        const flags = $('cQwFlags');
+        if (flags) flags.addEventListener('click', (e) => { const a = e.target.closest('[data-qw-yaml]'); if (a) { e.preventDefault(); qwCopyYaml(a.dataset.qwYaml); } });
+        const ch = $('cQwSvCh');
+        if (ch) ch.addEventListener('change', qwServoLimits);
+        const wide = $('cQwSvWide');
+        if (wide) wide.addEventListener('change', () => {
+            if (wide.checked && !window.confirm('Allow 500–2500 µs? Many hobby servos hit their end stops (and stall, drawing current) outside ~1000–2000 µs.')) wide.checked = false;
+            qwServoLimits();
+        });
+        const sl = $('cQwSvUs');
+        const nb = $('cQwSvNum');
+        if (sl && nb) {
+            sl.addEventListener('input', () => { nb.value = sl.value; });
+            sl.addEventListener('change', () => { qwServo('go').catch((e) => clog('qwiic: servo — ' + e.message, 'err')); });
+            nb.addEventListener('change', () => { sl.value = nb.value; });
+        }
+        const chip = $('qwiicChip');
+        const openPanel = () => {
+            if (Studio.setMode) Studio.setMode('console');
+            if (Studio.openConsolePanel) Studio.openConsolePanel('qwiic');
+        };
+        if (chip) {
+            chip.addEventListener('click', openPanel);
+            chip.addEventListener('keydown', (e) => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); openPanel(); } });
+        }
+        qwRenderDevice();
+    })();
+    const qwRun = (fn) => () => fn().catch((e) => { clog('qwiic: ' + e.message, 'err'); qwSetStatus('error: ' + e.message); });
+
     function aiRenderSweepTable(rep) {
         const row = $('cAiSweepRow');
         const tbl = $('cAiSweepTable');
@@ -6240,6 +6866,18 @@ <h2 id="modalTitle">Import error</h2>
             const a = resp && Wire.decodeAnalogIn(resp);
             if (a) $('cAiRead').textContent = 'AI1 ' + a.ain1Mv + ' mV · AI2 ' + a.ain2Mv + ' mV' + (a.flags != null ? ' · ' + window.StudioAnalogIn.describeFlags(a.flags).text : '');
         },
+        // Qwiic panel (LAB-214) — explore/test only, nothing logged to run logs
+        cqwscan: qwRun(() => qwScan()),
+        cqwread: qwRun(() => qwReadOnce()),
+        cqwlive: () => { if (qw.live) qwStopLive('stopped by user'); else qwStartLive(); },
+        cqwcsv: () => qwDownloadCsv(),
+        cqwyaml: qwRun(() => qwCopyYaml('auto')),
+        cqwbumparm: qwRun(qwBumpArm),
+        cqwbumpcheck: qwRun(qwBumpCheck),
+        cqwsvgo: qwRun(() => qwServo('go')),
+        cqwsvcenter: qwRun(() => qwServo('center')),
+        cqwsvrelease: qwRun(() => qwServo('release')),
+        cqwsvalloff: qwRun(() => qwServo('alloff')),
         // Analog In panel (analog-input-plan § 4 S1)
         caipoll: () => {
             aiUser.enabled = !aiUser.enabled;
@@ -6429,6 +7067,9 @@ <h2 id="modalTitle">Import error</h2>
         // Optional-guarded: if the module block failed to load (stale-cache
         // gotcha), connect/bench ops must still work — defaults just don't apply.
         if (Studio.applyRigIo) { try { await Studio.applyRigIo(); } catch (_) { /* logged inside */ } }
+        // Qwiic setup scan (LAB-214): once per connection, never retried; guarded
+        // so a failure never blocks connect.
+        if (Studio.qwiicSetup) { try { await Studio.qwiicSetup(); } catch (e) { clog('qwiic: setup failed — ' + e.message, 'err'); } }
         const q = async (bytes) => { try { return await session.send(bytes, { timeoutMs: 2000 }); } catch (_) { return null; } };
         const got = [];
         const rr = Wire.decodeRefreshRate(await q(Wire.encodeGetRefreshRate()));
@@ -7069,7 +7710,9 @@ <h2 id="modalTitle">Import error</h2>
             Studio.panelsStatus = 'disconnected';
             if (Studio._panelsFollowUp) { clearTimeout(Studio._panelsFollowUp); Studio._panelsFollowUp = null; }
             if (Studio.updateRigIoGating) Studio.updateRigIoGating();
+            if (Studio.qwiicReset) Studio.qwiicReset(); // never carry one controller's Qwiic scan into the next
         }
+        if (Studio.qwiicUpdateRunGates) Studio.qwiicUpdateRunGates();
     }
     if (session) session.on('state', syncEnabled);
     syncEnabled();
@@ -7409,6 +8052,7 @@ <h2 id="modalTitle">Import error</h2>
     };
     invalidateRigIo();
     renderRigIoMenu();
+    if (Studio.qwiicRecheck) Studio.qwiicRecheck(); // re-compare the last Qwiic scan with the new rig's peripherals:
     updateIspShowUI(); // the batch progress map needs a 20-panel layout
     if (window.Scope && window.Scope.applyRigBallDiameter) window.Scope.applyRigBallDiameter(); // scope forward-velocity calibration
     Studio.refreshState(); // device line + mismatch chip
@@ -7420,11 +8064,13 @@ <h2 id="modalTitle">Import error</h2>
 // The io: block lives in the rig YAML (index.json only carries name/arena), so
 // it's fetched lazily per session rig and cached. parseRigIo is tolerant: a
 // rig without an io: block parses to all-off and applyRigIo is a no-op.
+// The same fetch also parses the rig's `peripherals:` (Qwiic, LAB-214) — one
+// rig read, two tolerant parsers.
 let rigIo = { name: null, promise: null };
 function invalidateRigIo() {
     rigIo = { name: null, promise: null };
 }
-function fetchRigIo() {
+function fetchRigSections() {
     const name = Studio.currentRig && Studio.currentRig.name;
     if (!name) return Promise.resolve(null);
     if (rigIo.name === name && rigIo.promise) return rigIo.promise;
@@ -7434,14 +8080,27 @@ <h2 id="modalTitle">Import error</h2>
         try {
             const res = await fetch(entry.path, { cache: 'no-store' });
             if (!res.ok) return null;
-            return parseRigIo(parseRigYAMLText(await res.text()));
+            const data = parseRigYAMLText(await res.text());
+            const SQ = window.StudioQwiic;
+            return {
+                io: parseRigIo(data),
+                peripherals: SQ ? SQ.parseRigPeripherals(data) : { list: [], warnings: ['js/studio-qwiic.js not loaded'] }
+            };
         } catch (_) {
-            return null; // malformed rig YAML → treat as no io: block
+            return null; // malformed rig YAML → treat as no io: / peripherals: block
         }
     })();
     rigIo = { name: name, promise: p };
     return p;
 }
+function fetchRigIo() {
+    return fetchRigSections().then((r) => (r ? r.io : null));
+}
+// Rig `peripherals:` for the Qwiic glue (classic ConsoleView) → {list, warnings}.
+Studio.fetchRigPeripherals = async function () {
+    const r = await fetchRigSections();
+    return r ? r.peripherals : { list: [], warnings: [] };
+};
 // io_ext capability (0xC2 bit 5): the connected firmware supports
 // SET_DIO_ROLE/GET_DIO_ROLE/SET_AO_MODE/GET_ANALOG_IN. Set at connect.
 function hasIoExt() {
@@ -7469,6 +8128,7 @@ <h2 id="modalTitle">Import error</h2>
     } catch (_) { /* older fw / no reply — hasIoExt() stays false */ }
 }
 Studio.updateRigIoGating = function () { updateRigIoGating(); }; // classic shell re-gates on caps change
+Studio.ensureCapabilities = ensureCapabilities; // Qwiic setup gates on the 0xC2 feature bits
 // Enable/disable the capability-gated role options to match the CONNECTED
 // firmware (never version-guessing). AI 'in' stays disabled regardless —
 // the ±10V front-end calibration is TBD (bench).
@@ -17037,6 +17697,7 @@ <h2 id="modalTitle">Import error</h2>
   // The rail is a show/hide checklist: each row is role=checkbox (aria-checked
   // mirrors the panel's open state); Space/Enter toggle it like a click.
   function setOpen(t,o){var p=P(t),r=R(t); if(!p)return; p.classList.toggle('open',o); if(r){r.classList.toggle('sel',o); r.setAttribute('aria-checked',o?'true':'false');}}
+  if (window.Studio) window.Studio.openConsolePanel = function(t){ setOpen(t,true); var p=P(t); if(p&&p.scrollIntoView) p.scrollIntoView({block:'nearest'}); };
   document.querySelectorAll('#cRail .rail-btn').forEach(function(b){
     b.addEventListener('click',function(){var t=b.dataset.panel; if(!t)return; setOpen(t,!P(t).classList.contains('open'));});
     b.addEventListener('keydown',function(e){ if(e.key===' '||e.key==='Enter'){ e.preventDefault(); b.click(); } });
@@ -17225,6 +17886,16 @@ <h2 id="modalTitle">Import error</h2>
     '.rail-btn[data-panel="test"]': 'Test figures the browser draws and streams to the display — no memory card needed.',
     '.rail-btn[data-panel="io"]': 'The controller’s analog and digital input/output connectors.',
     '.rail-btn[data-panel="ai"]': 'Watch the two analog inputs live, and check the wiring by looping Analog Out back into an input.',
+    '.rail-btn[data-panel="qwiic"]': 'Find and try out the small sensors plugged into the arena’s Qwiic connector: scan, pick one, watch its readings. Nothing here is saved to run logs.',
+    '[data-cmd="cqwscan"]': 'Look for every device on the Qwiic connector and check each one against this rig’s list. Not available while a run is going.',
+    '#cQwYaml': 'Copy ready-made rig-file lines for the devices the scan found, so they can be recorded with each run.',
+    '#cQwDev': 'Pick one device to look at. Devices marked “undeclared” are plugged in but not listed in this rig’s file.',
+    '[data-cmd="cqwread"]': 'Take one reading from the selected device.',
+    '#cQwLive': 'Keep reading the selected device about once a second. Pauses by itself during a run.',
+    '[data-cmd="cqwbumpcheck"]': 'Was the motion sensor bumped since the last check? Checking resets the answer.',
+    '#cQwSvUs': 'Servo position. Let go of the slider to move the servo.',
+    '[data-cmd="cqwsvrelease"]': 'Let the servo go limp (it stops holding its position).',
+    '#qwiicChip': 'The sensors on the Qwiic connector compared with this rig’s list. Red = a listed sensor is missing; amber = something is plugged in that isn’t listed. Click to open them in the Console.',
     '.rail-btn[data-panel="fw"]': 'Update or check the firmware on the LED panels.',
     '[data-cmd="cinv"]': 'Show which panels the controller found at start-up and which firmware each one runs.',
     '[data-cmd="cinvscan"]': 'Look for the panels again and re-check their firmware (the display is stopped while this runs).',
@@ -17307,7 +17978,8 @@ <h2 id="modalTitle">Import error</h2>
     io: 'Read the analog input, set the analog output, and drive the two digital connectors.',
     ai: 'Both analog inputs, live. Cable Analog Out to an input and run the loopback sweep to check the wiring end to end; polling pauses by itself during a run.',
     fw: 'Check what firmware the panels run, and program new firmware into every panel from here.',
-    fictrac: 'Closed loop: connect the bridge, load a pattern in Step frames, set the gain, then Activate — the fly steers the pattern.'
+    fictrac: 'Closed loop: connect the bridge, load a pattern in Step frames, set the gain, then Activate — the fly steers the pattern.',
+    qwiic: 'Sensors on the Qwiic connector. Scan, pick one device, and watch its readings in real units; the motion sensor has a bump check and the servo board a position slider. For testing only — nothing is saved to run logs.'
   };
   Object.keys(PANEL_HELP).forEach(function(k){
     var t=document.querySelector('.panel[data-panel="'+k+'"] .panel-title');
diff --git a/docs/development/arena-studio-release-notes.md b/docs/development/arena-studio-release-notes.md
index e337b4fc..e70f8afc 100644
--- a/docs/development/arena-studio-release-notes.md
+++ b/docs/development/arena-studio-release-notes.md
@@ -4,6 +4,13 @@ The Studio's footer used to carry the full changelog inline; it now shows one li
 history lives here. Newest first. (Per-session engineering detail stays in
 `arena-studio-handover.md` and the design docs — this file is the user-facing what-changed list.)
 
+## v0.96 (2026-10-12) · Qwiic sensors in the Console (LAB-214)
+
+<!-- LAB-214 PR 1 -->
+- **Console → Qwiic: find and try the sensors on the arena's Qwiic / STEMMA QT connector.** Scan lists every device on the bus, identifies the supported parts (SHT4x temperature/humidity, LSM6DSOX tilt + bump, TSL2591 / VEML7700 / AS7343 light, PCA9685 servo driver) and compares them with the rig file. Pick one device to see its readings in real units, once or live; the motion sensor has a bump check, and the servo board a position slider with Center and Release. This panel is for testing — nothing in it is written to run logs.
+- **Rig files can list their Qwiic peripherals (`peripherals:`).** On connect the Studio scans once and shows a Qwiic chip in the top bar: green when every listed device is there, red when one is missing (no retry), amber when something is plugged in that the rig file doesn't list. **Copy as rig YAML** gives you the lines to add.
+- Controllers without a Qwiic connector are unaffected: the Studio never sends them I2C commands, and the chip stays hidden.
+
 ## v0.94 (2026-09-30) · LAB-158 ports (Protocol ▾, ⚙ Settings, two-column Console) + visibility themes · Multi-color G6 panels V1 — Panel LEDs layout, ON color, per-bank preview (LAB-228) · Flasher + Studio picker: one production build from the published catalog; legacy images hashed, never default (panel-fw-v1.3.1)
 
 <!-- #238 -->
diff --git a/js/arena-wire-g6.js b/js/arena-wire-g6.js
index de8479e7..3c008e37 100644
--- a/js/arena-wire-g6.js
+++ b/js/arena-wire-g6.js
@@ -90,6 +90,10 @@ const ArenaWireG6 = (function () {
         G6_VERIFY_PANEL: 0xc9, // [02 C9 panel_index] CRC the panel's running app flash vs /firmware/panel.bin footer
         PANEL_INVENTORY_SCAN: 0xd0, // [02 D0 action] re-probe the fleet: 0 presence (keeps fingerprints), 1 presence + fresh fingerprints; replies with 0xD1 page 0 (feature bit 0)
         GET_PANEL_INVENTORY: 0xd1, // [01 D1] | [02 D1 first] per-panel presence + firmware fingerprint, 32-panel pages (feature bit 0)
+        // Qwiic / STEMMA QT I2C bridge (feature bit 1, arena_12-18 jack J2 = Wire1). Sensor-agnostic:
+        // every register map lives host-side (js/qwiic-drivers.js). 0xB2–0xBF stay reserved.
+        GET_I2C_SCAN: 0xb0, // [01 B0] returns [count, addr...] — every 7-bit address that ACKs (setup only: ~10 ms loop stall)
+        I2C_TRANSFER: 0xb1, // [len B1 addr wlen w... rlen] write then repeated-start read; returns rlen bytes
         ALL_ON: 0xff
     };
 
@@ -1405,6 +1409,88 @@ const ArenaWireG6 = (function () {
 
     // g6-program-panel (0xC8) reply: status byte + ASCII detail. `ok` === flash
     // succeeded; `message` carries the controller's diagnostic / failure step.
+    // ── Qwiic I2C bridge (0xB0 / 0xB1) ──
+    // Status codes the firmware returns for both commands (I2C_TRANSFER also uses 2/3/5).
+    const I2C_STATUS_TEXT = {
+        1: 'bad framing',
+        2: 'address NACK',
+        3: 'data NACK',
+        4: 'bus error/timeout',
+        5: 'short read'
+    };
+    const I2C_READ_MAX = 64; // firmware qwiic_i2c_read_byte_count_max
+    const I2C_WRITE_MAX = 64; // host-side cap; register writes are a few bytes
+
+    function encodeGetI2cScan() {
+        return frame(OPCODES.GET_I2C_SCAN); // 01 B0
+    }
+
+    // [4+wlen, B1, addr, wlen, w..., rlen]. wlen = 0 → plain read; rlen = 0 → plain
+    // write; both 0 → ACK probe of the address.
+    function encodeI2cTransfer(addr, wbytes, rlen) {
+        requireInt(addr, 'addr');
+        if (addr < 0 || addr > 0x7f) {
+            throw new RangeError('addr must be a 7-bit address 0..127, got ' + addr);
+        }
+        const w = Array.from(wbytes || []);
+        if (w.length > I2C_WRITE_MAX) {
+            throw new RangeError('I2C write is ' + w.length + ' bytes, max ' + I2C_WRITE_MAX);
+        }
+        w.forEach((b, i) => u8(b, 'wbytes[' + i + ']'));
+        const n = rlen === undefined ? 0 : rlen;
+        requireInt(n, 'rlen');
+        if (n < 0 || n > I2C_READ_MAX) {
+            throw new RangeError('rlen must be 0..' + I2C_READ_MAX + ', got ' + n);
+        }
+        return frame(OPCODES.I2C_TRANSFER, [addr, w.length, ...w, n]);
+    }
+
+    function _asciiPayload(payload) {
+        let message = '';
+        for (let i = 0; i < payload.length; i++) {
+            const b = payload[i];
+            if (b >= 0x20 && b < 0x7f) message += String.fromCharCode(b);
+        }
+        return message;
+    }
+
+    // Shared shape for both I2C replies: a non-ok status carries an ASCII reason;
+    // "No Qwiic jack…" marks a firmware variant without the jack (arena_10-10 / 2x10).
+    function _i2cResult(r) {
+        const message = r.ok ? '' : _asciiPayload(r.payload);
+        return {
+            ok: r.ok,
+            status: r.status,
+            statusText: r.ok ? 'ok' : I2C_STATUS_TEXT[r.status] || 'status ' + r.status,
+            message,
+            noJack: !r.ok && /no qwiic jack/i.test(message)
+        };
+    }
+
+    // GET_I2C_SCAN → { ok, status, statusText, message, noJack, addresses: [7-bit…] }.
+    // null for a short/unparseable frame or a count that disagrees with the payload.
+    function decodeI2cScan(resp) {
+        const r = asResponse(resp);
+        if (!r) return null;
+        const out = _i2cResult(r);
+        out.addresses = [];
+        if (!r.ok) return out;
+        if (r.payload.length < 1) return null;
+        const count = r.payload[0];
+        if (r.payload.length !== 1 + count) return null;
+        out.addresses = Array.from(r.payload.slice(1, 1 + count));
+        return out;
+    }
+
+    // I2C_TRANSFER → { ok, status, statusText, message, noJack, data: Uint8Array }.
+    function decodeI2cTransfer(resp) {
+        const r = asResponse(resp);
+        if (!r) return null;
+        const out = _i2cResult(r);
+        out.data = r.ok ? Uint8Array.from(r.payload) : new Uint8Array(0);
+        return out;
+    }
+
     function decodeProgramPanelResponse(resp) {
         const r = asResponse(resp);
         if (!r) return null;
@@ -1423,6 +1509,8 @@ const ArenaWireG6 = (function () {
         PANEL_DISPLAY_MODE_NAMES,
         CAPABILITY_BITS,
         FEATURE_BITS,
+        I2C_STATUS_TEXT,
+        I2C_READ_MAX,
         PANEL_STATUS_NAMES,
         PANEL_INVENTORY_FLAGS,
         STREAM_FRAME_BYTES,
@@ -1483,6 +1571,8 @@ const ArenaWireG6 = (function () {
         encodeGetDioRole,
         encodeSetAoMode,
         encodeGetAnalogIn,
+        encodeGetI2cScan,
+        encodeI2cTransfer,
 
         // Decoders
         decodeResponse,
@@ -1520,6 +1610,8 @@ const ArenaWireG6 = (function () {
         decodeSetFirmwareFileResponse,
         decodeFirmwareInfo,
         decodeProgramPanelResponse,
+        decodeI2cScan,
+        decodeI2cTransfer,
         decodePanelInventory
     };
 })();
diff --git a/js/qwiic-drivers.js b/js/qwiic-drivers.js
new file mode 100644
index 00000000..8ffc868a
--- /dev/null
+++ b/js/qwiic-drivers.js
@@ -0,0 +1,1230 @@
+/**
+ * qwiic-drivers.js — host-side register maps for the Qwiic / STEMMA QT
+ * peripherals, driven over the controller's sensor-agnostic I2C bridge
+ * (GET_I2C_SCAN 0xB0 / I2C_TRANSFER 0xB1; fw PR #58, 0xC2 feature bit 1
+ * `qwiic_i2c`, arena_12-18 jack J2 = Wire1). LAB-214.
+ *
+ * A port of the firmware repo's tests/qwiic_sensors.py + tests/qwiic_peripherals.py
+ * (bench-verified 2026-10-12, docs/development/qwiic-bench-2026-10-12.md there).
+ * The firmware knows nothing about any part: every register map lives here.
+ *
+ *   createBus(send, opts)  transport + async MUTEX. `send(bytes, opts)` resolves
+ *                          to the raw response frame (ArenaSession.send).
+ *   bus.exclusive(fn)      run a multi-transfer sequence with no other I2C user
+ *                          in between (mux select + reads, SHT4x's two legs, IMU
+ *                          read + bump). NOT re-entrant: never call exclusive()
+ *                          from inside fn. The link FIFO only orders single
+ *                          commands; this orders whole sequences.
+ *   withDevice(bus, dev, fn)  exclusive() + PCA9548 channel select/restore.
+ *   locateDevices(bus)     scan + mux channel map; a PCA9685's all-call shadow
+ *                          at 0x70 is never mapped as a mux (decided from MODE1).
+ *   KINDS                  THE registry: one entry per supported part (label,
+ *                          role, default addresses, identify/setup/read, display
+ *                          fields, log columns). Add or drop a part HERE only.
+ *
+ * Bench quirks kept (do not "simplify" them away):
+ *   - SHT4x NACKs a read while measuring: write leg, wait, separate read leg —
+ *     never a repeated-start pair. Sensirion CRC-8 checked on every word.
+ *   - LSM6DSOX bump latch needs LIR + INT_CLR_ON_READ + INT1_WU routing (the INT1
+ *     pin is not wired; the routing is what latches). bumpFlag() reads AND CLEARS:
+ *     exactly one owner may call it (the trial logger during runs).
+ *   - PCA9685 answers its all-call 0x70 (reads too) until MODE1.ALLCALL is
+ *     cleared — the PCA9548's default address. configure() clears it.
+ *   - The Servo pHAT's logic is powered from its own USB-C, not the Qwiic 3.3 V:
+ *     unpowered = absent from the scan.
+ *   - TSL2591 full scale is 36863 at 100 ms integration, 65535 otherwise.
+ *
+ * LOADING: classic <script src> (window-global `QwiicDrivers` + CommonJS), no ES
+ * `export` — same rule as arena-session.js (CLAUDE.md).
+ */
+(function (global) {
+    'use strict';
+
+    const Wire =
+        (typeof require === 'function' &&
+            (() => {
+                try {
+                    return require('./arena-wire-g6.js');
+                } catch (_) {
+                    return null;
+                }
+            })()) ||
+        global.ArenaWireG6;
+
+    const hex2 = (a) => '0x' + (a & 0xff).toString(16).toUpperCase().padStart(2, '0');
+    const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+    const defaultNow = () =>
+        typeof performance !== 'undefined' && performance.now ? performance.now() : Date.now();
+
+    // ── errors ──────────────────────────────────────────────────────────────
+
+    class I2CError extends Error {
+        constructor(status, addr, msg) {
+            const text = (Wire && Wire.I2C_STATUS_TEXT[status]) || 'status ' + status;
+            super('I2C ' + hex2(addr) + ': ' + text + (msg ? ' (' + msg + ')' : ''));
+            this.name = 'I2CError';
+            this.status = status;
+            this.addr = addr;
+        }
+    }
+
+    /** The flashed firmware variant has no Qwiic jack (arena_10-10 / 2x10 builds). */
+    class NoQwiicJack extends Error {
+        constructor(msg) {
+            super(msg || 'No Qwiic jack on this hardware variant');
+            this.name = 'NoQwiicJack';
+        }
+    }
+
+    // ── bus ─────────────────────────────────────────────────────────────────
+
+    /**
+     * @param {(bytes:Uint8Array, opts:object)=>Promise<Uint8Array>} send
+     * @param {{sleep?, now?, timeoutMs?, scanTimeoutMs?, sendOpts?}} [opts]
+     */
+    function createBus(send, opts) {
+        const o = opts || {};
+        const sleep = o.sleep || defaultSleep;
+        const now = o.now || defaultNow;
+        const timeoutMs = o.timeoutMs || 1000;
+        const scanTimeoutMs = o.scanTimeoutMs || 2000;
+        const sendOpts = o.sendOpts || {};
+        let tail = Promise.resolve();
+        let held = false;
+
+        function exclusive(fn) {
+            const run = tail.then(async () => {
+                held = true;
+                try {
+                    return await fn();
+                } finally {
+                    held = false;
+                }
+            });
+            tail = run.catch(() => {});
+            return run;
+        }
+
+        async function scan() {
+            const d = Wire.decodeI2cScan(
+                await send(
+                    Wire.encodeGetI2cScan(),
+                    Object.assign({}, sendOpts, { timeoutMs: scanTimeoutMs })
+                )
+            );
+            if (!d) throw new Error('GET_I2C_SCAN: no or malformed reply');
+            if (d.noJack) throw new NoQwiicJack(d.message);
+            if (!d.ok)
+                throw new Error(
+                    'GET_I2C_SCAN failed: ' +
+                        d.statusText +
+                        (d.message ? ' (' + d.message + ')' : '')
+                );
+            return d.addresses;
+        }
+
+        /** Write `wbytes` then read `rlen` bytes (repeated start). Throws I2CError. */
+        async function xfer(addr, wbytes, rlen) {
+            const n = rlen || 0;
+            const d = Wire.decodeI2cTransfer(
+                await send(
+                    Wire.encodeI2cTransfer(addr, wbytes || [], n),
+                    Object.assign({}, sendOpts, { timeoutMs })
+                )
+            );
+            if (!d) throw new Error('I2C_TRANSFER ' + hex2(addr) + ': no or malformed reply');
+            if (d.noJack) throw new NoQwiicJack(d.message);
+            if (!d.ok) throw new I2CError(d.status, addr, d.message);
+            if (d.data.length !== n)
+                throw new I2CError(5, addr, 'got ' + d.data.length + ' of ' + n + ' bytes');
+            return d.data;
+        }
+
+        async function ack(addr) {
+            try {
+                await xfer(addr, [], 0);
+                return true;
+            } catch (e) {
+                if (e instanceof I2CError && e.status === 2) return false;
+                throw e;
+            }
+        }
+
+        const readReg = (addr, reg, n) => xfer(addr, [reg], n === undefined ? 1 : n);
+        const writeReg = (addr, reg, data) => xfer(addr, [reg, ...Array.from(data || [])], 0);
+
+        return {
+            exclusive,
+            get held() {
+                return held;
+            },
+            scan,
+            xfer,
+            ack,
+            readReg,
+            writeReg,
+            sleep,
+            now
+        };
+    }
+
+    // little-endian helpers over a Uint8Array
+    const u16 = (b, i) => b[i] | (b[i + 1] << 8);
+    const i16 = (b, i) => {
+        const v = u16(b, i);
+        return v & 0x8000 ? v - 0x10000 : v;
+    };
+    const le16 = (v) => [v & 0xff, (v >> 8) & 0xff];
+
+    // ── address book ────────────────────────────────────────────────────────
+
+    const MCP4725_ADDR = 0x60; // the arena's AO DAC — lives on Wire, never on the Qwiic Wire1
+    const isMux = (addr) => addr >= 0x70 && addr <= 0x77;
+
+    const ADDRESS_BOOK = {
+        0x10: 'VEML7700 lux',
+        0x29: 'TSL2591 light',
+        0x39: 'AS7343 spectral',
+        0x44: 'SHT4x temperature/humidity',
+        0x6a: 'LSM6DSOX 6-axis IMU (tilt/bump)',
+        0x6b: 'LSM6DSOX 6-axis IMU, SA0 high',
+        0x40: 'PCA9685 16-ch PWM / servo driver',
+        0x18: 'LIS3DH accelerometer (no driver)',
+        0x19: 'LIS3DH accelerometer, SA0 high (no driver)',
+        [MCP4725_ADDR]: 'MCP4725 DAC — the arena AO; must NOT be visible on the Qwiic bus'
+    };
+
+    function describe(addr) {
+        if (isMux(addr))
+            return 'PCA9548 8-ch mux (A2..A0 = ' + (addr - 0x70).toString(2).padStart(3, '0') + ')';
+        return ADDRESS_BOOK[addr] || 'unknown';
+    }
+
+    // ── PCA9548 mux ─────────────────────────────────────────────────────────
+    // UNVERIFIED on hardware (no second SHT4x on the 2026-10-12 bench).
+
+    class PCA9548 {
+        constructor(bus, addr) {
+            this.bus = bus;
+            this.addr = addr === undefined ? 0x70 : addr;
+        }
+        async readMask() {
+            return (await this.bus.xfer(this.addr, [], 1))[0];
+        }
+        async select(mask) {
+            await this.bus.xfer(this.addr, [mask & 0xff], 0);
+        }
+        /** Select channel `ch`, run fn, restore the previous mask. */
+        async channel(ch, fn) {
+            const previous = await this.readMask();
+            await this.select(1 << ch);
+            try {
+                return await fn();
+            } finally {
+                await this.select(previous);
+            }
+        }
+        /** {channel: [downstream addrs]} — excludes the root bus. Restores the mask. */
+        async channelMap() {
+            const previous = await this.readMask();
+            try {
+                await this.select(0);
+                const root = new Set(await this.bus.scan());
+                const out = {};
+                for (let ch = 0; ch < 8; ch++) {
+                    await this.select(1 << ch);
+                    out[ch] = (await this.bus.scan())
+                        .filter((a) => !root.has(a))
+                        .sort((a, b) => a - b);
+                }
+                return out;
+            } finally {
+                await this.select(previous);
+            }
+        }
+    }
+
+    /** A located device: {addr, mux: null|addr, channel: null|0..7}. */
+    const located = (addr, mux, channel) => ({
+        addr,
+        mux: mux === undefined ? null : mux,
+        channel: channel === undefined ? null : channel
+    });
+    const where = (dev) =>
+        dev.mux == null ? 'root' : 'mux ' + hex2(dev.mux) + ' ch' + dev.channel;
+    const sameLocation = (a, b) =>
+        a.addr === b.addr &&
+        (a.mux == null ? null : a.mux) === (b.mux == null ? null : b.mux) &&
+        (a.mux == null || a.channel === b.channel);
+
+    /** Run fn with the device reachable (mux channel selected; no-op for root). Caller holds the bus. */
+    async function reach(bus, dev, fn) {
+        if (dev.mux == null) return fn();
+        return new PCA9548(bus, dev.mux).channel(dev.channel, fn);
+    }
+
+    /** exclusive() + reach(): the standard way to talk to one located device. */
+    function withDevice(bus, dev, fn) {
+        return bus.exclusive(() => reach(bus, dev, fn));
+    }
+
+    /** A PCA9548 answers a 1-byte read of its control register. */
+    async function muxResponds(bus, addr) {
+        try {
+            await bus.xfer(addr, [], 1);
+            return true;
+        } catch (e) {
+            if (e instanceof I2CError) return false;
+            throw e;
+        }
+    }
+
+    // ── Sensirion CRC-8 (poly 0x31, init 0xFF) ──────────────────────────────
+
+    function crc8Sensirion(data) {
+        let crc = 0xff;
+        for (const b of data) {
+            crc ^= b;
+            for (let i = 0; i < 8; i++)
+                crc = crc & 0x80 ? ((crc << 1) ^ 0x31) & 0xff : (crc << 1) & 0xff;
+        }
+        return crc;
+    }
+
+    /** [msb lsb crc] × n → {words, ok}. */
+    function unpackSensirionWords(frame) {
+        const words = [];
+        let ok = true;
+        for (let i = 0; i < frame.length; i += 3) {
+            words.push((frame[i] << 8) | frame[i + 1]);
+            ok = ok && crc8Sensirion([frame[i], frame[i + 1]]) === frame[i + 2];
+        }
+        return { words, ok };
+    }
+
+    // ── SHT4x (0x44) ────────────────────────────────────────────────────────
+
+    class SHT4x {
+        constructor(bus, addr) {
+            this.bus = bus;
+            this.addr = addr === undefined ? SHT4x.ADDR : addr;
+        }
+        async _command(cmd, waitMs, rlen) {
+            await this.bus.xfer(this.addr, [cmd], 0); // write leg
+            await this.bus.sleep(waitMs);
+            return this.bus.xfer(this.addr, [], rlen === undefined ? 6 : rlen); // separate read leg
+        }
+        async identify() {
+            const { words, ok } = unpackSensirionWords(await this._command(SHT4x.CMD_SERIAL, 2));
+            return { serial: ((words[0] << 16) | words[1]) >>> 0, crc_ok: ok };
+        }
+        async softReset() {
+            await this.bus.xfer(this.addr, [SHT4x.CMD_SOFT_RESET], 0);
+            await this.bus.sleep(2);
+        }
+        /** Datasheet 4.6; RH clipped to 0..100. */
+        static convert(tRaw, rhRaw) {
+            const t = -45.0 + (175.0 * tRaw) / 65535.0;
+            const rh = Math.min(100.0, Math.max(0.0, -6.0 + (125.0 * rhRaw) / 65535.0));
+            return [t, rh];
+        }
+        async read(cmd) {
+            const c = cmd === undefined ? SHT4x.CMD_MEASURE_HIGH : cmd;
+            const { words, ok } = unpackSensirionWords(
+                await this._command(c, SHT4x.MEASURE_WAIT_MS[c])
+            );
+            const [t, rh] = SHT4x.convert(words[0], words[1]);
+            return { temp_c: t, rh_pct: rh, t_raw: words[0], rh_raw: words[1], crc_ok: ok };
+        }
+    }
+    SHT4x.ADDR = 0x44;
+    SHT4x.CMD_MEASURE_HIGH = 0xfd;
+    SHT4x.CMD_MEASURE_MED = 0xf6;
+    SHT4x.CMD_MEASURE_LOW = 0xe0;
+    SHT4x.CMD_SERIAL = 0x89;
+    SHT4x.CMD_SOFT_RESET = 0x94;
+    SHT4x.MEASURE_WAIT_MS = { 0xfd: 10, 0xf6: 6, 0xe0: 3 };
+
+    // ── LSM6DSOX (0x6A; SA0 high → 0x6B) ────────────────────────────────────
+
+    class LSM6DSOX {
+        constructor(bus, addr) {
+            this.bus = bus;
+            this.addr = addr === undefined ? LSM6DSOX.ADDR : addr;
+            this.fsG = 2;
+            this.fsDps = 250;
+        }
+        async identify() {
+            const who = (await this.bus.readReg(this.addr, LSM6DSOX.REG_WHO_AM_I))[0];
+            return { who_am_i: who, id_ok: who === LSM6DSOX.WHO_AM_I_EXPECTED };
+        }
+        async configure(o) {
+            const c = Object.assign(
+                { odr_hz: 104, fs_g: 2, gyro_odr_hz: 104, fs_dps: 250 },
+                o || {}
+            );
+            const L = LSM6DSOX;
+            if (!(c.odr_hz in L.ODR_CODE) || !(c.gyro_odr_hz in L.ODR_CODE))
+                throw new RangeError('LSM6DSOX: unsupported ODR');
+            if (!(c.fs_g in L.FS_XL_CODE) || !(c.fs_dps in L.FS_G_CODE))
+                throw new RangeError('LSM6DSOX: unsupported full scale');
+            this.fsG = c.fs_g;
+            this.fsDps = c.fs_dps;
+            await this.bus.writeReg(this.addr, L.REG_CTRL3_C, [L.CTRL3_BDU | L.CTRL3_IF_INC]);
+            await this.bus.writeReg(this.addr, L.REG_CTRL1_XL, [
+                (L.ODR_CODE[c.odr_hz] << 4) | (L.FS_XL_CODE[c.fs_g] << 2)
+            ]);
+            await this.bus.writeReg(this.addr, L.REG_CTRL2_G, [
+                (L.ODR_CODE[c.gyro_odr_hz] << 4) | (L.FS_G_CODE[c.fs_dps] << 2)
+            ]);
+            await this.bus.sleep((2.5 / Math.max(c.odr_hz, 12.5) + 0.01) * 1000); // first samples after the ODR change
+        }
+        get accelGPerLsb() {
+            return { 2: 0.061e-3, 4: 0.122e-3, 8: 0.244e-3, 16: 0.488e-3 }[this.fsG];
+        }
+        get gyroDpsPerLsb() {
+            return { 250: 8.75e-3, 500: 17.5e-3, 1000: 35e-3, 2000: 70e-3 }[this.fsDps];
+        }
+        /** One 14-byte block: temp + gyro + accel. */
+        async read() {
+            const b = await this.bus.readReg(this.addr, LSM6DSOX.REG_OUT_TEMP_L, 14);
+            const v = [];
+            for (let i = 0; i < 7; i++) v.push(i16(b, 2 * i));
+            const [tempRaw, gx, gy, gz, ax, ay, az] = v;
+            const a = [ax, ay, az].map((x) => x * this.accelGPerLsb);
+            const g = [gx, gy, gz].map((x) => x * this.gyroDpsPerLsb);
+            return Object.assign(
+                {
+                    accel_g: a,
+                    gyro_dps: g,
+                    temp_c: 25.0 + tempRaw / 256.0,
+                    accel_raw: [ax, ay, az]
+                },
+                LSM6DSOX.tilt(a)
+            );
+        }
+        /** Inclination from the gravity vector (degrees). |a| ≈ 1 g when still. */
+        static tilt(a) {
+            const [ax, ay, az] = a;
+            const norm = Math.sqrt(ax * ax + ay * ay + az * az);
+            const deg = (r) => (r * 180) / Math.PI;
+            if (norm === 0)
+                return { pitch_deg: NaN, roll_deg: NaN, from_vertical_deg: NaN, accel_norm_g: 0 };
+            return {
+                pitch_deg: deg(Math.atan2(ax, Math.sqrt(ay * ay + az * az))),
+                roll_deg: deg(Math.atan2(ay, az)),
+                from_vertical_deg: deg(Math.acos(Math.max(-1, Math.min(1, Math.abs(az) / norm)))),
+                accel_norm_g: norm
+            };
+        }
+        /** Latched wake-up "bumped" flag. Threshold resolution FS/64 (31.25 mg at ±2 g). */
+        async armBump(thresholdG) {
+            const L = LSM6DSOX;
+            const lsb = this.fsG / 64.0;
+            const ths = Math.max(
+                0,
+                Math.min(63, Math.round((thresholdG === undefined ? 0.25 : thresholdG) / lsb))
+            );
+            await this.bus.writeReg(this.addr, L.REG_WAKE_UP_DUR, [0x00]);
+            await this.bus.writeReg(this.addr, L.REG_WAKE_UP_THS, [ths]);
+            await this.bus.writeReg(this.addr, L.REG_TAP_CFG0, [
+                L.TAP_CFG0_LIR | L.TAP_CFG0_INT_CLR_ON_READ
+            ]);
+            await this.bus.writeReg(this.addr, L.REG_MD1_CFG, [L.MD1_CFG_INT1_WU]); // routing is what latches
+            await this.bus.writeReg(this.addr, L.REG_TAP_CFG2, [L.TAP_CFG2_INTERRUPTS_ENABLE]);
+            await this.bumpFlag(); // clear anything latched while arming
+            return ths;
+        }
+        async disarmBump() {
+            const L = LSM6DSOX;
+            await this.bus.writeReg(this.addr, L.REG_TAP_CFG2, [0]);
+            await this.bus.writeReg(this.addr, L.REG_MD1_CFG, [0]);
+            await this.bus.writeReg(this.addr, L.REG_TAP_CFG0, [0]);
+        }
+        /** READ-AND-CLEAR. One owner only. */
+        async bumpFlag() {
+            const src = (await this.bus.readReg(this.addr, LSM6DSOX.REG_WAKE_UP_SRC))[0];
+            const axes = [
+                ['X', 4],
+                ['Y', 2],
+                ['Z', 1]
+            ]
+                .filter(([, bit]) => src & bit)
+                .map(([n]) => n)
+                .join('');
+            return { bumped: !!(src & LSM6DSOX.WAKE_UP_SRC_WU_IA), axes, raw: src };
+        }
+        async powerOff() {
+            await this.disarmBump();
+            await this.bus.writeReg(this.addr, LSM6DSOX.REG_CTRL1_XL, [0]);
+            await this.bus.writeReg(this.addr, LSM6DSOX.REG_CTRL2_G, [0]);
+        }
+    }
+    Object.assign(LSM6DSOX, {
+        ADDR: 0x6a,
+        ADDR_ALT: 0x6b,
+        WHO_AM_I_EXPECTED: 0x6c,
+        REG_WHO_AM_I: 0x0f,
+        REG_CTRL1_XL: 0x10,
+        REG_CTRL2_G: 0x11,
+        REG_CTRL3_C: 0x12,
+        REG_WAKE_UP_SRC: 0x1b,
+        REG_OUT_TEMP_L: 0x20,
+        REG_TAP_CFG0: 0x56,
+        REG_TAP_CFG2: 0x58,
+        REG_WAKE_UP_THS: 0x5b,
+        REG_WAKE_UP_DUR: 0x5c,
+        REG_MD1_CFG: 0x5e,
+        CTRL3_BDU: 0x40,
+        CTRL3_IF_INC: 0x04,
+        ODR_CODE: { 0: 0x0, 12.5: 0x1, 26: 0x2, 52: 0x3, 104: 0x4, 208: 0x5, 416: 0x6 },
+        FS_XL_CODE: { 2: 0x0, 16: 0x1, 4: 0x2, 8: 0x3 },
+        FS_G_CODE: { 250: 0x0, 500: 0x1, 1000: 0x2, 2000: 0x3 },
+        TAP_CFG0_LIR: 0x01,
+        TAP_CFG0_INT_CLR_ON_READ: 0x40,
+        TAP_CFG2_INTERRUPTS_ENABLE: 0x80,
+        MD1_CFG_INT1_WU: 0x20,
+        WAKE_UP_SRC_WU_IA: 0x08
+    });
+
+    // ── TSL2591 (0x29) ──────────────────────────────────────────────────────
+
+    class TSL2591 {
+        constructor(bus, addr) {
+            this.bus = bus;
+            this.addr = addr === undefined ? TSL2591.ADDR : addr;
+            this.gain = 'med';
+            this.atimeMs = 100;
+        }
+        _rd(reg, n) {
+            return this.bus.readReg(this.addr, TSL2591.CMD | reg, n);
+        }
+        _wr(reg, v) {
+            return this.bus.writeReg(this.addr, TSL2591.CMD | reg, [v]);
+        }
+        async identify() {
+            const v = (await this._rd(TSL2591.REG_ID, 1))[0];
+            return { id: v, id_ok: v === TSL2591.ID_EXPECTED };
+        }
+        async configure(o) {
+            const c = Object.assign({ gain: 'med', atime_ms: 100 }, o || {});
+            if (!(c.gain in TSL2591.GAIN))
+                throw new RangeError('TSL2591 gain must be low|med|high|max');
+            if (!(c.atime_ms in TSL2591.ATIME))
+                throw new RangeError('TSL2591 atime_ms must be 100..600 in 100s');
+            this.gain = c.gain;
+            this.atimeMs = Number(c.atime_ms);
+            await this._wr(
+                TSL2591.REG_CONTROL,
+                TSL2591.GAIN[c.gain][0] | TSL2591.ATIME[c.atime_ms]
+            );
+            await this._wr(TSL2591.REG_ENABLE, TSL2591.ENABLE_PON | TSL2591.ENABLE_AEN);
+            await this.bus.sleep(this.atimeMs * 1.2 + 50);
+        }
+        /** ADC full scale: 36863 at 100 ms integration, 65535 otherwise (datasheet § ALS ADC). */
+        static ceilingFor(atimeMs) {
+            return Number(atimeMs) === 100 ? 36863 : 65535;
+        }
+        get ceiling() {
+            return TSL2591.ceilingFor(this.atimeMs);
+        }
+        /** Pure decode, shared by read() and the tests. */
+        decode(status, full, ir) {
+            const sat = full >= this.ceiling || ir >= this.ceiling;
+            const out = {
+                full,
+                ir,
+                visible: full - ir,
+                sat,
+                valid: !!(status & 0x01),
+                lux_approx: null
+            };
+            if (full > 0 && !sat) {
+                const cpl = (this.atimeMs * TSL2591.GAIN[this.gain][1]) / 408.0;
+                out.lux_approx = ((full - ir) * (1.0 - ir / full)) / cpl;
+            }
+            return out;
+        }
+        async read() {
+            const status = (await this._rd(TSL2591.REG_STATUS, 1))[0];
+            const b = await this._rd(TSL2591.REG_C0DATAL, 4);
+            return this.decode(status, u16(b, 0), u16(b, 2));
+        }
+        async powerOff() {
+            await this._wr(TSL2591.REG_ENABLE, 0);
+        }
+    }
+    Object.assign(TSL2591, {
+        ADDR: 0x29,
+        CMD: 0xa0,
+        REG_ENABLE: 0x00,
+        REG_CONTROL: 0x01,
+        REG_ID: 0x12,
+        REG_STATUS: 0x13,
+        REG_C0DATAL: 0x14,
+        ID_EXPECTED: 0x50,
+        ENABLE_PON: 0x01,
+        ENABLE_AEN: 0x02,
+        GAIN: { low: [0x00, 1.0], med: [0x10, 25.0], high: [0x20, 428.0], max: [0x30, 9876.0] },
+        ATIME: { 100: 0x00, 200: 0x01, 300: 0x02, 400: 0x03, 500: 0x04, 600: 0x05 }
+    });
+
+    // ── VEML7700 (0x10) ─────────────────────────────────────────────────────
+
+    class VEML7700 {
+        constructor(bus, addr) {
+            this.bus = bus;
+            this.addr = addr === undefined ? VEML7700.ADDR : addr;
+        }
+        async read16(reg) {
+            return u16(await this.bus.readReg(this.addr, reg, 2), 0);
+        }
+        async identify() {
+            const v = await this.read16(VEML7700.REG_ID);
+            // Early silicon has no ID register, so a mismatch is reported, not failed.
+            return {
+                id_raw: v,
+                device_id: v & 0xff,
+                device_id_ok: (v & 0xff) === VEML7700.DEVICE_ID_EXPECTED
+            };
+        }
+        async configure() {
+            await this.bus.writeReg(this.addr, VEML7700.REG_CONF, le16(VEML7700.CONF_GAIN1_IT100));
+            await this.bus.sleep(250); // > 2 integration windows at 100 ms
+        }
+        async read() {
+            const als = await this.read16(VEML7700.REG_ALS);
+            const white = await this.read16(VEML7700.REG_WHITE);
+            return {
+                als,
+                white,
+                lux_approx: als * VEML7700.LUX_PER_COUNT_GAIN1_IT100,
+                sat: als >= 0xffff || white >= 0xffff
+            };
+        }
+    }
+    Object.assign(VEML7700, {
+        ADDR: 0x10,
+        REG_CONF: 0x00,
+        REG_ALS: 0x04,
+        REG_WHITE: 0x05,
+        REG_ID: 0x07,
+        CONF_GAIN1_IT100: 0x0000,
+        LUX_PER_COUNT_GAIN1_IT100: 0.0576,
+        DEVICE_ID_EXPECTED: 0x81
+    });
+
+    // ── AS7343 (0x39) ───────────────────────────────────────────────────────
+
+    class AS7343 {
+        constructor(bus, addr) {
+            this.bus = bus;
+            this.addr = addr === undefined ? AS7343.ADDR : addr;
+            this.fullScale = 65535;
+            this.tintMs = 50.0;
+            this.gain = 256;
+            this._startedAt = null;
+        }
+        _wr(reg, v) {
+            return this.bus.writeReg(this.addr, reg, Array.isArray(v) ? v : [v]);
+        }
+        async identify() {
+            const A = AS7343;
+            await this._wr(A.REG_CFG0, A.CFG0_REG_BANK); // registers < 0x80 need bank 1
+            let b;
+            try {
+                b = await this.bus.readReg(this.addr, A.REG_AUXID, 3);
+            } finally {
+                await this._wr(A.REG_CFG0, 0x00);
+            }
+            return { auxid: b[0], revid: b[1], id: b[2], id_ok: b[2] === A.ID_EXPECTED };
+        }
+        async configure(o) {
+            const A = AS7343;
+            const c = Object.assign({ gain: 256, atime: 29, astep: 599 }, o || {});
+            if (!(c.gain in A.GAIN_CODE))
+                throw new RangeError(
+                    'AS7343 gain must be one of ' + Object.keys(A.GAIN_CODE).join(', ')
+                );
+            await this._wr(A.REG_CFG0, 0x00);
+            await this._wr(A.REG_ENABLE, A.ENABLE_PON);
+            await this._wr(A.REG_ATIME, c.atime);
+            await this._wr(A.REG_ASTEP_L, le16(c.astep));
+            await this._wr(A.REG_CFG1, A.GAIN_CODE[c.gain]);
+            await this._wr(A.REG_CFG20, A.CFG20_AUTO_SMUX_18);
+            this.gain = Number(c.gain);
+            this.fullScale = Math.min(65535, (c.atime + 1) * (c.astep + 1));
+            this.tintMs = ((c.atime + 1) * (c.astep + 1) * A.STEP_US) / 1000.0;
+        }
+        /** One 18-channel measurement = three SMUX cycles. */
+        get frameMs() {
+            return 3 * this.tintMs;
+        }
+        /** Kick off a measurement; the part integrates on its own until collect(). */
+        async start() {
+            const A = AS7343;
+            await this._wr(A.REG_ENABLE, A.ENABLE_PON);
+            const status = (await this.bus.readReg(this.addr, A.REG_STATUS, 1))[0];
+            await this._wr(A.REG_STATUS, status); // clear sticky flags
+            await this._wr(A.REG_ENABLE, A.ENABLE_PON | A.ENABLE_SP_EN);
+            this._startedAt = this.bus.now();
+        }
+        /** ms left before the frame can be valid (callers sleep this WITHOUT holding the bus). */
+        remainingMs() {
+            if (this._startedAt == null) return 0;
+            return Math.max(0, this._startedAt + this.frameMs - this.bus.now());
+        }
+        /** Poll AVALID, latch + read 18 channels, stop. Caller already slept remainingMs(). */
+        async collect(timeoutMs) {
+            const A = AS7343;
+            const deadline = this.bus.now() + (timeoutMs || 2000);
+            let status2;
+            try {
+                for (;;) {
+                    status2 = (await this.bus.readReg(this.addr, A.REG_STATUS2, 1))[0];
+                    if (status2 & A.STATUS2_AVALID) break;
+                    if (this.bus.now() > deadline) throw new Error('AS7343: AVALID never set');
+                    await this.bus.sleep(2);
+                }
+                const block = await this.bus.readReg(
+                    this.addr,
+                    A.REG_ASTATUS,
+                    1 + 2 * A.CHANNELS.length
+                );
+                return this.decode(block, status2);
+            } finally {
+                await this._wr(A.REG_ENABLE, A.ENABLE_PON);
+                this._startedAt = null;
+            }
+        }
+        decode(block, status2) {
+            const A = AS7343;
+            const channels = {};
+            A.CHANNELS.forEach((name, i) => (channels[name] = u16(block, 1 + 2 * i)));
+            const spectral = {};
+            A.SPECTRAL.forEach((k) => (spectral[k] = channels[k]));
+            const vis = A.CHANNELS.filter((k) => k.startsWith('VIS')).map((k) => channels[k]);
+            const fd = A.CHANNELS.filter((k) => k.startsWith('FD')).map((k) => channels[k]);
+            const mean = (xs) => xs.reduce((s, x) => s + x, 0) / xs.length;
+            return {
+                channels,
+                spectral,
+                vis: mean(vis),
+                fd: mean(fd),
+                sat: Math.max(...Object.values(spectral)) >= this.fullScale,
+                sat_vis: Math.max(...vis) >= this.fullScale,
+                asat_flags: (status2 & A.STATUS2_ASAT) | (block[0] & 0x80),
+                full_scale: this.fullScale,
+                tint_ms: this.tintMs
+            };
+        }
+        async powerOff() {
+            await this._wr(AS7343.REG_ENABLE, 0);
+        }
+    }
+    Object.assign(AS7343, {
+        ADDR: 0x39,
+        REG_AUXID: 0x58,
+        REG_ENABLE: 0x80,
+        REG_ATIME: 0x81,
+        REG_STATUS2: 0x90,
+        REG_STATUS: 0x93,
+        REG_ASTATUS: 0x94,
+        REG_CFG0: 0xbf,
+        REG_CFG1: 0xc6,
+        REG_ASTEP_L: 0xd4,
+        REG_CFG20: 0xd6,
+        CFG0_REG_BANK: 0x10,
+        ENABLE_PON: 0x01,
+        ENABLE_SP_EN: 0x02,
+        STATUS2_AVALID: 0x40,
+        STATUS2_ASAT: 0x18,
+        CFG20_AUTO_SMUX_18: 3 << 5,
+        ID_EXPECTED: 0x81,
+        GAIN_CODE: {
+            0.5: 0,
+            1: 1,
+            2: 2,
+            4: 3,
+            8: 4,
+            16: 5,
+            32: 6,
+            64: 7,
+            128: 8,
+            256: 9,
+            512: 10,
+            1024: 11,
+            2048: 12
+        },
+        STEP_US: 2.78,
+        // 18-ch auto-SMUX order (3 cycles × 6 ADCs); VIS = clear, FD = flicker (not light, kept out of sat).
+        CHANNELS: [
+            'FZ_450',
+            'FY_555',
+            'FXL_600',
+            'NIR_855',
+            'VIS0',
+            'FD0',
+            'F2_425',
+            'F3_475',
+            'F4_515',
+            'F6_640',
+            'VIS1',
+            'FD1',
+            'F1_405',
+            'F7_690',
+            'F8_745',
+            'F5_550',
+            'VIS2',
+            'FD2'
+        ],
+        SPECTRAL: [
+            'F1_405',
+            'F2_425',
+            'FZ_450',
+            'F3_475',
+            'F4_515',
+            'F5_550',
+            'FY_555',
+            'FXL_600',
+            'F6_640',
+            'F7_690',
+            'F8_745',
+            'NIR_855'
+        ]
+    });
+
+    // ── PCA9685 (0x40 default) ──────────────────────────────────────────────
+
+    class PCA9685 {
+        constructor(bus, addr) {
+            this.bus = bus;
+            this.addr = addr === undefined ? PCA9685.ADDR : addr;
+            this.freqHz = 200.0; // POR prescale 0x1E
+            this.configured = false;
+        }
+        async identify() {
+            const P = PCA9685;
+            const mode1 = (await this.bus.readReg(this.addr, P.REG_MODE1))[0];
+            const prescale = (await this.bus.readReg(this.addr, P.REG_PRESCALE))[0];
+            return {
+                mode1,
+                prescale,
+                freq_hz: P.freqForPrescale(prescale),
+                sleeping: !!(mode1 & P.MODE1_SLEEP),
+                allcall: !!(mode1 & P.MODE1_ALLCALL)
+            };
+        }
+        static prescaleFor(freqHz) {
+            return Math.max(
+                3,
+                Math.min(255, Math.round(PCA9685.OSC_HZ / (PCA9685.COUNTS * freqHz)) - 1)
+            );
+        }
+        static freqForPrescale(prescale) {
+            return PCA9685.OSC_HZ / (PCA9685.COUNTS * (prescale + 1));
+        }
+        /** Set PWM frequency (prescale only writable in SLEEP), wake, auto-increment, ALLCALL off. */
+        async configure(o) {
+            const P = PCA9685;
+            const freq = (o && o.freq_hz) || 50.0;
+            const mode1 =
+                (await this.bus.readReg(this.addr, P.REG_MODE1))[0] & ~P.MODE1_RESTART & 0xff;
+            await this.bus.writeReg(this.addr, P.REG_MODE1, [
+                (mode1 | P.MODE1_SLEEP) & ~P.MODE1_ALLCALL & 0xff
+            ]);
+            await this.bus.writeReg(this.addr, P.REG_PRESCALE, [P.prescaleFor(freq)]);
+            await this.bus.writeReg(this.addr, P.REG_MODE1, [
+                (mode1 | P.MODE1_AI) & ~P.MODE1_SLEEP & ~P.MODE1_ALLCALL & 0xff
+            ]);
+            await this.bus.sleep(1); // oscillator start-up ≥ 500 µs
+            await this.bus.writeReg(this.addr, P.REG_MODE1, [
+                (mode1 | P.MODE1_AI | P.MODE1_RESTART) & ~P.MODE1_SLEEP & ~P.MODE1_ALLCALL & 0xff
+            ]);
+            this.freqHz = P.freqForPrescale(P.prescaleFor(freq));
+            this.configured = true;
+        }
+        async setCounts(channel, on, off) {
+            if (!(Number.isInteger(channel) && channel >= 0 && channel < PCA9685.CHANNELS))
+                throw new RangeError('channel ' + channel + ' out of 0..15');
+            await this.bus.writeReg(this.addr, PCA9685.REG_LED0_ON_L + 4 * channel, [
+                ...le16(on & 0x1fff),
+                ...le16(off & 0x1fff)
+            ]);
+        }
+        async readCounts(channel) {
+            const b = await this.bus.readReg(this.addr, PCA9685.REG_LED0_ON_L + 4 * channel, 4);
+            return [u16(b, 0), u16(b, 2)];
+        }
+        pulseToCounts(pulseUs) {
+            return Math.max(
+                0,
+                Math.min(
+                    PCA9685.COUNTS - 1,
+                    Math.round(pulseUs * 1e-6 * this.freqHz * PCA9685.COUNTS)
+                )
+            );
+        }
+        /** Hobby servo: ~1000–2000 µs within a 20 ms (50 Hz) frame. Returns the OFF count. */
+        async setPulseUs(channel, pulseUs) {
+            const off = this.pulseToCounts(pulseUs);
+            await this.setCounts(channel, 0, off);
+            return off;
+        }
+        /** Full OFF (LEDn_OFF_H bit 4): the servo goes limp. */
+        async setOff(channel) {
+            await this.setCounts(channel, 0, 0x1000);
+        }
+        async allOff() {
+            await this.bus.writeReg(this.addr, PCA9685.REG_ALL_LED_ON_L, [0, 0, 0x00, 0x10]);
+        }
+        async sleep() {
+            const mode1 = (await this.bus.readReg(this.addr, PCA9685.REG_MODE1))[0];
+            await this.bus.writeReg(this.addr, PCA9685.REG_MODE1, [
+                (mode1 | PCA9685.MODE1_SLEEP) & ~PCA9685.MODE1_RESTART & 0xff
+            ]);
+        }
+    }
+    Object.assign(PCA9685, {
+        ADDR: 0x40,
+        ALLCALL_ADDR: 0x70,
+        REG_MODE1: 0x00,
+        REG_LED0_ON_L: 0x06,
+        REG_ALL_LED_ON_L: 0xfa,
+        REG_PRESCALE: 0xfe,
+        MODE1_RESTART: 0x80,
+        MODE1_AI: 0x20,
+        MODE1_SLEEP: 0x10,
+        MODE1_ALLCALL: 0x01,
+        OSC_HZ: 25000000,
+        CHANNELS: 16,
+        COUNTS: 4096
+    });
+
+    /**
+     * The address a PCA9685 is shadowing with its all-call (0x70 while MODE1.ALLCALL
+     * is set — reads included), or null. Decided from MODE1, never from a read probe.
+     */
+    async function pca9685AllcallShadow(bus, scan) {
+        if (!scan.includes(PCA9685.ADDR) || !scan.includes(PCA9685.ALLCALL_ADDR)) return null;
+        try {
+            const mode1 = (await bus.readReg(PCA9685.ADDR, PCA9685.REG_MODE1))[0];
+            return mode1 & PCA9685.MODE1_ALLCALL ? PCA9685.ALLCALL_ADDR : null;
+        } catch (e) {
+            if (e instanceof I2CError) return null;
+            throw e;
+        }
+    }
+
+    /**
+     * Scan the root bus, map every real mux's channels. Holds the bus for the whole
+     * walk. → { scan: [root addrs], shadow: addr|null, devices: [located…] }.
+     */
+    function locateDevices(bus) {
+        return bus.exclusive(async () => {
+            const root = await bus.scan();
+            const devices = root.map((a) => located(a));
+            const shadow = await pca9685AllcallShadow(bus, root);
+            for (const muxAddr of root) {
+                if (!isMux(muxAddr) || muxAddr === shadow || !(await muxResponds(bus, muxAddr)))
+                    continue;
+                const map = await new PCA9548(bus, muxAddr).channelMap();
+                for (const ch of Object.keys(map))
+                    for (const a of map[ch]) devices.push(located(a, muxAddr, Number(ch)));
+            }
+            return { scan: root, shadow, devices };
+        });
+    }
+
+    // ── KINDS registry ──────────────────────────────────────────────────────
+    // One entry per supported part — the ONLY place to add or drop one.
+    //   role:     env | tilt | light | actuator (consumers pick by role, never by part)
+    //   identify: (driver) → {ok, detail, info}            caller holds the bus
+    //   setup:    (driver, config, {forRun}) → applied cfg  caller holds the bus
+    //   read:     (bus, dev, driver) → reading             takes the bus ITSELF
+    //   display:  readout fields [{key, label, unit, digits|fmt}]
+    //   columns:  numeric log columns (keys into values())
+    //   values:   (reading) → {column: number|null}
+
+    const n = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+    const simpleRead = (bus, dev, s) => withDevice(bus, dev, () => s.read());
+
+    const KINDS = {
+        sht4x: {
+            kind: 'sht4x',
+            label: 'SHT4x',
+            title: 'SHT4x temperature / humidity',
+            role: 'env',
+            addresses: [0x44],
+            Driver: SHT4x,
+            async identify(s) {
+                const r = await s.identify();
+                const serial = '0x' + r.serial.toString(16).toUpperCase().padStart(8, '0');
+                return {
+                    ok: r.crc_ok,
+                    detail: 'serial ' + serial + (r.crc_ok ? '' : ' (CRC FAIL)'),
+                    info: { serial }
+                };
+            },
+            async setup() {
+                return {};
+            },
+            read: simpleRead,
+            display: [
+                { key: 'temp_c', label: 'Temperature', unit: '°C', digits: 2 },
+                { key: 'rh_pct', label: 'Humidity', unit: '%RH', digits: 1 },
+                { key: 'crc_ok', label: 'CRC', fmt: 'okfail' }
+            ],
+            columns: ['temp_c', 'rh_pct'],
+            values: (r) => ({ temp_c: n(r.temp_c), rh_pct: n(r.rh_pct) })
+        },
+        lsm6dsox: {
+            kind: 'lsm6dsox',
+            label: 'LSM6DSOX',
+            title: 'LSM6DSOX IMU — tilt + bump latch',
+            role: 'tilt',
+            addresses: [0x6a, 0x6b],
+            Driver: LSM6DSOX,
+            async identify(s) {
+                const r = await s.identify();
+                return {
+                    ok: r.id_ok,
+                    detail: 'WHO_AM_I ' + hex2(r.who_am_i) + ' (expect 0x6C)',
+                    info: {}
+                };
+            },
+            // Tilt always; the bump latch only when asked (it is read-to-clear: one owner).
+            async setup(s, cfg, ctx) {
+                await s.configure({ odr_hz: 104 });
+                const applied = { odr_hz: 104 };
+                if (ctx && ctx.armBump) {
+                    applied.bump_g = (cfg && cfg.bump_g) || 0.25;
+                    applied.bump_ths = await s.armBump(applied.bump_g);
+                }
+                return applied;
+            },
+            read: simpleRead,
+            display: [
+                { key: 'from_vertical_deg', label: 'Tilt from vertical', unit: '°', digits: 1 },
+                { key: 'pitch_deg', label: 'Pitch', unit: '°', digits: 1, signed: true },
+                { key: 'roll_deg', label: 'Roll', unit: '°', digits: 1, signed: true },
+                { key: 'accel_norm_g', label: '|a|', unit: 'g', digits: 3 },
+                { key: 'temp_c', label: 'Die temperature', unit: '°C', digits: 1 }
+            ],
+            columns: ['from_vertical_deg', 'pitch_deg', 'roll_deg', 'accel_norm_g', 'temp_c'],
+            values: (r) => ({
+                from_vertical_deg: n(r.from_vertical_deg),
+                pitch_deg: n(r.pitch_deg),
+                roll_deg: n(r.roll_deg),
+                accel_norm_g: n(r.accel_norm_g),
+                temp_c: n(r.temp_c)
+            }),
+            hasBump: true
+        },
+        tsl2591: {
+            kind: 'tsl2591',
+            label: 'TSL2591',
+            title: 'TSL2591 broadband light',
+            role: 'light',
+            addresses: [0x29],
+            Driver: TSL2591,
+            async identify(s) {
+                const r = await s.identify();
+                return { ok: r.id_ok, detail: 'ID ' + hex2(r.id) + ' (expect 0x50)', info: {} };
+            },
+            async setup(s, cfg) {
+                const c = {
+                    gain: (cfg && cfg.gain) || 'med',
+                    atime_ms: (cfg && cfg.atime_ms) || 100
+                };
+                await s.configure(c);
+                return c;
+            },
+            read: simpleRead,
+            options: {
+                gain: { label: 'Gain', values: ['low', 'med', 'high', 'max'], default: 'med' },
+                atime_ms: {
+                    label: 'Integration (ms)',
+                    values: [100, 200, 300, 400, 500, 600],
+                    default: 100
+                }
+            },
+            display: [
+                { key: 'full', label: 'Full (C0)', unit: 'counts', digits: 0 },
+                { key: 'ir', label: 'IR (C1)', unit: 'counts', digits: 0 },
+                { key: 'lux_approx', label: 'Lux (approx.)', unit: 'lx', digits: 1 },
+                { key: 'sat', label: 'Saturated', fmt: 'flag' }
+            ],
+            columns: ['full', 'ir', 'lux_approx'],
+            values: (r) => ({ full: n(r.full), ir: n(r.ir), lux_approx: n(r.lux_approx) })
+        },
+        veml7700: {
+            kind: 'veml7700',
+            label: 'VEML7700',
+            title: 'VEML7700 ambient light',
+            role: 'light',
+            addresses: [0x10],
+            Driver: VEML7700,
+            async identify(s) {
+                const r = await s.identify();
+                // early silicon has no ID register → reported, never failed
+                const id = '0x' + r.id_raw.toString(16).toUpperCase().padStart(4, '0');
+                return {
+                    ok: true,
+                    detail:
+                        'ID reg ' +
+                        id +
+                        (r.device_id_ok ? ' ok' : ' (0x81 expected on current silicon)'),
+                    info: {}
+                };
+            },
+            async setup(s) {
+                await s.configure();
+                return { gain: 1, it_ms: 100 };
+            },
+            read: simpleRead,
+            display: [
+                { key: 'als', label: 'ALS', unit: 'counts', digits: 0 },
+                { key: 'white', label: 'White', unit: 'counts', digits: 0 },
+                { key: 'lux_approx', label: 'Lux (approx.)', unit: 'lx', digits: 1 },
+                { key: 'sat', label: 'Saturated', fmt: 'flag' }
+            ],
+            columns: ['als', 'white', 'lux_approx'],
+            values: (r) => ({ als: n(r.als), white: n(r.white), lux_approx: n(r.lux_approx) })
+        },
+        as7343: {
+            kind: 'as7343',
+            label: 'AS7343',
+            title: 'AS7343 14-channel spectral',
+            role: 'light',
+            addresses: [0x39],
+            Driver: AS7343,
+            async identify(s) {
+                const r = await s.identify();
+                return {
+                    ok: r.id_ok,
+                    detail: 'ID ' + hex2(r.id) + ' (expect 0x81) rev ' + hex2(r.revid),
+                    info: {}
+                };
+            },
+            async setup(s, cfg) {
+                const c = { gain: (cfg && cfg.gain) || 64 };
+                await s.configure(c);
+                return c;
+            },
+            // start → release the bus while it integrates (~150 ms) → collect.
+            async read(bus, dev, s) {
+                await withDevice(bus, dev, () => s.start());
+                const wait = s.remainingMs();
+                if (wait > 0) await bus.sleep(wait);
+                return withDevice(bus, dev, () => s.collect());
+            },
+            options: { gain: { label: 'Gain', values: [1, 4, 16, 64, 256, 1024], default: 64 } },
+            display: [
+                { key: 'vis', label: 'Clear (VIS)', unit: 'counts', digits: 0 },
+                { key: 'sat', label: 'Saturated', fmt: 'flag' },
+                { key: 'spectral', label: 'Spectrum', fmt: 'bars' }
+            ],
+            columns: ['vis'].concat(AS7343.SPECTRAL),
+            values: (r) => {
+                const out = { vis: n(r.vis) };
+                AS7343.SPECTRAL.forEach((k) => (out[k] = n(r.spectral[k])));
+                return out;
+            }
+        },
+        pca9685: {
+            kind: 'pca9685',
+            label: 'PCA9685',
+            title: 'PCA9685 servo / PWM driver',
+            role: 'actuator',
+            addresses: [0x40],
+            Driver: PCA9685,
+            async identify(s) {
+                const r = await s.identify();
+                const detail =
+                    'MODE1 ' +
+                    hex2(r.mode1) +
+                    ' prescale ' +
+                    r.prescale +
+                    ' (' +
+                    r.freq_hz.toFixed(0) +
+                    ' Hz)' +
+                    (r.sleeping ? ' SLEEP' : '') +
+                    (r.allcall ? ' ALLCALL' : '');
+                return { ok: true, detail, info: { allcall: r.allcall, sleeping: r.sleeping } }; // no ID register
+            },
+            async setup(s, cfg) {
+                const c = { freq_hz: (cfg && cfg.freq_hz) || 50 };
+                await s.configure(c);
+                return c;
+            },
+            read: (bus, dev, s) => withDevice(bus, dev, () => s.identify()),
+            display: [
+                { key: 'freq_hz', label: 'PWM frequency', unit: 'Hz', digits: 2 },
+                { key: 'sleeping', label: 'Oscillator', fmt: 'sleep' },
+                { key: 'allcall', label: 'All-call 0x70', fmt: 'onoff' }
+            ],
+            columns: [],
+            values: () => ({})
+        }
+    };
+
+    const KIND_BY_ADDR = {};
+    for (const k of Object.values(KINDS)) for (const a of k.addresses) KIND_BY_ADDR[a] = k.kind;
+
+    /** The default kind for an address (the address book), or null. */
+    const kindForAddress = (addr) => KIND_BY_ADDR[addr] || null;
+
+    /** Make the driver instance for a kind at an address. */
+    function createDriver(bus, kind, addr) {
+        const k = KINDS[kind];
+        if (!k) throw new Error('unknown Qwiic kind "' + kind + '"');
+        return new k.Driver(bus, addr === undefined ? k.addresses[0] : addr);
+    }
+
+    /** Identify a located device as `kind` (holds the bus). Never throws: errors → ok:false. */
+    async function identifyDevice(bus, dev, kind, driver) {
+        const k = KINDS[kind];
+        const s = driver || createDriver(bus, kind, dev.addr);
+        try {
+            const r = await withDevice(bus, dev, () => k.identify(s));
+            return Object.assign({ kind, driver: s }, r);
+        } catch (e) {
+            return { kind, driver: s, ok: false, detail: e.message, info: {}, error: e };
+        }
+    }
+
+    const QwiicDrivers = {
+        I2CError,
+        NoQwiicJack,
+        createBus,
+        withDevice,
+        reach,
+        located,
+        where,
+        sameLocation,
+        locateDevices,
+        pca9685AllcallShadow,
+        muxResponds,
+        isMux,
+        describe,
+        hex2,
+        MCP4725_ADDR,
+        crc8Sensirion,
+        unpackSensirionWords,
+        SHT4x,
+        LSM6DSOX,
+        TSL2591,
+        VEML7700,
+        AS7343,
+        PCA9685,
+        PCA9548,
+        KINDS,
+        kindForAddress,
+        createDriver,
+        identifyDevice
+    };
+
+    if (typeof module !== 'undefined' && module.exports) module.exports = QwiicDrivers;
+    global.QwiicDrivers = QwiicDrivers;
+})(typeof window !== 'undefined' ? window : globalThis);
diff --git a/js/studio-qwiic.js b/js/studio-qwiic.js
new file mode 100644
index 00000000..5bf05a0b
--- /dev/null
+++ b/js/studio-qwiic.js
@@ -0,0 +1,608 @@
+/**
+ * studio-qwiic.js — Arena Studio glue for the Qwiic peripherals (LAB-214),
+ * DOM-free so it is Node-testable (tests/test-studio-qwiic.js). The register
+ * maps live in js/qwiic-drivers.js; this file is about the RIG and the CHECK:
+ *
+ *   parseRigPeripherals(rigData)   rig YAML `peripherals:` → {list, warnings}.
+ *                                  Tolerant like parseRigIo: never throws; a bad
+ *                                  entry is dropped with a warning string.
+ *   discover(bus)                  scan + mux map + identify every known part
+ *                                  (the Console Scan, and step 1 of setup).
+ *   checkAgainstScan(declared, d)  BOTH directions: declared-but-missing (error,
+ *                                  never retried) and attached-but-undeclared
+ *                                  (warning flag; Console-only, never logged).
+ *   applySetup(bus, check, opts)   configure the declared, present, identified
+ *                                  parts (PCA9685 ALLCALL off, IMU on, …).
+ *   chipState(state)               the top-bar / rail chip text + level.
+ *   toRigYaml(discovery, opts)     the "Copy as rig YAML" snippet.
+ *   formatField(field, reading)    readout text for one KINDS display field.
+ *
+ * Scan only at SETUP (connect, Console Scan button, run start): GET_I2C_SCAN
+ * stalls the controller loop ~10 ms, so never while a display runs.
+ *
+ * LOADING: classic <script src> after js/qwiic-drivers.js (window-global
+ * `StudioQwiic` + CommonJS), no ES `export` (CLAUDE.md).
+ */
+(function (global) {
+    'use strict';
+
+    const Q =
+        (typeof require === 'function' &&
+            (() => {
+                try {
+                    return require('./qwiic-drivers.js');
+                } catch (_) {
+                    return null;
+                }
+            })()) ||
+        global.QwiicDrivers;
+
+    const hex2 = (a) => '0x' + (a & 0xff).toString(16).toUpperCase().padStart(2, '0');
+    const POLL_INTERVAL_MIN_S = 0.5;
+    const BOARD_BUDGET = 8; // pull-up stack: ~8 Adafruit-class boards (bench 2026-10-12)
+    const SERVO_US_DEFAULT = { min_us: 1000, max_us: 2000 };
+    const SERVO_US_LIMITS = { min_us: 500, max_us: 2500 };
+
+    /** Location key: same address on a different mux channel is a different device. */
+    const locKey = (d) =>
+        (d.mux == null ? 'root' : hex2(d.mux) + '.' + d.channel) + ':' + hex2(d.addr);
+
+    function parseAddress(v) {
+        if (typeof v === 'number' && Number.isInteger(v)) return v;
+        if (typeof v === 'string') {
+            const s = v.trim();
+            if (/^0x[0-9a-f]+$/i.test(s)) return parseInt(s, 16);
+            if (/^\d+$/.test(s)) return parseInt(s, 10);
+        }
+        return null;
+    }
+
+    function parsePoll(raw, label, warnings) {
+        const poll = { trialStart: false, intervalS: null, onDemand: false };
+        const items =
+            raw === undefined || raw === null ? ['on_demand'] : Array.isArray(raw) ? raw : [raw];
+        for (const it of items) {
+            if (it === 'trial_start') poll.trialStart = true;
+            else if (it === 'on_demand') poll.onDemand = true;
+            else if (it && typeof it === 'object' && 'interval' in it) {
+                const s = Number(it.interval);
+                if (!Number.isFinite(s) || s <= 0) {
+                    warnings.push(
+                        label +
+                            ': poll interval "' +
+                            it.interval +
+                            '" is not a positive number of seconds — ignored'
+                    );
+                } else if (s < POLL_INTERVAL_MIN_S) {
+                    warnings.push(
+                        label +
+                            ': poll interval ' +
+                            s +
+                            ' s raised to the ' +
+                            POLL_INTERVAL_MIN_S +
+                            ' s minimum'
+                    );
+                    poll.intervalS = POLL_INTERVAL_MIN_S;
+                } else poll.intervalS = s;
+            } else {
+                warnings.push(
+                    label +
+                        ': unknown poll "' +
+                        JSON.stringify(it) +
+                        '" — use trial_start | {interval: s} | on_demand'
+                );
+            }
+        }
+        if (!poll.trialStart && poll.intervalS == null) poll.onDemand = true;
+        return poll;
+    }
+
+    function parseChannels(raw, label, warnings) {
+        const out = {};
+        if (raw === undefined || raw === null) return out;
+        if (typeof raw !== 'object' || Array.isArray(raw)) {
+            warnings.push(
+                label +
+                    ': channels must be a mapping {name: channel | {channel, min_us, max_us}} — ignored'
+            );
+            return out;
+        }
+        for (const [name, v] of Object.entries(raw)) {
+            const spec = typeof v === 'object' && v !== null ? v : { channel: v };
+            const ch = Number(spec.channel);
+            if (!Number.isInteger(ch) || ch < 0 || ch > 15) {
+                warnings.push(label + ': channel "' + name + '" must be 0..15 — dropped');
+                continue;
+            }
+            let min = spec.min_us === undefined ? SERVO_US_DEFAULT.min_us : Number(spec.min_us);
+            let max = spec.max_us === undefined ? SERVO_US_DEFAULT.max_us : Number(spec.max_us);
+            if (!(min >= SERVO_US_LIMITS.min_us && max <= SERVO_US_LIMITS.max_us && min < max)) {
+                warnings.push(
+                    label +
+                        ': channel "' +
+                        name +
+                        '" pulse limits must satisfy 500 ≤ min_us < max_us ≤ 2500 — using 1000–2000'
+                );
+                min = SERVO_US_DEFAULT.min_us;
+                max = SERVO_US_DEFAULT.max_us;
+            }
+            out[name] = { channel: ch, min_us: min, max_us: max };
+        }
+        return out;
+    }
+
+    /**
+     * Rig YAML `peripherals:` → { list: [entry…], warnings: [string…] }.
+     * entry = { name, kind, address, mux: null|{address, channel}, poll, config, channels }
+     */
+    function parseRigPeripherals(rigData) {
+        const result = { list: [], warnings: [] };
+        const raw = rigData && typeof rigData === 'object' ? rigData.peripherals : undefined;
+        if (raw === undefined || raw === null) return result;
+        if (!Array.isArray(raw)) {
+            result.warnings.push('peripherals must be a list — ignored');
+            return result;
+        }
+        const names = new Set();
+        const locs = new Set();
+        raw.forEach((e, i) => {
+            const label = 'peripherals[' + i + ']';
+            if (!e || typeof e !== 'object' || Array.isArray(e)) {
+                result.warnings.push(label + ': not a mapping — dropped');
+                return;
+            }
+            const kind = typeof e.kind === 'string' ? e.kind.trim().toLowerCase() : '';
+            const K = Q.KINDS[kind];
+            if (!K) {
+                result.warnings.push(
+                    label +
+                        ': unknown kind "' +
+                        e.kind +
+                        '" (known: ' +
+                        Object.keys(Q.KINDS).join(', ') +
+                        ') — dropped'
+                );
+                return;
+            }
+            let address = e.address === undefined ? K.addresses[0] : parseAddress(e.address);
+            if (address === null || address < 0x08 || address > 0x77) {
+                result.warnings.push(
+                    label +
+                        ': address "' +
+                        e.address +
+                        '" must be a 7-bit address 0x08..0x77 — dropped'
+                );
+                return;
+            }
+            if (!K.addresses.includes(address)) {
+                result.warnings.push(
+                    label +
+                        ': ' +
+                        K.label +
+                        ' at ' +
+                        hex2(address) +
+                        ' (expected ' +
+                        K.addresses.map(hex2).join('/') +
+                        ') — kept; check the address straps'
+                );
+            }
+            let mux = null;
+            if (e.mux !== undefined && e.mux !== null) {
+                const ma =
+                    e.mux && typeof e.mux === 'object'
+                        ? parseAddress(e.mux.address === undefined ? 0x70 : e.mux.address)
+                        : null;
+                const mc = e.mux && typeof e.mux === 'object' ? Number(e.mux.channel) : NaN;
+                if (ma === null || !Q.isMux(ma) || !Number.isInteger(mc) || mc < 0 || mc > 7) {
+                    result.warnings.push(
+                        label + ': mux must be {address: 0x70..0x77, channel: 0..7} — dropped'
+                    );
+                    return;
+                }
+                mux = { address: ma, channel: mc };
+            }
+            const name =
+                e.name === undefined
+                    ? kind + '_' + address.toString(16).padStart(2, '0')
+                    : String(e.name);
+            if (!/^[A-Za-z][A-Za-z0-9_]*$/.test(name)) {
+                result.warnings.push(
+                    label +
+                        ': name "' +
+                        name +
+                        '" must be letters/digits/underscore, starting with a letter — dropped'
+                );
+                return;
+            }
+            if (names.has(name)) {
+                result.warnings.push(label + ': duplicate name "' + name + '" — dropped');
+                return;
+            }
+            const key = locKey({
+                addr: address,
+                mux: mux && mux.address,
+                channel: mux && mux.channel
+            });
+            if (locs.has(key)) {
+                result.warnings.push(
+                    label +
+                        ': "' +
+                        name +
+                        '" is at the same address/mux channel as an earlier entry (' +
+                        key +
+                        ') — dropped'
+                );
+                return;
+            }
+            let poll = parsePoll(e.poll, label + ' (' + name + ')', result.warnings);
+            if (K.role === 'actuator' && (poll.trialStart || poll.intervalS != null)) {
+                result.warnings.push(
+                    label + ' (' + name + '): ' + K.label + ' is an actuator — poll ignored'
+                );
+                poll = { trialStart: false, intervalS: null, onDemand: true };
+            }
+            let config = {};
+            if (e.config !== undefined && e.config !== null) {
+                if (typeof e.config === 'object' && !Array.isArray(e.config))
+                    config = Object.assign({}, e.config);
+                else
+                    result.warnings.push(
+                        label + ' (' + name + '): config must be a mapping — ignored'
+                    );
+            }
+            const channels =
+                kind === 'pca9685'
+                    ? parseChannels(e.channels, label + ' (' + name + ')', result.warnings)
+                    : {};
+            names.add(name);
+            locs.add(key);
+            result.list.push({ name, kind, address, mux, poll, config, channels });
+        });
+        if (result.list.length > BOARD_BUDGET) {
+            result.warnings.push(
+                result.list.length +
+                    ' peripherals declared: beyond ~' +
+                    BOARD_BUDGET +
+                    ' boards the bus pull-ups stack below the I2C 3 mA floor (bench 2026-10-12) — cut pull-up jumpers or use the mux'
+            );
+        }
+        return result;
+    }
+
+    const declaredLoc = (p) => ({
+        addr: p.address,
+        mux: p.mux ? p.mux.address : null,
+        channel: p.mux ? p.mux.channel : null
+    });
+
+    /**
+     * Scan + mux map + identify every known part. Holds the bus per step, never
+     * applies configuration. → { at, scan, shadow, devices: [{dev, key, kind, label,
+     * where, ident: {ok, detail, info}|null, driver}], error }
+     */
+    async function discover(bus) {
+        const out = { at: Date.now(), scan: [], shadow: null, devices: [], error: null };
+        let loc;
+        try {
+            loc = await Q.locateDevices(bus);
+        } catch (e) {
+            out.error = e;
+            return out;
+        }
+        out.scan = loc.scan;
+        out.shadow = loc.shadow;
+        for (const dev of loc.devices) {
+            const item = {
+                dev,
+                key: locKey(dev),
+                kind: null,
+                label: Q.describe(dev.addr),
+                where: Q.where(dev),
+                ident: null,
+                driver: null
+            };
+            if (dev.addr === loc.shadow && dev.mux == null) {
+                item.label = 'PCA9685 all-call address (MODE1.ALLCALL set) — not a mux';
+                item.shadow = true;
+            } else if (Q.isMux(dev.addr) && dev.mux == null) {
+                item.mux = true;
+            } else {
+                const kind = Q.kindForAddress(dev.addr);
+                if (kind) {
+                    const r = await Q.identifyDevice(bus, dev, kind);
+                    item.kind = kind;
+                    item.label = Q.KINDS[kind].label;
+                    item.driver = r.driver;
+                    item.ident = { ok: r.ok, detail: r.detail, info: r.info || {} };
+                }
+                if (dev.addr === Q.MCP4725_ADDR) item.wiringError = true;
+            }
+            out.devices.push(item);
+        }
+        return out;
+    }
+
+    /**
+     * Compare the rig's declaration with what is on the bus — both directions.
+     * → { entries: [{decl, status: ok|missing|id_fail|wrong_location, detail, item}],
+     *     undeclared: [item…], counts, ok }
+     */
+    function checkAgainstScan(declared, discovery) {
+        const list = declared || [];
+        const devices = (discovery && discovery.devices) || [];
+        const used = new Set();
+        const whereOf = (decl) =>
+            decl.mux ? 'mux ' + hex2(decl.mux.address) + ' ch' + decl.mux.channel : 'root';
+        // Pass 1: exact location matches claim their devices first, so a same-address
+        // device elsewhere is only offered to entries that found nothing.
+        const exact = list.map((decl) => {
+            const it = devices.find((d) => Q.sameLocation(d.dev, declaredLoc(decl)));
+            if (it) used.add(it.key);
+            return it || null;
+        });
+        const entries = list.map((decl, i) => {
+            const K = Q.KINDS[decl.kind];
+            const where = whereOf(decl);
+            const item = exact[i];
+            if (item) {
+                if (item.ident && !item.ident.ok) {
+                    return {
+                        decl,
+                        item,
+                        status: 'id_fail',
+                        detail:
+                            K.label +
+                            ' ' +
+                            hex2(decl.address) +
+                            ' answered but failed its ID check: ' +
+                            item.ident.detail
+                    };
+                }
+                return {
+                    decl,
+                    item,
+                    status: 'ok',
+                    detail:
+                        K.label +
+                        ' ' +
+                        hex2(decl.address) +
+                        ' @ ' +
+                        where +
+                        (item.ident ? ' — ' + item.ident.detail : '')
+                };
+            }
+            const elsewhere = devices.find(
+                (d) => d.dev.addr === decl.address && !used.has(d.key) && !d.shadow
+            );
+            if (elsewhere) {
+                used.add(elsewhere.key);
+                return {
+                    decl,
+                    item: elsewhere,
+                    status: 'wrong_location',
+                    detail:
+                        K.label +
+                        ' ' +
+                        hex2(decl.address) +
+                        ' declared @ ' +
+                        where +
+                        ' but found @ ' +
+                        elsewhere.where
+                };
+            }
+            const hint =
+                K.role === 'actuator'
+                    ? ' (self-powered boards such as the Servo pHAT vanish from the bus when their own supply is off)'
+                    : '';
+            return {
+                decl,
+                item: null,
+                status: 'missing',
+                detail:
+                    K.label +
+                    ' ' +
+                    hex2(decl.address) +
+                    ' (' +
+                    decl.name +
+                    ') declared in the rig YAML but not on the Qwiic bus' +
+                    hint
+            };
+        });
+        // Muxes that carry a declared device are implicitly declared; the PCA9685 shadow is not a device.
+        const declaredMuxes = new Set(list.filter((p) => p.mux).map((p) => p.mux.address));
+        const undeclared = devices.filter(
+            (it) => !used.has(it.key) && !it.shadow && !(it.mux && declaredMuxes.has(it.dev.addr))
+        );
+        const counts = {
+            declared: list.length,
+            ok: entries.filter((e) => e.status === 'ok').length,
+            missing: entries.filter((e) => e.status === 'missing').length,
+            idFail: entries.filter((e) => e.status === 'id_fail').length,
+            wrongLocation: entries.filter((e) => e.status === 'wrong_location').length,
+            undeclared: undeclared.length,
+            devices: devices.filter((it) => !it.shadow).length
+        };
+        return { entries, undeclared, counts, ok: counts.ok === counts.declared };
+    }
+
+    /**
+     * Configure the declared parts that are present and identified. Holds the bus
+     * per device; failures are recorded, never thrown.
+     * opts.armBump: arm the LSM6DSOX latch (the run-start owner does this, PR 2).
+     * → { applied: {name: cfg}, errors: [{name, message}] }
+     */
+    async function applySetup(bus, check, opts) {
+        const o = opts || {};
+        const out = { applied: {}, errors: [] };
+        for (const e of (check && check.entries) || []) {
+            if (e.status !== 'ok' || !e.item || !e.item.driver) continue;
+            const K = Q.KINDS[e.decl.kind];
+            try {
+                out.applied[e.decl.name] = await Q.withDevice(bus, e.item.dev, () =>
+                    K.setup(e.item.driver, e.decl.config, {
+                        armBump: !!o.armBump && e.decl.poll.trialStart
+                    })
+                );
+            } catch (err) {
+                out.errors.push({ name: e.decl.name, message: err.message });
+            }
+        }
+        return out;
+    }
+
+    /**
+     * Chip for the top bar / Console rail.
+     * state = { available: bool, reason?, declared: [...], check?, discovery? }
+     * → { text, level: off|ok|warn|err, title }
+     */
+    function chipState(state) {
+        const s = state || {};
+        if (!s.available)
+            return {
+                text: 'Qwiic —',
+                level: 'off',
+                title: s.reason || 'no Qwiic I2C bridge on this controller'
+            };
+        if (s.discovery && s.discovery.error) {
+            return { text: 'Qwiic: scan failed', level: 'err', title: s.discovery.error.message };
+        }
+        const c = s.check;
+        if (!c) return { text: 'Qwiic …', level: 'off', title: 'not scanned yet' };
+        const n = c.counts;
+        const und = n.undeclared ? ' · ' + n.undeclared + ' undeclared' : '';
+        const bad = c.entries.filter((e) => e.status !== 'ok');
+        if (bad.length) {
+            const first = bad[0];
+            const K = Q.KINDS[first.decl.kind];
+            const what =
+                first.status === 'missing'
+                    ? 'missing'
+                    : first.status === 'id_fail'
+                      ? 'failed ID'
+                      : 'wrong mux channel';
+            return {
+                text:
+                    'Qwiic: ' +
+                    K.label +
+                    ' ' +
+                    hex2(first.decl.address) +
+                    ' ' +
+                    what +
+                    (bad.length > 1 ? ' +' + (bad.length - 1) : '') +
+                    und,
+                level: 'err',
+                title: bad.map((e) => e.detail).join('\n')
+            };
+        }
+        if (!n.declared) {
+            return {
+                text: 'Qwiic: ' + n.devices + ' device' + (n.devices === 1 ? '' : 's') + und,
+                level: n.undeclared ? 'warn' : 'ok',
+                title: n.undeclared
+                    ? 'Attached but not in the rig YAML — Console → Qwiic → Copy as rig YAML'
+                    : 'Qwiic bus scanned'
+            };
+        }
+        return {
+            text: 'Qwiic ✓ ' + n.ok + '/' + n.declared + und,
+            level: n.undeclared ? 'warn' : 'ok',
+            title: n.undeclared
+                ? n.undeclared +
+                  ' attached device(s) not in the rig YAML — Console → Qwiic → Copy as rig YAML'
+                : 'every declared peripheral is on the bus'
+        };
+    }
+
+    const SUGGESTED_POLL = { env: 'trial_start', tilt: 'trial_start', light: 'on_demand' };
+
+    /**
+     * "Copy as rig YAML": a `peripherals:` snippet from a discovery. opts.only:
+     * an array of items (e.g. check.undeclared) to emit just those entries.
+     */
+    function toRigYaml(discovery, opts) {
+        const o = opts || {};
+        const items = o.only || (discovery && discovery.devices) || [];
+        const lines = ['peripherals:'];
+        const used = new Set();
+        for (const it of items) {
+            if (it.shadow || it.mux) continue;
+            if (!it.kind) {
+                lines.push(
+                    '  # ' + hex2(it.dev.addr) + ' @ ' + it.where + ': ' + it.label + ' — no driver'
+                );
+                continue;
+            }
+            const K = Q.KINDS[it.kind];
+            let name = it.kind + '_' + it.dev.addr.toString(16).padStart(2, '0');
+            if (it.dev.mux != null) name += '_m' + it.dev.channel;
+            while (used.has(name)) name += '_';
+            used.add(name);
+            lines.push('  - name: ' + name);
+            lines.push('    kind: ' + it.kind);
+            lines.push('    address: ' + hex2(it.dev.addr));
+            if (it.dev.mux != null)
+                lines.push(
+                    '    mux: {address: ' + hex2(it.dev.mux) + ', channel: ' + it.dev.channel + '}'
+                );
+            if (SUGGESTED_POLL[K.role]) lines.push('    poll: ' + SUGGESTED_POLL[K.role]);
+            if (it.kind === 'pca9685') {
+                lines.push('    config: {freq_hz: 50}');
+                lines.push('    channels: {servo0: {channel: 0, min_us: 1000, max_us: 2000}}');
+            }
+        }
+        return lines.join('\n') + '\n';
+    }
+
+    /** Readout text for one KINDS display field. */
+    function formatField(field, reading) {
+        const v = reading ? reading[field.key] : undefined;
+        if (v === undefined || v === null) return '—';
+        switch (field.fmt) {
+            case 'okfail':
+                return v ? 'ok' : 'FAIL';
+            case 'flag':
+                return v ? 'SATURATED' : 'no';
+            case 'onoff':
+                return v ? 'on' : 'off';
+            case 'sleep':
+                return v ? 'asleep (not configured)' : 'running';
+            case 'bars':
+                return '';
+        }
+        if (typeof v !== 'number' || !Number.isFinite(v)) return String(v);
+        const digits = field.digits === undefined ? 2 : field.digits;
+        const text = (field.signed && v >= 0 ? '+' : '') + v.toFixed(digits);
+        return field.unit ? text + ' ' + field.unit : text;
+    }
+
+    /** One device's dropdown label: "SHT4x · 0x44 · root (env)". */
+    function deviceLabel(item, declaredName) {
+        const base =
+            (item.kind ? Q.KINDS[item.kind].label : item.label) +
+            ' · ' +
+            hex2(item.dev.addr) +
+            ' · ' +
+            item.where;
+        return declaredName ? base + ' (' + declaredName + ')' : base;
+    }
+
+    const StudioQwiic = {
+        parseRigPeripherals,
+        discover,
+        checkAgainstScan,
+        applySetup,
+        chipState,
+        toRigYaml,
+        formatField,
+        deviceLabel,
+        locKey,
+        parseAddress,
+        BOARD_BUDGET,
+        POLL_INTERVAL_MIN_S,
+        SERVO_US_DEFAULT,
+        SERVO_US_LIMITS
+    };
+
+    if (typeof module !== 'undefined' && module.exports) module.exports = StudioQwiic;
+    global.StudioQwiic = StudioQwiic;
+})(typeof window !== 'undefined' ? window : globalThis);
diff --git a/tests/test-arena-wire-g6.js b/tests/test-arena-wire-g6.js
index 1d891ce3..4bd7eb97 100644
--- a/tests/test-arena-wire-g6.js
+++ b/tests/test-arena-wire-g6.js
@@ -1073,5 +1073,88 @@ console.log('\n=== panel inventory (0xC2 features, 0xD0 / 0xD1) ===');
     check('OPCODES.GET_PANEL_INVENTORY', Wire.OPCODES.GET_PANEL_INVENTORY, 0xd1);
 }
 
+console.log('\n=== Qwiic I2C bridge (0xB0 / 0xB1) — LAB-214 ===');
+{
+    // Byte vectors identical to the firmware repo's tests/qwiic_sensors.py i2c_xfer framing:
+    // params = [addr, wlen, *w, rlen] → frame [len(params)+1, 0xB1, *params].
+    checkBytes('encodeGetI2cScan', Wire.encodeGetI2cScan(), '01 b0');
+    checkBytes('I2C probe (ACK only)', Wire.encodeI2cTransfer(0x44, [], 0), '04 b1 44 00 00');
+    checkBytes(
+        'SHT4x measure-high write leg',
+        Wire.encodeI2cTransfer(0x44, [0xfd], 0),
+        '05 b1 44 01 fd 00'
+    );
+    checkBytes(
+        'SHT4x read leg (plain 6-byte read)',
+        Wire.encodeI2cTransfer(0x44, [], 6),
+        '04 b1 44 00 06'
+    );
+    checkBytes(
+        'TSL2591 ID read (CMD|0x12)',
+        Wire.encodeI2cTransfer(0x29, [0xb2], 1),
+        '05 b1 29 01 b2 01'
+    );
+    checkBytes(
+        'PCA9685 LED0 write (4 bytes)',
+        Wire.encodeI2cTransfer(0x40, [0x06, 0, 0, 0x33, 0x01], 0),
+        '09 b1 40 05 06 00 00 33 01 00'
+    );
+    checkBytes('rlen default 0', Wire.encodeI2cTransfer(0x10, [0x07]), '05 b1 10 01 07 00');
+    checkThrows('addr 0x80 rejected', () => Wire.encodeI2cTransfer(0x80, [], 0));
+    checkThrows('rlen 65 rejected', () => Wire.encodeI2cTransfer(0x10, [], 65));
+    checkThrows('write byte 256 rejected', () => Wire.encodeI2cTransfer(0x10, [256], 0));
+    checkThrows('write > 64 bytes rejected', () =>
+        Wire.encodeI2cTransfer(0x10, new Array(65).fill(0), 0)
+    );
+
+    const scan = Wire.decodeI2cScan(Uint8Array.from([7, 0, 0xb0, 4, 0x10, 0x29, 0x39, 0x44]));
+    checkBool('decodeI2cScan ok', scan && scan.ok && scan.addresses.join(',') === '16,41,57,68');
+    const empty = Wire.decodeI2cScan(Uint8Array.from([3, 0, 0xb0, 0]));
+    checkBool('decodeI2cScan empty bus', empty && empty.ok && empty.addresses.length === 0);
+    check(
+        'decodeI2cScan count/payload mismatch → null',
+        Wire.decodeI2cScan(Uint8Array.from([4, 0, 0xb0, 3, 0x10])),
+        null
+    );
+    const noJackMsg = 'No Qwiic jack on this hardware variant';
+    const noJack = Wire.decodeI2cScan(
+        Uint8Array.from([2 + noJackMsg.length, 1, 0xb0, ...Buffer.from(noJackMsg)])
+    );
+    checkBool(
+        'decodeI2cScan no-jack variant',
+        noJack && !noJack.ok && noJack.noJack && noJack.message === noJackMsg
+    );
+    const busErr = Wire.decodeI2cScan(Uint8Array.from([4, 4, 0xb0, 0x45, 0x52]));
+    checkBool(
+        'decodeI2cScan status 4 → bus error text',
+        busErr && busErr.statusText === 'bus error/timeout' && !busErr.noJack
+    );
+
+    const xfer = Wire.decodeI2cTransfer(Uint8Array.from([3, 0, 0xb1, 0x50]));
+    checkBool(
+        'decodeI2cTransfer data',
+        xfer && xfer.ok && xfer.data.length === 1 && xfer.data[0] === 0x50
+    );
+    const nack = Wire.decodeI2cTransfer(
+        Uint8Array.from([2 + 16, 2, 0xb1, ...Buffer.from('I2C address NACK')])
+    );
+    checkBool(
+        'decodeI2cTransfer address NACK',
+        nack &&
+            !nack.ok &&
+            nack.status === 2 &&
+            nack.statusText === 'address NACK' &&
+            nack.data.length === 0
+    );
+    check(
+        'decodeI2cTransfer short frame → null',
+        Wire.decodeI2cTransfer(Uint8Array.from([5, 0, 0xb1])),
+        null
+    );
+    check('OPCODES.GET_I2C_SCAN', Wire.OPCODES.GET_I2C_SCAN, 0xb0);
+    check('OPCODES.I2C_TRANSFER', Wire.OPCODES.I2C_TRANSFER, 0xb1);
+    check('I2C_READ_MAX', Wire.I2C_READ_MAX, 64);
+}
+
 console.log(`\n=== Summary ===\n${totalChecks - failures} / ${totalChecks} checks passed`);
 process.exit(failures > 0 ? 1 : 0);
diff --git a/tests/test-qwiic-drivers.js b/tests/test-qwiic-drivers.js
new file mode 100644
index 00000000..fd12fd8a
--- /dev/null
+++ b/tests/test-qwiic-drivers.js
@@ -0,0 +1,555 @@
+#!/usr/bin/env node
+/**
+ * test-qwiic-drivers.js — js/qwiic-drivers.js against a simulated Qwiic bus
+ * (no hardware). Vectors ported from the firmware repo's
+ * tests/test_qwiic_sensors_unit.py + tests/test_qwiic_peripherals_unit.py, plus
+ * the bench quirks (SHT4x two-leg read, LSM6DSOX latch, PCA9685 all-call shadow),
+ * the bus mutex, and mux location. LAB-214.
+ *
+ *   pixi run node tests/test-qwiic-drivers.js
+ */
+'use strict';
+
+const Q = require('../js/qwiic-drivers.js');
+const Wire = require('../js/arena-wire-g6.js');
+
+let failures = 0;
+let total = 0;
+function ok(name, cond, info) {
+    total++;
+    console.log(`  ${cond ? 'PASS' : 'FAIL'}  ${name}${info !== undefined ? ' — ' + info : ''}`);
+    if (!cond) failures++;
+}
+const close = (a, b, tol) => Math.abs(a - b) <= (tol === undefined ? 1e-9 : tol);
+const hex = (b) =>
+    Array.from(b)
+        .map((x) => x.toString(16).padStart(2, '0'))
+        .join(' ');
+
+// ── simulated bus ───────────────────────────────────────────────────────────
+// Register-file device: a write sets the pointer (first byte) and stores the rest
+// with auto-increment; a read returns bytes from the pointer. Pointer keys are the
+// raw bytes written, so TSL2591's CMD bit is just part of the key.
+class RegDevice {
+    constructor(regs) {
+        this.regs = Object.assign({}, regs || {});
+        this.ptr = 0;
+        this.writes = [];
+    }
+    write(w) {
+        if (!w.length) return;
+        this.ptr = w[0];
+        for (let i = 1; i < w.length; i++) this.regs[(w[0] + i - 1) & 0xff] = w[i];
+        if (w.length > 1) this.writes.push([w[0], ...w.slice(1)]);
+        this.onWrite && this.onWrite(w);
+    }
+    read(n) {
+        const out = [];
+        for (let i = 0; i < n; i++) out.push(this.readByte((this.ptr + i) & 0xff));
+        return out;
+    }
+    readByte(reg) {
+        return this.regs[reg] === undefined ? 0 : this.regs[reg];
+    }
+}
+
+// SHT4x: command byte → 6-byte frame; NACKs a read while "measuring" if read in
+// the same transfer as the command (repeated start).
+class ShtDevice {
+    constructor(tRaw, rhRaw, serial) {
+        this.t = tRaw;
+        this.rh = rhRaw;
+        this.serial = serial;
+        this.pending = null;
+    }
+    word(v) {
+        const b = [(v >> 8) & 0xff, v & 0xff];
+        return [...b, Q.crc8Sensirion(b)];
+    }
+    write(w) {
+        if (!w.length) return; // the read leg (plain read) carries no command
+        if (w[0] === 0x89)
+            this.pending = [...this.word(this.serial >>> 16), ...this.word(this.serial & 0xffff)];
+        else this.pending = [...this.word(this.t), ...this.word(this.rh)];
+    }
+    read(n) {
+        return (this.pending || []).slice(0, n);
+    }
+}
+
+// PCA9548: one control register; channel k exposes `channels[k]` devices.
+class MuxDevice {
+    constructor(channels) {
+        this.mask = 0;
+        this.channels = channels || {};
+    }
+    write(w) {
+        if (w.length) this.mask = w[0];
+    }
+    read() {
+        return [this.mask];
+    }
+}
+
+function createSim(devices, opts) {
+    const o = opts || {};
+    const log = [];
+    function visible() {
+        const out = new Map(Object.entries(devices).map(([a, d]) => [Number(a), d]));
+        for (const [a, d] of Object.entries(devices)) {
+            if (d instanceof MuxDevice) {
+                for (let ch = 0; ch < 8; ch++) {
+                    if (!(d.mask & (1 << ch))) continue;
+                    for (const [ca, cd] of Object.entries(d.channels[ch] || {}))
+                        out.set(Number(ca), cd);
+                }
+            }
+        }
+        // PCA9685 at 0x40 with ALLCALL set also answers 0x70 (reads return MODE1).
+        const pca = out.get(0x40);
+        if (pca && pca.isPca && pca.regs[0x00] & 0x01 && !out.has(0x70)) {
+            out.set(0x70, { write() {}, read: (n) => new Array(n).fill(pca.regs[0x00]) });
+        }
+        return out;
+    }
+    const reply = (status, cmd, payload) =>
+        Uint8Array.from([2 + payload.length, status, cmd, ...payload]);
+    async function send(bytes) {
+        const b = Array.from(bytes);
+        log.push(hex(b));
+        if (o.noJack)
+            return reply(
+                1,
+                b[1],
+                Array.from(Buffer.from('No Qwiic jack on this hardware variant'))
+            );
+        if (b[1] === 0xb0) {
+            const addrs = [...visible().keys()]
+                .filter((a) => a >= 0x08 && a <= 0x77)
+                .sort((x, y) => x - y);
+            return reply(0, 0xb0, [addrs.length, ...addrs]);
+        }
+        if (b[1] === 0xb1) {
+            const addr = b[2];
+            const wlen = b[3];
+            const w = b.slice(4, 4 + wlen);
+            const rlen = b[4 + wlen];
+            const dev = visible().get(addr);
+            if (!dev) return reply(2, 0xb1, Array.from(Buffer.from('I2C address NACK')));
+            if (dev instanceof ShtDevice && wlen > 0 && rlen > 0)
+                return reply(2, 0xb1, Array.from(Buffer.from('I2C address NACK')));
+            dev.write(w);
+            return reply(0, 0xb1, rlen ? dev.read(rlen) : []);
+        }
+        return reply(1, b[1], []);
+    }
+    return { send, log, devices };
+}
+
+const noSleep = () => Promise.resolve();
+
+(async () => {
+    console.log('\n=== vectors ported from the Python unit tests ===');
+    ok('Sensirion CRC datasheet vector 0xBEEF → 0x92', Q.crc8Sensirion([0xbe, 0xef]) === 0x92);
+    ok('Sensirion CRC 0x0000 → 0x81', Q.crc8Sensirion([0, 0]) === 0x81);
+    {
+        const g = Q.unpackSensirionWords([0xbe, 0xef, 0x92, 0, 0, 0x81]);
+        ok('unpack words good', g.ok && g.words[0] === 0xbeef && g.words[1] === 0);
+        ok(
+            'unpack words flags a bad CRC',
+            !Q.unpackSensirionWords([0xbe, 0xef, 0x93, 0, 0, 0x81]).ok
+        );
+    }
+    {
+        let [t, rh] = Q.SHT4x.convert(0, 0);
+        ok('SHT4x convert 0,0 → -45 °C, RH clipped 0', t === -45 && rh === 0);
+        [t, rh] = Q.SHT4x.convert(0xffff, 0xffff);
+        ok('SHT4x convert max → 130 °C, RH clipped 100', close(t, 130) && rh === 100);
+        [t, rh] = Q.SHT4x.convert(0x62ac, 0x8e85);
+        ok(
+            'SHT4x bench frame 2026-10-12 → 22.45 °C 63.6 %RH',
+            close(t, 22.45, 0.01) && close(rh, 63.6, 0.1),
+            t.toFixed(2) + ' ' + rh.toFixed(1)
+        );
+    }
+    {
+        const T = Q.LSM6DSOX.tilt;
+        const flat = T([0, 0, 1]);
+        ok(
+            'tilt flat',
+            close(flat.from_vertical_deg, 0) &&
+                close(flat.pitch_deg, 0) &&
+                close(flat.roll_deg, 0) &&
+                close(flat.accel_norm_g, 1)
+        );
+        const edge = T([1, 0, 0]);
+        ok('tilt on edge = 90°', close(edge.from_vertical_deg, 90) && close(edge.pitch_deg, 90));
+        ok(
+            'tilt upside down = 0° (inclination, not orientation)',
+            close(T([0, 0, -1]).from_vertical_deg, 0)
+        );
+        const r = (10 * Math.PI) / 180;
+        ok('tilt 10°', close(T([Math.sin(r), 0, Math.cos(r)]).from_vertical_deg, 10, 1e-9));
+        ok('tilt zero vector → NaN', Number.isNaN(T([0, 0, 0]).pitch_deg));
+        const imu = new Q.LSM6DSOX(null);
+        ok('LSM6DSOX 1 g at ±2 g', close(16393 * imu.accelGPerLsb, 1.0, 0.001));
+        ok('LSM6DSOX gyro 8.75 mdps/LSB', close(imu.gyroDpsPerLsb, 8.75e-3));
+    }
+    {
+        const P = Q.PCA9685;
+        ok('PCA9685 prescale 50 Hz = 121', P.prescaleFor(50) === 121);
+        ok('PCA9685 prescale 121 = 50.03 Hz', close(P.freqForPrescale(121), 50.03, 0.01));
+        ok(
+            'PCA9685 prescale clamps 3..255',
+            P.prescaleFor(10000) === 3 && P.prescaleFor(1) === 255
+        );
+        const pwm = new P(null);
+        pwm.freqHz = P.freqForPrescale(121);
+        ok('PCA9685 1500 µs → 307 counts', pwm.pulseToCounts(1500) === 307);
+        ok(
+            'PCA9685 pulse clamps 0..4095',
+            pwm.pulseToCounts(0) === 0 && pwm.pulseToCounts(1e6) === 4095
+        );
+    }
+    {
+        const T = Q.TSL2591;
+        ok('TSL2591 ceiling 36863 at 100 ms', T.ceilingFor(100) === 36863);
+        ok(
+            'TSL2591 ceiling 65535 otherwise',
+            [200, 300, 400, 500, 600].every((a) => T.ceilingFor(a) === 65535)
+        );
+        const s = new T(null);
+        const atCeil = s.decode(1, 36863, 10);
+        ok(
+            'TSL2591 saturated at the ceiling (not 0xFFFF)',
+            atCeil.sat && atCeil.lux_approx === null
+        );
+        const below = s.decode(1, 36862, 10);
+        ok('TSL2591 just below ceiling → lux', !below.sat && below.lux_approx !== null);
+        ok('TSL2591 IR-only saturation', s.decode(1, 5000, 36863).sat);
+        s.atimeMs = 200;
+        ok('TSL2591 40000 counts at 200 ms not saturated', !s.decode(1, 40000, 10).sat);
+        s.atimeMs = 100;
+        const dark = s.decode(1, 0, 0);
+        ok('TSL2591 dark is not saturated, lux null', !dark.sat && dark.lux_approx === null);
+    }
+
+    console.log('\n=== bus ===');
+    {
+        const sim = createSim({ 0x10: new RegDevice({ 0x07: 0x81 }) });
+        const bus = Q.createBus(sim.send, { sleep: noSleep });
+        const scan = await bus.scan();
+        ok('scan', scan.join(',') === '16');
+        ok('ack present', (await bus.ack(0x10)) === true);
+        ok('ack absent → false (address NACK)', (await bus.ack(0x44)) === false);
+        let err = null;
+        try {
+            await bus.readReg(0x44, 0x00, 1);
+        } catch (e) {
+            err = e;
+        }
+        ok(
+            'NACK → I2CError status 2',
+            err instanceof Q.I2CError && err.status === 2 && /0x44: address NACK/.test(err.message),
+            err && err.message
+        );
+        const nj = Q.createBus(createSim({}, { noJack: true }).send, { sleep: noSleep });
+        let e2 = null;
+        try {
+            await nj.scan();
+        } catch (e) {
+            e2 = e;
+        }
+        ok('no-jack firmware → NoQwiicJack', e2 instanceof Q.NoQwiicJack);
+        let e3 = null;
+        try {
+            await nj.xfer(0x10, [0], 1);
+        } catch (e) {
+            e3 = e;
+        }
+        ok('no-jack on transfer → NoQwiicJack', e3 instanceof Q.NoQwiicJack);
+    }
+
+    console.log('\n=== mutex ===');
+    {
+        // Two sequences that both sleep mid-way must not interleave their transfers.
+        const sim = createSim({ 0x10: new RegDevice(), 0x29: new RegDevice() });
+        const bus = Q.createBus(sim.send, { sleep: (ms) => new Promise((r) => setTimeout(r, ms)) });
+        const a = bus.exclusive(async () => {
+            await bus.xfer(0x10, [1], 0);
+            await bus.sleep(15);
+            await bus.xfer(0x10, [2], 0);
+        });
+        const b = bus.exclusive(async () => {
+            await bus.xfer(0x29, [3], 0);
+            await bus.sleep(1);
+            await bus.xfer(0x29, [4], 0);
+        });
+        await Promise.all([a, b]);
+        const order = sim.log.map((l) => l.split(' ')[2]).join(',');
+        ok('exclusive sequences never interleave', order === '10,10,29,29', order);
+        const failing = bus.exclusive(async () => {
+            throw new Error('boom');
+        });
+        let threw = false;
+        try {
+            await failing;
+        } catch (_) {
+            threw = true;
+        }
+        const after = await bus.exclusive(async () => 'next');
+        ok('a throwing sequence releases the bus', threw && after === 'next' && bus.held === false);
+    }
+
+    console.log('\n=== SHT4x two-leg read (bench quirk) ===');
+    {
+        const sim = createSim({ 0x44: new ShtDevice(0x62ac, 0x8e85, 0x14dcf709) });
+        const bus = Q.createBus(sim.send, { sleep: noSleep });
+        const s = new Q.SHT4x(bus);
+        const id = await s.identify();
+        ok('SHT4x serial + CRC', id.serial === 0x14dcf709 && id.crc_ok, id.serial.toString(16));
+        sim.log.length = 0;
+        const r = await s.read();
+        ok(
+            'SHT4x read = separate write leg then read leg',
+            sim.log.join(' | ') === '05 b1 44 01 fd 00 | 04 b1 44 00 06',
+            sim.log.join(' | ')
+        );
+        ok('SHT4x reading', close(r.temp_c, 22.45, 0.01) && close(r.rh_pct, 63.6, 0.1) && r.crc_ok);
+    }
+
+    console.log('\n=== LSM6DSOX bump latch (bench quirk) ===');
+    {
+        const imu = new RegDevice({ 0x0f: 0x6c });
+        // WAKE_UP_SRC clears on read only with LIR + INT_CLR_ON_READ + INT1_WU routing.
+        imu.readByte = function (reg) {
+            const v = this.regs[reg] || 0;
+            if (reg === 0x1b && (this.regs[0x56] & 0x41) === 0x41 && this.regs[0x5e] & 0x20)
+                this.regs[0x1b] = 0;
+            return v;
+        };
+        // accel block: z = +1 g (16393 LSB at ±2 g), temp raw 0 → 25 °C
+        Object.assign(imu.regs, { 0x26: 0, 0x27: 0, 0x2c: 16393 & 0xff, 0x2d: 16393 >> 8 });
+        const sim = createSim({ 0x6a: imu });
+        const bus = Q.createBus(sim.send, { sleep: noSleep });
+        const s = new Q.LSM6DSOX(bus);
+        ok('identify WHO_AM_I 0x6C', (await s.identify()).id_ok);
+        await s.configure();
+        ok(
+            'configure: BDU+IF_INC, 104 Hz ±2 g',
+            imu.regs[0x12] === 0x44 && imu.regs[0x10] === 0x40
+        );
+        const ths = await s.armBump(0.25);
+        ok('armBump: threshold 8 LSB at ±2 g', ths === 8 && imu.regs[0x5b] === 8);
+        ok('armBump: LIR + INT_CLR_ON_READ', imu.regs[0x56] === 0x41);
+        ok('armBump: INT1_WU routing (what latches)', imu.regs[0x5e] === 0x20);
+        ok('armBump: interrupts enabled', imu.regs[0x58] === 0x80);
+        imu.regs[0x1b] = 0x08 | 0x04; // WU_IA + X
+        const b1 = await s.bumpFlag();
+        ok('bumpFlag reports the event + axis', b1.bumped && b1.axes === 'X');
+        const b2 = await s.bumpFlag();
+        ok('bumpFlag cleared on read', !b2.bumped);
+        const r = await s.read();
+        ok(
+            'read: |a| ≈ 1 g flat, die 25 °C',
+            close(r.accel_norm_g, 1, 0.002) && close(r.from_vertical_deg, 0, 0.1) && r.temp_c === 25
+        );
+    }
+
+    console.log('\n=== PCA9685 all-call shadow + servo ===');
+    {
+        const pca = new RegDevice({ 0x00: 0x11, 0xfe: 30 });
+        pca.isPca = true;
+        const sim = createSim({ 0x40: pca });
+        const bus = Q.createBus(sim.send, { sleep: noSleep });
+        const loc = await Q.locateDevices(bus);
+        ok('scan sees 0x40 and its 0x70 shadow', loc.scan.join(',') === '64,112');
+        ok('0x70 recognized as the all-call shadow', loc.shadow === 0x70);
+        ok(
+            'no mux channels mapped through the shadow',
+            loc.devices.every((d) => d.mux === null) && loc.devices.length === 2
+        );
+        const s = new Q.PCA9685(bus);
+        const id = await s.identify();
+        ok(
+            'identify: POR MODE1 0x11 SLEEP+ALLCALL, prescale 30 ≈ 197 Hz',
+            id.sleeping && id.allcall && Math.round(id.freq_hz) === 197
+        );
+        await s.configure({ freq_hz: 50 });
+        ok(
+            'configure: prescale 121, ALLCALL cleared, awake, AI',
+            pca.regs[0xfe] === 121 &&
+                !(pca.regs[0x00] & 0x01) &&
+                !(pca.regs[0x00] & 0x10) &&
+                pca.regs[0x00] & 0x20
+        );
+        ok('after configure 0x70 leaves the scan', (await bus.scan()).join(',') === '64');
+        const off = await s.setPulseUs(0, 1500);
+        const counts = await s.readCounts(0);
+        ok(
+            '1500 µs → OFF 307 written + read back',
+            off === 307 && counts[1] === 307 && counts[0] === 0
+        );
+        await s.setOff(0);
+        ok('setOff sets the full-OFF bit', (await s.readCounts(0))[1] === 0x1000);
+        let threw = false;
+        try {
+            await s.setPulseUs(16, 1500);
+        } catch (_) {
+            threw = true;
+        }
+        ok('channel 16 rejected', threw);
+    }
+
+    console.log('\n=== PCA9548 mux location (unverified on hardware) ===');
+    {
+        const sht = new ShtDevice(0x62ac, 0x8e85, 1);
+        const mux = new MuxDevice({ 2: { 0x44: sht } });
+        const sim = createSim({ 0x70: mux, 0x29: new RegDevice({ 0xb2: 0x50 }) });
+        const bus = Q.createBus(sim.send, { sleep: noSleep });
+        const loc = await Q.locateDevices(bus);
+        const behind = loc.devices.find((d) => d.addr === 0x44);
+        ok(
+            'device behind mux ch2 located',
+            behind && behind.mux === 0x70 && behind.channel === 2,
+            behind && Q.where(behind)
+        );
+        ok('mux mask restored after the walk', mux.mask === 0);
+        const r = await Q.withDevice(bus, behind, () => new Q.SHT4x(bus).read());
+        ok('read through the mux', close(r.temp_c, 22.45, 0.01) && mux.mask === 0);
+        ok(
+            'where() text',
+            Q.where(behind) === 'mux 0x70 ch2' && Q.where({ addr: 1, mux: null }) === 'root'
+        );
+    }
+
+    console.log('\n=== light sensors ===');
+    {
+        const tsl = new RegDevice({
+            0xb2: 0x50,
+            0xb3: 0x01,
+            0xb4: 1000 & 0xff,
+            0xb5: 1000 >> 8,
+            0xb6: 100,
+            0xb7: 0
+        });
+        // VEML7700 registers are 16-bit words; the sim's flat byte file only needs ID 0x0081.
+        const veml = new RegDevice({ 0x07: 0x81, 0x08: 0x00 });
+        const sim = createSim({ 0x29: tsl, 0x10: veml });
+        const bus = Q.createBus(sim.send, { sleep: noSleep });
+        const t = new Q.TSL2591(bus);
+        ok('TSL2591 identify', (await t.identify()).id_ok);
+        await t.configure({ gain: 'high', atime_ms: 200 });
+        ok(
+            'TSL2591 configure CONTROL = gain high | 200 ms',
+            tsl.regs[0xa1] === 0x21 && tsl.regs[0xa0] === 0x03
+        );
+        const r = await t.read();
+        ok(
+            'TSL2591 read full/ir/visible',
+            r.full === 1000 && r.ir === 100 && r.visible === 900 && !r.sat && r.valid
+        );
+        const v = new Q.VEML7700(bus);
+        ok('VEML7700 id ok', (await v.identify()).device_id_ok);
+    }
+    {
+        const as = new RegDevice({ 0x5a: 0x81, 0x59: 0x01, 0x58: 0x02 });
+        as.readByte = function (reg) {
+            if (reg === 0x90) return 0x40; // AVALID
+            if (reg === 0x94) return 0x00; // ASTATUS
+            if (reg >= 0x95 && reg < 0x95 + 36) {
+                const i = (reg - 0x95) >> 1; // channel i = 100 * (i+1)
+                const v = 100 * (i + 1);
+                return (reg - 0x95) & 1 ? v >> 8 : v & 0xff;
+            }
+            return this.regs[reg] || 0;
+        };
+        const sim = createSim({ 0x39: as, 0x44: new ShtDevice(0x62ac, 0x8e85, 1) });
+        const bus = Q.createBus(sim.send, {
+            sleep: (ms) => new Promise((r) => setTimeout(r, Math.min(ms, 30)))
+        });
+        const s = new Q.AS7343(bus);
+        const id = await s.identify();
+        ok(
+            'AS7343 identify via bank 1, bank restored',
+            id.id_ok && id.revid === 1 && as.regs[0xbf] === 0
+        );
+        await s.configure({ gain: 64 });
+        ok(
+            'AS7343 configure: gain code 7, 18-ch SMUX, 50 ms',
+            as.regs[0xc6] === 7 && as.regs[0xd6] === 0x60 && close(s.tintMs, 50.04, 0.01)
+        );
+        // While the AS7343 integrates, another bus user gets in (read releases the bus).
+        const dev = Q.located(0x39);
+        let shtDoneWhileIntegrating = false;
+        const pAs = Q.KINDS.as7343.read(bus, dev, s);
+        const pSht = Q.withDevice(bus, Q.located(0x44), () => new Q.SHT4x(bus).read()).then(() => {
+            shtDoneWhileIntegrating = s._startedAt !== null;
+        });
+        const [r] = await Promise.all([pAs, pSht]);
+        ok('AS7343 read hands the bus back during integration', shtDoneWhileIntegrating);
+        ok(
+            'AS7343 decode: FZ_450 = ch0 = 100, F1_405 = ch12 = 1300',
+            r.channels.FZ_450 === 100 && r.spectral.F1_405 === 1300
+        );
+        ok('AS7343 VIS = mean of VIS0/1/2', close(r.vis, (500 + 1100 + 1700) / 3));
+        ok('AS7343 not saturated', !r.sat);
+    }
+
+    console.log('\n=== KINDS registry ===');
+    {
+        const kinds = Object.keys(Q.KINDS);
+        ok(
+            'kinds',
+            kinds.join(',') === 'sht4x,lsm6dsox,tsl2591,veml7700,as7343,pca9685',
+            kinds.join(',')
+        );
+        ok(
+            'every kind has role/label/display/columns/values',
+            kinds.every((k) => {
+                const e = Q.KINDS[k];
+                return (
+                    e.role &&
+                    e.label &&
+                    Array.isArray(e.display) &&
+                    Array.isArray(e.columns) &&
+                    typeof e.values === 'function' &&
+                    typeof e.read === 'function'
+                );
+            })
+        );
+        ok(
+            'roles',
+            Q.KINDS.sht4x.role === 'env' &&
+                Q.KINDS.lsm6dsox.role === 'tilt' &&
+                Q.KINDS.pca9685.role === 'actuator' &&
+                ['tsl2591', 'veml7700', 'as7343'].every((k) => Q.KINDS[k].role === 'light')
+        );
+        ok(
+            'kindForAddress',
+            Q.kindForAddress(0x44) === 'sht4x' &&
+                Q.kindForAddress(0x6b) === 'lsm6dsox' &&
+                Q.kindForAddress(0x55) === null
+        );
+        ok(
+            'describe flags the AO DAC',
+            /must NOT/.test(Q.describe(0x60)) && /PCA9548/.test(Q.describe(0x71))
+        );
+        const sim = createSim({ 0x44: new ShtDevice(1, 2, 0xabcdef01) });
+        const bus = Q.createBus(sim.send, { sleep: noSleep });
+        const idr = await Q.identifyDevice(bus, Q.located(0x44), 'sht4x');
+        ok('identifyDevice sht4x', idr.ok && idr.info.serial === '0xABCDEF01', idr.detail);
+        const bad = await Q.identifyDevice(bus, Q.located(0x6a), 'lsm6dsox');
+        ok(
+            'identifyDevice on an absent part → ok:false, never throws',
+            !bad.ok && /NACK/.test(bad.detail)
+        );
+        ok('lsm6dsox values exclude the bump flag', !Q.KINDS.lsm6dsox.columns.includes('bumped'));
+    }
+
+    console.log(`\n=== Summary ===\n${total - failures} / ${total} checks passed`);
+    process.exit(failures > 0 ? 1 : 0);
+})().catch((e) => {
+    console.error(e);
+    process.exit(1);
+});
diff --git a/tests/test-studio-analog-in.js b/tests/test-studio-analog-in.js
index e6db928a..ed57d534 100644
--- a/tests/test-studio-analog-in.js
+++ b/tests/test-studio-analog-in.js
@@ -277,7 +277,7 @@ async function main() {
     checkBool(
         'loads js/studio-analog-in.js as a classic script after the wire module',
         studioHtml.indexOf('<script src="js/studio-analog-in.js"') >
-            studioHtml.indexOf('<script src="js/arena-wire-g6.js"') &&
+            studioHtml.indexOf('<script src="js/arena-wire-g6.js') &&
             studioHtml.indexOf('<script src="js/studio-analog-in.js"') > 0,
         'script tag'
     );
diff --git a/tests/test-studio-qwiic.js b/tests/test-studio-qwiic.js
new file mode 100644
index 00000000..61dd73b0
--- /dev/null
+++ b/tests/test-studio-qwiic.js
@@ -0,0 +1,520 @@
+#!/usr/bin/env node
+/**
+ * test-studio-qwiic.js — js/studio-qwiic.js (rig `peripherals:` parser, the
+ * scan-vs-YAML check in both directions, setup, chip, YAML snippet, readout
+ * formatting) + the arena_studio.html Qwiic panel wiring. LAB-214.
+ *
+ *   pixi run node tests/test-studio-qwiic.js
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const SQ = require('../js/studio-qwiic.js');
+const Q = require('../js/qwiic-drivers.js');
+
+let failures = 0;
+let total = 0;
+function ok(name, cond, info) {
+    total++;
+    console.log(`  ${cond ? 'PASS' : 'FAIL'}  ${name}${info !== undefined ? ' — ' + info : ''}`);
+    if (!cond) failures++;
+}
+
+// Discovery fixture without touching a bus: what SQ.discover() returns.
+const item = (addr, kind, extra) =>
+    Object.assign(
+        {
+            dev: Q.located(addr, extra && extra.mux, extra && extra.channel),
+            key: SQ.locKey(Q.located(addr, extra && extra.mux, extra && extra.channel)),
+            kind,
+            label: kind ? Q.KINDS[kind].label : Q.describe(addr),
+            where: Q.where(Q.located(addr, extra && extra.mux, extra && extra.channel)),
+            ident: kind ? { ok: !(extra && extra.idFail), detail: 'id', info: {} } : null,
+            driver: null
+        },
+        extra && extra.flags
+    );
+
+(async () => {
+    console.log('\n=== parseRigPeripherals ===');
+    {
+        const none = SQ.parseRigPeripherals({ name: 'x' });
+        ok(
+            'no peripherals: → empty, no warnings',
+            none.list.length === 0 && none.warnings.length === 0
+        );
+        ok('null rig → empty', SQ.parseRigPeripherals(null).list.length === 0);
+        ok(
+            'not a list → warning',
+            SQ.parseRigPeripherals({ peripherals: { a: 1 } }).warnings.length === 1
+        );
+
+        const r = SQ.parseRigPeripherals({
+            peripherals: [
+                { name: 'env', kind: 'sht4x', address: '0x44', poll: 'trial_start' },
+                {
+                    name: 'tilt',
+                    kind: 'LSM6DSOX',
+                    address: 0x6a,
+                    poll: ['trial_start', { interval: 1.0 }],
+                    config: { bump_g: 0.3 }
+                },
+                { kind: 'tsl2591' },
+                {
+                    name: 'env2',
+                    kind: 'sht4x',
+                    mux: { address: '0x70', channel: 2 },
+                    poll: { interval: 0.1 }
+                },
+                {
+                    name: 'servo',
+                    kind: 'pca9685',
+                    poll: 'trial_start',
+                    channels: { gate: 0, door: { channel: 3, min_us: 900, max_us: 2100 }, bad: 22 }
+                }
+            ]
+        });
+        const by = Object.fromEntries(r.list.map((p) => [p.name, p]));
+        ok('five entries kept', r.list.length === 5, r.list.map((p) => p.name).join(','));
+        ok(
+            'hex string address',
+            by.env.address === 0x44 && by.env.poll.trialStart && !by.env.poll.onDemand
+        );
+        ok(
+            'kind is case-insensitive; poll list',
+            by.tilt.kind === 'lsm6dsox' && by.tilt.poll.trialStart && by.tilt.poll.intervalS === 1
+        );
+        ok('config passes through', by.tilt.config.bump_g === 0.3);
+        ok(
+            'default name + address + on_demand',
+            by.tsl2591_29 && by.tsl2591_29.address === 0x29 && by.tsl2591_29.poll.onDemand
+        );
+        ok(
+            'mux parsed; same address on a mux channel is a different device',
+            by.env2.mux.address === 0x70 && by.env2.mux.channel === 2
+        );
+        ok(
+            'interval below 0.5 s raised + warned',
+            by.env2.poll.intervalS === 0.5 && r.warnings.some((w) => /minimum/.test(w))
+        );
+        ok(
+            'actuator poll ignored + warned',
+            by.servo.poll.onDemand &&
+                !by.servo.poll.trialStart &&
+                r.warnings.some((w) => /actuator/.test(w))
+        );
+        ok(
+            'servo channels: bare int, spec, bad dropped',
+            by.servo.channels.gate.channel === 0 &&
+                by.servo.channels.gate.min_us === 1000 &&
+                by.servo.channels.door.min_us === 900 &&
+                !by.servo.channels.bad &&
+                r.warnings.some((w) => /bad/.test(w))
+        );
+
+        const bad = SQ.parseRigPeripherals({
+            peripherals: [
+                'nope',
+                { kind: 'bme280' },
+                { kind: 'sht4x', address: 0x99 },
+                { kind: 'sht4x', mux: { address: 0x40, channel: 1 } },
+                { kind: 'sht4x', name: '9lives' },
+                { kind: 'sht4x', name: 'a' },
+                { kind: 'sht4x', name: 'a', mux: { channel: 1 } },
+                { kind: 'sht4x', name: 'b' },
+                { kind: 'sht4x', address: 0x45, name: 'c', poll: 'every_second' }
+            ]
+        });
+        ok(
+            'malformed entries dropped, never thrown',
+            bad.list.map((p) => p.name).join(',') === 'a,c',
+            bad.list.map((p) => p.name).join(',')
+        );
+        ok('a warning per problem', bad.warnings.length >= 9, bad.warnings.length + ' warnings');
+        ok(
+            'unknown kind names the known kinds',
+            bad.warnings.some((w) => /unknown kind "bme280".*sht4x/.test(w))
+        );
+        ok(
+            'duplicate location dropped',
+            bad.warnings.some((w) => /same address\/mux channel/.test(w))
+        );
+        ok(
+            'off-book address kept with a strap warning',
+            bad.warnings.some((w) => /0x45.*straps/.test(w))
+        );
+        ok(
+            'unknown poll warned',
+            bad.warnings.some((w) => /unknown poll/.test(w))
+        );
+
+        const many = SQ.parseRigPeripherals({
+            peripherals: Array.from({ length: 9 }, (_, i) => ({
+                kind: 'sht4x',
+                name: 's' + i,
+                mux: { address: 0x70, channel: i % 8 },
+                address: i < 8 ? 0x44 : 0x45
+            }))
+        });
+        ok(
+            '> 8 boards → pull-up budget warning (no cap)',
+            many.list.length === 9 && many.warnings.some((w) => /pull-ups/.test(w))
+        );
+    }
+
+    console.log('\n=== checkAgainstScan — both directions ===');
+    {
+        const declared = SQ.parseRigPeripherals({
+            peripherals: [
+                { name: 'env', kind: 'sht4x', poll: 'trial_start' },
+                { name: 'tilt', kind: 'lsm6dsox', poll: 'trial_start' },
+                { name: 'servo', kind: 'pca9685' },
+                { name: 'env2', kind: 'sht4x', mux: { address: 0x70, channel: 2 } }
+            ]
+        }).list;
+        const disc = {
+            scan: [0x29, 0x44, 0x6a, 0x70],
+            shadow: null,
+            devices: [
+                item(0x29, 'tsl2591'),
+                item(0x44, 'sht4x'),
+                item(0x6a, 'lsm6dsox', { idFail: true }),
+                item(0x70, null, { flags: { mux: true } }),
+                item(0x44, 'sht4x', { mux: 0x70, channel: 5 })
+            ]
+        };
+        const c = SQ.checkAgainstScan(declared, disc);
+        const st = Object.fromEntries(c.entries.map((e) => [e.decl.name, e.status]));
+        ok('present + identified → ok', st.env === 'ok');
+        ok('answered but failed ID → id_fail', st.tilt === 'id_fail');
+        ok(
+            'declared, not on the bus → missing (with the self-powered hint)',
+            st.servo === 'missing' && /own supply/.test(c.entries[2].detail)
+        );
+        ok('declared behind ch2, found behind ch5 → wrong_location', st.env2 === 'wrong_location');
+        ok(
+            'attached but undeclared → flagged',
+            c.undeclared.length === 1 && c.undeclared[0].dev.addr === 0x29,
+            c.undeclared.map((u) => u.key).join(',')
+        );
+        ok(
+            'a mux carrying a declared device is not "undeclared"',
+            !c.undeclared.some((u) => u.mux)
+        );
+        ok(
+            'counts',
+            c.counts.ok === 1 &&
+                c.counts.missing === 1 &&
+                c.counts.idFail === 1 &&
+                c.counts.wrongLocation === 1 &&
+                c.counts.undeclared === 1 &&
+                !c.ok
+        );
+
+        const shadowDisc = {
+            scan: [0x40, 0x70],
+            shadow: 0x70,
+            devices: [item(0x40, 'pca9685'), item(0x70, null, { flags: { shadow: true } })]
+        };
+        const c2 = SQ.checkAgainstScan(
+            [
+                {
+                    name: 'servo',
+                    kind: 'pca9685',
+                    address: 0x40,
+                    mux: null,
+                    poll: {},
+                    config: {},
+                    channels: {}
+                }
+            ],
+            shadowDisc
+        );
+        ok('PCA9685 all-call shadow is never "undeclared"', c2.ok && c2.undeclared.length === 0);
+        const c3 = SQ.checkAgainstScan([], {
+            scan: [0x44],
+            shadow: null,
+            devices: [item(0x44, 'sht4x')]
+        });
+        ok('nothing declared → every device undeclared', c3.counts.undeclared === 1 && c3.ok);
+
+        const chipErr = SQ.chipState({ available: true, check: c });
+        ok(
+            'chip: red, names the first problem, counts undeclared',
+            chipErr.level === 'err' &&
+                /SHT4x 0x44|LSM6DSOX 0x6A/.test(chipErr.text) &&
+                /\+2/.test(chipErr.text) &&
+                /1 undeclared/.test(chipErr.text),
+            chipErr.text
+        );
+        const okDisc = {
+            scan: [0x44, 0x6a, 0x29],
+            shadow: null,
+            devices: [item(0x44, 'sht4x'), item(0x6a, 'lsm6dsox'), item(0x29, 'tsl2591')]
+        };
+        const c4 = SQ.checkAgainstScan(declared.slice(0, 2), okDisc);
+        const chipWarn = SQ.chipState({ available: true, check: c4 });
+        ok(
+            'chip: amber "✓ 2/2 · 1 undeclared"',
+            chipWarn.level === 'warn' && chipWarn.text === 'Qwiic ✓ 2/2 · 1 undeclared',
+            chipWarn.text
+        );
+        const chipOk = SQ.chipState({
+            available: true,
+            check: SQ.checkAgainstScan(declared.slice(0, 2), {
+                scan: [],
+                shadow: null,
+                devices: okDisc.devices.slice(0, 2)
+            })
+        });
+        ok(
+            'chip: green "✓ 2/2"',
+            chipOk.level === 'ok' && chipOk.text === 'Qwiic ✓ 2/2',
+            chipOk.text
+        );
+        ok('chip: off without the bridge', SQ.chipState({ available: false }).level === 'off');
+        ok(
+            'chip: nothing declared, devices found → amber count',
+            SQ.chipState({ available: true, check: c3 }).text === 'Qwiic: 1 device · 1 undeclared'
+        );
+
+        const yaml = SQ.toRigYaml(disc);
+        ok(
+            'YAML snippet: entries for known parts, mux line, poll by role',
+            /- name: tsl2591_29\n    kind: tsl2591\n    address: 0x29\n    poll: on_demand/.test(
+                yaml
+            ) &&
+                /mux: \{address: 0x70, channel: 5\}/.test(yaml) &&
+                /kind: sht4x\n    address: 0x44\n    poll: trial_start/.test(yaml),
+            yaml
+        );
+        ok(
+            'YAML snippet parses back to the same devices',
+            (() => {
+                const YAML = require('../js/vendor/yaml/browser/dist/index.js');
+                const back = SQ.parseRigPeripherals(YAML.parse(yaml));
+                return back.warnings.length === 0 && back.list.length === 4;
+            })()
+        );
+        ok(
+            'YAML snippet: only the undeclared',
+            SQ.toRigYaml(disc, { only: c.undeclared }).split('- name:').length === 2
+        );
+    }
+
+    console.log('\n=== applySetup + discover on a simulated bus ===');
+    {
+        // Tiny register-file sim: SHT4x at 0x44 (no ID needed beyond the serial) + LSM6DSOX at 0x6A.
+        const regs = { 0x6a: { 0x0f: 0x6c } };
+        let shtPending = [];
+        const word = (v) => {
+            const b = [(v >> 8) & 0xff, v & 0xff];
+            return [...b, Q.crc8Sensirion(b)];
+        };
+        const ptr = {};
+        const reply = (status, cmd, payload) =>
+            Uint8Array.from([2 + payload.length, status, cmd, ...payload]);
+        const send = async (bytes) => {
+            const b = Array.from(bytes);
+            if (b[1] === 0xb0) return reply(0, 0xb0, [2, 0x44, 0x6a]);
+            const addr = b[2];
+            const w = b.slice(4, 4 + b[3]);
+            const rlen = b[4 + b[3]];
+            if (addr === 0x44) {
+                if (w.length) shtPending = [...word(0x1234), ...word(0x5678)];
+                return reply(0, 0xb1, shtPending.slice(0, rlen));
+            }
+            if (addr !== 0x6a) return reply(2, 0xb1, []);
+            const r = regs[addr];
+            if (w.length) {
+                ptr[addr] = w[0];
+                w.slice(1).forEach((v, i) => (r[w[0] + i] = v));
+            }
+            return reply(
+                0,
+                0xb1,
+                Array.from({ length: rlen }, (_, i) => r[ptr[addr] + i] || 0)
+            );
+        };
+        const bus = Q.createBus(send, { sleep: () => Promise.resolve() });
+        const d = await SQ.discover(bus);
+        ok(
+            'discover identifies both parts',
+            d.devices.length === 2 && d.devices.every((it) => it.ident && it.ident.ok),
+            d.devices.map((it) => it.label + ':' + (it.ident && it.ident.detail)).join(' | ')
+        );
+        const declared = SQ.parseRigPeripherals({
+            peripherals: [
+                { name: 'env', kind: 'sht4x' },
+                { name: 'tilt', kind: 'lsm6dsox', poll: 'trial_start', config: { bump_g: 0.5 } }
+            ]
+        }).list;
+        const check = SQ.checkAgainstScan(declared, d);
+        const res = await SQ.applySetup(bus, check, { armBump: false });
+        ok(
+            'setup configures the IMU without arming the bump latch',
+            res.applied.tilt &&
+                res.applied.tilt.odr_hz === 104 &&
+                !('bump_ths' in res.applied.tilt) &&
+                regs[0x6a][0x10] === 0x40 &&
+                !regs[0x6a][0x5e]
+        );
+        const res2 = await SQ.applySetup(bus, check, { armBump: true });
+        ok(
+            'armBump (run-start owner) arms only trial_start devices',
+            res2.applied.tilt.bump_ths === 16 &&
+                regs[0x6a][0x5e] === 0x20 &&
+                res2.errors.length === 0
+        );
+        const nj = await SQ.discover(
+            Q.createBus(async (b) =>
+                reply(1, b[1], Array.from(Buffer.from('No Qwiic jack on this hardware variant')))
+            )
+        );
+        ok(
+            'discover on a jack-less board → error, no throw',
+            nj.error && nj.error.name === 'NoQwiicJack'
+        );
+        ok(
+            'chip after a failed scan',
+            SQ.chipState({ available: true, discovery: nj }).level === 'err'
+        );
+    }
+
+    console.log('\n=== formatField ===');
+    {
+        ok(
+            'number + unit',
+            SQ.formatField({ key: 't', unit: '°C', digits: 2 }, { t: 22.456 }) === '22.46 °C'
+        );
+        ok(
+            'signed',
+            SQ.formatField({ key: 'p', unit: '°', digits: 1, signed: true }, { p: 3 }) === '+3.0 °'
+        );
+        ok('null → dash', SQ.formatField({ key: 'lux', unit: 'lx' }, { lux: null }) === '—');
+        ok('flag', SQ.formatField({ key: 's', fmt: 'flag' }, { s: true }) === 'SATURATED');
+        ok('okfail', SQ.formatField({ key: 'c', fmt: 'okfail' }, { c: false }) === 'FAIL');
+        ok(
+            'every KINDS display field formats a sample',
+            Object.values(Q.KINDS).every((k) =>
+                k.display.every((f) => typeof SQ.formatField(f, {}) === 'string')
+            )
+        );
+        ok(
+            'deviceLabel',
+            SQ.deviceLabel(item(0x44, 'sht4x'), 'env') === 'SHT4x · 0x44 · root (env)'
+        );
+    }
+
+    console.log('\n=== arena_studio.html wiring ===');
+    {
+        const html = fs.readFileSync(path.join(__dirname, '..', 'arena_studio.html'), 'utf8');
+        const idx = (s) => html.indexOf(s);
+        ok(
+            'drivers + glue load as classic scripts after the wire module, before arena-link',
+            idx('<script src="js/qwiic-drivers.js"') > idx('<script src="js/arena-wire-g6.js') &&
+                idx('<script src="js/studio-qwiic.js"') >
+                    idx('<script src="js/qwiic-drivers.js"') &&
+                idx('<script src="js/arena-link.js"') > idx('<script src="js/studio-qwiic.js"')
+        );
+        ok(
+            'ONE Qwiic panel + rail button',
+            (html.match(/<section class="panel" data-panel="qwiic">/g) || []).length === 1 &&
+                /class="rail-btn" data-panel="qwiic"/.test(html)
+        );
+        for (const id of [
+            'cQwStatus',
+            'cQwDev',
+            'cQwOut',
+            'cQwFlags',
+            'cQwTable',
+            'cQwLive',
+            'cQwRate',
+            'cQwYaml',
+            'cQwCsv',
+            'cQwBump',
+            'cQwServo',
+            'cQwSvCh',
+            'cQwSvUs',
+            'qwiicChip',
+            'cQwSum'
+        ]) {
+            ok('element #' + id, html.includes('id="' + id + '"'));
+        }
+        for (const cmd of [
+            'cqwscan',
+            'cqwread',
+            'cqwlive',
+            'cqwcsv',
+            'cqwyaml',
+            'cqwbumparm',
+            'cqwbumpcheck',
+            'cqwsvgo',
+            'cqwsvcenter',
+            'cqwsvrelease',
+            'cqwsvalloff'
+        ]) {
+            ok(
+                'button + handler ' + cmd,
+                html.includes('data-cmd="' + cmd + '"') &&
+                    new RegExp('\\n\\s+' + cmd + ': ').test(html)
+            );
+        }
+        ok(
+            'quiet reads: the bus uses session.send with silent:true',
+            /QD\.createBus\(\(b, o\) => session\.send\(b, o\), \{ sendOpts: \{ silent: true \} \}\)/.test(
+                html
+            )
+        );
+        ok(
+            'scan refused during a run',
+            /session\.running\) return \{ ok: false, reason: what === 'scan' \? 'refused — a run is active/.test(
+                html
+            )
+        );
+        ok(
+            'connect-time setup scan from initFromController',
+            /initFromController[\s\S]{0,900}Studio\.qwiicSetup\(\)/.test(html)
+        );
+        ok(
+            'setup does not arm the bump latch (one owner: the run)',
+            /SQ\.applySetup\(qwBus\(\), check, \{ armBump: false \}\)/.test(html)
+        );
+        ok(
+            'disconnect resets the Qwiic state',
+            /Studio\.qwiicReset\(\); \/\/ never carry/.test(html)
+        );
+        ok(
+            'rig change re-checks without rescanning',
+            /Studio\.qwiicRecheck\(\); \/\/ re-compare/.test(html)
+        );
+        ok(
+            'rig fetch parses peripherals alongside io',
+            /peripherals: SQ \? SQ\.parseRigPeripherals\(data\)/.test(html) &&
+                /Studio\.fetchRigPeripherals = async function/.test(html)
+        );
+        ok(
+            'undeclared devices flagged in table + dropdown',
+            /⚠ undeclared/.test(html) && /not in the rig YAML/.test(html)
+        );
+        ok(
+            'HELP rail + chip + PANEL_HELP entries',
+            html.includes(`'.rail-btn[data-panel="qwiic"]':`) &&
+                html.includes(`'#qwiicChip':`) &&
+                /\n\s+qwiic: 'Sensors on the Qwiic connector/.test(html)
+        );
+        ok('panel order rule', html.includes('.panel[data-panel="qwiic"]{order:10}'));
+        ok(
+            'footer bumped past v0.94',
+            !/Arena Studio v0\.94 \|/.test(html) &&
+                /Arena Studio v0\.\d+ \| \d{4}-\d\d-\d\d \d\d:\d\d ET/.test(html)
+        );
+    }
+
+    console.log(`\n=== Summary ===\n${total - failures} / ${total} checks passed`);
+    process.exit(failures > 0 ? 1 : 0);
+})().catch((e) => {
+    console.error(e);
+    process.exit(1);
+});
diff --git a/tests/test-studio-shell.js b/tests/test-studio-shell.js
index adb30fb7..b7126f84 100644
--- a/tests/test-studio-shell.js
+++ b/tests/test-studio-shell.js
@@ -146,7 +146,7 @@ console.log('=== Console Tools checklist ===');
 const railRows = Array.from(
     studio.matchAll(/<div class="rail-btn( sel)?" data-panel="([a-z]+)"([^>]*)>/g)
 );
-check('nine rail rows', railRows.length === 9, String(railRows.length));
+check('ten rail rows', railRows.length === 10, String(railRows.length));
 railRows.forEach((m) => {
     const sel = !!m[1];
     const attrs = m[3];

From 22f24a01e89c3eec7ae2a1a112359e4d072806a1 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Mon, 12 Oct 2026 16:52:18 -0400
Subject: [PATCH 11/17] =?UTF-8?q?fix(studio):=20Qwiic=20panel=20=E2=80=94?=
 =?UTF-8?q?=20pick=20a=20device=20by=20radio=20row,=20category=20+=20conne?=
 =?UTF-8?q?ction=20columns,=20no=20sticky=20"live"=20status=20(LAB-214)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Bench feedback (all six boards working on the 12-18):
- The scan table is the picker: one radio row per identified device (click the
  row or its button); the dropdown is gone.
- Each row names its category (Servo / PWM, Temp / humidity, Accel / tilt / bump,
  Light (broadband / lux / spectral), I2C mux) — KINDS.category, one place.
- "where" is now "connection": direct (on the controller's own chain) or
  "mux 0x70 · ch N" (behind a PCA9548 channel).
- Stopping Live restores the scan summary; a tick in flight at Stop no longer
  re-writes "live · N Hz".
- Table text left-aligned (it inherited the analog table's right alignment).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 arena_studio.html          | 98 ++++++++++++++++++++++----------------
 js/qwiic-drivers.js        |  7 +++
 js/studio-qwiic.js         | 32 +++++++++++--
 tests/test-studio-qwiic.js | 29 +++++++++--
 4 files changed, 116 insertions(+), 50 deletions(-)

diff --git a/arena_studio.html b/arena_studio.html
index 9bdec4b7..16d6def4 100644
--- a/arena_studio.html
+++ b/arena_studio.html
@@ -2237,7 +2237,13 @@
   .console-view #cAiChart{display:block;width:100%;max-width:460px;height:90px;border:1px solid var(--border);border-radius:4px;background:var(--chart-bg)}
   .console-view .ai-table{font-size:10.5px;border-collapse:collapse}
   /* Qwiic panel (LAB-214): scan table, one-device readout grid, AS7343 spectrum bars */
-  .console-view .qw-table td,.console-view .qw-table th{padding:2px 8px 2px 0;text-align:left;vertical-align:top}
+  .console-view table.qw-table td,.console-view table.qw-table th{padding:2px 10px 2px 0;text-align:left;vertical-align:top}
+  .console-view .qw-table tr.qw-pick{cursor:pointer}
+  .console-view .qw-table tr.qw-pick:hover td{background:var(--surface2)}
+  .console-view .qw-table tr.qw-selrow td{background:color-mix(in srgb,var(--accent) 10%,transparent)}
+  .console-view .qw-table input[type=radio]{margin:0 2px 0 0;accent-color:var(--accent);cursor:pointer}
+  .console-view .qw-table .qw-cat{color:var(--text);font-weight:600;white-space:nowrap}
+  .console-view .qw-sel{font-family:var(--head);font-size:11.5px;color:var(--text);min-width:180px}
   .console-view .qw-flags{font-size:11px;line-height:1.5}
   .console-view .qw-out{display:block}
   .console-view .qw-title{font-family:var(--head);font-size:12px;margin-bottom:4px}
@@ -3254,10 +3260,10 @@ <h2 id="modalTitle">Import error</h2>
             <span class="dim" id="cQwScanSum" title="Addresses that ACKed the last scan"></span></div>
           <div class="crow qw-flags" id="cQwFlags" style="display:none"></div>
           <div class="crow" id="cQwTableRow" style="display:none"><table class="ai-table qw-table" id="cQwTable"></table></div>
-          <div class="crow"><span class="lbl" title="One device at a time">device</span>
-            <select id="cQwDev" disabled title="Devices found and identified by the last scan — pick one to see its readings"><option value="">— scan first —</option></select>
-            <button class="pill" data-cmd="cqwread" title="Read the selected device once (configures it first if needed)">Read</button>
-            <button class="pill" id="cQwLive" data-cmd="cqwlive" aria-pressed="false" title="Start / stop a live readout of the selected device at the chosen rate; pauses by itself during a run">Live</button>
+          <div class="crow"><span class="lbl" title="One device at a time — pick it with the radio button in the table above">selected</span>
+            <span class="qw-sel" id="cQwSel" title="The device the readout below shows — pick another with the radio buttons in the scan table">— scan first —</span>
+            <button class="pill" data-cmd="cqwread" disabled title="Read the selected device once (configures it first if needed)">Read</button>
+            <button class="pill" id="cQwLive" data-cmd="cqwlive" disabled aria-pressed="false" title="Start / stop a live readout of the selected device at the chosen rate; pauses by itself during a run">Live</button>
             <label title="Live readout rate (Console preview only)">rate <select id="cQwRate"><option value="1">1 Hz</option><option value="2">2 Hz</option><option value="0.5">0.5 Hz</option></select></label>
             <button class="pill" id="cQwCsv" data-cmd="cqwcsv" disabled title="Download the readings collected in this session for the selected device as CSV (a Console scratch file — not a run log)">Download CSV</button></div>
           <div class="crow" id="cQwOpts" style="display:none"></div>
@@ -3410,7 +3416,7 @@ <h2 id="modalTitle">Import error</h2>
 </div>
 
 <footer id="footer">
-  <span class="foot-left">Arena Studio v0.96 | 2026-10-12 16:08 ET · <a href="https://github.com/reiserlab/webDisplayTools" target="_blank" rel="noopener" title="webDisplayTools on GitHub: source, issues, and release notes (docs/development/arena-studio-release-notes.md)">GitHub</a></span>
+  <span class="foot-left">Arena Studio v0.96 | 2026-10-12 16:50 ET · <a href="https://github.com/reiserlab/webDisplayTools" target="_blank" rel="noopener" title="webDisplayTools on GitHub: source, issues, and release notes (docs/development/arena-studio-release-notes.md)">GitHub</a></span>
   <!-- Course-repo quick-links: open protocols / logs / patterns in a new tab.
        Hrefs built from the configured repo + bench id (updateGhQuickLinks). -->
   <span id="ghQuickLinks" title="Open the course repo on GitHub (new tab)">
@@ -6141,7 +6147,10 @@ <h2 id="modalTitle">Import error</h2>
         }
         const statusByKey = {};
         (qw.check ? qw.check.entries : []).forEach((e) => { if (e.item) statusByKey[e.item.key] = e; });
-        let html = '<tr><th title="7-bit I2C address">addr</th><th>part</th><th title="root bus, or the PCA9548 mux channel it sits behind">where</th><th>identify</th><th title="Compared with the session rig YAML peripherals: list">rig YAML</th></tr>';
+        const head = (t, tip) => '<th' + (tip ? ' title="' + qwEsc(tip) + '"' : '') + '>' + t + '</th>';
+        let html = '<tr>' + head('', 'Pick one device to show its readings below') + head('device') + head('part') + head('addr', '7-bit I2C address') +
+            head('connection', 'direct = on the controller\'s own Qwiic chain · mux 0x70 · ch N = behind a PCA9548 I2C multiplexer channel (only needed for two identical fixed-address parts)') +
+            head('identify', 'The part\'s ID register / serial number check') + head('rig YAML', 'Compared with the session rig YAML peripherals: list') + '</tr>';
         for (const it of d.devices) {
             const e = statusByKey[it.key];
             let yaml = '';
@@ -6149,11 +6158,16 @@ <h2 id="modalTitle">Import error</h2>
             else if (e) yaml = e.status === 'ok' ? '<span class="qw-ok-t">declared: ' + qwEsc(e.decl.name) + '</span>' : '<span class="qw-err-t">' + qwEsc(e.status.replace('_', ' ')) + '</span>';
             else if (qwIsUndeclared(it)) yaml = '<span class="qw-warn-t" title="Attached but not in the rig YAML — Copy as rig YAML to declare it">⚠ undeclared</span>';
             const id = it.ident ? (it.ident.ok ? '<span class="qw-ok-t">OK</span> ' : '<span class="qw-err-t">FAIL</span> ') + qwEsc(it.ident.detail) : it.wiringError ? '<span class="qw-err-t">wiring error</span>' : '<span class="dim">no driver</span>';
-            html += '<tr><td>' + qwHex(it.dev.addr) + '</td><td>' + qwEsc(it.label) + '</td><td>' + qwEsc(it.where) + '</td><td>' + id + '</td><td>' + yaml + '</td></tr>';
+            const pickable = qwSelectable(it);
+            const radio = pickable ? '<input type="radio" name="cQwPick" value="' + qwEsc(it.key) + '"' + (it.key === qw.selKey ? ' checked' : '') + ' title="Show this device\'s readings">' : '';
+            const part = it.shadow ? 'PCA9685 all-call address — not a mux' : it.kind ? QD.KINDS[it.kind].label : it.label;
+            html += '<tr class="' + (pickable ? 'qw-pick' : '') + (it.key === qw.selKey ? ' qw-selrow' : '') + '" data-qw-key="' + qwEsc(it.key) + '"><td>' + radio + '</td><td class="qw-cat">' + qwEsc(SQ.categoryOf(it)) + '</td><td>' + qwEsc(part) + '</td><td>' + qwHex(it.dev.addr) + '</td><td>' + qwEsc(SQ.connectionText(it.dev)) + '</td><td>' + id + '</td><td>' + yaml + '</td></tr>';
         }
         for (const e of qw.check ? qw.check.entries : []) {
             if (e.item) continue;
-            html += '<tr><td>' + qwHex(e.decl.address) + '</td><td>' + qwEsc(QD.KINDS[e.decl.kind].label) + '</td><td>' + (e.decl.mux ? 'mux ' + qwHex(e.decl.mux.address) + ' ch' + e.decl.mux.channel : 'root') + '</td><td class="dim">—</td><td><span class="qw-err-t">✕ missing: ' + qwEsc(e.decl.name) + '</span></td></tr>';
+            const K = QD.KINDS[e.decl.kind];
+            const conn = SQ.connectionText({ mux: e.decl.mux ? e.decl.mux.address : null, channel: e.decl.mux ? e.decl.mux.channel : null });
+            html += '<tr><td></td><td class="qw-cat">' + qwEsc(K.category) + '</td><td>' + qwEsc(K.label) + '</td><td>' + qwHex(e.decl.address) + '</td><td>' + qwEsc(conn) + '</td><td class="dim">—</td><td><span class="qw-err-t">✕ missing: ' + qwEsc(e.decl.name) + '</span></td></tr>';
         }
         tbl.innerHTML = html;
         row.style.display = '';
@@ -6167,30 +6181,26 @@ <h2 id="modalTitle">Import error</h2>
             flags.style.display = msgs.length ? '' : 'none';
         }
     }
-    function qwRenderDropdown() {
-        const sel = $('cQwDev');
-        if (!sel) return;
-        const items = qw.discovery && !qw.discovery.error ? qw.discovery.devices.filter((it) => it.kind && it.ident && it.ident.ok) : [];
-        sel.innerHTML = '';
-        if (!items.length) {
-            sel.innerHTML = '<option value="">' + (qw.discovery ? '— no supported device found —' : '— scan first —') + '</option>';
-            sel.disabled = true;
-            qw.selKey = null;
-            qwRenderDevice();
-            return;
-        }
-        for (const it of items) {
-            const decl = qwDeclFor(it);
-            const o = document.createElement('option');
-            o.value = it.key;
-            o.textContent = SQ.deviceLabel(it, decl && decl.name) + (qwIsUndeclared(it) ? '  ⚠ undeclared' : '');
-            sel.appendChild(o);
+    // Devices you can pick: found AND identified by a supported driver.
+    const qwSelectable = (it) => !!(it.kind && it.ident && it.ident.ok);
+    function qwRenderSelection() {
+        const items = qw.discovery && !qw.discovery.error ? qw.discovery.devices.filter(qwSelectable) : [];
+        if (!items.some((it) => it.key === qw.selKey)) qw.selKey = items.length ? items[0].key : null;
+        qwRenderTable();
+        const lbl = $('cQwSel');
+        const item = qw.selKey && qwItem(qw.selKey);
+        if (lbl) {
+            const decl = item && qwDeclFor(item);
+            lbl.textContent = item ? SQ.deviceLabel(item, decl && decl.name) + (qwIsUndeclared(item) ? '  ⚠ undeclared' : '') : qw.discovery ? '— no supported device found —' : '— scan first —';
         }
-        sel.disabled = false;
-        if (!items.some((it) => it.key === qw.selKey)) qw.selKey = items[0].key;
-        sel.value = qw.selKey;
         qwRenderDevice();
     }
+    function qwSelect(key) {
+        if (key === qw.selKey) return;
+        qwStopLive('device changed');
+        qw.selKey = key;
+        qwRenderSelection();
+    }
     // fromDom=false: the defaults (rig config, else the KINDS default) — used while the
     // option selects still belong to the PREVIOUS device.
     function qwOptionValues(item, fromDom) {
@@ -6306,6 +6316,7 @@ <h2 id="modalTitle">Import error</h2>
         if (qw.liveTimer) { clearInterval(qw.liveTimer); qw.liveTimer = null; }
         const was = qw.live;
         qw.live = false;
+        if (was) qwSetStatus(qw.idleStatus || 'idle'); // never leave "live · N Hz" behind
         const b = $('cQwLive');
         if (b) { b.setAttribute('aria-pressed', 'false'); b.textContent = 'Live'; }
         if (was && reason) clog('qwiic: live readout stopped — ' + reason, reason.startsWith('error') ? 'err' : 'info');
@@ -6320,6 +6331,7 @@ <h2 id="modalTitle">Import error</h2>
         clog('qwiic: live readout at ' + hz + ' Hz', 'info');
         const tick = async () => {
             if (qw.inFlight) return; // single-flight
+            if (!qw.live) return;
             const g = qwGate('read');
             if (!g.ok) { qwSetStatus(g.reason); return; }
             if (!$('cQwGrid')) return;
@@ -6327,7 +6339,7 @@ <h2 id="modalTitle">Import error</h2>
             try {
                 await qwReadOnce({ quiet: true });
                 qw.errStreak = 0;
-                qwSetStatus('live · ' + hz + ' Hz');
+                if (qw.live) qwSetStatus('live · ' + hz + ' Hz'); // a tick in flight at Stop must not re-say "live"
             } catch (e) {
                 qw.errStreak++;
                 qwSetStatus('error: ' + e.message);
@@ -6369,18 +6381,18 @@ <h2 id="modalTitle">Import error</h2>
             qw.check = SQ.checkAgainstScan(qw.declared.list, d);
             Studio.qwiic = { available: true, declared: qw.declared.list, discovery: d, check: qw.check, at: d.at };
             const n = qw.check.counts;
-            qwSetStatus(n.devices + ' device' + (n.devices === 1 ? '' : 's') + (n.declared ? ' · ' + n.ok + '/' + n.declared + ' declared present' : ''));
+            qw.idleStatus = n.devices + ' device' + (n.devices === 1 ? '' : 's') + (n.declared ? ' · ' + n.ok + '/' + n.declared + ' declared present' : '');
+            qwSetStatus(qw.idleStatus);
             const sum = $('cQwScanSum');
             if (sum) sum.textContent = 'scan: ' + (d.scan.length ? d.scan.map(qwHex).join(' ') : 'nothing ACKed — check the cable, the boards\' power LEDs and the jack');
             clog('qwiic: ' + (setup ? 'setup ' : '') + 'scan — ' + (d.scan.length ? d.scan.map(qwHex).join(' ') : 'no devices') + (d.shadow ? ' (0x70 = the PCA9685 all-call address, not a mux)' : ''), 'info');
             qw.declared.warnings.forEach((w) => clog('qwiic: rig YAML: ' + w, 'warn'));
             qw.check.entries.filter((e) => e.status !== 'ok').forEach((e) => clog('qwiic: ' + e.detail, 'err'));
-            qw.check.undeclared.filter((u) => !u.mux).forEach((u) => clog('qwiic: ' + u.label + ' ' + qwHex(u.dev.addr) + ' @ ' + u.where + ' is attached but not in the rig YAML — Console → Qwiic → Copy as rig YAML', 'warn'));
+            qw.check.undeclared.filter((u) => !u.mux).forEach((u) => clog('qwiic: ' + u.label + ' ' + qwHex(u.dev.addr) + ' (' + SQ.connectionText(u.dev) + ') is attached but not in the rig YAML — Console → Qwiic → Copy as rig YAML', 'warn'));
             d.devices.filter((it) => it.wiringError).forEach((it) => clog('qwiic: ' + it.label, 'err'));
             const yamlBtn = $('cQwYaml');
             if (yamlBtn) yamlBtn.disabled = !d.devices.some((it) => it.kind);
-            qwRenderTable();
-            qwRenderDropdown();
+            qwRenderSelection();
             return qw.check;
         } catch (e) {
             qwSetStatus('error: ' + e.message);
@@ -6436,8 +6448,7 @@ <h2 id="modalTitle">Import error</h2>
         try { qw.declared = Studio.fetchRigPeripherals ? await Studio.fetchRigPeripherals() : { list: [], warnings: [] }; } catch (_) { return; }
         qw.check = SQ.checkAgainstScan(qw.declared.list, qw.discovery);
         Studio.qwiic = Object.assign({}, Studio.qwiic, { declared: qw.declared.list, check: qw.check });
-        qwRenderTable();
-        qwRenderDropdown();
+        qwRenderSelection();
         qwRenderChip();
     };
     Studio.qwiicReset = function () {
@@ -6446,12 +6457,12 @@ <h2 id="modalTitle">Import error</h2>
         qw.check = null;
         qw.configured = {};
         qw.selKey = null;
+        qw.idleStatus = '';
         Studio.qwiic = null;
         qwSetStatus('connect to scan');
         const sum = $('cQwScanSum');
         if (sum) sum.textContent = '';
-        qwRenderTable();
-        qwRenderDropdown();
+        qwRenderSelection();
         qwRenderChip();
     };
     // Bump check + servo are disabled while a run owns the link / the bump latch.
@@ -6581,8 +6592,11 @@ <h2 id="modalTitle">Import error</h2>
         clog('qwiic: ' + rows.length + ' reading(s) saved as CSV (Console only — not a run log)', 'info');
     }
     (function qwWire() {
-        const sel = $('cQwDev');
-        if (sel) sel.addEventListener('change', () => { qwStopLive('device changed'); qw.selKey = sel.value || null; qwRenderDevice(); });
+        const tbl = $('cQwTable');
+        if (tbl) tbl.addEventListener('click', (e) => {
+            const tr = e.target.closest('tr.qw-pick');
+            if (tr && tr.dataset.qwKey) qwSelect(tr.dataset.qwKey);
+        });
         const rate = $('cQwRate');
         if (rate) rate.addEventListener('change', () => { if (qw.live) qwStartLive(); });
         const flags = $('cQwFlags');
@@ -17889,7 +17903,7 @@ <h2 id="modalTitle">Import error</h2>
     '.rail-btn[data-panel="qwiic"]': 'Find and try out the small sensors plugged into the arena’s Qwiic connector: scan, pick one, watch its readings. Nothing here is saved to run logs.',
     '[data-cmd="cqwscan"]': 'Look for every device on the Qwiic connector and check each one against this rig’s list. Not available while a run is going.',
     '#cQwYaml': 'Copy ready-made rig-file lines for the devices the scan found, so they can be recorded with each run.',
-    '#cQwDev': 'Pick one device to look at. Devices marked “undeclared” are plugged in but not listed in this rig’s file.',
+    '#cQwTable': 'Everything the scan found. Click a row (or its round button) to show that device’s readings below. “Direct” means plugged into the arena’s own Qwiic chain; “undeclared” means plugged in but not listed in this rig’s file.',
     '[data-cmd="cqwread"]': 'Take one reading from the selected device.',
     '#cQwLive': 'Keep reading the selected device about once a second. Pauses by itself during a run.',
     '[data-cmd="cqwbumpcheck"]': 'Was the motion sensor bumped since the last check? Checking resets the answer.',
diff --git a/js/qwiic-drivers.js b/js/qwiic-drivers.js
index 8ffc868a..197942e9 100644
--- a/js/qwiic-drivers.js
+++ b/js/qwiic-drivers.js
@@ -938,6 +938,7 @@
 
     // ── KINDS registry ──────────────────────────────────────────────────────
     // One entry per supported part — the ONLY place to add or drop one.
+    //   category: the short label the Console shows (Servo / PWM, Temp / humidity, …)
     //   role:     env | tilt | light | actuator (consumers pick by role, never by part)
     //   identify: (driver) → {ok, detail, info}            caller holds the bus
     //   setup:    (driver, config, {forRun}) → applied cfg  caller holds the bus
@@ -952,6 +953,7 @@
     const KINDS = {
         sht4x: {
             kind: 'sht4x',
+            category: 'Temp / humidity',
             label: 'SHT4x',
             title: 'SHT4x temperature / humidity',
             role: 'env',
@@ -980,6 +982,7 @@
         },
         lsm6dsox: {
             kind: 'lsm6dsox',
+            category: 'Accel / tilt / bump',
             label: 'LSM6DSOX',
             title: 'LSM6DSOX IMU — tilt + bump latch',
             role: 'tilt',
@@ -1023,6 +1026,7 @@
         },
         tsl2591: {
             kind: 'tsl2591',
+            category: 'Light (broadband)',
             label: 'TSL2591',
             title: 'TSL2591 broadband light',
             role: 'light',
@@ -1060,6 +1064,7 @@
         },
         veml7700: {
             kind: 'veml7700',
+            category: 'Light (lux)',
             label: 'VEML7700',
             title: 'VEML7700 ambient light',
             role: 'light',
@@ -1094,6 +1099,7 @@
         },
         as7343: {
             kind: 'as7343',
+            category: 'Light (spectral)',
             label: 'AS7343',
             title: 'AS7343 14-channel spectral',
             role: 'light',
@@ -1134,6 +1140,7 @@
         },
         pca9685: {
             kind: 'pca9685',
+            category: 'Servo / PWM',
             label: 'PCA9685',
             title: 'PCA9685 servo / PWM driver',
             role: 'actuator',
diff --git a/js/studio-qwiic.js b/js/studio-qwiic.js
index 5bf05a0b..f9777b50 100644
--- a/js/studio-qwiic.js
+++ b/js/studio-qwiic.js
@@ -332,7 +332,10 @@
         const devices = (discovery && discovery.devices) || [];
         const used = new Set();
         const whereOf = (decl) =>
-            decl.mux ? 'mux ' + hex2(decl.mux.address) + ' ch' + decl.mux.channel : 'root';
+            connectionText({
+                mux: decl.mux ? decl.mux.address : null,
+                channel: decl.mux ? decl.mux.channel : null
+            });
         // Pass 1: exact location matches claim their devices first, so a same-address
         // device elsewhere is only offered to entries that found nothing.
         const exact = list.map((decl) => {
@@ -387,7 +390,7 @@
                         ' declared @ ' +
                         where +
                         ' but found @ ' +
-                        elsewhere.where
+                        connectionText(elsewhere.dev)
                 };
             }
             const hint =
@@ -575,14 +578,33 @@
         return field.unit ? text + ' ' + field.unit : text;
     }
 
-    /** One device's dropdown label: "SHT4x · 0x44 · root (env)". */
+    /**
+     * How the device is reached, for people: "direct" (on the controller's own
+     * Qwiic chain — the drivers call it "root") or "mux 0x70 · ch 2" (behind a
+     * PCA9548 channel, only needed for two identical fixed-address parts).
+     */
+    function connectionText(dev) {
+        return dev.mux == null ? 'direct' : 'mux ' + hex2(dev.mux) + ' · ch ' + dev.channel;
+    }
+
+    /** Short category label: "Temp / humidity", "Servo / PWM", "I2C mux", … */
+    function categoryOf(item) {
+        if (item.kind) return Q.KINDS[item.kind].category;
+        if (item.shadow) return '(PCA9685 all-call)';
+        if (item.mux) return 'I2C mux';
+        return 'unknown';
+    }
+
+    /** One device's label: "Temp / humidity · SHT4x · 0x44 · direct (env)". */
     function deviceLabel(item, declaredName) {
         const base =
+            categoryOf(item) +
+            ' · ' +
             (item.kind ? Q.KINDS[item.kind].label : item.label) +
             ' · ' +
             hex2(item.dev.addr) +
             ' · ' +
-            item.where;
+            connectionText(item.dev);
         return declaredName ? base + ' (' + declaredName + ')' : base;
     }
 
@@ -595,6 +617,8 @@
         toRigYaml,
         formatField,
         deviceLabel,
+        connectionText,
+        categoryOf,
         locKey,
         parseAddress,
         BOARD_BUDGET,
diff --git a/tests/test-studio-qwiic.js b/tests/test-studio-qwiic.js
index 61dd73b0..2d76b8c9 100644
--- a/tests/test-studio-qwiic.js
+++ b/tests/test-studio-qwiic.js
@@ -402,8 +402,20 @@ const item = (addr, kind, extra) =>
             )
         );
         ok(
-            'deviceLabel',
-            SQ.deviceLabel(item(0x44, 'sht4x'), 'env') === 'SHT4x · 0x44 · root (env)'
+            'deviceLabel: category · part · addr · connection (name)',
+            SQ.deviceLabel(item(0x44, 'sht4x'), 'env') ===
+                'Temp / humidity · SHT4x · 0x44 · direct (env)'
+        );
+        ok(
+            'connectionText: direct / mux · ch',
+            SQ.connectionText(Q.located(0x44)) === 'direct' &&
+                SQ.connectionText(Q.located(0x44, 0x70, 2)) === 'mux 0x70 · ch 2'
+        );
+        ok(
+            'categoryOf: every kind has a category; mux + shadow labelled',
+            Object.keys(Q.KINDS).every((k) => SQ.categoryOf({ kind: k }).length > 2) &&
+                SQ.categoryOf({ mux: true }) === 'I2C mux' &&
+                /all-call/.test(SQ.categoryOf({ shadow: true }))
         );
     }
 
@@ -425,7 +437,7 @@ const item = (addr, kind, extra) =>
         );
         for (const id of [
             'cQwStatus',
-            'cQwDev',
+            'cQwSel',
             'cQwOut',
             'cQwFlags',
             'cQwTable',
@@ -495,7 +507,16 @@ const item = (addr, kind, extra) =>
                 /Studio\.fetchRigPeripherals = async function/.test(html)
         );
         ok(
-            'undeclared devices flagged in table + dropdown',
+            'one device at a time: radio rows in the scan table, no dropdown',
+            /name="cQwPick"/.test(html) && !/id="cQwDev"/.test(html) && /tr\.qw-pick/.test(html)
+        );
+        ok(
+            'Live stop restores the idle status (no sticky "live · N Hz")',
+            /if \(was\) qwSetStatus\(qw\.idleStatus/.test(html) &&
+                /if \(qw\.live\) qwSetStatus\('live · '/.test(html)
+        );
+        ok(
+            'undeclared devices flagged in table + selection',
             /⚠ undeclared/.test(html) && /not in the rig YAML/.test(html)
         );
         ok(

From ab6e8af861026e1988cf3e76d01c535e823f4a6d Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Mon, 12 Oct 2026 17:00:40 -0400
Subject: [PATCH 12/17] feat(rigs): G6_1x12of18 bench + G6_3x10of14 ring arenas
 and rigs (LAB-214)

- js/arena-configs.js regenerated (scripts/generate-arena-configs.js) from the
  maDisplayTools branch feat/arenas-1x12of18-3x10of14: G6 arena IDs 7
  (G6_1x12of18) and 8 (G6_3x10of14). angle_offset_deg centers the gap at the back
  so the installed panels sit centered at the front in the 3D view and icons
  (Mercator/Mollweide center the installed arc by construction).
- configs/rigs/g6_1x12of18_bench.yaml: the arena_12-18 bench, one row, with the
  six-board Qwiic chain declared under peripherals:; g6_3x10of14.yaml with
  peripherals: [] until its chain is known. Both added to configs/rigs/index.json.
- tests: geometry, IDs, centering, index entries, clean peripherals parse.

The maDisplayTools change must merge first: the sync-arena-configs workflow
regenerates arena-configs.js from maDisplayTools main.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 configs/rigs/g6_1x12of18_bench.yaml           | 67 +++++++++++++++++
 configs/rigs/g6_3x10of14.yaml                 | 34 +++++++++
 configs/rigs/index.json                       | 12 +++
 .../development/arena-studio-release-notes.md |  1 +
 js/arena-configs.js                           | 52 ++++++++++++-
 tests/test-studio-qwiic.js                    | 73 +++++++++++++++++++
 6 files changed, 238 insertions(+), 1 deletion(-)
 create mode 100644 configs/rigs/g6_1x12of18_bench.yaml
 create mode 100644 configs/rigs/g6_3x10of14.yaml

diff --git a/configs/rigs/g6_1x12of18_bench.yaml b/configs/rigs/g6_1x12of18_bench.yaml
new file mode 100644
index 00000000..d8ed0e51
--- /dev/null
+++ b/configs/rigs/g6_1x12of18_bench.yaml
@@ -0,0 +1,67 @@
+# G6 rig configuration — arena_12-18 bench build, 1 panel high (12 of 18 columns)
+#
+# The bench arena_12-18 v1.0 controller with one row of panels, used to test
+# patterns and the Qwiic / STEMMA QT peripherals (LAB-214). The controller's
+# firmware build reports 4x12 in GET_FIRMWARE_VERSION, so this rig is never
+# auto-derived: pick it in ⚙ Settings or open the Studio with ?rig=g6_1x12of18_bench.
+
+format_version: "1.0"
+name: "G6 1x12of18 bench (arena_12-18)"
+description: "Bench arena_12-18 controller, one panel high, with the six-board Qwiic test chain"
+
+arena: "G6_1x12of18"
+
+controller:
+  host: "0.0.0.0" # not used for serial/USB
+  port: 62222
+
+plugins: {}
+
+io:
+  dio:
+    - port: 1
+      role: out_debug_framescan # HIGH during each frame's SPI transmission
+      default: 0
+    - port: 2
+      role: off
+      default: 0
+  ai:
+    role: off
+  ao:
+    role: programmable
+    default: 5.0 # volts — this hardware idles at 5 V
+
+# Qwiic / STEMMA QT peripherals on jack J2 (LAB-214). The Studio scans once at
+# connect and compares: a listed device that is missing is an error (never
+# retried), an attached device that is not listed is flagged. Console → Qwiic →
+# "Copy as rig YAML" produces entries for anything new.
+#   poll: trial_start | {interval: <s>} | on_demand  (run logging: LAB-214 PR 2)
+peripherals:
+  - name: env
+    kind: sht4x # Adafruit SHT41 — temperature / humidity
+    address: 0x44
+    poll: [trial_start, {interval: 1.0}]
+  - name: tilt
+    kind: lsm6dsox # Adafruit 4438 — tilt + latched "bumped" flag
+    address: 0x6A
+    poll: trial_start
+    config: {bump_g: 0.25}
+  - name: photometer
+    kind: tsl2591 # broadband light — LED calibration (on demand)
+    address: 0x29
+    poll: on_demand
+    config: {gain: med, atime_ms: 100}
+  - name: lux
+    kind: veml7700
+    address: 0x10
+    poll: on_demand
+  - name: spectral
+    kind: as7343 # 14-channel spectral
+    address: 0x39
+    poll: on_demand
+    config: {gain: 64}
+  - name: servo
+    kind: pca9685 # SparkFun Servo pHAT — needs its own USB-C power, else absent from the scan
+    address: 0x40
+    config: {freq_hz: 50}
+    channels: {servo0: {channel: 0, min_us: 1000, max_us: 2000}}
diff --git a/configs/rigs/g6_3x10of14.yaml b/configs/rigs/g6_3x10of14.yaml
new file mode 100644
index 00000000..d30340f8
--- /dev/null
+++ b/configs/rigs/g6_3x10of14.yaml
@@ -0,0 +1,34 @@
+# G6 rig configuration — 10-of-14 ring, 3 panels high
+#
+# The 10-of-14 ring arena (10 columns installed on a 14-column circle, gap at
+# the back). Its controller has a Qwiic / STEMMA QT jack; list the boards in
+# peripherals: once the chain is known (Console → Qwiic → "Copy as rig YAML").
+
+format_version: "1.0"
+name: "G6 3x10of14"
+description: "G6 10-of-14 ring, 3 rows (~257°), controller over USB/serial, no external plugins"
+
+arena: "G6_3x10of14"
+
+controller:
+  host: "0.0.0.0" # not used for serial/USB
+  port: 62222
+
+plugins: {}
+
+io:
+  dio:
+    - port: 1
+      role: out_debug_framescan # HIGH during each frame's SPI transmission
+      default: 0
+    - port: 2
+      role: off
+      default: 0
+  ai:
+    role: off
+  ao:
+    role: programmable
+    default: 5.0 # volts — this hardware idles at 5 V
+
+# Qwiic peripherals (LAB-214): none listed yet.
+peripherals: []
diff --git a/configs/rigs/index.json b/configs/rigs/index.json
index 5a7b8da0..ed356d1c 100644
--- a/configs/rigs/index.json
+++ b/configs/rigs/index.json
@@ -33,6 +33,18 @@
       "label": "CSHL G6 — 2×8 of 10 (288°)",
       "path": "./configs/rigs/cshl_g6_2x8.yaml",
       "arena": "G6_2x8of10"
+    },
+    {
+      "name": "g6_1x12of18_bench",
+      "label": "G6 — 1×12 of 18 bench (arena_12-18, Qwiic)",
+      "path": "./configs/rigs/g6_1x12of18_bench.yaml",
+      "arena": "G6_1x12of18"
+    },
+    {
+      "name": "g6_3x10of14",
+      "label": "G6 — 3×10 of 14 ring (257°)",
+      "path": "./configs/rigs/g6_3x10of14.yaml",
+      "arena": "G6_3x10of14"
     }
   ]
 }
diff --git a/docs/development/arena-studio-release-notes.md b/docs/development/arena-studio-release-notes.md
index e70f8afc..25971a62 100644
--- a/docs/development/arena-studio-release-notes.md
+++ b/docs/development/arena-studio-release-notes.md
@@ -10,6 +10,7 @@ history lives here. Newest first. (Per-session engineering detail stays in
 - **Console → Qwiic: find and try the sensors on the arena's Qwiic / STEMMA QT connector.** Scan lists every device on the bus, identifies the supported parts (SHT4x temperature/humidity, LSM6DSOX tilt + bump, TSL2591 / VEML7700 / AS7343 light, PCA9685 servo driver) and compares them with the rig file. Pick one device to see its readings in real units, once or live; the motion sensor has a bump check, and the servo board a position slider with Center and Release. This panel is for testing — nothing in it is written to run logs.
 - **Rig files can list their Qwiic peripherals (`peripherals:`).** On connect the Studio scans once and shows a Qwiic chip in the top bar: green when every listed device is there, red when one is missing (no retry), amber when something is plugged in that the rig file doesn't list. **Copy as rig YAML** gives you the lines to add.
 - Controllers without a Qwiic connector are unaffected: the Studio never sends them I2C commands, and the chip stays hidden.
+- **Two new rigs in ⚙ Settings:** the arena_12-18 bench (one panel high, 12 of 18 columns, its six Qwiic boards listed) and the 10-of-14 ring (three panels high). Both show their installed panels centered at the front in the Pattern Designer's views.
 
 ## v0.94 (2026-09-30) · LAB-158 ports (Protocol ▾, ⚙ Settings, two-column Console) + visibility themes · Multi-color G6 panels V1 — Panel LEDs layout, ON color, per-bank preview (LAB-228) · Flasher + Studio picker: one production build from the published catalog; legacy images hashed, never default (panel-fw-v1.3.1)
 
diff --git a/js/arena-configs.js b/js/arena-configs.js
index e3d3ddfb..44f89cd7 100644
--- a/js/arena-configs.js
+++ b/js/arena-configs.js
@@ -6,6 +6,32 @@
  */
 
 const STANDARD_CONFIGS = {
+  "G6_1x12of18": {
+    "label": "G6 (1×18) - 240°",
+    "description": "G6 arena, 1 row, 12 of 18 columns installed (240 degree coverage)",
+    "arena": {
+      "generation": "G6",
+      "num_rows": 1,
+      "num_cols": 18,
+      "columns_installed": [
+        0,
+        1,
+        2,
+        3,
+        4,
+        5,
+        6,
+        7,
+        8,
+        9,
+        10,
+        11
+      ],
+      "orientation": "normal",
+      "column_order": "cw",
+      "angle_offset_deg": -60
+    }
+  },
   "G6_2x10": {
     "label": "G6 (2×10) - 360°",
     "description": "Full G6 arena, 2 rows x 10 columns, 360 degree coverage",
@@ -54,6 +80,30 @@ const STANDARD_CONFIGS = {
       "angle_offset_deg": 0
     }
   },
+  "G6_3x10of14": {
+    "label": "G6 (3×14) - 257°",
+    "description": "G6 arena, 3 rows, 10 of 14 columns installed (257 degree coverage)",
+    "arena": {
+      "generation": "G6",
+      "num_rows": 3,
+      "num_cols": 14,
+      "columns_installed": [
+        0,
+        1,
+        2,
+        3,
+        4,
+        5,
+        6,
+        7,
+        8,
+        9
+      ],
+      "orientation": "normal",
+      "column_order": "cw",
+      "angle_offset_deg": -51.4286
+    }
+  },
   "G6_3x12of18": {
     "label": "G6 (3×18) - 240°",
     "description": "G6 arena, 3 rows, 12 of 18 columns installed (240 degree coverage)",
@@ -213,7 +263,7 @@ const GENERATIONS = {
 const ARENA_REGISTRY = {
     'G4': { 1: 'G4_4x12', 2: 'G4_3x12of18' },
     'G4.1': { 1: 'G41_2x12_cw' },
-    'G6': { 1: 'G6_2x10', 2: 'G6_2x8of10', 3: 'G6_3x12of18', 4: 'G6_3x16_full', 5: 'G6_3x10', 6: 'G6_4x10' }
+    'G6': { 1: 'G6_2x10', 2: 'G6_2x8of10', 3: 'G6_3x12of18', 4: 'G6_3x16_full', 5: 'G6_3x10', 6: 'G6_4x10', 7: 'G6_1x12of18', 8: 'G6_3x10of14' }
 };
 
 /**
diff --git a/tests/test-studio-qwiic.js b/tests/test-studio-qwiic.js
index 2d76b8c9..3f60494b 100644
--- a/tests/test-studio-qwiic.js
+++ b/tests/test-studio-qwiic.js
@@ -533,6 +533,79 @@ const item = (addr, kind, extra) =>
         );
     }
 
+    console.log('\n=== bench rigs + arena configs ===');
+    {
+        const YAML = require('../js/vendor/yaml/browser/dist/index.js');
+        const AC = require('../js/arena-configs.js');
+        const root = path.join(__dirname, '..');
+        const index = JSON.parse(
+            fs.readFileSync(path.join(root, 'configs/rigs/index.json'), 'utf8')
+        );
+        const cases = [
+            {
+                rig: 'g6_1x12of18_bench',
+                arena: 'G6_1x12of18',
+                rows: 1,
+                cols: 18,
+                installed: 12,
+                id: 7,
+                offset: -60,
+                peripherals: 6
+            },
+            {
+                rig: 'g6_3x10of14',
+                arena: 'G6_3x10of14',
+                rows: 3,
+                cols: 14,
+                installed: 10,
+                id: 8,
+                offset: -51.4286,
+                peripherals: 0
+            }
+        ];
+        for (const c of cases) {
+            const cfg = AC.getConfig(c.arena);
+            ok(
+                c.arena + ': registered with geometry',
+                !!cfg &&
+                    cfg.arena.num_rows === c.rows &&
+                    cfg.arena.num_cols === c.cols &&
+                    cfg.arena.columns_installed.length === c.installed
+            );
+            ok(
+                c.arena + ': arena ID ' + c.id,
+                AC.getArenaId('G6', c.arena) === c.id && AC.getArenaName('G6', c.id) === c.arena
+            );
+            // Installed panels centered at the front: the gap's middle sits at the back (south).
+            const alpha = 360 / c.cols;
+            const gapMid = (c.installed + (c.cols - c.installed) / 2) * alpha; // degrees from column 0's edge
+            ok(
+                c.arena + ': offset centers the gap at the back',
+                Math.abs(((((-gapMid + cfg.arena.angle_offset_deg) % 360) + 360) % 360) - 0) <
+                    0.01 ||
+                    Math.abs(((((-gapMid + cfg.arena.angle_offset_deg) % 360) + 360) % 360) - 360) <
+                        0.01
+            );
+            const entry = index.rigs.find((r) => r.name === c.rig);
+            ok(
+                c.rig + ': index entry → arena + path',
+                entry &&
+                    entry.arena === c.arena &&
+                    entry.path === './configs/rigs/' + c.rig + '.yaml'
+            );
+            const rig = YAML.parse(
+                fs.readFileSync(path.join(root, 'configs/rigs', c.rig + '.yaml'), 'utf8')
+            );
+            ok(c.rig + ': rig arena', rig.arena === c.arena);
+            const per = SQ.parseRigPeripherals(rig);
+            ok(
+                c.rig + ': peripherals parse clean (' + c.peripherals + ')',
+                per.warnings.length === 0 && per.list.length === c.peripherals,
+                per.warnings.join('; ')
+            );
+        }
+    }
+
     console.log(`\n=== Summary ===\n${total - failures} / ${total} checks passed`);
     process.exit(failures > 0 ? 1 : 0);
 })().catch((e) => {

From 8935a699dc2c1eb0dd8cc43c47fb04ae228f65d1 Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Mon, 12 Oct 2026 17:00:59 -0400
Subject: [PATCH 13/17] docs: Qwiic peripherals rules in CLAUDE.md + parity
 ledger row (LAB-214)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CLAUDE.md                               | 18 ++++++++++++++++++
 docs/development/arena-studio-parity.md |  1 +
 2 files changed, 19 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 24d2f417..f8ba4842 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -622,6 +622,24 @@ fix flows to every page automatically; two hand-written HTML pages never will.
   like 0xA8 on the 0xCB telemetry flag; `Studio.readCrashReport()` logs a `crash_report` event.
   Breadcrumb ops 6–9 are the SET_FRAME_POSITION sub-steps (disarm timer / preload / arm / respond).
 
+- **Qwiic peripherals (LAB-214, v0.96):** the controller exposes only a sensor-agnostic I2C bridge
+  (`GET_I2C_SCAN` 0xB0, `I2C_TRANSFER` 0xB1; 0xB2–0xBF stay reserved), advertised by the 0xC2
+  feature bit `qwiic_i2c` — **gate EVERY I2C send on it** (jack-less 10-10 / 2x10 builds answer
+  CE_UNKNOWN_CMD + an error glyph). All register maps are host-side in `js/qwiic-drivers.js`
+  (port of the firmware repo's `tests/qwiic_sensors.py` + `qwiic_peripherals.py`); the `KINDS`
+  registry there is THE one place to add/drop a part (category, role env|tilt|light|actuator,
+  display fields, log columns) — consumers pick by role, never by part. `js/studio-qwiic.js` holds
+  the rig `peripherals:` parser (tolerant, parseRigIo contract), the scan-vs-YAML check in BOTH
+  directions (declared-but-missing = error, never retried; attached-but-undeclared = amber flag,
+  never logged), setup, chip and "Copy as rig YAML". Rules: (1) ONE page-wide bus
+  (`Studio.qwiicBus()`) — its `exclusive()` mutex orders whole sequences (mux select + reads,
+  SHT4x's two legs); never nest `exclusive()`. (2) Scan only at SETUP (connect, the Scan button,
+  run start): ~10 ms controller loop stall; refused during runs. (3) The LSM6DSOX bump flag is
+  read-to-clear: one owner (the trial logger during runs; Console "Check" is disabled then);
+  connect-time setup never arms it. (4) Bench quirks are load-bearing (SHT4x two-leg read; LIR +
+  INT_CLR_ON_READ + INT1 routing; PCA9685 ALLCALL shadow at 0x70 decided from MODE1, cleared by
+  configure). The rig fetch (`fetchRigSections`) parses `io:` and `peripherals:` from one read.
+
 ## Pattern Designer (`pattern_editor.html`)
 
 Renamed from "Pattern Editor" (v0.10, 2026-07-04); the FILENAME stays `pattern_editor.html`
diff --git a/docs/development/arena-studio-parity.md b/docs/development/arena-studio-parity.md
index d4d30856..a68c742f 100644
--- a/docs/development/arena-studio-parity.md
+++ b/docs/development/arena-studio-parity.md
@@ -37,6 +37,7 @@ Update this list when a Studio feature intentionally skips the twins.
 | "+ add / ✕ remove" optional CONTROLLER params on command cards (Studio v0.41; first user: trialParams `duty`). The standalone designer renders/edits a `duty` present in the YAML or seeded by the shared schema default (detailKeys synced), but can't add it to or remove it from an existing command | n/a | ✗ (render/edit only) |
 | Conditional LED activation editor — the `led_activation` nested-object sub-editor on a trialParams card (level / hysteresis / on-ranges list; Studio v0.59). The runner engine + parser + schema are SHARED (flow everywhere), so a `led_activation` authored in Studio round-trips and RUNS from the standalone; it's just not editable there (kept out of the standalone's detailKeys — the scalar field renderer can't show a nested object) | n/a | ✗ (preserved on export, not editable) |
 | Runtime variables (Studio v0.84) — the Run view panel for `runtime_controls:` (bounded operator changes, explicit Apply, next-trial activation, logged provenance; `js/runtime-controls.js` + `js/studio-runtime-vars.js`) and the `requires:` capability gate that refuses to run protocols needing `flow_control`. The parser preserves both keys on round trip, so a protocol authored with them still opens/exports in the standalone — it just has no panel and no gate there | ✗ | ✗ (preserved, not shown; no run gate) |
+| Qwiic peripherals (LAB-214, Studio v0.96) — Console → Qwiic (scan, identify, one device's readout, bump check, servo go-to-position, Copy as rig YAML), the connect-time scan + top-bar chip, and rig `peripherals:`. Drivers are shared modules (`js/qwiic-drivers.js`, `js/studio-qwiic.js`) — Studio only, by policy | ✗ | n/a |
 
 | Alt-study shell ports (LAB-158, ported from Arena Studio Alt into Classic): **Protocol ▾** menu (renamed from File; protocol actions only, section heads) + **⚙ Settings** menu (session rig, GitHub + storage, Run logging — browser settings, not the YAML); Edit's drawer renamed "⚙ Protocol settings"; Console **Tools** rail as an accessible checklist + a 2-column Console stage on wide screens; Run view widened to 1500 px; Scope `labels: full/clean` pill + toggle state in text/`aria-pressed`; replay re-pins the current step when the Scope is resized; visibility themes in ⚙ Settings → Display (Dark / Light / High contrast / Night / Color-blind safe / Match this computer). Guarded by `tests/test-studio-shell.js` | ✗ | ✗ |
 

From c5eff70c8ead332a19c58a1047304e088384270f Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Mon, 12 Oct 2026 17:20:02 -0400
Subject: [PATCH 14/17] feat(studio): live Console sliders, firmware-sized
 test-display frames, color-bank figure; Qwiic read-on-select (LAB-214)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Qwiic: clicking a device reads it immediately; Live keeps running across device
  changes (each tick reads the selected device); the servo follows its slider while
  dragging.
- Console sliders act while dragging — Test display level/duty re-send the last
  figure, LED power sets the LED — through liveSender(): single-flight, latest
  value wins, nothing sent while a run owns the link, one log line on release.
- Test display streams at the CONTROLLER's frame geometry (0xCB rows×cols; fw
  panel_count_per_frame) instead of refusing every non-20-panel rig: the rig figure
  is placed in the firmware frame (installed columns from the left, rig rows
  repeated up), so the 1×12 bench drives a 4×12 build. Wire.streamFrameBytes +
  encodeStreamFrame(payload, {panels}) with golden tests; .bin/.pat file streaming
  stays 20-panel.
- Test display → color A–D: light one LED bank (T0–T3) at a time via the shared
  PanelColor.bankAt (100 of 400 LEDs per panel).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 arena_studio.html                             | 184 ++++++++++++++----
 .../development/arena-studio-release-notes.md |   4 +
 js/arena-wire-g6.js                           |  31 ++-
 tests/test-arena-wire-g6.js                   |  16 ++
 tests/test-studio-qwiic.js                    |  27 +++
 5 files changed, 222 insertions(+), 40 deletions(-)

diff --git a/arena_studio.html b/arena_studio.html
index 16d6def4..f9c3fa64 100644
--- a/arena_studio.html
+++ b/arena_studio.html
@@ -3206,6 +3206,9 @@ <h2 id="modalTitle">Import error</h2>
             <input id="cFileInput" type="file" accept=".bin,.pat" style="display:none">
             <span class="thumb" id="cStreamThumb" title="Streamed-frame preview"></span>
           </div>
+          <div class="crow"><span class="lbl" title="Color panels: each 20×20 panel has four LED banks laid out as a 2×2 mosaic. Light one bank at a time to check each color.">color</span>
+            <span class="seg2" id="cBankSeg"><button data-cmd="cbank0" title="Light only bank A (T0) — one LED in four per panel, at the level above">A</button><button data-cmd="cbank1" title="Light only bank B (T1) — one LED in four per panel, at the level above">B</button><button data-cmd="cbank2" title="Light only bank C (T2) — one LED in four per panel, at the level above">C</button><button data-cmd="cbank3" title="Light only bank D (T3) — one LED in four per panel, at the level above">D</button></span>
+            <span class="dim" title="A–D = the panel firmware's banks T0–T3 (host coords: T2/T3 on row 0, T0/T1 on row 1 — bench-verified 2026-09-29)">one LED bank at a time (A–D = T0–T3)</span></div>
           </div>
         </section>
 
@@ -3276,7 +3279,7 @@ <h2 id="modalTitle">Import error</h2>
           <div id="cQwServo" style="display:none">
             <div class="crow"><span class="lbl" title="PCA9685 servo driver (e.g. SparkFun Servo pHAT)">servo</span>
               <select id="cQwSvCh" title="PWM channel 0–15 (named channels come from the rig YAML channels:)"></select>
-              <input id="cQwSvUs" type="range" min="1000" max="2000" step="10" value="1500" style="width:140px" title="Pulse width in µs — releasing the slider moves the servo">
+              <input id="cQwSvUs" type="range" min="1000" max="2000" step="10" value="1500" style="width:140px" title="Pulse width in µs — the servo follows the slider as you drag">
               <input id="cQwSvNum" type="number" min="1000" max="2000" step="10" value="1500" style="width:64px" title="Pulse width in µs (clamped to the channel's limits)"><span class="dim">µs</span>
               <span class="dim" id="cQwSvLim" title="Allowed pulse range for this channel">1000–2000 µs</span>
               <label title="Widen the range to 500–2500 µs (asks first — many servos stall at their end stops)"><input type="checkbox" id="cQwSvWide"> wide</label></div>
@@ -3416,7 +3419,7 @@ <h2 id="modalTitle">Import error</h2>
 </div>
 
 <footer id="footer">
-  <span class="foot-left">Arena Studio v0.96 | 2026-10-12 16:50 ET · <a href="https://github.com/reiserlab/webDisplayTools" target="_blank" rel="noopener" title="webDisplayTools on GitHub: source, issues, and release notes (docs/development/arena-studio-release-notes.md)">GitHub</a></span>
+  <span class="foot-left">Arena Studio v0.96 | 2026-10-12 17:19 ET · <a href="https://github.com/reiserlab/webDisplayTools" target="_blank" rel="noopener" title="webDisplayTools on GitHub: source, issues, and release notes (docs/development/arena-studio-release-notes.md)">GitHub</a></span>
   <!-- Course-repo quick-links: open protocols / logs / patterns in a new tab.
        Hrefs built from the configured repo + bench id (updateGhQuickLinks). -->
   <span id="ghQuickLinks" title="Open the course repo on GitHub (new tab)">
@@ -3436,6 +3439,7 @@ <h2 id="modalTitle">Import error</h2>
 <script src="js/studio-panel-inventory.js"></script>
 <script src="js/qwiic-drivers.js"></script>
 <script src="js/studio-qwiic.js"></script>
+<script src="js/panel-color.js"></script> <!-- color-bank test figure (PanelColor.bankAt) -->
 <script src="js/arena-link.js"></script>
 <script src="js/arena-runner-g6.js?v=20260926-cl-start"></script> <!-- ?v= forces a fresh load: a cached runner/client silently runs the old closed-loop start -->
 <script src="js/run-log.js"></script>
@@ -6195,11 +6199,22 @@ <h2 id="modalTitle">Import error</h2>
         }
         qwRenderDevice();
     }
+    // Picking a device shows a reading at once; a running Live readout just moves to
+    // the new device (each tick reads whatever is selected).
     function qwSelect(key) {
         if (key === qw.selKey) return;
-        qwStopLive('device changed');
         qw.selKey = key;
         qwRenderSelection();
+        qwReadSelected();
+    }
+    function qwReadSelected() {
+        const item = qw.selKey && qwItem(qw.selKey);
+        if (!item || QD.KINDS[item.kind].role === 'actuator') return; // actuators refresh in qwRenderDevice
+        if (!qwGate('read').ok || qw.inFlight) return;
+        qw.inFlight = true;
+        qwReadOnce({ quiet: true })
+            .catch((e) => { qwSetStatus('error: ' + e.message); clog('qwiic: ' + e.message, 'err'); })
+            .finally(() => { qw.inFlight = false; });
     }
     // fromDom=false: the defaults (rig config, else the KINDS default) — used while the
     // option selects still belong to the PREVIOUS device.
@@ -6393,6 +6408,7 @@ <h2 id="modalTitle">Import error</h2>
             const yamlBtn = $('cQwYaml');
             if (yamlBtn) yamlBtn.disabled = !d.devices.some((it) => it.kind);
             qwRenderSelection();
+            if (!setup) setTimeout(qwReadSelected, 0); // a fresh Scan shows the first device's reading
             return qw.check;
         } catch (e) {
             qwSetStatus('error: ' + e.message);
@@ -6535,7 +6551,8 @@ <h2 id="modalTitle">Import error</h2>
         const lim = $('cQwSvLim');
         if (lim) lim.textContent = s.min + '–' + s.max + ' µs';
     }
-    async function qwServo(action) {
+    async function qwServo(action, opts) {
+        const quiet = !!(opts && opts.quiet);
         const g = qwGate('read');
         const s = qwServoSpec();
         if (!g.ok || !s.item || s.item.kind !== 'pca9685') { clog('qwiic: ' + (g.ok ? 'select the PCA9685 first' : g.reason), 'err'); return; }
@@ -6562,11 +6579,13 @@ <h2 id="modalTitle">Import error</h2>
             if (rb[1] !== o) throw new Error('read-back OFF ' + rb[1] + ' ≠ ' + o);
             return o;
         });
-        $('cQwSvUs').value = us;
-        $('cQwSvNum').value = us;
-        qwReadOnce({ quiet: true }).catch(() => {}); // refresh the PWM / oscillator readout
+        if (!quiet) {
+            $('cQwSvUs').value = us;
+            $('cQwSvNum').value = us;
+            qwReadOnce({ quiet: true }).catch(() => {}); // refresh the PWM / oscillator readout
+        }
         if (out) out.textContent = 'ch' + s.ch + ' → ' + us + ' µs (OFF count ' + off + ' @ ' + drv.freqHz.toFixed(2) + ' Hz, read back ✓)';
-        clog('qwiic: servo ch' + s.ch + ' → ' + us + ' µs (count ' + off + ')', 'info');
+        if (!quiet) clog('qwiic: servo ch' + s.ch + ' → ' + us + ' µs (count ' + off + ')', 'info');
     }
     async function qwCopyYaml(which) {
         if (!qw.discovery || qw.discovery.error) { clog('qwiic: scan first', 'err'); return; }
@@ -6611,7 +6630,9 @@ <h2 id="modalTitle">Import error</h2>
         const sl = $('cQwSvUs');
         const nb = $('cQwSvNum');
         if (sl && nb) {
-            sl.addEventListener('input', () => { nb.value = sl.value; });
+            // The servo follows the slider while dragging (single-flight, latest wins); release logs.
+            const svLive = liveSender(() => qwServo('go', { quiet: true }));
+            sl.addEventListener('input', () => { nb.value = sl.value; svLive(); });
             sl.addEventListener('change', () => { qwServo('go').catch((e) => clog('qwiic: servo — ' + e.message, 'err')); });
             nb.addEventListener('change', () => { sl.value = nb.value; });
         }
@@ -7019,13 +7040,17 @@ <h2 id="modalTitle">Import error</h2>
         crawclear: () => { logEl().innerHTML = ''; },
         crawcopy: async () => { try { await navigator.clipboard.writeText(logEl().innerText); } catch (e) {} },
         // depth toggles (also set the module-block stream depth)
-        cgs16: (e) => { segPick(e, 'cGs16', 'cGs2'); if (Studio.setStreamGs) Studio.setStreamGs(16); if ($('cLevel')) $('cLevel').parentElement.style.opacity = '1'; },
-        cgs2: (e) => { segPick(e, 'cGs2', 'cGs16'); if (Studio.setStreamGs) Studio.setStreamGs(2); },
+        cgs16: (e) => { segPick(e, 'cGs16', 'cGs2'); if (Studio.setStreamGs) Studio.setStreamGs(16); if ($('cLevel')) $('cLevel').parentElement.style.opacity = '1';  if (Studio.restreamLast) Studio.restreamLast(); },
+        cgs2: (e) => { segPick(e, 'cGs2', 'cGs16'); if (Studio.setStreamGs) Studio.setStreamGs(2);  if (Studio.restreamLast) Studio.restreamLast(); },
         // stream test figures (builders live in the module block)
         cstreamff: () => Studio.doStream && Studio.doStream('fullfield'),
         cstreampm: () => Studio.doStream && Studio.doStream('panelmap'),
         cstreamor: () => Studio.doStream && Studio.doStream('orientation'),
         cstreamck: () => Studio.doStream && Studio.doStream('checker'),
+        cbank0: () => Studio.doStream && Studio.doStream('bank', 0),
+        cbank1: () => Studio.doStream && Studio.doStream('bank', 1),
+        cbank2: () => Studio.doStream && Studio.doStream('bank', 2),
+        cbank3: () => Studio.doStream && Studio.doStream('bank', 3),
         cpaste: () => Studio.openPasteModal && Studio.openPasteModal(),
         cloadfile: () => { if (Studio.filePlaying && Studio.filePlaying()) Studio.stopFilePlay('user'); else $('cFileInput').click(); }
     };
@@ -7493,7 +7518,28 @@ <h2 id="modalTitle">Import error</h2>
     Studio.clog = clog;
     // level slider readout + duty → module-block stream state. The duty slider
     // and its number box stay in lockstep; typed values clamp to 0–255.
-    $('cLevel').addEventListener('input', () => { $('cLevelVal').textContent = $('cLevel').value + '/15'; });
+    // Live sliders: act while dragging. liveSender() is single-flight, latest value wins
+    // (a fast drag never queues a backlog of commands); nothing is sent while a run owns
+    // the link. Drags are quiet; the release ('change') logs one line.
+    function liveSender(fn) {
+        let busy = false, pending = null, has = false;
+        return function (v) {
+            pending = v; has = true;
+            if (busy) return;
+            busy = true;
+            (async () => {
+                try {
+                    while (has) { has = false; await fn(pending); }
+                } catch (e) { clog('live update failed: ' + (e.message || e), 'err'); } finally { busy = false; }
+            })();
+        };
+    }
+    const liveOk = () => !!(session && session.connected && !session.running);
+    Studio.liveSender = liveSender;
+    // Test display: level / duty re-send the last test figure (no-op until one was sent).
+    const restreamLive = liveSender(() => (liveOk() && Studio.restreamLast ? Studio.restreamLast() : null));
+    $('cLevel').addEventListener('input', () => { $('cLevelVal').textContent = $('cLevel').value + '/15'; restreamLive(); });
+    $('cLevel').addEventListener('change', () => { if (liveOk()) clog('test display: level ' + $('cLevel').value + '/15 (re-sent the last figure)', 'info'); });
     // LED tool: slider + number box in lockstep (like duty), 0.0–100.0 in 0.1 steps,
     // with a readout of the resolved BuckPuck control voltage.
     function applyLed(v) {
@@ -7508,8 +7554,15 @@ <h2 id="modalTitle">Import error</h2>
         if (el) el.textContent = conv ? conv(n) + ' mV' : '';
     }
     Studio.applyLed = applyLed;
-    if ($('cLedPct')) $('cLedPct').addEventListener('input', () => applyLed($('cLedPct').value));
-    if ($('cLedNum')) $('cLedNum').addEventListener('change', () => applyLed($('cLedNum').value));
+    // LED power follows the slider (quiet SET_AO_VOLTAGE while dragging; one log line on release).
+    const ledMvFor = (p) => { const conv = window.ArenaRunnerG6 && window.ArenaRunnerG6.ledPercentToMv; return conv ? conv(p) : 5000; };
+    const ledLive = liveSender(async (p) => { if (liveOk()) await session.send(Wire.encodeSetAoVoltage(ledMvFor(p)), { timeoutMs: 1000 }); });
+    const ledCommitLog = () => { if (liveOk()) { const p = num('cLedPct'); clog('LED ' + p + '% → SET_AO_VOLTAGE 0xA0 ' + ledMvFor(p) + ' mV', 'tx'); } };
+    if ($('cLedPct')) {
+        $('cLedPct').addEventListener('input', () => { applyLed($('cLedPct').value); ledLive(num('cLedPct')); });
+        $('cLedPct').addEventListener('change', ledCommitLog);
+    }
+    if ($('cLedNum')) $('cLedNum').addEventListener('change', () => { applyLed($('cLedNum').value); ledLive(num('cLedPct')); ledCommitLog(); });
     if ($('cLedPct')) applyLed($('cLedPct').value);
     function applyDuty(v) {
         // A number input holding garbage reports '' (and Number('') === 0), so
@@ -7522,8 +7575,9 @@ <h2 id="modalTitle">Import error</h2>
         $('cDutyNum').value = n;
         if (Studio.setStreamDuty) Studio.setStreamDuty(n);
     }
-    $('cDuty').addEventListener('input', () => applyDuty($('cDuty').value));
-    $('cDutyNum').addEventListener('change', () => applyDuty($('cDutyNum').value));
+    $('cDuty').addEventListener('input', () => { applyDuty($('cDuty').value); restreamLive(); });
+    $('cDuty').addEventListener('change', () => { if (liveOk()) clog('test display: duty ' + $('cDuty').value + ' (re-sent the last figure)', 'info'); });
+    $('cDutyNum').addEventListener('change', () => { applyDuty($('cDutyNum').value); restreamLive(); });
 
     // console dropdown menus (Controller ▾ / Debug ▾) — open/close + click-away
     document.querySelectorAll('.cmenu[data-cmenu] > .cmenu-btn').forEach((btn) => {
@@ -9042,7 +9096,8 @@ <h2 id="modalTitle">Import error</h2>
     const cfg = Studio.currentRig && Studio.currentRig.arenaConfig;
     const arena = cfg ? arenaForConfig(cfg) : null;
     const rc = (arena && arena.num_rows) || 2;
-    const cc = (arena && arena.num_cols) || 10;
+    // Partial arenas stream their INSTALLED columns (a 1x12of18 figure is 12 panels wide).
+    const cc = (arena && (arena.columns_installed ? arena.columns_installed.length : arena.num_cols)) || 10;
     return { rowCount: rc, colCount: cc, pixelRows: rc * 20, pixelCols: cc * 20 };
 }
 function newGrid() { const a = activeArenaGeom(); return new Uint8Array(a.pixelRows * a.pixelCols); }
@@ -9078,25 +9133,70 @@ <h2 id="modalTitle">Import error</h2>
     drawGlyph(grid, a, 'R', a.pixelCols - cw - 1, midRow, val, s);
     return grid;
 }
+// Color banks (LAB-223/228 color panels): light ONLY bank k (0..3 = A..D = T0..T3) —
+// one LED in four per panel (a 10×10 lattice at 2-px pitch) — via the shared
+// bench-verified PanelColor.bankAt (host coords, row 0 = bottom; panels are 20 px,
+// so arena-global parity equals panel-local parity).
+const BANK_NAMES = ['A', 'B', 'C', 'D'];
+function genBank(k, level) {
+    const a = activeArenaGeom(); const grid = newGrid(); const val = streamGs === 2 ? 1 : level;
+    const PC = window.PanelColor;
+    const bankAt = PC ? PC.bankAt : (r, c) => 2 * ((r + 1) & 1) + (c & 1);
+    for (let r = 0; r < a.pixelRows; r++) for (let c = 0; c < a.pixelCols; c++) if (bankAt(r, c) === k) grid[r * a.pixelCols + c] = val;
+    return grid;
+}
 function genChecker() {
     const a = activeArenaGeom(); const grid = newGrid(); const val = streamGs === 2 ? 1 : 15;
     for (let pr = 0; pr < a.rowCount; pr++) for (let pc = 0; pc < a.colCount; pc++) if ((pr + pc) % 2 === 0)
         for (let y = 0; y < 20; y++) for (let x = 0; x < 20; x++) setPx(grid, a, pr * 20 + y, pc * 20 + x, val);
     return grid;
 }
+// The controller accepts stream frames of exactly ITS compiled geometry (0xCB rows ×
+// cols; fw constants.h panel_count_per_frame): 2x10 on the CSHL boards, 4x12 on the
+// arena_12-18 build. The rig's figure is placed into that frame: installed columns
+// from the left, the rig's rows repeated up the frame (so a one-row bench install
+// lights whichever row connector its panels are on). Firmware without 0xCB: the
+// legacy 20-panel rule.
+function streamTarget() {
+    const rig = activeArenaGeom();
+    const fv = Studio.firmwareVersion;
+    if (fv && fv.rows > 0 && fv.cols > 0) {
+        if (rig.rowCount > fv.rows || rig.colCount > fv.cols) {
+            return { ok: false, rig, reason: 'the rig is ' + rig.rowCount + '×' + rig.colCount + ' panels but this firmware build streams ' + fv.rows + '×' + fv.cols };
+        }
+        return { ok: true, rig, rows: fv.rows, cols: fv.cols };
+    }
+    if (rig.rowCount * rig.colCount === 20) return { ok: true, rig, rows: rig.rowCount, cols: rig.colCount };
+    return { ok: false, rig, reason: 'this firmware does not report its panel geometry (0xCB), so only 20-panel arenas can be streamed' };
+}
+function toFirmwareGrid(grid, t) {
+    const rp = t.rig.pixelRows, cp = t.rig.pixelCols;
+    const R = t.rows * 20, C = t.cols * 20;
+    if (R === rp && C === cp) return grid;
+    const out = new Uint8Array(R * C);
+    for (let r = 0; r < R; r++) out.set(grid.subarray((r % rp) * cp, (r % rp) * cp + cp), r * C);
+    return out;
+}
+function encodeStreamPat(grid, gs, rows, cols) {
+    return window.PatEncoder.encode({
+        generation: 'G6', gs_val: gs, numFrames: 1, rowCount: rows, colCount: cols,
+        pixelRows: rows * 20, pixelCols: cols * 20, frames: [grid], stretchValues: [streamDuty]
+    });
+}
 function buildStreamFrame(grid, gs) {
-    const a = activeArenaGeom();
-    const patData = {
-        generation: 'G6', gs_val: gs, numFrames: 1, rowCount: a.rowCount, colCount: a.colCount,
-        pixelRows: a.pixelRows, pixelCols: a.pixelCols, frames: [grid], stretchValues: [streamDuty]
-    };
-    const patArrayBuffer = window.PatEncoder.encode(patData);
-    const buf = new Uint8Array(patArrayBuffer);
-    const len = Wire.STREAM_FRAME_BYTES[gs === 2 ? 'GS2' : 'GS16'];
+    const t = streamTarget();
+    if (!t.ok) throw new Error(t.reason);
+    const panels = t.rows * t.cols;
+    const fwPat = encodeStreamPat(toFirmwareGrid(grid, t), gs, t.rows, t.cols);
+    const buf = new Uint8Array(fwPat);
+    const len = Wire.streamFrameBytes(panels, gs);
     const payload = buf.subarray(window.PatEncoder.G6_HEADER_SIZE, window.PatEncoder.G6_HEADER_SIZE + len);
-    return { bytes: Wire.encodeStreamFrame(payload), patArrayBuffer };
+    // The thumbnail shows the RIG's figure (the preview draws the rig's arena).
+    const samePat = t.rows === t.rig.rowCount && t.cols === t.rig.colCount;
+    const patArrayBuffer = samePat ? fwPat : encodeStreamPat(grid, gs, t.rig.rowCount, t.rig.colCount);
+    return { bytes: Wire.encodeStreamFrame(payload, { panels }), patArrayBuffer, target: t };
 }
-function streamable() { const a = activeArenaGeom(); return a.rowCount * a.colCount === 20; } // FW accepts 20-panel frames only
+function streamable() { return streamTarget().ok; }
 function renderStreamThumb(patArrayBuffer, hostId) {
     const host = $(hostId || 'cStreamThumb');
     if (!host || !PP) return;
@@ -9118,29 +9218,42 @@ <h2 id="modalTitle">Import error</h2>
 Studio.setStreamGs = (gs) => { streamGs = gs; };
 Studio.setStreamDuty = (d) => { streamDuty = d; };
 // Stream one already-built pixel grid (shared by the figures + paste-frame).
-async function streamGrid(grid, gs, label) {
+async function streamGrid(grid, gs, label, opts) {
     const clog = Studio.clog || Studio.rawLog;
     if (!Studio.session || !Studio.session.connected) { clog('connect first', 'err'); return false; }
-    if (!streamable()) { clog('stream: needs a 20-panel arena (e.g. G6_2x10) — unlock the session rig selector in ⚙ Settings', 'err'); return false; }
+    const tgt = streamTarget();
+    if (!tgt.ok) { clog('stream: ' + tgt.reason + ' — check the session rig in ⚙ Settings', 'err'); return false; }
     let built;
     try { built = buildStreamFrame(grid, gs); } catch (e) { clog('stream build failed: ' + (e.message || e), 'err'); return false; }
     renderStreamThumb(built.patArrayBuffer);
     try {
         await Studio.session.send(built.bytes, { expectedCmd: Wire.OPCODES.STREAM_FRAME, timeoutMs: 1500 });
-        clog('› STREAM_FRAME 0x32 · ' + label + ' (' + (gs === 2 ? 'GS2' : 'GS16') + ')', 'tx');
+        const t = built.target;
+        const mapped = t.rows !== t.rig.rowCount || t.cols !== t.rig.colCount ? ' · ' + t.rig.rowCount + '×' + t.rig.colCount + ' rig in a ' + t.rows + '×' + t.cols + ' firmware frame' : '';
+        if (!opts || !opts.quiet) clog('› STREAM_FRAME 0x32 · ' + label + ' (' + (gs === 2 ? 'GS2' : 'GS16') + ')' + mapped, 'tx');
         return true;
     } catch (e) { clog('stream send failed: ' + (e.message || e), 'err'); return false; }
 }
 Studio.streamGrid = streamGrid;
-Studio.doStream = async function (kind) {
+// Remember the last test figure so the level / duty sliders can re-send it live.
+let lastStreamFigure = null;
+Studio.doStream = async function (kind, arg, opts) {
     const level = Number(($('cLevel') || {}).value || 15);
     let grid;
+    let label = kind;
     if (kind === 'fullfield') grid = genUniform(level);
     else if (kind === 'panelmap') grid = genPanelMap();
     else if (kind === 'orientation') grid = genOrient();
     else if (kind === 'checker') grid = genChecker();
-    else return;
-    await streamGrid(grid, streamGs, kind);
+    else if (kind === 'bank') { grid = genBank(arg, level); label = 'color bank ' + BANK_NAMES[arg] + ' (T' + arg + ')'; }
+    else return false;
+    lastStreamFigure = { kind, arg };
+    return streamGrid(grid, streamGs, label, opts);
+};
+// Re-send the last figure (level / duty / depth changed). No-op before the first figure.
+Studio.restreamLast = async function () {
+    if (!lastStreamFigure || !Studio.session || !Studio.session.connected || Studio.session.running) return false;
+    return Studio.doStream(lastStreamFigure.kind, lastStreamFigure.arg, { quiet: true });
 };
 
 // ---- batch panel programming (ISP) — the panel-firmware tile's batch row ----
@@ -9526,7 +9639,8 @@ <h2 id="modalTitle">Import error</h2>
     const clog = Studio.clog || Studio.rawLog;
     Studio.stopFilePlay('silent');
     if (!Studio.session || !Studio.session.connected) { clog('connect first', 'err'); return; }
-    if (!streamable()) { clog('stream: needs a 20-panel arena (e.g. G6_2x10)', 'err'); return; }
+    const ft = streamTarget();
+    if (!ft.ok || ft.rows * ft.cols !== 20) { clog('stream: file streaming (.bin/.pat) needs a 20-panel controller frame (e.g. G6_2x10)' + (ft.ok ? ' — this firmware streams ' + ft.rows + '×' + ft.cols : ''), 'err'); return; }
     if (!Bin) { clog('bin-classifier unavailable', 'err'); return; }
     let buf;
     try { buf = new Uint8Array(await file.arrayBuffer()); } catch (e) { clog('file read failed: ' + (e.message || e), 'err'); return; }
@@ -17907,7 +18021,7 @@ <h2 id="modalTitle">Import error</h2>
     '[data-cmd="cqwread"]': 'Take one reading from the selected device.',
     '#cQwLive': 'Keep reading the selected device about once a second. Pauses by itself during a run.',
     '[data-cmd="cqwbumpcheck"]': 'Was the motion sensor bumped since the last check? Checking resets the answer.',
-    '#cQwSvUs': 'Servo position. Let go of the slider to move the servo.',
+    '#cQwSvUs': 'Servo position. The servo follows the slider as you move it.',
     '[data-cmd="cqwsvrelease"]': 'Let the servo go limp (it stops holding its position).',
     '#qwiicChip': 'The sensors on the Qwiic connector compared with this rig’s list. Red = a listed sensor is missing; amber = something is plugged in that isn’t listed. Click to open them in the Console.',
     '.rail-btn[data-panel="fw"]': 'Update or check the firmware on the LED panels.',
diff --git a/docs/development/arena-studio-release-notes.md b/docs/development/arena-studio-release-notes.md
index 25971a62..61ba3d34 100644
--- a/docs/development/arena-studio-release-notes.md
+++ b/docs/development/arena-studio-release-notes.md
@@ -10,6 +10,10 @@ history lives here. Newest first. (Per-session engineering detail stays in
 - **Console → Qwiic: find and try the sensors on the arena's Qwiic / STEMMA QT connector.** Scan lists every device on the bus, identifies the supported parts (SHT4x temperature/humidity, LSM6DSOX tilt + bump, TSL2591 / VEML7700 / AS7343 light, PCA9685 servo driver) and compares them with the rig file. Pick one device to see its readings in real units, once or live; the motion sensor has a bump check, and the servo board a position slider with Center and Release. This panel is for testing — nothing in it is written to run logs.
 - **Rig files can list their Qwiic peripherals (`peripherals:`).** On connect the Studio scans once and shows a Qwiic chip in the top bar: green when every listed device is there, red when one is missing (no retry), amber when something is plugged in that the rig file doesn't list. **Copy as rig YAML** gives you the lines to add.
 - Controllers without a Qwiic connector are unaffected: the Studio never sends them I2C commands, and the chip stays hidden.
+- **Console → Qwiic: clicking a device shows its reading straight away, and Live keeps running as you switch devices.** The servo follows its slider as you drag.
+- **Console sliders act as you move them.** Test display level and duty re-send the last test figure, and LED power sets the LED, while you drag (never during a run).
+- **Test display works on more arenas.** Figures are sent at the controller's own frame size, so the 1×12 bench arena (and other non-2×10 rigs on matching firmware) can show full-field, panel map, orientation and checker.
+- **Test display → color: light one LED bank at a time (A–D).** For color panels: each button lights only that bank — one LED in four per panel — at the chosen level.
 - **Two new rigs in ⚙ Settings:** the arena_12-18 bench (one panel high, 12 of 18 columns, its six Qwiic boards listed) and the 10-of-14 ring (three panels high). Both show their installed panels centered at the front in the Pattern Designer's views.
 
 ## v0.94 (2026-09-30) · LAB-158 ports (Protocol ▾, ⚙ Settings, two-column Console) + visibility themes · Multi-color G6 panels V1 — Panel LEDs layout, ON color, per-bank preview (LAB-228) · Flasher + Studio picker: one production build from the published catalog; legacy images hashed, never default (panel-fw-v1.3.1)
diff --git a/js/arena-wire-g6.js b/js/arena-wire-g6.js
index 3c008e37..eda58d61 100644
--- a/js/arena-wire-g6.js
+++ b/js/arena-wire-g6.js
@@ -331,18 +331,37 @@ const ArenaWireG6 = (function () {
      * @param {Uint8Array|number[]} payload per-frame body (1064 GS2 / 4064 GS16)
      * @returns {Uint8Array} on-wire stream frame [0x32, len_lo, len_hi, ...payload]
      */
-    function encodeStreamFrame(payload) {
+    // Stream-frame payload size for a firmware build that drives `panels` panels:
+    // 4-byte prefix + one block per panel (GS2 53 B, GS16 203 B). The firmware
+    // accepts exactly its compiled panel count (constants.h panel_count_per_frame):
+    // 20 on the 2x10 build (1064 / 4064 = STREAM_FRAME_BYTES), 48 on 4x12, etc.
+    const STREAM_BLOCK_BYTES = { GS2: 53, GS16: 203 };
+    function streamFrameBytes(panels, gs) {
+        requireInt(panels, 'panels');
+        if (panels < 1) throw new RangeError('panels must be >= 1, got ' + panels);
+        return 4 + panels * (gs === 2 ? STREAM_BLOCK_BYTES.GS2 : STREAM_BLOCK_BYTES.GS16);
+    }
+
+    // opts.panels: the connected firmware's panel count (default 20 — the 2x10 sizes).
+    function encodeStreamFrame(payload, opts) {
         const body = payload instanceof Uint8Array ? payload : Uint8Array.from(payload);
-        if (body.length !== STREAM_FRAME_BYTES.GS2 && body.length !== STREAM_FRAME_BYTES.GS16) {
+        const panels = opts && opts.panels !== undefined ? opts.panels : 20;
+        const gs2 = streamFrameBytes(panels, 2);
+        const gs16 = streamFrameBytes(panels, 16);
+        if (body.length !== gs2 && body.length !== gs16) {
             throw new RangeError(
-                'stream-frame payload must be ' +
-                    STREAM_FRAME_BYTES.GS2 +
+                'stream-frame payload for ' +
+                    panels +
+                    ' panels must be ' +
+                    gs2 +
                     ' (GS2) or ' +
-                    STREAM_FRAME_BYTES.GS16 +
+                    gs16 +
                     ' (GS16) bytes, got ' +
                     body.length
             );
         }
+        if (body.length > 0xffff)
+            throw new RangeError('stream-frame payload exceeds the u16 length field');
         const out = new Uint8Array(3 + body.length);
         out[0] = OPCODES.STREAM_FRAME; // 0x32
         out[1] = body.length & 0xff; // payload length lo
@@ -1514,6 +1533,8 @@ const ArenaWireG6 = (function () {
         PANEL_STATUS_NAMES,
         PANEL_INVENTORY_FLAGS,
         STREAM_FRAME_BYTES,
+        STREAM_BLOCK_BYTES,
+        streamFrameBytes,
 
         // Encoders (request frames)
         encodeAllOn,
diff --git a/tests/test-arena-wire-g6.js b/tests/test-arena-wire-g6.js
index 4bd7eb97..f2ac0da3 100644
--- a/tests/test-arena-wire-g6.js
+++ b/tests/test-arena-wire-g6.js
@@ -293,6 +293,22 @@ checkBool(
 // Only the two firmware-accepted sizes are valid (mode inferred from size).
 checkThrows('stream wrong size 100 throws', () => Wire.encodeStreamFrame(new Uint8Array(100)));
 checkThrows('stream wrong size 4063 throws', () => Wire.encodeStreamFrame(new Uint8Array(4063)));
+// Firmware-sized frames: the controller accepts exactly its compiled panel count.
+check('streamFrameBytes(20, GS2) = STREAM_FRAME_BYTES.GS2', Wire.streamFrameBytes(20, 2), 1064);
+check('streamFrameBytes(20, GS16) = STREAM_FRAME_BYTES.GS16', Wire.streamFrameBytes(20, 16), 4064);
+check('streamFrameBytes(48, GS2) — 4x12 build (arena_12-18)', Wire.streamFrameBytes(48, 2), 2548);
+check('streamFrameBytes(48, GS16) — 4x12 build', Wire.streamFrameBytes(48, 16), 9748);
+check(
+    'streamFrameBytes(40, GS16) — 4x10 build (fw constants.h 8124)',
+    Wire.streamFrameBytes(40, 16),
+    8124
+);
+const sf48 = Wire.encodeStreamFrame(new Uint8Array(9748), { panels: 48 });
+checkBytes('48-panel GS16 header: 32 + u16 LE 9748', sf48.slice(0, 3), '32 14 26');
+checkThrows('a 20-panel payload is refused for a 48-panel build', () =>
+    Wire.encodeStreamFrame(new Uint8Array(4064), { panels: 48 })
+);
+checkThrows('panels 0 rejected', () => Wire.streamFrameBytes(0, 16));
 
 console.log('\n=== decodeResponse framing ===');
 // get-controller-info reply: [len=4, status=0, echo=0xC2, version=2, cap=0x11].
diff --git a/tests/test-studio-qwiic.js b/tests/test-studio-qwiic.js
index 3f60494b..254ef0f6 100644
--- a/tests/test-studio-qwiic.js
+++ b/tests/test-studio-qwiic.js
@@ -515,6 +515,33 @@ const item = (addr, kind, extra) =>
             /if \(was\) qwSetStatus\(qw\.idleStatus/.test(html) &&
                 /if \(qw\.live\) qwSetStatus\('live · '/.test(html)
         );
+        ok(
+            'clicking a device reads it; Live keeps running across selections',
+            /function qwSelect\(key\) \{[\s\S]{0,200}qwReadSelected\(\);/.test(html) &&
+                !/qwStopLive\('device changed'\)/.test(html)
+        );
+        ok(
+            'servo follows the slider while dragging (single-flight)',
+            /const svLive = liveSender\(\(\) => qwServo\('go', \{ quiet: true \}\)\)/.test(html)
+        );
+        ok(
+            'live level / duty / LED sliders go through liveSender',
+            /const restreamLive = liveSender\(/.test(html) &&
+                /const ledLive = liveSender\(/.test(html)
+        );
+        ok(
+            'stream frames are sized to the firmware geometry (0xCB), not just 20 panels',
+            /function streamTarget\(\)/.test(html) &&
+                /Wire\.encodeStreamFrame\(payload, \{ panels \}\)/.test(html)
+        );
+        ok(
+            'Test display color banks A–D via PanelColor.bankAt',
+            ['cbank0', 'cbank1', 'cbank2', 'cbank3'].every((c) =>
+                html.includes('data-cmd="' + c + '"')
+            ) &&
+                /function genBank\(k, level\)/.test(html) &&
+                html.includes('<script src="js/panel-color.js"')
+        );
         ok(
             'undeclared devices flagged in table + selection',
             /⚠ undeclared/.test(html) && /not in the rig YAML/.test(html)

From 0a0c03a75e1f3130b069f825d3223bded610c89e Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Mon, 12 Oct 2026 18:42:59 -0400
Subject: [PATCH 15/17] =?UTF-8?q?chore:=20drop=20the=20self-bump=20(v0.96?=
 =?UTF-8?q?=20footer=20+=20notes=20entry)=20=E2=80=94=20the=20release=20co?=
 =?UTF-8?q?mmit=20bumps;=20notes=20live=20in=20the=20PR=20body?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 arena_studio.html                              |  2 +-
 docs/development/arena-studio-release-notes.md | 12 ------------
 tests/test-studio-qwiic.js                     |  5 -----
 3 files changed, 1 insertion(+), 18 deletions(-)

diff --git a/arena_studio.html b/arena_studio.html
index f9c3fa64..2b5aea16 100644
--- a/arena_studio.html
+++ b/arena_studio.html
@@ -3419,7 +3419,7 @@ <h2 id="modalTitle">Import error</h2>
 </div>
 
 <footer id="footer">
-  <span class="foot-left">Arena Studio v0.96 | 2026-10-12 17:19 ET · <a href="https://github.com/reiserlab/webDisplayTools" target="_blank" rel="noopener" title="webDisplayTools on GitHub: source, issues, and release notes (docs/development/arena-studio-release-notes.md)">GitHub</a></span>
+  <span class="foot-left">Arena Studio v0.94 | 2026-09-30 07:22 ET · <a href="https://github.com/reiserlab/webDisplayTools" target="_blank" rel="noopener" title="webDisplayTools on GitHub: source, issues, and release notes (docs/development/arena-studio-release-notes.md)">GitHub</a></span>
   <!-- Course-repo quick-links: open protocols / logs / patterns in a new tab.
        Hrefs built from the configured repo + bench id (updateGhQuickLinks). -->
   <span id="ghQuickLinks" title="Open the course repo on GitHub (new tab)">
diff --git a/docs/development/arena-studio-release-notes.md b/docs/development/arena-studio-release-notes.md
index 61ba3d34..e337b4fc 100644
--- a/docs/development/arena-studio-release-notes.md
+++ b/docs/development/arena-studio-release-notes.md
@@ -4,18 +4,6 @@ The Studio's footer used to carry the full changelog inline; it now shows one li
 history lives here. Newest first. (Per-session engineering detail stays in
 `arena-studio-handover.md` and the design docs — this file is the user-facing what-changed list.)
 
-## v0.96 (2026-10-12) · Qwiic sensors in the Console (LAB-214)
-
-<!-- LAB-214 PR 1 -->
-- **Console → Qwiic: find and try the sensors on the arena's Qwiic / STEMMA QT connector.** Scan lists every device on the bus, identifies the supported parts (SHT4x temperature/humidity, LSM6DSOX tilt + bump, TSL2591 / VEML7700 / AS7343 light, PCA9685 servo driver) and compares them with the rig file. Pick one device to see its readings in real units, once or live; the motion sensor has a bump check, and the servo board a position slider with Center and Release. This panel is for testing — nothing in it is written to run logs.
-- **Rig files can list their Qwiic peripherals (`peripherals:`).** On connect the Studio scans once and shows a Qwiic chip in the top bar: green when every listed device is there, red when one is missing (no retry), amber when something is plugged in that the rig file doesn't list. **Copy as rig YAML** gives you the lines to add.
-- Controllers without a Qwiic connector are unaffected: the Studio never sends them I2C commands, and the chip stays hidden.
-- **Console → Qwiic: clicking a device shows its reading straight away, and Live keeps running as you switch devices.** The servo follows its slider as you drag.
-- **Console sliders act as you move them.** Test display level and duty re-send the last test figure, and LED power sets the LED, while you drag (never during a run).
-- **Test display works on more arenas.** Figures are sent at the controller's own frame size, so the 1×12 bench arena (and other non-2×10 rigs on matching firmware) can show full-field, panel map, orientation and checker.
-- **Test display → color: light one LED bank at a time (A–D).** For color panels: each button lights only that bank — one LED in four per panel — at the chosen level.
-- **Two new rigs in ⚙ Settings:** the arena_12-18 bench (one panel high, 12 of 18 columns, its six Qwiic boards listed) and the 10-of-14 ring (three panels high). Both show their installed panels centered at the front in the Pattern Designer's views.
-
 ## v0.94 (2026-09-30) · LAB-158 ports (Protocol ▾, ⚙ Settings, two-column Console) + visibility themes · Multi-color G6 panels V1 — Panel LEDs layout, ON color, per-bank preview (LAB-228) · Flasher + Studio picker: one production build from the published catalog; legacy images hashed, never default (panel-fw-v1.3.1)
 
 <!-- #238 -->
diff --git a/tests/test-studio-qwiic.js b/tests/test-studio-qwiic.js
index 254ef0f6..96e94fb8 100644
--- a/tests/test-studio-qwiic.js
+++ b/tests/test-studio-qwiic.js
@@ -553,11 +553,6 @@ const item = (addr, kind, extra) =>
                 /\n\s+qwiic: 'Sensors on the Qwiic connector/.test(html)
         );
         ok('panel order rule', html.includes('.panel[data-panel="qwiic"]{order:10}'));
-        ok(
-            'footer bumped past v0.94',
-            !/Arena Studio v0\.94 \|/.test(html) &&
-                /Arena Studio v0\.\d+ \| \d{4}-\d\d-\d\d \d\d:\d\d ET/.test(html)
-        );
     }
 
     console.log('\n=== bench rigs + arena configs ===');

From 6bbd8d1b36218fe726bbd2f0dd6b42ea54b2792e Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Tue, 13 Oct 2026 11:51:29 -0400
Subject: [PATCH 16/17] =?UTF-8?q?fix(studio):=20rc4=20review=20=E2=80=94?=
 =?UTF-8?q?=20full-grid=20stream=20mapping=20(2=C3=978of10=20regression),?=
 =?UTF-8?q?=20live=20gates,=20deferred=20Qwiic=20setup=20(LAB-214)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

From the adversarial review of candidate 2026-10-06 rc4 (PR #247 comment):
- BLOCKING: test figures are drawn on the rig's FULL arena grid again
  (activeArenaGeom = num_rows × num_cols); grid column c → firmware column c and
  only the installed columns must fit the firmware frame. rc4 collapsed partial
  arenas to installed width and left-aligned them, which shifted every figure one
  panel on G6_2x8of10 (columns 1–8) with 0xCB firmware and refused it outright on
  pre-0xCB firmware; it also mis-numbered the ISP progress map and changed the
  paste dimensions. Mapping now lives in js/studio-stream-geometry.js with Node
  tests (2×10 / 2×8of10 identity on both firmware kinds, 1×12of18 → 4×12).
- Live slider re-streams and Qwiic reads pause during an ISP batch and a
  post-mortem (a stream re-activates the display; 0xC8/0xC9 need it stopped).
- Connect-time Qwiic setup starts after the controller reads and is not awaited,
  so its sensor configure waits never delay the SD listing.
- Orientation glyphs sit inside the installed span (1×12of18's "R").
- Best-effort servo release (PCA9685 all off) on an intentional disconnect.
- Docs: drop the stale "v0.96" (the release commit owns versions).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CLAUDE.md                               |   9 +-
 arena_studio.html                       |  76 +++++++-------
 docs/development/arena-studio-parity.md |   2 +-
 js/studio-stream-geometry.js            | 129 ++++++++++++++++++++++++
 tests/test-studio-qwiic.js              |  29 +++++-
 tests/test-studio-stream-geometry.js    | 123 ++++++++++++++++++++++
 6 files changed, 329 insertions(+), 39 deletions(-)
 create mode 100644 js/studio-stream-geometry.js
 create mode 100644 tests/test-studio-stream-geometry.js

diff --git a/CLAUDE.md b/CLAUDE.md
index f8ba4842..70aabc9f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -622,7 +622,7 @@ fix flows to every page automatically; two hand-written HTML pages never will.
   like 0xA8 on the 0xCB telemetry flag; `Studio.readCrashReport()` logs a `crash_report` event.
   Breadcrumb ops 6–9 are the SET_FRAME_POSITION sub-steps (disarm timer / preload / arm / respond).
 
-- **Qwiic peripherals (LAB-214, v0.96):** the controller exposes only a sensor-agnostic I2C bridge
+- **Qwiic peripherals (LAB-214):** the controller exposes only a sensor-agnostic I2C bridge
   (`GET_I2C_SCAN` 0xB0, `I2C_TRANSFER` 0xB1; 0xB2–0xBF stay reserved), advertised by the 0xC2
   feature bit `qwiic_i2c` — **gate EVERY I2C send on it** (jack-less 10-10 / 2x10 builds answer
   CE_UNKNOWN_CMD + an error glyph). All register maps are host-side in `js/qwiic-drivers.js`
@@ -639,6 +639,13 @@ fix flows to every page automatically; two hand-written HTML pages never will.
   connect-time setup never arms it. (4) Bench quirks are load-bearing (SHT4x two-leg read; LIR +
   INT_CLR_ON_READ + INT1 routing; PCA9685 ALLCALL shadow at 0x70 decided from MODE1, cleared by
   configure). The rig fetch (`fetchRigSections`) parses `io:` and `peripherals:` from one read.
+- **Test display streams at the CONTROLLER's frame geometry** (0xCB rows × cols = fw
+  `panel_count_per_frame`), not a fixed 20 panels. The mapping lives in `js/studio-stream-geometry.js`
+  (Node-tested): figures are drawn on the rig's FULL arena grid (`activeArenaGeom()` = num_rows ×
+  num_cols — NEVER installed-columns-only: G6_2x8of10's panels are physical columns 1–8), grid column
+  c → firmware column c (only installed columns must fit), rig rows repeated up the frame; no 0xCB →
+  the legacy 20-panel rule. Live Console sliders go through `liveSender()` (single-flight, latest
+  wins) and pause during runs, ISP batches and post-mortems.
 
 ## Pattern Designer (`pattern_editor.html`)
 
diff --git a/arena_studio.html b/arena_studio.html
index 2b5aea16..54c933c1 100644
--- a/arena_studio.html
+++ b/arena_studio.html
@@ -3439,6 +3439,7 @@ <h2 id="modalTitle">Import error</h2>
 <script src="js/studio-panel-inventory.js"></script>
 <script src="js/qwiic-drivers.js"></script>
 <script src="js/studio-qwiic.js"></script>
+<script src="js/studio-stream-geometry.js"></script>
 <script src="js/panel-color.js"></script> <!-- color-bank test figure (PanelColor.bankAt) -->
 <script src="js/arena-link.js"></script>
 <script src="js/arena-runner-g6.js?v=20260926-cl-start"></script> <!-- ?v= forces a fresh load: a cached runner/client silently runs the old closed-loop start -->
@@ -4385,6 +4386,7 @@ <h2 id="modalTitle">Import error</h2>
             return;
         }
         if (Studio.session.connected) {
+            if (Studio.qwiicReleaseServos) { try { await Studio.qwiicReleaseServos(); } catch (_) { /* best-effort */ } }
             try { await Studio.session.disconnect(); } catch (e) { /* ignore */ }
             return;
         }
@@ -6107,6 +6109,7 @@ <h2 id="modalTitle">Import error</h2>
         if (!qwHas()) return { ok: false, reason: 'no Qwiic I2C bridge on this controller (0xC2 feature bit 1 clear — arena_12-18 boards only)' };
         if (session.running) return { ok: false, reason: what === 'scan' ? 'refused — a run is active (the scan stalls the controller ~10 ms)' : 'paused — run active' };
         if (Studio._activePostmortem) return { ok: false, reason: 'paused — post-mortem owns the link' };
+        if (Studio.ispBatchRunning && Studio.ispBatchRunning()) return { ok: false, reason: 'paused — panel firmware batch running' };
         return { ok: true };
     }
     function qwSetStatus(t) {
@@ -6491,6 +6494,17 @@ <h2 id="modalTitle">Import error</h2>
         if (note) note.textContent = running ? 'a run owns the bump latch — checks are off until it ends' : '';
     }
     Studio.qwiicUpdateRunGates = qwUpdateRunGates;
+    // Intentional disconnect: release every PCA9685 this session configured (servos go
+    // limp rather than holding their last position unattended). Best-effort, time-boxed.
+    Studio.qwiicReleaseServos = async function () {
+        if (!qw.discovery || qw.discovery.error || !qwHas() || !(session && session.connected)) return;
+        const pcas = qw.discovery.devices.filter((it) => it.kind === 'pca9685' && qw.configured[it.key] && it.driver);
+        if (!pcas.length) return;
+        qwStopLive();
+        const work = Promise.all(pcas.map((it) => QD.withDevice(qwBus(), it.dev, () => it.driver.allOff()).catch(() => {})));
+        await Promise.race([work, new Promise((r) => setTimeout(r, 800))]);
+        clog('qwiic: released ' + pcas.length + ' servo board' + (pcas.length === 1 ? '' : 's') + ' before disconnect', 'info');
+    };
     if (session) session.on('runstatus', () => qwUpdateRunGates());
     async function qwBumpArm() {
         const g = qwGate('read');
@@ -7106,9 +7120,6 @@ <h2 id="modalTitle">Import error</h2>
         // Optional-guarded: if the module block failed to load (stale-cache
         // gotcha), connect/bench ops must still work — defaults just don't apply.
         if (Studio.applyRigIo) { try { await Studio.applyRigIo(); } catch (_) { /* logged inside */ } }
-        // Qwiic setup scan (LAB-214): once per connection, never retried; guarded
-        // so a failure never blocks connect.
-        if (Studio.qwiicSetup) { try { await Studio.qwiicSetup(); } catch (e) { clog('qwiic: setup failed — ' + e.message, 'err'); } }
         const q = async (bytes) => { try { return await session.send(bytes, { timeoutMs: 2000 }); } catch (_) { return null; } };
         const got = [];
         const rr = Wire.decodeRefreshRate(await q(Wire.encodeGetRefreshRate()));
@@ -7124,6 +7135,11 @@ <h2 id="modalTitle">Import error</h2>
         const fi = Wire.decodeFirmwareInfo(await q(Wire.encodeGetFirmwareInfo()));
         if (fi && fi.version) { $('cFwName').textContent = 'on SD: ' + fi.version; got.push('SD fw «' + fi.version + '»'); }
         if (got.length) clog('init from controller: ' + got.join(' · '), 'info');
+        // Qwiic setup scan (LAB-214): once per connection, never retried. Started
+        // AFTER the controller reads and NOT awaited, so its sensor configure waits
+        // (~0.5 s on a full chain) never hold up the SD listing; a failure never
+        // blocks connect. Gated inside on the 0xC2 qwiic_i2c feature bit.
+        if (Studio.qwiicSetup) Studio.qwiicSetup().catch((e) => clog('qwiic: setup failed — ' + e.message, 'err'));
     }
     function downloadBlob(bytes, name, mime) {
         const blob = new Blob([bytes], { type: mime || 'application/octet-stream' });
@@ -7534,7 +7550,12 @@ <h2 id="modalTitle">Import error</h2>
             })();
         };
     }
-    const liveOk = () => !!(session && session.connected && !session.running);
+    // Live sends pause during a run, an ISP batch (a stream would re-activate the display and
+    // the firmware refuses 0xC8/0xC9 then) and a post-mortem (it owns the link).
+    const liveOk = () =>
+        !!(session && session.connected && !session.running) &&
+        !(Studio.ispBatchRunning && Studio.ispBatchRunning()) &&
+        !Studio._activePostmortem;
     Studio.liveSender = liveSender;
     // Test display: level / duty re-send the last test figure (no-op until one was sent).
     const restreamLive = liveSender(() => (liveOk() && Studio.restreamLast ? Studio.restreamLast() : null));
@@ -9092,13 +9113,12 @@ <h2 id="modalTitle">Import error</h2>
     5: [7, 4, 7, 1, 7], 6: [7, 4, 7, 5, 7], 7: [7, 1, 2, 2, 2], 8: [7, 5, 7, 5, 7], 9: [7, 5, 7, 1, 7],
     R: [6, 5, 6, 5, 5], L: [4, 4, 4, 4, 7], U: [5, 5, 5, 5, 7], D: [6, 5, 5, 5, 6]
 };
+// The rig's FULL arena grid (num_rows × num_cols; an uninstalled column is still a
+// grid column, so grid column c = physical column c) — js/studio-stream-geometry.js.
 function activeArenaGeom() {
     const cfg = Studio.currentRig && Studio.currentRig.arenaConfig;
     const arena = cfg ? arenaForConfig(cfg) : null;
-    const rc = (arena && arena.num_rows) || 2;
-    // Partial arenas stream their INSTALLED columns (a 1x12of18 figure is 12 panels wide).
-    const cc = (arena && (arena.columns_installed ? arena.columns_installed.length : arena.num_cols)) || 10;
-    return { rowCount: rc, colCount: cc, pixelRows: rc * 20, pixelCols: cc * 20 };
+    return window.StudioStreamGeometry.rigGeometry(arena);
 }
 function newGrid() { const a = activeArenaGeom(); return new Uint8Array(a.pixelRows * a.pixelCols); }
 function setPx(grid, a, row, col, val) { if (row < 0 || row >= a.pixelRows || col < 0 || col >= a.pixelCols) return; grid[row * a.pixelCols + col] = val; }
@@ -9126,11 +9146,13 @@ <h2 id="modalTitle">Import error</h2>
 function genOrient() {
     const a = activeArenaGeom(); const grid = newGrid(); const val = streamGs === 2 ? 1 : 15; const s = 2;
     const cw = 3 * s, gh = 5 * s;
-    const midCol = Math.floor(a.pixelCols / 2 - cw / 2), midRow = Math.floor(a.pixelRows / 2 - gh / 2);
+    // Glyphs sit inside the INSTALLED span (a 1×12of18 has no panels in grid columns 12–17).
+    const span = window.StudioStreamGeometry.installedSpan(a);
+    const midCol = Math.floor((span.lo + span.hi) / 2 - cw / 2), midRow = Math.floor(a.pixelRows / 2 - gh / 2);
     drawGlyph(grid, a, 'U', midCol, a.pixelRows - gh - 1, val, s);
     drawGlyph(grid, a, 'D', midCol, 1, val, s);
-    drawGlyph(grid, a, 'L', 1, midRow, val, s);
-    drawGlyph(grid, a, 'R', a.pixelCols - cw - 1, midRow, val, s);
+    drawGlyph(grid, a, 'L', span.lo + 1, midRow, val, s);
+    drawGlyph(grid, a, 'R', span.hi - cw - 1, midRow, val, s);
     return grid;
 }
 // Color banks (LAB-223/228 color panels): light ONLY bank k (0..3 = A..D = T0..T3) —
@@ -9151,31 +9173,13 @@ <h2 id="modalTitle">Import error</h2>
         for (let y = 0; y < 20; y++) for (let x = 0; x < 20; x++) setPx(grid, a, pr * 20 + y, pc * 20 + x, val);
     return grid;
 }
-// The controller accepts stream frames of exactly ITS compiled geometry (0xCB rows ×
-// cols; fw constants.h panel_count_per_frame): 2x10 on the CSHL boards, 4x12 on the
-// arena_12-18 build. The rig's figure is placed into that frame: installed columns
-// from the left, the rig's rows repeated up the frame (so a one-row bench install
-// lights whichever row connector its panels are on). Firmware without 0xCB: the
-// legacy 20-panel rule.
+// Stream frames are sized to the CONTROLLER's compiled geometry (0xCB rows × cols);
+// the mapping rules live in js/studio-stream-geometry.js (Node-tested).
 function streamTarget() {
-    const rig = activeArenaGeom();
-    const fv = Studio.firmwareVersion;
-    if (fv && fv.rows > 0 && fv.cols > 0) {
-        if (rig.rowCount > fv.rows || rig.colCount > fv.cols) {
-            return { ok: false, rig, reason: 'the rig is ' + rig.rowCount + '×' + rig.colCount + ' panels but this firmware build streams ' + fv.rows + '×' + fv.cols };
-        }
-        return { ok: true, rig, rows: fv.rows, cols: fv.cols };
-    }
-    if (rig.rowCount * rig.colCount === 20) return { ok: true, rig, rows: rig.rowCount, cols: rig.colCount };
-    return { ok: false, rig, reason: 'this firmware does not report its panel geometry (0xCB), so only 20-panel arenas can be streamed' };
+    return window.StudioStreamGeometry.streamTarget(activeArenaGeom(), Studio.firmwareVersion);
 }
 function toFirmwareGrid(grid, t) {
-    const rp = t.rig.pixelRows, cp = t.rig.pixelCols;
-    const R = t.rows * 20, C = t.cols * 20;
-    if (R === rp && C === cp) return grid;
-    const out = new Uint8Array(R * C);
-    for (let r = 0; r < R; r++) out.set(grid.subarray((r % rp) * cp, (r % rp) * cp + cp), r * C);
-    return out;
+    return window.StudioStreamGeometry.toFirmwareGrid(grid, t);
 }
 function encodeStreamPat(grid, gs, rows, cols) {
     return window.PatEncoder.encode({
@@ -9192,7 +9196,7 @@ <h2 id="modalTitle">Import error</h2>
     const len = Wire.streamFrameBytes(panels, gs);
     const payload = buf.subarray(window.PatEncoder.G6_HEADER_SIZE, window.PatEncoder.G6_HEADER_SIZE + len);
     // The thumbnail shows the RIG's figure (the preview draws the rig's arena).
-    const samePat = t.rows === t.rig.rowCount && t.cols === t.rig.colCount;
+    const samePat = !window.StudioStreamGeometry.isMapped(t);
     const patArrayBuffer = samePat ? fwPat : encodeStreamPat(grid, gs, t.rig.rowCount, t.rig.colCount);
     return { bytes: Wire.encodeStreamFrame(payload, { panels }), patArrayBuffer, target: t };
 }
@@ -9229,7 +9233,7 @@ <h2 id="modalTitle">Import error</h2>
     try {
         await Studio.session.send(built.bytes, { expectedCmd: Wire.OPCODES.STREAM_FRAME, timeoutMs: 1500 });
         const t = built.target;
-        const mapped = t.rows !== t.rig.rowCount || t.cols !== t.rig.colCount ? ' · ' + t.rig.rowCount + '×' + t.rig.colCount + ' rig in a ' + t.rows + '×' + t.cols + ' firmware frame' : '';
+        const mapped = window.StudioStreamGeometry.isMapped(t) ? ' · ' + t.rig.rowCount + '×' + t.rig.colCount + ' rig in a ' + t.rows + '×' + t.cols + ' firmware frame (rig rows repeated up the frame)' : '';
         if (!opts || !opts.quiet) clog('› STREAM_FRAME 0x32 · ' + label + ' (' + (gs === 2 ? 'GS2' : 'GS16') + ')' + mapped, 'tx');
         return true;
     } catch (e) { clog('stream send failed: ' + (e.message || e), 'err'); return false; }
@@ -9253,6 +9257,8 @@ <h2 id="modalTitle">Import error</h2>
 // Re-send the last figure (level / duty / depth changed). No-op before the first figure.
 Studio.restreamLast = async function () {
     if (!lastStreamFigure || !Studio.session || !Studio.session.connected || Studio.session.running) return false;
+    // A stream re-activates the display: never during an ISP batch (0xC8/0xC9 need it stopped) or a post-mortem.
+    if ((Studio.ispBatchRunning && Studio.ispBatchRunning()) || Studio._activePostmortem) return false;
     return Studio.doStream(lastStreamFigure.kind, lastStreamFigure.arg, { quiet: true });
 };
 
diff --git a/docs/development/arena-studio-parity.md b/docs/development/arena-studio-parity.md
index a68c742f..f0d49513 100644
--- a/docs/development/arena-studio-parity.md
+++ b/docs/development/arena-studio-parity.md
@@ -37,7 +37,7 @@ Update this list when a Studio feature intentionally skips the twins.
 | "+ add / ✕ remove" optional CONTROLLER params on command cards (Studio v0.41; first user: trialParams `duty`). The standalone designer renders/edits a `duty` present in the YAML or seeded by the shared schema default (detailKeys synced), but can't add it to or remove it from an existing command | n/a | ✗ (render/edit only) |
 | Conditional LED activation editor — the `led_activation` nested-object sub-editor on a trialParams card (level / hysteresis / on-ranges list; Studio v0.59). The runner engine + parser + schema are SHARED (flow everywhere), so a `led_activation` authored in Studio round-trips and RUNS from the standalone; it's just not editable there (kept out of the standalone's detailKeys — the scalar field renderer can't show a nested object) | n/a | ✗ (preserved on export, not editable) |
 | Runtime variables (Studio v0.84) — the Run view panel for `runtime_controls:` (bounded operator changes, explicit Apply, next-trial activation, logged provenance; `js/runtime-controls.js` + `js/studio-runtime-vars.js`) and the `requires:` capability gate that refuses to run protocols needing `flow_control`. The parser preserves both keys on round trip, so a protocol authored with them still opens/exports in the standalone — it just has no panel and no gate there | ✗ | ✗ (preserved, not shown; no run gate) |
-| Qwiic peripherals (LAB-214, Studio v0.96) — Console → Qwiic (scan, identify, one device's readout, bump check, servo go-to-position, Copy as rig YAML), the connect-time scan + top-bar chip, and rig `peripherals:`. Drivers are shared modules (`js/qwiic-drivers.js`, `js/studio-qwiic.js`) — Studio only, by policy | ✗ | n/a |
+| Qwiic peripherals (LAB-214) — Console → Qwiic (scan, identify, one device's readout, bump check, servo go-to-position, Copy as rig YAML), the connect-time scan + top-bar chip, and rig `peripherals:`. Drivers are shared modules (`js/qwiic-drivers.js`, `js/studio-qwiic.js`) — Studio only, by policy | ✗ | n/a |
 
 | Alt-study shell ports (LAB-158, ported from Arena Studio Alt into Classic): **Protocol ▾** menu (renamed from File; protocol actions only, section heads) + **⚙ Settings** menu (session rig, GitHub + storage, Run logging — browser settings, not the YAML); Edit's drawer renamed "⚙ Protocol settings"; Console **Tools** rail as an accessible checklist + a 2-column Console stage on wide screens; Run view widened to 1500 px; Scope `labels: full/clean` pill + toggle state in text/`aria-pressed`; replay re-pins the current step when the Scope is resized; visibility themes in ⚙ Settings → Display (Dark / Light / High contrast / Night / Color-blind safe / Match this computer). Guarded by `tests/test-studio-shell.js` | ✗ | ✗ |
 
diff --git a/js/studio-stream-geometry.js b/js/studio-stream-geometry.js
new file mode 100644
index 00000000..701b4b7d
--- /dev/null
+++ b/js/studio-stream-geometry.js
@@ -0,0 +1,129 @@
+/**
+ * studio-stream-geometry.js — where a Studio test figure lands in a host-streamed
+ * STREAM_FRAME (0x32), DOM-free so it is Node-testable
+ * (tests/test-studio-stream-geometry.js).
+ *
+ * The controller accepts stream frames of exactly ITS compiled panel geometry
+ * (firmware constants.h panel_count_per_frame; reported by GET_FIRMWARE_VERSION
+ * 0xCB as rows × cols): 2×10 on the CSHL boards, 4×12 on the arena_12-18 build.
+ * Test figures are drawn on the rig's FULL arena grid (num_rows × num_cols — an
+ * uninstalled column is still a grid column), and grid column c is physical
+ * column c, so:
+ *
+ *   - grid column c → firmware column c. Only the INSTALLED columns have to fit
+ *     the firmware's column count (G6_1x12of18: installed 0–11 fit a 12-column
+ *     build; grid columns 12–17 have no panels and are dropped).
+ *   - grid row r → firmware rows r, r + R, r + 2R, … (the rig's rows repeated up
+ *     the frame), so a one-row bench install lights whichever row connector its
+ *     panels are on. Only firmware rows beyond the rig's own get the repeat.
+ *   - firmware without 0xCB: the legacy rule — the rig grid itself must be 20
+ *     panels (it is sent as-is).
+ *
+ * 2×10 and 2×8of10 rigs on 2×10 firmware therefore get the identical frames they
+ * got before firmware-sized streaming (the full 2×10 grid, identity mapping).
+ *
+ * LOADING: classic <script src> (window-global `StudioStreamGeometry` + CommonJS),
+ * no ES `export` (CLAUDE.md).
+ */
+(function (global) {
+    'use strict';
+
+    const PANEL_PX = 20;
+
+    /**
+     * Rig figure geometry from an arena config's `arena` block (null → 2×10).
+     * → { rowCount, colCount, pixelRows, pixelCols, installed: [col…] }
+     */
+    function rigGeometry(arena) {
+        const rowCount = (arena && arena.num_rows) || 2;
+        const colCount = (arena && arena.num_cols) || 10;
+        const installed =
+            arena && Array.isArray(arena.columns_installed) && arena.columns_installed.length
+                ? arena.columns_installed.slice().sort((a, b) => a - b)
+                : Array.from({ length: colCount }, (_, i) => i);
+        return {
+            rowCount,
+            colCount,
+            pixelRows: rowCount * PANEL_PX,
+            pixelCols: colCount * PANEL_PX,
+            installed
+        };
+    }
+
+    /**
+     * Where the rig's figure goes. firmware = the decoded 0xCB record ({rows, cols})
+     * or null. → { ok: true, rig, rows, cols } | { ok: false, rig, reason }
+     */
+    function streamTarget(rig, firmware) {
+        const fv = firmware && firmware.rows > 0 && firmware.cols > 0 ? firmware : null;
+        if (fv) {
+            const lastInstalled = rig.installed[rig.installed.length - 1];
+            if (rig.rowCount > fv.rows || lastInstalled >= fv.cols) {
+                return {
+                    ok: false,
+                    rig,
+                    reason:
+                        'the rig is ' +
+                        rig.rowCount +
+                        '×' +
+                        rig.colCount +
+                        (rig.installed.length < rig.colCount
+                            ? ' (' + rig.installed.length + ' columns installed)'
+                            : '') +
+                        ' but this firmware build streams ' +
+                        fv.rows +
+                        '×' +
+                        fv.cols
+                };
+            }
+            return { ok: true, rig, rows: fv.rows, cols: fv.cols };
+        }
+        if (rig.rowCount * rig.colCount === 20)
+            return { ok: true, rig, rows: rig.rowCount, cols: rig.colCount };
+        return {
+            ok: false,
+            rig,
+            reason: 'this firmware does not report its panel geometry (0xCB), so only 20-panel arenas can be streamed'
+        };
+    }
+
+    /** Map a rig-grid pixel array (row-major, row 0 = bottom) into the firmware frame. */
+    function toFirmwareGrid(grid, target) {
+        const rp = target.rig.pixelRows;
+        const cp = target.rig.pixelCols;
+        const R = target.rows * PANEL_PX;
+        const C = target.cols * PANEL_PX;
+        if (R === rp && C === cp) return grid;
+        const out = new Uint8Array(R * C);
+        const w = Math.min(cp, C);
+        for (let r = 0; r < R; r++) {
+            const src = (r % rp) * cp;
+            out.set(grid.subarray(src, src + w), r * C);
+        }
+        return out;
+    }
+
+    /** True when target places the rig in a different-shaped firmware frame. */
+    const isMapped = (target) =>
+        target.rows !== target.rig.rowCount || target.cols !== target.rig.colCount;
+
+    /** Pixel-column span of the installed panels: { lo, hi } (hi exclusive). */
+    function installedSpan(rig) {
+        return {
+            lo: rig.installed[0] * PANEL_PX,
+            hi: (rig.installed[rig.installed.length - 1] + 1) * PANEL_PX
+        };
+    }
+
+    const StudioStreamGeometry = {
+        PANEL_PX,
+        rigGeometry,
+        streamTarget,
+        toFirmwareGrid,
+        isMapped,
+        installedSpan
+    };
+
+    if (typeof module !== 'undefined' && module.exports) module.exports = StudioStreamGeometry;
+    global.StudioStreamGeometry = StudioStreamGeometry;
+})(typeof window !== 'undefined' ? window : globalThis);
diff --git a/tests/test-studio-qwiic.js b/tests/test-studio-qwiic.js
index 96e94fb8..fcae6f0b 100644
--- a/tests/test-studio-qwiic.js
+++ b/tests/test-studio-qwiic.js
@@ -486,8 +486,33 @@ const item = (addr, kind, extra) =>
             )
         );
         ok(
-            'connect-time setup scan from initFromController',
-            /initFromController[\s\S]{0,900}Studio\.qwiicSetup\(\)/.test(html)
+            'connect-time setup runs AFTER the controller reads and is not awaited (never delays the SD listing)',
+            /init from controller: [\s\S]{0,700}if \(Studio\.qwiicSetup\) Studio\.qwiicSetup\(\)\.catch\(/.test(
+                html
+            ) && !/await Studio\.qwiicSetup\(\)/.test(html)
+        );
+        ok(
+            'live sends + Qwiic pause during an ISP batch and a post-mortem',
+            /const liveOk = \(\) =>[\s\S]{0,200}ispBatchRunning[\s\S]{0,80}_activePostmortem/.test(
+                html
+            ) &&
+                /paused — panel firmware batch running/.test(html) &&
+                /Studio\.restreamLast = async function \(\) \{[\s\S]{0,400}ispBatchRunning/.test(
+                    html
+                )
+        );
+        ok(
+            'servo boards released on an intentional disconnect',
+            /Studio\.qwiicReleaseServos = async function/.test(html) &&
+                /await Studio\.qwiicReleaseServos\(\);[\s\S]{0,120}Studio\.session\.disconnect\(\)/.test(
+                    html
+                )
+        );
+        ok(
+            'stream geometry delegates to js/studio-stream-geometry.js (full grid, never installed-only)',
+            html.includes('<script src="js/studio-stream-geometry.js"') &&
+                /return window\.StudioStreamGeometry\.rigGeometry\(arena\);/.test(html) &&
+                !/columns_installed\.length : arena\.num_cols/.test(html)
         );
         ok(
             'setup does not arm the bump latch (one owner: the run)',
diff --git a/tests/test-studio-stream-geometry.js b/tests/test-studio-stream-geometry.js
new file mode 100644
index 00000000..9313a9ae
--- /dev/null
+++ b/tests/test-studio-stream-geometry.js
@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+/**
+ * test-studio-stream-geometry.js — js/studio-stream-geometry.js: where a Studio
+ * test figure lands in a firmware-sized STREAM_FRAME. Regression cover for the
+ * rc4 review blocker (2×8of10 shifted one panel / refused on pre-0xCB firmware).
+ *
+ *   pixi run node tests/test-studio-stream-geometry.js
+ */
+'use strict';
+
+const SG = require('../js/studio-stream-geometry.js');
+const AC = require('../js/arena-configs.js');
+
+let failures = 0;
+let total = 0;
+function ok(name, cond, info) {
+    total++;
+    console.log(`  ${cond ? 'PASS' : 'FAIL'}  ${name}${info !== undefined ? ' — ' + info : ''}`);
+    if (!cond) failures++;
+}
+const arena = (name) => AC.getConfig(name).arena;
+// A figure that marks every grid panel with its 1-based number (pixel value = panel number).
+function numbered(rig) {
+    const g = new Uint8Array(rig.pixelRows * rig.pixelCols);
+    for (let r = 0; r < rig.pixelRows; r++)
+        for (let c = 0; c < rig.pixelCols; c++)
+            g[r * rig.pixelCols + c] = Math.floor(r / 20) * rig.colCount + Math.floor(c / 20) + 1;
+    return g;
+}
+const at = (grid, cols, pr, pc) => grid[(pr * 20 + 10) * cols * 20 + pc * 20 + 10]; // centre pixel of panel (pr, pc)
+
+console.log('\n=== rigGeometry ===');
+{
+    const g = SG.rigGeometry(arena('G6_2x8of10'));
+    ok(
+        '2×8of10 keeps the FULL 2×10 grid',
+        g.rowCount === 2 && g.colCount === 10 && g.pixelCols === 200
+    );
+    ok('2×8of10 installed = 1..8', g.installed.join(',') === '1,2,3,4,5,6,7,8');
+    ok(
+        'null arena → 2×10 default',
+        SG.rigGeometry(null).colCount === 10 && SG.rigGeometry(null).installed.length === 10
+    );
+    const b = SG.rigGeometry(arena('G6_1x12of18'));
+    ok(
+        '1×12of18 full grid 1×18, installed 0..11',
+        b.rowCount === 1 && b.colCount === 18 && b.installed[11] === 11
+    );
+    ok(
+        'installedSpan 2×8of10 = px 20..180',
+        SG.installedSpan(g).lo === 20 && SG.installedSpan(g).hi === 180
+    );
+}
+
+console.log('\n=== 2×10 and 2×8of10 behave exactly as before ===');
+for (const name of ['G6_2x10', 'G6_2x8of10']) {
+    const rig = SG.rigGeometry(arena(name));
+    const grid = numbered(rig);
+    for (const fw of [null, { rows: 2, cols: 10 }]) {
+        const t = SG.streamTarget(rig, fw);
+        ok(
+            name + ' on ' + (fw ? '2×10 firmware' : 'pre-0xCB firmware') + ': streamable as 2×10',
+            t.ok && t.rows === 2 && t.cols === 10,
+            t.reason
+        );
+        ok(
+            name + ' ' + (fw ? '0xCB' : 'pre-0xCB') + ': identity (same array, no remap)',
+            SG.toFirmwareGrid(grid, t) === grid && !SG.isMapped(t)
+        );
+    }
+}
+{
+    // The rc4 bug: 2×8of10's first panel is physical column 1, not 0.
+    const rig = SG.rigGeometry(arena('G6_2x8of10'));
+    const out = SG.toFirmwareGrid(numbered(rig), SG.streamTarget(rig, { rows: 2, cols: 10 }));
+    ok(
+        '2×8of10: grid column 1 (first installed) lands on firmware column 1',
+        at(out, 10, 0, 1) === 2 && at(out, 10, 0, 8) === 9
+    );
+}
+
+console.log('\n=== 1×12of18 bench on the 4×12 arena_12-18 build ===');
+{
+    const rig = SG.rigGeometry(arena('G6_1x12of18'));
+    const t = SG.streamTarget(rig, { rows: 4, cols: 12 });
+    ok('streamable into 4×12', t.ok && t.rows === 4 && t.cols === 12 && SG.isMapped(t), t.reason);
+    const out = SG.toFirmwareGrid(numbered(rig), t);
+    ok('frame is 80×240 px', out.length === 80 * 240);
+    ok(
+        'column c → firmware column c (0 and 11)',
+        at(out, 12, 0, 0) === 1 && at(out, 12, 0, 11) === 12
+    );
+    ok(
+        'the one rig row is repeated in all 4 firmware rows',
+        [0, 1, 2, 3].every((r) => at(out, 12, r, 5) === 6)
+    );
+    ok('pre-0xCB firmware: refused (not 20 panels)', !SG.streamTarget(rig, null).ok);
+}
+
+console.log('\n=== mismatches are refused with a reason ===');
+{
+    const rig = SG.rigGeometry(arena('G6_2x10'));
+    const t = SG.streamTarget(rig, { rows: 1, cols: 12 });
+    ok('2×10 rig on a 1-row build: refused', !t.ok && /streams 1×12/.test(t.reason), t.reason);
+    const ring = SG.rigGeometry(arena('G6_3x10of14'));
+    ok(
+        '3×10of14 on 4×12: fits (installed 0..9 < 12, 3 ≤ 4 rows)',
+        SG.streamTarget(ring, { rows: 4, cols: 12 }).ok
+    );
+    ok('3×10of14 on 2×10: refused (3 rows)', !SG.streamTarget(ring, { rows: 2, cols: 10 }).ok);
+    const wide = SG.rigGeometry({ num_rows: 1, num_cols: 18, columns_installed: [0, 13] });
+    ok(
+        'an installed column beyond the firmware columns: refused',
+        !SG.streamTarget(wide, { rows: 4, cols: 12 }).ok
+    );
+    ok(
+        '2×10 rig on 4×10 firmware: streamable (rows repeated)',
+        SG.streamTarget(rig, { rows: 4, cols: 10 }).ok
+    );
+}
+
+console.log(`\n=== Summary ===\n${total - failures} / ${total} checks passed`);
+process.exit(failures > 0 ? 1 : 0);

From a4a2a9c82968a7a3fea2bf73a0d6c0521758559e Mon Sep 17 00:00:00 2001
From: Michael B Reiser <mreiser@gmail.com>
Date: Tue, 13 Oct 2026 11:51:46 -0400
Subject: [PATCH 17/17] =?UTF-8?q?release:=202026-10-06=20rc5=20=E2=80=94?=
 =?UTF-8?q?=20Arena=20Console=20v11,=20Pattern=20Icon=20Generator=20v1.5,?=
 =?UTF-8?q?=20Pattern=20Designer=20v0.13,=20Arena=20Studio=20v0.95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Candidate for Production. PRs: #245, #246, #248, #250.

Release-Manifest: releases/2026-10-06.json
---
 arena_console.html                            |  2 +-
 arena_studio.html                             |  2 +-
 .../development/arena-studio-release-notes.md | 27 +++++++++
 .../pattern-designer-release-notes.md         | 15 +++++
 docs/development/web-tools-release-notes.md   |  9 +++
 icon_generator.html                           |  2 +-
 pattern_editor.html                           |  2 +-
 releases/2026-10-06.json                      | 60 +++++++++++++++++++
 8 files changed, 115 insertions(+), 4 deletions(-)
 create mode 100644 releases/2026-10-06.json

diff --git a/arena_console.html b/arena_console.html
index 84796dae..08599579 100644
--- a/arena_console.html
+++ b/arena_console.html
@@ -1521,7 +1521,7 @@
                 </div>
                 <div id="log"></div>
             </div>
-            <footer id="footer">Arena Console v10 | 2026-09-28 10:45 ET</footer>
+            <footer id="footer">Arena Console v11 | 2026-10-13 11:51 ET</footer>
         </div>
 
         <!-- Paste-a-frame modal -->
diff --git a/arena_studio.html b/arena_studio.html
index 146f1a5c..5e3a4a97 100644
--- a/arena_studio.html
+++ b/arena_studio.html
@@ -3419,7 +3419,7 @@ <h2 id="modalTitle">Import error</h2>
 </div>
 
 <footer id="footer">
-  <span class="foot-left">Arena Studio v0.94 | 2026-09-30 07:22 ET · <a href="https://github.com/reiserlab/webDisplayTools" target="_blank" rel="noopener" title="webDisplayTools on GitHub: source, issues, and release notes (docs/development/arena-studio-release-notes.md)">GitHub</a></span>
+  <span class="foot-left">Arena Studio v0.95 | 2026-10-13 11:51 ET · <a href="https://github.com/reiserlab/webDisplayTools" target="_blank" rel="noopener" title="webDisplayTools on GitHub: source, issues, and release notes (docs/development/arena-studio-release-notes.md)">GitHub</a></span>
   <!-- Course-repo quick-links: open protocols / logs / patterns in a new tab.
        Hrefs built from the configured repo + bench id (updateGhQuickLinks). -->
   <span id="ghQuickLinks" title="Open the course repo on GitHub (new tab)">
diff --git a/docs/development/arena-studio-release-notes.md b/docs/development/arena-studio-release-notes.md
index e337b4fc..62e88c46 100644
--- a/docs/development/arena-studio-release-notes.md
+++ b/docs/development/arena-studio-release-notes.md
@@ -4,6 +4,33 @@ The Studio's footer used to carry the full changelog inline; it now shows one li
 history lives here. Newest first. (Per-session engineering detail stays in
 `arena-studio-handover.md` and the design docs — this file is the user-facing what-changed list.)
 
+## v0.95 (2026-10-13) · ISP time estimate ~5 s/panel, not ~20 s (#244) · Pattern Designer + Studio: partial-arena °/px and 3D/2D mapping, unmirrored icons, short SD-safe filenames, upload name checks (LAB-295) · First command after Connect no longer waits ~60 s behind the thumbnail download (LAB-298) · Console → Qwiic peripherals, rig peripherals:, live Console sliders, firmware-sized test display + color banks (LAB-214)
+
+<!-- #245 -->
+- The panel firmware **Program set** dialog now estimates the time correctly (about 2 minutes for a full 20-panel arena, not 8).
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+<!-- #246 -->
+- **A pattern name the arena can't store is refused before the upload starts,** with the reason, instead of failing after the file has been sent. Names with spaces or parentheses still upload.
+- **The upload warns when the arena would reject a pattern:** the session rig is a partial arena, or the pattern's panel grid doesn't match the rig.
+- **Re-uploading a pattern that's already on the card is flagged.** The arena keeps both copies (the new one as `X001_…`); the Studio now shows them as duplicates instead of quietly playing the old one.
+- **Pattern thumbnails are no longer mirrored.** The gap behind the fly is now at the bottom, as in the 3D view. This is the same fix as in the Pattern Designer and also covers the Console's thumbnails.
+- **The run-log replay's 3D view maps G6 2×8of10 patterns to the right columns.** This is the same fix as the Pattern Designer's 3D view.
+
+<!-- #248 -->
+- **Commands respond right after Connect.** The first command after connecting no longer waits up to a minute behind the pattern picker's thumbnail download; background reads at connect now step aside for anything you send.
+- **Pattern downloads from the SD card arrive complete.** Studio opens the arena's serial port with a larger read buffer, so downloads no longer come up short or drop the connection, and a download that stalls gives up after 5 s instead of 60 s.
+- **Thumbnails for patterns that are only on the SD card.** Studio downloads one for a thumbnail only if it is 1 MB or smaller; while a pattern is displaying, the tooltip explains that the controller can't send files until you stop it.
+
+<!-- #250 -->
+- **Console → Qwiic: find and try the sensors on the arena's Qwiic / STEMMA QT connector.** Scan lists every device on the bus with its category (Temp / humidity, Accel / tilt / bump, Light, Servo / PWM) and checks it against the rig file. Click one to see its readings in real units, once or live. The motion sensor has a bump check and the servo board a position slider. This panel is for testing; nothing in it is written to run logs.
+- **Rig files can list their Qwiic peripherals (`peripherals:`).** On connect the Studio scans once and shows a Qwiic chip in the top bar: green when every listed device is there, red when one is missing, amber when something is plugged in that the rig file doesn't list. **Copy as rig YAML** gives you the lines to add. Controllers without a Qwiic connector are unaffected.
+- **Console sliders act as you move them.** Test display level and duty re-send the last test figure, and LED power sets the LED, while you drag (never during a run).
+- **Test display works on more arenas.** Figures are sent at the controller's own frame size, so the 1×12 bench arena can show full-field, panel map, orientation and checker.
+- **Test display → color: light one LED bank at a time (A–D).** For color panels: each button lights only that bank, one LED in four per panel, at the chosen level.
+- **Two new rigs in ⚙ Settings:** the arena_12-18 bench (one panel high, its six Qwiic boards listed) and the 10-of-14 ring (three panels high).
+
 ## v0.94 (2026-09-30) · LAB-158 ports (Protocol ▾, ⚙ Settings, two-column Console) + visibility themes · Multi-color G6 panels V1 — Panel LEDs layout, ON color, per-bank preview (LAB-228) · Flasher + Studio picker: one production build from the published catalog; legacy images hashed, never default (panel-fw-v1.3.1)
 
 <!-- #238 -->
diff --git a/docs/development/pattern-designer-release-notes.md b/docs/development/pattern-designer-release-notes.md
index 0de1f155..5b780173 100644
--- a/docs/development/pattern-designer-release-notes.md
+++ b/docs/development/pattern-designer-release-notes.md
@@ -3,6 +3,21 @@
 Newest first. Each entry is one Production release (see `releases/` for the exact
 candidate manifest: main commit + the PRs and their head SHAs).
 
+## v0.13 (2026-10-13) · ISP time estimate ~5 s/panel, not ~20 s (#244) · Pattern Designer + Studio: partial-arena °/px and 3D/2D mapping, unmirrored icons, short SD-safe filenames, upload name checks (LAB-295) · First command after Connect no longer waits ~60 s behind the thumbnail download (LAB-298) · Console → Qwiic peripherals, rig peripherals:, live Console sliders, firmware-sized test display + color banks (LAB-214)
+
+<!-- #246 -->
+- **Degrees and pixels now convert correctly on partial arenas.** On arenas with missing columns (G4 3×12of18, G6 3×12of18, G6 2×8of10), the px↔° labels, a spatial period typed in pixels, and a step size typed in degrees used the installed width instead of the full circle. For example, 24 px on the G4 3×12of18 arena made a 45° grating instead of 30°. Regenerate any such patterns made with a pixel period or a degree step.
+- **The 3D view shows each panel of a G6 2×8of10 pattern on the right column.** Before, it showed the whole pattern one panel to the side.
+- **Animate → Frame Shifting's hint shows the real span on partial arenas** (e.g. "240° = 192 px", not "360°").
+- **The 2D view has an azimuth scale.** Degrees from straight ahead (0°) appear under the grid, negative to the fly's left, in the same coordinates as the Mollweide view.
+- **2D panel numbers name the physical panels on partial arenas.** On G6 2×8of10 the first pattern panel now reads 2/12, the same as the 3D view.
+- **Pattern thumbnails are no longer mirrored.** They now match the 3D top-down view: the gap behind the fly is at the bottom and the columns run clockwise.
+- **Saving a pattern for a partial G6 arena shows a one-time heads-up.** The arena's current firmware can't play partial-arena patterns yet.
+- **Generated names say which colors they use, and stay short.** For example `grat_rot_20px_50pct_4c-B-G.pat` means ON blue, OFF green on four-color panels, so color variants no longer overwrite each other. Saved and renamed names are kept within what the arena's SD card can store (plain letters/digits/`_-.`, ≤ 58 characters), and the rename prompt says when it adjusted a name.
+
+<!-- #250 -->
+- **Two new arenas: G6 1×12 of 18 and G6 3×10 of 14.** Both show their installed panels centered at the front.
+
 ## v0.12 (2026-09-30) · LAB-158 ports (Protocol ▾, ⚙ Settings, two-column Console) + visibility themes · Multi-color G6 panels V1 — Panel LEDs layout, ON color, per-bank preview (LAB-228) · Flasher + Studio picker: one production build from the published catalog; legacy images hashed, never default (panel-fw-v1.3.1)
 
 <!-- #238 -->
diff --git a/docs/development/web-tools-release-notes.md b/docs/development/web-tools-release-notes.md
index 63b72d32..54c28318 100644
--- a/docs/development/web-tools-release-notes.md
+++ b/docs/development/web-tools-release-notes.md
@@ -3,6 +3,15 @@
 Newest first. Each entry is one Production release (see `releases/` for the exact
 candidate manifest: main commit + the PRs and their head SHAs).
 
+## Pattern Icon Generator v1.5 (2026-10-13) · ISP time estimate ~5 s/panel, not ~20 s (#244) · Pattern Designer + Studio: partial-arena °/px and 3D/2D mapping, unmirrored icons, short SD-safe filenames, upload name checks (LAB-295) · First command after Connect no longer waits ~60 s behind the thumbnail download (LAB-298) · Console → Qwiic peripherals, rig peripherals:, live Console sliders, firmware-sized test display + color banks (LAB-214)
+
+- Maintenance release (no user-visible notes).
+
+## Arena Console v11 (2026-10-13) · ISP time estimate ~5 s/panel, not ~20 s (#244) · Pattern Designer + Studio: partial-arena °/px and 3D/2D mapping, unmirrored icons, short SD-safe filenames, upload name checks (LAB-295) · First command after Connect no longer waits ~60 s behind the thumbnail download (LAB-298) · Console → Qwiic peripherals, rig peripherals:, live Console sliders, firmware-sized test display + color banks (LAB-214)
+
+<!-- #248 -->
+- **Pattern downloads from the SD card arrive complete.** The same larger serial read buffer and 5 s stall limit as in Studio.
+
 ## G6 Panel Flash Programmer v0.4 (2026-09-30) · LAB-158 ports (Protocol ▾, ⚙ Settings, two-column Console) + visibility themes · Multi-color G6 panels V1 — Panel LEDs layout, ON color, per-bank preview (LAB-228) · Flasher + Studio picker: one production build from the published catalog; legacy images hashed, never default (panel-fw-v1.3.1)
 
 <!-- #242 -->
diff --git a/icon_generator.html b/icon_generator.html
index fe7413a8..873a11d3 100644
--- a/icon_generator.html
+++ b/icon_generator.html
@@ -469,7 +469,7 @@ <h1>Pattern Icon Generator</h1>
         </div>
 
         <footer>
-            <p>Pattern Icon Generator v1.4 | 2026-02-04 08:19 ET</p>
+            <p>Pattern Icon Generator v1.5 | 2026-10-13 11:51 ET</p>
             <p><a href="index.html">← Back to Tools</a></p>
         </footer>
     </div>
diff --git a/pattern_editor.html b/pattern_editor.html
index e8d7579b..934cba83 100644
--- a/pattern_editor.html
+++ b/pattern_editor.html
@@ -2497,7 +2497,7 @@ <h2>No Pattern Loaded</h2>
         </div>
     </div>
 
-    <footer class="pd-footer">Pattern Designer v0.12 | 2026-09-30 07:22 ET · <a href="https://github.com/reiserlab/webDisplayTools" target="_blank" rel="noopener" title="webDisplayTools on GitHub — source, issues, and release notes (docs/development/)">GitHub</a></footer>
+    <footer class="pd-footer">Pattern Designer v0.13 | 2026-10-13 11:51 ET · <a href="https://github.com/reiserlab/webDisplayTools" target="_blank" rel="noopener" title="webDisplayTools on GitHub — source, issues, and release notes (docs/development/)">GitHub</a></footer>
 
     <!-- Hidden file input -->
     <input type="file" id="fileInput" accept=".pat" style="display: none;">
diff --git a/releases/2026-10-06.json b/releases/2026-10-06.json
new file mode 100644
index 00000000..48d95824
--- /dev/null
+++ b/releases/2026-10-06.json
@@ -0,0 +1,60 @@
+{
+  "schema": 1,
+  "name": "2026-10-06",
+  "kind": "candidate",
+  "rc": 5,
+  "created_at": "2026-10-13T15:51:46Z",
+  "created_at_et": "2026-10-13 11:51 ET",
+  "main_sha": "7c68dfcee8706f2028775a5f3decf8cbf5f06540",
+  "headline": "",
+  "prs": [
+    {
+      "number": 245,
+      "title": "fix(studio): ISP time estimate ~5 s/panel, not ~20 s (#244)",
+      "head_sha": "5b0b30dcce3927f9ea2f39918a313a055acde142",
+      "head_ref": "fix/244-isp-estimate",
+      "url": "https://github.com/reiserlab/webDisplayTools/pull/245"
+    },
+    {
+      "number": 246,
+      "title": "Pattern Designer + Studio: partial-arena \u00b0/px and 3D/2D mapping, unmirrored icons, short SD-safe filenames, upload name checks (LAB-295)",
+      "head_sha": "84daa996a134e35566a4e903a01c2a8ad6381836",
+      "head_ref": "claude/keen-bassi-5bc125",
+      "url": "https://github.com/reiserlab/webDisplayTools/pull/246"
+    },
+    {
+      "number": 248,
+      "title": "Studio: first command after Connect no longer waits ~60 s behind the thumbnail download (LAB-298)",
+      "head_sha": "546d9c625678ab48858f2c6eba8da44450b2f997",
+      "head_ref": "claude/studio-connect-latency",
+      "url": "https://github.com/reiserlab/webDisplayTools/pull/248"
+    },
+    {
+      "number": 250,
+      "title": "Studio: Console \u2192 Qwiic peripherals, rig peripherals:, live Console sliders, firmware-sized test display + color banks (LAB-214)",
+      "head_sha": "6bbd8d1b36218fe726bbd2f0dd6b42ea54b2792e",
+      "head_ref": "claude/qwiic-peripherals-lab-214",
+      "url": "https://github.com/reiserlab/webDisplayTools/pull/250"
+    }
+  ],
+  "versions": {
+    "console": {
+      "from": "v10",
+      "to": "v11"
+    },
+    "icon-generator": {
+      "from": "v1.4",
+      "to": "v1.5"
+    },
+    "pattern-designer": {
+      "from": "v0.12",
+      "to": "v0.13"
+    },
+    "studio": {
+      "from": "v0.94",
+      "to": "v0.95"
+    }
+  },
+  "hotfix_reason": null,
+  "bridge_changed": false
+}