mixdog 0.9.172 → 0.9.174

package/scripts/lib/test-failure-records.mjs

@@ -0,0 +1,46 @@
+// Structured failure records for the run-level failure summary.
+//
+// Node keeps ownership of diagnostics, totals and exit status; this only
+// records "which test failed, in which file" as one JSON line each, so the
+// runner can name every failure after all other output even when the run log
+// was filtered (scripts/lib/run-node-tests.mjs).
+//
+// It rides the existing summary reporter instead of adding a third node:test
+// reporter: a third reporter pushes the shared TestsStream past its listener
+// cap and every run would start with a MaxListenersExceededWarning.
+import { appendFileSync } from 'node:fs';
+import { relative } from 'node:path';
+
+export const FAILURE_RECORDS_ENV = 'MIXDOG_TEST_FAILURE_RECORDS';
+
+// Ancestor names are tracked per file: node:test runs files concurrently, so
+// one flat stack would mix their nestings.
+export function failureRecord(event, stacks) {
+  const file = event.data?.file ? relative(process.cwd(), String(event.data.file)).replaceAll('\\', '/') : '';
+  if (event.type === 'test:start') {
+    const stack = stacks.get(file) ?? [];
+    stack.length = event.data.nesting;
+    stack[event.data.nesting] = event.data.name;
+    stacks.set(file, stack);
+    return null;
+  }
+  if (event.type !== 'test:fail') return null;
+  // A failing todo does not fail the run, and a suite reports its children's
+  // failures as its own; only the leaves that decide the exit status belong
+  // in the summary.
+  if (event.data.todo) return null;
+  if (event.data.details?.error?.failureType === 'subtestsFailed') return null;
+  const ancestors = (stacks.get(file) ?? []).slice(0, event.data.nesting);
+  return { file, name: [...ancestors, event.data.name].join(' > ') };
+}
+
+// The runner sets FAILURE_RECORDS_ENV to a per-spawn JSONL path. Without it
+// nothing is recorded, so a direct `node --test` run is unaffected.
+export function createFailureRecorder(path = process.env[FAILURE_RECORDS_ENV]) {
+  if (!path) return () => {};
+  const stacks = new Map();
+  return (event) => {
+    const record = failureRecord(event, stacks);
+    if (record) appendFileSync(path, `${JSON.stringify(record)}\n`);
+  };
+}

package/scripts/lib/test-failure-summary.mjs

@@ -0,0 +1,59 @@
+// Run-level failure classification and the final summary block.
+//
+// A filtered run log loses a failure: `ℹ fail 1` says a test failed but never
+// which one. Every line here carries SUMMARY_TAG and names its file and test,
+// so the block survives `grep`/`Select-String` filtering, and the runner
+// prints it after all other output (scripts/lib/run-node-tests.mjs).
+export const SUMMARY_TAG = '[failure-summary]';
+
+const keyOf = (record) => `${record.file}\u0000${record.name}`;
+const byLocation = (a, b) => (a.file === b.file ? a.name.localeCompare(b.name) : a.file.localeCompare(b.file));
+
+// A test that failed and then passed inside the re-run budget is flaky; one
+// that fails every attempt stays failed. A failure that only appears during a
+// re-run joins the failed set from the attempt that produced it, so a re-run
+// can never hide a test it just broke.
+//
+// attempts: [{ files: [rerun file paths], failures: [{ file, name }] }]
+export function classifyRerunOutcomes(initialFailures, attempts = []) {
+  const pending = new Map(initialFailures.map((record) => [keyOf(record), { ...record }]));
+  const flaky = new Map();
+  for (const [index, attempt] of attempts.entries()) {
+    const attemptNumber = index + 1;
+    const rerunFiles = new Set(attempt.files);
+    const stillFailing = new Set(attempt.failures.map(keyOf));
+    for (const [key, record] of [...pending]) {
+      if (!rerunFiles.has(record.file) || stillFailing.has(key)) continue;
+      pending.delete(key);
+      flaky.set(key, { ...record, passedOnAttempt: attemptNumber });
+    }
+    for (const record of attempt.failures) {
+      const key = keyOf(record);
+      if (pending.has(key) || flaky.has(key)) continue;
+      pending.set(key, { ...record, firstSeenOnRerun: attemptNumber });
+    }
+  }
+  return { failed: [...pending.values()].sort(byLocation), flaky: [...flaky.values()].sort(byLocation) };
+}
+
+// Exit-code policy, stated wherever the classification is shown.
+export function policyLine(rerunFailed) {
+  return rerunFailed > 0
+    ? `policy: --rerun-failed ${rerunFailed} is set, so a flaky test does not fail the run; a test that fails every re-run still exits 1`
+    : 'policy: --rerun-failed is off, so every failure fails the run (pass --rerun-failed <n> to classify flaky)';
+}
+
+export function formatFailureSummary({ failed = [], flaky = [], rerunFailed = 0 }) {
+  const lines = [`${SUMMARY_TAG} ${failed.length} failed, ${flaky.length} flaky (every failed test is named below)`];
+  for (const record of failed) {
+    const origin = record.firstSeenOnRerun ? ` (first seen on re-run ${record.firstSeenOnRerun})` : '';
+    lines.push(`${SUMMARY_TAG} FAILED ${record.file} > ${record.name}${origin}`);
+  }
+  for (const record of flaky) {
+    lines.push(
+      `${SUMMARY_TAG} FLAKY ${record.file} > ${record.name} (failed, then passed on re-run ${record.passedOnAttempt}/${rerunFailed})`
+    );
+  }
+  if (failed.length > 0 || flaky.length > 0) lines.push(`${SUMMARY_TAG} ${policyLine(rerunFailed)}`);
+  return `${lines.join('\n')}\n`;
+}

package/scripts/lib/test-summary-reporter.mjs

@@ -1,14 +1,18 @@
 import { Readable } from 'node:stream';
 import { spec } from 'node:test/reporters';
+import { createFailureRecorder } from './test-failure-records.mjs';
 import timingReporter from './test-timing-reporter.mjs';
 
 // Filter structured success events, never arbitrary stdout/stderr text.
 // Node's own reporter still owns failure diagnostics, warnings and totals.
-// The runner writes an unfiltered spec report alongside this summary.
+// The runner writes an unfiltered spec report alongside this summary, and
+// every failure is also recorded for the run's final failure summary.
 export default async function* summaryReporter(source) {
   const timings = [];
+  const recordFailure = createFailureRecorder();
   async function* events() {
     for await (const event of source) {
+      recordFailure(event);
       if ((event.type === 'test:pass' || event.type === 'test:fail') && event.data.nesting === 0) {
         timings.push({
           type: event.type,
@@ -17,8 +21,8 @@ export default async function* summaryReporter(source) {
       }
       // A start without its matching pass leaves a pending name in spec's
       // parent stack. Suppress both; fail events carry their own location.
-      if (event.type !== 'test:start' &&
-          (event.type !== 'test:pass' || event.data.skip || event.data.todo)) yield event;
+      if (event.type !== 'test:start' && (event.type !== 'test:pass' || event.data.skip || event.data.todo))
+        yield event;
     }
   }
   yield* Readable.from(events()).pipe(new spec());

package/scripts/lib/trace-stats.mjs

@@ -0,0 +1,38 @@
+// Latency statistics shared by the scripts/ CLIs and benches. Nearest-rank
+// percentiles: p50 of an even-sized sample is the lower middle sample, never
+// an interpolated value, so a reported number is always one the run actually
+// produced. An empty sample reports null rather than a zero that would read
+// as a real measurement.
+
+// `p` is a percent (0-100); `sorted` must already be ascending.
+export function percentile(sorted, p) {
+  if (sorted.length === 0) return null;
+  const index = Math.min(sorted.length - 1, Math.max(0, Math.ceil((p / 100) * sorted.length) - 1));
+  return sorted[index];
+}
+
+// The nearest-rank p50 of an ascending sample.
+export function median(sorted) {
+  return percentile(sorted, 50);
+}
+
+// The finite number samples in ascending order, as a new array; anything
+// else (NaN, Infinity, null, strings) is dropped, never coerced.
+export function sortedFinite(values) {
+  return values.filter((n) => Number.isFinite(n)).sort((a, b) => a - b);
+}
+
+export function stats(nums) {
+  const arr = sortedFinite(nums);
+  if (arr.length === 0) return null;
+  const sum = arr.reduce((a, b) => a + b, 0);
+  return {
+    n: arr.length,
+    sum,
+    avg: Math.round(sum / arr.length),
+    p50: percentile(arr, 50),
+    p90: percentile(arr, 90),
+    p99: percentile(arr, 99),
+    max: arr[arr.length - 1],
+  };
+}

package/scripts/lib/trace-stats.test.mjs

@@ -0,0 +1,56 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { median, percentile, sortedFinite, stats } from './trace-stats.mjs';
+
+test('percentile picks the nearest rank of an ascending sample', () => {
+  const sorted = [10, 20, 30, 40];
+  assert.equal(percentile(sorted, 50), 20);
+  assert.equal(percentile(sorted, 90), 40);
+  assert.equal(percentile(sorted, 99), 40);
+  assert.equal(percentile([5], 50), 5);
+  assert.equal(percentile([], 50), null);
+  // Rank 0 and below clamp to the first sample, never to undefined.
+  assert.equal(percentile(sorted, 0), 10);
+});
+
+test('median is the nearest-rank p50: the lower middle sample, null when empty', () => {
+  assert.equal(median([10, 20, 30, 40]), 20);
+  assert.equal(median([10, 20, 30]), 20);
+  assert.equal(median([7]), 7);
+  assert.equal(median([]), null);
+});
+
+test('percentile is nearest-rank, not floor(n*p) index truncation', () => {
+  // floor(n*p) indexing reports 20 for p50 of [10,20] and 20 for p95 of 1..20.
+  assert.equal(percentile([10, 20], 50), 10);
+  assert.equal(
+    percentile(
+      Array.from({ length: 20 }, (_, i) => i + 1),
+      95
+    ),
+    19
+  );
+});
+
+test('sortedFinite sorts a copy and drops non-finite entries without coercing them', () => {
+  const input = [3, null, '2', Number.NaN, 1, undefined, Number.NEGATIVE_INFINITY];
+  assert.deepEqual(sortedFinite(input), [1, 3]);
+  assert.equal(input[0], 3);
+});
+
+test('stats summarizes finite samples and reports null for an empty set', () => {
+  assert.deepEqual(stats([30, 10, 20]), { n: 3, sum: 60, avg: 20, p50: 20, p90: 30, p99: 30, max: 30 });
+  assert.equal(stats([]), null);
+  assert.equal(stats([Number.NaN, Number.POSITIVE_INFINITY]), null);
+});
+
+test('stats drops non-finite samples and leaves the caller array untouched', () => {
+  const input = [3, Number.NaN, 1, Number.POSITIVE_INFINITY, 2];
+  assert.deepEqual(stats(input), { n: 3, sum: 6, avg: 2, p50: 2, p90: 3, p99: 3, max: 3 });
+  assert.deepEqual(input, [3, Number.NaN, 1, Number.POSITIVE_INFINITY, 2]);
+});
+
+test('stats rounds the average, matching the reported millisecond columns', () => {
+  assert.equal(stats([1, 2]).avg, 2);
+  assert.equal(stats([1, 1, 2]).avg, 1);
+});

package/scripts/llm-trace-summary.mjs

@@ -3,19 +3,8 @@ import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { resolve } from 'node:path';
 import { parseSince } from './lib/parse-since.mjs';
-
-function argValue(name, fallback = null) {
-  const idx = process.argv.indexOf(name);
-  if (idx >= 0 && idx + 1 < process.argv.length) return process.argv[idx + 1];
-  const pref = `${name}=`;
-  const hit = process.argv.find((arg) => arg.startsWith(pref));
-  return hit ? hit.slice(pref.length) : fallback;
-}
-
-function intArg(name, fallback) {
-  const n = Number.parseInt(argValue(name, String(fallback)), 10);
-  return Number.isFinite(n) && n > 0 ? n : fallback;
-}
+import { argValue, intArg } from './lib/cli-args.mjs';
+import { stats } from './lib/trace-stats.mjs';
 
 const pathArg = argValue('--path', null);
 const dataDir = argValue('--data-dir', null);
@@ -94,27 +83,6 @@ function values(rows, name) {
   return rows.map((row) => numberField(row, name)).filter((n) => n != null);
 }
 
-function percentile(sorted, p) {
-  if (sorted.length === 0) return null;
-  const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil((p / 100) * sorted.length) - 1));
-  return sorted[idx];
-}
-
-function stats(nums) {
-  const arr = nums.filter((n) => Number.isFinite(n)).sort((a, b) => a - b);
-  if (arr.length === 0) return null;
-  const sum = arr.reduce((a, b) => a + b, 0);
-  return {
-    n: arr.length,
-    sum,
-    avg: Math.round(sum / arr.length),
-    p50: percentile(arr, 50),
-    p90: percentile(arr, 90),
-    p99: percentile(arr, 99),
-    max: arr[arr.length - 1],
-  };
-}
-
 function formatStats(s) {
   if (!s) return 'n=0';
   return `n=${s.n} avg=${s.avg}ms p50=${s.p50}ms p90=${s.p90}ms p99=${s.p99}ms max=${s.max}ms`;

package/scripts/mouse-probe.mjs

@@ -29,10 +29,8 @@ process.on('SIGINT', cleanup);
 process.stdin.on('data', (buf) => {
   const s = buf.toString('utf8');
   if (s === 'q' || s === '\x03') return cleanup();
-  let m;
-  MOUSE.lastIndex = 0;
   let sawMouse = false;
-  while ((m = MOUSE.exec(s)) !== null) {
+  for (const m of s.matchAll(MOUSE)) {
     sawMouse = true;
     const b = Number(m[1]);
     const mods = [b & 4 ? 'shift' : '', b & 8 ? 'alt' : '', b & 16 ? 'ctrl' : ''].filter(Boolean).join('+') || 'none';

package/scripts/native-tool-download.mjs

@@ -32,6 +32,11 @@ export const NATIVE_TOOL_PLATFORM_KEYS = Object.freeze([
   'win32-x64',
 ]);
 
+/** Platforms a native tool release may add beyond the required set. A host
+ *  whose manifest lacks one runs the asset platformKeyCandidates falls back to
+ *  (Windows on ARM runs win32-x64 under emulation). */
+export const OPTIONAL_NATIVE_TOOL_PLATFORM_KEYS = Object.freeze(['win32-arm64']);
+
 /** Released asset name. */
 export function nativeToolAssetName(kind, target) {
   const suffix = target.platform === 'win32' ? '.exe' : '';

package/scripts/office/author-deck.mjs

@@ -6,18 +6,12 @@ import { readFile, writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { executeOfficeTool } from '../../src/runtime/office/index.mjs';
 import { isAdvisoryOfficeIssue } from '../../src/runtime/office/quality/quality-pipeline.mjs';
+import { argValue, hasFlag, positionalArgs } from '../lib/cli-args.mjs';
 
 const value = (result) => JSON.parse(result.content[0].text);
-const argv = process.argv.slice(2);
-const flag = (name) => {
-  const at = argv.indexOf(name);
-  return at >= 0 ? argv[at + 1] : null;
-};
-const positional = argv.filter(
-  (arg, index) =>
-    !arg.startsWith('--') && !(index > 0 && argv[index - 1].startsWith('--') && !['--render'].includes(argv[index - 1]))
-);
-const [scriptPath, deckPath] = positional;
+// Flags that take no value; every other bare `--flag` consumes the next entry.
+const BOOLEAN_FLAGS = new Set(['--render']);
+const [scriptPath, deckPath] = positionalArgs(process.argv.slice(2), BOOLEAN_FLAGS);
 if (!scriptPath || !deckPath) {
   console.error(
     'usage: node scripts/office/author-deck.mjs <script.js> <deck.pptx> [--mode portable|auto] [--render] [--critique critique.json] [--out result.json]'
@@ -26,7 +20,7 @@ if (!scriptPath || !deckPath) {
 }
 const cwd = resolve('.');
 const script = await readFile(scriptPath, 'utf8');
-const mode = flag('--mode') || 'portable';
+const mode = argValue('--mode') || 'portable';
 const authored = value(
   await executeOfficeTool({ action: 'author', path: deckPath, script, mode, overwrite: true, render: false }, { cwd })
 );
@@ -52,7 +46,7 @@ const result = {
   authored: { kit: authored.kit, nativeGradients: authored.nativeGradients || 0, bytes: authored.bytes },
   issues,
 };
-if (argv.includes('--render') || flag('--critique')) {
+if (hasFlag('--render') || argValue('--critique')) {
   const rendered = value(await executeOfficeTool({ action: 'render', session }, { cwd }));
   result.render = {
     output: rendered.output,
@@ -67,7 +61,7 @@ if (argv.includes('--render') || flag('--critique')) {
   if (rendered.contactSheet?.path) console.log(`  contact sheet: ${rendered.contactSheet.path}`);
   if (rendered.receipt?.deck?.rhythm) console.log(`  rhythm: ${JSON.stringify(rendered.receipt.deck.rhythm)}`);
 }
-const critiquePath = flag('--critique');
+const critiquePath = argValue('--critique');
 if (critiquePath) {
   const critique = JSON.parse(await readFile(critiquePath, 'utf8'));
   const finalized = value(
@@ -86,7 +80,7 @@ if (critiquePath) {
 } else {
   await executeOfficeTool({ action: 'close', session, save: false }, { cwd }).catch(() => {});
 }
-const out = flag('--out');
+const out = argValue('--out');
 if (out) await writeFile(out, JSON.stringify(result, null, 2));
 let exitCode = 0;
 if (critiquePath && !result.finalize?.ok) exitCode = 3;

package/scripts/office/build-pptx-icons.mjs

@@ -135,7 +135,6 @@ export const ICON_NAMES = [
   'circle-dollar-sign',
   'dollar-sign',
   'euro',
-  'landmark',
   // technology and product
   'cpu',
   'microchip',

package/scripts/patch-replay.mjs

@@ -11,17 +11,7 @@ import { homedir, tmpdir } from 'node:os';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { executePatchTool } from '../src/runtime/agent/orchestrator/tools/patch.mjs';
-
-function argValue(name, fallback = null) {
-  const idx = process.argv.indexOf(name);
-  if (idx >= 0 && idx + 1 < process.argv.length) return process.argv[idx + 1];
-  const pref = `${name}=`;
-  const hit = process.argv.find((a) => a.startsWith(pref));
-  return hit ? hit.slice(pref.length) : fallback;
-}
-function hasFlag(name) {
-  return process.argv.includes(name);
-}
+import { argValue, hasFlag } from './lib/cli-args.mjs';
 
 function replayDir() {
   if (process.env.MIXDOG_PATCH_REPLAY_DIR) return resolve(process.env.MIXDOG_PATCH_REPLAY_DIR);

package/scripts/perf/transcript-runtime-probe.mjs

@@ -16,6 +16,7 @@ import {
 import { readTopLevelLifecycleRecord } from '../../src/runtime/agent/orchestrator/session/lifecycle-scan.mjs';
 import { createCanonicalSessionReader } from '../../src/runtime/agent/orchestrator/session/store/canonical-reader.mjs';
 import { yieldToRenderer } from '../../src/tui/session/render-timing.mjs';
+import { median, sortedFinite } from '../lib/trace-stats.mjs';
 
 const directory = mkdtempSync(join(tmpdir(), 'mixdog-transcript-perf-'));
 const messages = Array.from({ length: 1000 }, (_, i) => ({
@@ -28,7 +29,6 @@ writeFileSync(target, raw);
 const currentReader = createCanonicalSessionReader();
 const oldReader = () => readTopLevelLifecycleRecord(readFileSync(target, 'utf8'));
 const currentFloors = (value) => Math.max(denseTokenFloor(value), structuredTokenFloor(value));
-const median = (values) => [...values].sort((a, b) => a - b)[Math.floor(values.length / 2)];
 const timed = async (name, action, repetitions = 5) => {
   const samples = [];
   for (let i = 0; i < repetitions; i++) {
@@ -37,11 +37,23 @@ const timed = async (name, action, repetitions = 5) => {
     await action();
     samples.push(performance.now() - start);
   }
-  return { name, medianMs: +median(samples).toFixed(3), samplesMs: samples.map((n) => +n.toFixed(3)) };
+  return { name, medianMs: +median(sortedFinite(samples)).toFixed(3), samplesMs: samples.map((n) => +n.toFixed(3)) };
 };
 const results = [];
-results.push(await timed('token-floors-before', () => messages.forEach((m) => legacyTokenFloors(m.content))));
-results.push(await timed('token-floors-after', () => messages.forEach((m) => currentFloors(m.content))));
+results.push(
+  await timed('token-floors-before', () => {
+    messages.forEach((m) => {
+      legacyTokenFloors(m.content);
+    });
+  })
+);
+results.push(
+  await timed('token-floors-after', () => {
+    messages.forEach((m) => {
+      currentFloors(m.content);
+    });
+  })
+);
 results.push(await timed('full-token-meter-after', () => estimateMessagesTokens(messages)));
 results.push(await timed('context-summary-cold-after', () => summarizeContextMessages(structuredClone(messages))));
 summarizeContextMessages(messages);
@@ -57,14 +69,18 @@ for (const [name, action] of [
   [
     'shared-loop-before',
     () => {
-      messages.forEach((m) => legacyTokenFloors(m.content));
+      messages.forEach((m) => {
+        legacyTokenFloors(m.content);
+      });
       oldReader();
     },
   ],
   [
     'shared-loop-after',
     () => {
-      messages.forEach((m) => currentFloors(m.content));
+      messages.forEach((m) => {
+        currentFloors(m.content);
+      });
       currentReader(target, true);
     },
   ],

package/scripts/pg-memory-diet.mjs

@@ -5,6 +5,7 @@ import { join, resolve } from 'node:path';
 import { spawn } from 'node:child_process';
 import { createServer } from 'node:net';
 import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
 import pg from 'pg';
 import { searchRelevantHybrid } from '../src/runtime/memory/lib/memory-recall-store.mjs';
 
@@ -250,10 +251,7 @@ async function prepare(dataDir, runtimeDir, sourcePort) {
   }
 }
 
-if (
-  process.argv[1] &&
-  resolve(process.argv[1]) === resolve(new URL(import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, '$1'))
-) {
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
   if (process.argv[2] !== 'prepare' || !process.argv[3] || !process.argv[4]) {
     throw new Error('Usage: node scripts/pg-memory-diet.mjs prepare <data-dir> <runtime-dir> <source-port>');
   }

package/scripts/pptx-kit-index.mjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+// Builds the pptx skill's helper index (references/kit-index.md) from the code the runtime runs before every deck
+// script: kit.md, charts.md, and pictures.md. The model reads the index — each helper's signature and the guidance
+// written above it — instead of every helper's body; the bodies stay where they are, and run.
+//   node scripts/pptx-kit-index.mjs          rewrite the index
+//   node scripts/pptx-kit-index.mjs --check  exit 1 when the index is stale
+import { readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { parse } from 'acorn';
+
+const REFERENCES = resolve(dirname(fileURLToPath(import.meta.url)), '../src/defaults/skills/pptx/references');
+export const KIT_INDEX_PATH = join(REFERENCES, 'kit-index.md');
+// Which prose of a source travels with its helpers: kit.md and charts.md are read only through the index, so their
+// rules come along whole; pictures.md is still read on its own trigger, so only its headings mark where helpers sit.
+const SOURCES = [
+  { file: 'kit.md', prose: 'all' },
+  { file: 'charts.md', prose: 'all' },
+  { file: 'pictures.md', prose: 'headings' },
+];
+// A statement this short says its whole meaning (a constant, a one-line arrow); a longer one gives its first line.
+const WHOLE_STATEMENT = 240;
+
+const propertyName = (property) =>
+  property.type === 'Property' ? String(property.key.name ?? property.key.value ?? '') : property.type === 'SpreadElement' ? '…' : '';
+
+// The keys an object literal offers a script, one level into object-valued keys ("body: { x, y, w, h }"). A table of
+// like entries (STYLES: an id per style, each with the same fields) reads as its ids and the fields each carries.
+function objectShape(node) {
+  const properties = node.properties.filter((property) => propertyName(property));
+  const nested = properties.filter((property) => property.value?.type === 'ObjectExpression');
+  if (properties.length >= 4 && nested.length === properties.length) {
+    const fields = [...new Set(nested.flatMap((property) => property.value.properties.map(propertyName)))].filter(Boolean);
+    return `{ ${properties.map(propertyName).join(', ')} } each { ${fields.join(', ')} }`;
+  }
+  const keys = properties.map((property) =>
+    property.value?.type === 'ObjectExpression'
+      ? `${propertyName(property)}: { ${property.value.properties.map(propertyName).filter(Boolean).join(', ')} }`
+      : propertyName(property)
+  );
+  return `{ ${keys.join(', ')} }`;
+}
+
+// What a function hands back when it returns an object literal (zones() → Z, typeScale() → TYPE): the body is
+// elided, and without its shape the script had to open the file to learn Z.foot.takeaway or TYPE.poster.
+function returnedShape(fn) {
+  const shapes = [];
+  const visit = (node) => {
+    if (!node || typeof node.type !== 'string') return;
+    if (node !== fn.body && /Function/.test(node.type)) return;
+    if (node.type === 'ReturnStatement' && node.argument?.type === 'ObjectExpression') shapes.push(objectShape(node.argument));
+    for (const value of Object.values(node)) {
+      if (Array.isArray(value)) value.forEach(visit);
+      else if (value && typeof value === 'object' && typeof value.type === 'string') visit(value);
+    }
+  };
+  visit(fn.body);
+  return shapes.length ? ` // returns ${shapes[shapes.length - 1]}` : '';
+}
+
+function declarationSummary(source, node) {
+  const text = source.slice(node.start, node.end);
+  if (node.type === 'FunctionDeclaration' || node.type === 'ClassDeclaration') {
+    const shape = node.type === 'FunctionDeclaration' ? returnedShape(node) : '';
+    return `${source.slice(node.start, node.body.start).trimEnd()} { … }${shape}`;
+  }
+  if (text.length <= WHOLE_STATEMENT) return text;
+  if (node.type === 'VariableDeclaration') {
+    return node.declarations
+      .map((declarator) => {
+        const init = declarator.init;
+        const head = `${node.kind} ${source.slice(declarator.id.start, declarator.id.end)}`;
+        if (init && (init.type === 'ArrowFunctionExpression' || init.type === 'FunctionExpression')) {
+          return `${head} = ${source.slice(init.start, init.body.start).trimEnd()} …;`;
+        }
+        if (init?.type === 'ObjectExpression') return `${head} = ${objectShape(init)};`;
+        return `${head} = ${source.slice(init?.start ?? declarator.end, declarator.end).split('\n')[0]} …;`;
+      })
+      .join('\n');
+  }
+  return `${text.split('\n')[0]} …`;
+}
+
+function summarizeCode(code) {
+  const comments = [];
+  const program = parse(code, {
+    ecmaVersion: 'latest',
+    sourceType: 'script',
+    allowAwaitOutsideFunction: true,
+    allowReturnOutsideFunction: true,
+    onComment: comments,
+  });
+  const lines = [];
+  let cursor = 0;
+  const pushComments = (until) => {
+    for (const comment of comments) {
+      if (comment.start < cursor || comment.end > until) continue;
+      lines.push(code.slice(comment.start, comment.end));
+    }
+  };
+  for (const node of program.body) {
+    pushComments(node.start);
+    lines.push(declarationSummary(code, node));
+    cursor = node.end;
+  }
+  pushComments(code.length);
+  return lines.join('\n');
+}
+
+function summarizeFile({ file, prose }) {
+  const text = readFileSync(join(REFERENCES, file), 'utf8');
+  const parts = text.split(/^```[^\n]*\n?/m);
+  const output = [];
+  parts.forEach((part, index) => {
+    if (index % 2) {
+      output.push('```js', summarizeCode(part).trimEnd(), '```');
+      return;
+    }
+    const kept = prose === 'all' ? part.trim() : part.split('\n').filter((line) => /^#{1,3} /.test(line)).join('\n');
+    if (kept) output.push(kept.replace(/^# /m, '## '));
+  });
+  return [`# ${file}`, ...output].join('\n\n');
+}
+
+export function buildKitIndex() {
+  return [
+    '# Kit index',
+    '',
+    'Generated from `kit.md`, `charts.md`, and `pictures.md` by `scripts/pptx-kit-index.mjs`; do not edit it by hand.',
+    'The runtime runs every code block of those three files before the script. Here each helper keeps its signature,',
+    'its defaults, and the guidance written above it; a body reads as `{ … }`. Open the helper in its own file only to',
+    'redefine it or when a default this index does not state decides the page.',
+    '',
+    ...SOURCES.map((source) => summarizeFile(source)),
+    '',
+  ].join('\n');
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const next = buildKitIndex();
+  if (process.argv.includes('--check')) {
+    const current = (() => {
+      try {
+        return readFileSync(KIT_INDEX_PATH, 'utf8');
+      } catch {
+        return '';
+      }
+    })();
+    if (current !== next) {
+      console.error('references/kit-index.md is stale: run node scripts/pptx-kit-index.mjs');
+      process.exit(1);
+    }
+  } else {
+    writeFileSync(KIT_INDEX_PATH, next);
+    console.log(`wrote ${KIT_INDEX_PATH} (${next.length} chars)`);
+  }
+}

package/scripts/prepare-native-assets.mjs

@@ -4,6 +4,7 @@ import { chmod, copyFile, mkdir, mkdtemp, rename, rm } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { platformKeyCandidates } from '../src/runtime/shared/native-asset.mjs';
 import { NATIVE_TOOL_FILENAMES, packageNativeToolsDir } from '../src/runtime/shared/native-tool-paths.mjs';
 import { ensureGraphBinary } from '../src/runtime/agent/orchestrator/tools/graph-binary-fetcher.mjs';
 import { ensurePatchBinary } from '../src/runtime/agent/orchestrator/tools/patch-binary-fetcher.mjs';
@@ -31,13 +32,10 @@ export async function prepareRequiredNativeAssets({
   arch = process.arch,
 } = {}) {
   const platformKey = nativeAssetPlatformKey(platform, arch);
-  if (!NATIVE_ASSET_PLATFORMS.includes(platformKey)) {
-    const guidance =
-      platformKey === 'win32-arm64'
-        ? ' Windows ARM64 Node.js is not supported; use x64 Node.js under Windows x64 emulation.'
-        : '';
+  // Windows on ARM runs the x64 assets under its built-in emulation.
+  if (!platformKeyCandidates(platform, arch).some((key) => NATIVE_ASSET_PLATFORMS.includes(key))) {
     throw new Error(
-      `native assets are not published for ${platformKey}; supported: ${NATIVE_ASSET_PLATFORMS.join(', ')}.${guidance}`
+      `native assets are not published for ${platformKey}; supported: ${NATIVE_ASSET_PLATFORMS.join(', ')}.`
     );
   }
   const root = resolve(String(packageRoot || ''));