Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
71 commits
Select commit Hold shift + click to select a range
a9b59b0
feat(TL-U10): add bounded offline Markdown/MDX fence discovery for CLI
christophersesugh Nov 15, 2026
b6a62cb
feat(TL-U10): confine trusted Node host and CLI filesystem reads and …
christophersesugh Nov 15, 2026
dbb01d4
feat(TL-U10): reuse strict bounded duplicate-key JSON scan for untrus…
christophersesugh Nov 15, 2026
16e9851
feat(TL-U10): expose trusted Node-only Remark host loader with strict…
christophersesugh Nov 15, 2026
4f282f4
fix(TL-U10): allow explicit repository-root directory checks without …
christophersesugh Nov 15, 2026
b3d4048
feat(TL-U10): implement validate materialize check CLI with reviewed …
christophersesugh Nov 15, 2026
ef9adc0
feat(TL-U10): add standalone Node binary entrypoint
christophersesugh Nov 15, 2026
25f954b
fix(TL-U10): preserve stable underlying failure codes and type manife…
christophersesugh Nov 15, 2026
8cced56
feat(TL-U10): register standalone thl binary and optional Node host w…
christophersesugh Nov 15, 2026
64fe624
feat(TL-U10): register standalone thl binary and optional Node host w…
christophersesugh Nov 15, 2026
a113a95
test(TL-U10): exercise offline CLI, reviewed sidecars, symlink confin…
christophersesugh Nov 15, 2026
19517ed
test(TL-U10): verify optional Node host and executable CLI are includ…
christophersesugh Nov 15, 2026
4bfca67
test(TL-U10): require packed CLI and Node host to validate sidecars o…
christophersesugh Nov 15, 2026
4acd7c1
fix(TL-U10): resolve strict TypeScript CLI imports and trusted-root d…
christophersesugh Nov 15, 2026
305ad80
fix(TL-U10): resolve strict TypeScript CLI imports and trusted-root d…
christophersesugh Nov 15, 2026
dbf2f9b
fix(TL-U10): classify duplicate JSON syntax before schema-version err…
christophersesugh Nov 15, 2026
b72e849
docs(TL-U10): document offline CLI, review gate, filesystem confineme…
christophersesugh Nov 15, 2026
268b0c0
docs(TL-U10): show real trusted Node host adapter and CLI-based revie…
christophersesugh Nov 15, 2026
e1bff09
docs(TL-U10): align CHANGELOG.md with offline CLI, node host and pre-…
christophersesugh Nov 15, 2026
264584b
docs(TL-U10): align docs/README.md with offline CLI, node host and pr…
christophersesugh Nov 15, 2026
d8739ab
docs(TL-U10): align README.md with offline CLI, node host and pre-rel…
christophersesugh Nov 15, 2026
cd82f7b
docs(TL-U10): align docs/releasing.md with offline CLI, node host and…
christophersesugh Nov 15, 2026
cad5c26
fix(TL-U10): explicitly externalize Node-only builtins in optional ho…
christophersesugh Nov 15, 2026
27b82ec
fix(TL-U10): accept source-less re-export facades backed by mapped CL…
christophersesugh Nov 15, 2026
d679c14
fix(TL-U10): use plain-text facade detection for source map fallback
christophersesugh Nov 15, 2026
1c1c8e0
feat(TL-U10): remove v1 domain compiler, grammar and model exports fr…
christophersesugh Nov 15, 2026
03f453d
feat(TL-U10): expose native schema-2 player and embed only in React e…
christophersesugh Nov 15, 2026
abdd3c7
test(TL-U10): retain historical v1 regressions via internal modules, …
christophersesugh Nov 15, 2026
cc2091f
test(TL-U10): retain historical v1 regressions via internal modules, …
christophersesugh Nov 15, 2026
cff5c4b
test(TL-U10): keep old player tests private after public v1 React ret…
christophersesugh Nov 15, 2026
7fe7b60
test(TL-U10): keep old player tests private after public v1 React ret…
christophersesugh Nov 15, 2026
9bc2f91
test(TL-U10): keep old player tests private after public v1 React ret…
christophersesugh Nov 15, 2026
7c83c70
test(TL-U10): keep old player tests private after public v1 React ret…
christophersesugh Nov 15, 2026
bc00db7
test(TL-U10): keep old player tests private after public v1 React ret…
christophersesugh Nov 15, 2026
9e3c65f
test(TL-U10): keep old player tests private after public v1 React ret…
christophersesugh Nov 15, 2026
cfe420e
test(TL-U10): keep old player tests private after public v1 React ret…
christophersesugh Nov 15, 2026
0464084
test(TL-U10): isolate legacy browser suite from supported schema-2 Re…
christophersesugh Nov 15, 2026
bd95295
test(TL-U10): isolate legacy browser suite from supported schema-2 Re…
christophersesugh Nov 15, 2026
a1835e5
test(TL-U10): isolate legacy browser suite from supported schema-2 Re…
christophersesugh Nov 15, 2026
e118eff
test(TL-U10): isolate legacy browser suite from supported schema-2 Re…
christophersesugh Nov 15, 2026
2fc0078
test(TL-U10): isolate legacy browser suite from supported schema-2 Re…
christophersesugh Nov 15, 2026
109ef78
test(TL-U10): isolate legacy browser suite from supported schema-2 Re…
christophersesugh Nov 15, 2026
ccd3ea7
test(TL-U10): isolate legacy browser suite from supported schema-2 Re…
christophersesugh Nov 15, 2026
27c1df0
test(TL-U10): replace packed v1 Node/React consumer paths with schema…
christophersesugh Nov 15, 2026
ccf967e
test(TL-U10): migrate independent packed browser SSR/hydration proof …
christophersesugh Nov 15, 2026
a7690f2
test(TL-U10): smoke native schema-2 public exports and reject legacy …
christophersesugh Nov 15, 2026
52df716
test(TL-U10): keep legacy domain boundary regressions internal after …
christophersesugh Nov 15, 2026
967cb7d
fix(TL-U10): verify schema-2 root re-export facade without legacy reg…
christophersesugh Nov 15, 2026
fe279e5
fix(TL-U10): permit larger schema-2 export facade while requiring map…
christophersesugh Nov 15, 2026
e923a60
test(TL-U10): assert null-prototype inspector cell semantics rather t…
christophersesugh Nov 15, 2026
a83e768
fix(TL-U10): make native fullscreen control capability SSR and hydrat…
christophersesugh Nov 15, 2026
697c50b
docs(TL-U10): replace outdated v1 architecture with current schema-2 …
christophersesugh Nov 15, 2026
9fff88e
docs(TL-U10): align contributor rules with v2-only exports, CLI and n…
christophersesugh Nov 15, 2026
7638f4a
fix(TL-U10): replace raw fence scanner with non-evaluating Markdown a…
christophersesugh Nov 15, 2026
71785e6
fix(TL-U10): use actual Markdown or MDX AST code nodes in CLI check a…
christophersesugh Nov 15, 2026
b874610
fix(TL-U10): declare and audit non-evaluating Markdown/MDX parser dep…
christophersesugh Nov 15, 2026
c9c1970
fix(TL-U10): declare and audit non-evaluating Markdown/MDX parser dep…
christophersesugh Nov 15, 2026
666ec96
fix(TL-U10): declare and audit non-evaluating Markdown/MDX parser dep…
christophersesugh Nov 15, 2026
a9ac11b
fix(TL-U10): declare and audit non-evaluating Markdown/MDX parser dep…
christophersesugh Nov 15, 2026
7f455f1
fix(TL-U10): declare and audit non-evaluating Markdown/MDX parser dep…
christophersesugh Nov 15, 2026
bf0016c
chore(TL-U10): temporarily run branch-scoped lock regeneration for re…
christophersesugh Nov 15, 2026
63b8587
chore(TL-U10): lock audited Markdown and MDX syntax parsers
github-actions[bot] Nov 15, 2026
ac8c587
chore(TL-U10): remove temporary lockfile refresh after signed-off fro…
christophersesugh Nov 15, 2026
a3413e1
test(TL-U10): require real mdast depth-first nested fences and reject…
christophersesugh Nov 15, 2026
9cb5fde
fix(TL-U10): give bounded mdast discovery a stable authoring limit di…
christophersesugh Nov 15, 2026
21f9324
test(TL-U10): update legacy scanner expectation to actual CommonMark …
christophersesugh Nov 15, 2026
e6b07be
test(TL-U10): assert independent packed CLI parses nested mdast fence…
christophersesugh Nov 15, 2026
ac954b3
docs(TL-U10): align CHANGELOG.md with real syntax-tree discovery and …
christophersesugh Nov 15, 2026
fd0eddf
docs(TL-U10): align docs/cli.md with real syntax-tree discovery and s…
christophersesugh Nov 15, 2026
e407d6e
docs(TL-U10): align src/node/index.ts with real syntax-tree discovery…
christophersesugh Nov 15, 2026
74cf260
fix(TL-U10): locate pnpm-hoisted transitive type dependencies during …
christophersesugh Nov 15, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
146 changes: 49 additions & 97 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,106 +1,58 @@
# AGENTS.md
# Repository instructions

Instructions for coding agents working in this repository. This file applies
to the entire repository; follow any more specific `AGENTS.md` in a
subdirectory when present.
These instructions apply to the entire Throughline repository. Follow more specific `AGENTS.md` files where present. Read the [public architecture](docs/architecture.md) and the relevant contract before changing observable behavior.

## Project overview
## Purpose and boundaries

Throughline (`@0xbuff/throughline`) is a standalone TypeScript/ESM package
for compiling Markdown-authored state traces into bounded, deterministic
snapshots. Its React 19 player is optional. The package must remain usable
without a host application, account, backend, network connection, or React
when importing the core compiler.
Throughline is a standalone TypeScript/ESM package for authoring and inspecting deterministic, evidence-linked **schema-2 `VisualArtifact`** timelines. The compiler is pure and offline. React 19 is optional. The CLI is Node 24+ only. Neither the compiler nor the CLI executes authoring prose or calls an AI provider.

Read `README.md`, `docs/architecture.md`, and the relevant grammar/domain
documentation before changing observable behavior. The source and
`package.json` define the implementation and published package contract.
The current source is a pre-release schema-2 redesign. Do not describe it as already published to npm. The package version and the artifact schema version are different concepts. No version-1 backward compatibility or translation layer may be added.

## Development and verification
## Public contracts

Use Node.js 24+, pnpm 11.2.2 and the committed lockfile in this
single-package repository. Run the relevant tests for each change and
follow [verification and release procedures](docs/releasing.md) for a
full release candidate. Never misrepresent skipped or failed checks.
Keep exactly these package exports unless a reviewed ticket explicitly changes them:

- `@0xbuff/throughline`: `validateArtifact`, `parseArtifactJson`, `serializeArtifact`, `compileArtifact`, `inspectTrace`, `projectView`, `projectInspection`, authoring/hash helpers and associated schema-2 types.
- `@0xbuff/throughline/remark`: mdast validation and literal-data MDX transform.
- `@0xbuff/throughline/node`: trusted Node filesystem host and non-executing Markdown/MDX AST discovery for the CLI.
- `@0xbuff/throughline/react`: `ThroughlineGraphPlayer` and `ThroughlineEmbed`.
- `@0xbuff/throughline/examples`: four reference artifacts with matched explanations, questions, expected answers, evidence event IDs and caveats.
- `@0xbuff/throughline/styles/throughline.css`: explicitly imported, namespaced CSS.

The separate executable is `thl` and supports `validate`, `materialize`, `check` and help. Do not add wildcard exports or require deep imports. Public `parseThl`, `compile`, `compileProgram`, `ThroughlinePlayer` and domain-tagged fences were intentionally removed.

## Repository map

- `src/index.ts`, `src/compiler.ts`, `src/dsl.ts`, `src/model.ts`,
`src/tracer.ts`: the core parser, validation, types, and trace compiler.
- `src/domains/`: the legacy v1 supported domains: `flow`, `bindings`,
`binary`, `matrix`, and `callstack`, pending TL-U08 migration.
- `src/remark/`: optional mdast validation plugin; keep React out and preserve
host-owned source positions.
- `src/layout/`, `src/layout.ts`, `src/scene.ts`: React-independent
scene composition and layout.
- `src/react/`: optional player, controls, inspector, accessible
captions, and opt-in sonification.
- `src/styles/throughline.css`: explicitly imported, `thl-`-namespaced
player styles and `--thl-*` customization tokens.
- `src/examples.ts`: public examples and acceptance fixtures.
- `src/**/__tests__/`, `scripts/`: regression, browser, packaging,
source-boundary, and license checks.
- `docs/`: grammar, authoring, integration and architecture documentation.
- `.github/workflows/ci.yml`: read-only quality checks.
- `.github/workflows/publish.yml`, `docs/releasing.md`: manual npm
staging, provenance, and maintainer approval procedures.

## Public API and compatibility

Support exactly these package imports:

- `@0xbuff/throughline`
- `@0xbuff/throughline/remark`
- `@0xbuff/throughline/react`
- `@0xbuff/throughline/examples`
- `@0xbuff/throughline/styles/throughline.css`

Do not add undocumented deep imports or wildcard exports. The core
compiler must never depend on React, browser globals, or host-specific
code. Keep `react` and `react-dom` as optional peer dependencies.

The accepted future contract is schema-2 `VisualArtifact` (see
`docs/schema-v2.md` and context Specification 0004 §§10–13).
`Program.version` and `Trace.version` are current legacy schema-1 source
implementation, not a compatibility guarantee. There are no existing v1 users
whose migration must block the accepted redesign. Keep v1 stable within an
individual incremental PR only to avoid leaving the repository untestable;
replace and remove legacy public APIs with the reviewed TL-U03–TL-U10 work.
Preserve deterministic compilation and stable seeking through frames.

## Implementation and security rules

- Follow the existing strict TypeScript, ESM, and code formatting
conventions; keep changes small and avoid unnecessary dependencies.
- Never execute authored source, call `eval`, or fetch remote resources
as part of compilation. No telemetry or persistent source storage.
- Render author-provided strings as text, not untrusted HTML.
- Preserve bounds on source size, work, state and expansion, plus
source-positioned errors, cycle rejection, and atomic state updates.
- Preserve accessible labels, keyboard navigation, live status, focus
visibility, reduced-motion behavior, responsive layout, and SSR
hydration. Keep sound opt-in.
- Review dependency licenses, notices, bundled output, and package
contents before changing dependencies or build configuration.
- Never add credentials, private planning links, host-only packages,
unpublished dependencies, or sensitive materials to public source.

## Change and release workflow

- Work on a dedicated branch and open a focused PR against `main`.
Document purpose, compatibility impact, implementation, and checks
actually run. Keep `README.md`, relevant `docs/`, tests, and
`CHANGELOG.md` in sync with user-visible changes.
- Final review, any required signing, merges, Git tags and npm release
approvals require maintainer authorization. Never invent approvals or
claim unperformed actions are complete.
- Do not publish, stage, approve, move release tags, change repository
visibility, or rewrite Git history without explicit authorization.
- Publication uses an immutable, GitHub-verified signed tag and the
manually dispatched `publish.yml` workflow. Only its protected
`npm-publish` staging job receives `id-token: write`. No npm
token or OIDC write permission belongs in quality CI. npm staging
is not a public release; final npm 2FA approval is separate.

See `CONTRIBUTING.md`, `SECURITY.md` and `docs/releasing.md` for
contribution, security reporting and release procedures.
- `src/v2/`: canonical schema-2 model, strict JSON, atomic replay, queries, source-preserving projections, authoring, digests and limits.
- `src/remark/`: host-neutral mdast transform. It must validate every matching `thl` node before mutating the tree.
- `src/node/`: trusted Node-only filesystem and Markdown/MDX AST parsing. Discovery must reflect **actual** code nodes, including nested containers; HTML comments and embedded syntax are not code fences.
- `src/cli/`: offline command-line arguments, validation, unreviewed materialization and check diagnostics.
- `src/react/`: native player, caption, controls, accessibility, optional narration and SSR/hydration behavior.
- `src/reference/`, `src/examples.ts`: the four schema-2 reference baselines.
- `src/styles/`: `thl-`-scoped styles and `--thl-*` tokens.
- `src/domains/`, `src/compiler.ts`, `src/dsl.ts` and other older files: **internal** v1 regression scaffolding pending later cleanup. Do not export or extend these for production.
- `scripts/`, `src/**/__tests__/`: pure, Node/CLI, packed archive, browser, framework, security and provenance checks.
- `docs/`: authoritative human-readable public architecture, grammar, CLI, integration and release guides.
- `.github/workflows/ci.yml`: quality-only, read-only CI. Publication requires the separate maintainer-controlled process.

## Implementation rules

Use Node.js 24+, pnpm 11.2.2, strict TypeScript and the committed lockfile. Keep a single canonical source of truth; do not duplicate artifact state or infer events from visuals, graph edges, notes or message timestamps. Each step commits atomically; known `null` is not unknown. Evidence must cite declared events. Maintain bounded source, state, JSON and replay work.

Markdown/MDX discovery must parse syntax trees **without running MDX or JavaScript**. Its depth-first zero-based `thl` ordinals, source content and positions must agree with the Remark host. Unqualified `thl` is the only supported fence. The opening brace selects strict JSON; prose requires an exact, separately reviewed sidecar. A new or regenerated sidecar always remains `unreviewed` until a human explicitly reviews it. No auto-approval command.

The Node host alone may read filesystem paths, using a trusted real root, strict relative POSIX locators, bounded decoding and symlink rejection. Never reflect a raw loader exception, let content select a root or execute its embedded code. Keep the root library and Remark entry free of Node filesystem, React and network dependencies. React and React DOM remain optional peers; browser-only capabilities must be detected after hydration.

Follow the project's existing naming and code style. Review third-party dependency licenses and notices; update both `package.json` and the committed lockfile when adding packages. Avoid undocumented exports, arbitrary imports and dependencies on unpublished versions. Never insert private architecture links, tokens or internal-project details in public documentation.

## Verification

Before proposing review, run the relevant checks and ensure the exact PR head has passing CI. For a full package change, verify TypeScript, local preview build/typecheck, pure/CLI tests, browser tests, distribution, source/license audits, an independently packed Node-only/CLI consumer, optional Remark/React/MDX integrations, mobile SSR/hydration and framework consumers. Include negative regressions for malformed or unauthorized input, changed source hashes, unknown states and false code-node discovery.

Do not claim tests passed if not run. Do not substitute local source imports for packed-consumer proof, or infer npm publication from a successful archive build. Keep [documentation](docs/README.md) and the [changelog](CHANGELOG.md) aligned with user-facing contracts.

## Pull requests and releases

Use one focused branch and PR per accepted ticket. Give the maintainer an accurate summary of decisions, user-visible changes, security limits and actual verification. Respond to and resolve review threads only after the corrections and tests are confirmed. Leave PRs unmerged until the maintainer authorizes merging.

Do not deploy, publish, sign or move release tags, change repository visibility, archive architecture tickets, grant new credentials or rewrite Git history without the appropriate explicit approval. Release stages and the live documentation-app upgrade are separate gates. See [release guidance](docs/releasing.md), [contribution guidelines](CONTRIBUTING.md) and [security reporting](SECURITY.md).
20 changes: 18 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,30 @@
# Changelog

All notable changes to Throughline are recorded here. Package versions follow
[Semantic Versioning](https://semver.org/) independently of version-1
program and trace schemas. Changes are grouped using
[Semantic Versioning](https://semver.org/) independently of schema-2
`VisualArtifact.schemaVersion`. Changes are grouped using
[Keep a Changelog](https://keepachangelog.com/).

## [Unreleased]

### Added

- TL-U10 adds a separately packed Node 24+ `thl` CLI with strict
`validate`, `materialize` and `check` commands. Materialization computes
LF-normalized source and canonical artifact SHA-256, creates ordered
version-1 sidecars as **unreviewed**, and requires separate editorial review
before check/production. Strict JSON and sidecar errors use stable codes
with source line/ordinal where known. The independent `./node` host entry
confines file reads to a trusted root, rejects symlink/path escapes and
supplies reviewed sidecar loading for actual Remark/MDX integrations.
No AI, React or Node filesystem dependency reaches the pure root entry.
CLI and Node host have dedicated security tests and independently packed
consumer proof; the real documentation-app deployment is TL-U20.
TL-U10 review hardening replaced the heuristic CLI scanner with a
non-evaluating CommonMark/MDX mdast parser, ensuring nested list/JSX
code nodes are validated while comments and expression-like strings
are excluded. Strict parser dependencies are frozen in the lockfile,
tested with nested-source coordinates and through the packed CLI.
- TL-U09 replaces the published example catalog with four domain-neutral
typed schema-2 reference artifacts: factorial call stack, 2×2 matrix
multiplication, unsigned binary addition and a hypothetical distributed
Expand Down
20 changes: 20 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -196,6 +196,25 @@ References' mathematical truth and persistence order are independently tested.
Matched questions are a baseline for future comprehension studies, not
evidence of measured educational improvement.

## Offline CLI and reviewed Markdown authoring

The unreleased source now includes a standalone Node 24+ binary and a
Node-only trusted host entry. The commands accept only strict schema-2
artifacts, plain `thl` fences and reviewed, SHA-256-bound prose sidecars:

~~~sh
thl validate artifacts/factorial.json
thl materialize --document content/docs/factorial.mdx --ordinal 0 \
--artifact artifacts/factorial.json --manifest throughline/manifest.json
# Manually review the artifact and the generated unreviewed manifest entry.
thl check content/docs --manifest throughline/manifest.json
~~~

Materialization **never approves** generated artifacts. Hosts can use
`@0xbuff/throughline/node` to map VFile paths and load confined sidecars;
core validation still requires no Node filesystem, React or provider SDK.
See the [CLI and editorial-review procedure](docs/cli.md).

## Installation and version boundary

Install the published package with:
Expand Down Expand Up @@ -302,6 +321,7 @@ pending the separately reviewed v1 cleanup tickets.
- [Universal `thl` grammar](docs/grammar.md) and
[typed reference authoring](docs/authoring.md)
- [Framework integration guide](docs/framework-integrations.md)
- [Offline CLI, safe file loading and manual review](docs/cli.md)
- [Semantic schema-2 runtime](docs/schema-v2.md)
- [Documentation index](docs/README.md)
- [Changelog](CHANGELOG.md) and [release guidance](docs/releasing.md)
Expand Down
2 changes: 2 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ and render it with the optional native React player.
- [Universal thl contract](grammar.md): strict JSON/prose syntax, event semantics,
limits and diagnostics.
- [Reference catalog](catalog.md): factorial, matrix, binary and checkout.
- [Offline CLI and trusted Node host](cli.md): validate, materialize,
editorial-review gate, check and confinement boundaries.
- [Framework integration](framework-integrations.md): Fumadocs, Next.js,
Astro and other Markdown renderers.
- [Reference traces](reference-traces.md): the four independently checked schema-2 teaching models
Expand Down
Loading
Loading