diff --git a/AGENTS.md b/AGENTS.md index 15b50d5c..c3bb22fd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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). diff --git a/CHANGELOG.md b/CHANGELOG.md index 95d252bc..54d12657 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/README.md b/README.md index 22d3dcb5..8186aae2 100644 --- a/README.md +++ b/README.md @@ -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: @@ -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) diff --git a/docs/README.md b/docs/README.md index 9d8deaf5..0fe469e8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 diff --git a/docs/architecture.md b/docs/architecture.md index 6d828655..64a086e5 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,285 +1,74 @@ # 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. +Throughline turns authored, evidence-linked state changes into a deterministic timeline that readers can inspect. The source of truth is a **schema-2 `VisualArtifact`**, not a domain-specific language or executable program. Its compiler and inspection APIs work without React, a browser, an AI provider or a network connection. -## Data flow +The separately exported Node CLI and filesystem host add only build-time responsibilities. They cannot change the semantics of the core artifact. Nothing in this architecture supports the previous version-1 `Program` or `Trace` public APIs. -1. **Source:** `parseThl` reads one `thl ` 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. The optional title, centered diagram, borderless - playback controls, step count, caption and inspector disclosure - form the presentation shell. Browser fullscreen enters and exits for - this player element when supported; seeking never invents timing. +## From source to a view -## Pure scene projection +1. **Author.** A `VisualArtifact` declares stable entity, relation, group and origin IDs, initial known or unknown cells, and ordered steps. Each step contains named write, topology, message or observation events. Prose, model comments and relations do not themselves cause state changes. +2. **Validate.** `validateArtifact` or `parseArtifactJson` checks strict schema-2 data, uniqueness and references, topology, permissible JSON values and bounded size and work. Unsupported schema versions and malformed or duplicate-key JSON fail rather than being adapted. +3. **Compile.** `compileArtifact` commits each modeled step atomically, beginning from an explicit initial frame. It produces immutable `CompiledTrace` frames; messages and observations are evidence only, never implicit writes. +4. **Inspect.** `inspectTrace` serves indexed state-at-frame, entity history, source-event lookup, changes and declared causal dependencies. A missing acknowledgment stays missing; an unknown cell never becomes known because the diagram implies it. +5. **Project.** `projectView` creates source-linked graph, sequence and state-table descriptors from that same compiled truth. `projectInspection` produces the Explain/Inspect data model. Projection cannot invent an event or mutate a trace. A sequence request without message evidence falls back to an honest state table. +6. **Present.** `ThroughlineGraphPlayer` (`./react`) renders responsive views, playback and inspection. `ThroughlineEmbed` receives inert, validated `artifactJson` from Markdown/MDX and compiles it into the same player. The optional React 19 peer, CSS, browser narration and screen interactions belong here rather than in the core. -The internal `projectScene(snapshot, groups, preferences)` function separates -**compiled system state** from **presentation state**. Its overview projects all -authored-visible entities and links, with deterministic node, edge and flat -lane-group descriptors. Every node retains its original entity ID; every -edge and transfer retains its authored relation ID. A `send` remains a transfer -annotation, not evidence that the destination persisted the value. +```text +thl source (strict JSON or reviewed prose sidecar) + | + validation of VisualArtifact (schema 2) + | + compileArtifact — immutable CompiledTrace + | + inspectTrace + / \ + projectView projectInspection + \ / + React 19 player / host-owned rendering +``` -Focus mode selects explicitly chosen or focused entities, authored active -targets, and endpoints of currently visible transfers. When every target is -hidden or stale, the projection falls back to overview rather than blanking -visible system state. Authored `hide`/`show` always takes precedence over -presentation preferences, and hidden endpoints suppress their links. +There is **one canonical artifact**. Graph, sequence, state-table, inspector, captions and comprehension text present that artifact; they do not supply alternative transition systems. Every meaningful result must be traceable to declared source events. -View entities, relations, transfer payloads, groups, and descriptor arrays -are detached from compiled snapshot objects and frozen, including nested JSON -values. Projection copies only entities included in the view plus transfer -annotations—not the trace history—and relies on compiler-enforced JSON -depth/work budgets. The original snapshot remains mutable by neither -projection nor selection, and may be shared across compiled frames. The -React scene receives authored group layout preferences, preserving existing -`tree` and `column` lane semantics; optional hierarchy and collapse -are implemented in the later group-projection layer described below. +## Universal Markdown and MDX authoring -`projectLayout` filters the existing deterministic trace-wide fallback -geometry by a projection, retaining the stable positions, viewBox, directions, -cycles and self-loops across arbitrary seeking and selection. The React scene -uses this internal boundary without adding a package export, trace schema, -viewport control, or public selection API. Pan/zoom, automatic camera following and user-driven collapse are separate -presentation layers above projection. +A Markdown code node has exactly one recognized language: an **unqualified `thl` fence**. No `thl flow`, `thl matrix`, `thl binary`, `thl bindings` or `thl callstack` dispatch remains in the published interface. -## Optional spoken explanation +A body beginning with `{` is strict schema-2 JSON and validates offline without a manifest. Otherwise the body is inert descriptive intent: the host must supply a separately reviewed `VisualArtifact` with matching document-relative POSIX path, zero-based `thl` ordinal, normalized-LF intent SHA-256 and canonical artifact SHA-256. Invalid, missing, tampered or unreviewed sidecars fail closed. A malformed JSON-looking body is never reclassified as prose. -The React-only narration controller synthesizes authored caption text -(frame label, notes, guided chapter/causal content and explicit sends). -No new trace event or compiler schema is introduced. +`remarkThroughline` (`./remark`) consumes actual mdast `code` nodes in depth-first order. It validates all matching nodes before rewriting any. In `mode: "mdx"` it replaces them with inert `mdxJsxFlowElement` nodes containing **literal `artifactJson` attributes**, not executable expressions or imports. The host registers `ThroughlineEmbed` itself. Unrelated code blocks, math, Mermaid and other MDX elements remain host-owned. -While narration is enabled, speech completion drives playback ticks -instead of a fixed interval. Only the active utterance may advance -the selected trace; seeking (including to the same step) and changed -authored guidance invalidate stale callbacks. Pause/resume -controls the voice, and unavailable or failed synthesis pauses the -narration clock with an accessible error. When narration is disabled, -the existing timed playback returns. Step tones remain independent. +The standalone `thl` Node CLI reads the same code-node semantics using a non-evaluating Markdown/MDX syntax tree. `thl validate` checks a model file; `thl materialize` records exact intent/artifact digests as **unreviewed**; `thl check` validates every discovered `thl` node and requires a separately reviewed matching sidecar for prose. It cannot approve generated artifacts, execute source text or invoke an AI provider. -Browser speechSynthesis is a shared page resource. Throughline maintains a -per-engine, browser-local owner coordinator: the newest Throughline player -to begin narration takes over the global speech queue, pauses/disables the -previous player and announces displacement. Only the current owner may -call global `cancel()`, `pause()` or `resume()`; a displaced player's later -seek, toggle or unmount cannot cancel the new owner's speech. Deliberate -cancellation detaches event handlers before calling the browser API, while -unexpected `canceled`/`interrupted` errors trigger an accessible error -and pause rather than advancing the timeline. After a natural speech end, -ownership is released without global cancellation. This mechanism does not -coordinate with arbitrary third-party scripts using speechSynthesis and -cannot guarantee browser/OS voice isolation. Some voices may use -browser-managed remote services. +## Public package boundaries -## Responsive player shell - -`ThroughlinePlayer` composes one header, measured diagram, -transport and caption. The viewport owns camera and selection state and -supplies the diagram and its view controls. One native popover groups -chapter and step navigation, diagram controls, and display and audio options. -Container queries move viewport tools above the diagram in narrow embeds, -shorten the visual step count, and reflow transport controls as needed. -Fullscreen gives the SVG the flexible space between the header and the -playback and caption area. The SVG keeps the viewBox centered as Details opens. - -The transport displays the current step and total, and **Go to step** uses -the same reducer action as chapter navigation. The native details -disclosure follows the transport. The closed summary shows the step title -and note preview. The expanded body contains the full note, evidence and -inspector in a bounded scrolling area. The SVG references the caption -summary for descriptive accessibility. - -## Accumulated authored playback progress - -The internal React-only `traceProgress(trace, step)` selector scans compiled -active targets, explicit transfers and authored link-reveal events only -through the selected frame. It returns sets of participating nodes, -traversed relations and structurally revealed relations. Recomputing -from the selected frame on seeking makes rewind deterministic; memoization -by trace identity and timeline index avoids redundant work on resize. -No new trace field, compiler event, parser rule or external dependency -is introduced, and the compiler remains React-free. - -The player distinguishes **persistent participation**, **current focus -and value changes**, and **a current explicit send**. It animates the -actual directed SVG connector using a normalized path length and a -new element key for each send frame. Consecutive sends can reanimate. -There is no superimposed flow path. Only a forward single step carries -`animate`; the player latches that decision per step so unrelated renders -never restart or cancel it, and seeks and rewinds settle without replaying. -Animations are declared only under `prefers-reduced-motion: no-preference`; -an override cannot be relied on because the animated selectors are more -specific. Durations derive from `--thl-step-ms`, which the player sets from -the playback speed. - -Authored visibility always wins: hidden elements cannot be revived by -presentation progress. A collapsed aggregate remains dashed and reports -how many true constituent relation IDs have sent so far; it does not -animate as a single fabricated transfer. Authored `show link` is styled -as a structural reveal. Sending never claims destination acknowledgment, -processing or persistence, even if both endpoints are tinted as -participating entities. - -## Authored guidance and separate alternatives - -The React-only `ThroughlineGuidance` presentation contract is not serialized -into a trace or used by the compiler. Validation checks bounded chapter ranges, -real frame-event references and at least one authored state-changing event for -each causal explanation. Causal prose remains author-supplied and is not -deduced from temporal adjacency or `send` transfers. Current chapter and -explanation titles are included in the screen-reader status, with all details -and evidence in structured caption text. - -`ThroughlineScenarios` takes independent compiled traces with stable IDs -and remounts the selected player on option changes. Timeline, camera, -selection, chapter context, audio and inspector presentation reset without -mutating any frame; there is no native branching graph. Root and Remark -imports remain React-free; this API is optional and only on `./react`. -No `Program` or `Trace` fields, grammar or domain behaviors change. - -## Public module boundaries - -| Module | Responsibility | React required? | +| Import | Purpose | Dependencies | | --- | --- | --- | -| `@0xbuff/throughline` | Parsing, validation, compilation, tracer and types | No | -| `@0xbuff/throughline/remark` | Validate Markdown code nodes or emit literal MDX JSX nodes | No | -| `@0xbuff/throughline/react` | Accessible player, memoized source embed and optional sonification | Yes, React 19 peer | -| `@0xbuff/throughline/examples` | Public sample inputs | No | -| `@0xbuff/throughline/styles/throughline.css` | Namespaced player CSS | No | - -The Remark entry point inspects mdast code nodes, checks domain-only metadata, -compiles bounded parser-owned bodies and maps ProgramError line diagnostics -through the host VFile. Statement columns are verified against the -original Markdown when available, accounting for blockquote/list prefixes. -Diagnostics without precise source provenance remain file-level instead of -pointing at an unrelated fence header or Markdown container marker. The -default mode is validation-only and does not rewrite nodes. Opt-in -`mdx` mode validates all matching fences before atomically replacing their -code nodes with `mdxJsxFlowElement` nodes containing only a literal -`source` string attribute. Invalid component names and source fail rather -than being interpreted as expressions. The plugin imports no React/DOM, -and the MDX host must register the component in its mapping. A document -with many individual fences also needs host-level aggregate size limits. - -`ThroughlineEmbed` lives only in `./react`: `useMemo` compiles when its -literal source changes and passes a stable trace to `ThroughlinePlayer`. -SSR performs the same deterministic compilation as the browser, so this -bridge does not claim to eliminate client-side compilation. Untrusted -MDX documents may contain other executable expressions independent of -Throughline's literal-only transform. - -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. - -## Group hierarchy and projection - -Optional `SceneGroup.id`/`parentId` metadata forms a static tree of uniquely -identified groups. The authoring parser validates the graph before compilation, -including forward-declared parents, duplicate identities, unknown parents and -cycles. The historic flat layout remains unchanged when no parent references -exist; nested traces re-pack their deterministic trace-wide node boxes into -parent groups using the existing edge router. - -Collapse is presentation-only state in the React viewport and a pure option -in `projectScene`. The projection maps only authored-visible descendants to -a synthetic summary (which is not a real entity), deduplicates directed boundary -links while retaining each real relation ID, and leaves `send` annotations -separate from persistent `set` events. Original snapshots and values are -neither frozen nor mutated by the projection. Group drill-down changes only -camera and presentation state; replacing a trace resets group preferences. - -Hierarchy is an **additive** version-1 metadata extension, not a new domain or -public entry point. Older readers can flatten optional metadata but cannot -perform hierarchical collapse; old authoring parsers reject the new grammar. -Consumers should coordinate deployment of the new hierarchy grammar with -the installed compiler and player versions. - -## 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. +| `@0xbuff/throughline` | Schema-2 validation, compilation, indexed queries, canonical hashing and projection | Pure TypeScript/ESM; no Node IO, React, DOM or network | +| `@0xbuff/throughline/remark` | Read actual mdast nodes; validate or replace with literal MDX data | Host-provided Remark/MDX tree; no React | +| `@0xbuff/throughline/node` | Trusted content-root mapping, safe artifact loading and strict manifest parsing | Node 24+ filesystem; parser packages are confined to this entry | +| `@0xbuff/throughline/react` | `ThroughlineGraphPlayer` and `ThroughlineEmbed` | Optional React 19 peer | +| `@0xbuff/throughline/examples` | Four typed schema-2 mathematical/engineering references with questions and evidence | Pure core only | +| `@0xbuff/throughline/styles/throughline.css` | Explicitly imported, namespaced presentation styles | CSS | +| `thl` (executable) | Offline validation, unreviewed materialization, and build-time check | Node 24+; not imported from the pure root | -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). +The published API intentionally **does not** export `parseThl`, `compileProgram`, domain-specific tracers or `ThroughlinePlayer`. Historical version-1 source and tests, where still present during cleanup, are internal regression scaffolding only. They are neither a supported import nor a conversion layer. The npm package version is separate from `VisualArtifact.schemaVersion = 2`. -## Playback and accessibility +## Trust and failure boundaries -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. +The pure validator rejects unsupported shapes, unsafe values, conflicting writes, invalid references and resource-budget overruns. A source `message:sent` is not evidence of `received`, `processed`, `acknowledged` or a persistent write. An authored claim cites explicit evidence, and assumptions stay marked as assumptions. -Focus on the player group enables ArrowLeft/ArrowRight, Home/End and -Space without intercepting events from focused native buttons, step-number -input, speed selector or the details inspector. Current-frame -announcements use a screen-reader status and the scene has a textual -description. A distinct alert reports refused fullscreen requests; failures -do not disable in-page playback. An unrelated trace object resets step, -speed and playing state; the reducer and timer lifecycle keep playback state -separate from immutable frame data. +The Node host alone owns filesystem access. A trusted repository root determines allowed paths, while untrusted Markdown cannot choose a loader or root. The host verifies relative POSIX locators, rejects symlink traversal and reads files with bounded UTF-8 decoding. Materialized sidecar entries cannot be approved by the generating command; reviewed digests are verified again at check/build time. Diagnostics use stable codes and locations when available without reflecting host exception secrets. Markdown/MDX syntax parsing does not execute embedded JavaScript, JSX, HTML or prose. -The measured diagram container stays mounted across empty/filled trace replacements -so ResizeObserver can keep the SVG responsive. The scoped CSS disables -transfer animations for reduced-motion users, and controls reflow for a -narrow player container. Existing packed-consumer checks exercise React 19 SSR and -client hydration, while browser tests cover keyboard, inspector, fullscreen, -reduced-motion styles and replacement regressions. +React is optional. Player seeking selects immutable compiled frames; switching layouts, collapsing groups, viewport navigation, playback and optional narration cannot change compiled truth. Controls preserve keyboard, reduced-motion and accessible-status behavior. Browser speech synthesis may be provided by the user's browser/OS; it is never a core inference or artifact-authoring service. SSR and hydration must agree on their initial markup; browser-only capability detection happens after mount. -Sonification is explicitly opted into by the caller and is not -triggered merely by importing the package. A provided `sonification` -option is required to display sound controls. A running oscillator is -stopped and disconnected at most once when playback changes or when the -trace object is replaced, including with an equal-length trace. Sound is -not restarted by rerendering the same trace object. An already-ended -voice does not break cleanup. Neither playback nor -compilation records grades or authenticates learners. +## Repository ownership and verification -## Build and trust boundaries +- `src/v2/` owns validation, replay, source-linked queries, projection, authoring and hash contracts. +- `src/remark/` owns the host-neutral mdast transform; `src/node/` owns Node-only safe file loading and CLI syntax-tree discovery; `src/cli/` owns command argument, diagnostic and review behavior. +- `src/react/` owns the native player and inert-data embedding; `src/reference/` and `src/examples.ts` own public reference evidence; `src/styles/` owns presentation tokens. +- `src/domains/` and other older files may remain only for non-public historical regression tests until their separately reviewed cleanup. +- `scripts/` tests package exports, compiler integrity, real Node/MDX/React consumers, SSR/hydration, framework integrations, boundaries and licenses. A source-only unit test does not establish published runtime behavior. -`tsdown` produces ESM, declarations and JavaScript source maps for -the four 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. +The npm archive must be checked from an **independent installation**, including its `thl` binary, Node-only consumer without React, optional Remark integration, React SSR/hydration and representative MDX hosts. No successful CI check authorizes publication: signed releases, staged package verification and documentation rollout remain separate maintainer-approved actions. -Tests and package audits verify specific technical contracts; they do not -replace source-rights, provenance or release authorization reviews. +See [schema-2 semantic contract](schema-v2.md), [one-fence grammar](grammar.md), [CLI and human review](cli.md), [framework integration](framework-integrations.md), [reference explanations](reference-traces.md) and [release procedure](releasing.md). diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 00000000..e0be4c32 --- /dev/null +++ b/docs/cli.md @@ -0,0 +1,145 @@ +# Offline authoring and validation CLI (TL-U10) + +The first-party `thl` binary is a **Node.js 24+** build tool. It +validates and materializes schema-2 models, without calling an AI provider, +running Markdown/MDX as code, importing React or accessing the network. +The candidate CLI is currently unreleased source. Use it only from a +reviewed checkout or after its package version has been published. + +## Commands + +~~~sh +# Validate one strict VisualArtifact JSON file and its replay semantics: +thl validate artifacts/counter.json + +# Record a prose fence's source digest and artifact digest: +thl materialize \ + --document content/docs/counter.mdx \ + --ordinal 0 \ + --artifact artifacts/counter.json \ + --manifest throughline/manifest.json + +# Check direct-JSON and reviewed-prose fences in a document or directory: +thl check content/docs --manifest throughline/manifest.json +# Direct-JSON-only content needs no --manifest: +thl check content/docs/inline-only.mdx +~~~ + +Use `--root /trusted/repository` with any command to select an +explicit trusted repository root. If omitted, the CLI's current working +directory is the root. **All document, artifact and manifest paths are +repository-relative POSIX paths**: no absolute paths, traversal, empty +segments, percent-encoded aliases or backslashes. The directory target +`.` means the root itself. + +### What materialize does + +The CLI locates the requested prose `thl` Markdown/MDX code node by +its zero-based ordinal, **counting only `thl` code nodes** in the +document. It normalizes the code-node body from CRLF/CR to LF without +trimming other content, then computes: + +- `intentSha256`: SHA-256 over UTF-8 bytes of that exact normalized body. +- `artifactSha256`: SHA-256 over canonical validated and fully compiled + schema-2 artifact JSON (independent of source JSON formatting). + +The operation creates or replaces one ordered, duplicate-free version-1 +manifest entry with `"review": "unreviewed"` **every time**. Even +re-materializing an unchanged, previously reviewed model resets review. +It can never generate an approved entry, edit the authored document or +silently invoke a provider. + +Example generated manifest: + +~~~json +{ + "version": 1, + "entries": [ + { + "document": "content/docs/counter.mdx", + "ordinal": 0, + "intentSha256": "<64 lowercase hex>", + "artifactPath": "artifacts/counter.json", + "artifactSha256": "<64 lowercase hex>", + "review": "unreviewed" + } + ] +} +~~~ + +### Separate human approval + +A maintainer must compare the actual model to its prompt, verify facts, +scope and provenance, and review the JSON artifact, hash and intended +document. **Only then**, in a distinct source-control change, set +`review` from `unreviewed` to `reviewed` and submit the manifest +for peer review. There is deliberately **no `thl approve` command**. + +The published-build `thl check` refuses unreviewed entries, stale +source digests, altered artifact digests, unsupported manifest shapes, +duplicate locators and unsafe paths. Direct strict JSON fences require +no sidecar, review entry or provider. An opening brace selects JSON +unconditionally; malformed JSON cannot silently become prose. + +### What check does + +The CLI walks `.md` and `.mdx` files in deterministic path order, +parses a **non-evaluating CommonMark/MDX syntax tree** (Remark with +MDX syntax enabled for `.mdx` documents), then validates each actual +`thl` code node in depth-first order. This includes fences under nested +list items, blockquotes and JSX containers. Strings resembling `~~~thl` +inside HTML comments, JavaScript code, MDX expressions or JSX attributes +are not code nodes and never acquire ordinals. Unrelated JavaScript, +math and Mermaid remain ordinary Markdown. Unqualified fences alone are accepted; domain +metadata such as `thl flow` fails. Each success reports its document, +one-based source line and column and zero-based `thl` ordinal; +the final summary reports documents and validated blocks. + +The check command fails closed with a nonzero exit for invalid, missing +or unreviewed materializations, invalid JSON, model semantics, unsafe +filesystem paths and IO errors. It emits stable `THL_*` error codes +(e.g. `THL_UNREVIEWED`, `THL_DIGEST`, `THL_PATH`, +`THL_ARTIFACT_SYNTAX`, `THL_ARTIFACT_REFERENCE`, +`THL_ARTIFACT_CONFLICT`, `THL_ARTIFACT_LIMIT`). +The origin/line/ordinal appear when genuinely known; the checker does +not print private host loader exception details. + +### Host filesystem security + +Node reads are scoped to a real trusted content root, use bounded UTF-8 +decoding, disallow symbolic-link traversal in both directories and +files, reject unsafe relative locators and write manifests via +exclusive temporary files and atomic rename. The host configuration +defines the root; Markdown cannot choose it or a loader callback. + +The separate Node entry point makes the same boundary available for +real Remark/MDX hosts: + +~~~ts +import { createNodeThroughlineHost } from "@0xbuff/throughline/node"; +import { remarkThroughline } from "@0xbuff/throughline/remark"; + +const host = createNodeThroughlineHost({ + root: "/absolute/trusted/repository", + manifestPath: "throughline/manifest.json", +}); +const throughlinePlugin = [remarkThroughline, { mode: "mdx", ...host }]; +~~~ + +For documents containing only inline schema-2 JSON, omit +`manifestPath` and use the same host. The host's real VFile paths +are mapped to reviewed repository-relative document locators. The +Remark adapter still consumes actual mdast nodes and emits only inert +literal `artifactJson` for the separately registered React component. + +See [framework integrations](framework-integrations.md), +[semantic model](schema-v2.md) and the +[reference truth suite](../src/__tests__/examples.test.ts). + +## Release boundaries + +The CLI/Node host source does not publish a package or authorize +deployment. The package release belongs to TL-U19. The live +documentation-app upgrade belongs to TL-U20 and must use a verified +published version. The proposed first schema-2 package is 0.2.0, +pending separate availability and release approval. diff --git a/docs/framework-integrations.md b/docs/framework-integrations.md index aeef9a89..6f1a858f 100644 --- a/docs/framework-integrations.md +++ b/docs/framework-integrations.md @@ -1,6 +1,6 @@ # Framework integrations -This guide covers the **unreleased TL-U08 schema-2 source**. Verify the +This guide covers the **unreleased TL-U10 schema-2 source**. Verify the installed npm version before using it. The older v0.1.0 published package has a different Markdown contract and does not receive a compatibility layer. @@ -90,8 +90,10 @@ A wrong source hash, mismatched canonical artifact hash, missing entry or unreviewed entry always fails closed. A trusted loader throwing an error produces the stable `THL_LOADER` diagnostic; arbitrary host exception messages and private loader paths are never included in the user-facing error. The -creation/check CLI and filesystem integration are scheduled separately under -TL-U10. +standalone `thl` CLI and a confined Node filesystem host are now +implemented in TL-U10 source, pending the package's separate publication. +See the [CLI guide](cli.md) for validated materialization, editorial review, +strict check mode and source-hash diagnostics. ## Remark and MDX @@ -102,35 +104,25 @@ position where known. It verifies the complete document before any MDX mutation. ~~~ts import { remarkThroughline } from "@0xbuff/throughline/remark"; -import { relative, isAbsolute, sep } from "node:path"; - -// This is host build tooling, not imported by the pure Throughline engine. -// Choose the trusted repository root that defines manifest document paths. -const repositoryRoot = "/trusted/repository/root"; -function documentForFile(absoluteFilePath: string): string { - const path = relative(repositoryRoot, absoluteFilePath); - if (!path || path === ".." || path.startsWith(".." + sep) || isAbsolute(path)) { - throw new Error("VFile path is outside the configured repository root"); - } - return path.split(sep).join("/"); -} +import { createNodeThroughlineHost } from "@0xbuff/throughline/node"; -const plugin = [remarkThroughline, { - mode: "mdx", - documentForFile, // maps every VFile path to the exact sidecar document key - manifest, // reviewed, host-loaded manifest - loadArtifact, // trusted, content-root-confined synchronous loader -}]; -// For one specific file, document: "content/docs/checkout.mdx" may replace -// documentForFile. Inline JSON needs neither loader nor document mapping. +// This Node-only host config owns the trusted root, blocks symlink escapes, +// and validates the exact manifest schema. No Markdown input can choose paths. +const host = createNodeThroughlineHost({ + root: "/absolute/trusted/repository", + manifestPath: "throughline/manifest.json", +}); +const plugin = [remarkThroughline, { mode: "mdx", ...host }]; +// For a project containing only direct JSON fences, omit manifestPath. ~~~ Remark receives the host's real VFile. Its path is commonly absolute, while sidecar document keys must remain repository-relative POSIX paths. Do **not** remove an assumed prefix, use the system working directory implicitly, or -loosen the path validator. A trusted host config either supplies an explicit -relative `document` for a single file, uses a validated already-relative VFile -path, or supplies `documentForFile` for a multi-document build. Missing or +loosen the path validator. The bundled Node host config supplies a strictly confined `documentForFile` +callback for multi-document builds. An advanced host may instead supply an +explicit relative `document` for one file or a validated already-relative +VFile path. Missing or unsafe mappings fail with `THL_PATH` and the known fence line/ordinal without printing a private absolute path. The callback must be provided by the trusted host, not by authored Markdown, and must not follow untrusted symlink paths. diff --git a/docs/releasing.md b/docs/releasing.md index cacdf073..d92c0092 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -14,6 +14,7 @@ release suite on the exact reviewed revision: pnpm install --frozen-lockfile pnpm audit:source pnpm typecheck +pnpm test:cli pnpm preview:typecheck pnpm preview:build pnpm test:run @@ -45,8 +46,8 @@ requirements. These checks are not replaced by mocked or fixture-only tests. changelog. Review the public history for any sensitive references. Historical exposure cannot be undone by deleting current-tree files. 2. Update the version in `package.json` and document the changes in - `CHANGELOG.md`. Maintain the five public package exports and keep - `Program.version` / `Trace.version` independent of npm SemVer. + `CHANGELOG.md`. Maintain the six public package exports and the separate `thl` binary; + schema-2 `VisualArtifact.schemaVersion` is independent of npm SemVer. 3. Run the source, TypeScript, preview, Chromium/Firefox/WebKit browser, build, license and packed consumer checks listed above. Record the exact candidate SHA, CI runs and applicable manual review. @@ -54,22 +55,22 @@ requirements. These checks are not replaced by mocked or fixture-only tests. ensure main CI is green. 4. From a clean checkout with a signing key registered with GitHub, create and push an immutable signed tag **only after** the release commit is - merged. For version `0.1.0`: + merged. For the proposed schema-2 version `0.2.0` (only if approved): ~~~sh git switch main git pull --ff-only - git tag -s v0.1.0 -m "Throughline v0.1.0" - git tag -v v0.1.0 - git push origin v0.1.0 + git tag -s v0.2.0 -m "Throughline v0.2.0" + git tag -v v0.2.0 + git push origin v0.2.0 ~~~ GitHub must show the tag as **Verified**. Protect `v*` tag updates and deletions. Do not move or reuse existing release tags. 5. In [GitHub Actions](https://github.com/0xbuffdev/throughline/actions), run **Throughline npm release (staged with provenance)** from `main`. - Enter the exact signed tag (e.g. `v0.1.0`) and confirmation - `STAGE-v0.1.0`. The read-only verification job checks the signed tag, + Enter the exact signed tag (e.g. `v0.2.0`) and confirmation + `STAGE-v0.2.0`. The read-only verification job checks the signed tag, manifest, build, tests, packed consumers and archive SHA-256. 6. Inspect the GitHub release artifact and approve the protected `npm-publish` environment job. Its **stage-only** Trusted Publisher @@ -100,7 +101,7 @@ requirements. These checks are not replaced by mocked or fixture-only tests. ~~~sh npm view @0xbuff/throughline version npm view @0xbuff/throughline dist-tags - npm view @0xbuff/throughline@0.1.0 version + npm view @0xbuff/throughline@0.2.0 version ~~~ Check [npm's package page](https://www.npmjs.com/package/@0xbuff/throughline) diff --git a/package.json b/package.json index 1d79b96f..2b6477f1 100644 --- a/package.json +++ b/package.json @@ -33,6 +33,10 @@ "types": "./dist/examples.d.ts", "default": "./dist/examples.js" }, + "./node": { + "types": "./dist/node/index.d.ts", + "default": "./dist/node/index.js" + }, "./styles/throughline.css": "./src/styles/throughline.css" }, "scripts": { @@ -48,7 +52,8 @@ "audit:browser": "node scripts/audit-browser.mjs", "audit:licenses": "node scripts/audit-licenses.mjs", "audit:frameworks": "node scripts/audit-frameworks.mjs", - "audit:markdown-hosts": "node scripts/audit-markdown-hosts.mjs" + "audit:markdown-hosts": "node scripts/audit-markdown-hosts.mjs", + "test:cli": "vitest run src/__tests__/cli.test.ts" }, "files": [ "dist", @@ -62,7 +67,10 @@ "**/*.css" ], "dependencies": { - "cn": "^0.4.0" + "cn": "^0.4.0", + "remark-mdx": "3.1.1", + "remark-parse": "11.0.0", + "unified": "11.0.5" }, "peerDependencies": { "react": "^19.2.7", @@ -102,5 +110,8 @@ "react", "developer-tools", "education" - ] + ], + "bin": { + "thl": "./dist/cli/main.js" + } } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 5330b57e..701c01b8 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -11,6 +11,15 @@ importers: cn: specifier: ^0.4.0 version: 0.4.0 + remark-mdx: + specifier: 3.1.1 + version: 3.1.1 + remark-parse: + specifier: 11.0.0 + version: 11.0.0 + unified: + specifier: 11.0.5 + version: 11.0.5 devDependencies: '@playwright/test': specifier: ^1.61.0 @@ -299,12 +308,27 @@ packages: '@types/chai@5.2.3': resolution: {integrity: sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==} + '@types/debug@4.1.13': + resolution: {integrity: sha512-KSVgmQmzMwPlmtljOomayoR89W4FynCAi3E8PPs7vmDVPe84hT+vGPKkJfThkmXs0x0jAaa9U8uW8bbfyS2fWw==} + '@types/deep-eql@4.0.2': resolution: {integrity: sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==} + '@types/estree-jsx@1.0.5': + resolution: {integrity: sha512-52CcUVNFyfb1A2ALocQw/Dd1BQFNmSdkuC3BkZ6iqhdMfQz7JWOFRuJFloOzjk+6WijU56m9oKXFAXc7o3Towg==} + '@types/estree@1.0.10': resolution: {integrity: sha512-lTyOMnOcmRBzdCv6/4zUZCrEhV0xrqQiUZBZtVcbmLHBXKLnN8q89v/wKRF/Q0HbwVsqbIG3o5HDoFl9sduM+g==} + '@types/hast@3.0.5': + resolution: {integrity: sha512-rp/ezSWaD1m44dPKICGhiskI13nVr7qTloFwDa/IYkhhf5nzwP+zIQcIJh3WIFSBOy/H1PzB40jPjMDksN4F+g==} + + '@types/mdast@4.0.4': + resolution: {integrity: sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA==} + + '@types/ms@2.1.0': + resolution: {integrity: sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==} + '@types/node@24.19.2': resolution: {integrity: sha512-93d49wCWJkCyN87MxLpNN6KXPCwFw7bVUg79mGUV1OS40JGWwVCr8n61DXCSqz7CV6/VfPkb7xec7uP2M+QHWQ==} @@ -316,6 +340,12 @@ packages: '@types/react@19.3.0': resolution: {integrity: sha512-N0rFCuH9YoxG9/m61l9MfpJKfmLOVU0em7ipIz6TRgSSkvReLB9vL85GB+yr8Bs5leqpvg96JSwF4ZS1s4viQg==} + '@types/unist@2.0.11': + resolution: {integrity: sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==} + + '@types/unist@3.0.3': + resolution: {integrity: sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==} + '@vitest/browser-playwright@4.1.12': resolution: {integrity: sha512-bU/TcyiBwFUijaIltxKXxgpQmLu9njO/t6G9wiD2LjSFX6SfmyUOf+pOJ8N26KsvhFOHWfVdzNS6P62ab/ONlA==} peerDependencies: @@ -386,18 +416,46 @@ packages: cpu: [x64] os: [win32] + acorn-jsx@5.3.2: + resolution: {integrity: sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==} + peerDependencies: + acorn: ^6.0.0 || ^7.0.0 || ^8.0.0 + + acorn@8.19.0: + resolution: {integrity: sha512-oJlA3XiRm7Cyk6qFD2Jn8ak9B7jSy0qy00ADO3+8dpT0LSjFihQYv4C02LFCSYJV3Q37xYwwRy5m+IpIiUzqWw==} + engines: {node: '>=0.4.0'} + hasBin: true + assertion-error@2.0.1: resolution: {integrity: sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==} engines: {node: '>=12'} + bail@2.0.2: + resolution: {integrity: sha512-0xO6mYd7JB2YesxDKplafRpsiOzPt9V02ddPCLbY1xYGPOX24NTyN50qnUxgCPcSoYMhKpAuBTjQoRZCAkUDRw==} + cac@7.1.0: resolution: {integrity: sha512-LMDU/U2yA4IPIY8KT0NsNPWEYZvAMkbgyspxJ6btJaYV+WMDOHAZCmB0lsTObiHaRS1V/ztKAl7+TSkTqXyeoA==} engines: {node: '>=20.19.0'} + ccount@2.0.1: + resolution: {integrity: sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==} + chai@6.3.0: resolution: {integrity: sha512-XWAtwJ6OHO+tj0EKCs0Y2UamnyOxseZWltU4x2U2wh8g4AigdjwvtUjvLP2tqkA/avxHEtzxNaqGq/YGNwckKg==} engines: {node: '>=18'} + character-entities-html4@2.1.0: + resolution: {integrity: sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA==} + + character-entities-legacy@3.0.0: + resolution: {integrity: sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ==} + + character-entities@2.0.2: + resolution: {integrity: sha512-shx7oQ0Awen/BRIdkjkvz54PnEEI/EjwXDSIZp86/KKdbafHh1Df/RYGBhn4hbe2+uKC9FnT5UCEdyPz3ai9hQ==} + + character-reference-invalid@2.0.1: + resolution: {integrity: sha512-iBZ4F4wRbyORVsu0jPV7gXkOsGYjGHPmAyv+HiHG8gi5PtC9KI2j1+v8/tlibRvjoWX027ypmG/n0HtO5t7unw==} + cn@0.4.0: resolution: {integrity: sha512-qOAeUhPwPzBxx6jaeQdo646XIKliKHc2j1ZF7Ngb1o0pJZKH5gq8FkA0aVdUdPFUDXNXyUCXpCtoJISo6dhizg==} engines: {node: '>=20'} @@ -409,13 +467,32 @@ packages: csstype@3.2.3: resolution: {integrity: sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==} + debug@4.4.3: + resolution: {integrity: sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==} + engines: {node: '>=6.0'} + peerDependencies: + supports-color: '*' + peerDependenciesMeta: + supports-color: + optional: true + + decode-named-character-reference@1.3.0: + resolution: {integrity: sha512-GtpQYB283KrPp6nRw50q3U9/VfOutZOe103qlN7BPP6Ad27xYnOIWv4lPzo8HCAL+mMZofJ9KEy30fq6MfaK6Q==} + defu@6.1.7: resolution: {integrity: sha512-7z22QmUWiQ/2d0KkdYmANbRUVABpZ9SNYyH5vx6PZ+nE5bcC0l7uFvEfHlyld/HcGBFTL536ClDt3DEcSlEJAQ==} + dequal@2.0.3: + resolution: {integrity: sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==} + engines: {node: '>=6'} + detect-libc@2.1.2: resolution: {integrity: sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==} engines: {node: '>=8'} + devlop@1.1.0: + resolution: {integrity: sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==} + dts-resolver@3.0.0: resolution: {integrity: sha512-1T1f+z+4tl9XD+m+0HBgWoL/nm0bOIffyWaUuUSBlFg/86IWvfx+wjNaO/ybU0AJzG9/Mi5hBUgGV6zCmWEN7Q==} engines: {node: ^22.18.0 || >=24.0.0} @@ -432,6 +509,12 @@ packages: es-module-lexer@2.3.2: resolution: {integrity: sha512-poHGpORABojJJucnV9KbOavETW8lBVnphkW77ER5/BQ5Fz7oXSoCNek7IH3vR5nRjdsEz926ibFYX8KtLQmdyw==} + estree-util-is-identifier-name@3.0.0: + resolution: {integrity: sha512-hFtqIDZTIUZ9BXLb8y4pYGyk6+wekIivNVTcmvk8NoOh+VeRn5y6cEHzbURrWbfp1fIqdVipilzj+lfaadNZmg==} + + estree-util-visit@2.0.0: + resolution: {integrity: sha512-m5KgiH85xAhhW8Wta0vShLcUvOsh3LLPI2YVwcbio1l7E09NTLL1EyMZFM1OyWowoH0skScNbhOPl4kcBgzTww==} + estree-walker@3.0.3: resolution: {integrity: sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==} @@ -439,6 +522,9 @@ packages: resolution: {integrity: sha512-KfYbmpRm0VbLjEvVa9yGwCi9GI34xvi7A/HXYWQO65CSD2u3MczUJSuwXKFIxlGsgBQizV9q5J9NHj4VG0n+pA==} engines: {node: '>=12.0.0'} + extend@3.0.2: + resolution: {integrity: sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==} + fdir@6.5.0: resolution: {integrity: sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==} engines: {node: '>=12.0.0'} @@ -464,6 +550,22 @@ packages: resolution: {integrity: sha512-vXoV9PjKHEednCUu01e98TkImxy67e3BJXbTIOmIq4Hyzw3IAwYRcuPkfeTzJzwyyts4kjuA73x+pWJLc4f86A==} engines: {node: ^22.18.0 || >=24.0.0} + is-alphabetical@2.0.1: + resolution: {integrity: sha512-FWyyY60MeTNyeSRpkM2Iry0G9hpr7/9kD40mD/cGQEuilcZYS4okz8SN2Q6rLCJ8gbCt6fN+rC+6tMGS99LaxQ==} + + is-alphanumerical@2.0.1: + resolution: {integrity: sha512-hmbYhX/9MUMF5uh7tOXyK/n0ZvWpad5caBA17GsC6vyuCqaWliRG5K1qS9inmUhEMaOBIW7/whAnSwveW/LtZw==} + + is-decimal@2.0.1: + resolution: {integrity: sha512-AAB9hiomQs5DXWcRB1rqsxGUstbRroFOPPVAomNk/3XHR5JyEZChOyTWe2oayKnsSsr/kcGqF+z6yuH6HHpN0A==} + + is-hexadecimal@2.0.1: + resolution: {integrity: sha512-DgZQp241c8oO6cA1SbTEWiXeoxV42vlcJxgH+B3hi1AiqqKruZR3ZGF8In3fj4+/y/7rHvlOZLZtgJ/4ttYGZg==} + + is-plain-obj@4.1.0: + resolution: {integrity: sha512-+Pgi+vMuUNkJyExiMBt5IlFoMyKnr5zhJ4Uspz58WOhBF5QoIZkFyNHIbBAtHwzVAgk5RtndVNsDRN61/mmDqg==} + engines: {node: '>=12'} + lightningcss-android-arm64@1.33.0: resolution: {integrity: sha512-gEpRTalKdosp4Bb8qWtc2iOgE5SeIHlpS1up9bFq2wAyYhl1UdTObYiHe98zEM9SQvSoqQZ1IQD0JNpg3Ml5pg==} engines: {node: '>= 12.0.0'} @@ -538,13 +640,130 @@ packages: resolution: {integrity: sha512-WkUDrojuJs0xkgGf2udWxa3yGBRxPtxUkB79i6aCZLRgc7PM8fZe9TosfPDcvEpQZbuFASnHYmRLBLUbmLOIIA==} engines: {node: '>= 12.0.0'} + longest-streak@3.1.0: + resolution: {integrity: sha512-9Ri+o0JYgehTaVBBDoMqIl8GXtbWg711O3srftcHhZ0dqnETqLaoIK0x17fUw9rFSlK/0NlsKe0Ahhyl5pXE2g==} + magic-string@0.30.21: resolution: {integrity: sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==} + mdast-util-from-markdown@2.1.0: + resolution: {integrity: sha512-KRLgmPaP2H1ul2bpoJkOS+9pAcDAAj9Nu1mqLnh8NLeJG5tlvj42TH80PIGBpROWlRXLk0lDrWNuZCFy/tsB4A==} + + mdast-util-mdx-expression@2.0.1: + resolution: {integrity: sha512-J6f+9hUp+ldTZqKRSg7Vw5V6MqjATc+3E4gf3CFNcuZNWD8XdyI6zQ8GqH7f8169MM6P7hMBRDVGnn7oHB9kXQ==} + + mdast-util-mdx-jsx@3.2.1: + resolution: {integrity: sha512-oXp1GIa+E9IwIs3a106+tr3Bz2MlTTBvlXjOZMoIat11kk7vjqgmBnksB9WHmWv+gZh7k3IUgpAHlwHB7DH4GQ==} + + mdast-util-mdx@3.0.0: + resolution: {integrity: sha512-JfbYLAW7XnYTTbUsmpu0kdBUVe+yKVJZBItEjwyYJiDJuZ9w4eeaqks4HQO+R7objWgS2ymV60GYpI14Ug554w==} + + mdast-util-mdxjs-esm@2.0.1: + resolution: {integrity: sha512-EcmOpxsZ96CvlP03NghtH1EsLtr0n9Tm4lPUJUBccV9RwUOneqSycg19n5HGzCf+10LozMRSObtVr3ee1WoHtg==} + + mdast-util-phrasing@4.1.0: + resolution: {integrity: sha512-TqICwyvJJpBwvGAMZjj4J2n0X8QWp21b9l0o7eXyVJ25YNWYbJDVIyD1bZXE6WtV6RmKJVYmQAKWa0zWOABz2w==} + + mdast-util-to-markdown@2.2.3: + resolution: {integrity: sha512-dImdB6VZRMRac1SwAW6o1c0ESk/7pFFAMCMuKM+9v7LpTSthMM5nzXpqKw4Mjo66aXVKhNkyrP4bMB9MurPyWg==} + + mdast-util-to-string@4.0.0: + resolution: {integrity: sha512-0H44vDimn51F0YwvxSJSm0eCDOJTRlmN0R1yBh4HLj9wiV1Dn0QoXGbvFAWj2hSItVTlCmBF1hqKlIyUBVFLPg==} + + micromark-core-commonmark@2.0.4: + resolution: {integrity: sha512-wxEeE8v8XVvOrxn1TZj74qYhAtTQsSqufHVS3uNVyT1MupXxhyaHk8/9xDNPh9BmL77QNDgWTkZ3RsYHB2ry7w==} + + micromark-extension-mdx-expression@3.0.1: + resolution: {integrity: sha512-dD/ADLJ1AeMvSAKBwO22zG22N4ybhe7kFIZ3LsDI0GlsNr2A3KYxb0LdC1u5rj4Nw+CHKY0RVdnHX8vj8ejm4Q==} + + micromark-extension-mdx-jsx@3.0.2: + resolution: {integrity: sha512-e5+q1DjMh62LZAJOnDraSSbDMvGJ8x3cbjygy2qFEi7HCeUT4BDKCvMozPozcD6WmOt6sVvYDNBKhFSz3kjOVQ==} + + micromark-extension-mdx-md@2.0.0: + resolution: {integrity: sha512-EpAiszsB3blw4Rpba7xTOUptcFeBFi+6PY8VnJ2hhimH+vCQDirWgsMpz7w1XcZE7LVrSAUGb9VJpG9ghlYvYQ==} + + micromark-extension-mdxjs-esm@3.0.0: + resolution: {integrity: sha512-DJFl4ZqkErRpq/dAPyeWp15tGrcrrJho1hKK5uBS70BCtfrIFg81sqcTVu3Ta+KD1Tk5vAtBNElWxtAa+m8K9A==} + + micromark-extension-mdxjs@3.0.0: + resolution: {integrity: sha512-A873fJfhnJ2siZyUrJ31l34Uqwy4xIFmvPY1oj+Ean5PHcPBYzEsvqvWGaWcfEIr11O5Dlw3p2y0tZWpKHDejQ==} + + micromark-factory-destination@2.0.1: + resolution: {integrity: sha512-Xe6rDdJlkmbFRExpTOmRj9N3MaWmbAgdpSrBQvCFqhezUn4AHqJHbaEnfbVYYiexVSs//tqOdY/DxhjdCiJnIA==} + + micromark-factory-label@2.0.1: + resolution: {integrity: sha512-VFMekyQExqIW7xIChcXn4ok29YE3rnuyveW3wZQWWqF4Nv9Wk5rgJ99KzPvHjkmPXF93FXIbBp6YdW3t71/7Vg==} + + micromark-factory-mdx-expression@2.0.3: + resolution: {integrity: sha512-kQnEtA3vzucU2BkrIa8/VaSAsP+EJ3CKOvhMuJgOEGg9KDC6OAY6nSnNDVRiVNRqj7Y4SlSzcStaH/5jge8JdQ==} + + micromark-factory-space@2.1.0: + resolution: {integrity: sha512-fS8hnLIjnjvdQIj39Geug8wWsR0HrYZ43KShKxNfwT7t2LOHo/LbWZEzEaSOjwtjdCsjoE6syHhonEzW0zv0+Q==} + + micromark-factory-title@2.0.1: + resolution: {integrity: sha512-5bZ+3CjhAd9eChYTHsjy6TGxpOFSKgKKJPJxr293jTbfry2KDoWkhBb6TcPVB4NmzaPhMs1Frm9AZH7OD4Cjzw==} + + micromark-factory-whitespace@2.0.1: + resolution: {integrity: sha512-Ob0nuZ3PKt/n0hORHyvoD9uZhr+Za8sFoP+OnMcnWK5lngSzALgQYKMr9RJVOWLqQYuyn6ulqGWSXdwf6F80lQ==} + + micromark-util-character@2.1.1: + resolution: {integrity: sha512-wv8tdUTJ3thSFFFJKtpYKOYiGP2+v96Hvk4Tu8KpCAsTMs6yi+nVmGh1syvSCsaxz45J6Jbw+9DD6g97+NV67Q==} + + micromark-util-chunked@2.0.1: + resolution: {integrity: sha512-QUNFEOPELfmvv+4xiNg2sRYeS/P84pTW0TCgP5zc9FpXetHY0ab7SxKyAQCNCc1eK0459uoLI1y5oO5Vc1dbhA==} + + micromark-util-classify-character@2.0.1: + resolution: {integrity: sha512-K0kHzM6afW/MbeWYWLjoHQv1sgg2Q9EccHEDzSkxiP/EaagNzCm7T/WMKZ3rjMbvIpvBiZgwR3dKMygtA4mG1Q==} + + micromark-util-combine-extensions@2.0.1: + resolution: {integrity: sha512-OnAnH8Ujmy59JcyZw8JSbK9cGpdVY44NKgSM7E9Eh7DiLS2E9RNQf0dONaGDzEG9yjEl5hcqeIsj4hfRkLH/Bg==} + + micromark-util-decode-numeric-character-reference@2.0.2: + resolution: {integrity: sha512-ccUbYk6CwVdkmCQMyr64dXz42EfHGkPQlBj5p7YVGzq8I7CtjXZJrubAYezf7Rp+bjPseiROqe7G6foFd+lEuw==} + + micromark-util-decode-string@2.0.1: + resolution: {integrity: sha512-nDV/77Fj6eH1ynwscYTOsbK7rR//Uj0bZXBwJZRfaLEJ1iGBR6kIfNmlNqaqJf649EP0F3NWNdeJi03elllNUQ==} + + micromark-util-edit-map@1.0.0: + resolution: {integrity: sha512-Pa2ljlsEL6sVwFaYeyrOLSYbQt73JvGbPOYFq+9AElXiSnfI5Q4465RRZ1sHv7lDjDOnGRDDaqPXqClqWK/q1Q==} + + micromark-util-encode@2.0.1: + resolution: {integrity: sha512-c3cVx2y4KqUnwopcO9b/SCdo2O67LwJJ/UyqGfbigahfegL9myoEFoDYZgkT7f36T0bLrM9hZTAaAyH+PCAXjw==} + + micromark-util-events-to-acorn@2.0.3: + resolution: {integrity: sha512-jmsiEIiZ1n7X1Rr5k8wVExBQCg5jy4UXVADItHmNk1zkwEVhBuIUKRu3fqv+hs4nxLISi2DQGlqIOGiFxgbfHg==} + + micromark-util-html-tag-name@2.0.1: + resolution: {integrity: sha512-2cNEiYDhCWKI+Gs9T0Tiysk136SnR13hhO8yW6BGNyhOC4qYFnwF1nKfD3HFAIXA5c45RrIG1ub11GiXeYd1xA==} + + micromark-util-normalize-identifier@2.0.1: + resolution: {integrity: sha512-sxPqmo70LyARJs0w2UclACPUUEqltCkJ6PhKdMIDuJ3gSf/Q+/GIe3WKl0Ijb/GyH9lOpUkRAO2wp0GVkLvS9Q==} + + micromark-util-resolve-all@2.0.1: + resolution: {integrity: sha512-VdQyxFWFT2/FGJgwQnJYbe1jjQoNTS4RjglmSjTUlpUMa95Htx9NHeYW4rGDJzbjvCsl9eLjMQwGeElsqmzcHg==} + + micromark-util-sanitize-uri@2.0.1: + resolution: {integrity: sha512-9N9IomZ/YuGGZZmQec1MbgxtlgougxTodVwDzzEouPKo3qFWvymFHWcnDi2vzV1ff6kas9ucW+o3yzJK9YB1AQ==} + + micromark-util-subtokenize@2.1.0: + resolution: {integrity: sha512-XQLu552iSctvnEcgXw6+Sx75GflAPNED1qx7eBJ+wydBb2KCbRZe+NwvIEEMM83uml1+2WSXpBAcp9IUCgCYWA==} + + micromark-util-symbol@2.0.1: + resolution: {integrity: sha512-vs5t8Apaud9N28kgCrRUdEed4UJ+wWNvicHLPxCa9ENlYuAY31M0ETy5y1vA33YoNPDFTghEbnh6efaE8h4x0Q==} + + micromark-util-types@2.0.3: + resolution: {integrity: sha512-oxB2Ik03hI0gv+VNn9tnh1t1YEe9MDPptViAEgfdf3YQHsn0pzGTgCdlSCJXcwhqm8phaEuM7zeEu3QQzVBrPg==} + + micromark@4.0.3: + resolution: {integrity: sha512-oGYfQzHSG5dOMovQcJ3fyTmZlWAWpi0XA0sJwJs+i6OT88o1+Jtw/8z0CmdowSLxGhhFK89rQ/oXph/wN02PNw==} + mrmime@2.0.1: resolution: {integrity: sha512-Y3wQdFg2Va6etvQ5I82yUhGdsKrcYox6p7FfL1LbK2J4V01F9TGlepTIhnK24t7koZibmg82KGglhA1XK5IsLQ==} engines: {node: '>=10'} + ms@2.1.3: + resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==} + nanoid@3.3.20: resolution: {integrity: sha512-uKdg2G3GNCKQn9byYOpxbGqrT2fGO5KRt5J/8b3pok8rT6qxGWF6hxMyJiEYtAf+FVyYuD9hRaDqX5uPFYJ4ZQ==} engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1} @@ -558,6 +777,9 @@ packages: resolution: {integrity: sha512-5vvB5+W7ePv+p3uqxi+RcW1XAzLW0/hxt3/4X4Lc4qHudzOhmBiBwOY6DRob4WnanAEGvNcLjF+KNOufrUoEQw==} engines: {node: '>=12.20.0'} + parse-entities@4.0.2: + resolution: {integrity: sha512-GG2AQYWoLgL877gQIKeRPGO1xF9+eG1ujIb5soS5gPvLQ1y2o8FL90w2QWNdf9I361Mpp7726c+lj3U0qK1uGw==} + pathe@2.0.3: resolution: {integrity: sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==} @@ -598,6 +820,12 @@ packages: resolution: {integrity: sha512-QNhWdt7nrgVWWQG58QuGsAR3jv3Hbe4mb4vz7w2csnHavciZJgda1CPNaldF6eVxv90ud3jUXpKlHL69gO38yw==} engines: {node: '>=0.10.0'} + remark-mdx@3.1.1: + resolution: {integrity: sha512-Pjj2IYlUY3+D8x00UJsIOg5BEvfMyeI+2uLPn9VO9Wg4MEtN/VTIq2NEJQfde9PnX15KgtHyl9S0BcTnWrIuWg==} + + remark-parse@11.0.0: + resolution: {integrity: sha512-FCxlKLNGknS5ba/1lmpYijMUzX2esxW5xQqjWxw2eHFfS2MSdaHVINFmhjo+qN1WhZhNimq0dZATN9pH0IDrpA==} + resolve-pkg-maps@1.0.0: resolution: {integrity: sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==} @@ -653,6 +881,9 @@ packages: std-env@4.3.0: resolution: {integrity: sha512-OtU/EgQ1kIm5KwqQpBC6ZEMXrZRui11w8zgfTWp8cdO9B8OaPsbA8bTHO2P+HNo1VlUTGMVBwPhydu6poeXiag==} + stringify-entities@4.0.4: + resolution: {integrity: sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg==} + tinybench@2.9.0: resolution: {integrity: sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==} @@ -675,6 +906,9 @@ packages: resolution: {integrity: sha512-sf4i37nQ2LBx4m3wB74y+ubopq6W/dIzXg0FDGjsYnZHVa1Da8FH853wlL2gtUhg+xJXjfk3kUZS3BRoQeoQBQ==} engines: {node: '>=6'} + trough@2.2.0: + resolution: {integrity: sha512-tmMpK00BjZiUyVyvrBK7knerNgmgvcV/KLVyuma/SC+TQN167GrMRciANTz09+k3zW8L8t60jWO1GpfkZdjTaw==} + tsdown@0.23.7: resolution: {integrity: sha512-w9nmWyEimfqQ7/HpVeKTldAeBvWGXiaWyNP7xaxSrr0GhKxsngEyTWqk1nOruRqvqRSkdpMMkpV2BcoWfLB4Uw==} engines: {node: ^22.18.0 || ^24.11.0 || >=26.0.0} @@ -723,10 +957,34 @@ packages: undici-types@7.24.6: resolution: {integrity: sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg==} + unified@11.0.5: + resolution: {integrity: sha512-xKvGhPWw3k84Qjh8bI3ZeJjqnyadK+GEFtazSfZv/rKeTkTjOJho6mFqh2SM96iIcZokxiOpg78GazTSg8+KHA==} + + unist-util-is@6.0.1: + resolution: {integrity: sha512-LsiILbtBETkDz8I9p1dQ0uyRUWuaQzd/cuEeS1hoRSyW5E5XGmTzlwY1OrNzzakGowI9Dr/I8HVaw4hTtnxy8g==} + + unist-util-position-from-estree@2.0.0: + resolution: {integrity: sha512-KaFVRjoqLyF6YXCbVLNad/eS4+OfPQQn2yOd7zF/h5T/CSL2v8NpN6a5TPvtbXthAGw5nG+PuTtq+DdIZr+cRQ==} + + unist-util-stringify-position@4.0.0: + resolution: {integrity: sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ==} + + unist-util-visit-parents@6.1.0: + resolution: {integrity: sha512-vKXxz6O38sKDj1mtx/k2cWvkkFBuYGx6uGrlzBkVeWCRF/F8sdI0j3Wbkz/5rVNRRuVc8UrgRdbCxNhmYXgP3w==} + + unist-util-visit@5.2.0: + resolution: {integrity: sha512-fpsYs/VVoZxfGY9/j3FQpZmN8wdLJaV1Pt38AaJNZu9uKIHcFU3halCdBveEq1HGKO1OEfJY65w1zvoFV1b3qQ==} + verkit@0.5.0: resolution: {integrity: sha512-u4J1hr6Y+C/hit34GwL3eIcUf3wngT8TlYUjK7tk0jxydKLAq3sYvifjdTDA6U3KCKRcQCQDGf/srjxfZF3l7g==} engines: {node: '>=18.12.0'} + vfile-message@4.0.4: + resolution: {integrity: sha512-66ycRswIkNmHH9PHku7ADtv5RVwgIrOcuv3J8Svz6h4qgGRrKVa+9/neuKyJZUXyOpYwLTvS+whZ4R2urHHgQg==} + + vfile@6.0.3: + resolution: {integrity: sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q==} + vite@8.3.6: resolution: {integrity: sha512-UI7dK29NnS54Fk+mmo7o+jI6U8Fp7hDl+X5Q1k45WH+d4dSlbLVUETGQ+hfkNgvLQGyoElPj837nZyv4MBc0VA==} engines: {node: ^20.19.0 || >=22.12.0} @@ -851,6 +1109,9 @@ packages: '@yuku-toolchain/wasm': optional: true + zwitch@2.0.4: + resolution: {integrity: sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A==} + snapshots: '@blazediff/core@1.9.1': {} @@ -1005,10 +1266,28 @@ snapshots: '@types/deep-eql': 4.0.2 assertion-error: 2.0.1 + '@types/debug@4.1.13': + dependencies: + '@types/ms': 2.1.0 + '@types/deep-eql@4.0.2': {} + '@types/estree-jsx@1.0.5': + dependencies: + '@types/estree': 1.0.10 + '@types/estree@1.0.10': {} + '@types/hast@3.0.5': + dependencies: + '@types/unist': 3.0.3 + + '@types/mdast@4.0.4': + dependencies: + '@types/unist': 3.0.3 + + '@types/ms@2.1.0': {} + '@types/node@24.19.2': dependencies: undici-types: 7.24.6 @@ -1021,6 +1300,10 @@ snapshots: dependencies: csstype: 3.2.3 + '@types/unist@2.0.11': {} + + '@types/unist@3.0.3': {} + '@vitest/browser-playwright@4.1.12(playwright@1.65.0)(vite@8.3.6(@types/node@24.19.2))(vitest@4.1.12)': dependencies: '@vitest/browser': 4.1.12(vite@8.3.6(@types/node@24.19.2))(vitest@4.1.12) @@ -1110,34 +1393,75 @@ snapshots: '@yuku-toolchain/win32-x64@0.27.0': optional: true + acorn-jsx@5.3.2(acorn@8.19.0): + dependencies: + acorn: 8.19.0 + + acorn@8.19.0: {} + assertion-error@2.0.1: {} + bail@2.0.2: {} + cac@7.1.0: {} + ccount@2.0.1: {} + chai@6.3.0: {} + character-entities-html4@2.1.0: {} + + character-entities-legacy@3.0.0: {} + + character-entities@2.0.2: {} + + character-reference-invalid@2.0.1: {} + cn@0.4.0: {} convert-source-map@2.0.0: {} csstype@3.2.3: {} + debug@4.4.3: + dependencies: + ms: 2.1.3 + + decode-named-character-reference@1.3.0: + dependencies: + character-entities: 2.0.2 + defu@6.1.7: {} + dequal@2.0.3: {} + detect-libc@2.1.2: {} + devlop@1.1.0: + dependencies: + dequal: 2.0.3 + dts-resolver@3.0.0: {} empathic@2.1.0: {} es-module-lexer@2.3.2: {} + estree-util-is-identifier-name@3.0.0: {} + + estree-util-visit@2.0.0: + dependencies: + '@types/estree-jsx': 1.0.5 + '@types/unist': 3.0.3 + estree-walker@3.0.3: dependencies: '@types/estree': 1.0.10 expect-type@1.4.0: {} + extend@3.0.2: {} + fdir@6.5.0(picomatch@4.0.7): optionalDependencies: picomatch: 4.0.7 @@ -1153,6 +1477,19 @@ snapshots: import-without-cache@0.4.1: {} + is-alphabetical@2.0.1: {} + + is-alphanumerical@2.0.1: + dependencies: + is-alphabetical: 2.0.1 + is-decimal: 2.0.1 + + is-decimal@2.0.1: {} + + is-hexadecimal@2.0.1: {} + + is-plain-obj@4.1.0: {} + lightningcss-android-arm64@1.33.0: optional: true @@ -1202,18 +1539,333 @@ snapshots: lightningcss-win32-arm64-msvc: 1.33.0 lightningcss-win32-x64-msvc: 1.33.0 + longest-streak@3.1.0: {} + magic-string@0.30.21: dependencies: '@jridgewell/sourcemap-codec': 1.6.0 + mdast-util-from-markdown@2.1.0: + dependencies: + '@types/mdast': 4.0.4 + '@types/unist': 3.0.3 + decode-named-character-reference: 1.3.0 + devlop: 1.1.0 + mdast-util-to-string: 4.0.0 + micromark: 4.0.3 + micromark-util-decode-numeric-character-reference: 2.0.2 + micromark-util-decode-string: 2.0.1 + micromark-util-normalize-identifier: 2.0.1 + micromark-util-symbol: 2.0.1 + micromark-util-types: 2.0.3 + unist-util-stringify-position: 4.0.0 + transitivePeerDependencies: + - supports-color + + mdast-util-mdx-expression@2.0.1: + dependencies: + '@types/estree-jsx': 1.0.5 + '@types/hast': 3.0.5 + '@types/mdast': 4.0.4 + devlop: 1.1.0 + mdast-util-from-markdown: 2.1.0 + mdast-util-to-markdown: 2.2.3 + transitivePeerDependencies: + - supports-color + + mdast-util-mdx-jsx@3.2.1: + dependencies: + '@types/estree-jsx': 1.0.5 + '@types/hast': 3.0.5 + '@types/mdast': 4.0.4 + '@types/unist': 3.0.3 + ccount: 2.0.1 + devlop: 1.1.0 + mdast-util-from-markdown: 2.1.0 + mdast-util-to-markdown: 2.2.3 + parse-entities: 4.0.2 + stringify-entities: 4.0.4 + unist-util-stringify-position: 4.0.0 + vfile-message: 4.0.4 + transitivePeerDependencies: + - supports-color + + mdast-util-mdx@3.0.0: + dependencies: + mdast-util-from-markdown: 2.1.0 + mdast-util-mdx-expression: 2.0.1 + mdast-util-mdx-jsx: 3.2.1 + mdast-util-mdxjs-esm: 2.0.1 + mdast-util-to-markdown: 2.2.3 + transitivePeerDependencies: + - supports-color + + mdast-util-mdxjs-esm@2.0.1: + dependencies: + '@types/estree-jsx': 1.0.5 + '@types/hast': 3.0.5 + '@types/mdast': 4.0.4 + devlop: 1.1.0 + mdast-util-from-markdown: 2.1.0 + mdast-util-to-markdown: 2.2.3 + transitivePeerDependencies: + - supports-color + + mdast-util-phrasing@4.1.0: + dependencies: + '@types/mdast': 4.0.4 + unist-util-is: 6.0.1 + + mdast-util-to-markdown@2.2.3: + dependencies: + '@types/mdast': 4.0.4 + '@types/unist': 3.0.3 + longest-streak: 3.1.0 + mdast-util-phrasing: 4.1.0 + mdast-util-to-string: 4.0.0 + micromark-util-character: 2.1.1 + micromark-util-classify-character: 2.0.1 + micromark-util-decode-string: 2.0.1 + micromark-util-html-tag-name: 2.0.1 + unist-util-visit: 5.2.0 + zwitch: 2.0.4 + + mdast-util-to-string@4.0.0: + dependencies: + '@types/mdast': 4.0.4 + + micromark-core-commonmark@2.0.4: + dependencies: + decode-named-character-reference: 1.3.0 + devlop: 1.1.0 + micromark-factory-destination: 2.0.1 + micromark-factory-label: 2.0.1 + micromark-factory-space: 2.1.0 + micromark-factory-title: 2.0.1 + micromark-factory-whitespace: 2.0.1 + micromark-util-character: 2.1.1 + micromark-util-chunked: 2.0.1 + micromark-util-classify-character: 2.0.1 + micromark-util-edit-map: 1.0.0 + micromark-util-html-tag-name: 2.0.1 + micromark-util-normalize-identifier: 2.0.1 + micromark-util-resolve-all: 2.0.1 + micromark-util-subtokenize: 2.1.0 + micromark-util-symbol: 2.0.1 + micromark-util-types: 2.0.3 + + micromark-extension-mdx-expression@3.0.1: + dependencies: + '@types/estree': 1.0.10 + devlop: 1.1.0 + micromark-factory-mdx-expression: 2.0.3 + micromark-factory-space: 2.1.0 + micromark-util-character: 2.1.1 + micromark-util-events-to-acorn: 2.0.3 + micromark-util-symbol: 2.0.1 + micromark-util-types: 2.0.3 + + micromark-extension-mdx-jsx@3.0.2: + dependencies: + '@types/estree': 1.0.10 + devlop: 1.1.0 + estree-util-is-identifier-name: 3.0.0 + micromark-factory-mdx-expression: 2.0.3 + micromark-factory-space: 2.1.0 + micromark-util-character: 2.1.1 + micromark-util-events-to-acorn: 2.0.3 + micromark-util-symbol: 2.0.1 + micromark-util-types: 2.0.3 + vfile-message: 4.0.4 + + micromark-extension-mdx-md@2.0.0: + dependencies: + micromark-util-types: 2.0.3 + + micromark-extension-mdxjs-esm@3.0.0: + dependencies: + '@types/estree': 1.0.10 + devlop: 1.1.0 + micromark-core-commonmark: 2.0.4 + micromark-util-character: 2.1.1 + micromark-util-events-to-acorn: 2.0.3 + micromark-util-symbol: 2.0.1 + micromark-util-types: 2.0.3 + unist-util-position-from-estree: 2.0.0 + vfile-message: 4.0.4 + + micromark-extension-mdxjs@3.0.0: + dependencies: + acorn: 8.19.0 + acorn-jsx: 5.3.2(acorn@8.19.0) + micromark-extension-mdx-expression: 3.0.1 + micromark-extension-mdx-jsx: 3.0.2 + micromark-extension-mdx-md: 2.0.0 + micromark-extension-mdxjs-esm: 3.0.0 + micromark-util-combine-extensions: 2.0.1 + micromark-util-types: 2.0.3 + + micromark-factory-destination@2.0.1: + dependencies: + micromark-util-character: 2.1.1 + micromark-util-symbol: 2.0.1 + micromark-util-types: 2.0.3 + + micromark-factory-label@2.0.1: + dependencies: + devlop: 1.1.0 + micromark-util-character: 2.1.1 + micromark-util-symbol: 2.0.1 + micromark-util-types: 2.0.3 + + micromark-factory-mdx-expression@2.0.3: + dependencies: + '@types/estree': 1.0.10 + devlop: 1.1.0 + micromark-factory-space: 2.1.0 + micromark-util-character: 2.1.1 + micromark-util-events-to-acorn: 2.0.3 + micromark-util-symbol: 2.0.1 + micromark-util-types: 2.0.3 + unist-util-position-from-estree: 2.0.0 + vfile-message: 4.0.4 + + micromark-factory-space@2.1.0: + dependencies: + micromark-util-character: 2.1.1 + micromark-util-types: 2.0.3 + + micromark-factory-title@2.0.1: + dependencies: + micromark-factory-space: 2.1.0 + micromark-util-character: 2.1.1 + micromark-util-symbol: 2.0.1 + micromark-util-types: 2.0.3 + + micromark-factory-whitespace@2.0.1: + dependencies: + micromark-factory-space: 2.1.0 + micromark-util-character: 2.1.1 + micromark-util-symbol: 2.0.1 + micromark-util-types: 2.0.3 + + micromark-util-character@2.1.1: + dependencies: + micromark-util-symbol: 2.0.1 + micromark-util-types: 2.0.3 + + micromark-util-chunked@2.0.1: + dependencies: + micromark-util-symbol: 2.0.1 + + micromark-util-classify-character@2.0.1: + dependencies: + micromark-util-character: 2.1.1 + micromark-util-symbol: 2.0.1 + micromark-util-types: 2.0.3 + + micromark-util-combine-extensions@2.0.1: + dependencies: + micromark-util-chunked: 2.0.1 + micromark-util-types: 2.0.3 + + micromark-util-decode-numeric-character-reference@2.0.2: + dependencies: + micromark-util-symbol: 2.0.1 + + micromark-util-decode-string@2.0.1: + dependencies: + decode-named-character-reference: 1.3.0 + micromark-util-character: 2.1.1 + micromark-util-decode-numeric-character-reference: 2.0.2 + micromark-util-symbol: 2.0.1 + + micromark-util-edit-map@1.0.0: + dependencies: + micromark-util-types: 2.0.3 + + micromark-util-encode@2.0.1: {} + + micromark-util-events-to-acorn@2.0.3: + dependencies: + '@types/estree': 1.0.10 + '@types/unist': 3.0.3 + devlop: 1.1.0 + estree-util-visit: 2.0.0 + micromark-util-symbol: 2.0.1 + micromark-util-types: 2.0.3 + vfile-message: 4.0.4 + + micromark-util-html-tag-name@2.0.1: {} + + micromark-util-normalize-identifier@2.0.1: + dependencies: + micromark-util-symbol: 2.0.1 + + micromark-util-resolve-all@2.0.1: + dependencies: + micromark-util-types: 2.0.3 + + micromark-util-sanitize-uri@2.0.1: + dependencies: + micromark-util-character: 2.1.1 + micromark-util-encode: 2.0.1 + micromark-util-symbol: 2.0.1 + + micromark-util-subtokenize@2.1.0: + dependencies: + devlop: 1.1.0 + micromark-util-chunked: 2.0.1 + micromark-util-symbol: 2.0.1 + micromark-util-types: 2.0.3 + + micromark-util-symbol@2.0.1: {} + + micromark-util-types@2.0.3: {} + + micromark@4.0.3: + dependencies: + '@types/debug': 4.1.13 + debug: 4.4.3 + decode-named-character-reference: 1.3.0 + devlop: 1.1.0 + micromark-core-commonmark: 2.0.4 + micromark-factory-space: 2.1.0 + micromark-util-character: 2.1.1 + micromark-util-chunked: 2.0.1 + micromark-util-combine-extensions: 2.0.1 + micromark-util-decode-numeric-character-reference: 2.0.2 + micromark-util-edit-map: 1.0.0 + micromark-util-encode: 2.0.1 + micromark-util-normalize-identifier: 2.0.1 + micromark-util-resolve-all: 2.0.1 + micromark-util-sanitize-uri: 2.0.1 + micromark-util-subtokenize: 2.1.0 + micromark-util-symbol: 2.0.1 + micromark-util-types: 2.0.3 + transitivePeerDependencies: + - supports-color + mrmime@2.0.1: {} + ms@2.1.3: {} + nanoid@3.3.20: {} obug@2.2.1: {} obug@3.0.0: {} + parse-entities@4.0.2: + dependencies: + '@types/unist': 2.0.11 + character-entities-legacy: 3.0.0 + character-reference-invalid: 2.0.1 + decode-named-character-reference: 1.3.0 + is-alphanumerical: 2.0.1 + is-decimal: 2.0.1 + is-hexadecimal: 2.0.1 + pathe@2.0.3: {} picocolors@1.1.1: {} @@ -1243,6 +1895,22 @@ snapshots: react@19.3.1: {} + remark-mdx@3.1.1: + dependencies: + mdast-util-mdx: 3.0.0 + micromark-extension-mdxjs: 3.0.0 + transitivePeerDependencies: + - supports-color + + remark-parse@11.0.0: + dependencies: + '@types/mdast': 4.0.4 + mdast-util-from-markdown: 2.1.0 + micromark-util-types: 2.0.3 + unified: 11.0.5 + transitivePeerDependencies: + - supports-color + resolve-pkg-maps@1.0.0: {} rolldown-plugin-dts@0.30.0(rolldown@1.3.0)(typescript@5.9.3): @@ -1317,6 +1985,11 @@ snapshots: std-env@4.3.0: {} + stringify-entities@4.0.4: + dependencies: + character-entities-html4: 2.1.0 + character-entities-legacy: 3.0.0 + tinybench@2.9.0: {} tinyexec@1.3.1: {} @@ -1332,6 +2005,8 @@ snapshots: totalist@3.0.1: {} + trough@2.2.0: {} + tsdown@0.23.7(typescript@5.9.3): dependencies: cac: 7.1.0 @@ -1370,8 +2045,51 @@ snapshots: undici-types@7.24.6: {} + unified@11.0.5: + dependencies: + '@types/unist': 3.0.3 + bail: 2.0.2 + devlop: 1.1.0 + extend: 3.0.2 + is-plain-obj: 4.1.0 + trough: 2.2.0 + vfile: 6.0.3 + + unist-util-is@6.0.1: + dependencies: + '@types/unist': 3.0.3 + + unist-util-position-from-estree@2.0.0: + dependencies: + '@types/unist': 3.0.3 + + unist-util-stringify-position@4.0.0: + dependencies: + '@types/unist': 3.0.3 + + unist-util-visit-parents@6.1.0: + dependencies: + '@types/unist': 3.0.3 + unist-util-is: 6.0.1 + + unist-util-visit@5.2.0: + dependencies: + '@types/unist': 3.0.3 + unist-util-is: 6.0.1 + unist-util-visit-parents: 6.1.0 + verkit@0.5.0: {} + vfile-message@4.0.4: + dependencies: + '@types/unist': 3.0.3 + unist-util-stringify-position: 4.0.0 + + vfile@6.0.3: + dependencies: + '@types/unist': 3.0.3 + vfile-message: 4.0.4 + vite@8.3.6(@types/node@24.19.2): dependencies: lightningcss: 1.33.0 @@ -1435,3 +2153,5 @@ snapshots: '@yuku-toolchain/linux-x64': 0.27.0 '@yuku-toolchain/win32-arm64': 0.27.0 '@yuku-toolchain/win32-x64': 0.27.0 + + zwitch@2.0.4: {} diff --git a/scripts/audit-browser.mjs b/scripts/audit-browser.mjs index 67053192..ccdef05b 100644 --- a/scripts/audit-browser.mjs +++ b/scripts/audit-browser.mjs @@ -8,248 +8,127 @@ import { chromium } from "@playwright/test"; import { createServer } from "vite"; const root = dirname(dirname(fileURLToPath(import.meta.url))); -const scratch = mkdtempSync(join(tmpdir(), "throughline-vite-consumer-")); -let browser; -let server; -let context; +const scratch = mkdtempSync(join(tmpdir(), "throughline-v2-browser-consumer-")); +let browser, context, server; function run(command, args, cwd) { const result = spawnSync(command, args, { - cwd, - encoding: "utf8", - maxBuffer: 8 * 1024 * 1024, + cwd, encoding: "utf8", maxBuffer: 8 * 1024 * 1024, }); - if (result.error || result.status !== 0) { - throw new Error( - [command, ...args].join(" ") + - " failed:\n" + - (result.stdout ?? "") + - "\n" + - (result.stderr ?? "") + - (result.error ? "\n" + result.error.message : ""), - ); - } + if (result.error || result.status !== 0) + throw new Error([command, ...args].join(" ") + " failed:\n" + + (result.stdout ?? "") + "\n" + (result.stderr ?? "") + + (result.error ? "\n" + result.error.message : "")); return result.stdout; } -// This fixture intentionally imports only the packed package by its public exports. +// This fixture imports only publicly packed schema-2 artifacts and entrypoints. const traceSource = [ - 'const fence = String.fromCharCode(96).repeat(3);', - 'const source = [fence + "thl flow", "node n \\"Number\\" = 0",', - ' "step \\"One\\"", " set n = 1", "step \\"Two\\"", " set n = 2", fence].join("\\n");', - 'const trace = compile(source);', + 'import { EXAMPLES } from "@0xbuff/throughline/examples";', + 'import { compileArtifact } from "@0xbuff/throughline";', + 'const artifact = EXAMPLES.find(item => item.id === "factorial").artifact;', + 'const trace = compileArtifact(artifact);', ].join("\n"); try { const tarball = join(scratch, "throughline.tgz"); run("pnpm", ["pack", "--out", tarball], root); - const consumer = join(scratch, "consumer"); mkdirSync(consumer); - writeFileSync( - join(consumer, "package.json"), - JSON.stringify({ name: "independent-throughline-vite", private: true, type: "module" }), - ); - run( - "npm", - [ - "install", - "--no-audit", - "--no-fund", - "--no-package-lock", - "--ignore-scripts", - tarball, - "react@^19", - "react-dom@^19", - ], - consumer, - ); - - // Node must reject unsupported deep imports even when dist files exist. - run( - "node", - [ - "--input-type=module", - "-e", - [ - 'import assert from "node:assert/strict";', - 'await assert.rejects(', - ' import("@0xbuff/throughline/dist/index.js"),', - ' (error) => error.code === "ERR_PACKAGE_PATH_NOT_EXPORTED",', - ');', - ].join("\n"), - ], - consumer, - ); - - // Generate actual server markup from the installed tarball, not source modules. - const markup = run( - "node", - [ - "--input-type=module", - "-e", - [ - 'import { createElement } from "react";', - 'import { renderToString } from "react-dom/server";', - 'import { compile } from "@0xbuff/throughline";', - 'import { ThroughlinePlayer } from "@0xbuff/throughline/react";', - traceSource, - 'process.stdout.write(renderToString(createElement(ThroughlinePlayer, { trace })));', - ].join("\n"), - ], - consumer, - ); - assert(markup.includes("Visualization player"), "Server did not render the player"); - writeFileSync( - join(consumer, "index.html"), - [ - "", - '', - '', - '
' + markup + "
", - '', - '', - "", - ].join("\n"), - ); - writeFileSync( - join(consumer, "main.js"), - [ - 'import { createElement, useEffect } from "react";', - 'import { hydrateRoot } from "react-dom/client";', - 'import { compile } from "@0xbuff/throughline";', - 'import { ThroughlinePlayer } from "@0xbuff/throughline/react";', - 'import "@0xbuff/throughline/styles/throughline.css";', - traceSource, - 'function App() {', - ' useEffect(() => { window.__HYDRATED = true; }, []);', - ' return createElement(ThroughlinePlayer, { trace });', - '}', - 'hydrateRoot(document.getElementById("root"), createElement(App));', - ].join("\n"), - ); + writeFileSync(join(consumer, "package.json"), + JSON.stringify({ name: "independent-throughline-v2-browser", private: true, type: "module" })); + run("npm", ["install", "--no-audit", "--no-fund", "--no-package-lock", + "--ignore-scripts", tarball, "react@^19", "react-dom@^19"], consumer); + run("node", ["--input-type=module", "-e", [ + 'import assert from "node:assert/strict";', + 'await assert.rejects(import("@0xbuff/throughline/dist/index.js"),', + ' error => error.code === "ERR_PACKAGE_PATH_NOT_EXPORTED");', + 'import * as root from "@0xbuff/throughline";', + 'import * as react from "@0xbuff/throughline/react";', + 'assert.equal("compile" in root, false);', + 'assert.equal("ThroughlinePlayer" in react, false);', + ].join("\n")], consumer); + const markup = run("node", ["--input-type=module", "-e", [ + 'import { createElement } from "react";', + 'import { renderToString } from "react-dom/server";', + 'import { ThroughlineGraphPlayer } from "@0xbuff/throughline/react";', + traceSource, + 'process.stdout.write(renderToString(createElement(ThroughlineGraphPlayer, { trace, initialView: "graph" })));', + ].join("\n")], consumer); + assert.match(markup, /Visualization player/, "SSR native schema-2 player not present"); + writeFileSync(join(consumer, "index.html"), [ + "", + "", + '
' + markup + "
", + '', + '', + "", + ].join("\n")); + writeFileSync(join(consumer, "main.js"), [ + 'import { createElement, useEffect } from "react";', + 'import { hydrateRoot } from "react-dom/client";', + 'import { ThroughlineGraphPlayer } from "@0xbuff/throughline/react";', + 'import "@0xbuff/throughline/styles/throughline.css";', + traceSource, + 'function App() {', + ' useEffect(() => { window.__HYDRATED = true; }, []);', + ' return createElement(ThroughlineGraphPlayer, { trace, initialView: "graph" });', + '}', + 'hydrateRoot(document.getElementById("root"), createElement(App));', + ].join("\n")); server = await createServer({ - configFile: false, - envFile: false, - root: consumer, - logLevel: "error", + configFile: false, envFile: false, root: consumer, logLevel: "error", mode: "development", server: { host: "127.0.0.1", port: 0, strictPort: false }, }); await server.listen(); const port = server.httpServer?.address()?.port; - assert.equal(typeof port, "number", "Vite did not select a port"); + assert.equal(typeof port, "number"); browser = await chromium.launch(); context = await browser.newContext({ viewport: { width: 375, height: 850 }, - reducedMotion: "reduce", - hasTouch: true, + reducedMotion: "reduce", hasTouch: true, }); const page = await context.newPage(); const errors = []; - page.on("pageerror", (error) => errors.push(error.message)); - page.on("console", (message) => { + page.on("pageerror", error => errors.push(error.message)); + page.on("console", message => { if (message.type() === "error") errors.push(message.text()); }); await page.goto("http://127.0.0.1:" + port + "/", { waitUntil: "networkidle" }); await page.waitForFunction(() => window.__HYDRATED === true, null, { timeout: 15_000 }); - - assert( - await page.evaluate( - () => document.querySelector("#root > .thl") === window.__SERVER_NODE, - ), - "React replaced rather than hydrated the server player node", - ); + assert(await page.evaluate(() => + document.querySelector("#root > .thl") === window.__SERVER_NODE), + "React replaced rather than hydrated native server player"); const player = page.getByRole("group", { name: "Visualization player" }); - assert(await player.isVisible(), "Hydrated player is not visible"); - assert.match(await page.getByRole("status").textContent(), /Step 1 of 3/); - - const visual = await player.evaluate((element) => ({ + assert(await player.isVisible()); + assert.match(await page.getByRole("status").textContent(), /Step 1 of 9/); + const visual = await player.evaluate(element => ({ overflow: element.scrollWidth > element.clientWidth, - border: getComputedStyle(element).borderTopWidth, - radiusToken: getComputedStyle(element).getPropertyValue("--thl-radius").trim(), - controls: getComputedStyle(element.querySelector(".thl-controls")).display, - captionBorder: getComputedStyle(element.querySelector(".thl-caption")).borderTopWidth, + radius: getComputedStyle(element).getPropertyValue("--thl-radius").trim(), + controls: getComputedStyle(element.querySelector(".thl-bottom")).display, + graph: element.querySelector(".thl-v2-diagram") !== null, reducedMotion: matchMedia("(prefers-reduced-motion: reduce)").matches, })); - assert.equal(visual.overflow, false, "Player overflows at phone width"); - assert.equal(visual.radiusToken, "0.125rem", "Packed player must preserve compact corner-radius tokens"); - assert.equal(visual.border, "0px", "The player must not have an outer border"); - assert.equal(visual.captionBorder, "0px", "The caption must remain borderless"); - assert.equal(visual.controls, "grid", "Package control-bar styles did not load"); - assert.equal(visual.reducedMotion, true, "Reduced-motion media preference absent"); - + assert.equal(visual.overflow, false, "Native schema-2 player overflows phone viewport"); + assert.equal(visual.radius, "0.125rem", "Packed CSS tokens not loaded"); + assert(visual.controls && visual.controls !== "none", "Controls not displayed"); + assert.equal(visual.graph, true, "Native graph not rendered"); + assert.equal(visual.reducedMotion, true); await page.getByRole("button", { name: "Step forward" }).click(); - assert.match(await page.getByRole("status").textContent(), /Step 2 of 3/); + assert.match(await page.getByRole("status").textContent(), /Step 2 of 9/); await player.focus(); await page.keyboard.press("ArrowRight"); - assert.match(await page.getByRole("status").textContent(), /Step 3 of 3/); - - // Use a real Chromium touch-enabled context, not a synthetic input event. - assert.equal(await page.getByRole("slider").count(), 0, "Player must be slider-free"); + assert.match(await page.getByRole("status").textContent(), /Step 3 of 9/); await page.getByRole("button", { name: "Player options" }).tap(); - await page.getByRole("spinbutton", { name: "Step number" }).fill("1"); - await page.getByRole("button", { name: "Go to step" }).tap(); - assert.match(await page.getByRole("status").textContent(), /Step 1 of 3/); - // Exercise the native fullscreen layout in a real Chromium document. - const options = page.getByRole("button", { name: "Player options" }); - await options.tap(); - await page.getByRole("button", { name: "Maximize player" }).tap(); - await page.waitForFunction(() => document.fullscreenElement?.classList.contains("thl")); - - const fullscreenBounds = () => player.evaluate((element) => { - const header = element.querySelector(".thl-header").getBoundingClientRect(); - const svg = element.querySelector(".thl-scene"); - const scene = svg.getBoundingClientRect(); - const bar = element.querySelector(".thl-bottom").getBoundingClientRect(); - const caption = element.querySelector(".thl-caption").getBoundingClientRect(); - const { x, y, width, height } = svg.viewBox.baseVal; - const center = new DOMPoint(x + width / 2, y + height / 2).matrixTransform(svg.getScreenCTM()); - const padding = Number.parseFloat(getComputedStyle(element).paddingBottom); - return { - width: element.clientWidth, - height: element.clientHeight, - scrollHeight: element.scrollHeight, - windowWidth: innerWidth, - windowHeight: innerHeight, - headerTop: header.top, - sceneHeight: scene.height, - sceneBottom: scene.bottom, - centerX: center.x, - centerY: center.y, - sceneCenterY: scene.top + scene.height / 2, - barTop: bar.top, - captionBottom: caption.bottom, - padding, - }; - }); - const closed = await fullscreenBounds(); - assert.equal(closed.width, closed.windowWidth, "Fullscreen should fill the browser width"); - assert.equal(closed.height, closed.windowHeight, "Fullscreen should fill the browser height"); - assert.equal(closed.scrollHeight, closed.height, "Fullscreen should fit without page scrolling"); - assert.equal(closed.headerTop, closed.padding, "Header should sit at the top"); - assert.equal(closed.captionBottom, closed.height - closed.padding, "Caption should sit at the bottom"); - assert(closed.sceneHeight > closed.height / 2, "Scene should fill the available height"); - assert(closed.sceneBottom <= closed.barTop, "Scene should fit above the controls"); - assert(Math.abs(closed.centerX - closed.width / 2) < 1, "Diagram should be centered horizontally"); - assert(Math.abs(closed.centerY - closed.sceneCenterY) < 1, "Diagram should be centered vertically"); - - await page.getByText("Details", { exact: true }).tap(); - const expanded = await fullscreenBounds(); - assert(expanded.barTop < closed.barTop, "Expanded details should move the controls up"); - assert(expanded.sceneHeight < closed.sceneHeight, "Expanded details should shrink the scene"); - assert.equal(expanded.headerTop, closed.headerTop, "Expanded details should keep the header in place"); - assert.equal(expanded.captionBottom, closed.captionBottom, "Expanded details should grow above the bottom edge"); - - await options.tap(); - await page.getByRole("button", { name: "Minimize player" }).tap(); - await page.waitForFunction(() => document.fullscreenElement === null); - - assert.deepEqual(errors, [], "Hydration or browser console errors were emitted"); - - console.log("Packed Vite React consumer passed SSR hydration, CSS, keyboard, touch step navigation, fullscreen, mobile and export checks."); + await page.getByRole("combobox", { name: "Visualization view" }).selectOption("state-table"); + assert(await page.getByRole("region", { name: "State and event table" }).isVisible()); + const state = await page.getByRole("region", { name: "State and event table" }).textContent(); + assert.match(state, /Modeled call stack/); + assert.deepEqual(errors, [], "Browser hydration/console failures occurred"); + console.log("Packed v2 browser consumer passed SSR hydration, mobile CSS, keyboard, touch, state-table and public-export gates."); } finally { await context?.close(); await browser?.close(); diff --git a/scripts/audit-licenses.mjs b/scripts/audit-licenses.mjs index a56e622b..e14b971e 100644 --- a/scripts/audit-licenses.mjs +++ b/scripts/audit-licenses.mjs @@ -8,7 +8,7 @@ const manifest = JSON.parse(readFileSync(join(root, "package.json"), "utf8")); assert.deepEqual( Object.keys(manifest.dependencies ?? {}).sort(), - ["cn"], + ["cn", "remark-mdx", "remark-parse", "unified"], "Unreviewed direct production dependency", ); assert.deepEqual( @@ -34,9 +34,13 @@ const visited = new Map(); function requirePackage(name, parent) { // pnpm's isolated linker keeps a dependency's children beside its own // symlink target; first-level dependencies use root/node_modules. + // pnpm 11 may hoist type-only and shared transitive dependencies into + // .pnpm/node_modules rather than creating a sibling link for each caller. + // Audit those resolved packages too; do not silently skip a dependency. + const hoisted = join(root, "node_modules", ".pnpm", "node_modules", name); const locations = parent - ? [join(dirname(parent), name), join(root, "node_modules", name)] - : [join(root, "node_modules", name)]; + ? [join(dirname(parent), name), join(root, "node_modules", name), hoisted] + : [join(root, "node_modules", name), hoisted]; const location = locations.find((candidate) => existsSync(candidate)); assert(location, "Missing installed dependency: " + name); const path = realpathSync(location); @@ -68,12 +72,18 @@ function auditPackage(name, parent) { if (existsSync(location)) auditPackage(dependency, path); } } -for (const name of ["cn", "react", "react-dom"]) { +for (const name of ["cn", "react", "react-dom", "remark-mdx", "remark-parse", "unified"]) { auditPackage(name); } // The published tarball is audited separately. Keep JS dependencies external // so the project's Apache LICENSE cannot silently cover embedded MIT files. +const nodeEntry = readFileSync(join(root, "dist", "node", "index.js"), "utf8"); +const cliEntry = readFileSync(join(root, "dist", "cli", "main.js"), "utf8"); +// Ensure the package does not embed copied third-party parser implementations. +// The actual parser is an explicit, locked production dependency instead. +assert(!nodeEntry.includes("function tokenizeFactory") && !cliEntry.includes("function tokenizeFactory"), + "Node/CLI parser dependencies must remain external and separately licensed"); const generated = join(root, "dist", "react", "index.js"); assert(existsSync(generated), "Run the build before this audit"); const code = readFileSync(generated, "utf8"); diff --git a/scripts/audit-pack.mjs b/scripts/audit-pack.mjs index 5c0d0290..141f20c5 100644 --- a/scripts/audit-pack.mjs +++ b/scripts/audit-pack.mjs @@ -49,6 +49,9 @@ try { "package/dist/remark/index.d.ts", "package/dist/examples.js", "package/dist/examples.d.ts", + "package/dist/node/index.js", + "package/dist/node/index.d.ts", + "package/dist/cli/main.js", "package/src/styles/throughline.css", ]) { assert(entries.includes(file), "Missing packed file: " + file); @@ -92,9 +95,10 @@ try { ); assert.deepEqual( Object.keys(packed.exports).sort(), - [".", "./react", "./remark", "./examples", "./styles/throughline.css"].sort(), + [".", "./react", "./remark", "./examples", "./node", "./styles/throughline.css"].sort(), ); - assert.deepEqual(Object.keys(packed.dependencies ?? {}), ["cn"]); + assert.equal(packed.bin?.thl, "./dist/cli/main.js"); + assert.deepEqual(Object.keys(packed.dependencies ?? {}), ["cn", "remark-mdx", "remark-parse", "unified"]); for (const dependencies of [ packed.dependencies ?? {}, packed.peerDependencies ?? {}, @@ -128,17 +132,125 @@ try { ); assert( !existsSync(join(consumer, "node_modules", "react")) && - !existsSync(join(consumer, "node_modules", "unified")), - "Core consumer unexpectedly installed React", + existsSync(join(consumer, "node_modules", "unified")) && + existsSync(join(consumer, "node_modules", "remark-parse")) && + existsSync(join(consumer, "node_modules", "remark-mdx")), + "Node-only package must contain syntax parsers but not React", ); + // Independently installed CLI/Node host: real archive, real bin, no + // compulsory React/AI, no MDX execution and no self-approval. + assert(existsSync(join(consumer, "node_modules", ".bin", "thl")), + "Packed CLI binary link missing"); + const cliPath = join(consumer, "node_modules", "@0xbuff", "throughline", "dist", "cli", "main.js"); + const cli = (...args) => run("node", [cliPath, ...args], consumer); + const fixtureRoot = join(consumer, "fixtures"); + mkdirSync(join(fixtureRoot, "docs"), { recursive: true }); + mkdirSync(join(fixtureRoot, "artifacts"), { recursive: true }); + const counterJson = JSON.stringify({ + schemaVersion: 2, id: "packedCounter", + origins: [{ id: "author", kind: "authored" }], + entities: [{ id: "x", label: "Counter" }], relations: [], + initialState: { x: { status: "known", value: 0 } }, + steps: [{ id: "increment", label: "Increment", events: [ + { id: "w", originId: "author", type: "write", + entityId: "x", path: [], value: { status: "known", value: 1 } }, + ] }], + }); + writeFileSync(join(fixtureRoot, "artifacts", "counter.json"), counterJson); + const prompt = "Explain the counter with explicit writes."; + writeFileSync(join(fixtureRoot, "docs", "sample.mdx"), + "## Semantic model\n\n~~~thl\n" + counterJson + "\n~~~\n\n" + + "~~~mermaid\ngraph TD\n~~~\n\n" + "~~~thl\n" + prompt + "\n~~~\n"); + assert.match(cli("validate", "artifacts/counter.json", "--root", fixtureRoot), /THL_OK validate/); + const before = spawnSync("node", [cliPath, "check", "docs", "--root", fixtureRoot], + { cwd: consumer, encoding: "utf8" }); + assert.notEqual(before.status, 0); + assert.match(before.stderr, /THL_UNRESOLVED.*thl #1/); + assert.match(cli("materialize", "--root", fixtureRoot, + "--document", "docs/sample.mdx", "--ordinal", "1", + "--artifact", "artifacts/counter.json", "--manifest", "manifest.json"), + /THL_UNREVIEWED materialize/); + const unreviewed = spawnSync("node", [cliPath, "check", "docs", + "--manifest", "manifest.json", "--root", fixtureRoot], + { cwd: consumer, encoding: "utf8" }); + assert.notEqual(unreviewed.status, 0); + assert.match(unreviewed.stderr, /THL_UNREVIEWED/); + const manifestLocation = join(fixtureRoot, "manifest.json"); + const generated = JSON.parse(readFileSync(manifestLocation, "utf8")); + assert.equal(generated.entries.length, 1); + assert.equal(generated.entries[0].ordinal, 1); + assert.equal(generated.entries[0].review, "unreviewed"); + generated.entries[0].review = "reviewed"; // trusted test-only editorial step + writeFileSync(manifestLocation, JSON.stringify(generated)); + assert.match(cli("check", ".", "--manifest", "manifest.json", "--root", fixtureRoot), + /checked 1 document\(s\), 2 thl block\(s\)/); + const pureHost = [ + 'import assert from "node:assert/strict";', + 'import { createNodeThroughlineHost } from "@0xbuff/throughline/node";', + 'import { resolveThlBody } from "@0xbuff/throughline";', + 'const root = process.argv[1];', + 'const host = createNodeThroughlineHost({ root, manifestPath: "manifest.json" });', + 'const doc = host.documentForFile(root + "/docs/sample.mdx");', + 'assert.equal(doc, "docs/sample.mdx");', + 'assert.equal(resolveThlBody("Explain the counter with explicit writes.",', + ' { document: doc, ordinal: 1, manifest: host.manifest, loadArtifact: host.loadArtifact }).id, "packedCounter");', + ].join("\n"); + run("node", ["--input-type=module", "-e", pureHost, fixtureRoot], consumer); + // A packed CLI must discover nested, real CommonMark code nodes. A + // line-level scanner incorrectly saw zero blocks here, and falsely + // included a thl-looking string inside an HTML comment. + const nestedSource = [ + "", "", + "- Parent", " - Child", "", + " ~~~thl", " Explain a nested model from the real AST.", " ~~~", + "", + "~~~js", "const fake = '~~~thl';", "~~~", + ].join("\n"); + writeFileSync(join(fixtureRoot, "docs", "nested.md"), nestedSource); + const nestedNotReviewed = spawnSync("node", [ + cliPath, "check", "docs/nested.md", "--manifest", "manifest.json", + "--root", fixtureRoot, + ], { cwd: consumer, encoding: "utf8" }); + assert.notEqual(nestedNotReviewed.status, 0, + "Packed CLI must fail closed on unmaterialized nested thl code"); + assert.match(nestedNotReviewed.stderr, + /THL_UNRESOLVED.*docs\/nested.md:10:5 thl #0/, + "Source location and ordinal must come from nested mdast code node"); + assert.match(cli("materialize", "--document", "docs/nested.md", + "--ordinal", "0", "--artifact", "artifacts/counter.json", + "--manifest", "manifest.json", "--root", fixtureRoot), + /THL_UNREVIEWED.*docs\/nested.md:10:5 thl #0/); + const pendingNested = JSON.parse(readFileSync(manifestLocation, "utf8")); + assert.deepEqual(pendingNested.entries.map(entry => entry.document), + ["docs/nested.md", "docs/sample.mdx"]); + assert.equal(pendingNested.entries[0].ordinal, 0); + assert.equal(pendingNested.entries[0].review, "unreviewed"); + const nestedNeedsApproval = spawnSync("node", [cliPath, "check", ".", + "--manifest", "manifest.json", "--root", fixtureRoot], + { cwd: consumer, encoding: "utf8" }); + assert.notEqual(nestedNeedsApproval.status, 0); + assert.match(nestedNeedsApproval.stderr, /THL_UNREVIEWED/); + pendingNested.entries[0].review = "reviewed"; // separate trusted test-only review + writeFileSync(manifestLocation, JSON.stringify(pendingNested)); + assert.match(cli("check", ".", "--manifest", "manifest.json", "--root", fixtureRoot), + /checked 2 document\(s\), 3 thl block\(s\)/); + + assert(!existsSync(join(consumer, "node_modules", "react")) && + !!existsSync(join(consumer, "node_modules", "unified")) && + !!existsSync(join(consumer, "node_modules", "remark-mdx")), + "CLI/Node host must not require React, but must carry its non-evaluating syntax parsers"); + const core = [ 'import assert from "node:assert/strict";', - 'import { compile, ProgramError, compileArtifact, inspectTrace, projectView, projectInspection } from "@0xbuff/throughline";', + 'import * as publicCore from "@0xbuff/throughline";', + 'import { compileArtifact, inspectTrace, projectView, projectInspection, resolveThlBody } from "@0xbuff/throughline";', 'import { EXAMPLES } from "@0xbuff/throughline/examples";', 'assert(Array.isArray(EXAMPLES) && EXAMPLES.length === 4);', 'assert(EXAMPLES.every(example => example.artifact.schemaVersion === 2 && example.questions.length >= 3));', 'assert(compileArtifact(EXAMPLES[0].artifact).frames.length > 2);', - 'assert.throws(() => compile("not a thl block"), ProgramError);', + 'assert.equal("compile" in publicCore, false);', + 'assert.equal("SUPPORTED_DOMAINS" in publicCore, false);', + 'assert.throws(() => resolveThlBody("{bad"), /invalid JSON/);', 'const artifact = { schemaVersion: 2, id: "counter", origins: [{ id: "author", kind: "authored" }], entities: [{ id: "counter", label: "Counter" }], relations: [], initialState: { counter: { status: "known", value: 0 } }, steps: [{ id: "increment", label: "Increment", events: [{ id: "write", originId: "author", type: "write", entityId: "counter", path: [], value: { status: "known", value: 1 } }] }] };', 'const compiled = compileArtifact(artifact);', 'assert.deepEqual(compiled.frames.map(frame => frame.id), ["@initial", "increment"]);', @@ -215,7 +327,7 @@ try { writeFileSync( join(consumer, "index.ts"), [ - 'import { compile, compileArtifact, inspectTrace, projectView, projectInspection, type Trace, type VisualArtifact, type CompiledTrace, type TraceInspector, type QueryCell, type StateChange, type HistoryEntry, type PresenceChange, type SemanticEvent, type ViewRequest, type ViewDescriptor, type ViewItem, type ViewKind, type InspectionRequest, type InspectionView, type InspectionRecorded } from "@0xbuff/throughline";', + 'import { compileArtifact, inspectTrace, projectView, projectInspection, type VisualArtifact, type CompiledTrace, type TraceInspector, type QueryCell, type StateChange, type HistoryEntry, type PresenceChange, type SemanticEvent, type ViewRequest, type ViewDescriptor, type ViewItem, type ViewKind, type InspectionRequest, type InspectionView, type InspectionRecorded } from "@0xbuff/throughline";', 'import { EXAMPLES } from "@0xbuff/throughline/examples";', 'const trace: CompiledTrace = compileArtifact(EXAMPLES[0]!.artifact);', 'const frames: number = trace.frames.length;', @@ -383,14 +495,10 @@ try { 'import assert from "node:assert/strict";', 'import { createElement } from "react";', 'import { renderToString } from "react-dom/server";', - 'import { compile, compileArtifact } from "@0xbuff/throughline";', - 'import { ThroughlinePlayer, ThroughlineGraphPlayer } from "@0xbuff/throughline/react";', - 'const fence = String.fromCharCode(96).repeat(3);', - 'const trace = compile([fence+"thl binary","a = 1","b = 1",fence].join(String.fromCharCode(10)));', - 'const html = renderToString(createElement(ThroughlinePlayer, { trace }));', - 'assert(html.includes("Visualization player"));', - 'assert.throws(() => renderToString(createElement(ThroughlinePlayer, { trace: { ...trace, version: 2 } })), /Expected trace version 1/);', - 'assert.throws(() => renderToString(createElement(ThroughlinePlayer, { trace: { ...trace, frames: null } })), /Expected trace version 1/);', + 'import { compileArtifact } from "@0xbuff/throughline";', + 'import { ThroughlineGraphPlayer } from "@0xbuff/throughline/react";', + 'import * as publishedReact from "@0xbuff/throughline/react";', + 'assert.deepEqual(Object.keys(publishedReact).sort(), ["ThroughlineEmbed", "ThroughlineGraphPlayer"].sort());', 'const v2Model = { schemaVersion: 2, id: "ssr", origins: [{ id: "author", kind: "authored" }], entities: [{ id: "alpha", label: "Alpha" }, { id: "beta", label: "Beta" }], relations: [{ id: "link", from: "alpha", to: "beta" }], initialState: { alpha: { status: "known", value: 1 }, beta: { status: "unknown", reason: "unobserved" } }, steps: [{ id: "sendStep", label: "Send", events: [{ id: "send", type: "message", originId: "author", relationId: "link", messageId: "message", phase: "sent" }] }] };', 'const v2 = compileArtifact(v2Model);', 'const graphHtml = renderToString(createElement(ThroughlineGraphPlayer, { trace: v2, initialView: "graph" }));', diff --git a/scripts/audit-source.mjs b/scripts/audit-source.mjs index c27ee31a..e47e7121 100644 --- a/scripts/audit-source.mjs +++ b/scripts/audit-source.mjs @@ -129,7 +129,7 @@ for (const path of paths) { } } -for (const name of ["cn", "react", "react-dom"]) { +for (const name of ["cn", "react", "react-dom", "remark-mdx", "remark-parse", "unified"]) { const dependency = JSON.parse( readFileSync(join(root, "node_modules", name, "package.json"), "utf8"), ); diff --git a/scripts/verify-dist.mjs b/scripts/verify-dist.mjs index 2b64a3a4..2c049f3b 100644 --- a/scripts/verify-dist.mjs +++ b/scripts/verify-dist.mjs @@ -1,4 +1,5 @@ import assert from "node:assert/strict"; +import { spawnSync } from "node:child_process"; import { existsSync, readFileSync, readdirSync } from "node:fs"; import { dirname, isAbsolute, relative, resolve } from "node:path"; import { fileURLToPath, pathToFileURL } from "node:url"; @@ -10,6 +11,7 @@ const expected = [ "./react", "./remark", "./examples", + "./node", "./styles/throughline.css", ]; assert.deepEqual(Object.keys(manifest.exports).sort(), expected.sort()); @@ -51,37 +53,70 @@ assert( // With more than one compiler entry, Rolldown may emit a source-less // re-export facade for the root, with executable core in a mapped chunk. -for (const filename of ["react/index.js", "remark/index.js", "examples.js"]) { - assert( - existsSync(resolve(root, "dist", `${filename}.map`)), - `Missing JavaScript source map: ${filename}.map`, - ); +for (const filename of ["react/index.js", "remark/index.js", "examples.js", "node/index.js", "cli/main.js"]) { + if (!existsSync(resolve(root, "dist", filename + ".map"))) { + // Rolldown emits a source-less re-export facade when shared code + // is emitted into a separately mapped chunk. + const facade = readFileSync(resolve(root, "dist", filename), "utf8"); + assert( + facade.length < 1024 && (facade.includes("export") || facade.includes("from")), + "Missing JavaScript source map or mapped facade: " + filename, + ); + } } if (!existsSync(resolve(root, "dist/index.js.map"))) { const rootFacade = readFileSync(resolve(root, "dist/index.js"), "utf8"); assert( - rootFacade.length < 1024 && - artifacts.some((file) => /^registry-.*\.js\.map$/.test(file)), - "Unmapped root entry must remain a small facade backed by mapped core code", + rootFacade.length < 16 * 1024 && + (rootFacade.includes("export") || rootFacade.includes("from")) && + artifacts.some((file) => file.endsWith(".js.map")), + "Unmapped root entry must be a bounded re-export facade with mapped chunks (size=" + rootFacade.length + ", maps=" + artifacts.filter(f => f.endsWith(".js.map")).length + ")", ); } const load = (entry) => import(pathToFileURL(resolve(root, "dist", entry)).href); -const { compile } = await load("index.js"); -assert.equal(typeof compile, "function"); -const trace = compile("```thl binary\na = 1\nb = 1\n```"); -assert.deepEqual( - trace.frames.at(-1)?.state.entities.find((entity) => entity.id === "sum") - ?.value, - [1, 0], -); +// Node validation is a completely separate entry: the core must not import IO. +const { createNodeThroughlineHost } = await load("node/index.js"); +assert.equal(typeof createNodeThroughlineHost, "function"); +assert.equal(manifest.bin?.thl, "./dist/cli/main.js"); +const cli = resolve(root, manifest.bin.thl); +assert(existsSync(cli), "Missing published standalone thl binary"); +assert.match(readFileSync(cli, "utf8").slice(0, 80), /^#!\/usr\/bin\/env node/, + "CLI executable requires a Node shebang"); +const help = spawnSync(process.execPath, [cli, "help"], { cwd: root, encoding: "utf8" }); +assert.equal(help.status, 0, help.stderr); +assert.match(help.stdout, /thl materialize/); +// Keep the pure package root free of Node-only and React dependencies. +const pure = readFileSync(resolve(root, "dist/index.js"), "utf8"); +assert(!pure.includes("node:fs") && !pure.includes("node:crypto"), + "Core root must not import CLI filesystem or crypto dependencies"); +const core = await load("index.js"); +assert.equal(typeof core.compile, "undefined", "Old domain compiler is not exported"); +assert.equal(typeof core.SUPPORTED_DOMAINS, "undefined", "Old domain router not public"); +assert.equal(typeof core.compileArtifact, "function"); +const exampleArtifact = { + schemaVersion: 2, id: "counter", + origins: [{ id: "author", kind: "authored" }], + entities: [{ id: "counter", label: "Counter" }], relations: [], + initialState: { counter: { status: "known", value: 0 } }, + steps: [{ id: "increment", label: "Increment", events: [ + { id: "write", originId: "author", type: "write", + entityId: "counter", path: [], value: { status: "known", value: 1 } }, + ] }], +}; +const trace = core.compileArtifact(exampleArtifact); +assert.deepEqual(trace.frames.map(frame => frame.id), ["@initial", "increment"]); +const cell = core.inspectTrace(trace).valueAt(1, "counter"); +assert.equal(cell.status, "known"); +assert.equal(cell.value, 1); +assert.equal(Object.getPrototypeOf(cell), null, "Queried cells must be immutable plain data"); const { remarkThroughline } = await load("remark/index.js"); assert.equal(typeof remarkThroughline, "function"); const { EXAMPLES } = await load("examples.js"); assert(Array.isArray(EXAMPLES) && EXAMPLES.length === 4); assert(EXAMPLES.every(example => example.artifact.schemaVersion === 2 && Array.isArray(example.questions) && example.questions.length >= 3)); -const { ThroughlinePlayer } = await load("react/index.js"); -assert.equal(typeof ThroughlinePlayer, "function"); +const react = await load("react/index.js"); +assert.deepEqual(Object.keys(react).sort(), ["ThroughlineEmbed", "ThroughlineGraphPlayer"].sort()); console.log("Throughline build exports, declarations, maps and smoke checks passed."); diff --git a/src/__tests__/cli.test.ts b/src/__tests__/cli.test.ts new file mode 100644 index 00000000..b857d641 --- /dev/null +++ b/src/__tests__/cli.test.ts @@ -0,0 +1,332 @@ +import { + mkdtempSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync, +} from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { afterEach, describe, expect, it } from "vitest"; +import remarkMdx from "remark-mdx"; +import remarkParse from "remark-parse"; +import { unified } from "unified"; +import { runCli } from "../cli/commands.js"; +import { createNodeThroughlineHost, scanMarkdownFences, TrustedContentRoot } from "../node/index.js"; +import { resolveThlBody, sha256Text, type SidecarManifest } from "../index.js"; + +const folders: string[] = []; +function root(): string { + const folder = mkdtempSync(join(tmpdir(), "throughline-cli-")); + folders.push(folder); + return folder; +} +afterEach(() => { + for (const folder of folders.splice(0)) rmSync(folder, { recursive: true, force: true }); +}); +const counter = (id = "counter") => JSON.stringify({ + schemaVersion: 2, id, + origins: [{ id: "author", kind: "authored" }], + entities: [{ id: "counter", label: "Counter" }], relations: [], + initialState: { counter: { status: "known", value: 0 } }, + steps: [{ id: "increment", label: "Increment", events: [ + { id: "update", type: "write", originId: "author", + entityId: "counter", path: [], value: { status: "known", value: 1 } }, + ] }], +}); +function capture(argv: string[]): { status: number; out: string; err: string } { + const out: string[] = [], err: string[] = []; + const status = runCli(argv, { + out: line => out.push(line), err: line => err.push(line), + }); + return { status, out: out.join("\n"), err: err.join("\n") }; +} +function fixture() { + const directory = root(); + mkdirSync(join(directory, "docs")); + mkdirSync(join(directory, "artifacts")); + writeFileSync(join(directory, "artifacts", "counter.json"), counter()); + writeFileSync(join(directory, "docs", "intro.mdx"), [ + "# Example", "", "Some **normal Markdown** and math $x + y$.", "", + "~~~javascript", "console.log('not executed')", "~~~", "", + "~~~thl", "Explain the counter.\r\nShow its explicit writes.", "~~~", "", + "~~~mermaid", "graph TD; A-->B", "~~~", "", + "~~~thl", counter(), "~~~", + ].join("\n")); + return directory; +} +function approve(directory: string) { + const path = join(directory, "manifest.json"); + const source = JSON.parse(readFileSync(path, "utf8")) as SidecarManifest; + writeFileSync(path, JSON.stringify({ + ...source, entries: source.entries.map(entry => ({ ...entry, review: "reviewed" })), + }, null, 2)); +} + +describe("TL-U10 CLI / source and sidecar boundary", () => { + it("runs all three commands, fails closed until review and keeps deterministic locator hashes", () => { + const directory = fixture(); + const base = ["--root", directory]; + const valid = capture(["validate", "artifacts/counter.json", ...base]); + expect(valid.status).toBe(0); + expect(valid.out).toMatch(/THL_OK validate.*schema=2.*steps=1.*sha256=[0-9a-f]{64}/); + const jsonOnly = capture(["check", "docs/intro.mdx", ...base]); + expect(jsonOnly.status).toBe(1); + expect(jsonOnly.err).toMatch(/THL_UNRESOLVED.*docs\/intro.mdx:9:1 thl #0/); + const materialized = capture(["materialize", "--document", "docs/intro.mdx", + "--ordinal", "0", "--artifact", "artifacts/counter.json", + "--manifest", "manifest.json", ...base]); + expect(materialized.status).toBe(0); + expect(materialized.out).toMatch(/THL_UNREVIEWED materialize/); + let manifest = JSON.parse(readFileSync(join(directory, "manifest.json"), "utf8")) as SidecarManifest; + expect(manifest.entries).toHaveLength(1); + expect(manifest.entries[0].document).toBe("docs/intro.mdx"); + expect(manifest.entries[0].ordinal).toBe(0); + expect(manifest.entries[0].review).toBe("unreviewed"); + expect(manifest.entries[0].intentSha256) + .toBe(sha256Text("Explain the counter.\nShow its explicit writes.")); + const unreviewed = capture(["check", "docs", "--manifest", "manifest.json", ...base]); + expect(unreviewed.status).toBe(1); + expect(unreviewed.err).toMatch(/THL_UNREVIEWED/); + approve(directory); + const checked = capture(["check", ".", "--manifest", "manifest.json", ...base]); + expect(checked.status).toBe(0); + expect(checked.out).toMatch(/checked 1 document\(s\), 2 thl block\(s\)/); + expect(checked.out).toMatch(/thl #1/); + const host = createNodeThroughlineHost({ root: directory, manifestPath: "manifest.json" }); + const relative = host.documentForFile(join(directory, "docs", "intro.mdx")); + expect(relative).toBe("docs/intro.mdx"); + expect(resolveThlBody("Explain the counter.\r\nShow its explicit writes.", { + document: relative, ordinal: 0, manifest: host.manifest, + loadArtifact: host.loadArtifact, + }).id).toBe("counter"); + // A second materialization must invalidate a prior review. + expect(capture(["materialize", "--document", "docs/intro.mdx", + "--ordinal", "0", "--artifact", "artifacts/counter.json", + "--manifest", "manifest.json", ...base]).status).toBe(0); + manifest = JSON.parse(readFileSync(join(directory, "manifest.json"), "utf8")) as SidecarManifest; + expect(manifest.entries[0].review).toBe("unreviewed"); + }); + + it("keeps unrelated Markdown/Math/Mermaid outside the thl ordinal contract", () => { + const markdown = [ + "~~~mdx", "text", "~~~", "", + "> ~~~thl", "> Explain nested quote.", "> ~~~", "", + "- ~~~thl", " Explain nested list.", " ~~~", "", + " ~~~thl", " Continuation nested in the list.", " ~~~", "", + "~~~thl binary", "meta is unsupported", "~~~", "", + "~~~mermaid", "graph TD", "~~~", + ].join("\n"); + const nodes = scanMarkdownFences(markdown); + expect(nodes.filter(node => node.lang === "thl") + .map(node => [node.ordinal, node.body])).toEqual([ + [0, "Explain nested quote."], [1, "Explain nested list."], + [2, "Continuation nested in the list."], + [3, "meta is unsupported"], + ]); + expect(nodes.filter(node => node.lang === "mermaid")).toHaveLength(1); + const directory = fixture(); + writeFileSync(join(directory, "docs", "nested.mdx"), markdown); + const result = capture(["check", "docs/nested.mdx", "--root", directory]); + expect(result.err).toMatch(/THL_UNRESOLVED.*thl #0/); + }); + + + it("finds deeply nested CommonMark code nodes in exact depth-first order; ignores HTML comments and code-like text", () => { + const input = [ + "# Real Markdown", "", + "", "", + "- Parent", " - Child", "", + " ~~~thl", " Explain the nested system.", " ~~~", "", + "~~~javascript", "const fake = String.raw`~~~thl`;", "~~~", "", + "> ~~~thl", "> Explain the quoted system.", "> ~~~", "", + "~~~thl", "Explain the final system.", "~~~", "", + " ~~~thl", " Indented literal text, not a fence", " ~~~", + ].join("\n"); + const nodes = scanMarkdownFences(input, { format: "md" }); + expect(nodes.filter(node => node.lang === "thl") + .map(node => [node.ordinal, node.line, node.column, node.body])) + .toEqual([ + [0, 12, 5, "Explain the nested system."], + [1, 20, 3, "Explain the quoted system."], + [2, 24, 1, "Explain the final system."], + ]); + // Compare with an independent traversal of the parser's actual mdast. + const tree = unified().use(remarkParse).parse(input); + const expected: Array<{ value?: string; line?: number; column?: number }> = []; + const visit = (node: { type: string; children?: readonly unknown[]; + lang?: string | null; value?: string; + position?: { start: { line: number; column: number } } }): void => { + if (node.type === "code" && node.lang === "thl") + expected.push({ + value: node.value, + line: node.position?.start.line, + column: node.position?.start.column, + }); + for (const child of node.children ?? []) + visit(child as typeof node); + }; + visit(tree); + expect(nodes.filter(node => node.lang === "thl") + .map(node => ({ value: node.body, line: node.line, column: node.column }))) + .toEqual(expected); + + const directory = fixture(); + writeFileSync(join(directory, "docs", "deep.md"), input); + const checked = capture(["check", "docs/deep.md", "--root", directory]); + expect(checked.status).toBe(1); + expect(checked.err).toMatch(/THL_UNRESOLVED.*docs\/deep.md:12:5 thl #0/); + const materialized = capture(["materialize", "--document", "docs/deep.md", + "--ordinal", "0", "--artifact", "artifacts/counter.json", + "--manifest", "manifest.json", "--root", directory]); + expect(materialized.status).toBe(0); + const saved = JSON.parse(readFileSync(join(directory, "manifest.json"), "utf8")) as SidecarManifest; + expect(saved.entries).toHaveLength(1); + expect(saved.entries[0].ordinal).toBe(0); + expect(saved.entries[0].intentSha256).toBe(sha256Text("Explain the nested system.")); + const second = capture(["materialize", "--document", "docs/deep.md", + "--ordinal", "1", "--artifact", "artifacts/counter.json", + "--manifest", "manifest.json", "--root", directory]); + expect(second.status).toBe(0); + const updated = JSON.parse(readFileSync(join(directory, "manifest.json"), "utf8")) as SidecarManifest; + expect(updated.entries.map(entry => entry.ordinal)).toEqual([0, 1]); + }); + + it("uses a non-evaluating MDX AST; excludes expression-like fake fences and preserves nested JSX codes", () => { + const input = [ + "# MDX", "", + "{/*", "~~~thl", "This is an MDX expression comment.", "~~~", "*/}", "", + "", "", + " ~~~thl", + " Explain the real JSX-child model.", + " ~~~", "", + "", "", + "~~~thl", + "Explain another valid block.", + "~~~", + ].join("\n"); + const nodes = scanMarkdownFences(input, { format: "mdx" }) + .filter(node => node.lang === "thl"); + const tree = unified().use(remarkParse).use(remarkMdx).parse(input); + const expected: string[] = []; + const traverse = (node: { type: string; children?: readonly unknown[]; + lang?: string | null; value?: string }): void => { + if (node.type === "code" && node.lang === "thl") + expected.push(node.value ?? ""); + for (const child of node.children ?? []) + traverse(child as typeof node); + }; + traverse(tree); + expect(nodes.map(node => node.body)).toEqual(expected); + expect(nodes.map(node => node.ordinal)).toEqual([0, 1]); + expect(nodes.map(node => node.body)).toEqual([ + "Explain the real JSX-child model.", + "Explain another valid block.", + ]); + const directory = fixture(); + writeFileSync(join(directory, "docs", "jsx.mdx"), input); + const check = capture(["check", "docs/jsx.mdx", "--root", directory]); + expect(check.status).toBe(1); + expect(check.err).toMatch(/THL_UNRESOLVED.*docs\/jsx.mdx:11:3 thl #0/); + }); + + it("does not mistake Markdown HTML comments for unresolved prose", () => { + const directory = fixture(); + const commented = [ + "", "", + "# A normal document", + "~~~js", "console.log('no code execution')", "~~~", + ].join("\n"); + writeFileSync(join(directory, "docs", "comments.md"), commented); + expect(scanMarkdownFences(commented, { format: "md" }) + .some(node => node.lang === "thl")).toBe(false); + const check = capture(["check", "docs/comments.md", "--root", directory]); + expect(check.status).toBe(0); + expect(check.out).toMatch(/checked 1 document\(s\), 0 thl block\(s\)/); + const materialize = capture(["materialize", "--document", "docs/comments.md", + "--ordinal", "0", "--artifact", "artifacts/counter.json", + "--manifest", "manifest.json", "--root", directory]); + expect(materialize.status).toBe(1); + expect(materialize.err).toMatch(/THL_UNRESOLVED.*thl #0 does not exist/); + }); + + it("fails closed on malformed MDX syntax instead of silently reporting zero fences", () => { + const directory = fixture(); + writeFileSync(join(directory, "docs", "broken.mdx"), "{not a valid mdx expression"); + const check = capture(["check", "docs/broken.mdx", "--root", directory]); + expect(check.status).toBe(1); + expect(check.err).toMatch(/THL_SYNTAX.*invalid MDX syntax/); + }); + + it("rejects stale edits, mismatched artifact digests, duplicate locators and metadata", () => { + const directory = fixture(); + const base = ["--root", directory]; + const make = () => capture(["materialize", "--document", "docs/intro.mdx", + "--ordinal", "0", "--artifact", "artifacts/counter.json", + "--manifest", "manifest.json", ...base]); + expect(make().status).toBe(0); + approve(directory); + const md = join(directory, "docs", "intro.mdx"); + const original = readFileSync(md, "utf8"); + writeFileSync(md, original.replace("Explain the counter.", "Explain a changed counter.")); + expect(capture(["check", "docs/intro.mdx", "--manifest", "manifest.json", ...base]).err) + .toMatch(/THL_DIGEST.*docs\/intro.mdx/); + writeFileSync(md, original); + writeFileSync(join(directory, "artifacts", "counter.json"), counter("different")); + expect(capture(["check", "docs/intro.mdx", "--manifest", "manifest.json", ...base]).err) + .toMatch(/THL_DIGEST/); + writeFileSync(join(directory, "artifacts", "counter.json"), counter()); + const manifest = JSON.parse(readFileSync(join(directory, "manifest.json"), "utf8")) as SidecarManifest; + writeFileSync(join(directory, "manifest.json"), JSON.stringify({ + version: 1, entries: [manifest.entries[0], manifest.entries[0]], + })); + expect(capture(["check", "docs/intro.mdx", "--manifest", "manifest.json", ...base]).err) + .toMatch(/THL_MANIFEST.*duplicate/); + writeFileSync(join(directory, "manifest.json"), '{"version":1,"version":1,"entries":[]}'); + expect(capture(["check", "docs/intro.mdx", "--manifest", "manifest.json", ...base]).err) + .toMatch(/THL_ARTIFACT_SYNTAX.*duplicate object key/); + writeFileSync(md, original.replace("~~~thl\n", "~~~thl flow\n")); + expect(capture(["check", "docs/intro.mdx", ...base]).err).toMatch(/THL_SYNTAX.*metadata/); + }); + + it("rejects traversal, absolute artifact paths and symlink escapes without leaking contents", () => { + const directory = fixture(); + const outside = root(); + writeFileSync(join(outside, "sensitive.json"), counter("private")); + symlinkSync(outside, join(directory, "escape")); + const base = ["--root", directory]; + for (const attempt of [ + ["validate", "../sensitive.json", ...base], + ["validate", "/tmp/sensitive.json", ...base], + ["validate", "escape/sensitive.json", ...base], + ["materialize", "--document", "docs/intro.mdx", "--ordinal", "0", + "--artifact", "escape/sensitive.json", "--manifest", "manifest.json", ...base], + ]) { + const result = capture(attempt); + expect(result.status).toBe(1); + expect(result.err).toMatch(/THL_PATH|THL_IO/); + expect(result.err).not.toContain("private"); + } + expect(() => createNodeThroughlineHost({ root: directory, + manifestPath: "escape/sensitive.json" })).toThrow(/THL_PATH/); + expect(() => new TrustedContentRoot(directory).relativeForFile( + join(outside, "sensitive.json"))).toThrow(/THL_PATH/); + }); + + it("rejects unsupported JSON and destructive or incomplete arguments with stable codes", () => { + const directory = fixture(); + const artifact = join(directory, "artifacts", "counter.json"); + const base = ["--root", directory]; + const cases = [ + ['{"schemaVersion":1}', "THL_ARTIFACT_VERSION"], + ['{"schemaVersion":2,"schemaVersion":2}', "THL_ARTIFACT_SYNTAX"], + ['{"schemaVersion":2}', "THL_ARTIFACT_SHAPE"], + ] as const; + for (const [text, code] of cases) { + writeFileSync(artifact, text); + expect(capture(["validate", "artifacts/counter.json", ...base]).err).toContain(code); + } + expect(capture(["materialize", "--document", "docs/intro.mdx", + "--ordinal", "-1", "--artifact", "artifacts/counter.json", + "--manifest", "manifest.json", ...base]).err).toContain("THL_USAGE"); + expect(capture(["materialize", "--document", "docs/intro.mdx", ...base]).err) + .toContain("THL_USAGE"); + expect(capture(["nonsense", ...base]).err).toContain("THL_USAGE"); + }); +}); diff --git a/src/__tests__/compilation-limits.test.ts b/src/__tests__/compilation-limits.test.ts index 91e2fb68..35c7b2c2 100644 --- a/src/__tests__/compilation-limits.test.ts +++ b/src/__tests__/compilation-limits.test.ts @@ -1,11 +1,7 @@ import { describe, expect, it } from "vitest"; -import { - compile, - compileAst, - compileProgram, - ProgramError, - validateProgram, -} from "../index.js"; +import { compile, compileAst } from "../domains/registry.js"; +import { compileProgram, validateProgram } from "../compiler.js"; +import { ProgramError } from "../model.js"; import type { Program } from "../model.js"; const program = (value: unknown) => ({ diff --git a/src/__tests__/dsl.test.ts b/src/__tests__/dsl.test.ts index 2b6721ec..d2e028b1 100644 --- a/src/__tests__/dsl.test.ts +++ b/src/__tests__/dsl.test.ts @@ -1,5 +1,7 @@ import { describe, expect, it } from "vitest"; -import { compile, compileAst, ProgramError, parseThl } from "../index.js"; +import { compile, compileAst } from "../domains/registry.js"; +import { ProgramError } from "../model.js"; +import { parseThl } from "../dsl.js"; const FLOW = 'node a "A" = 1\nstep "Read"\nfocus a'; diff --git a/src/cli/commands.ts b/src/cli/commands.ts new file mode 100644 index 00000000..38a53c50 --- /dev/null +++ b/src/cli/commands.ts @@ -0,0 +1,227 @@ +import { + artifactRelativePath, artifactSha256, parseIntentBlock, resolveThlBody, + ThroughlineAuthoringError, validateSidecarManifest, + type SidecarEntry, type SidecarManifest, +} from "../v2/authoring.js"; +import { compileArtifact } from "../v2/compiler.js"; +import { sha256Text } from "../v2/sha256.js"; +import { ArtifactValidationError, parseArtifactJson } from "../v2/validator.js"; +import { TrustedContentRoot, TrustedFileError } from "../node/files.js"; +import { scanMarkdownFences } from "../node/markdown.js"; +import { readSidecarManifest } from "../node/index.js"; + +type CliIO = Readonly<{ out: (line: string) => void; err: (line: string) => void }>; +const defaultIO: CliIO = { out: line => console.log(line), err: line => console.error(line) }; + +export class ThroughlineCliError extends Error { + constructor(readonly code: string, message: string) { + super(message); + this.name = "ThroughlineCliError"; + } +} +function usage(message: string): never { + throw new ThroughlineCliError("THL_USAGE", message); +} +const HELP = [ + "Throughline schema-2 CLI (offline, Node 24+)", + " thl validate artifact.json [--root ROOT]", + " thl materialize --document FILE --ordinal N --artifact FILE --manifest FILE [--root ROOT]", + " thl check FILE_OR_DIR [--manifest FILE] [--root ROOT]", + " thl help", + "All paths except ROOT are repository-relative POSIX paths. ROOT defaults to cwd.", + "Materialization always writes review=unreviewed; approve in a separate source review.", +].join("\n"); + +type Arguments = Readonly<{ positionals: readonly string[]; options: Readonly> }>; +function argumentsOf(values: readonly string[]): Arguments { + const positionals: string[] = []; + const options: Record = Object.create(null) as Record; + for (let i = 0; i < values.length; i++) { + const arg = values[i]; + if (!arg.startsWith("--")) { positionals.push(arg); continue; } + if (!["--document", "--ordinal", "--artifact", "--manifest", "--root"].includes(arg)) + usage("unsupported option: " + arg); + const field = arg.slice(2); + if (Object.hasOwn(options, field)) usage("duplicate option: " + arg); + if (i + 1 >= values.length || values[i + 1].startsWith("--")) + usage("missing value for " + arg); + options[field] = values[++i]; + } + return { positionals, options }; +} +function flag(options: Arguments, key: string): string { + const value = options.options[key]; + if (value === undefined || value === "") usage("required option --" + key); + return value; +} +function keysOnly(options: Arguments, allowed: string[]): void { + for (const key of Object.keys(options.options)) + if (!allowed.includes(key)) usage("unsupported option for this command: --" + key); +} +function sourcePath(source: string): string { + return artifactRelativePath(source); +} + +function toDiagnostic(error: unknown): { code: string; message: string } { + if (error instanceof ThroughlineCliError) + return { code: error.code, message: error.message }; + if (error instanceof ThroughlineAuthoringError || + error instanceof TrustedFileError) + return { code: error.code, message: error.message.replace(/^[A-Z_]+: /, "") }; + if (error instanceof ArtifactValidationError) { + const message = error.message; + let code: string; + if (error.name === "ArtifactCompilationError") { + code = /conflict|overlap|same.step/i.test(message) + ? "THL_ARTIFACT_CONFLICT" : "THL_ARTIFACT_COMPILATION"; + } else if (/duplicate object key|invalid JSON|at offset|unexpected trailing content/i.test(message)) { + code = "THL_ARTIFACT_SYNTAX"; + } else if (/schemaVersion|unsupported artifact schema/i.test(message)) { + code = "THL_ARTIFACT_VERSION"; + } else if (/limit|maximum|exceed|4 MiB|depth|too many|budget/i.test(message)) { + code = "THL_ARTIFACT_LIMIT"; + } else if (/undeclared|reference|unknown.*id|missing.*id|dependsOn/i.test(message)) { + code = "THL_ARTIFACT_REFERENCE"; + } else { + code = "THL_ARTIFACT_SHAPE"; + } + return { code, message }; + } + return { code: "THL_INTERNAL", message: "unexpected host failure; no untrusted details disclosed" }; +} +function format(error: unknown, location?: string): string { + const issue = toDiagnostic(error); + return issue.code + ": " + (location ? location + ": " : "") + issue.message; +} +function validateFile(root: TrustedContentRoot, file: string, io: CliIO): void { + const relative = sourcePath(file); + const artifact = compileArtifact(parseArtifactJson(root.read(relative))).artifact; + io.out("THL_OK validate " + relative + " schema=2 id=" + artifact.id + + " steps=" + artifact.steps.length + " sha256=" + artifactSha256(artifact)); +} + +function checkFile( + root: TrustedContentRoot, relative: string, + manifest: SidecarManifest | undefined, io: CliIO, +): number { + const markdown = root.read(relative); + const fences = scanMarkdownFences(markdown, { format: relative.endsWith(".mdx") ? "mdx" : "md" }); + let checked = 0; + for (const fence of fences) { + if (fence.lang !== "thl") continue; + const location = relative + ":" + fence.line + ":" + fence.column + + " thl #" + fence.ordinal; + try { + if (fence.meta !== null) + throw new ThroughlineAuthoringError("THL_SYNTAX", + "only an unqualified thl language fence is supported (no metadata or domain tags)"); + // Canonical source truth: the LF-normalized mdast code-node body + // and a repository-relative, explicitly scoped document locator. + resolveThlBody(fence.body, { + document: relative, + ordinal: fence.ordinal!, + ...(manifest ? { manifest } : {}), + ...(manifest ? { loadArtifact: (artifact: string) => root.read(artifact) } : {}), + }); + } catch (error) { + const issue = toDiagnostic(error); + throw new ThroughlineCliError(issue.code, location + ": " + issue.message); + } + checked++; + io.out("THL_OK check " + location); + } + return checked; +} +function checkTarget(root: TrustedContentRoot, args: Arguments, io: CliIO): void { + keysOnly(args, ["manifest", "root"]); + if (args.positionals.length !== 1) + usage("check expects exactly one Markdown file or directory"); + const target = args.positionals[0]; + const manifest = args.options.manifest === undefined + ? undefined : readSidecarManifest(root, sourcePath(args.options.manifest)); + const paths = root.walkMarkdown(target); + let checked = 0; + for (const path of paths) checked += checkFile(root, path, manifest, io); + io.out("THL_OK checked " + paths.length + " document(s), " + checked + " thl block(s)"); +} +function materialize(root: TrustedContentRoot, args: Arguments, io: CliIO): void { + keysOnly(args, ["document", "ordinal", "artifact", "manifest", "root"]); + if (args.positionals.length !== 0) + usage("materialize takes named arguments only"); + const document = sourcePath(flag(args, "document")); + const artifactPath = sourcePath(flag(args, "artifact")); + const manifestPath = sourcePath(flag(args, "manifest")); + const ordinalRaw = flag(args, "ordinal"); + if (!/^(?:0|[1-9]\d*)$/.test(ordinalRaw) || + !Number.isSafeInteger(Number(ordinalRaw))) + usage("--ordinal must be a zero-based safe integer"); + const ordinal = Number(ordinalRaw); + const fences = scanMarkdownFences(root.read(document), { format: document.endsWith(".mdx") ? "mdx" : "md" }); + const fence = fences.find(f => f.lang === "thl" && f.ordinal === ordinal); + if (!fence) + throw new ThroughlineCliError("THL_UNRESOLVED", + document + ": thl #" + ordinal + " does not exist"); + const location = document + ":" + fence.line + ":" + fence.column + " thl #" + ordinal; + if (fence.meta !== null) + throw new ThroughlineCliError("THL_SYNTAX", location + ": domain tags or metadata are unsupported"); + let body: string; + try { + body = parseIntentBlock(fence.body).body; + } catch (error) { + const issue = toDiagnostic(error); + throw new ThroughlineCliError(issue.code, location + ": " + issue.message); + } + const artifact = compileArtifact(parseArtifactJson(root.read(artifactPath))).artifact; + const entry: SidecarEntry = Object.freeze({ + document, ordinal, intentSha256: sha256Text(body), + artifactPath, artifactSha256: artifactSha256(artifact), + review: "unreviewed", + }); + const prior: SidecarManifest = root.exists(manifestPath) + ? readSidecarManifest(root, manifestPath) + : { version: 1, entries: [] }; + const entries = prior.entries.filter(row => + row.document !== document || row.ordinal !== ordinal); + const ordered = [...entries, entry].sort((left, right) => + left.document < right.document ? -1 : left.document > right.document ? 1 + : left.ordinal - right.ordinal); + const validated = validateSidecarManifest({ version: 1, entries: ordered }); + root.writeManifest(manifestPath, JSON.stringify(validated, null, 2) + "\n"); + io.out("THL_UNREVIEWED materialize " + location + " -> " + artifactPath + + " (manifest " + manifestPath + "; requires separate editorial review)"); +} + +/** + * Synchronous first-party Node CLI. External errors are converted to stable, + * non-secret codes; no command approves materializations or calls providers. + */ +export function runCli(argv: readonly string[], io: CliIO = defaultIO): number { + try { + if (argv.length === 0 || argv[0] === "help" || argv[0] === "--help") { + io.out(HELP); + return argv.length === 0 ? 1 : 0; + } + const command = argv[0]; + if (!["validate", "materialize", "check"].includes(command)) + usage("unknown command: " + command); + const args = argumentsOf(argv.slice(1)); + const root = new TrustedContentRoot(args.options.root ?? process.cwd()); + switch (command) { + case "validate": + keysOnly(args, ["root"]); + if (args.positionals.length !== 1) usage("validate expects one artifact path"); + validateFile(root, args.positionals[0], io); + break; + case "materialize": + materialize(root, args, io); + break; + case "check": + checkTarget(root, args, io); + break; + } + return 0; + } catch (error) { + io.err(format(error)); + return 1; + } +} diff --git a/src/cli/main.ts b/src/cli/main.ts new file mode 100644 index 00000000..0dca15a5 --- /dev/null +++ b/src/cli/main.ts @@ -0,0 +1,4 @@ +#!/usr/bin/env node +import { runCli } from "./commands.js"; + +process.exitCode = runCli(process.argv.slice(2)); diff --git a/src/domains/__tests__/public-api-boundaries.test.ts b/src/domains/__tests__/public-api-boundaries.test.ts index d87fc326..36f346ad 100644 --- a/src/domains/__tests__/public-api-boundaries.test.ts +++ b/src/domains/__tests__/public-api-boundaries.test.ts @@ -1,5 +1,5 @@ import { describe, expect, it } from "vitest"; -import { compile } from "../../index.js"; +import { compile } from "../registry.js"; describe("public compile API domain boundaries", () => { it("preserves leading zeroes when adding a one-bit operand", () => { diff --git a/src/index.ts b/src/index.ts index 4aaa84d7..4ad8ed3f 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,33 +1,6 @@ -/** Pure authoring and compilation API. The optional renderer lives at ./react. */ -export { parseProgram } from "./authoring.js"; -export { compileProgram, validateProgram } from "./compiler.js"; -export { describeFrame } from "./describe.js"; -export { compile, compileAst, SUPPORTED_DOMAINS } from "./domains/registry.js"; -export type { DomainName } from "./domains/types.js"; -export { parseThl, type ThlBlock } from "./dsl.js"; -export { COMPILATION_LIMITS } from "./limits.js"; -export type { - Beat, - Diagnostic, - Entity, - Event, - Frame, - GroupLayout, - Program, - Relation, - SceneGroup, - Snapshot, - SourceLocation, - Trace, - Value, - View, -} from "./model.js"; -export { ProgramError } from "./model.js"; -export { type StepApi, type Tracer, tracer } from "./tracer.js"; - +/** Pure schema-2 Throughline core. No legacy domain compiler or React imports. */ /** - * Schema-2 semantic artifact boundary (TL-U02). The v1 compiler/player - * migration is deliberately separate work in TL-U03–TL-U10. + * Schema-2 semantic artifact boundary (TL-U02). The previous domain-tagged parser is not a public API. */ export { ARTIFACT_LIMITS, @@ -45,6 +18,7 @@ export type { PresenceChange, TraceInspector, WriteChange, + Entity, Entity as V2Entity, EventBase, Group, @@ -54,6 +28,7 @@ export type { OriginKind, Path, QueryCell, + Relation, Relation as V2Relation, SemanticEvent, Step, diff --git a/src/node/files.ts b/src/node/files.ts new file mode 100644 index 00000000..e6614f99 --- /dev/null +++ b/src/node/files.ts @@ -0,0 +1,190 @@ +import { + closeSync, constants, fstatSync, fsyncSync, lstatSync, + openSync, readFileSync, readdirSync, realpathSync, renameSync, + unlinkSync, writeFileSync, +} from "node:fs"; +import { randomBytes } from "node:crypto"; +import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path"; +import { artifactRelativePath } from "../v2/authoring.js"; + +export class TrustedFileError extends Error { + constructor( + readonly code: "THL_IO" | "THL_PATH" | "THL_LIMIT", + message: string, + ) { + super(code + ": " + message); + this.name = "TrustedFileError"; + } +} +function fault(code: TrustedFileError["code"], message: string): never { + throw new TrustedFileError(code, message); +} +function within(root: string, absolute: string): boolean { + const path = relative(root, absolute); + return path === "" || (path !== ".." && !path.startsWith(".." + sep) && !isAbsolute(path)); +} +const utf8 = new TextDecoder("utf-8", { fatal: true }); +const DEFAULT_MAX_BYTES = 4 * 1024 * 1024; +const EXCLUDED_DIRECTORIES = new Set([ + ".git", "node_modules", ".next", ".astro", "dist", "build", "coverage", ".turbo", +]); + +/** + * A trusted filesystem root for first-party Node CLI and host plugins. + * Every relative name passes the pure POSIX locator validator; all traversed + * paths must stay inside the real root and must not be symbolic links. + * + * The library code never imports this module. In particular, host paths + * cannot come from Markdown/MDX content. Only trusted CLI/host config may + * select the root. + */ +export class TrustedContentRoot { + readonly root!: string; + constructor(path: string = process.cwd()) { + let root: string; + try { + root = realpathSync(resolve(path)); + if (!lstatSync(root).isDirectory()) fault("THL_PATH", "trusted root must be a directory"); + } catch { + return fault("THL_PATH", "cannot open trusted content root"); + } + this.root = root; + } + + /** Check the full path's parent chain without following any symlink. */ + private guarded(relativePath: string, allowMissingFile = false): string { + const document = artifactRelativePath(relativePath); + const segments = document.split("/"); + let current = this.root; + for (const [index, segment] of segments.entries()) { + current = join(current, segment); + if (!within(this.root, current)) fault("THL_PATH", "file escapes trusted content root"); + try { + const info = lstatSync(current); + if (info.isSymbolicLink()) fault("THL_PATH", "symbolic link forbidden in trusted content path: " + document); + if (index < segments.length - 1 && !info.isDirectory()) + fault("THL_PATH", "content path parent must be a directory: " + document); + } catch (error) { + if (error instanceof TrustedFileError) throw error; + if (allowMissingFile && index === segments.length - 1 && + (error as NodeJS.ErrnoException).code === "ENOENT") return current; + fault("THL_IO", "content path is not accessible: " + document); + } + } + try { + if (!within(this.root, realpathSync(current))) + fault("THL_PATH", "resolved content path escapes trusted root"); + } catch (error) { + if (error instanceof TrustedFileError) throw error; + if (!allowMissingFile) fault("THL_IO", "cannot resolve content path: " + document); + } + return current; + } + + relativeForFile(filePath: string): string { + if (typeof filePath !== "string" || !filePath) + fault("THL_PATH", "host VFile path is missing"); + const absolute = resolve(filePath); + if (!within(this.root, absolute) || absolute === this.root) + fault("THL_PATH", "host VFile path is outside trusted root"); + const candidate = relative(this.root, absolute).split(sep).join("/"); + this.guarded(candidate); + return artifactRelativePath(candidate); + } + + read(relativePath: string, maxBytes = DEFAULT_MAX_BYTES): string { + const name = artifactRelativePath(relativePath); + const absolute = this.guarded(name); + let fd: number | undefined; + try { + fd = openSync(absolute, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0)); + const stat = fstatSync(fd); + if (!stat.isFile()) fault("THL_IO", "content is not a regular file: " + name); + if (stat.size > maxBytes) fault("THL_LIMIT", "content exceeds file limit: " + name); + const bytes = readFileSync(fd); + if (bytes.length > maxBytes) fault("THL_LIMIT", "content exceeds file limit: " + name); + return utf8.decode(bytes); + } catch (error) { + if (error instanceof TrustedFileError) throw error; + return fault("THL_IO", "cannot read valid UTF-8 content: " + name); + } finally { + if (fd !== undefined) closeSync(fd); + } + } + + exists(relativePath: string): boolean { + const name = artifactRelativePath(relativePath); + try { + this.guarded(name); + return true; + } catch (error) { + if (error instanceof TrustedFileError && error.code === "THL_IO") { + // Check ENOENT only; all other IO failures remain errors. + const absolute = resolve(this.root, ...name.split("/")); + try { lstatSync(absolute); } catch (cause) { + if ((cause as NodeJS.ErrnoException).code === "ENOENT") return false; + } + } + throw error; + } + } + + isDirectory(relativePath: string): boolean { + return lstatSync(this.guarded(relativePath)).isDirectory(); + } + + walkMarkdown(relativePath: string): readonly string[] { + const start = relativePath === "." ? "" : artifactRelativePath(relativePath); + const absolute = start ? this.guarded(start) : this.root; + const results: string[] = []; + let visited = 0; + const visit = (directory: string, relativeName: string): void => { + for (const entry of readdirSync(directory, { withFileTypes: true }) + .sort((a, b) => a.name.localeCompare(b.name, "en"))) { + if (++visited > 50_000) fault("THL_LIMIT", "directory traversal work limit exceeded"); + if (entry.isDirectory() && EXCLUDED_DIRECTORIES.has(entry.name)) continue; + const child = relativeName ? relativeName + "/" + entry.name : entry.name; + const name = artifactRelativePath(child); + if (entry.isSymbolicLink()) fault("THL_PATH", "symbolic link forbidden in content tree: " + name); + const childPath = this.guarded(name); + if (entry.isDirectory()) visit(childPath, name); + else if (entry.isFile() && /\.(md|mdx)$/i.test(entry.name)) { + results.push(name); + if (results.length > 10_000) fault("THL_LIMIT", "too many Markdown documents"); + } + } + }; + if (lstatSync(absolute).isDirectory()) visit(absolute, start); + else if (/\.(md|mdx)$/i.test(start)) results.push(start); + else fault("THL_PATH", "check target must be a Markdown/MDX file or directory"); + return results.sort(); + } + + /** Atomic manifest creation/update; never use a caller-controlled temp path. */ + writeManifest(relativePath: string, content: string): void { + const name = artifactRelativePath(relativePath); + if (Buffer.byteLength(content, "utf8") > DEFAULT_MAX_BYTES) + fault("THL_LIMIT", "manifest exceeds 4 MiB"); + const target = this.guarded(name, true); + const parent = dirname(target); + const temp = join(parent, "." + basename(target) + + "." + randomBytes(12).toString("hex") + ".tmp"); + let fd: number | undefined; + try { + fd = openSync(temp, constants.O_CREAT | constants.O_EXCL | + constants.O_WRONLY | (constants.O_NOFOLLOW ?? 0), 0o600); + writeFileSync(fd, content, { encoding: "utf8" }); + fsyncSync(fd); + closeSync(fd); + fd = undefined; + this.guarded(name, true); + renameSync(temp, target); + } catch (error) { + if (error instanceof TrustedFileError) throw error; + fault("THL_IO", "cannot atomically update manifest: " + name); + } finally { + if (fd !== undefined) closeSync(fd); + try { unlinkSync(temp); } catch { /* temp already renamed or absent */ } + } + } +} diff --git a/src/node/index.ts b/src/node/index.ts new file mode 100644 index 00000000..7f376fc6 --- /dev/null +++ b/src/node/index.ts @@ -0,0 +1,42 @@ +import { + validateSidecarManifest, type SidecarManifest, +} from "../v2/authoring.js"; +import { parseStrictJsonData } from "../v2/validator.js"; +import { TrustedContentRoot, TrustedFileError } from "./files.js"; +import { scanMarkdownFences, type MarkdownFence, type MarkdownFormat } from "./markdown.js"; + +export { TrustedContentRoot, TrustedFileError, scanMarkdownFences }; +export type { MarkdownFence, MarkdownFormat }; + +export type NodeHostOptions = Readonly<{ + /** Trusted repository/content root. All sidecar paths resolve within it. */ + root: string; + /** Root-relative manifest path. Optional for inline-JSON-only projects. */ + manifestPath?: string; +}>; + +/** Strict, never self-approving sidecar parsing. */ +export function readSidecarManifest( + root: TrustedContentRoot, relativePath: string, +): SidecarManifest { + const source = root.read(relativePath); + return validateSidecarManifest(parseStrictJsonData(source)); +} + +/** + * Node-only Remark host boundary, suitable for Fumadocs/Next/Astro builds. + * No symlink escapes, implicit AI/remote access or application-specific + * source rewriting. The registered Remark plugin still does the actual + * mdast validation and emits inert literal artifact JSON for MDX. + */ +export function createNodeThroughlineHost(options: NodeHostOptions) { + const root = new TrustedContentRoot(options.root); + const manifest = options.manifestPath === undefined + ? undefined + : readSidecarManifest(root, options.manifestPath); + return Object.freeze({ + ...(manifest ? { manifest } : {}), + documentForFile: (filePath: string) => root.relativeForFile(filePath), + loadArtifact: (relativePath: string) => root.read(relativePath), + }); +} diff --git a/src/node/markdown.ts b/src/node/markdown.ts new file mode 100644 index 00000000..c5a87a1c --- /dev/null +++ b/src/node/markdown.ts @@ -0,0 +1,108 @@ +/** + * Offline Markdown/MDX code-node discovery for the Node CLI. + * + * The syntax tree comes from the same Remark/mdast parser family used by + * framework hosts. Parsing does not transform, render, evaluate or execute + * Markdown, HTML, JavaScript, JSX or MDX expressions. + */ +import remarkMdx from "remark-mdx"; +import remarkParse from "remark-parse"; +import { unified } from "unified"; +import { normalizeThlBody, ThroughlineAuthoringError } from "../v2/authoring.js"; + +export type MarkdownFence = Readonly<{ + lang: string | null; + meta: string | null; + body: string; + line: number; + column: number; + ordinal: number | null; +}>; + +export type MarkdownFormat = "md" | "mdx"; +type MarkdownNode = Readonly<{ + type: string; + children?: readonly MarkdownNode[]; + lang?: string | null; + meta?: string | null; + value?: string; + position?: { start?: { line: number; column: number } }; +}>; + +const MAX_MARKDOWN_BYTES = 4 * 1024 * 1024; +const MAX_AST_NODES = 100_000; +const MAX_FENCES = 10_000; +const MAX_AST_DEPTH = 128; +const markdown = unified().use(remarkParse); +const mdx = unified().use(remarkParse).use(remarkMdx); + +/** + * Enumerate actual mdast `code` nodes in depth-first document order. + * + * Remark and this function count only nodes whose language is exactly + * `thl`, including those with unsupported metadata (which `thl check` + * later rejects). Other fences have a null ordinal. The node value and + * source position come from the parser rather than from delimiters guessed + * by line scanning. This includes arbitrary list/blockquote nesting and + * excludes code-like text inside HTML, JSX, comments or indented code. + */ +export function scanMarkdownFences( + source: string, + options: Readonly<{ format?: MarkdownFormat }> = {}, +): readonly MarkdownFence[] { + if (typeof source !== "string" || + Buffer.byteLength(source, "utf8") > MAX_MARKDOWN_BYTES) + throw new ThroughlineAuthoringError("THL_SYNTAX", "Markdown/MDX source exceeds 4 MiB or is not UTF-8 text"); + const format = options.format ?? "md"; + if (format !== "md" && format !== "mdx") + throw new ThroughlineAuthoringError("THL_SYNTAX", "format must be md or mdx"); + + const normalized = normalizeThlBody(source); + let tree: MarkdownNode; + try { + tree = (format === "mdx" ? mdx : markdown).parse(normalized) as MarkdownNode; + } catch (error) { + // Do not reflect arbitrary untrusted input or filesystem paths from + // parser errors; preserve only bounded, precise source coordinates. + const point = error as { line?: unknown; column?: unknown; place?: { start?: { line?: unknown; column?: unknown } } }; + const line = point.line ?? point.place?.start?.line; + const column = point.column ?? point.place?.start?.column; + const at = Number.isSafeInteger(line) && Number.isSafeInteger(column) && + (line as number) > 0 && (column as number) > 0 + ? " at " + line + ":" + column : ""; + throw new ThroughlineAuthoringError("THL_SYNTAX", "invalid " + format.toUpperCase() + " syntax" + at); + } + + const fences: MarkdownFence[] = []; + let ordinal = 0; + let visited = 0; + const pending: Array<{ node: MarkdownNode; depth: number }> = [{ node: tree, depth: 0 }]; + while (pending.length) { + const { node, depth } = pending.pop()!; + if (++visited > MAX_AST_NODES || depth > MAX_AST_DEPTH) + throw new ThroughlineAuthoringError("THL_LIMIT", "Markdown/MDX AST exceeds work or depth budget"); + if (node.type === "code") { + if (fences.length >= MAX_FENCES) + throw new ThroughlineAuthoringError("THL_LIMIT", "too many Markdown/MDX code nodes"); + const position = node.position?.start; + if (!position || !Number.isSafeInteger(position.line) || + !Number.isSafeInteger(position.column) || + position.line < 1 || position.column < 1) + throw new ThroughlineAuthoringError("THL_SYNTAX", "code node lacks a valid source position"); + const isThl = node.lang === "thl"; + fences.push(Object.freeze({ + lang: node.lang ?? null, + meta: node.meta ?? null, + body: node.value ?? "", + line: position.line, + column: position.column, + ordinal: isThl ? ordinal++ : null, + })); + } + if (node.children) { + for (let i = node.children.length - 1; i >= 0; i--) + pending.push({ node: node.children[i], depth: depth + 1 }); + } + } + return Object.freeze(fences); +} diff --git a/src/react/__tests__/compact.browser.test.tsx b/src/react/__tests__/compact.browser.test.tsx index 6301dd3b..d628ca5e 100644 --- a/src/react/__tests__/compact.browser.test.tsx +++ b/src/react/__tests__/compact.browser.test.tsx @@ -3,7 +3,7 @@ import { page } from "vitest/browser"; import { render } from "vitest-browser-react"; import { compile } from "../../domains/registry.js"; import { CHECKOUT_GUIDANCE, EXAMPLES } from "../../legacy-examples.js"; -import { ThroughlinePlayer } from "../index.js"; +import { ThroughlinePlayer } from "../player.js"; import "../../styles/throughline.css"; import { openPlayerPanel, stepCount } from "./player-actions.js"; diff --git a/src/react/__tests__/cross-browser-geometry.browser.test.tsx b/src/react/__tests__/cross-browser-geometry.browser.test.tsx index 04ecf90b..3300d60f 100644 --- a/src/react/__tests__/cross-browser-geometry.browser.test.tsx +++ b/src/react/__tests__/cross-browser-geometry.browser.test.tsx @@ -3,7 +3,7 @@ import { page } from "vitest/browser"; import { render } from "vitest-browser-react"; import { compile } from "../../domains/registry.js"; import { CHECKOUT_GUIDANCE, CHECKOUT_SCENARIOS } from "../../legacy-examples.js"; -import { ThroughlinePlayer } from "../index.js"; +import { ThroughlinePlayer } from "../player.js"; import "../../styles/throughline.css"; /** diff --git a/src/react/__tests__/guidance.browser.test.tsx b/src/react/__tests__/guidance.browser.test.tsx index f453e99c..3e83c627 100644 --- a/src/react/__tests__/guidance.browser.test.tsx +++ b/src/react/__tests__/guidance.browser.test.tsx @@ -3,7 +3,8 @@ import { page } from "vitest/browser"; import { render } from "vitest-browser-react"; import { compile } from "../../domains/registry.js"; import { CHECKOUT_GUIDANCE, CHECKOUT_SCENARIOS } from "../../legacy-examples.js"; -import { ThroughlinePlayer, ThroughlineScenarios } from "../index.js"; +import { ThroughlinePlayer } from "../player.js"; +import { ThroughlineScenarios } from "../scenarios.js"; import "../../styles/throughline.css"; import { openPlayerPanel, seekFrame, stepCount } from "./player-actions.js"; diff --git a/src/react/__tests__/hardening.browser.test.tsx b/src/react/__tests__/hardening.browser.test.tsx index 2d6a7018..59c2bbcd 100644 --- a/src/react/__tests__/hardening.browser.test.tsx +++ b/src/react/__tests__/hardening.browser.test.tsx @@ -2,7 +2,7 @@ import { expect, it } from "vitest"; import { page } from "vitest/browser"; import { render } from "vitest-browser-react"; import { compileProgram } from "../../compiler.js"; -import { ThroughlinePlayer } from "../index.js"; +import { ThroughlinePlayer } from "../player.js"; import "../../styles/throughline.css"; it("renders malicious-looking labels, notes and values as inert text on mobile", async () => { diff --git a/src/react/__tests__/hierarchy.browser.test.tsx b/src/react/__tests__/hierarchy.browser.test.tsx index 586da69e..371d6587 100644 --- a/src/react/__tests__/hierarchy.browser.test.tsx +++ b/src/react/__tests__/hierarchy.browser.test.tsx @@ -2,7 +2,7 @@ import { expect, it } from "vitest"; import { page, userEvent } from "vitest/browser"; import { render } from "vitest-browser-react"; import { compile } from "../../domains/registry.js"; -import { ThroughlinePlayer } from "../index.js"; +import { ThroughlinePlayer } from "../player.js"; import "../../styles/throughline.css"; import { closePlayerPanel, openPlayerPanel } from "./player-actions.js"; diff --git a/src/react/__tests__/narration-review.browser.test.tsx b/src/react/__tests__/narration-review.browser.test.tsx index 71e1c299..ee3681ab 100644 --- a/src/react/__tests__/narration-review.browser.test.tsx +++ b/src/react/__tests__/narration-review.browser.test.tsx @@ -3,7 +3,7 @@ import { page, userEvent } from "vitest/browser"; import { render } from "vitest-browser-react"; import { compile } from "../../domains/registry.js"; import type { ThroughlineGuidance } from "../guidance.js"; -import { ThroughlinePlayer } from "../index.js"; +import { ThroughlinePlayer } from "../player.js"; import "../../styles/throughline.css"; import { closePlayerPanel, openPlayerPanel } from "./player-actions.js"; diff --git a/src/react/__tests__/narration.browser.test.tsx b/src/react/__tests__/narration.browser.test.tsx index 486df7ed..943d09ab 100644 --- a/src/react/__tests__/narration.browser.test.tsx +++ b/src/react/__tests__/narration.browser.test.tsx @@ -1,7 +1,8 @@ import { afterEach, expect, it, vi } from "vitest"; import { render } from "vitest-browser-react"; import { compile } from "../../domains/registry.js"; -import { ThroughlinePlayer, ThroughlineScenarios } from "../index.js"; +import { ThroughlinePlayer } from "../player.js"; +import { ThroughlineScenarios } from "../scenarios.js"; import "../../styles/throughline.css"; import { closePlayerPanel, openPlayerPanel, seekFrame } from "./player-actions.js"; diff --git a/src/react/__tests__/player.browser.test.tsx b/src/react/__tests__/player.browser.test.tsx index 79d3eb54..ee9cd9ad 100644 --- a/src/react/__tests__/player.browser.test.tsx +++ b/src/react/__tests__/player.browser.test.tsx @@ -3,7 +3,7 @@ import { page } from "vitest/browser"; import { render } from "vitest-browser-react"; import { compile } from "../../domains/registry.js"; import { EXAMPLES } from "../../legacy-examples.js"; -import { ThroughlinePlayer } from "../index.js"; +import { ThroughlinePlayer } from "../player.js"; import "../../styles/throughline.css"; import { closePlayerPanel, openPlayerPanel, seekFrame, stepCount } from "./player-actions.js"; diff --git a/src/react/__tests__/progress.browser.test.tsx b/src/react/__tests__/progress.browser.test.tsx index e255c421..c5f37961 100644 --- a/src/react/__tests__/progress.browser.test.tsx +++ b/src/react/__tests__/progress.browser.test.tsx @@ -3,7 +3,8 @@ import { page } from "vitest/browser"; import { render } from "vitest-browser-react"; import { compile } from "../../domains/registry.js"; import { CHECKOUT_SCENARIOS, EXAMPLES } from "../../legacy-examples.js"; -import { ThroughlinePlayer, ThroughlineScenarios } from "../index.js"; +import { ThroughlinePlayer } from "../player.js"; +import { ThroughlineScenarios } from "../scenarios.js"; import "../../styles/throughline.css"; import { openPlayerPanel, seekFrame, stepCount } from "./player-actions.js"; diff --git a/src/react/__tests__/sound.browser.test.tsx b/src/react/__tests__/sound.browser.test.tsx index 842fc2f7..24dca3b8 100644 --- a/src/react/__tests__/sound.browser.test.tsx +++ b/src/react/__tests__/sound.browser.test.tsx @@ -2,7 +2,8 @@ import { StrictMode } from "react"; import { afterEach, expect, it, vi } from "vitest"; import { render } from "vitest-browser-react"; import { compile } from "../../domains/registry.js"; -import { ThroughlinePlayer, ThroughlineScenarios } from "../index.js"; +import { ThroughlinePlayer } from "../player.js"; +import { ThroughlineScenarios } from "../scenarios.js"; import { closePlayerPanel, openPlayerPanel } from "./player-actions.js"; const trace = compile( diff --git a/src/react/__tests__/states.browser.test.tsx b/src/react/__tests__/states.browser.test.tsx index 886f220c..913fbede 100644 --- a/src/react/__tests__/states.browser.test.tsx +++ b/src/react/__tests__/states.browser.test.tsx @@ -3,7 +3,7 @@ import { page, userEvent } from "vitest/browser"; import { render } from "vitest-browser-react"; import { compile } from "../../domains/registry.js"; import { EXAMPLES } from "../../legacy-examples.js"; -import { ThroughlinePlayer } from "../index.js"; +import { ThroughlinePlayer } from "../player.js"; import "../../styles/throughline.css"; import { openPlayerPanel, seekFrame } from "./player-actions.js"; diff --git a/src/react/__tests__/toolbar.browser.test.tsx b/src/react/__tests__/toolbar.browser.test.tsx index 26a50bd1..5662a152 100644 --- a/src/react/__tests__/toolbar.browser.test.tsx +++ b/src/react/__tests__/toolbar.browser.test.tsx @@ -4,7 +4,7 @@ import { render } from "vitest-browser-react"; import { compileProgram } from "../../compiler.js"; import { compile } from "../../domains/registry.js"; import { CHECKOUT_GUIDANCE, CHECKOUT_SCENARIOS } from "../../legacy-examples.js"; -import { ThroughlinePlayer } from "../index.js"; +import { ThroughlinePlayer } from "../player.js"; import "../../styles/throughline.css"; import { openPlayerPanel, seekFrame } from "./player-actions.js"; diff --git a/src/react/__tests__/viewport.browser.test.tsx b/src/react/__tests__/viewport.browser.test.tsx index 89601aca..35293a2e 100644 --- a/src/react/__tests__/viewport.browser.test.tsx +++ b/src/react/__tests__/viewport.browser.test.tsx @@ -2,7 +2,7 @@ import { expect, it } from "vitest"; import { page, userEvent } from "vitest/browser"; import { render } from "vitest-browser-react"; import { compile } from "../../domains/registry.js"; -import { ThroughlinePlayer } from "../index.js"; +import { ThroughlinePlayer } from "../player.js"; import "../../styles/throughline.css"; import { closePlayerPanel, openPlayerPanel } from "./player-actions.js"; diff --git a/src/react/__tests__/viewport.review.browser.test.tsx b/src/react/__tests__/viewport.review.browser.test.tsx index 7953ff2c..cc78da16 100644 --- a/src/react/__tests__/viewport.review.browser.test.tsx +++ b/src/react/__tests__/viewport.review.browser.test.tsx @@ -2,7 +2,7 @@ import { expect, it } from "vitest"; import { page, userEvent } from "vitest/browser"; import { render } from "vitest-browser-react"; import { compile } from "../../domains/registry.js"; -import { ThroughlinePlayer } from "../index.js"; +import { ThroughlinePlayer } from "../player.js"; import "../../styles/throughline.css"; import { openPlayerPanel } from "./player-actions.js"; diff --git a/src/react/graph-player.tsx b/src/react/graph-player.tsx index 4d349cb3..954f83a9 100644 --- a/src/react/graph-player.tsx +++ b/src/react/graph-player.tsx @@ -264,6 +264,9 @@ export function ThroughlineGraphPlayer({ const [inspectionMode, setInspectionMode] = useState<"explain" | "inspect">("explain"); const [camera, setCamera] = useState(null); const [fullscreen, setFullscreen] = useState(false); + // Capability detection is client-only. SSR and the first hydration render + // must agree before the mount effect enables fullscreen controls. + const [fullscreenAvailable, setFullscreenAvailable] = useState(false); const [fullscreenError, setFullscreenError] = useState(null); if (identity !== trace) { setIdentity(trace); @@ -355,6 +358,7 @@ export function ThroughlineGraphPlayer({ }, [layout, effectiveCamera, view.kind]); useEffect(() => { const sync = () => setFullscreen(document.fullscreenElement === rootRef.current); + setFullscreenAvailable(Boolean(document.fullscreenEnabled)); sync(); document.addEventListener("fullscreenchange", sync); return () => document.removeEventListener("fullscreenchange", sync); @@ -434,8 +438,8 @@ export function ThroughlineGraphPlayer({ enabled: narrating, available: voice.available, toggle: voice.toggle, } : undefined} fullscreen={{ - active: fullscreen, available: typeof document !== "undefined" && - Boolean(document.fullscreenEnabled), toggle: toggleFullscreen, + active: fullscreen, available: fullscreenAvailable, + toggle: toggleFullscreen, }}/> diff --git a/src/react/index.ts b/src/react/index.ts index 05b78a3d..ead29a02 100644 --- a/src/react/index.ts +++ b/src/react/index.ts @@ -1,9 +1,3 @@ -export type { SonificationEvent, SonificationOptions } from "../sonify.js"; -export { ThroughlinePlayer, type ThroughlinePlayerProps } from "./player.js"; +/** Native schema-2 React entry. No v1 trace or domain-player compatibility. */ export { ThroughlineEmbed, type ThroughlineEmbedProps } from "./embed.js"; - -export { ThroughlineScenarios, type ThroughlineScenario, type ThroughlineScenariosProps } from "./scenarios.js"; -export type { ThroughlineGuidance, GuidedChapter, CausalLink, GuidanceEvidence } from "./guidance.js"; - -/** Native schema-2 graph/sequence player with TL-U07 Explain/Inspect. */ export { ThroughlineGraphPlayer, type ThroughlineGraphPlayerProps } from "./graph-player.js"; diff --git a/src/v2/authoring.ts b/src/v2/authoring.ts index 08a74373..805c33b4 100644 --- a/src/v2/authoring.ts +++ b/src/v2/authoring.ts @@ -9,7 +9,7 @@ export type ThlBody = | Readonly<{ kind: "artifact"; value: VisualArtifact }>; export type AuthoringErrorCode = - | "THL_EMPTY" | "THL_INTENT_LIMIT" | "THL_UNICODE" | "THL_SYNTAX" + | "THL_EMPTY" | "THL_INTENT_LIMIT" | "THL_LIMIT" | "THL_UNICODE" | "THL_SYNTAX" | "THL_UNSUPPORTED_DOCUMENT" | "THL_PATH" | "THL_MANIFEST" | "THL_UNRESOLVED" | "THL_UNREVIEWED" | "THL_DIGEST" | "THL_LOADER"; diff --git a/src/v2/validator.ts b/src/v2/validator.ts index 072006ff..7ecf4bd3 100644 --- a/src/v2/validator.ts +++ b/src/v2/validator.ts @@ -544,6 +544,23 @@ function rejectDuplicateJsonKeys(source: string, budget: Budget): void { if (cursor !== source.length) syntax("unexpected trailing content"); } +/** + * Parse bounded JSON data without losing duplicate keys. The Node-only sidecar + * loader uses this lexical gate before the manifest's exact shape validator. + * This is deliberately not the public artifact-deserialization entry point. + */ +export function parseStrictJsonData(source: string): unknown { + if (typeof source !== "string") fail("$", "expected strict JSON text"); + if (new TextEncoder().encode(source).byteLength > ARTIFACT_LIMITS.artifactBytes) + fail("$", "JSON input exceeds 4 MiB UTF-8"); + rejectDuplicateJsonKeys(source, new Budget()); + try { + return JSON.parse(source) as unknown; + } catch { + return fail("$", "invalid JSON text"); + } +} + /** Parse serialized artifacts, rejecting duplicate JSON keys before decoding. */ export function parseArtifactJson(source: string): VisualArtifact { if (typeof source !== "string") fail("$", "expected JSON text"); diff --git a/tsdown.config.ts b/tsdown.config.ts index bfad46f0..a39a06f9 100644 --- a/tsdown.config.ts +++ b/tsdown.config.ts @@ -1,7 +1,7 @@ import { defineConfig } from "tsdown"; /** - * Keep these four JS + declaration entry paths aligned with package exports. + * Keep library exports and separate Node CLI entry aligned with package metadata. * The CSS remains an explicit, consumer-loaded source asset. */ export default defineConfig({ @@ -10,6 +10,8 @@ export default defineConfig({ "react/index": "src/react/index.ts", "remark/index": "src/remark/index.ts", examples: "src/examples.ts", + "node/index": "src/node/index.ts", + "cli/main": "src/cli/main.ts", }, outDir: "dist", format: "esm", @@ -22,6 +24,6 @@ export default defineConfig({ tsconfig: "./tsconfig.build.json", deps: { // Keep optional React outside the pure compiler and prevent private imports. - onlyImport: ["cn", "react", "react-dom"], + onlyImport: ["cn", "react", "react-dom", "node:fs", "node:path", "node:crypto", "remark-parse", "remark-mdx", "unified"], }, });