@0xbuff/throughline 0.0.1 → 0.0.2

package/CHANGELOG.md

@@ -1,27 +1,26 @@
 # Changelog
 
-Notable externally observable changes are recorded here. Package
-versions follow Semantic Versioning, independently of trace/program
-schema version `1`.
+Notable changes to Throughline are recorded here. Package versions follow
+Semantic Versioning independently of the version-1 trace and program schemas.
 
-## [0.0.1] — Prepared, not yet published
+## [0.0.2] — 2026-11-08
 
-Initial proposed public release of Throughline.
+### Changed
 
-### Included
+- 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.
 
-- Deterministic, bounded authored-state trace compiler.
-- Version-1 `Program` and `Trace` formats with source diagnostics and
-  deterministic frame seeking.
-- Five supported domains: `flow`, `bindings`, `binary`, `matrix`,
-  and `callstack`.
-- Optional React 19 player with keyboard playback, captions, state
-  inspection, responsive layouts, reduced motion and optional sound.
-- Explicitly namespaced CSS, typed ESM exports and copyable examples.
-- Independent Node, TypeScript, SSR, Chromium and Vite hydration tests.
-- Apache-2.0 license and 0xBUFF attribution.
+## [0.0.1] — 2026-11-08
 
-**Publication pending:** the npm package is not yet released.
-Source-history clearance, legal-rights review, immutable release
-revision, registry staging/provenance and maintainer approval remain
-separate prerequisites.
+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

@@ -1,15 +1,8 @@
-# Copyright and attribution
+# Copyright and license
 
-Throughline
+Copyright 2026 0xBUFF.
 
-Copyright 2026 0xBUFF
+Throughline is licensed under the Apache License, Version 2.0.
+See [LICENSE](LICENSE) for the full terms.
 
-Throughline is licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE)
-for its terms.
-
-"0xBUFF" is the maintainer-designated project copyright attribution. This
-notice does not represent that the brand is incorporated as a separate legal
-entity, or that a transfer of underlying copyright title has occurred. The
-maintainer must verify authorship, legal ownership and redistribution rights
-before a public source or npm release. Third-party attribution obligations
-are reviewed separately; no third-party code is bundled in this package.
+Third-party dependencies retain their respective licenses and notices.

package/README.md

@@ -12,11 +12,6 @@ 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.
 
-> **Release status:** GitHub source is public and npm version `0.0.1`
-> is prepared for release. Check the registry for actual publication and
-> provenance; see [release operations](RELEASING.md).
-> The historical private planning reference still needs review.
-
 ## Features
 
 - **Author in Markdown:** write a `thl` code fence with explicit, named steps.
@@ -33,7 +28,7 @@ or application-specific runtime.
 
 ## Installation
 
-Once the first release is published to npm:
+Install the package from npm:
 
 ~~~sh
 npm install @0xbuff/throughline
@@ -93,8 +88,11 @@ export function TraceDemo() {
 }
 ~~~
 
-Import the stylesheet once in the host application. The player accepts
+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`.
 
@@ -138,21 +136,22 @@ React-free, network-free and usable in offline tooling.
    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 separate from package version `0.0.1`.
+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 technical details, see the [architecture notes](docs/architecture.md).
+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
 
-- [Grammar and authored flow](docs/grammar.md)
-- [Domain catalog and domain-specific limits](docs/catalog.md)
-- [Architecture, trace format and runtime boundaries](docs/architecture.md)
-- [Adding a computed domain](docs/authoring.md)
-- [Changelog](CHANGELOG.md)
+- [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
 
@@ -173,20 +172,19 @@ pnpm audit:browser
 ~~~
 
 The packed-consumer audits install the built archive into independent
-Node, TypeScript, React SSR and Vite/browser environments. Build success
-does not, by itself, authorize a public release.
+Node, TypeScript, React SSR and Vite/browser environments.
 
 ## Community
 
-Read [contributing guidelines](CONTRIBUTING.md) before opening a PR.
+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](SUPPORT.md) for support and [SECURITY.md](SECURITY.md)
+[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](CODE_OF_CONDUCT.md).
+the [code of conduct](https://github.com/0xbuffdev/throughline/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
-Licensed under [Apache-2.0](LICENSE).
-Copyright 2026 0xBUFF; see [COPYRIGHT.md](COPYRIGHT.md).
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0xbuff/throughline",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Readable state over time, authored in Markdown. A deterministic trace compiler with an optional React player.",
   "private": false,
   "license": "Apache-2.0",
@@ -33,7 +33,6 @@
   "files": [
     "dist",
     "src/styles",
-    "docs",
     "README.md",
     "LICENSE",
     "COPYRIGHT.md",
@@ -74,7 +73,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "homepage": "https://github.com/0xbuffdev/throughline#readme",
+  "homepage": "https://docs.0xbuff.com/docs/throughline",
   "keywords": [
     "state-traces",
     "visualization",

package/docs/architecture.md

@@ -1,93 +0,0 @@
-# Throughline architecture
-
-Throughline separates **authored programs**, **compiled snapshots**
-and **optional presentation**. This allows the compiler to run in Node
-build pipelines or other offline ESM environments without React or a DOM.
-
-## Data flow
-
-1. **Source:** `parseThl` reads one `thl <domain>` block (optionally
-   surrounded by Markdown backtick/tilde fences). It preserves source
-   line positions for diagnostics; parsing an entire Markdown document
-   belongs to the host application.
-2. **Domain:** `compileAst` dispatches `flow` to the authored-program
-   parser. The four computed adapters parse small parameter languages
-   and build the same `Program` through a deterministic tracer.
-3. **Validation:** `validateProgram` checks version, entity and relation
-   identifiers, event shapes, finite JSON-like values, targets,
-   overlapping writes, visibility and limits. Errors are surfaced
-   as `ProgramError` with diagnostics.
-4. **Compilation:** `compileProgram` emits a version-1 `Trace` with frame
-   zero (the initial state) followed by an immutable snapshot for each
-   authored beat. Each frame records active/changed targets,
-   transfers, notes and any source information.
-5. **Presentation:** `ThroughlinePlayer` derives a deterministic SVG
-   scene from these frames and lays out nodes/links for the available
-   width. Controls seek among precompiled frames instead of re-running
-   authoring code. Accessible captions and the inspector expose state
-   beyond the visual scene.
-
-## Public module boundaries
-
-| Module | Responsibility | React required? |
-| --- | --- | --- |
-| `@0xbuff/throughline` | Parsing, validation, compilation, tracer and types | No |
-| `@0xbuff/throughline/react` | Accessible player and optional sonification | Yes, React 19 peer |
-| `@0xbuff/throughline/examples` | Public sample inputs | No |
-| `@0xbuff/throughline/styles/throughline.css` | Namespaced player CSS | No |
-
-The root compiler does not fetch remote data or use runtime application
-services. External consumers import only the declared public exports;
-deep imports are deliberately unsupported.
-
-## Trace format and compatibility
-
-`Program.version` and `Trace.version` are both `1`, not the npm package
-version. Each authored step yields one frame after the initial frame,
-with state values, visibility and relevant event annotations.
-
-A package upgrade that changes syntax, model types, trace meaning,
-diagnostics, controls or CSS selectors is potentially breaking even
-when the trace-schema version stays constant. Maintain fixtures,
-regression tests and release notes for such changes.
-
-## Work and validation limits
-
-- Maximum source: **262,144 UTF-16 code units**.
-- Program: **200 entities**, **1,000 relations**, **2,000 steps**,
-  **10,000 events**.
-- Program payload budget: **1,000,000 deterministic work units**.
-- Expanded trace budget: **8,000,000 deterministic work units**.
-- Reject unsupported or cyclic/non-JSON input values and conflicting
-  overlapping writes with explicit diagnostics.
-
-These are work/payload constraints, not exact memory or CPU
-measurements. The four computed adapters apply their own domain limits;
-see [the catalog](catalog.md).
-
-## Playback and accessibility
-
-The player uses SVG to render the active scene. It keeps entity identity
-stable across changes, reserves layout space for future values,
-supports responsive groups and bounded views of large values, and
-provides a textual inspector. Keyboard navigation, native inputs,
-live status, reduced-motion preferences and SSR/hydration behavior
-are covered by browser and packed-consumer tests.
-
-Sonification is explicitly opted into by the caller and is not
-triggered merely by importing the package. Neither playback nor
-compilation records grades or authenticates learners.
-
-## Build and trust boundaries
-
-`tsdown` produces ESM, declarations and JavaScript source maps for
-the three JavaScript exports. The stylesheet is shipped separately.
-The source package uses one Node 24/pnpm CI job to run compiler and
-browser tests, inspect third-party dependency license files and
-install a packed tarball in independent Node, TypeScript, SSR and
-Vite/React consumers.
-
-These checks are necessary but do not establish copyright ownership,
-absence of all secrets, or public-release permission. The private
-source history must be separately cleared before any public-source
-cutover.

package/docs/authoring.md

@@ -1,54 +0,0 @@
-# Throughline adapter authoring guide
-
-How to add a computed domain. Copy `binary.ts` (simplest) or
-`bindings.ts` (dynamic topology on static edges); keep the adapter
-~100 lines plus tests.
-
-## Recipe
-
-1. **Syntax.** Define 2–5 lines of params in the fence body, e.g.
-   `a = 1011`. Iterate them with `sourceLines(ast)` (blank lines and `#`
-   comments skipped without shifting the original fence-relative numbers).
-2. **Parse: `parseX(ast: ThlBlock): Params`.** Validate everything and throw
-   `ProgramError([{ message, line }])` — these fail the build with the
-   same rendering as grammar errors. Parse never computes.
-3. **Build: `buildX(params: Params): Program`.** Run the ordinary
-   algorithm and narrate it with `tracer()`: `node`/`link` declarations
-   first, then one `step(label, body)` per micro-step using
-   `set`/`focus`/`send`/`note`. Use `group(name, "row" | "column" | "tree")`
-   to arrange a set of nodes. `tracer().get()` reads live state
-   between steps. Validate by compiling: `compileProgram` enforces
-   unknown targets, conflicting writes, and value shapes.
-4. **Register.** Add the name to `DomainName` (`domains/types.ts`),
-   `SUPPORTED_DOMAINS`, and the `COMPUTED` dispatch table
-   (`domains/registry.ts`), all re-exported from the package index.
-5. **Document.** Add a catalog entry: syntax, params, exactly which
-   micro-steps it emits, a minimal example, and its limits.
-
-## Staging rules
-
-The two staging rules live in `grammar.md` (one idea per beat;
-`send` does not mutate) and bind computed adapters too. Two
-adapter-specific additions:
-- **Stable identities, changing visibility.** Predeclare nodes and links;
-  future objects and inactive references start with `hidden: true`.
-  Use `show("node", id)` / `hide("node", id)` and their `"link"` equivalents
-  to describe the current structure. Rebinding hides the previous reference
-  and shows its replacement in one step. A transfer cannot use a hidden link
-  or endpoint. Reserving layout space does not require showing future objects.
-- **One source line = one beat** where the domain has source lines
-  (`bindings`); otherwise one computation step = one beat (`binary`
-  bits, `matrix` cells, `callstack` pushes/pops).
-
-## Tests (same change, no exceptions)
-
-- Parse: happy path plus every error branch (missing/duplicate/bad
-  operand, out-of-range) asserting the `/Line N/` message.
-- Build: beat labels in order, final entity values, at least one
-  transfer assertion, and one failure/edge case (zero carry, rebind,
-  1×1 grid, depth 1).
-- Registry: one routing test per domain in `__tests__/registry.test.ts`.
-- From this standalone package root, run `pnpm test:run` and
-  `pnpm typecheck`, plus browser tests for interactive changes.
-  Avoid `describe.only`, `test.only`, and skipped tests; current CI
-  does not automatically reject them.

package/docs/catalog.md

@@ -1,96 +0,0 @@
-# Throughline adapter catalog
-
-Computed domains turn terse params into micro-step Programs. Each adapter
-is `parse(ast) → params`, `build(params) → Program` (via `tracer()`),
-routed by the fence domain in `compile`. Hand-authored traces stay on
-`flow` (`grammar.md`); adapters exist only where humans should not
-hand-write the steps.
-
-## flow (hand-authored)
-
-Core grammar: `node`, `link`, `step`, `set`, `focus`,
-`send`, `note`, `show`, `hide`. The fallback for every domain without a computed
-adapter — workflows, protocols, pipelines, git/CI, threat models.
-See `grammar.md`. No limits beyond the engine caps (200 entities,
-1000 relations, 2000 steps, 10000 events).
-
-## bindings — variable slots, primitives vs references
-
-    ```thl bindings
-    let a = 5
-    let b = a
-    b = 9
-    const list = [1, 2]
-    const alias = list
-    alias.push(3)
-    alias = [7]
-    ```
-
-- Statements: `let`/`const <name> = <json|name>`, `<name> = <json|name>`,
-  `<name>.push(<json>, …)`. One source line = one beat.
-- Emits: a `Stack` lane (one slot per variable, `null` until declared)
-  plus a `Heap` lane (`o1`, `o2`, … per array/object literal). Copying a
-  reference sends a packet along a `var → heap` edge; pushing focuses
-  every variable sharing the object so the sync is visible.
-- Limits: `const` is not enforced; no expressions, indexing, or methods
-  besides `push`; push targets arrays only. Future variables and heap objects
-  start hidden. Only current reference edges are visible; rebinding hides
-  the previous edge while retaining the heap object for other aliases.
-
-## binary — ripple-carry addition
-
-    ```thl binary
-    a = 1011
-    b = 0110
-    ```
-
-- Params: `a = <bits>`, `b = <bits>` (order free). Operands are 1–16
-  binary digits.
-- Emits: `A`/`B` as `bits` nodes, a `Sum` row (MSB-first with a leading
-  carry-out slot, `·` placeholders), a `Carry` number. One beat per bit,
-  LSB first (`bit 0` …), then a `Result` beat: carries ripple visibly
-  because each beat sets its sum cell and the carry together.
-- Limits: 16 bits; unsigned only. Final result is always width n+1
-  (leading zero when there is no carry-out).
-
-## matrix — matrix multiplication
-
-    ```thl matrix
-    A = [[1,2],[3,4]]
-    B = [[5,6],[7,8]]
-    ```
-
-- Params: `A = <grid>`, `B = <grid>` (order free). Grids are 1–4 rows of
-  1–4 finite numbers, all rows equal length, inner dimensions matching.
-- Emits: `A`, `B`, `C` as `matrix` nodes (`C` starts as `·`), a `Terms`
-  work row, and `row`/`col` read edges. One beat per output cell in
-  row-major order: focuses the A row and B column cells, writes
-  `C[i][j]`, lands the pairwise products in `Terms`, and sends both
-  reads as packets. Notes carry the full `C[i][j] = t0 + t1 = total`
-  expansion.
-- Limits: 4×4. No transpose/inverse/determinant — `flow` covers the rest.
-
-## callstack — factorial recursion
-
-    ```thl callstack
-    fact 4
-    ```
-
-- Params: one line, `fact <n>`, depth 1–6.
-- Emits: `slot1…slotN` frame slots (`Call stack` lane, bottom-up) plus a
-  `Returns` row. Push beats run `fact(n)` down to `fact(1)` (`calls`
-  packets travel caller → callee); unwind beats pop each frame to `null`,
-  record its value, and send a `↩` packet; a final `done` beat lands the
-  total. Notes narrate the blocked-on / got-back arithmetic.
-- Limits: factorial only, depth ≤ 6 (13 beats max). General calls,
-  branches, and prediction are future adapters.
-
-## Planned (tier 2, lesson-on-demand)
-
-Each is one `parse` + one `build()` on `tracer()`, ~100 lines with
-tests — transcription of the `visualizer/` reference computations, never
-bespoke SVG: `vectors` (dot-product geometry, SEF6), `gradient`
-(descent + finite-difference compare, SEF6/AI3), `search` (binary
-search, SEF3), `sort` (bubble/insertion, SEF3), `cache`/`race`/`tcp`
-(SYS1–SYS4 simulators). Workflows never need adapters: `flow` + the
-grammar covers them.

package/docs/grammar.md

@@ -1,97 +0,0 @@
-# Throughline grammar reference — `thl flow`
-
-Source of truth for hand-authored traces. AI lesson authors write this;
-`compile` parses and validates it into snapshots. A host can call this during
-its build or at runtime.
-Parameterized domains (`bindings`, `binary`, `matrix`, `callstack`) are
-documented in `catalog.md`; they compile to this same grammar.
-
-## Fence
-
-    ```thl flow
-    node input "Vector" in "Memory" as array = [1,2,3]
-    step "Load"
-      focus input
-      note "Vector in memory"
-    ```
-
-- Info string names the domain: ```` ```thl flow ````.
-- Everything between the fences is the program. Surrounding prose carries
-  the concept; the fence carries only state and beats.
-- Blank lines and `#` comment lines are ignored.
-
-## Statements
-
-| Statement | Syntax | Notes |
-| --- | --- | --- |
-| `group` | `group "<name>" as <row|column|tree>` | Arranges nodes sharing this group name; omitted groups use `row`. |
-| `node` | `node <id> "<label>" [in "<lane>"] [as <view>] [hidden] [= <json>]` | Declares an entity. Missing value defaults to `null`. |
-| `link` | `link <id> <from> -> <to> ["<label>"] [hidden]` | Declares a directed edge between two node ids. |
-| `step` | `step "<label>"` | Opens a beat. Every `set`/`focus`/`send`/`note` after it belongs to it until the next `step`. |
-| `set` | `set <target> = <json>` | Writes a JSON value into an entity or a position inside it. |
-| `focus` | `focus [<target>, ...]` | Highlights entities/positions for this beat. Comma- or space-separated; may be empty. |
-| `send` | `send <relation> [= <json>]` | Highlights a directed transfer along a link; payload appears in the caption. Value optional. |
-| `note` | `note "<text>"` | Caption for this beat. |
-| `show` / `hide` | `show node <id>` / `hide link <id>` | Changes persistent visibility; either verb accepts `node` or `link`. |
-
-Groups, nodes, and links must come before the first `step`. Events before any
-`step` fail the build.
-
-## Targets and values
-
-- Target: an entity id, optionally followed by positions: `arr`, `arr[3]`,
-  `grid[1][2]`, `cfg.mode`. Writes to impossible paths (indexing a
-  non-array, `.key` on a non-record, out-of-range index) fail the build
-  at compile time. `focus` targets only need a known entity id — a
-  position that never resolves simply never highlights. Arrays may grow
-  by exactly one (`arr[len]` appends); records may gain keys.
-- Value: finite JSON. Quote strings (`"emit"`); arrays and objects are
-  supported. `NaN`/`Infinity` are rejected.
-- Views (per node, `as <view>`): `auto`, `text`, `number`, `array`,
-  `stack`, `matrix`, `bits`, `record`. Unknown views fail the build.
-- Lanes (per node, `in "<lane>"`): free-form grouping string rendered as
-  a group header (e.g. `"Memory"`, `"Output"`).
-
-## Frames
-
-Compilation emits frame 0 (`Initial state`, entity initial values) plus
-one frame per `step`. Seeking is a snapshot lookup, never recompute.
-
-- `set` updates the entity value for this and later frames; the beat's
-  `changed` list carries the raw target strings (e.g. `input[1]`).
-- `focus` and `set` targets together form the beat's `active` list.
-- `send` adds a transfer for this beat only.
-- `note` appends to the beat's caption lines.
-- `show` / `hide` changes visibility for this and later frames. Hidden nodes
-  retain their values and identities; links with hidden endpoints are omitted.
-  Declare future objects with `hidden`, then show them when they appear.
-  Conflicting visibility writes and transfers along hidden links or endpoints
-  fail compilation. Changes within a step are applied together.
-
-## Two staging rules (learned the hard way)
-
-1. **One idea per beat.** Square *then* add; carry *then* land. Fusing
-   two state changes into one step fuses their highlights and captions,
-   and a same-value write (e.g. `1² = 1` over `1`) shows no change highlight — only
-   the focus ring. Split beats stay legible.
-2. **`send` does not mutate.** The edge highlights the transfer, but the
-   destination keeps its old value until a `set` writes it. To show state
-   sync, pair them across beats (`send feed = 4` on the Add beat, or a
-   `Carry` beat with only `send` followed by a `Land` beat with `set`).
-
-## Limits
-
-200 entities, 1000 relations, 2000 steps, 10000 events per program.
-Overlapping writes to the same target (or its parent/child path) inside
-one step fail: split into separate steps.
-
-## Errors (line-aware, fail the build)
-
-    Line 2: Unknown view "sparkle". Use auto, text, number, array, stack, matrix, bits, record.
-    Line 4: Invalid target "a..x". Use an id, optionally followed by [index] or .key.
-    Line 5: Conflicting writes to "a[1]" in one step; split into separate steps.
-
-`ProgramError` carries diagnostics with source lines where available.
-Compiling a block throws on invalid syntax or state. A host build must invoke
-the compiler to reject invalid content before publication; the Academy also
-has a render-time error panel for malformed content.