indusagi-coding-agent 0.1.59 → 0.1.60

package/dist/types/sessions/library.d.ts

@@ -0,0 +1,95 @@
+/**
+ * SessionLibrary — the catalog-and-navigation layer over persisted transcripts.
+ *
+ * The conductor owns a single session at a time as a {@link TranscriptStore}.
+ * The library owns the *collection*: it scans the workspace `sessions/`
+ * directory for the NDJSON files the conductor's filesystem backend writes,
+ * lists them as {@link SavedSession} catalog rows, opens any one back into a
+ * live store via the store's own loader + {@link replay} reducer, and offers the
+ * two read projections a chooser UI needs — a flattened {@link BranchNode} tree
+ * for a branch navigator and a {@link PriorTurn} list for re-asking an earlier
+ * prompt. It also performs the two file-level mutations a manager needs:
+ * renaming and deleting a session on disk.
+ *
+ * The library never re-implements transcript parsing or message serialization —
+ * it delegates entirely to the conductor's transcript-store surface
+ * ({@link TranscriptStore}, {@link fsBackend}, {@link replay}). Its own logic is
+ * purely the directory enumeration, the tree flatten, and the text reduction.
+ */
+import { TranscriptStore } from "../conductor";
+import type { BranchNode, PriorTurn, SavedSession } from "./contract";
+/** Construction inputs — just the directory sessions live under. */
+export interface SessionLibraryOptions {
+    /** Absolute path to the workspace `sessions/` directory. */
+    readonly sessionsDir: string;
+}
+/**
+ * The collection-level handle over a workspace's persisted sessions.
+ *
+ * Construct it with the resolved `sessionsDir` (from the workspace locator),
+ * then call {@link list} / {@link open} / {@link rename} / {@link remove} to
+ * manage files, and {@link tree} / {@link priorTurns} to project a loaded
+ * transcript for navigation and forking.
+ */
+export declare class SessionLibrary {
+    #private;
+    constructor(options: SessionLibraryOptions);
+    /** The sessions directory this library is rooted at. */
+    get directory(): string;
+    /**
+     * Enumerate persisted sessions as catalog rows, newest-modified first.
+     *
+     * Scans the directory for `*.ndjson` files and `stat`s each for its size and
+     * modification time. When `deep` is set, it also opens each file to fill in
+     * `messageCount` and the opening-turn `preview`; otherwise it returns the
+     * shallow rows (id/path/size/lastModified) so a large directory lists fast.
+     * A missing directory yields an empty list rather than an error.
+     */
+    list(options?: {
+        readonly deep?: boolean;
+    }): Promise<SavedSession[]>;
+    /**
+     * Open a persisted session back into a live, hydrated {@link TranscriptStore},
+     * or return `null` when no file with that id exists.
+     *
+     * Delegates to the store's own static opener, which reads the backend and
+     * rebuilds state through the {@link replay} reducer — the library adds nothing
+     * to the rehydration beyond binding the filesystem backend.
+     */
+    open(id: string): Promise<TranscriptStore | null>;
+    /**
+     * Rename a session file from one id to another, returning the new absolute
+     * path. The on-disk identifier *is* the filename stem, so this is a plain file
+     * move; the in-file head still names the old id, which the store tolerates on
+     * the next load (the head's leaf is what matters, not its session label).
+     *
+     * @throws if the source file is missing or the target id already exists.
+     */
+    rename(fromId: string, toId: string): Promise<string>;
+    /**
+     * Delete a session file. Returns `true` when a file was removed, `false` when
+     * there was nothing to delete — never throws on an already-absent session.
+     */
+    remove(id: string): Promise<boolean>;
+    /** Absolute path a session id persists to. */
+    pathOf(id: string): string;
+    /**
+     * Flatten a loaded transcript into an ordered {@link BranchNode} list for a
+     * tree navigator.
+     *
+     * Walks every node from each root downward in a stable depth-first order,
+     * emitting one row per node with its render label, depth indentation, leaf
+     * flag, and a current-marker derived from the store's active head. A node is a
+     * leaf when no other node names it as `parent`.
+     */
+    tree(store: TranscriptStore): BranchNode[];
+    /**
+     * Extract the user prompts along a loaded transcript's active branch as fork
+     * candidates, in chronological order.
+     *
+     * Reads the root→leaf branch the store currently points at (the conversation
+     * the agent would replay) and keeps only the user-role nodes that carry real
+     * text, projecting each to a {@link PriorTurn} a forking picker can offer.
+     */
+    priorTurns(store: TranscriptStore): PriorTurn[];
+}

package/dist/types/sessions/sessions.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * SessionLibrary behavioral tests.
+ *
+ * Exercises the catalog-and-navigation layer end-to-end against a real temp
+ * `sessions/` directory: we seed a couple of sessions by driving real
+ * {@link TranscriptStore}s over a filesystem backend (so the on-disk NDJSON is
+ * the genuine format), then assert the library lists them, opens them, flattens
+ * the branch tree, and extracts prior user turns. File mutations (rename/remove)
+ * are checked too. No network, no framework agent — just disk + the store.
+ */
+export {};

package/dist/types/settings/contract.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Settings subsystem — the typed surface of the user-tunable preferences an
+ * interactive coding-agent session reads at startup and while it runs.
+ *
+ * This module declares *only* shapes and frozen defaults — no I/O, no class, no
+ * filesystem. It is the single place every preference key is named, typed, and
+ * given a fallback. The two-tier manager ({@link "./manager"}) is written
+ * against the {@link Preferences} record declared here, and any console surface
+ * that toggles a preference reads its value through the same record.
+ *
+ * Design stance:
+ *   - Every key is optional on the record so a partially-written file is a
+ *     legal {@link Preferences} value; the manager fills the gaps from
+ *     {@link DEFAULT_PREFERENCES} when a reader asks for a concrete value.
+ *   - Reasoning-effort vocabulary is borrowed from the framework
+ *     ({@link ThinkingLevel}) rather than re-declared, so the agent and the UI
+ *     speak the same words.
+ *   - The other small string unions ({@link ColourScheme} is a free string,
+ *     while {@link EscapeAction}) pin the surfaces a console reads.
+ */
+import type { ThinkingLevel } from "indusagi/agent";
+/** Re-exported framework reasoning vocabulary, surfaced through this contract. */
+export type { ThinkingLevel };
+/**
+ * What a double-tap of the escape key does in the interactive console.
+ *
+ *   - `tree`     — open the turn history as a navigable tree of branches.
+ *   - `fork`     — open the prior-turn picker to branch off an earlier turn.
+ *   - `clear`    — wipe the composer buffer.
+ *
+ * The legacy `rewind` / `branch` aliases are still accepted and treated as
+ * `fork` / `tree` respectively so an older preference file keeps working.
+ */
+export type EscapeAction = "tree" | "fork" | "clear" | "rewind" | "branch";
+/** Every {@link EscapeAction} value, as a frozen tuple for menus and guards. */
+export declare const ESCAPE_ACTIONS: readonly EscapeAction[];
+/** Narrow an arbitrary value to a known {@link EscapeAction}. */
+export declare function isEscapeAction(value: unknown): value is EscapeAction;
+/**
+ * How a queue of pending turns (steering corrections or follow-up prompts) is
+ * drained back into the run.
+ *
+ *   - `all`           — release every queued turn at once on the next handoff.
+ *   - `one-at-a-time` — release a single queued turn per handoff.
+ */
+export type DeliveryMode = "all" | "one-at-a-time";
+/** Every {@link DeliveryMode} value, as a frozen tuple for menus and guards. */
+export declare const DELIVERY_MODES: readonly DeliveryMode[];
+/** Narrow an arbitrary value to a known {@link DeliveryMode}. */
+export declare function isDeliveryMode(value: unknown): value is DeliveryMode;
+/**
+ * Every preference an interactive coding-agent session reads, as one flat,
+ * fully-optional record.
+ *
+ * A value of this type may be the empty object (a brand-new install), a sparse
+ * project override, or a fully-populated global file — all three are legal.
+ * Concrete reads always go through the manager, which layers the project file
+ * over the global file over {@link DEFAULT_PREFERENCES}, so a reader never sees
+ * `undefined` for a key with a default.
+ */
+export interface Preferences {
+    /** Named colour scheme the console renders with (e.g. `"midnight"`). */
+    colourScheme?: string;
+    /** Whether inline image content is rendered in the transcript. */
+    showImages?: boolean;
+    /** Whether the model's reasoning / thinking text is shown as it streams. */
+    showReasoning?: boolean;
+    /** When true, the reasoning block is folded away even if the model emits one. */
+    hideThinking?: boolean;
+    /** Whether oversized images are shrunk to fit before being handed to a provider. */
+    imageAutoResize?: boolean;
+    /** When true, image content is withheld from providers entirely. */
+    blockImages?: boolean;
+    /** Whether discovered skills are surfaced as their own slash commands. */
+    enableSkillCommands?: boolean;
+    /** How queued steering corrections are released back into the run. */
+    steeringMode?: DeliveryMode;
+    /** How queued follow-up prompts are released back into the run. */
+    followUpMode?: DeliveryMode;
+    /** Prefer a condensed changelog after the console updates itself. */
+    collapseChangelog?: boolean;
+    /** Reveal the terminal's own cursor instead of the software-drawn caret. */
+    showHardwareCursor?: boolean;
+    /** Horizontal padding, in columns, around the prompt editor. */
+    editorPaddingX?: number;
+    /** Glob / id patterns selecting which models appear in the picker; empty means all. */
+    enabledModels?: string[];
+    /** Provider id the session defaults to when none is named (e.g. `"anthropic"`). */
+    defaultProvider?: string;
+    /** Model id the session opens with under {@link defaultProvider}. */
+    defaultModel?: string;
+    /** Reasoning effort the session requests by default. */
+    defaultThinkingLevel?: ThinkingLevel;
+    /** Suppress the banner / tips shown on a normal interactive launch. */
+    quietStartup?: boolean;
+    /** Whether the window-budget manager compacts the transcript automatically. */
+    autoCompact?: boolean;
+    /** What a double-escape does in the console. */
+    doubleEscapeAction?: EscapeAction;
+    /** Extension-package sources the launcher installs and loads (npm / git / local). */
+    extensionPackages?: string[];
+}
+/** The set of legal preference keys, derived from {@link Preferences}. */
+export type SettingKey = keyof Preferences;
+/**
+ * The fallback value for every preference, used whenever neither the project
+ * nor the global tier supplies a key.
+ *
+ * Frozen so it can be shared without a defensive copy; the manager spreads it
+ * rather than mutating it. Every key in {@link Preferences} appears here with a
+ * concrete (non-`undefined`) value, which is what lets a typed reader resolve a
+ * guaranteed result.
+ */
+export declare const DEFAULT_PREFERENCES: Required<Preferences>;
+/** Every preference key, as a frozen tuple for iteration and validation. */
+export declare const SETTING_KEYS: readonly SettingKey[];

package/dist/types/settings/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Settings subsystem — public barrel.
+ *
+ * One import site for the typed {@link Preferences} record and its
+ * {@link SettingKey} / {@link EscapeAction} / {@link ThinkingLevel}
+ * vocabularies, the frozen {@link DEFAULT_PREFERENCES}, and the two-tier
+ * {@link PreferenceStore} reader/writer. Console surfaces and boot stages depend
+ * on this module rather than reaching into the individual files.
+ */
+export type { Preferences, SettingKey, EscapeAction, DeliveryMode, ThinkingLevel, } from "./contract";
+export { DEFAULT_PREFERENCES, SETTING_KEYS, ESCAPE_ACTIONS, isEscapeAction, DELIVERY_MODES, isDeliveryMode, } from "./contract";
+export { PreferenceStore } from "./manager";
+export type { PreferenceLocations } from "./manager";

package/dist/types/settings/manager.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Settings manager — the two-tier reader/writer over the preference record.
+ *
+ * Two files back the same {@link Preferences} shape:
+ *
+ *   - the **global** file, one per machine, living in the resolved workspace
+ *     profile directory ({@link Workspace.settingsPath});
+ *   - the **project** file, one per checkout, living beside the working tree in
+ *     a brand-named config directory.
+ *
+ * A read layers the project tier over the global tier over
+ * {@link DEFAULT_PREFERENCES}: a key set in the project file wins, then the
+ * global file, then the built-in default — so a reader of {@link PreferenceStore.get}
+ * always receives a concrete value. A write through {@link PreferenceStore.set}
+ * lands in the **project** tier only; the global file is left untouched, which
+ * keeps a per-checkout override from silently leaking machine-wide.
+ *
+ * Loading is tolerant: a missing file is the empty record, and a corrupt file
+ * (bad JSON, or a JSON value that is not an object) degrades to the empty record
+ * rather than throwing, so one mangled file never blocks startup.
+ *
+ * Construction is injectable. {@link PreferenceStore.fromWorkspace} resolves the
+ * two paths from a {@link Workspace} and the working directory; {@link PreferenceStore.atPaths}
+ * pins both paths directly, which is what the tests drive against a temp dir so
+ * the real home is never read or written.
+ */
+import type { Workspace } from "../boot/contract";
+import { type Preferences, type SettingKey } from "./contract";
+/**
+ * The resolved location of the two preference tiers.
+ *
+ * Both are absolute paths. The {@link global} file is machine-wide; the
+ * {@link project} file is per-checkout. Either may be absent on disk — the
+ * store treats a missing file as the empty record.
+ */
+export interface PreferenceLocations {
+    /** Machine-wide preference file (the global tier). */
+    readonly global: string;
+    /** Per-checkout preference file (the project tier). */
+    readonly project: string;
+}
+/**
+ * Two-tier preference store: project-over-global-over-default on read, and a
+ * project-tier write on save.
+ *
+ * Construct via {@link fromWorkspace} (resolve from the workspace + cwd) or
+ * {@link atPaths} (pin both files explicitly, as the tests do). Internally the
+ * two tiers are held in memory and refreshed from disk on construction and on
+ * {@link reload}; {@link set} stages a change into the in-memory project tier
+ * and {@link save} flushes it.
+ */
+export declare class PreferenceStore {
+    private readonly locations;
+    private globalTier;
+    private projectTier;
+    private constructor();
+    /**
+     * Build a store whose two tiers are pinned to explicit absolute paths.
+     *
+     * The direct seam used by tests: point both files at a temp dir and the real
+     * home is never touched. Neither file needs to exist yet.
+     */
+    static atPaths(locations: PreferenceLocations): PreferenceStore;
+    /**
+     * Build a store from a resolved {@link Workspace} (global tier) and a working
+     * directory (project tier).
+     *
+     * The global file is {@link Workspace.settingsPath}; the project file is
+     * `<cwd>/<brand profile dir>/settings.json`, so a checkout carries its own
+     * overrides next to its source. `cwd` defaults to the process working
+     * directory.
+     */
+    static fromWorkspace(workspace: Workspace, cwd?: string): PreferenceStore;
+    /** The two resolved file locations this store reads and writes. */
+    paths(): PreferenceLocations;
+    /** Re-read both tiers from disk, discarding any unsaved staged change. */
+    reload(): void;
+    /**
+     * Read one preference, resolved across the tiers.
+     *
+     * Precedence is project → global → {@link DEFAULT_PREFERENCES}: the first tier
+     * that defines the key (with a non-`undefined` value) wins. The return type is
+     * the concrete default-backed type for the key, so callers never branch on
+     * `undefined`.
+     */
+    get<K extends SettingKey>(key: K): Required<Preferences>[K];
+    /**
+     * Stage a preference into the in-memory **project** tier.
+     *
+     * Does not write to disk on its own — call {@link save} to persist. Setting a
+     * key to `undefined` clears the project-tier override for it, letting the
+     * value fall back to the global tier or the default on the next read.
+     */
+    set<K extends SettingKey>(key: K, value: Preferences[K]): void;
+    /** The fully-resolved snapshot: defaults under global under project. */
+    snapshot(): Required<Preferences>;
+    /** The raw in-memory project tier (the keys a checkout overrides). */
+    projectOverrides(): Preferences;
+    /** The raw in-memory global tier (machine-wide keys). */
+    globalDefaults(): Preferences;
+    /**
+     * Persist the staged in-memory **project** tier to its file.
+     *
+     * Writes the project tier only; the global file is never rewritten here, so a
+     * per-checkout `set` cannot mutate machine-wide preferences. Creates the
+     * containing directory if it is missing.
+     */
+    save(): void;
+}

package/dist/types/settings/settings.test.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Settings subsystem — unit tests.
+ *
+ * Everything runs against a temp directory pinned through
+ * {@link PreferenceStore.atPaths}; the real home is never read or written. The
+ * tests pin the public store behaviour:
+ *
+ *   1. Defaults load: a store over two non-existent files resolves every key to
+ *      its {@link DEFAULT_PREFERENCES} value.
+ *   2. Precedence: a key present in both tiers reads from the project tier, and
+ *      a key present only globally still resolves; a corrupt project file falls
+ *      back to defaults without throwing.
+ *   3. Round-trip: a `set` + `save` writes the project file, and a fresh store
+ *      over the same paths reads the persisted value back.
+ */
+export {};

package/dist/types/transcript-export/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Transcript-export subsystem — public barrel.
+ *
+ * The HTML transcript publisher and its supporting machinery: the table-driven
+ * SGR painter ({@link paintSgr}) that turns terminal-styled output into safe HTML
+ * spans, the {@link ThemeBridge} that computes export colors from an
+ * {@link ExportTheme} via a WCAG luminance LUT, the regenerated page-shell
+ * {@link PAGE_SHELL} template with its `{{TOKEN}}` slots and {@link fill} helper,
+ * and {@link publishTranscript} which renders a session transcript to a
+ * standalone HTML document using `marked`, `highlight.js`, and the painter.
+ *
+ * Consumers import the publish surface from `src/transcript-export` rather than
+ * reaching into individual modules.
+ */
+export { paintSgr, tokenizeSgr, foldSgr, SGR_CODE_TABLE } from "./sgr";
+export { DefaultThemeBridge, createThemeBridge, buildLuminanceLut, parseColor, formatColor, } from "./theme-bridge";
+export { PAGE_SHELL, PAGE_STYLES, CLIENT_SCRIPT, fill, type SlotValues, } from "./template";
+export { publishTranscript, type PublishEntry, type PublishMessage, type PublishRole, type MessagePart, } from "./publish";
+export { FALLBACK_EXPORT_THEME, SHELL_SLOTS, SGR_INITIAL_STATE, briefingFault, } from "../briefing/contract";
+export type { ExportTheme, ThemeBridge, ThemeMode, LuminanceLut, Rgb, SgrState, SgrToken, SgrMutation, PublishOptions, WidgetRender, TranscriptPart, ShellSlot, } from "../briefing/contract";

package/dist/types/transcript-export/publish.d.ts

@@ -0,0 +1,81 @@
+/**
+ * publishTranscript — render a session transcript to a standalone, self-contained
+ * HTML document.
+ *
+ * The publisher takes a list of transcript entries (each carrying a framework
+ * message) and produces one HTML string with no external dependencies: prose is
+ * rendered to HTML with `marked`, fenced code is syntax-highlighted with
+ * `highlight.js`, terminal-styled tool output is painted to spans by
+ * {@link paintSgr}, and all colors come from a {@link ThemeBridge} over an
+ * {@link ExportTheme}. Markdown and highlighting are run *here*, at publish time,
+ * so the rendered HTML is baked into the page payload and the page needs no
+ * client-side parser to display — the page ships ready to read.
+ *
+ * The two third-party libraries this layer leans on are MIT (`marked`) and
+ * BSD-3-Clause (`highlight.js`); their license notices are preserved verbatim in
+ * the emitted document (the `MARKED_LIB` / `HIGHLIGHT_LIB` shell slots) as the
+ * licenses require, while the libraries themselves are used, never reimplemented.
+ */
+import { type ImageContent, type PublishOptions, type TextContent } from "../briefing/contract";
+/**
+ * The conversational role a published turn carries. Mirrors the conductor's node
+ * roles but is declared locally so the publisher depends only on the briefing
+ * contract, not on the conductor subsystem.
+ */
+export type PublishRole = "user" | "assistant" | "tool" | "system" | "condense" | "note";
+/**
+ * One transcript node the publisher consumes. Structurally a subset of the
+ * conductor's persisted entry: a `role` for attribution and a `message` carrying
+ * the framework content this node renders. The `message` is read with narrow
+ * structural access so the publisher never imports the framework message union.
+ */
+export interface PublishEntry {
+    /** Attribution role for this node. */
+    readonly role: PublishRole;
+    /** The framework message payload to render. */
+    readonly message: PublishMessage;
+}
+/**
+ * The narrow view of a framework message the publisher reads. Covers the three
+ * concrete message roles' content shapes plus the tool-call linkage a tool result
+ * carries, without redeclaring the whole framework union.
+ */
+export interface PublishMessage {
+    /** The framework message role. */
+    readonly role: string;
+    /** The message content — a bare string or a list of content parts. */
+    readonly content: string | readonly MessagePart[];
+    /** Present on tool-result messages; links the node to its originating call. */
+    readonly toolCallId?: string;
+    /** Present on tool-result messages; the invoked tool's display name. */
+    readonly toolName?: string;
+}
+/**
+ * The content-part union the publisher renders. Text and image parts alias the
+ * framework's; thinking and tool-call parts are read structurally so the
+ * assistant turn can surface a call's name and arguments.
+ */
+export type MessagePart = TextContent | ImageContent | {
+    readonly type: "thinking";
+    readonly thinking: string;
+} | {
+    readonly type: "toolCall";
+    readonly id: string;
+    readonly name: string;
+    readonly arguments: Readonly<Record<string, unknown>>;
+};
+/**
+ * Render a session transcript to a standalone HTML document.
+ *
+ * Configures the markdown + highlight pipeline, renders every entry to a turn,
+ * serializes the turns into a base64 payload, resolves the theme through a
+ * {@link ThemeBridge}, and fills the page shell. The returned string is a complete
+ * `<!doctype html>` document with all styling, content, and the preserved library
+ * notices inlined — it can be written to disk and opened directly.
+ *
+ * @param entries the transcript nodes to publish, in display order
+ * @param opts    optional theme, title, output directory, and widget overrides
+ * @returns the rendered standalone HTML document
+ * @throws a {@link briefingFault} of kind `"publish"` if assembly fails
+ */
+export declare function publishTranscript(entries: readonly PublishEntry[], opts?: PublishOptions): string;

package/dist/types/transcript-export/sgr.d.ts

@@ -0,0 +1,90 @@
+/**
+ * SGR painter — a table-driven ANSI Select-Graphic-Rendition state machine that
+ * converts a terminal byte stream into a sequence of styled HTML spans.
+ *
+ * Terminal programs encode color and emphasis with CSI sequences of the form
+ * `ESC [ p1 ; p2 ; … m` (the trailing `m` is the SGR final byte). The parameters
+ * are small integers whose meaning is fixed by ECMA-48 / ISO 6429: `0` resets,
+ * `1`/`3`/`4` switch on weight/italic/underline, `30`–`37` and `90`–`97` set the
+ * foreground from the sixteen-color palette, `40`–`47` and `100`–`107` set the
+ * background, and the two extended introducers `38`/`48` pull a 256-index or a
+ * 24-bit triple out of the following parameters.
+ *
+ * Rather than a long `switch`, the semantics live in a *table*: each handled code
+ * maps to an {@link SgrMutation} — the partial {@link SgrState} that code imposes —
+ * and the painter folds the matched mutation over the running state. Extending the
+ * machine is adding a row, never editing control flow. The two extended
+ * introducers are the only parametric cases and are handled by a small reader
+ * that consumes their trailing parameters.
+ *
+ * The pipeline is three stages:
+ *   1. {@link tokenizeSgr} splits the raw stream into an alternation of text runs
+ *      and SGR parameter lists ({@link SgrToken}s).
+ *   2. {@link foldSgr} folds an SGR parameter list into the running
+ *      {@link SgrState} using the {@link SGR_CODE_TABLE} dispatch table.
+ *   3. {@link paintSgr} drives the two over the whole stream, wrapping each text
+ *      run in a `<span>` whose class list and inline color style reflect the state
+ *      in force.
+ *
+ * The {@link SgrState} / {@link SgrToken} / {@link SgrMutation} vocabulary is the
+ * briefing contract's; the SGR code meanings are the published standard's.
+ */
+import { type SgrMutation, type SgrState, type SgrToken } from "../briefing/contract";
+/**
+ * The read-only public view of the SGR dispatch table — each fixed-meaning SGR
+ * code mapped to the {@link SgrMutation} it imposes. Exported so callers can
+ * introspect the handled code space (the extended `38`/`48` introducers are not
+ * present here; they are parametric and resolved by the painter).
+ */
+export declare const SGR_CODE_TABLE: ReadonlyMap<number, SgrMutation>;
+/**
+ * Fold one SGR parameter list into a running {@link SgrState}, returning the next
+ * state.
+ *
+ * Walks the parameters left to right. A fixed-meaning code is resolved through
+ * the {@link CODE_TABLE} and its mutation merged over the state. The two extended
+ * introducers `38` (foreground) and `48` (background) are handled inline: the
+ * reader consumes their trailing `5;n` or `2;r;g;b` parameters and the resolved
+ * color is written to the matching channel. An empty list is the bare `ESC[m`
+ * form and is treated as a reset, matching terminal behavior.
+ *
+ * Pure: the input state is never mutated; a fresh object is returned.
+ *
+ * @param state  the style in force before this sequence
+ * @param params the numeric parameter list of one SGR sequence
+ */
+export declare function foldSgr(state: SgrState, params: readonly number[]): SgrState;
+/**
+ * Split a raw terminal stream into an ordered list of {@link SgrToken}s.
+ *
+ * Scans for CSI sequences of the form `ESC [ … m`. Each such sequence becomes an
+ * `sgr` token carrying its parsed numeric parameters (an empty selector yields an
+ * empty list, the bare-reset form). The runs of ordinary characters between
+ * sequences become `text` tokens. Non-SGR control sequences — any CSI whose final
+ * byte is not `m`, plus bare escapes — are dropped: they carry cursor and screen
+ * commands that have no place in flowed HTML, so swallowing them keeps the output
+ * clean while preserving every printable character.
+ *
+ * Empty `text` runs are never emitted, so the token stream is dense.
+ *
+ * @param input the raw ANSI/terminal byte stream
+ */
+export declare function tokenizeSgr(input: string): SgrToken[];
+/**
+ * Paint an ANSI/terminal byte stream into a string of styled HTML spans.
+ *
+ * Drives the three stages end to end: tokenize the stream, fold each SGR sequence
+ * into the running {@link SgrState}, and wrap each intervening text run in a span
+ * reflecting the state in force when that run was emitted. Text is HTML-escaped;
+ * non-SGR control sequences are dropped; runs under the neutral state are emitted
+ * without a wrapping span. The result is safe to splice directly into a transcript
+ * page.
+ *
+ * The state resets to {@link SGR_INITIAL_STATE} only on an explicit reset code (or
+ * a bare `ESC[m`); it otherwise persists across text runs, so a color set once
+ * stays in force until changed, exactly as a terminal renders it.
+ *
+ * @param input the raw ANSI/terminal byte stream to convert
+ * @returns an HTML fragment of escaped text and styled `<span>`s
+ */
+export declare function paintSgr(input: string): string;

package/dist/types/transcript-export/template.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Page-shell template — the standalone HTML/CSS scaffold the transcript publisher
+ * fills.
+ *
+ * This module is a freshly authored single-file page: its own element names
+ * (`<main class="xscript">`, `.turn`, `.turn-tag`, `.turn-body`, `.tool-frame`,
+ * `.aside-note`), its own stylesheet, and its own `{{TOKEN}}` placeholder names —
+ * the {@link SHELL_SLOTS} values from the briefing contract
+ * (`THEME_VARS`/`PAGE_SURFACE`/…/`MARKED_LIB`/`HIGHLIGHT_LIB`). None of the class
+ * names, DOM structure, placeholder tokens, or color values are carried over from
+ * any prior export template.
+ *
+ * The publisher computes a value for every slot and calls {@link fill} to splice
+ * them in. The page is self-contained: theme colors arrive as CSS custom
+ * properties in `:root`, the markdown and syntax-highlight libraries are inlined,
+ * the session payload is embedded as base64, and a small client renderer
+ * (the `SCRIPT` slot) hydrates the transcript on load.
+ */
+import { type ShellSlot } from "../briefing/contract";
+/**
+ * The page stylesheet, emitted into the `STYLES` slot. Reads its colors from the
+ * `--x-*` custom properties the `THEME_VARS` slot defines, so re-theming is a
+ * matter of changing the variables, not the rules. Class names are this page's
+ * own (`xscript`, `turn`, `tool-frame`, `aside-note`, the `sgr-*` family the
+ * painter emits, and the highlight `xhl` block).
+ */
+export declare const PAGE_STYLES: string;
+/**
+ * The client-side renderer, emitted into the `SCRIPT` slot. Decodes the base64
+ * session payload, walks its turns, and renders each into the `.xscript` root
+ * using the inlined `marked` (markdown) and `highlight.js` (code) libraries. Code
+ * fences are highlighted into the page's own `xhl-*` classes; prose is parsed by
+ * marked. Pre-rendered tool widgets and SGR-painted text arrive already-HTML in
+ * the payload and are inserted verbatim.
+ */
+export declare const CLIENT_SCRIPT: string;
+/**
+ * The HTML page shell carrying every {@link SHELL_SLOTS} placeholder as a
+ * `{{TOKEN}}` marker. {@link fill} replaces each marker with its computed value.
+ * The structure: a themed `:root`, the inlined stylesheet, the two vendored
+ * libraries, the base64 payload bound to `window.__XSCRIPT_PAYLOAD__`, and the
+ * client renderer that hydrates `#xscript-root`.
+ */
+export declare const PAGE_SHELL = "<!doctype html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\" />\n<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />\n<title>Session Transcript</title>\n<style>\n:root {\n{{THEME_VARS}}\n  --x-page-surface: {{PAGE_SURFACE}};\n  --x-card-surface: {{CARD_SURFACE}};\n  --x-note-surface: {{NOTE_SURFACE}};\n}\n{{STYLES}}\n</style>\n</head>\n<body>\n<main class=\"xscript\">\n  <header class=\"xscript-head\">\n    <h1>Session Transcript</h1>\n    <div class=\"xscript-meta\">Self-contained HTML export</div>\n  </header>\n  <div id=\"xscript-root\"></div>\n</main>\n<script>\n/* {{MARKED_LIB}} */\n</script>\n<script>\n/* {{HIGHLIGHT_LIB}} */\n</script>\n<script>\nwindow.__XSCRIPT_PAYLOAD__ = \"{{PAYLOAD}}\";\n</script>\n<script>\n{{SCRIPT}}\n</script>\n</body>\n</html>";
+/**
+ * The map a {@link fill} call supplies — one value per {@link ShellSlot} token. A
+ * value may be omitted, in which case its placeholder is replaced with the empty
+ * string (so a partial fill leaves no stray `{{TOKEN}}` in the output).
+ */
+export type SlotValues = Partial<Record<ShellSlot, string>>;
+/**
+ * Replace every `{{TOKEN}}` placeholder in a template with the value supplied for
+ * that slot, returning the filled string.
+ *
+ * Walks the known {@link SHELL_SLOTS} (not an open scan), so only sanctioned
+ * placeholders are substituted and a stray `{{…}}` in user content is left
+ * untouched. Each token is replaced globally; a slot with no supplied value
+ * collapses to the empty string. The replacement is value-literal — a `$` in a
+ * value does not trigger regex backreference expansion.
+ *
+ * @param template the shell carrying `{{TOKEN}}` markers
+ * @param values   the per-slot values to splice in
+ */
+export declare function fill(template: string, values: SlotValues): string;