@0xbuff/throughline 0.0.0-stage → 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+Notable changes to Throughline are recorded here. Package versions follow
+Semantic Versioning independently of the version-1 trace and program schemas.
+
+## [0.0.2] — 2026-11-08
+
+### Changed
+
+- Updated the npm package homepage to the Throughline documentation site.
+- Refined installation, styling, security and maintenance documentation.
+- Replaced first-release-specific staging logic with reusable, version-checked
+  signed-tag and provenance publishing.
+- Removed obsolete public-release planning records and excluded source-only
+  development documentation from the npm tarball.
+
+## [0.0.1] — 2026-11-08
+
+Initial public release:
+
+- Deterministic, bounded Markdown-authored state-trace compiler.
+- Version-1 `Program` and `Trace` with diagnostics and deterministic seeking.
+- Flow, bindings, binary, matrix and callstack domains.
+- Optional React 19 player with keyboard playback, captions, state inspector,
+  responsive layouts, reduced-motion support and opt-in sound.
+- Four explicit typed ESM/CSS exports, Apache-2.0 license and 0xBUFF attribution.

package/COPYRIGHT.md

@@ -0,0 +1,8 @@
+# Copyright and license
+
+Copyright 2026 0xBUFF.
+
+Throughline is licensed under the Apache License, Version 2.0.
+See [LICENSE](LICENSE) for the full terms.
+
+Third-party dependencies retain their respective licenses and notices.

package/LICENSE

@@ -0,0 +1,201 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,190 @@
-# Temporary Holding Version
+# Throughline
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Readable state over time, authored in Markdown.**
+
+Throughline compiles small, explanatory state traces into deterministic,
+versioned snapshots. Its optional React player makes each change visible as
+a step-by-step SVG scene—with keyboard controls, accessible descriptions,
+responsive layouts and opt-in sound.
+
+Use it to explain what changes during an algorithm, a data-structure
+operation, a recursive call or a system workflow. Throughline does not
+execute arbitrary code or require an account, server, network connection
+or application-specific runtime.
+
+## Features
+
+- **Author in Markdown:** write a `thl` code fence with explicit, named steps.
+- **Deterministic snapshots:** compile once, then seek through immutable
+  frames without re-running the authored program.
+- **Five supported domains:** hand-authored `flow`, reference `bindings`,
+  `binary` addition, `matrix` multiplication and recursive `callstack`.
+- **React is optional:** use the pure compiler from Node or other ESM
+  environments without loading React or browser globals.
+- **Accessible playback:** keyboard navigation, step captions, a state
+  inspector, reduced-motion support and explicit CSS/theme controls.
+- **Bounded by design:** source, state, event and expansion limits provide
+  predictable rejection rather than uncontrolled trace growth.
+
+## Installation
+
+Install the package from npm:
+
+~~~sh
+npm install @0xbuff/throughline
+~~~
+
+For the optional React player, use React 19 and React DOM 19 in the
+consuming application:
+
+~~~sh
+npm install react@^19 react-dom@^19
+~~~
+
+The package targets Node.js 24 or later, uses ESM and ships TypeScript
+declarations. React is not required for the root compiler import.
+
+## Quick start
+
+### Compile a trace
+
+~~~ts
+import { compile } from "@0xbuff/throughline";
+
+const source = [
+  "```thl flow",
+  'node counter "Counter" = 0',
+  'step "Increment"',
+  "  set counter = 1",
+  "  focus counter",
+  '  note "Counter now holds one."',
+  "```",
+].join("\n");
+
+const trace = compile(source);
+
+// Frame 0 contains the initial state; later frames capture authored steps.
+console.log(trace.version);       // 1
+console.log(trace.frames.length); // 2
+~~~
+
+A `thl flow` block declares entities and relationships first, followed by
+named steps using operations such as `set`, `focus`, `note`, `send`,
+`show` and `hide`. Markdown fences are optional when calling `compile`
+directly, but each source must identify its `thl` domain.
+
+### Render it with React
+
+~~~tsx
+import { compile } from "@0xbuff/throughline";
+import { EXAMPLES } from "@0xbuff/throughline/examples";
+import { ThroughlinePlayer } from "@0xbuff/throughline/react";
+import "@0xbuff/throughline/styles/throughline.css";
+
+const trace = compile(EXAMPLES[0].source);
+
+export function TraceDemo() {
+  return <ThroughlinePlayer trace={trace} theme="auto" />;
+}
+~~~
+
+Import the optional stylesheet once in the host application. The player accepts
+`light`, `dark` or `auto` themes and supports `--thl-*` CSS variables.
+Override those variables using the player's `className` prop and a host
+stylesheet loaded after the package CSS. A complete custom stylesheet is
+also possible, but must provide the required layout and accessibility styles.
+Pass a stable trace reference while stepping; replacing it resets playback.
+Audio controls are absent unless you explicitly supply `sonification`.
+
+## Supported domains
+
+| Domain | What it explains | Authoring model |
+| --- | --- | --- |
+| `flow` | State, relationships and changes | Explicit nodes, links and steps |
+| `bindings` | Primitives, references, mutation and rebinding | Small assignment/push language |
+| `binary` | Ripple-carry binary addition | Two unsigned binary operands |
+| `matrix` | Matrix multiplication | Two small compatible matrices |
+| `callstack` | Recursive factorial calls and returns | A bounded factorial input |
+
+All five domains produce the same version-1 trace shape. Domains are
+intentionally limited; Throughline is not a general-purpose JavaScript
+interpreter or an automatic execution tracer.
+
+## Public package exports
+
+| Import path | Contents |
+| --- | --- |
+| `@0xbuff/throughline` | Core compiler, parser, types, validation, tracer |
+| `@0xbuff/throughline/react` | Optional `ThroughlinePlayer` and React types |
+| `@0xbuff/throughline/examples` | Copyable authored fixtures |
+| `@0xbuff/throughline/styles/throughline.css` | Opt-in, namespaced CSS |
+
+Only these four entry points are supported; importing from package
+`src/` or `dist/` paths is not part of the API. The compiler is
+React-free, network-free and usable in offline tooling.
+
+## How it works
+
+1. **Parse:** `compile` reads one `thl <domain>` block, preserving useful
+   source-line information for diagnostics.
+2. **Build:** `flow` is parsed into an authored program; computed domains
+   construct the same program model from bounded input parameters.
+3. **Validate and compile:** the engine rejects invalid references, JSON
+   values, conflicting writes and excessive work, then produces an initial
+   frame plus a snapshot for each step.
+4. **Present (optional):** the React player uses the compiled frames to
+   render a responsive scene, controls, captions and an inspectable state.
+   Seeking a frame does not execute the source a second time.
+
+Trace schema version `1` is independent of the npm package version.
+Source length is capped at 262,144 UTF-16 code units; the authored
+program is limited to 200 entities, 1,000 relations, 2,000 steps and
+10,000 events, plus work/expansion budgets. These limits are for
+deterministic work, not a guarantee of exact heap or CPU usage.
+
+For the complete guide, see the [Throughline documentation](https://docs.0xbuff.com/docs/throughline) and the [architecture notes](https://github.com/0xbuffdev/throughline/blob/main/docs/architecture.md).
+
+## Documentation
+
+- [Throughline documentation](https://docs.0xbuff.com/docs/throughline)
+- [Grammar and authored flow](https://github.com/0xbuffdev/throughline/blob/main/docs/grammar.md)
+- [Domain catalog and domain-specific limits](https://github.com/0xbuffdev/throughline/blob/main/docs/catalog.md)
+- [Architecture, trace format and runtime boundaries](https://github.com/0xbuffdev/throughline/blob/main/docs/architecture.md)
+- [Adding a computed domain](https://github.com/0xbuffdev/throughline/blob/main/docs/authoring.md)
+- [Changelog](https://github.com/0xbuffdev/throughline/blob/main/CHANGELOG.md)
+
+## Development
+
+The source is a standalone Node 24 / pnpm 11.2.2 package, not a
+multi-package workspace.
+
+~~~sh
+pnpm install --frozen-lockfile
+pnpm audit:source
+pnpm typecheck
+pnpm test:run
+pnpm exec playwright install chromium
+pnpm test:browser:run
+pnpm build
+pnpm audit:licenses
+pnpm audit:pack
+pnpm audit:browser
+~~~
+
+The packed-consumer audits install the built archive into independent
+Node, TypeScript, React SSR and Vite/browser environments.
+
+## Community
+
+Read [contributing guidelines](https://github.com/0xbuffdev/throughline/blob/main/CONTRIBUTING.md) before opening a PR.
+Use [GitHub issues](https://github.com/0xbuffdev/throughline/issues)
+for reproducible bugs and feature proposals; see
+[SUPPORT.md](https://github.com/0xbuffdev/throughline/blob/main/SUPPORT.md) for support and [SECURITY.md](https://github.com/0xbuffdev/throughline/blob/main/SECURITY.md)
+for confidential vulnerability reports. Participation is governed by
+the [code of conduct](https://github.com/0xbuffdev/throughline/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+Licensed under [Apache-2.0](https://github.com/0xbuffdev/throughline/blob/main/LICENSE).
+Copyright 2026 0xBUFF; see [COPYRIGHT.md](https://github.com/0xbuffdev/throughline/blob/main/COPYRIGHT.md).
+The license covers software rights under its terms, not trademark use.

package/dist/describe-ZC7v_r7z.js

@@ -0,0 +1,138 @@
+// src/path.ts
+const TARGET = /^([A-Za-z][\w-]*)((?:\[\d+\]|\.[A-Za-z_][\w-]*)*)$/;
+const BLOCKED = /* @__PURE__ */ new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+function parseTarget(text) {
+	const match = TARGET.exec(text);
+	if (!match) return null;
+	const path = [];
+	for (const part of match[2].matchAll(/\[(\d+)\]|\.([A-Za-z_][\w-]*)/g)) path.push(part[1] !== void 0 ? Number(part[1]) : part[2]);
+	if (path.some((key) => typeof key === "string" && BLOCKED.has(key))) return null;
+	return {
+		id: match[1],
+		path
+	};
+}
+const overlaps = (a, b) => a.slice(0, Math.min(a.length, b.length)).every((key, index) => key === b[index]);
+function getAt(value, path) {
+	let current = value;
+	for (const key of path) {
+		if (typeof key === "number") current = Array.isArray(current) ? current[key] : void 0;
+		else current = current !== null && typeof current === "object" && !Array.isArray(current) && Object.hasOwn(current, key) ? current[key] : void 0;
+		if (current === void 0) return void 0;
+	}
+	return current;
+}
+/** Immutable write. Arrays may grow by exactly one (index === length); records may gain keys. */
+function setAt(value, path, next) {
+	if (!path.length) return next;
+	const [head, ...rest] = path;
+	if (typeof head === "number") {
+		if (!Array.isArray(value)) throw new Error(`Cannot index [${head}] into a non-array value.`);
+		if (head > value.length) throw new Error(`Index [${head}] is out of range (length ${value.length}).`);
+		const copy = value.slice();
+		copy[head] = setAt(head === value.length ? null : value[head], rest, next);
+		return copy;
+	}
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(`Cannot read .${head} from a non-record value.`);
+	return {
+		...value,
+		[head]: setAt(Object.hasOwn(value, head) ? value[head] : null, rest, next)
+	};
+}
+// src/layout/measure.ts
+const format = (value) => typeof value === "string" ? value : JSON.stringify(value);
+/** A node's requested view if the value supports it, otherwise the best fit. Evaluated per frame. */
+function effectiveView(view, value) {
+	const guess = () => Array.isArray(value) ? value.length > 0 && value.every((row) => Array.isArray(row)) ? "matrix" : "array" : typeof value === "number" ? "number" : value !== null && typeof value === "object" ? "record" : "text";
+	switch (view) {
+		case "array":
+		case "stack": return Array.isArray(value) ? view : guess();
+		case "matrix": return Array.isArray(value) && value.every((row) => Array.isArray(row)) ? "matrix" : guess();
+		case "bits": return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? "bits" : guess();
+		case "record": return value !== null && typeof value === "object" && !Array.isArray(value) ? "record" : guess();
+		case "number": return typeof value === "number" ? "number" : guess();
+		case "text": return "text";
+		default: return guess();
+	}
+}
+// src/scene.ts
+/** Hidden endpoints suppress their links without destroying either identity. */
+function visibleScene(state) {
+	const entities = state.entities.filter((entity) => !entity.hidden);
+	const ids = new Set(entities.map((entity) => entity.id));
+	return {
+		entities,
+		relations: state.relations.filter((relation) => !relation.hidden && ids.has(relation.from) && ids.has(relation.to))
+	};
+}
+// src/describe.ts
+/**
+* Semantic summary: one screen-reader-navigable paragraph per frame.
+* The player voices this through a live region and the scene's
+* accessible name, so the trace never depends on vision alone.
+*/
+const entityValue = (frame, id) => frame.state.entities.find((entity) => entity.id === id)?.value;
+/** `input[0]` reads as its addressed value; whole ids read as labels. */
+function changedSummary(frame, target) {
+	const parsed = parseTarget(target);
+	if (!parsed) return target;
+	const value = entityValue(frame, parsed.id);
+	if (value === void 0) return target;
+	const current = parsed.path.length ? getAt(value, parsed.path) : value;
+	if (current === void 0) return target;
+	return `${parsed.path.length ? target : frame.state.entities.find((entity) => entity.id === parsed.id)?.label ?? parsed.id} is ${format(current)}`;
+}
+const transferSummary = (frame, relation, value) => {
+	const known = frame.state.relations.find((candidate) => candidate.id === relation);
+	const what = value === void 0 ? "a signal" : format(value);
+	if (!known) return `Send ${what} along ${relation}.`;
+	return `Send ${what} along ${relation}${known.label ? ` (${known.label})` : ""} from ${known.from} to ${known.to}.`;
+};
+/**
+* One paragraph naming the step position, label, changed values,
+* focus targets, transfers, and author notes. Deterministic: the
+* same frame always reads the same way.
+*/
+function describeFrame(frame, total) {
+	const count = total ?? frame.index + 1;
+	const parts = [`Step ${frame.index + 1} of ${count}: ${frame.label}.`];
+	const { state } = frame;
+	const scene = visibleScene(state);
+	const visible = scene.entities;
+	const visibleIds = new Set(visible.map((entity) => entity.id));
+	const hiddenIds = new Set(state.entities.filter((entity) => entity.hidden).map((entity) => entity.id));
+	const shownTarget = (target) => !hiddenIds.has(parseTarget(target)?.id ?? "");
+	const changed = state.changed.filter(shownTarget);
+	const active = state.active.filter(shownTarget);
+	if (visible.length === 0 && frame.events.length === 0) {
+		parts.push("No entities.");
+		return parts.join(" ");
+	}
+	if (frame.index === 0 && state.changed.length === 0 && state.transfers.length === 0 && state.notes.length === 0 && state.active.length === 0) {
+		parts.push(`${visible.map((entity) => `${entity.label} is ${format(entity.value)}`).join("; ")}.`);
+		return parts.join(" ");
+	}
+	for (const event of frame.events) {
+		if (event.op !== "show" && event.op !== "hide") continue;
+		const item = event.kind === "node" ? state.entities.find((entity) => entity.id === event.id) : state.relations.find((relation) => relation.id === event.id);
+		if (event.op === "show" && !(event.kind === "node" ? visibleIds.has(event.id) : scene.relations.some((relation) => relation.id === event.id))) continue;
+		parts.push(`${event.op === "show" ? "Show" : "Hide"} ${item?.label ?? event.id}.`);
+		if (event.op === "show" && event.kind === "node" && !changed.some((target) => parseTarget(target)?.id === event.id)) parts.push(`${changedSummary(frame, event.id)}.`);
+		if (event.op === "show" && event.kind === "link") {
+			const relation = scene.relations.find((candidate) => candidate.id === event.id);
+			if (relation) parts.push(`From ${relation.from} to ${relation.to}.`);
+		}
+	}
+	if (changed.length > 0) parts.push(`${changed.map((target) => changedSummary(frame, target)).join("; ")}.`);
+	if (active.length > 0) parts.push(`Focus on ${active.join(", ")}.`);
+	for (const transfer of state.transfers) parts.push(transferSummary(frame, transfer.relation, transfer.value));
+	if (state.notes.length > 0) parts.push(state.notes.join(" "));
+	return parts.join(" ");
+}
+export { getAt as a, setAt as c, format as i, visibleScene as n, overlaps as o, effectiveView as r, parseTarget as s, describeFrame as t };
+
+//# sourceMappingURL=describe-ZC7v_r7z.js.map

package/dist/describe-ZC7v_r7z.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-ZC7v_r7z.js","names":[],"sources":["../src/path.ts","../src/layout/measure.ts","../src/scene.ts","../src/describe.ts"],"sourcesContent":["import type { Value } from \"./model.js\";\n\nexport type Path = (string | number)[];\nexport type Target = { id: string; path: Path };\n\nconst TARGET = /^([A-Za-z][\\w-]*)((?:\\[\\d+\\]|\\.[A-Za-z_][\\w-]*)*)$/;\nconst BLOCKED = new Set([\"__proto__\", \"constructor\", \"prototype\"]);\n\nexport function parseTarget(text: string): Target | null {\n\tconst match = TARGET.exec(text);\n\tif (!match) return null;\n\tconst path: Path = [];\n\tfor (const part of match[2].matchAll(/\\[(\\d+)\\]|\\.([A-Za-z_][\\w-]*)/g))\n\t\tpath.push(part[1] !== undefined ? Number(part[1]) : part[2]);\n\tif (path.some((key) => typeof key === \"string\" && BLOCKED.has(key)))\n\t\treturn null;\n\treturn { id: match[1], path };\n}\n\nexport const overlaps = (a: Path, b: Path) =>\n\ta\n\t\t.slice(0, Math.min(a.length, b.length))\n\t\t.every((key, index) => key === b[index]);\n\nexport function getAt(value: Value | undefined, path: Path): Value | undefined {\n\tlet current = value;\n\tfor (const key of path) {\n\t\tif (typeof key === \"number\")\n\t\t\tcurrent = Array.isArray(current) ? current[key] : undefined;\n\t\telse\n\t\t\tcurrent =\n\t\t\t\tcurrent !== null &&\n\t\t\t\ttypeof current === \"object\" &&\n\t\t\t\t!Array.isArray(current) &&\n\t\t\t\tObject.hasOwn(current, key)\n\t\t\t\t\t? current[key]\n\t\t\t\t\t: undefined;\n\t\tif (current === undefined) return undefined;\n\t}\n\treturn current;\n}\n\n/** Immutable write. Arrays may grow by exactly one (index === length); records may gain keys. */\nexport function setAt(value: Value, path: Path, next: Value): Value {\n\tif (!path.length) return next;\n\tconst [head, ...rest] = path;\n\tif (typeof head === \"number\") {\n\t\tif (!Array.isArray(value))\n\t\t\tthrow new Error(`Cannot index [${head}] into a non-array value.`);\n\t\tif (head > value.length)\n\t\t\tthrow new Error(\n\t\t\t\t`Index [${head}] is out of range (length ${value.length}).`,\n\t\t\t);\n\t\tconst copy = value.slice();\n\t\tcopy[head] = setAt(head === value.length ? null : value[head], rest, next);\n\t\treturn copy;\n\t}\n\tif (value === null || typeof value !== \"object\" || Array.isArray(value))\n\t\tthrow new Error(`Cannot read .${head} from a non-record value.`);\n\treturn {\n\t\t...value,\n\t\t[head]: setAt(Object.hasOwn(value, head) ? value[head] : null, rest, next),\n\t};\n}\n","import type { Value, View } from \"../model.js\";\n\ntype Shown = Exclude<View, \"auto\">;\n\nexport const format = (value: Value): string =>\n\ttypeof value === \"string\" ? value : JSON.stringify(value);\n\n/** A node's requested view if the value supports it, otherwise the best fit. Evaluated per frame. */\nexport function effectiveView(view: View | undefined, value: Value): Shown {\n\tconst guess = (): Shown =>\n\t\tArray.isArray(value)\n\t\t\t? value.length > 0 && value.every((row) => Array.isArray(row))\n\t\t\t\t? \"matrix\"\n\t\t\t\t: \"array\"\n\t\t\t: typeof value === \"number\"\n\t\t\t\t? \"number\"\n\t\t\t\t: value !== null && typeof value === \"object\"\n\t\t\t\t\t? \"record\"\n\t\t\t\t\t: \"text\";\n\tswitch (view) {\n\t\tcase \"array\":\n\t\tcase \"stack\":\n\t\t\treturn Array.isArray(value) ? view : guess();\n\t\tcase \"matrix\":\n\t\t\treturn Array.isArray(value) && value.every((row) => Array.isArray(row))\n\t\t\t\t? \"matrix\"\n\t\t\t\t: guess();\n\t\tcase \"bits\":\n\t\t\treturn typeof value === \"number\" &&\n\t\t\t\tNumber.isSafeInteger(value) &&\n\t\t\t\tvalue >= 0\n\t\t\t\t? \"bits\"\n\t\t\t\t: guess();\n\t\tcase \"record\":\n\t\t\treturn value !== null &&\n\t\t\t\ttypeof value === \"object\" &&\n\t\t\t\t!Array.isArray(value)\n\t\t\t\t? \"record\"\n\t\t\t\t: guess();\n\t\tcase \"number\":\n\t\t\treturn typeof value === \"number\" ? \"number\" : guess();\n\t\tcase \"text\":\n\t\t\treturn \"text\";\n\t\tdefault:\n\t\t\treturn guess();\n\t}\n}\n","import type { Snapshot } from \"./model.js\";\n\n/** Hidden endpoints suppress their links without destroying either identity. */\nexport function visibleScene(\n\tstate: Snapshot,\n): Pick<Snapshot, \"entities\" | \"relations\"> {\n\tconst entities = state.entities.filter((entity) => !entity.hidden);\n\tconst ids = new Set(entities.map((entity) => entity.id));\n\tconst relations = state.relations.filter(\n\t\t(relation) =>\n\t\t\t!relation.hidden && ids.has(relation.from) && ids.has(relation.to),\n\t);\n\treturn { entities, relations };\n}\n","import { format } from \"./layout.js\";\nimport type { Frame, Value } from \"./model.js\";\nimport { getAt, parseTarget } from \"./path.js\";\nimport { visibleScene } from \"./scene.js\";\n\n/**\n * Semantic summary: one screen-reader-navigable paragraph per frame.\n * The player voices this through a live region and the scene's\n * accessible name, so the trace never depends on vision alone.\n */\n\nconst entityValue = (frame: Frame, id: string): Value | undefined =>\n\tframe.state.entities.find((entity) => entity.id === id)?.value;\n\n/** `input[0]` reads as its addressed value; whole ids read as labels. */\nfunction changedSummary(frame: Frame, target: string): string {\n\tconst parsed = parseTarget(target);\n\tif (!parsed) return target;\n\tconst value = entityValue(frame, parsed.id);\n\tif (value === undefined) return target;\n\tconst current: Value | undefined = parsed.path.length\n\t\t? getAt(value, parsed.path)\n\t\t: value;\n\tif (current === undefined) return target;\n\tconst name = parsed.path.length\n\t\t? target\n\t\t: (frame.state.entities.find((entity) => entity.id === parsed.id)?.label ??\n\t\t\tparsed.id);\n\treturn `${name} is ${format(current)}`;\n}\n\nconst transferSummary = (frame: Frame, relation: string, value?: Value) => {\n\tconst known = frame.state.relations.find(\n\t\t(candidate) => candidate.id === relation,\n\t);\n\tconst what = value === undefined ? \"a signal\" : format(value);\n\tif (!known) return `Send ${what} along ${relation}.`;\n\tconst via = known.label ? ` (${known.label})` : \"\";\n\treturn `Send ${what} along ${relation}${via} from ${known.from} to ${known.to}.`;\n};\n\n/**\n * One paragraph naming the step position, label, changed values,\n * focus targets, transfers, and author notes. Deterministic: the\n * same frame always reads the same way.\n */\nexport function describeFrame(frame: Frame, total?: number): string {\n\tconst count = total ?? frame.index + 1;\n\tconst parts = [`Step ${frame.index + 1} of ${count}: ${frame.label}.`];\n\tconst { state } = frame;\n\tconst scene = visibleScene(state);\n\tconst visible = scene.entities;\n\tconst visibleIds = new Set(visible.map((entity) => entity.id));\n\tconst hiddenIds = new Set(\n\t\tstate.entities.filter((entity) => entity.hidden).map((entity) => entity.id),\n\t);\n\tconst shownTarget = (target: string): boolean =>\n\t\t!hiddenIds.has(parseTarget(target)?.id ?? \"\");\n\tconst changed = state.changed.filter(shownTarget);\n\tconst active = state.active.filter(shownTarget);\n\tif (visible.length === 0 && frame.events.length === 0) {\n\t\tparts.push(\"No entities.\");\n\t\treturn parts.join(\" \");\n\t}\n\tif (\n\t\tframe.index === 0 &&\n\t\tstate.changed.length === 0 &&\n\t\tstate.transfers.length === 0 &&\n\t\tstate.notes.length === 0 &&\n\t\tstate.active.length === 0\n\t) {\n\t\tparts.push(\n\t\t\t`${visible.map((entity) => `${entity.label} is ${format(entity.value)}`).join(\"; \")}.`,\n\t\t);\n\t\treturn parts.join(\" \");\n\t}\n\tfor (const event of frame.events) {\n\t\tif (event.op !== \"show\" && event.op !== \"hide\") continue;\n\t\tconst item =\n\t\t\tevent.kind === \"node\"\n\t\t\t\t? state.entities.find((entity) => entity.id === event.id)\n\t\t\t\t: state.relations.find((relation) => relation.id === event.id);\n\t\tif (\n\t\t\tevent.op === \"show\" &&\n\t\t\t!(event.kind === \"node\"\n\t\t\t\t? visibleIds.has(event.id)\n\t\t\t\t: scene.relations.some((relation) => relation.id === event.id))\n\t\t)\n\t\t\tcontinue;\n\t\tparts.push(\n\t\t\t`${event.op === \"show\" ? \"Show\" : \"Hide\"} ${item?.label ?? event.id}.`,\n\t\t);\n\t\tif (\n\t\t\tevent.op === \"show\" &&\n\t\t\tevent.kind === \"node\" &&\n\t\t\t!changed.some((target) => parseTarget(target)?.id === event.id)\n\t\t)\n\t\t\tparts.push(`${changedSummary(frame, event.id)}.`);\n\t\tif (event.op === \"show\" && event.kind === \"link\") {\n\t\t\tconst relation = scene.relations.find(\n\t\t\t\t(candidate) => candidate.id === event.id,\n\t\t\t);\n\t\t\tif (relation) parts.push(`From ${relation.from} to ${relation.to}.`);\n\t\t}\n\t}\n\tif (changed.length > 0)\n\t\tparts.push(\n\t\t\t`${changed.map((target) => changedSummary(frame, target)).join(\"; \")}.`,\n\t\t);\n\tif (active.length > 0) parts.push(`Focus on ${active.join(\", \")}.`);\n\tfor (const transfer of state.transfers)\n\t\tparts.push(transferSummary(frame, transfer.relation, transfer.value));\n\tif (state.notes.length > 0) parts.push(state.notes.join(\" \"));\n\treturn parts.join(\" \");\n}\n"],"mappings":"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"}

package/dist/examples.d.ts

@@ -0,0 +1,17 @@
+/** Copyable sources shared by the gallery, editor and compiler acceptance tests. */
+export declare const EXAMPLES: readonly [{
+  readonly id: "reconciliation";
+  readonly title: "Reconciliation";
+  readonly description: "Compare keyed children, preserve identity, and prepare the changes to commit.";
+  readonly source: string;
+}, {
+  readonly id: "references";
+  readonly title: "Shared references";
+  readonly description: "Copy a reference, mutate the shared object, then move one pointer.";
+  readonly source: string;
+}, {
+  readonly id: "matrix";
+  readonly title: "Matrix multiplication";
+  readonly description: "Follow one row and one column to each output cell.";
+  readonly source: "```thl matrix\nA = [[1,2],[3,4]]\nB = [[5,6],[7,8]]\n```";
+}];