de-shell 0.2.0__tar.gz → 0.3.0__tar.gz

{de_shell-0.2.0 → de_shell-0.3.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: de-shell
-Version: 0.2.0
+Version: 0.3.0
 Summary: The Electron + Python desktop-app shell Direct Electron's apps (SpyDE, Ground Crew, Autopilot) are assembled from
 Author-email: Carter Francis <cartsfrancis@gmail.com>
 License: MIT
-Project-URL: Homepage, https://github.com/CSSFrancis/de-shell
-Project-URL: Repository, https://github.com/CSSFrancis/de-shell
-Project-URL: Issues, https://github.com/CSSFrancis/de-shell/issues
-Project-URL: Changelog, https://github.com/CSSFrancis/de-shell/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://github.com/directelectron/de-shell
+Project-URL: Repository, https://github.com/directelectron/de-shell
+Project-URL: Issues, https://github.com/directelectron/de-shell/issues
+Project-URL: Changelog, https://github.com/directelectron/de-shell/blob/main/CHANGELOG.rst
 Keywords: electron,desktop,anyplotlib,electron-microscopy,direct-electron
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
@@ -26,7 +26,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy>=1.20.0
-Requires-Dist: anyplotlib>=0.7.3
+Requires-Dist: anyplotlib>=0.10.0
 Requires-Dist: pyyaml
 Provides-Extra: tests
 Requires-Dist: pytest>=3.6; extra == "tests"
@@ -36,7 +36,7 @@ Dynamic: license-file
 # DE Shell
 
 [![PyPI](https://img.shields.io/pypi/v/de-shell.svg)](https://pypi.org/project/de-shell/)
-[![CI](https://github.com/CSSFrancis/de-shell/actions/workflows/ci.yml/badge.svg)](https://github.com/CSSFrancis/de-shell/actions/workflows/ci.yml)
+[![CI](https://github.com/directelectron/de-shell/actions/workflows/ci.yml/badge.svg)](https://github.com/directelectron/de-shell/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 The substrate Direct Electron's desktop apps are assembled from: **SpyDE**
@@ -122,8 +122,10 @@ peer dependencies — react, electron, electron-updater, @playwright/test —
 are the app's to declare; every app already does. The e2e specs take the
 harness from `shell/testing/harness.cjs`.
 
-Autopilot and SpyDE (on its `chore/de-shell-split` branch) are wired this
-way; Ground Crew still carries a copy under its `packages/` and is next.
+All three apps are wired this way: Autopilot, SpyDE
+([directelectron/spyde#152](https://github.com/directelectron/spyde/pull/152))
+and Ground Crew ([directelectron/de_ground_crew#183](https://github.com/directelectron/de_ground_crew/pull/183)),
+pinned to the `0.2` line.
 
 ## Developing it
 
@@ -148,8 +150,20 @@ tests, and builds the wheel and checks what it carries.
 
 The version is written once, in `de_shell/__init__.py`. To release:
 
-1. Bump `__version__`, move the `CHANGELOG.md` entries under the new version.
-2. Commit, tag `vX.Y.Z`, push the tag.
+1. Run **Prepare Release** from the Actions tab and pick the bump (`minor`,
+   `bugfix`, `major`, `pre-release`, or `finalize` to drop a `bN` suffix). It
+   bumps `__version__`, assembles `CHANGELOG.rst` from the news fragments in
+   `upcoming_changes/`, runs the pre-flight checks, and opens a release PR that
+   names the one tag that will pass.
+2. Review and merge that PR, then tag the merge commit and push the tag — the
+   PR body has the exact commands.
+
+The tag has to match `__version__` exactly; going through the workflow makes
+them agree by construction, because the PR *is* the bump. To assemble the
+changelog by hand instead, `uv tool run towncrier build --version X.Y.Z` does
+the same thing — but stage `upcoming_changes/` with `git add -A`, because
+towncrier deletes the fragments it consumed and a plain `git add CHANGELOG.rst`
+leaves the deletions behind for the next release to re-publish.
 
 `.github/workflows/publish.yml` builds the distributions, refuses a tag that
 does not match `__version__`, and uploads to PyPI through trusted publishing
@@ -175,9 +189,9 @@ SpyDE commit the app copies were taken from:
   panes on large stills), JSON emit that never writes bare `NaN`, the harness
   hardening, and the unit tests for all of it.
 
-Not yet included: Ground Crew's `dev/instrument-actions` shell deltas
-(`stdoutDemux`, `sizeReporter`, the `frameBytes` transport) — they ride a
-branch that has not merged.
+* Ground Crew `main` @ 0382549 (0.2.1): the chunk-list stdout demuxer, the
+  size reporter and StrictMode-safe registration in `FigureFrame`, the figure
+  document's scroll pin, and the anyplotlib 0.8.0 floor.
 
 ## Rules
 
@@ -189,6 +203,9 @@ branch that has not merged.
 * **The protocol is the contract.** `PLOTAPP:` JSON lines and `PLOTBIN:`
   binary frames over the sidecar's stdio. Both halves of it live in this one
   package on purpose; keep it that way.
+* **Every pull request carries its own changelog entry**, as a news fragment
+  under [`upcoming_changes/`](upcoming_changes/README.rst) — one file per PR,
+  so two of them never conflict over the same lines of `CHANGELOG.rst`.
 * **LF line endings**, enforced by `.gitattributes`.
 
 ## License

{de_shell-0.2.0 → de_shell-0.3.0}/README.md

@@ -1,7 +1,7 @@
 # DE Shell
 
 [![PyPI](https://img.shields.io/pypi/v/de-shell.svg)](https://pypi.org/project/de-shell/)
-[![CI](https://github.com/CSSFrancis/de-shell/actions/workflows/ci.yml/badge.svg)](https://github.com/CSSFrancis/de-shell/actions/workflows/ci.yml)
+[![CI](https://github.com/directelectron/de-shell/actions/workflows/ci.yml/badge.svg)](https://github.com/directelectron/de-shell/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 The substrate Direct Electron's desktop apps are assembled from: **SpyDE**
@@ -87,8 +87,10 @@ peer dependencies — react, electron, electron-updater, @playwright/test —
 are the app's to declare; every app already does. The e2e specs take the
 harness from `shell/testing/harness.cjs`.
 
-Autopilot and SpyDE (on its `chore/de-shell-split` branch) are wired this
-way; Ground Crew still carries a copy under its `packages/` and is next.
+All three apps are wired this way: Autopilot, SpyDE
+([directelectron/spyde#152](https://github.com/directelectron/spyde/pull/152))
+and Ground Crew ([directelectron/de_ground_crew#183](https://github.com/directelectron/de_ground_crew/pull/183)),
+pinned to the `0.2` line.
 
 ## Developing it
 
@@ -113,8 +115,20 @@ tests, and builds the wheel and checks what it carries.
 
 The version is written once, in `de_shell/__init__.py`. To release:
 
-1. Bump `__version__`, move the `CHANGELOG.md` entries under the new version.
-2. Commit, tag `vX.Y.Z`, push the tag.
+1. Run **Prepare Release** from the Actions tab and pick the bump (`minor`,
+   `bugfix`, `major`, `pre-release`, or `finalize` to drop a `bN` suffix). It
+   bumps `__version__`, assembles `CHANGELOG.rst` from the news fragments in
+   `upcoming_changes/`, runs the pre-flight checks, and opens a release PR that
+   names the one tag that will pass.
+2. Review and merge that PR, then tag the merge commit and push the tag — the
+   PR body has the exact commands.
+
+The tag has to match `__version__` exactly; going through the workflow makes
+them agree by construction, because the PR *is* the bump. To assemble the
+changelog by hand instead, `uv tool run towncrier build --version X.Y.Z` does
+the same thing — but stage `upcoming_changes/` with `git add -A`, because
+towncrier deletes the fragments it consumed and a plain `git add CHANGELOG.rst`
+leaves the deletions behind for the next release to re-publish.
 
 `.github/workflows/publish.yml` builds the distributions, refuses a tag that
 does not match `__version__`, and uploads to PyPI through trusted publishing
@@ -140,9 +154,9 @@ SpyDE commit the app copies were taken from:
   panes on large stills), JSON emit that never writes bare `NaN`, the harness
   hardening, and the unit tests for all of it.
 
-Not yet included: Ground Crew's `dev/instrument-actions` shell deltas
-(`stdoutDemux`, `sizeReporter`, the `frameBytes` transport) — they ride a
-branch that has not merged.
+* Ground Crew `main` @ 0382549 (0.2.1): the chunk-list stdout demuxer, the
+  size reporter and StrictMode-safe registration in `FigureFrame`, the figure
+  document's scroll pin, and the anyplotlib 0.8.0 floor.
 
 ## Rules
 
@@ -154,6 +168,9 @@ branch that has not merged.
 * **The protocol is the contract.** `PLOTAPP:` JSON lines and `PLOTBIN:`
   binary frames over the sidecar's stdio. Both halves of it live in this one
   package on purpose; keep it that way.
+* **Every pull request carries its own changelog entry**, as a news fragment
+  under [`upcoming_changes/`](upcoming_changes/README.rst) — one file per PR,
+  so two of them never conflict over the same lines of `CHANGELOG.rst`.
 * **LF line endings**, enforced by `.gitattributes`.
 
 ## License

{de_shell-0.2.0 → de_shell-0.3.0}/de_shell/__init__.py

@@ -20,6 +20,6 @@ from __future__ import annotations
 
 #: The package version — the one place it is written. pyproject.toml reads it
 #: (dynamic version) and the release workflow refuses a tag that disagrees.
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 __all__ = ["ipc", "log_stream", "process_guard", "debug_flags", "compute"]

{de_shell-0.2.0 → de_shell-0.3.0}/de_shell/js/main/backendProcess.ts

@@ -9,6 +9,7 @@ import process from 'process'
 // Extension spelled out so node:test can load this module without a bundler
 // (native type-stripping resolves relative imports literally).
 import { shellConfig } from './config.ts'
+import { createStdoutDemux } from './stdoutDemux.ts'
 
 export interface BackendHandlers {
   onMessage: (msg: Record<string, unknown>) => void
@@ -19,9 +20,6 @@ export interface BackendHandlers {
   onBinary?: (header: Record<string, unknown>, payload: Buffer) => void
 }
 
-const PLOTBIN = Buffer.from('PLOTBIN:')
-const NL = 0x0a
-
 let proc: ChildProcess | null = null
 let tickTimer: ReturnType<typeof setInterval> | null = null
 
@@ -95,60 +93,20 @@ export function startBackend(
     if (!proc && tickTimer) { clearInterval(tickTimer); tickTimer = null }
   }, 2000)
 
-  // Custom stdout demuxer: the stream interleaves text lines (PLOTAPP: JSON and
-  // plain log output, both '\n'-terminated) with raw PLOTBIN binary frames
-  // (PLOTBIN:<hlen>:<plen>\n<header_json><payload>). readline can't carry binary,
-  // so we parse the raw Buffer stream ourselves, accumulating partial reads.
-  let acc: Buffer = Buffer.alloc(0)
-  child.stdout!.on('data', (chunk: Buffer) => {
-    acc = acc.length ? Buffer.concat([acc, chunk]) : chunk
-    // Process as many complete units as are buffered; stop when we need more.
-    for (;;) {
-      if (acc.length === 0) break
-      // A binary frame if the buffer starts with the PLOTBIN marker.
-      if (acc.length >= PLOTBIN.length &&
-          acc.subarray(0, PLOTBIN.length).equals(PLOTBIN)) {
-        const nl = acc.indexOf(NL)
-        if (nl < 0) break                       // prefix line incomplete
-        const prefix = acc.subarray(PLOTBIN.length, nl).toString('ascii')
-        const [hlenS, plenS] = prefix.split(':')
-        const hlen = parseInt(hlenS, 10), plen = parseInt(plenS, 10)
-        if (!(hlen >= 0) || !(plen >= 0)) {     // malformed → drop the line
-          handlers.onStream(`[sidecar protocol] malformed PLOTBIN prefix: ${prefix}\n`, 'stderr')
-          acc = acc.subarray(nl + 1); continue
-        }
-        const bodyStart = nl + 1
-        const end = bodyStart + hlen + plen
-        if (acc.length < end) break             // body not fully arrived yet
-        let header: Record<string, unknown> = {}
-        try {
-          header = JSON.parse(acc.subarray(bodyStart, bodyStart + hlen).toString('utf8'))
-        } catch { /* malformed header — still consume the frame */ }
-        // Copy the payload out so it survives `acc` being sliced/reused.
-        const payload = Buffer.from(acc.subarray(bodyStart + hlen, end))
-        acc = acc.subarray(end)
-        try { handlers.onBinary?.(header, payload) } catch { /* ignore */ }
-        continue
-      }
-      // Otherwise a text line up to the next '\n'.
-      const nl = acc.indexOf(NL)
-      if (nl < 0) break                         // line incomplete
-      const line = acc.subarray(0, nl).toString('utf8')
-      acc = acc.subarray(nl + 1)
-      if (line.startsWith('PLOTAPP:')) {
-        try {
-          handlers.onMessage(JSON.parse(line.slice(8)) as Record<string, unknown>)
-        } catch {
-          // Say so rather than swallow it: a truncated frame is how a backend
-          // bug presents, and silence turns it into "the UI just stopped".
-          handlers.onStream(`[sidecar protocol] malformed JSON message: ${line.slice(0, 200)}\n`, 'stderr')
-        }
-      } else if (line.trim()) {
-        rememberOutput(line)
-        handlers.onStream(line + '\n', 'stdout')
-      }
-    }
+  // Custom stdout demuxer (stdoutDemux.ts): the stream interleaves text lines
+  // (PLOTAPP: JSON and plain log output, both '\n'-terminated) with raw PLOTBIN
+  // binary frames (PLOTBIN:<hlen>:<plen>\n<header_json><payload>). readline
+  // can't carry binary, so the raw Buffer stream is parsed with a chunk-list
+  // accumulator — each byte is copied exactly once, into the emitted unit
+  // (the old whole-prefix Buffer.concat per chunk was O(N²/chunkSize) while a
+  // large frame streamed in: 11.9 s per 64 MB frame at 64 KiB chunks). Plain
+  // output is remembered for a problem report on the way past; the demuxer
+  // itself says so on a malformed message rather than swallowing it.
+  const demux = createStdoutDemux({
+    ...handlers,
+    onStream: (text, kind) => { rememberOutput(text); handlers.onStream(text, kind) },
   })
+  child.stdout!.on('data', (chunk: Buffer) => demux.push(chunk))
 
   child.stderr!.on('data', (d: Buffer) => {
     rememberOutput(d.toString())

{de_shell-0.2.0 → de_shell-0.3.0}/de_shell/js/main/pythonEnv.test.ts

@@ -10,9 +10,9 @@
  * Run: `node --test src/pythonEnv.test.ts` (from packages/shell-main/), or via
  * the `test:unit` npm script.
  */
-import { test } from 'node:test'
+import { test, after } from 'node:test'
 import assert from 'node:assert/strict'
-import { mkdtempSync, writeFileSync, mkdirSync } from 'fs'
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from 'fs'
 import { join } from 'path'
 import { tmpdir } from 'os'
 import { configureShell } from './config.ts'
@@ -24,17 +24,29 @@ configureShell({
   pythonModule: 'testapp',
 })
 
+/** Every temp directory these tests make, removed when the file is done. */
+const tempDirs: string[] = []
+after(() => {
+  for (const dir of tempDirs) rmSync(dir, { recursive: true, force: true })
+})
+
+function tempDir(prefix: string): string {
+  const dir = mkdtempSync(join(tmpdir(), prefix))
+  tempDirs.push(dir)
+  return dir
+}
+
 /** A directory containing a uv stub under both spellings, so these tests do not
  *  fork on the host platform. */
 function dirWithUv(): string {
-  const dir = mkdtempSync(join(tmpdir(), 'uv-stub-'))
+  const dir = tempDir('uv-stub-')
   writeFileSync(join(dir, 'uv'), '')
   writeFileSync(join(dir, 'uv.exe'), '')
   return dir
 }
 
 function emptyDir(): string {
-  return mkdtempSync(join(tmpdir(), 'uv-none-'))
+  return tempDir('uv-none-')
 }
 
 /** An env whose PATH and every fallback root point somewhere we control. */

de_shell-0.3.0/de_shell/js/main/stdoutDemux.test.ts

@@ -0,0 +1,195 @@
+/**
+ * stdoutDemux.test.ts — node:test unit tests for the backend stdout demuxer.
+ *
+ * The stream interleaves '\n'-terminated text lines (PLOTAPP: JSON + plain
+ * log output) with raw PLOTBIN binary frames
+ * (PLOTBIN:<hlen>:<plen>\n<header_json><payload>). The demuxer must produce
+ * the SAME event trace regardless of how the OS slices the stream into
+ * 'data' chunks — Windows delivers a single large child-stdout write as
+ * uniform 64 KiB chunks (measured 2026-08-15), and chunk boundaries can land
+ * mid-marker, mid-prefix, mid-header or mid-payload.
+ *
+ * Also pins the accumulator's cost shape: a 16 MB frame arriving as 64 KiB
+ * chunks must demux in linear time. The pre-fix Buffer.concat accumulator
+ * recopied the whole prefix per chunk — O(N²/chunk): measured 813 ms at
+ * 16 MB, 11.9 s at 64 MB (notes/runs/2026-08-15-perf-review-measurements.md
+ * §1) — so the 250 ms budget is ~3× under the old cost and ~38× over the
+ * chunk-list cost (6.6 ms measured); generous against CI timer noise on
+ * both sides.
+ *
+ * Run: `node --test src/stdoutDemux.test.ts` (from packages/shell-main/),
+ * or via the `test:unit` npm script.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { createStdoutDemux } from './stdoutDemux.ts'
+
+type Event =
+  | { kind: 'message'; msg: Record<string, unknown> }
+  | { kind: 'stream'; text: string }
+  | { kind: 'binary'; header: Record<string, unknown>; payload: string }
+
+function collector() {
+  const events: Event[] = []
+  const demux = createStdoutDemux({
+    onMessage: (msg) => events.push({ kind: 'message', msg }),
+    onStream: (text) => events.push({ kind: 'stream', text }),
+    onBinary: (header, payload) =>
+      events.push({ kind: 'binary', header, payload: payload.toString('hex') }),
+  })
+  return { events, demux }
+}
+
+function frame(header: Record<string, unknown>, payload: Buffer): Buffer {
+  const h = Buffer.from(JSON.stringify(header), 'utf8')
+  return Buffer.concat([
+    Buffer.from(`PLOTBIN:${h.length}:${payload.length}\n`, 'ascii'),
+    h,
+    payload,
+  ])
+}
+
+/** Feed `stream` in slices of `sizes` (cycled); return the event trace. */
+function run(stream: Buffer, sizes: number[]): Event[] {
+  const { events, demux } = collector()
+  let pos = 0
+  let i = 0
+  while (pos < stream.length) {
+    const n = Math.min(sizes[i % sizes.length], stream.length - pos)
+    demux.push(stream.subarray(pos, pos + n))
+    pos += n
+    i++
+  }
+  return events
+}
+
+function patternPayload(n: number): Buffer {
+  const p = Buffer.allocUnsafe(n)
+  for (let i = 0; i < n; i++) p[i] = i & 0xff // includes 0x0a bytes
+  return p
+}
+
+// A representative interleaved stream: log line, PLOTAPP message, a binary
+// frame whose payload contains newline bytes and marker-lookalike bytes,
+// another log line, a second frame back-to-back with a third, final message.
+function interleavedStream(): Buffer {
+  const nasty = Buffer.concat([
+    Buffer.from('\nPLOTBIN:9:9\nPLOTAPP:{}\n', 'ascii'), // lookalikes INSIDE payload
+    patternPayload(3000),
+  ])
+  return Buffer.concat([
+    Buffer.from('starting up\n', 'utf8'),
+    Buffer.from('PLOTAPP:{"type":"state_update","key":"clim"}\n', 'utf8'),
+    frame({ fig_id: 'f1', key: 'image' }, nasty),
+    Buffer.from('mid-run log\n', 'utf8'),
+    frame({ fig_id: 'f2', key: 'image' }, patternPayload(1)),
+    frame({ fig_id: 'f3', key: 'spec' }, Buffer.alloc(0)),
+    Buffer.from('PLOTAPP:{"type":"done"}\n', 'utf8'),
+  ])
+}
+
+test('one whole-stream chunk parses every unit in order', () => {
+  const events = run(interleavedStream(), [1 << 30])
+  assert.deepEqual(events.map((e) => e.kind),
+    ['stream', 'message', 'binary', 'stream', 'binary', 'binary', 'message'])
+  const b1 = events[2] as Extract<Event, { kind: 'binary' }>
+  assert.deepEqual(b1.header, { fig_id: 'f1', key: 'image' })
+  const b3 = events[5] as Extract<Event, { kind: 'binary' }>
+  assert.equal(b3.payload, '')
+  assert.deepEqual((events[6] as Extract<Event, { kind: 'message' }>).msg,
+    { type: 'done' })
+})
+
+test('the event trace is chunking-invariant (64 KiB, tiny, 1-byte, ragged)', () => {
+  const stream = interleavedStream()
+  const reference = run(stream, [1 << 30])
+  for (const sizes of [[65536], [7], [1], [3, 1, 40, 2, 1000, 1]]) {
+    assert.deepEqual(run(stream, sizes), reference,
+      `trace diverged for chunk sizes ${JSON.stringify(sizes)}`)
+  }
+})
+
+test('splits inside the marker, prefix, header and payload all reassemble', () => {
+  const f = frame({ fig_id: 'x' }, patternPayload(64))
+  const reference = run(f, [1 << 30])
+  // Split at every single boundary position of the frame — brute force
+  // covers mid-marker, mid-prefix, mid-header and mid-payload by exhaustion.
+  for (let cut = 1; cut < f.length; cut++) {
+    const { events, demux } = collector()
+    demux.push(f.subarray(0, cut))
+    demux.push(f.subarray(cut))
+    assert.deepEqual(events, reference, `split at byte ${cut} diverged`)
+  }
+})
+
+test('a malformed PLOTBIN prefix line is dropped and parsing resumes', () => {
+  const stream = Buffer.concat([
+    Buffer.from('PLOTBIN:not:numbers\n', 'ascii'),
+    Buffer.from('PLOTAPP:{"type":"after"}\n', 'utf8'),
+  ])
+  for (const sizes of [[1 << 30], [1]]) {
+    const events = run(stream, sizes)
+    assert.deepEqual(events, [
+      { kind: 'message', msg: { type: 'after' } },
+    ])
+  }
+})
+
+test('a malformed header still consumes the frame and delivers the payload', () => {
+  const h = Buffer.from('{broken', 'utf8')
+  const payload = patternPayload(32)
+  const stream = Buffer.concat([
+    Buffer.from(`PLOTBIN:${h.length}:${payload.length}\n`, 'ascii'),
+    h, payload,
+    Buffer.from('PLOTAPP:{"type":"after"}\n', 'utf8'),
+  ])
+  const events = run(stream, [5])
+  assert.deepEqual(events, [
+    { kind: 'binary', header: {}, payload: payload.toString('hex') },
+    { kind: 'message', msg: { type: 'after' } },
+  ])
+})
+
+test('malformed PLOTAPP JSON is reported, not swallowed; blank lines emit nothing', () => {
+  // A truncated frame is how a backend bug presents, and silence turns it
+  // into "the UI just stopped" — so the line is dropped AND said so, on
+  // stderr, and the parse carries on to the next unit.
+  const stream = Buffer.from('PLOTAPP:{nope\n\n   \nreal log\n', 'utf8')
+  const events = run(stream, [2])
+  assert.equal(events.length, 2)
+  assert.match((events[0] as { text?: string }).text ?? '',
+               /^\[sidecar protocol\] malformed JSON message: PLOTAPP:\{nope/)
+  assert.deepEqual(events[1], { kind: 'stream', text: 'real log\n' })
+})
+
+test('a handler that throws does not stop the parse', () => {
+  const seen: string[] = []
+  const demux = createStdoutDemux({
+    onMessage: (m) => { seen.push(`m:${(m as { type?: string }).type}`) },
+    onStream: () => { throw new Error('boom') },
+    onBinary: () => { throw new Error('boom') },
+  })
+  demux.push(Buffer.concat([
+    Buffer.from('log line\n', 'utf8'),
+    frame({ fig_id: 'f' }, patternPayload(8)),
+    Buffer.from('PLOTAPP:{"type":"after"}\n', 'utf8'),
+  ]))
+  assert.deepEqual(seen, ['m:after'])
+})
+
+test('PERF PIN: a 16 MB frame in 64 KiB chunks demuxes in linear time', () => {
+  const payload = Buffer.allocUnsafe(16 * 1024 * 1024).fill(7)
+  const stream = frame({ fig_id: 'big', key: 'image' }, payload)
+  const { events, demux } = collector()
+  const t0 = process.hrtime.bigint()
+  for (let pos = 0; pos < stream.length; pos += 65536) {
+    demux.push(stream.subarray(pos, Math.min(pos + 65536, stream.length)))
+  }
+  const ms = Number(process.hrtime.bigint() - t0) / 1e6
+  assert.equal(events.length, 1)
+  assert.equal((events[0] as Extract<Event, { kind: 'binary' }>).payload.length,
+    payload.length * 2) // hex doubles
+  assert.ok(ms < 250,
+    `16 MB frame took ${ms.toFixed(0)} ms — the quadratic Buffer.concat ` +
+    `accumulator signature (measured 813 ms pre-fix, 6.6 ms chunk-list)`)
+})