From a9b59b0b126034ba5b85c8ceb7d944268b498cf1 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:05:35 +0100 Subject: [PATCH 01/71] feat(TL-U10): add bounded offline Markdown/MDX fence discovery for CLI --- src/node/markdown.ts | 125 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 src/node/markdown.ts diff --git a/src/node/markdown.ts b/src/node/markdown.ts new file mode 100644 index 00000000..de1902bc --- /dev/null +++ b/src/node/markdown.ts @@ -0,0 +1,125 @@ +/** + * Offline, non-evaluating Markdown/MDX fenced-code discovery for the CLI. + * No MDX execution, React, Remark plugins, HTML rendering or AI providers. + * Supports CommonMark fences in plain, quoted and list code blocks. + * Production Remark integration continues to consume real mdast nodes. + */ +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; +}>; + +const MAX_MARKDOWN_BYTES = 4 * 1024 * 1024; +const MAX_NODES = 10_000; +const fail = (message: string): never => { + throw new ThroughlineAuthoringError("THL_SYNTAX", message); +}; +type Prefix = { quotes: number; listIndent: number; leading: number; remaining: string }; + +function stripQuotes(value: string, depth: number): string | null { + let at = 0; + for (let index = 0; index < depth; index++) { + const match = /^ {0,3}> ?/.exec(value.slice(at)); + if (!match) return null; + at += match[0].length; + } + return value.slice(at); +} +function openerPrefix(line: string): Prefix { + let remaining = line; + let quotes = 0; + while (quotes < 32) { + const match = /^ {0,3}> ?/.exec(remaining); + if (!match) break; + quotes++; + remaining = remaining.slice(match[0].length); + } + let listIndent = 0; + const list = /^ {0,3}(?:[-+*]|\d{1,9}[.)])([ \t]+)/.exec(remaining); + if (list) { + listIndent = list[0].length; + remaining = remaining.slice(listIndent); + } + const leading = /^ */.exec(remaining)?.[0].length ?? 0; + return { quotes, listIndent, leading, remaining }; +} +function contentLine(line: string, prefix: Prefix): string | null { + let rest = stripQuotes(line, prefix.quotes); + if (rest === null) { + if (line.trim() === "") return ""; + return null; + } + if (prefix.listIndent) { + if (rest.trim() === "") return ""; + const spaces = /^ */.exec(rest)?.[0].length ?? 0; + if (spaces < prefix.listIndent) return null; + rest = rest.slice(prefix.listIndent); + } + const indent = /^ */.exec(rest)?.[0].length ?? 0; + return rest.slice(Math.min(prefix.leading, indent)); +} +function closingFence(line: string, symbol: string, minimum: number): boolean { + const match = /^ {0,3}(\x60+|~+)[ \t]*$/.exec(line); + return !!match && match[1][0] === symbol && match[1].length >= minimum; +} + +/** + * Extract fenced code nodes in lexical/depth-first order. The info string + * cannot contain a backtick for that fence style. Unclosed fences are + * CommonMark-valid and consume the rest of their container. + * The body excludes delimiters and a synthetic final newline. + */ +export function scanMarkdownFences(source: string): readonly MarkdownFence[] { + if (typeof source !== "string" || Buffer.byteLength(source, "utf8") > MAX_MARKDOWN_BYTES) + fail("Markdown document is not a bounded UTF-8 string"); + const normalized = normalizeThlBody(source).replace(/^\uFEFF/, ""); + const lines = normalized.split("\n"); + const results: MarkdownFence[] = []; + let ordinal = 0; + for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) { + const current = lines[lineIndex]; + const prefix = openerPrefix(current); + if (prefix.leading > 3) continue; + const raw = prefix.remaining.slice(prefix.leading); + const opening = /^(\x60{3,}|~{3,})([^\r\n]*)$/.exec(raw); + if (!opening) continue; + const symbol = opening[1][0]; + const info = opening[2].trim(); + if (symbol === "\x60" && info.includes("\x60")) continue; + // First info word is language, rest metadata. Domain tags are invalid. + const tokens = /^(\S+)(?:\s+([\s\S]+))?$/.exec(info); + const lang = tokens?.[1] ?? null; + const meta = tokens?.[2] ?? null; + const bodyLines: string[] = []; + let end = lineIndex; + for (let next = lineIndex + 1; next < lines.length; next++) { + const parsed = contentLine(lines[next], prefix); + if (parsed === null) break; + if (closingFence(parsed, symbol, opening[1].length)) { + end = next; + break; + } + if (next === lines.length - 1 && lines[next] === "" && normalized.endsWith("\n")) { + end = next; + break; + } + bodyLines.push(parsed); + end = next; + } + if (results.length >= MAX_NODES) fail("too many fenced code nodes"); + const isThl = lang === "thl"; + results.push(Object.freeze({ + lang, meta, body: bodyLines.join("\n"), line: lineIndex + 1, + column: current.length - raw.length + 1, + ordinal: isThl ? ordinal++ : null, + })); + lineIndex = end; + } + return Object.freeze(results); +} From b6a62cbd1df087c363fd1f52262b95c681c08254 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:06:42 +0100 Subject: [PATCH 02/71] feat(TL-U10): confine trusted Node host and CLI filesystem reads and atomic manifest writes --- src/node/files.ts | 190 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 190 insertions(+) create mode 100644 src/node/files.ts diff --git a/src/node/files.ts b/src/node/files.ts new file mode 100644 index 00000000..dca2c504 --- /dev/null +++ b/src/node/files.ts @@ -0,0 +1,190 @@ +import { + closeSync, constants, fstatSync, fsyncSync, lstatSync, mkdirSync, + 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; + 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 = artifactRelativePath(relativePath); + const absolute = this.guarded(start); + 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 + "/" + 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 */ } + } + } +} From dbb01d455093310a6afa8577771ad823376e4a7c Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:07:27 +0100 Subject: [PATCH 03/71] feat(TL-U10): reuse strict bounded duplicate-key JSON scan for untrusted sidecar files --- src/v2/validator.ts | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) 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"); From 16e98515efba64e3a157f00f1fd862e074d85d8e Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:07:52 +0100 Subject: [PATCH 04/71] feat(TL-U10): expose trusted Node-only Remark host loader with strict sidecar parsing --- src/node/index.ts | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 src/node/index.ts diff --git a/src/node/index.ts b/src/node/index.ts new file mode 100644 index 00000000..07de3b7a --- /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 } from "./markdown.js"; + +export { TrustedContentRoot, TrustedFileError, scanMarkdownFences }; +export type { MarkdownFence }; + +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), + }); +} From 4f282f435b8cdaea6d233eff6fcd54b304701342 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:08:46 +0100 Subject: [PATCH 05/71] fix(TL-U10): allow explicit repository-root directory checks without relaxing file locators --- src/node/files.ts | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/node/files.ts b/src/node/files.ts index dca2c504..41bdfad6 100644 --- a/src/node/files.ts +++ b/src/node/files.ts @@ -1,5 +1,5 @@ import { - closeSync, constants, fstatSync, fsyncSync, lstatSync, mkdirSync, + closeSync, constants, fstatSync, fsyncSync, lstatSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, unlinkSync, writeFileSync, } from "node:fs"; @@ -134,8 +134,8 @@ export class TrustedContentRoot { } walkMarkdown(relativePath: string): readonly string[] { - const start = artifactRelativePath(relativePath); - const absolute = this.guarded(start); + 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 => { @@ -143,7 +143,7 @@ export class TrustedContentRoot { .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 + "/" + entry.name; + 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); From b3d4048ba2f5aa62015a12f2c5cea984f8ce08e7 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:09:41 +0100 Subject: [PATCH 06/71] feat(TL-U10): implement validate materialize check CLI with reviewed digests and stable diagnostics --- src/cli/commands.ts | 224 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 224 insertions(+) create mode 100644 src/cli/commands.ts diff --git a/src/cli/commands.ts b/src/cli/commands.ts new file mode 100644 index 00000000..8d34df8f --- /dev/null +++ b/src/cli/commands.ts @@ -0,0 +1,224 @@ +import { + artifactRelativePath, artifactSha256, parseIntentBlock, resolveThlBody, + sha256Text, ThroughlineAuthoringError, validateSidecarManifest, + type SidecarEntry, type SidecarManifest, +} from "../v2/authoring.js"; +import { compileArtifact } from "../v2/compiler.js"; +import { ArtifactValidationError, parseArtifactJson, serializeArtifact } 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 (/schemaVersion|unsupported artifact schema/i.test(message)) { + code = "THL_ARTIFACT_VERSION"; + } else if (/duplicate object key|invalid JSON|at offset|unexpected trailing content/i.test(message)) { + code = "THL_ARTIFACT_SYNTAX"; + } 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); + 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"); + // 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) { + throw new ThroughlineCliError("THL_CHECK", format(error, location)); + } + 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)); + 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) { + throw new ThroughlineCliError("THL_MATERIALIZE", format(error, location)); + } + 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 = root.exists(manifestPath) + ? readSidecarManifest(root, manifestPath) + : { version: 1 as const, 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; + } +} From ef9adc0ac50ac0f69de9c93a96785d05e1f88143 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:09:57 +0100 Subject: [PATCH 07/71] feat(TL-U10): add standalone Node binary entrypoint --- src/cli/main.ts | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 src/cli/main.ts 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)); From 25f954b54ddb1f9d16e01a2ffb478203059a57ba Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:10:20 +0100 Subject: [PATCH 08/71] fix(TL-U10): preserve stable underlying failure codes and type manifest updates --- src/cli/commands.ts | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/src/cli/commands.ts b/src/cli/commands.ts index 8d34df8f..4752f5e6 100644 --- a/src/cli/commands.ts +++ b/src/cli/commands.ts @@ -4,7 +4,7 @@ import { type SidecarEntry, type SidecarManifest, } from "../v2/authoring.js"; import { compileArtifact } from "../v2/compiler.js"; -import { ArtifactValidationError, parseArtifactJson, serializeArtifact } from "../v2/validator.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"; @@ -123,7 +123,8 @@ function checkFile( ...(manifest ? { loadArtifact: (artifact: string) => root.read(artifact) } : {}), }); } catch (error) { - throw new ThroughlineCliError("THL_CHECK", format(error, location)); + const issue = toDiagnostic(error); + throw new ThroughlineCliError(issue.code, location + ": " + issue.message); } checked++; io.out("THL_OK check " + location); @@ -166,7 +167,8 @@ function materialize(root: TrustedContentRoot, args: Arguments, io: CliIO): void try { body = parseIntentBlock(fence.body).body; } catch (error) { - throw new ThroughlineCliError("THL_MATERIALIZE", format(error, location)); + 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({ @@ -174,9 +176,9 @@ function materialize(root: TrustedContentRoot, args: Arguments, io: CliIO): void artifactPath, artifactSha256: artifactSha256(artifact), review: "unreviewed", }); - const prior = root.exists(manifestPath) + const prior: SidecarManifest = root.exists(manifestPath) ? readSidecarManifest(root, manifestPath) - : { version: 1 as const, entries: [] }; + : { version: 1, entries: [] }; const entries = prior.entries.filter(row => row.document !== document || row.ordinal !== ordinal); const ordered = [...entries, entry].sort((left, right) => From 8cced560c55509040ec70c2f56e21bc63d3bed73 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:10:53 +0100 Subject: [PATCH 09/71] feat(TL-U10): register standalone thl binary and optional Node host without core dependencies --- package.json | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/package.json b/package.json index 1d79b96f..9e3acc03 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", @@ -102,5 +107,8 @@ "react", "developer-tools", "education" - ] + ], + "bin": { + "thl": "./dist/cli/main.js" + } } From 64fe624c22c1a6efb397f90608dbbe575d96cf05 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:10:56 +0100 Subject: [PATCH 10/71] feat(TL-U10): register standalone thl binary and optional Node host without core dependencies --- tsdown.config.ts | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tsdown.config.ts b/tsdown.config.ts index bfad46f0..b95b351d 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", From a113a957817ca2282d7b4824987af75f074d6c3e Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:12:05 +0100 Subject: [PATCH 11/71] test(TL-U10): exercise offline CLI, reviewed sidecars, symlink confinement and stable diagnostics --- src/__tests__/cli.test.ts | 201 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 201 insertions(+) create mode 100644 src/__tests__/cli.test.ts diff --git a/src/__tests__/cli.test.ts b/src/__tests__/cli.test.ts new file mode 100644 index 00000000..1e0dfe0b --- /dev/null +++ b/src/__tests__/cli.test.ts @@ -0,0 +1,201 @@ +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 { 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", " indented code, not a fence", " ~~~", "", + "~~~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, "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("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"); + }); +}); From 19517edc53d2a7987f6587aa0e70060fd5474480 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:12:42 +0100 Subject: [PATCH 12/71] test(TL-U10): verify optional Node host and executable CLI are included without root IO leakage --- scripts/verify-dist.mjs | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/scripts/verify-dist.mjs b/scripts/verify-dist.mjs index 2b64a3a4..5106d7e0 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,7 +53,7 @@ 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"]) { +for (const filename of ["react/index.js", "remark/index.js", "examples.js", "node/index.js", "cli/main.js"]) { assert( existsSync(resolve(root, "dist", `${filename}.map`)), `Missing JavaScript source map: ${filename}.map`, @@ -68,6 +70,21 @@ if (!existsSync(resolve(root, "dist/index.js.map"))) { const load = (entry) => import(pathToFileURL(resolve(root, "dist", entry)).href); +// 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 { compile } = await load("index.js"); assert.equal(typeof compile, "function"); const trace = compile("```thl binary\na = 1\nb = 1\n```"); From 4bfca677958a8b26e1eca10f3659c213e5136313 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:13:40 +0100 Subject: [PATCH 13/71] test(TL-U10): require packed CLI and Node host to validate sidecars offline with real approval gate --- scripts/audit-pack.mjs | 69 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 68 insertions(+), 1 deletion(-) diff --git a/scripts/audit-pack.mjs b/scripts/audit-pack.mjs index 5c0d0290..4ec02aee 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,8 +95,9 @@ try { ); assert.deepEqual( Object.keys(packed.exports).sort(), - [".", "./react", "./remark", "./examples", "./styles/throughline.css"].sort(), + [".", "./react", "./remark", "./examples", "./node", "./styles/throughline.css"].sort(), ); + assert.equal(packed.bin?.thl, "./dist/cli/main.js"); assert.deepEqual(Object.keys(packed.dependencies ?? {}), ["cn"]); for (const dependencies of [ packed.dependencies ?? {}, @@ -131,6 +135,69 @@ try { !existsSync(join(consumer, "node_modules", "unified")), "Core consumer unexpectedly installed 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); + assert(!existsSync(join(consumer, "node_modules", "react")) && + !existsSync(join(consumer, "node_modules", "unified")), + "CLI/Node host must not require React or a runtime Markdown executor"); + const core = [ 'import assert from "node:assert/strict";', 'import { compile, ProgramError, compileArtifact, inspectTrace, projectView, projectInspection } from "@0xbuff/throughline";', From 4acd7c110743d3f09a254e5e115d9a4cbea301bd Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:15:31 +0100 Subject: [PATCH 14/71] fix(TL-U10): resolve strict TypeScript CLI imports and trusted-root definite return --- src/cli/commands.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/cli/commands.ts b/src/cli/commands.ts index 4752f5e6..28bec486 100644 --- a/src/cli/commands.ts +++ b/src/cli/commands.ts @@ -1,9 +1,10 @@ import { artifactRelativePath, artifactSha256, parseIntentBlock, resolveThlBody, - sha256Text, ThroughlineAuthoringError, validateSidecarManifest, + 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"; From 305ad804df3bb60e95cbda846ea499ecc2d58358 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:15:35 +0100 Subject: [PATCH 15/71] fix(TL-U10): resolve strict TypeScript CLI imports and trusted-root definite return --- src/node/files.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/node/files.ts b/src/node/files.ts index 41bdfad6..e6614f99 100644 --- a/src/node/files.ts +++ b/src/node/files.ts @@ -39,7 +39,7 @@ const EXCLUDED_DIRECTORIES = new Set([ * select the root. */ export class TrustedContentRoot { - readonly root: string; + readonly root!: string; constructor(path: string = process.cwd()) { let root: string; try { @@ -106,7 +106,7 @@ export class TrustedContentRoot { return utf8.decode(bytes); } catch (error) { if (error instanceof TrustedFileError) throw error; - fault("THL_IO", "cannot read valid UTF-8 content: " + name); + return fault("THL_IO", "cannot read valid UTF-8 content: " + name); } finally { if (fd !== undefined) closeSync(fd); } From dbf2f9bd380960db876e216617247ba4c3003329 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:17:09 +0100 Subject: [PATCH 16/71] fix(TL-U10): classify duplicate JSON syntax before schema-version error and clarify metadata diagnostic --- src/cli/commands.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/cli/commands.ts b/src/cli/commands.ts index 28bec486..c704a489 100644 --- a/src/cli/commands.ts +++ b/src/cli/commands.ts @@ -74,10 +74,10 @@ function toDiagnostic(error: unknown): { code: string; message: string } { if (error.name === "ArtifactCompilationError") { code = /conflict|overlap|same.step/i.test(message) ? "THL_ARTIFACT_CONFLICT" : "THL_ARTIFACT_COMPILATION"; - } else if (/schemaVersion|unsupported artifact schema/i.test(message)) { - code = "THL_ARTIFACT_VERSION"; } 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)) { @@ -114,7 +114,7 @@ function checkFile( try { if (fence.meta !== null) throw new ThroughlineAuthoringError("THL_SYNTAX", - "only an unqualified thl language fence is supported"); + "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, { From b72e8491924e00d18e0125622e309279cfff0b96 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:18:31 +0100 Subject: [PATCH 17/71] docs(TL-U10): document offline CLI, review gate, filesystem confinement and Node host usage --- docs/cli.md | 141 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 docs/cli.md diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 00000000..d746897e --- /dev/null +++ b/docs/cli.md @@ -0,0 +1,141 @@ +# 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, +discovers fenced code blocks without evaluating MDX, and validates each +`thl` code node. 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. From 268b0c0ed29192fbaa706869eb5cdadb9de8a2df Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:19:31 +0100 Subject: [PATCH 18/71] docs(TL-U10): show real trusted Node host adapter and CLI-based reviewed materialization --- docs/framework-integrations.md | 44 ++++++++++++++-------------------- 1 file changed, 18 insertions(+), 26 deletions(-) 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. From e1bff09580688c1f79bea29194e45a8617829580 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:20:04 +0100 Subject: [PATCH 19/71] docs(TL-U10): align CHANGELOG.md with offline CLI, node host and pre-release boundaries --- CHANGELOG.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 95d252bc..db32b810 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,17 @@ program and trace schemas. Changes are grouped using ### 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-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 From 264584bedb261414152fa16bcc8d856eb2fb2907 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:20:07 +0100 Subject: [PATCH 20/71] docs(TL-U10): align docs/README.md with offline CLI, node host and pre-release boundaries --- docs/README.md | 2 ++ 1 file changed, 2 insertions(+) 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 From d8739abca94e98131d70d2e86057ed6fef932cb1 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:20:09 +0100 Subject: [PATCH 21/71] docs(TL-U10): align README.md with offline CLI, node host and pre-release boundaries --- README.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) 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) From cd82f7bfaf7859ea7eefe3b287e52eab9fd4689a Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:20:12 +0100 Subject: [PATCH 22/71] docs(TL-U10): align docs/releasing.md with offline CLI, node host and pre-release boundaries --- docs/releasing.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) 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) From cad5c263849dc8385c28e999f544c22566f1139a Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:20:57 +0100 Subject: [PATCH 23/71] fix(TL-U10): explicitly externalize Node-only builtins in optional host and CLI bundles --- tsdown.config.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tsdown.config.ts b/tsdown.config.ts index b95b351d..c14c072a 100644 --- a/tsdown.config.ts +++ b/tsdown.config.ts @@ -24,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"], }, }); From 27b82ec45709f63f5e275ae20d9704e1c118eeec Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:26:09 +0100 Subject: [PATCH 24/71] fix(TL-U10): accept source-less re-export facades backed by mapped CLI and Node chunks --- scripts/verify-dist.mjs | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/scripts/verify-dist.mjs b/scripts/verify-dist.mjs index 5106d7e0..eef87059 100644 --- a/scripts/verify-dist.mjs +++ b/scripts/verify-dist.mjs @@ -54,10 +54,15 @@ 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", "node/index.js", "cli/main.js"]) { - assert( - existsSync(resolve(root, "dist", `${filename}.map`)), - `Missing JavaScript source map: ${filename}.map`, - ); + 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 && /\\b(?:export|from)\\b/.test(facade), + "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"); From d679c14bff0cf6ee031b45ed5c5699ea1d2cc686 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:26:44 +0100 Subject: [PATCH 25/71] fix(TL-U10): use plain-text facade detection for source map fallback --- scripts/verify-dist.mjs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/verify-dist.mjs b/scripts/verify-dist.mjs index eef87059..2513b56d 100644 --- a/scripts/verify-dist.mjs +++ b/scripts/verify-dist.mjs @@ -59,7 +59,7 @@ for (const filename of ["react/index.js", "remark/index.js", "examples.js", "nod // is emitted into a separately mapped chunk. const facade = readFileSync(resolve(root, "dist", filename), "utf8"); assert( - facade.length < 1024 && /\\b(?:export|from)\\b/.test(facade), + facade.length < 1024 && (facade.includes("export") || facade.includes("from")), "Missing JavaScript source map or mapped facade: " + filename, ); } From 1c1c8e07a547ab40b6b38fb207a64775f06fc532 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:29:48 +0100 Subject: [PATCH 26/71] feat(TL-U10): remove v1 domain compiler, grammar and model exports from public pure root --- src/index.ts | 33 ++++----------------------------- 1 file changed, 4 insertions(+), 29 deletions(-) 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, From 03f453d8b72c92b0ca08ef953febf052efead777 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:29:51 +0100 Subject: [PATCH 27/71] feat(TL-U10): expose native schema-2 player and embed only in React entry --- src/react/index.ts | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) 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"; From abdd3c757d057af92ed180755c15e778a1f4cf70 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:30:22 +0100 Subject: [PATCH 28/71] test(TL-U10): retain historical v1 regressions via internal modules, not public exports --- src/__tests__/dsl.test.ts | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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'; From cc2091fff219691d4fabacb4413d0e3e6a67af23 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:30:25 +0100 Subject: [PATCH 29/71] test(TL-U10): retain historical v1 regressions via internal modules, not public exports --- src/__tests__/compilation-limits.test.ts | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) 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) => ({ From cff5c4bd0fe26aca9a4ad2e070a969126766dd2e Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:30:44 +0100 Subject: [PATCH 30/71] test(TL-U10): keep old player tests private after public v1 React retirement --- src/react/__tests__/compact.browser.test.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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"; From 7fe7b60e389119c96df282dd6b8c13dc7c015d5c Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:30:47 +0100 Subject: [PATCH 31/71] test(TL-U10): keep old player tests private after public v1 React retirement --- src/react/__tests__/cross-browser-geometry.browser.test.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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"; /** From 9bc2f9129725a6da03d2bbe7316f5293722e0b3a Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:30:49 +0100 Subject: [PATCH 32/71] test(TL-U10): keep old player tests private after public v1 React retirement --- src/react/__tests__/guidance.browser.test.tsx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) 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"; From 7c83c70b4c69df0aba3dd290647fe6f881284174 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:30:52 +0100 Subject: [PATCH 33/71] test(TL-U10): keep old player tests private after public v1 React retirement --- src/react/__tests__/hardening.browser.test.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 () => { From bc00db75058e82c04e6de741d8be9be7f8e405db Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:30:55 +0100 Subject: [PATCH 34/71] test(TL-U10): keep old player tests private after public v1 React retirement --- src/react/__tests__/hierarchy.browser.test.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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"; From 9e3c65f90cfd35f466cb6a83064c12393ae040e5 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:30:58 +0100 Subject: [PATCH 35/71] test(TL-U10): keep old player tests private after public v1 React retirement --- src/react/__tests__/narration-review.browser.test.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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"; From cfe420e2b5d15523e611fa4ea669b84156ae0091 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:31:01 +0100 Subject: [PATCH 36/71] test(TL-U10): keep old player tests private after public v1 React retirement --- src/react/__tests__/narration.browser.test.tsx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) 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"; From 04640846b5394152c0b74544af37aa4f70e5b14e Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:31:15 +0100 Subject: [PATCH 37/71] test(TL-U10): isolate legacy browser suite from supported schema-2 React exports --- src/react/__tests__/player.browser.test.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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"; From bd952958080f0d91796272ae9afda2acb98d3ac3 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:31:18 +0100 Subject: [PATCH 38/71] test(TL-U10): isolate legacy browser suite from supported schema-2 React exports --- src/react/__tests__/progress.browser.test.tsx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) 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"; From a1835e5e8f9743de2e2a10b7a630a3a15dc3145a Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:31:21 +0100 Subject: [PATCH 39/71] test(TL-U10): isolate legacy browser suite from supported schema-2 React exports --- src/react/__tests__/sound.browser.test.tsx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) 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( From e118effa5c6c39e6349ac9d304953140bfbc8d6e Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:31:24 +0100 Subject: [PATCH 40/71] test(TL-U10): isolate legacy browser suite from supported schema-2 React exports --- src/react/__tests__/states.browser.test.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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"; From 2fc0078b55d146deb849d73d7a206e5dab2796d1 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:31:27 +0100 Subject: [PATCH 41/71] test(TL-U10): isolate legacy browser suite from supported schema-2 React exports --- src/react/__tests__/toolbar.browser.test.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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"; From 109ef7888058e9b806be4351d7557718c2379929 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:31:30 +0100 Subject: [PATCH 42/71] test(TL-U10): isolate legacy browser suite from supported schema-2 React exports --- src/react/__tests__/viewport.browser.test.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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"; From ccd3ea7fab3d4a517090086196e1a122999db670 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:31:33 +0100 Subject: [PATCH 43/71] test(TL-U10): isolate legacy browser suite from supported schema-2 React exports --- src/react/__tests__/viewport.review.browser.test.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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"; From 27c1df0382d72d5fd3a284817b4abc4ad72e2b17 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:34:35 +0100 Subject: [PATCH 44/71] test(TL-U10): replace packed v1 Node/React consumer paths with schema-2-only exports --- scripts/audit-pack.mjs | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/scripts/audit-pack.mjs b/scripts/audit-pack.mjs index 4ec02aee..695926e7 100644 --- a/scripts/audit-pack.mjs +++ b/scripts/audit-pack.mjs @@ -200,12 +200,15 @@ try { 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"]);', @@ -282,7 +285,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;', @@ -450,14 +453,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" }));', From ccf967ece5d7d8420a881652b46fcb24a299833a Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:35:20 +0100 Subject: [PATCH 45/71] test(TL-U10): migrate independent packed browser SSR/hydration proof to native schema-2 player --- scripts/audit-browser.mjs | 281 +++++++++++--------------------------- 1 file changed, 80 insertions(+), 201 deletions(-) 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(); From a7690f27f96a96b044a5424118f7d98f695343b8 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:35:43 +0100 Subject: [PATCH 46/71] test(TL-U10): smoke native schema-2 public exports and reject legacy domain/React interfaces --- scripts/verify-dist.mjs | 29 +++++++++++++++++++---------- 1 file changed, 19 insertions(+), 10 deletions(-) diff --git a/scripts/verify-dist.mjs b/scripts/verify-dist.mjs index 2513b56d..531fb5a0 100644 --- a/scripts/verify-dist.mjs +++ b/scripts/verify-dist.mjs @@ -90,20 +90,29 @@ assert.match(help.stdout, /thl materialize/); 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 { 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], -); +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"]); +assert.deepEqual(core.inspectTrace(trace).valueAt(1, "counter"), { status: "known", value: 1 }); 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."); From 52df71617b943a26349faa26dcaec6ed12b6c8e9 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:36:37 +0100 Subject: [PATCH 47/71] test(TL-U10): keep legacy domain boundary regressions internal after public removal --- src/domains/__tests__/public-api-boundaries.test.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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", () => { From 967cb7d59bc21c7954565fdebfbf2ae5a5bcb05a Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:39:10 +0100 Subject: [PATCH 48/71] fix(TL-U10): verify schema-2 root re-export facade without legacy registry chunk name --- scripts/verify-dist.mjs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/scripts/verify-dist.mjs b/scripts/verify-dist.mjs index 531fb5a0..9c3f6037 100644 --- a/scripts/verify-dist.mjs +++ b/scripts/verify-dist.mjs @@ -68,8 +68,9 @@ 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.includes("export") || rootFacade.includes("from")) && + artifacts.some((file) => file.endsWith(".js.map")), + "Unmapped root entry must be a small re-export facade with mapped chunks", ); } From fe279e526d1a99d789cacbb88975a73e15e4da7c Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:41:02 +0100 Subject: [PATCH 49/71] fix(TL-U10): permit larger schema-2 export facade while requiring mapped runtime chunks --- scripts/verify-dist.mjs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/scripts/verify-dist.mjs b/scripts/verify-dist.mjs index 9c3f6037..2b148afc 100644 --- a/scripts/verify-dist.mjs +++ b/scripts/verify-dist.mjs @@ -67,10 +67,10 @@ for (const filename of ["react/index.js", "remark/index.js", "examples.js", "nod if (!existsSync(resolve(root, "dist/index.js.map"))) { const rootFacade = readFileSync(resolve(root, "dist/index.js"), "utf8"); assert( - rootFacade.length < 1024 && + rootFacade.length < 16 * 1024 && (rootFacade.includes("export") || rootFacade.includes("from")) && artifacts.some((file) => file.endsWith(".js.map")), - "Unmapped root entry must be a small re-export facade with mapped chunks", + "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 + ")", ); } From e923a60167776bb3e015912cc669222e292dcbda Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:42:52 +0100 Subject: [PATCH 50/71] test(TL-U10): assert null-prototype inspector cell semantics rather than plain-object equality --- scripts/verify-dist.mjs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/scripts/verify-dist.mjs b/scripts/verify-dist.mjs index 2b148afc..2c049f3b 100644 --- a/scripts/verify-dist.mjs +++ b/scripts/verify-dist.mjs @@ -107,7 +107,10 @@ const exampleArtifact = { }; const trace = core.compileArtifact(exampleArtifact); assert.deepEqual(trace.frames.map(frame => frame.id), ["@initial", "increment"]); -assert.deepEqual(core.inspectTrace(trace).valueAt(1, "counter"), { status: "known", value: 1 }); +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"); From a83e768eaeaf87b72d18d4a62a8ba66829a5e59b Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 13:45:15 +0100 Subject: [PATCH 51/71] fix(TL-U10): make native fullscreen control capability SSR and hydration-stable --- src/react/graph-player.tsx | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) 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, }}/> From 697c50b16884ea2bd3254edb621c69363b2f3811 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 14:09:28 +0100 Subject: [PATCH 52/71] docs(TL-U10): replace outdated v1 architecture with current schema-2 data, API and host boundaries --- docs/architecture.md | 311 +++++++------------------------------------ 1 file changed, 50 insertions(+), 261 deletions(-) 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). From 9fff88eb90a2d114e0d76a070116bc6db66967d6 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 14:10:08 +0100 Subject: [PATCH 53/71] docs(TL-U10): align contributor rules with v2-only exports, CLI and non-evaluating mdast contract --- AGENTS.md | 146 ++++++++++++++++++------------------------------------ 1 file changed, 49 insertions(+), 97 deletions(-) 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). From 7638f4aa2a093a23728ee5ba3256cd84d57de948 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 14:11:26 +0100 Subject: [PATCH 54/71] fix(TL-U10): replace raw fence scanner with non-evaluating Markdown and MDX mdast traversal --- src/node/markdown.ts | 191 ++++++++++++++++++++----------------------- 1 file changed, 87 insertions(+), 104 deletions(-) diff --git a/src/node/markdown.ts b/src/node/markdown.ts index de1902bc..c5a87a1c 100644 --- a/src/node/markdown.ts +++ b/src/node/markdown.ts @@ -1,9 +1,13 @@ /** - * Offline, non-evaluating Markdown/MDX fenced-code discovery for the CLI. - * No MDX execution, React, Remark plugins, HTML rendering or AI providers. - * Supports CommonMark fences in plain, quoted and list code blocks. - * Production Remark integration continues to consume real mdast nodes. + * 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<{ @@ -15,111 +19,90 @@ export type MarkdownFence = Readonly<{ ordinal: number | null; }>; -const MAX_MARKDOWN_BYTES = 4 * 1024 * 1024; -const MAX_NODES = 10_000; -const fail = (message: string): never => { - throw new ThroughlineAuthoringError("THL_SYNTAX", message); -}; -type Prefix = { quotes: number; listIndent: number; leading: number; remaining: string }; +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 } }; +}>; -function stripQuotes(value: string, depth: number): string | null { - let at = 0; - for (let index = 0; index < depth; index++) { - const match = /^ {0,3}> ?/.exec(value.slice(at)); - if (!match) return null; - at += match[0].length; - } - return value.slice(at); -} -function openerPrefix(line: string): Prefix { - let remaining = line; - let quotes = 0; - while (quotes < 32) { - const match = /^ {0,3}> ?/.exec(remaining); - if (!match) break; - quotes++; - remaining = remaining.slice(match[0].length); - } - let listIndent = 0; - const list = /^ {0,3}(?:[-+*]|\d{1,9}[.)])([ \t]+)/.exec(remaining); - if (list) { - listIndent = list[0].length; - remaining = remaining.slice(listIndent); - } - const leading = /^ */.exec(remaining)?.[0].length ?? 0; - return { quotes, listIndent, leading, remaining }; -} -function contentLine(line: string, prefix: Prefix): string | null { - let rest = stripQuotes(line, prefix.quotes); - if (rest === null) { - if (line.trim() === "") return ""; - return null; - } - if (prefix.listIndent) { - if (rest.trim() === "") return ""; - const spaces = /^ */.exec(rest)?.[0].length ?? 0; - if (spaces < prefix.listIndent) return null; - rest = rest.slice(prefix.listIndent); - } - const indent = /^ */.exec(rest)?.[0].length ?? 0; - return rest.slice(Math.min(prefix.leading, indent)); -} -function closingFence(line: string, symbol: string, minimum: number): boolean { - const match = /^ {0,3}(\x60+|~+)[ \t]*$/.exec(line); - return !!match && match[1][0] === symbol && match[1].length >= minimum; -} +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); /** - * Extract fenced code nodes in lexical/depth-first order. The info string - * cannot contain a backtick for that fence style. Unclosed fences are - * CommonMark-valid and consume the rest of their container. - * The body excludes delimiters and a synthetic final newline. + * 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): readonly MarkdownFence[] { - if (typeof source !== "string" || Buffer.byteLength(source, "utf8") > MAX_MARKDOWN_BYTES) - fail("Markdown document is not a bounded UTF-8 string"); - const normalized = normalizeThlBody(source).replace(/^\uFEFF/, ""); - const lines = normalized.split("\n"); - const results: MarkdownFence[] = []; +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; - for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) { - const current = lines[lineIndex]; - const prefix = openerPrefix(current); - if (prefix.leading > 3) continue; - const raw = prefix.remaining.slice(prefix.leading); - const opening = /^(\x60{3,}|~{3,})([^\r\n]*)$/.exec(raw); - if (!opening) continue; - const symbol = opening[1][0]; - const info = opening[2].trim(); - if (symbol === "\x60" && info.includes("\x60")) continue; - // First info word is language, rest metadata. Domain tags are invalid. - const tokens = /^(\S+)(?:\s+([\s\S]+))?$/.exec(info); - const lang = tokens?.[1] ?? null; - const meta = tokens?.[2] ?? null; - const bodyLines: string[] = []; - let end = lineIndex; - for (let next = lineIndex + 1; next < lines.length; next++) { - const parsed = contentLine(lines[next], prefix); - if (parsed === null) break; - if (closingFence(parsed, symbol, opening[1].length)) { - end = next; - break; - } - if (next === lines.length - 1 && lines[next] === "" && normalized.endsWith("\n")) { - end = next; - break; - } - bodyLines.push(parsed); - end = next; + 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 }); } - if (results.length >= MAX_NODES) fail("too many fenced code nodes"); - const isThl = lang === "thl"; - results.push(Object.freeze({ - lang, meta, body: bodyLines.join("\n"), line: lineIndex + 1, - column: current.length - raw.length + 1, - ordinal: isThl ? ordinal++ : null, - })); - lineIndex = end; } - return Object.freeze(results); + return Object.freeze(fences); } From 71785e699b51c55d874af2f85ac33e00f4281653 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 14:11:38 +0100 Subject: [PATCH 55/71] fix(TL-U10): use actual Markdown or MDX AST code nodes in CLI check and materialize --- src/cli/commands.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/cli/commands.ts b/src/cli/commands.ts index c704a489..38a53c50 100644 --- a/src/cli/commands.ts +++ b/src/cli/commands.ts @@ -105,7 +105,7 @@ function checkFile( manifest: SidecarManifest | undefined, io: CliIO, ): number { const markdown = root.read(relative); - const fences = scanMarkdownFences(markdown); + const fences = scanMarkdownFences(markdown, { format: relative.endsWith(".mdx") ? "mdx" : "md" }); let checked = 0; for (const fence of fences) { if (fence.lang !== "thl") continue; @@ -156,7 +156,7 @@ function materialize(root: TrustedContentRoot, args: Arguments, io: CliIO): void !Number.isSafeInteger(Number(ordinalRaw))) usage("--ordinal must be a zero-based safe integer"); const ordinal = Number(ordinalRaw); - const fences = scanMarkdownFences(root.read(document)); + 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", From b8746100f08768f4f29c82ef6e324ca0dac68930 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 14:12:05 +0100 Subject: [PATCH 56/71] fix(TL-U10): declare and audit non-evaluating Markdown/MDX parser dependencies (package.json) --- package.json | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/package.json b/package.json index 9e3acc03..2b6477f1 100644 --- a/package.json +++ b/package.json @@ -67,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", From c9c1970bf4cb39033fa055b88d48271778b0d2bb Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 14:12:08 +0100 Subject: [PATCH 57/71] fix(TL-U10): declare and audit non-evaluating Markdown/MDX parser dependencies (tsdown.config.ts) --- tsdown.config.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tsdown.config.ts b/tsdown.config.ts index c14c072a..a39a06f9 100644 --- a/tsdown.config.ts +++ b/tsdown.config.ts @@ -24,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", "node:fs", "node:path", "node:crypto"], + onlyImport: ["cn", "react", "react-dom", "node:fs", "node:path", "node:crypto", "remark-parse", "remark-mdx", "unified"], }, }); From 666ec962e66f0edd37854d79d1cd2555b226ba1f Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 14:12:10 +0100 Subject: [PATCH 58/71] fix(TL-U10): declare and audit non-evaluating Markdown/MDX parser dependencies (scripts/audit-licenses.mjs) --- scripts/audit-licenses.mjs | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/scripts/audit-licenses.mjs b/scripts/audit-licenses.mjs index a56e622b..1377c769 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( @@ -68,12 +68,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"); From a9ac11bb42bb84f6a396e7eb5873c92255fcb9bf Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 14:12:13 +0100 Subject: [PATCH 59/71] fix(TL-U10): declare and audit non-evaluating Markdown/MDX parser dependencies (scripts/audit-source.mjs) --- scripts/audit-source.mjs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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"), ); From 7f455f1b1c67e7c7c3e43987e18c3dc67ca94e2f Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 14:12:16 +0100 Subject: [PATCH 60/71] fix(TL-U10): declare and audit non-evaluating Markdown/MDX parser dependencies (scripts/audit-pack.mjs) --- scripts/audit-pack.mjs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/scripts/audit-pack.mjs b/scripts/audit-pack.mjs index 695926e7..ca758817 100644 --- a/scripts/audit-pack.mjs +++ b/scripts/audit-pack.mjs @@ -98,7 +98,7 @@ try { [".", "./react", "./remark", "./examples", "./node", "./styles/throughline.css"].sort(), ); assert.equal(packed.bin?.thl, "./dist/cli/main.js"); - assert.deepEqual(Object.keys(packed.dependencies ?? {}), ["cn"]); + assert.deepEqual(Object.keys(packed.dependencies ?? {}), ["cn", "remark-mdx", "remark-parse", "unified"]); for (const dependencies of [ packed.dependencies ?? {}, packed.peerDependencies ?? {}, @@ -195,7 +195,8 @@ try { ].join("\n"); run("node", ["--input-type=module", "-e", pureHost, fixtureRoot], consumer); assert(!existsSync(join(consumer, "node_modules", "react")) && - !existsSync(join(consumer, "node_modules", "unified")), + !!existsSync(join(consumer, "node_modules", "unified")) && + !!existsSync(join(consumer, "node_modules", "remark-mdx")), "CLI/Node host must not require React or a runtime Markdown executor"); const core = [ From bf0016cceb0c4dff302fcc2d989c7ef6f54102c7 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 14:12:40 +0100 Subject: [PATCH 61/71] chore(TL-U10): temporarily run branch-scoped lock regeneration for reviewed parser dependencies --- .github/workflows/tl-u10-lock-refresh.yml | 39 +++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 .github/workflows/tl-u10-lock-refresh.yml diff --git a/.github/workflows/tl-u10-lock-refresh.yml b/.github/workflows/tl-u10-lock-refresh.yml new file mode 100644 index 00000000..f5a80d59 --- /dev/null +++ b/.github/workflows/tl-u10-lock-refresh.yml @@ -0,0 +1,39 @@ +name: Temporary TL-U10 lockfile refresh + +# Temporary branch-scoped maintenance job. Remove after the lockfile is committed. +on: + push: + branches: + - feat/tl-u10-cli-host-security + paths: + - .github/workflows/tl-u10-lock-refresh.yml + +permissions: + contents: write + +jobs: + refresh: + runs-on: ubuntu-latest + timeout-minutes: 10 + steps: + - uses: actions/checkout@v6 + with: + persist-credentials: true + - uses: pnpm/action-setup@v6 + - uses: actions/setup-node@v6 + with: + node-version: '24' + - name: Generate exact lockfile for reviewed AST dependencies + run: pnpm install --lockfile-only --no-frozen-lockfile --ignore-scripts + - name: Commit changed dependency resolution to same branch + shell: bash + run: | + if git diff --quiet -- pnpm-lock.yaml; then + echo "Lockfile already current" + exit 0 + fi + git config user.name 'github-actions[bot]' + git config user.email '41898282+github-actions[bot]@users.noreply.github.com' + git add pnpm-lock.yaml + git -c commit.gpgsign=false commit --signoff -m 'chore(TL-U10): lock audited Markdown and MDX syntax parsers' + git push origin HEAD:refs/heads/feat/tl-u10-cli-host-security From 63b8587ce617f6dd225bce6bcf6080afe80fcb51 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sun, 15 Nov 2026 13:13:05 +0000 Subject: [PATCH 62/71] chore(TL-U10): lock audited Markdown and MDX syntax parsers Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- pnpm-lock.yaml | 720 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 720 insertions(+) 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: {} From ac8c58775205e69d5a007c4bb1f735c136bb7173 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 14:13:38 +0100 Subject: [PATCH 63/71] chore(TL-U10): remove temporary lockfile refresh after signed-off frozen resolution --- .github/workflows/tl-u10-lock-refresh.yml | 39 ----------------------- 1 file changed, 39 deletions(-) delete mode 100644 .github/workflows/tl-u10-lock-refresh.yml diff --git a/.github/workflows/tl-u10-lock-refresh.yml b/.github/workflows/tl-u10-lock-refresh.yml deleted file mode 100644 index f5a80d59..00000000 --- a/.github/workflows/tl-u10-lock-refresh.yml +++ /dev/null @@ -1,39 +0,0 @@ -name: Temporary TL-U10 lockfile refresh - -# Temporary branch-scoped maintenance job. Remove after the lockfile is committed. -on: - push: - branches: - - feat/tl-u10-cli-host-security - paths: - - .github/workflows/tl-u10-lock-refresh.yml - -permissions: - contents: write - -jobs: - refresh: - runs-on: ubuntu-latest - timeout-minutes: 10 - steps: - - uses: actions/checkout@v6 - with: - persist-credentials: true - - uses: pnpm/action-setup@v6 - - uses: actions/setup-node@v6 - with: - node-version: '24' - - name: Generate exact lockfile for reviewed AST dependencies - run: pnpm install --lockfile-only --no-frozen-lockfile --ignore-scripts - - name: Commit changed dependency resolution to same branch - shell: bash - run: | - if git diff --quiet -- pnpm-lock.yaml; then - echo "Lockfile already current" - exit 0 - fi - git config user.name 'github-actions[bot]' - git config user.email '41898282+github-actions[bot]@users.noreply.github.com' - git add pnpm-lock.yaml - git -c commit.gpgsign=false commit --signoff -m 'chore(TL-U10): lock audited Markdown and MDX syntax parsers' - git push origin HEAD:refs/heads/feat/tl-u10-cli-host-security From a3413e1309fc431427e6dc63c4e8680b3b4dde18 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 14:14:40 +0100 Subject: [PATCH 64/71] test(TL-U10): require real mdast depth-first nested fences and reject comment/JSX false positives --- src/__tests__/cli.test.ts | 130 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) diff --git a/src/__tests__/cli.test.ts b/src/__tests__/cli.test.ts index 1e0dfe0b..ffae2528 100644 --- a/src/__tests__/cli.test.ts +++ b/src/__tests__/cli.test.ts @@ -4,6 +4,9 @@ import { 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"; @@ -123,6 +126,133 @@ describe("TL-U10 CLI / source and sidecar boundary", () => { 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]; From 9cb5fde57183e5ec3b6e67a854b8bfccbb1654a6 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 14:15:38 +0100 Subject: [PATCH 65/71] fix(TL-U10): give bounded mdast discovery a stable authoring limit diagnostic --- src/v2/authoring.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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"; From 21f93244a81e2926b28707595831b1e5d470e9b4 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 14:16:55 +0100 Subject: [PATCH 66/71] test(TL-U10): update legacy scanner expectation to actual CommonMark nested-list semantics --- src/__tests__/cli.test.ts | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/__tests__/cli.test.ts b/src/__tests__/cli.test.ts index ffae2528..b857d641 100644 --- a/src/__tests__/cli.test.ts +++ b/src/__tests__/cli.test.ts @@ -109,7 +109,7 @@ describe("TL-U10 CLI / source and sidecar boundary", () => { "~~~mdx", "text", "~~~", "", "> ~~~thl", "> Explain nested quote.", "> ~~~", "", "- ~~~thl", " Explain nested list.", " ~~~", "", - " ~~~thl", " indented code, not a fence", " ~~~", "", + " ~~~thl", " Continuation nested in the list.", " ~~~", "", "~~~thl binary", "meta is unsupported", "~~~", "", "~~~mermaid", "graph TD", "~~~", ].join("\n"); @@ -117,7 +117,8 @@ describe("TL-U10 CLI / source and sidecar boundary", () => { expect(nodes.filter(node => node.lang === "thl") .map(node => [node.ordinal, node.body])).toEqual([ [0, "Explain nested quote."], [1, "Explain nested list."], - [2, "meta is unsupported"], + [2, "Continuation nested in the list."], + [3, "meta is unsupported"], ]); expect(nodes.filter(node => node.lang === "mermaid")).toHaveLength(1); const directory = fixture(); From e6b07be6640e933067779f4b53aadfa7e2d51194 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 14:18:02 +0100 Subject: [PATCH 67/71] test(TL-U10): assert independent packed CLI parses nested mdast fences and ignores HTML comments --- scripts/audit-pack.mjs | 47 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 44 insertions(+), 3 deletions(-) diff --git a/scripts/audit-pack.mjs b/scripts/audit-pack.mjs index ca758817..141f20c5 100644 --- a/scripts/audit-pack.mjs +++ b/scripts/audit-pack.mjs @@ -132,8 +132,10 @@ 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. @@ -194,10 +196,49 @@ try { ' { 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 or a runtime Markdown executor"); + "CLI/Node host must not require React, but must carry its non-evaluating syntax parsers"); const core = [ 'import assert from "node:assert/strict";', From ac954b38a63fdf084159d37a4f36eed6034f59db Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 14:18:40 +0100 Subject: [PATCH 68/71] docs(TL-U10): align CHANGELOG.md with real syntax-tree discovery and schema-2 boundary --- CHANGELOG.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index db32b810..54d12657 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,8 @@ # 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] @@ -20,6 +20,11 @@ program and trace schemas. Changes are grouped using 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 From fd0eddfa11c37793aa7a35b1890931e3a50fe3c7 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 14:18:43 +0100 Subject: [PATCH 69/71] docs(TL-U10): align docs/cli.md with real syntax-tree discovery and schema-2 boundary --- docs/cli.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index d746897e..e0be4c32 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -84,9 +84,13 @@ unconditionally; malformed JSON cannot silently become prose. ### What check does The CLI walks `.md` and `.mdx` files in deterministic path order, -discovers fenced code blocks without evaluating MDX, and validates each -`thl` code node. Unrelated JavaScript, math and Mermaid remain -ordinary Markdown. Unqualified fences alone are accepted; domain +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. From e407d6e204db7465a3689517979f4fc066803190 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 14:18:46 +0100 Subject: [PATCH 70/71] docs(TL-U10): align src/node/index.ts with real syntax-tree discovery and schema-2 boundary --- src/node/index.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/node/index.ts b/src/node/index.ts index 07de3b7a..7f376fc6 100644 --- a/src/node/index.ts +++ b/src/node/index.ts @@ -3,10 +3,10 @@ import { } from "../v2/authoring.js"; import { parseStrictJsonData } from "../v2/validator.js"; import { TrustedContentRoot, TrustedFileError } from "./files.js"; -import { scanMarkdownFences, type MarkdownFence } from "./markdown.js"; +import { scanMarkdownFences, type MarkdownFence, type MarkdownFormat } from "./markdown.js"; export { TrustedContentRoot, TrustedFileError, scanMarkdownFences }; -export type { MarkdownFence }; +export type { MarkdownFence, MarkdownFormat }; export type NodeHostOptions = Readonly<{ /** Trusted repository/content root. All sidecar paths resolve within it. */ From 74cf26006047baed29973ea5df6a35d0d8887a97 Mon Sep 17 00:00:00 2001 From: "Christopher S. Aondona" Date: Sun, 15 Nov 2026 14:21:10 +0100 Subject: [PATCH 71/71] fix(TL-U10): locate pnpm-hoisted transitive type dependencies during strict license audit --- scripts/audit-licenses.mjs | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/scripts/audit-licenses.mjs b/scripts/audit-licenses.mjs index 1377c769..e14b971e 100644 --- a/scripts/audit-licenses.mjs +++ b/scripts/audit-licenses.mjs @@ -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);