@patterkit/ops 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,833 @@
+import { ProjectFile, Scene, LocaleFile, AuthoringFile, Bundle, GameData, CoverageDriver, DocumentationClass, DocLine } from '@patterkit/model';
+import { ValidationIssue } from '@patterkit/core';
+import { ConditionIssue } from '@patterkit/compiler';
+import { ChoiceOption } from '@patterkit/runtime';
+
+interface LoadedProject {
+    root: string;
+    projectFile: string;
+    project: ProjectFile;
+    scenes: Scene[];
+    locales: LocaleFile[];
+    /** Source file for each scene (scene id -> absolute path) - "where it lives". */
+    sceneFiles: Record<string, string>;
+    /** Source file of each entry in `locales`, index-aligned. */
+    localeFiles: string[];
+    /** Authoring metadata shards (comments / statuses / estimates - spec section 5 schema). */
+    authoring: AuthoringFile[];
+    /** Source file of each entry in `authoring`, index-aligned. */
+    authoringFiles: string[];
+}
+/**
+ * Find the nearest `*.patterproj` at or above `startPath` - one readdir per
+ * level (never a recursive scan of ancestors). Throws if none is found, or if
+ * a directory holds more than one (ambiguous - the alphabetically-first would
+ * silently win).
+ */
+declare function findProjectFile(startPath: string): string;
+/**
+ * The scene id a shard path belongs to, for a file-association launch (Finder / argv onto a scene's flow
+ * / loc / authoring file): a flow file declares its scene, a loc file names its scene, an authoring shard
+ * mirrors the flow stem. Returns undefined for the project root / manifest / any non-scene path (so the
+ * caller lands on the remembered scene instead). Cheap - parses at most the one shard (and, for an
+ * authoring shard, its sibling flow file).
+ */
+declare function sceneIdForShard(shardPath: string): string | undefined;
+/**
+ * Phase-1 "landing" load (Patterpad's lazy open): parse the manifest and ONLY the landing scene's shards
+ * (its flow file + its source-language loc), leaving the rest of the project unparsed. The result is a
+ * partial `LoadedProject` whose `scenes` / `locales` hold just the landing scene, so the editor can paint
+ * it immediately; `loadProject` (the full eager parse) hydrates the rest in phase 2.
+ *
+ * The landing scene is the one named by `launchPath` (a file-association open onto a scene shard), else
+ * `preferId` (the remembered scene), else the first scene file. `authoring` is left empty - it is read
+ * lazily per scene from disk (project.ts), never from this array.
+ */
+declare function loadProjectLanding(startPath: string, opts?: {
+    launchPath?: string;
+    preferId?: string;
+}): LoadedProject;
+/** Sort scenes into the project's authored nav order (`ProjectFile.sceneOrder`), in place.
+ *  Listed scenes come first in list order; unlisted scenes follow in their existing (file) order;
+ *  listed ids that no longer exist are simply ignored. Presentation only - play order is untouched. */
+declare function applySceneOrder(scenes: Scene[], order: string[] | undefined): void;
+declare function loadProject(startPath: string): LoadedProject;
+
+/** One file write an op wants performed. `content` is full canonical file text. */
+interface PlannedWrite {
+    path: string;
+    content: string;
+}
+/**
+ * Commit planned writes to disk (UTF-8), creating parent directories. The PLAIN
+ * filesystem applier - for tests and no-VCS embedders only; product code (the
+ * CLI, Patterpad) routes through @patterkit/vcs so writes land correctly in a
+ * Perforce / locked workspace (spec §12).
+ */
+declare function applyWrites(writes: PlannedWrite[]): void;
+
+/** A raw-bytes hygiene problem in one source file (repairable by `format`). */
+interface HygieneIssue {
+    file: string;
+    message: string;
+}
+interface ValidateResult {
+    structural: ValidationIssue[];
+    conditions: ConditionIssue[];
+    /** Inline `{@ref}` interpolation issues (voiced-line slots, unknown/malformed refs). */
+    interpolation: ConditionIssue[];
+    /** Encoding/EOL hygiene (BOM, CRLF) - spec §10. */
+    hygiene: HygieneIssue[];
+    /** Committed `.patterc` bundles whose hash no longer matches source (spec §11). */
+    staleBundles: HygieneIssue[];
+    /** Lingering `.patterconflict` sidecars - an unresolved merge (patter-merge.md §3.6). */
+    unresolvedMerges: HygieneIssue[];
+    ok: boolean;
+}
+/** Run structural + expression + interpolation + hygiene + bundle-staleness + merge validation. */
+declare function runValidate(loaded: LoadedProject): ValidateResult;
+
+/** Compile a loaded project to the runtime bundle, applying its build localisation mode (spec §11):
+ *  "embedded" (default) keeps every locale's strings inline; "ids" strips them so the runtime emits beat
+ *  IDs (the game localises). `sourceDebug` keeps only the SOURCE locale, embedded for debug playback and
+ *  flagged so the runtime warns it is not a shippable build. */
+declare function runExport(loaded: LoadedProject): Bundle;
+/** Compile WITHOUT the localisation-mode transform - the full bundle with every locale inline. Used where
+ *  the host needs all strings regardless of build mode (e.g. Patterpad's Play window + Export Localisation). */
+declare function runExportFull(loaded: LoadedProject): Bundle;
+/**
+ * The conventional output path for the compiled `.patterc` bundle (spec §11):
+ * the project's `export.bundle` (relative to the root, or absolute) if set,
+ * else `dist/<project-file-stem>.patterc`. This is where `patter export` writes
+ * with no `-o`, and a stable place the staleness gate (validate) can find.
+ */
+declare function bundleOutputPath(loaded: LoadedProject): string;
+
+/** Build a single self-contained playable HTML document for the loaded project. Pure: returns the file's
+ *  text; the caller writes it. One file to email anyone; it plays offline in any browser. */
+declare function runExportHtml(loaded: LoadedProject): string;
+/** The Publish-for-Web split (Inky-style): the same page as four files. `index.html` + `style.css`
+ *  are the writer's HARNESS - published once, then left alone so their customisations survive;
+ *  `story.js` + `patterplay.js` are refreshed on every publish. The story is a plain script-tag
+ *  ASSIGNMENT (no fetch), so the folder still plays straight from disk with no server. */
+interface WebExport {
+    /** The harness page: markup only, linking the other three files. Published once. */
+    indexHtml: string;
+    /** The look of the page, separated so it's approachable to edit. Published once. */
+    styleCss: string;
+    /** The Patterplay runtime + this page's player glue. Refreshed on every publish. */
+    patterplayJs: string;
+    /** The compiled story as `window.PATTER_BUNDLE = …`. Refreshed on every publish. */
+    storyJs: string;
+}
+declare function runExportWeb(loaded: LoadedProject): WebExport;
+
+declare function scanAudioStatus(loaded: LoadedProject): Map<string, string> | undefined;
+
+interface PlayOptions {
+    /** Scene id to start at (defaults to the bundle's first scene). */
+    scene?: string;
+    /** Block id within the scene to start at. */
+    block?: string;
+    /** Scripted choice-option ids, consumed in order at each choice point. */
+    choices?: string[];
+    /** Seed for the runtime PRNG (shuffle / random), for reproducible runs. */
+    seed?: number;
+    /** Safety bound on steps (default 1000) to stop runaway loops. */
+    maxSteps?: number;
+}
+/** One thing that happened during a playthrough, in order. */
+type PlayEvent = {
+    type: "line";
+    id: string;
+    text: string;
+    character?: string;
+    direction?: string;
+    gameData?: GameData;
+} | {
+    type: "text";
+    id: string;
+    text: string;
+    gameData?: GameData;
+} | {
+    type: "gameEvent";
+    id: string;
+    gameData?: GameData;
+} | {
+    type: "choice";
+    options: ChoiceOption[];
+    picked?: string;
+};
+/** "end" = the flow finished; "stalled" = a choice with no pickable option; "max-steps" = bound hit. */
+type PlayOutcome = "end" | "stalled" | "max-steps";
+interface PlayResult {
+    events: PlayEvent[];
+    outcome: PlayOutcome;
+}
+/**
+ * Compile a loaded project and play it headlessly through the reference
+ * runtime. At each choice point it consumes the next scripted choice id, else
+ * picks the first eligible option - so it always runs to an outcome. The whole
+ * pipeline in one call: load -> export -> Engine playthrough.
+ */
+declare function runPlay(loaded: LoadedProject, opts?: PlayOptions): PlayResult;
+/** Render a play result as the CLI's readable transcript lines. */
+declare function renderPlay(result: PlayResult): string[];
+
+interface CoverageOptions {
+    /** Number of random playthroughs (default 5000). */
+    runs?: number;
+    /** Per-run step cap, a divert-cycle guard (default 200). */
+    maxSteps?: number;
+    /** Seed for the harness PRNG; the whole run is reproducible from it (default 0). */
+    seed?: number;
+    /** Start-point override (else the project's authored start, else the first scene). */
+    scene?: string;
+    block?: string;
+    /** Input drivers to feed host scopes (`@world`) across the run; defaults to the project's
+     *  `coverageDrivers`. Pass `proposeCoverageDrivers(loaded)` to auto-drive from the conditions. */
+    drivers?: CoverageDriver[];
+}
+interface CoverageHooks {
+    /** Periodic progress (done runs, total). Called occasionally, not every run. */
+    onProgress?: (done: number, total: number) => void;
+    /** Cooperative cancel; checked between runs. The partial report is returned. */
+    signal?: {
+        readonly aborted: boolean;
+    };
+}
+/** One beat in the coverage population, with how often it was reached. */
+interface CoverageBeat {
+    id: string;
+    scene: string;
+    kind: "line" | "text" | "gameEvent";
+    character?: string;
+    /** A short text preview for the results table ("(game event)" for game-event beats). */
+    preview: string;
+    /** Total hits across all runs (weighting). */
+    hits: number;
+    /** Distinct runs that reached it - the numerator for reach %. */
+    reachedRuns: number;
+    /** reachedRuns / runs-executed * 100; 0 iff never reached. */
+    reachPct: number;
+    /** Set on a never-reached beat that is gated on a host-scope ref (`@world.x`) nothing writes and no
+     *  driver provides, i.e. it may just need an input, not be truly dead. Lists the offending refs. */
+    needsInput?: string[];
+}
+/** A choice that ran DRY during the coverage run: at some point it had no takeable option and no eligible
+ *  fallback, so it fell through silently and the flow carried on past it. This is easy to author by
+ *  accident (all options gated and every condition happened to fail, or a re-enterable hub whose once-only
+ *  options all got consumed) and the runtime hides it, so coverage surfaces it explicitly. */
+interface DryChoice {
+    /** The choice group's id. */
+    id: string;
+    /** The scene the choice lives in. */
+    scene: string;
+    /** Distinct runs in which this choice ran dry (out of runs executed). */
+    runs: number;
+}
+interface CoverageReport {
+    /** Runs actually executed (= requested, unless cancelled). */
+    runs: number;
+    maxSteps: number;
+    seed: number;
+    start: {
+        scene?: string;
+        block?: string;
+    };
+    beats: CoverageBeat[];
+    totals: {
+        beats: number;
+        covered: number;
+        neverHit: number;
+        coveragePct: number;
+    };
+    /** How each run ended, for the summary header. */
+    termination: {
+        ended: number;
+        capped: number;
+        stalled: number;
+        evalError: number;
+    };
+    /** The input drivers actually applied this run (empty when none). */
+    drivers: CoverageDriver[];
+    /** Host-scope refs (`@world.x`) that gate a never-reached beat but nothing writes and no driver feeds:
+     *  the "add an input?" candidates, deduped across the report. */
+    unwrittenInputs: string[];
+    /** Choices observed running dry (falling through with nothing takeable) during the run, most-frequent
+     *  first. Empty when none. A dry choice is a likely dead-end-by-accident the runtime hides. */
+    dryChoices: DryChoice[];
+    cancelled: boolean;
+}
+/**
+ * Auto-propose coverage drivers by scanning the project's conditions for host-scope refs (`@world.x`)
+ * and the literals they are compared against. Each proposed driver is `recurring`/`sometimes` and offers
+ * the straddling values (e.g. `>= 50` → 49, 50, 51; an enum/bool → its members). Refs the story already
+ * writes are skipped (they are covered for free). The author edits + saves the result as `coverageDrivers`.
+ */
+declare function proposeCoverageDrivers(loaded: LoadedProject): CoverageDriver[];
+/**
+ * Run narrative coverage over a loaded project. Pure (compiles once, then N
+ * independent playthroughs); optional progress + cancel via `hooks`.
+ */
+declare function runCoverage(loaded: LoadedProject, options?: CoverageOptions, hooks?: CoverageHooks): CoverageReport;
+/** Render a coverage report as the CLI's readable text: a summary, then a per-scene beat table with
+ *  never-reached (0%) rows marked. */
+declare function renderCoverageText(report: CoverageReport, sceneName?: (id: string) => string): string[];
+
+/** Resolve where a flow starts: an explicit override, else the project's authored `start`, else `{}`
+ *  (the runtime's first-scene default). Shared by `runPlay` and `runCoverage`. */
+declare function resolveStart(loaded: LoadedProject, override?: {
+    scene?: string;
+    block?: string;
+}): {
+    scene?: string;
+    block?: string;
+};
+
+interface FormatResult {
+    file: string;
+    changed: boolean;
+    /** The canonical content to commit - present only when `changed`. */
+    write?: PlannedWrite;
+}
+/** Compute the canonical form of each file. Returns planned writes; writes nothing. */
+declare function runFormat(files: string[]): FormatResult[];
+
+/** Counts for the WRITTEN population (line + text + label beats). */
+interface WrittenCounts {
+    count: number;
+    words: number;
+    byWriting: Record<string, number>;
+}
+/** Counts for the VOICED population (line beats only) - adds recording + readiness. */
+interface VoicedCounts extends WrittenCounts {
+    byRecording: Record<string, number>;
+    readyToRecord: number;
+    readyToShip: number;
+}
+interface SceneReport {
+    sceneId: string;
+    name: string;
+    file?: string;
+    /** The scene's writing status: its LOWEST-rung status-tracked beat. Absent when it has no such beats. */
+    status?: string;
+    /** True when this scene is guesswork-estimated (its actuals are replaced by `estimate`). */
+    estimated: boolean;
+    choices: number;
+    /** Actual VOICED counts. Empty (zeroed) for an estimated scene - its numbers come from the estimate. */
+    voiced: VoicedCounts;
+    /** Actual WRITTEN counts. Empty for an estimated scene. */
+    written: WrittenCounts;
+    /** The scene's estimate in written lines, when `estimated`. */
+    estimate?: number;
+    /** Written / voiced lines DONE and REMAINING. For an estimated scene: 0 done, the estimate remaining. */
+    writtenDone: number;
+    writtenRemaining: number;
+    voicedDone: number;
+    voicedRemaining: number;
+}
+interface CharacterReport {
+    character: string;
+    /** Actual (authored, non-estimated) spoken lines. */
+    lines: number;
+    words: number;
+    /** Lines projected onto this character by estimated scenes (their share of those scenes' estimates). */
+    estimatedLines: number;
+    recording: Record<string, number>;
+}
+interface LocaleReport {
+    locale: string;
+    translated: number;
+    missing: number;
+    /** Translated but the source changed since (source modifiedAt > localisedAt). */
+    stale: number;
+    words: number;
+}
+interface ReportTotals {
+    voiced: VoicedCounts;
+    written: WrittenCounts;
+    choices: number;
+    writtenDone: number;
+    writtenRemaining: number;
+    voicedDone: number;
+    voicedRemaining: number;
+    /** writtenDone + writtenRemaining (built scenes + estimated scenes' estimates). */
+    projectedWritten: number;
+    projectedVoiced: number;
+}
+interface ReportData {
+    project: {
+        id: string;
+        name: string;
+    };
+    voiced: boolean;
+    /** Whether audio/recording status is tracked (#206): a voiced project that hasn't opted out via
+     *  `trackAudioStatus`. Gates the recording-status breakdown in every renderer (text / xlsx / view). */
+    recordingTracked: boolean;
+    writingLadder: string[];
+    recordingLadder: string[];
+    scenes: SceneReport[];
+    characters: CharacterReport[];
+    locales: LocaleReport[];
+    /** Cut content (excluded from everything above), surfaced so removals are visible. */
+    cut: {
+        scenes: number;
+        voicedLines: number;
+        writtenLines: number;
+    };
+    /** Whether Estimating is turned on (renderers hide estimate figures when false). */
+    estimating: boolean;
+    /** How many scenes sit at each writing-ladder rung (by their lowest-beat status). */
+    scenesByStatus: Record<string, number>;
+    /** Estimate coverage: only meaningful when `estimating` is on. */
+    coverage: {
+        totalScenes: number;
+        estimated: number;
+    };
+    totals: ReportTotals;
+}
+/** Compute the production report. Pure: data out, no rendering, no I/O. */
+declare function runReport(loaded: LoadedProject, recordingOverride?: Map<string, string>): ReportData;
+/** Render the report as compact console lines (the CLI view). */
+declare function renderReportText(data: ReportData): string[];
+
+/** Render the report as an .xlsx workbook. */
+declare function runReportXlsx(data: ReportData): Promise<Buffer>;
+
+/** One localisable string. `id` is the beat id (or `cast:<NAME>` for a display name). */
+interface LocEntry {
+    id: string;
+    /** Owning scene id, or `@project` for project-level strings (display names). */
+    scene: string;
+    /** The default-locale source text. */
+    source: string;
+    /** The target-locale text ("" when missing / a template). */
+    translation: string;
+    /** Localiser-channel notes for this id (DocLine text, ancestors outermost-first). */
+    comments: string[];
+    /** Best-effort context for the translator. */
+    context?: {
+        character?: string;
+        kind?: string;
+    };
+    /** Translated, but the source changed since (source modifiedAt > localisedAt[locale]). */
+    stale: boolean;
+}
+interface LocCatalog {
+    /** Project id (ProjectFile.project.id). */
+    project: string;
+    defaultLocale: string;
+    /** The target locale this catalog carries, or undefined for a source-only TEMPLATE (POT). */
+    locale?: string;
+    entries: LocEntry[];
+}
+interface ApplyStats {
+    /** Distinct ids whose translation was written. */
+    updated: number;
+    /** Loc shard files touched. */
+    files: number;
+}
+/**
+ * Build the format-neutral localisation catalog. With no `locale` (or the default locale) it is a
+ * TEMPLATE: every `translation` is "". Otherwise translations come from that locale's shards.
+ */
+declare function extractLoc(loaded: LoadedProject, opts?: {
+    locale?: string;
+}): LocCatalog;
+/**
+ * Write a catalog's translations back. Produces the loc-shard writes (one per scene touched) and stamps
+ * `localisedAt[locale]` into the per-scene authoring shards (skipped when importing the default locale -
+ * staleness is tracked against the source, not for it). Caller commits the returned writes.
+ *
+ * Import conflict policy (decision 3a): a translation is accepted even when the source has since changed;
+ * the stale flag stays derivable from `localisedAt` vs source `modifiedAt` and surfaces on the next export.
+ */
+declare function applyLoc(loaded: LoadedProject, catalog: LocCatalog, opts?: {
+    now?: string;
+}): {
+    writes: PlannedWrite[];
+    stats: ApplyStats;
+};
+
+/** The catalog IS the JSON shape: a stable, lossless, human-diffable envelope. */
+declare function catalogToJson(catalog: LocCatalog): string;
+/** Parse a JSON catalog; light validation so a hand-mangled file fails loudly, not deep in apply. */
+declare function jsonToCatalog(text: string): LocCatalog;
+/** Render the catalog as a PO file (or a POT template when `catalog.locale` is undefined). */
+declare function catalogToPo(catalog: LocCatalog): string;
+/** Parse a PO / POT file back into a catalog. `locale` (from the Language header) may be overridden by
+ *  the caller's --locale. Entries without a msgctxt (the header) are skipped. */
+declare function poToCatalog(text: string): LocCatalog;
+
+/** Render the catalog as an .xlsx workbook: a sheet per scene, translator-facing columns. */
+declare function catalogToXlsx(catalog: LocCatalog): Promise<Buffer>;
+/** Parse an .xlsx workbook back into a catalog. Scene = sheet name; stale = Status "stale". `locale` is
+ *  not carried in the sheet, so the caller supplies it (--locale). */
+declare function xlsxToCatalog(buffer: Buffer): Promise<LocCatalog>;
+
+interface VoiceLine {
+    /** Readable container trail (`Scene › Block › Option`) - the scope changes signal a new run / branch. */
+    scope: string;
+    /** The line beat's id (recordings / filenames key to this). */
+    id: string;
+    /** The canonical speaker token. */
+    character: string;
+    /** The cast member's voice actor, if known. */
+    actor?: string;
+    /** The line's source-locale text. */
+    text: string;
+    /** `vo` notes: the line's own, plus the enclosing group/option's on the first line of a run. */
+    comments: string[];
+    /** The line's recording-ladder status (the "voice status"). */
+    recordingStatus: string;
+}
+interface VoiceScript {
+    project: string;
+    voiced: boolean;
+    recordingLadder: string[];
+    /** True when the filter was bypassed (every voiced line, not just ready-to-record). */
+    everything: boolean;
+    lines: VoiceLine[];
+}
+/** Compute the production VO script. Pure: data out, no I/O. `recordingOverride` replaces the
+ *  manual recording map with status derived from files on disk (#206 Audio Folders) - the same
+ *  contract as `runReport`, so the script agrees with the report and the inspector. */
+declare function runVoiceScript(loaded: LoadedProject, opts?: {
+    everything?: boolean;
+    recordingOverride?: Map<string, string>;
+}): VoiceScript;
+
+/** Render the VO script as an .xlsx workbook (a single "Voice Script" sheet). */
+declare function voiceScriptToXlsx(data: VoiceScript): Promise<Buffer>;
+
+/** A formatting run of body text. `code` marks an inline `{@property}` interpolation (rendered as accent
+ *  mono); `bold`/`italic` carry Patter's closed `<b>/<i>/<bi>` markup. Renderers turn these into Word runs
+ *  or PDF font/colour switches. */
+interface TextRun {
+    text: string;
+    bold: boolean;
+    italic: boolean;
+    code: boolean;
+}
+/** One renderable item in reading order. `indent` is the structural nesting depth (0 = block-level) - the
+ *  reader's structure cue. `snippet` is an id shared by every element of one snippet WHEN that snippet sits
+ *  inside a selector (branch / sequence / choice); the renderers draw a light left edge spanning each such
+ *  snippet, so rows that would otherwise blur (a sequence's steps) read as distinct beats. Absent = a
+ *  top-level snippet (delimited by space alone). Headings carry no indent (they reset it). */
+type ScriptElement = {
+    kind: "scene";
+    text: string;
+} | {
+    kind: "block";
+    text: string;
+}
+/** A spoken line: SPEAKER cue (coloured, uppercase), an optional (direction), and the body runs. */
+ | {
+    kind: "line";
+    indent: number;
+    snippet?: number;
+    character: string;
+    direction?: string;
+    runs: TextRun[];
+}
+/** Prose narration / on-screen text (speaker-less), upright in a soft ink, flush left. */
+ | {
+    kind: "narration";
+    indent: number;
+    snippet?: number;
+    runs: TextRun[];
+}
+/** A gating condition, set in accent mono above the beat it controls: `‹ if @brave ›`. */
+ | {
+    kind: "condition";
+    indent: number;
+    snippet?: number;
+    text: string;
+}
+/** A selector group's label ("Choose", "One of · first match wins", "In sequence"). */
+ | {
+    kind: "group";
+    indent: number;
+    label: string;
+}
+/** A branch's catch-all row header ("else · catch-all"). */
+ | {
+    kind: "else";
+    indent: number;
+}
+/** A choice option: a ◇-led prompt, plus a quiet small-caps flag tag (once only / repeatable). */
+ | {
+    kind: "option";
+    indent: number;
+    snippet?: number;
+    runs: TextRun[];
+    tag?: string;
+}
+/** A jump, set apart right-aligned in accent: `↪ The Crossroads` (readable target, never the id). */
+ | {
+    kind: "jump";
+    indent: number;
+    snippet?: number;
+    text: string;
+}
+/** A game event, set apart right-aligned in accent mono: `⚙ game event · door.open`. */
+ | {
+    kind: "gameEvent";
+    indent: number;
+    snippet?: number;
+    text: string;
+};
+interface ScriptDoc {
+    /** Project display name - the document title. */
+    project: string;
+    elements: ScriptElement[];
+}
+/** Compute the readable script document. Pure: data out, no I/O. */
+declare function runScriptDoc(loaded: LoadedProject): ScriptDoc;
+
+/** Render the readable screenplay as a Word document. */
+declare function scriptToDocx(doc: ScriptDoc): Promise<Buffer>;
+
+/** Render the readable screenplay as a PDF. Resolves once PDFKit has flushed the whole document. */
+declare function scriptToPdf(doc: ScriptDoc): Promise<Buffer>;
+
+type InitVcs = "git" | "perforce" | "plastic" | "svn";
+/** Whether the compiled `.patterc` bundle is committed or built in CI (spec §11). */
+type BundlePosture = "commit" | "ignore";
+interface InitOptions {
+    /** Directory to scaffold into (created by the caller's `applyWrites`). */
+    dir: string;
+    /** Project name; defaults to the directory's basename. */
+    name?: string;
+    /** Emit VCS config for this VCS (spec §12). */
+    vcs?: InitVcs;
+    /** Compiled-bundle posture (spec §11): "commit" (default - team ships it,
+     *  kept honest by the validate staleness gate) or "ignore" (built in CI). */
+    bundle?: BundlePosture;
+}
+interface InitResult {
+    writes: PlannedWrite[];
+    /** Path of the project file the scaffold creates. */
+    projectFile: string;
+    name: string;
+}
+/** Scaffold a new project as planned writes. Throws if `dir` already holds a project. */
+declare function runInit(opts: InitOptions): InitResult;
+/** The VCS-specific config writes for a project (spec §12): the `vcs-setup.md` guide, git's
+ *  `.gitattributes`, and the VCS's ignore file. Shared by `runInit` (scaffold) and the Project Settings
+ *  "switch VCS" path (which re-emits these for the newly-chosen VCS). No collision check - callers
+ *  overwrite when switching. */
+declare function vcsConfigWrites(dir: string, vcs: InitVcs | undefined, bundle?: BundlePosture): PlannedWrite[];
+
+/** The editor's caret context, so a search can float the current scene's hits (from the caret onwards) to
+ *  the top. Omit for a context-free search (the CLI). */
+interface SearchFocus {
+    /** The scene the editor is currently showing. */
+    sceneId: string;
+    /** The beat id the caret is in (its hits, and later ones in the scene, rank first). */
+    fromBeatId?: string;
+}
+interface ResolveEntry {
+    id: string;
+    kind: "scene" | "block" | "group" | "snippet" | "beat";
+    /** The author name (scenes / blocks only - other nodes are unnamed). */
+    name?: string;
+    /** The host-facing Game ID address (scenes / blocks only). */
+    gameId?: string;
+    /** The default-locale text content (line / text beats + choice prompts) - for the content search. */
+    text?: string;
+    /** The named location trail: scene name, then block name. */
+    location: string[];
+    /** The id of the scene this node lives in (for jump-to in the editor). */
+    sceneId: string;
+    /** The scene source file the node lives in. */
+    file?: string;
+}
+/**
+ * Look up a query against every node and beat in the project. Matching, in
+ * priority order: exact id -> exact Game ID -> exact name (case-insensitive) ->
+ * substring of id / Game ID / name (case-insensitive). The first tier with any
+ * hits wins, so an exact match never drowns in fuzzy ones. This is the path that
+ * answers "a locale string / audio file / log names id X - what line is that?".
+ */
+declare function runResolve(loaded: LoadedProject, query: string): ResolveEntry[];
+/**
+ * The editor's MAIN search (spec §6): content-oriented, the everyday "go to a thing" path. Matches a
+ * query against **Game IDs, scene / block titles, and dialogue / narration / choice text**, with the
+ * "Go to ID" power-search folded in: paste an opaque id and the node it names is found. Ranking: title /
+ * Game-ID, then dialogue / text content, then raw id.
+ */
+declare function runSearch(loaded: LoadedProject, query: string, focus?: SearchFocus): ResolveEntry[];
+/**
+ * Status browse (Patterpad #205): every LINE / TEXT beat whose writing status is `status`, in document
+ * order (the caret's scene first when `focus` is given). A beat with no explicit status reads as the LOWEST
+ * rung, so browsing the lowest status surfaces every un-started line. Actions and choice prompts are never
+ * status-tracked, so they're excluded (mirrors the surface + the production report).
+ */
+declare function runStatusBrowse(loaded: LoadedProject, status: string, dimension?: "writing" | "recording", focus?: SearchFocus, recordingOverride?: Map<string, string>): ResolveEntry[];
+/**
+ * List every distinct author tag (#215) used anywhere in the project, with how many nodes carry it, sorted
+ * alphabetically. Drives the search window's Tag tab chips (the tag counterpart to the status ladder).
+ * Counts a node's OWN tags only (not the accumulated runtime union), so the number is "places I applied it".
+ */
+declare function listProjectTags(loaded: LoadedProject): Array<{
+    name: string;
+    count: number;
+}>;
+/**
+ * Tag browse (#215 follow-up): every node whose OWN tags include `tag`, at any level (scene, block, group,
+ * snippet, prompt, or beat), in document order (the caret's scene first when `focus` is given). Matches the
+ * authored tag, not the accumulated runtime union, so it points at where the tag was actually applied.
+ * A row previews what the node is: a beat / prompt shows its text, a snippet its first beat, a scene / block
+ * its name.
+ */
+declare function runTagBrowse(loaded: LoadedProject, tag: string, focus?: SearchFocus): ResolveEntry[];
+/**
+ * Property-usage search (#205 follow-up): every node that REFERENCES a property in a **condition**, an
+ * **effect** (a `set` target or value), or **interpolated text**: the coverage-driven "this dead branch's
+ * condition uses `@x`; where else is `@x` used?" path. `query` is a property ref (`@gold`, `gold`,
+ * `@world.threat`), optionally followed by a value to narrow to usages that also mention it (`gold 10`,
+ * `faction rebels`). Returns a row per usage, with `text` describing it (the condition, the `set`, or the
+ * interpolated string). Bare names also match their explicit `@patter.` form.
+ */
+declare function runPropertyUsage(loaded: LoadedProject, query: string, focus?: SearchFocus): ResolveEntry[];
+
+interface ReplaceOptions {
+    /** The literal text to find (not a regex: special characters match themselves). */
+    query: string;
+    /** The literal replacement text. */
+    replacement: string;
+    /** Match case (default off). */
+    caseSensitive?: boolean;
+    /** Match whole words only (word boundaries around the query; default off). */
+    wholeWord?: boolean;
+    /** Restrict the replacement to a single beat id (the per-row "Replace this one"). */
+    onlyId?: string;
+}
+/** One replaced string, for the preview / confirm list. */
+interface ReplaceHit {
+    id: string;
+    sceneId: string;
+    /** Scene › block breadcrumb. */
+    location: string[];
+    before: string;
+    after: string;
+}
+interface ReplacePlan {
+    hits: ReplaceHit[];
+    /** Shard writes the caller commits through the VC layer (one per touched scene). */
+    writes: PlannedWrite[];
+    /** The rewritten shard objects (index-aligned with `writes`), so the caller can swap them into its
+     *  in-memory `LoadedProject.locales` after committing: keeping reads + the open scene current. */
+    shards: LocaleFile[];
+    /** Distinct scenes touched. */
+    scenes: number;
+}
+/**
+ * Plan a project-wide replacement. Walks the default-locale string shards (the source prose), substitutes
+ * matches, and returns the hits + the shard writes. With `onlyId`, only that one beat's string is touched.
+ */
+declare function runReplace(loaded: LoadedProject, opts: ReplaceOptions): ReplacePlan;
+
+/** The source-shard extensions a document carries (the merge-friendly truth). */
+declare const SHARD_EXTENSIONS: readonly [".patterflow", ".patterloc", ".patterx", ".patterproj"];
+/** Manifest embedded at the document root - what this envelope is and contains. */
+interface DocumentManifest {
+    schema: "patter/document@0";
+    project: {
+        id: string;
+        name: string;
+    };
+    /** Shard paths (relative, forward-slashed), sorted - the document's contents. */
+    files: string[];
+}
+/** Pack a project's source shards into a `.patterpack` document (zip bytes). */
+declare function runPack(startPath: string): Promise<Buffer>;
+
+type MergeFileType = "flow" | "loc" | "authoring" | "project";
+type ConflictKind = "both-changed" | "delete-vs-edit" | "no-timestamp" | "moved" | "added-both" | "structural";
+/** One unresolved 3-way conflict; provisional output is OURS. */
+interface Conflict {
+    /** The unit id (beat/node/comment/scene id or planned name); "" for a file-level field. */
+    id: string;
+    /** Dotted path within the file, e.g. `strings.L_1` or `writing.L_1`. */
+    path: string;
+    base: unknown;
+    ours: unknown;
+    theirs: unknown;
+    kind: ConflictKind;
+}
+/** A non-blocking note - the merge proceeded, but a human may want to check. */
+interface Warning {
+    id: string;
+    path: string;
+    message: string;
+}
+interface MergeResult {
+    type: MergeFileType;
+    /** The merged model - valid canonical source; conflicts resolved to OURS. */
+    merged: Record<string, unknown>;
+    conflicts: Conflict[];
+    /** Advisory notes (e.g. both sides inserted at the same anchor, kept ours-then-theirs). */
+    warnings: Warning[];
+}
+/** Thrown when asked to merge a type M1 does not handle yet (flow / project). */
+declare class UnsupportedMergeError extends Error {
+}
+type Obj = Record<string, unknown>;
+/** Detect the merge type from a file's `schema` tag. */
+declare function detectMergeType(file: {
+    schema?: unknown;
+}): MergeFileType;
+/** 3-way merge BASE / OURS / THEIRS (parsed models). Dispatches by file type. */
+declare function runMerge(base: Obj, ours: Obj, theirs: Obj, opts?: {
+    type?: MergeFileType;
+}): MergeResult;
+
+/** A document entry whose path escapes the target dir (rejected). */
+declare class UnsafeEntryError extends Error {
+}
+/** Unpack a `.patterpack` document (zip bytes) into planned writes under `targetDir`. */
+declare function runUnpack(bytes: Buffer | Uint8Array, targetDir: string): Promise<PlannedWrite[]>;
+/** One shard's outcome in a merge-unpack. */
+interface MergedShard {
+    /** Relative path within the project. */
+    path: string;
+    /** Merge result, or undefined when the shard was ADDED (new file from the author). */
+    result?: MergeResult;
+    added: boolean;
+}
+interface UnpackMergeResult {
+    shards: MergedShard[];
+    /** Merged (and added) shard contents to write into the project. */
+    writes: PlannedWrite[];
+    /** `.patterconflict` sidecars for shards with conflicts. */
+    sidecars: PlannedWrite[];
+    conflicts: number;
+    warnings: number;
+}
+/**
+ * Merge a RETURNED `.patterpack` document (`theirs`) back into the project at
+ * `projectDir` (`ours`), using the document originally sent (`base`) as the
+ * common ancestor. Per shard: 3-way merge (added files written verbatim). Pure -
+ * returns planned writes + sidecars; the caller commits. A shard the author
+ * DELETED is left in the working tree (whole-file deletes are not propagated in
+ * v1 - safe, no data loss).
+ */
+declare function runUnpackMerge(returnedBytes: Buffer | Uint8Array, baseBytes: Buffer | Uint8Array, projectDir: string): Promise<UnpackMergeResult>;
+/** True if a document entry is an absolute path or would escape the target dir.
+ *  (JSZip's own API normalises `..` away, but a zip from any other tool may not.) */
+declare function isUnsafeEntry(name: string): boolean;
+
+/** The class names whose notes deliver to `channel` (a class with `deliver: "*"` matches every channel). */
+declare function classesForChannel(classes: DocumentationClass[], channel: string): Set<string>;
+/**
+ * Resolve documentation for an export `channel`: a map from node/beat id to the
+ * ordered notes delivered there - ancestors outermost-first, then the node's own.
+ * Only ids with at least one delivered note appear. Untyped notes are skipped
+ * (editor-only).
+ */
+declare function resolveDocumentation(loaded: LoadedProject, channel: string): Map<string, DocLine[]>;
+
+export { type ApplyStats, type BundlePosture, type CharacterReport, type Conflict, type ConflictKind, type CoverageBeat, type CoverageHooks, type CoverageOptions, type CoverageReport, type DocumentManifest, type FormatResult, type HygieneIssue, type InitOptions, type InitResult, type InitVcs, type LoadedProject, type LocCatalog, type LocEntry, type LocaleReport, type MergeFileType, type MergeResult, type MergedShard, type PlannedWrite, type PlayEvent, type PlayOptions, type PlayOutcome, type PlayResult, type ReplaceHit, type ReplaceOptions, type ReplacePlan, type ReportData, type ReportTotals, type ResolveEntry, SHARD_EXTENSIONS, type SceneReport, type ScriptDoc, type ScriptElement, type SearchFocus, type UnpackMergeResult, UnsafeEntryError, UnsupportedMergeError, type ValidateResult, type VoiceLine, type VoiceScript, type VoicedCounts, type WebExport, type WrittenCounts, applyLoc, applySceneOrder, applyWrites, bundleOutputPath, catalogToJson, catalogToPo, catalogToXlsx, classesForChannel, detectMergeType, extractLoc, findProjectFile, isUnsafeEntry, jsonToCatalog, listProjectTags, loadProject, loadProjectLanding, poToCatalog, proposeCoverageDrivers, renderCoverageText, renderPlay, renderReportText, resolveDocumentation, resolveStart, runCoverage, runExport, runExportFull, runExportHtml, runExportWeb, runFormat, runInit, runMerge, runPack, runPlay, runPropertyUsage, runReplace, runReport, runReportXlsx, runResolve, runScriptDoc, runSearch, runStatusBrowse, runTagBrowse, runUnpack, runUnpackMerge, runValidate, runVoiceScript, scanAudioStatus, sceneIdForShard, scriptToDocx, scriptToPdf, vcsConfigWrites, voiceScriptToXlsx, xlsxToCatalog };