@patterkit/ops 0.11.0 → 0.12.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ProjectFile, Bundle, HostScopeRegistry, Scene, LocaleFile, AuthoringFile, GameData, CoverageDriver, GrammaticalGender, DocumentationClass, DocLine } from '@patterkit/model';
+import { ProjectFile, Bundle, HostScopeRegistry, Scene, LocaleFile, AuthoringFile, GameData, CoverageDriver, GrammaticalGender, DocumentationClass, DocLine, HandoffFile, Suggestion, LineBeat, Comment } from '@patterkit/model';
 import { NamedScopesFile, MergedScopes, ScopesIssue, ScopesCatalogueEntry, ScopesFile } from '@wildwinter/scoperegistry/scopes';
 export { GAME_SCOPES_DIR, GAME_SCOPES_FILE, serialiseScopesFile } from '@wildwinter/scoperegistry/scopes';
 import { ScopeDeclaration, ScopeRegistry } from '@wildwinter/scoperegistry';
@@ -734,33 +734,42 @@ interface TextRun {
  *  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). */
+ *  top-level snippet (delimited by space alone). Headings carry no indent (they reset it).
+ *
+ *  `id` is the scene, block, node, or beat the element shows, so an export that hands the script to someone
+ *  outside (the editable script) can tie each row back to the project. The readable script ignores it. */
 type ScriptElement = {
     kind: "scene";
+    id: string;
     text: string;
 } | {
     kind: "block";
+    id: string;
     text: string;
 }
 /** A spoken line: SPEAKER cue (coloured, uppercase), an optional (direction), and the body runs. */
  | {
     kind: "line";
+    id: string;
     indent: number;
     snippet?: number;
     character: string;
     direction?: string;
     runs: TextRun[];
 }
-/** Prose narration / on-screen text (speaker-less), upright in a soft ink, flush left. */
+/** Prose narration / on-screen text (speaker-less), upright in a soft ink, flush left. `id` is the beat. */
  | {
     kind: "narration";
+    id: string;
     indent: number;
     snippet?: number;
     runs: TextRun[];
 }
-/** A gating condition, set in accent mono above the beat it controls: `‹ if @brave ›`. */
+/** A gating condition, set in accent mono above the beat it controls: `‹ if @brave ›`. `id` is the node
+ *  it gates. */
  | {
     kind: "condition";
+    id: string;
     indent: number;
     snippet?: number;
     text: string;
@@ -768,43 +777,73 @@ type ScriptElement = {
 /** A selector group's label ("Choose", "One of · first match wins", "In sequence"). */
  | {
     kind: "group";
+    id: string;
     indent: number;
     label: string;
 }
-/** A branch's catch-all row header ("else · catch-all"). */
+/** A branch's catch-all row header ("else · catch-all"). `id` is the catch-all row's node. */
  | {
     kind: "else";
+    id: string;
     indent: number;
 }
-/** A choice option: a ◇-led prompt, plus a quiet small-caps flag tag (once only / repeatable). */
+/** A choice option: a ◇-led prompt, plus a quiet small-caps flag tag (once only / repeatable). `id` is the
+ *  prompt beat, `node` the option itself. */
  | {
     kind: "option";
+    id: string;
+    node: string;
     indent: number;
     snippet?: number;
     runs: TextRun[];
     tag?: string;
 }
-/** A jump, set apart right-aligned in accent: `↪ The Crossroads` (readable target, never the id). */
+/** A jump, set apart right-aligned in accent: `↪ The Crossroads` (readable target, never the id). `id` is
+ *  the snippet carrying it, `to` the target's id (or END). */
  | {
     kind: "jump";
+    id: string;
+    to: string;
     indent: number;
     snippet?: number;
     text: string;
 }
-/** A game event, set apart right-aligned in accent mono: `⚙ game event · door.open`. */
+/** A game event, set apart right-aligned in accent mono: `⚙ game event · door.open`. `id` is the beat. */
  | {
     kind: "gameEvent";
+    id: string;
+    indent: number;
+    snippet?: number;
+    text: string;
+}
+/** A documentation note on the element above, when the caller asked for notes (`ScriptDocOptions.notes`).
+ *  `id` is the node or beat the note is on. The readable script asks for none. */
+ | {
+    kind: "note";
+    id: string;
     indent: number;
     snippet?: number;
     text: string;
+    class?: string;
 };
+/** What `runScriptDoc` includes beyond the readable script's defaults. */
+interface ScriptDocOptions {
+    /** Only these scenes (by id), in project order. All scenes when absent. */
+    scenes?: string[];
+    /** Documentation notes to show under the node they're on: those delivered to a channel (`{ channel:
+     *  "editor" }`), or every classed note (`"all"`). Untyped notes are editor-only and never shown. Absent:
+     *  no notes, as the readable script has none. */
+    notes?: {
+        channel: string;
+    } | "all";
+}
 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;
+declare function runScriptDoc(loaded: LoadedProject, opts?: ScriptDocOptions): ScriptDoc;
 
 /** Render the readable screenplay as a Word document. */
 declare function scriptToDocx(doc: ScriptDoc): Promise<Buffer>;
@@ -984,6 +1023,9 @@ interface DocumentManifest {
     /** The game scopes files the pack carries as `game-scopes/<name>` entries, by name, sorted. Absent
      *  when the project has no game scopes folder (or it holds none). */
     gameScopes?: string[];
+    /** The open handoff records the pack carries as `handoffs/<id>.json` entries, by entry name, sorted.
+     *  Absent when there are none. */
+    handoffs?: string[];
 }
 /** Pack a project's source shards into a `.patterpack` document (zip bytes). */
 declare function runPack(startPath: string): Promise<Buffer>;
@@ -1056,7 +1098,7 @@ declare class UnsafeEntryError extends Error {
 /** What unpacking a document plans: its shards, and its game scopes snapshot (empty for a pack with none,
  *  which is every pack from before packs carried one). */
 interface UnpackResult {
-    /** The shards, under `targetDir`. */
+    /** The shards, under `targetDir`, with any open handoff records the pack carries (`handoffs/`). */
     shards: PlannedWrite[];
     /** The game's scopes files, in `<targetDir>/game-scopes/`, where the new project finds them first. */
     scopes: PlannedWrite[];
@@ -1115,6 +1157,9 @@ interface UnpackMergeResult {
         path: string;
         error?: string;
     };
+    /** Handoff records the pack brought (relative paths): added, or with reimports from their side added to
+     *  ours. Their writes are in `writes`. Absent when the pack carried none that changed anything. */
+    handoffs?: string[];
 }
 /**
  * Merge a RETURNED `.patterpack` document (`theirs`) back into the project at
@@ -1136,4 +1181,246 @@ declare function classesForChannel(classes: DocumentationClass[], channel: strin
  */
 declare function resolveDocumentation(loaded: LoadedProject, channel: string): Map<string, DocLine[]>;
 
-export { AUTHORING_HANDLED, type ApplyStats, type BundlePosture, CONFLICT_SIDECAR, type CharacterReport, type Conflict, type ConflictKind, type CoverageAsyncHooks, type CoverageBeat, type CoverageHooks, type CoverageOptions, type CoverageOrder, type CoverageReport, type DocumentManifest, type FormatResult, GAME_SCOPES_OWNER, type GameScopes, type GameScopesIssue, type HygieneIssue, type InitOptions, type InitResult, type InitVcs, type LoadedProject, type LocCatalog, type LocEntry, type LocaleReport, type MergeFileType, type MergeResult, type MergedShard, PATTER_SCOPES_FILE, PATTER_SCOPES_OWNER, type PinPlan, type PinnedName, type PlannedWrite, type PlayEvent, type PlayOptions, type PlayOutcome, type PlayResult, type ProvenanceCheck, RARE_REACH_PCT, type ReplaceHit, type ReplaceOptions, type ReplacePlan, type ReportData, type ReportTotals, type ResolveEntry, SHARD_EXTENSIONS, type SceneReport, type ScriptDoc, type ScriptElement, type SearchFocus, type UnpackMergeResult, type UnpackResult, UnsafeEntryError, UnsupportedMergeError, type ValidateResult, type VoiceLine, type VoiceScript, type VoicedCounts, type WebExport, type WrittenCounts, applyLoc, applySceneOrder, applyWrites, bundleOutputPath, catalogToJson, catalogToPo, catalogToXlsx, classesForChannel, defaultGameScopesDir, detectMergeType, discoverGameScopes, drivableScopes, extractLoc, findProjectFile, gameScopeTokens, gameScopesCatalogue, gameScopesSnapshot, hostScopeTokens, jsonToCatalog, leastReachedFirst, listProjectTags, loadProject, loadProjectLanding, patterScopesFile, patterScopesStale, patterScopesWrite, planPins, planReturnedWorld, planShareScopes, planWorldSave, poToCatalog, previewRegistry, proposeCoverageDrivers, reachabilityIssues, readGameScopes, renderCoverageText, renderPlay, renderReportText, resolveDocumentation, resolveStart, runCoverage, runCoverageAsync, 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, sidecarIssues, vcsConfigWrites, voiceScriptToXlsx, worldSettingsScopes, xlsxToCatalog };
+/** The project folder handoff records live in. */
+declare const HANDOFF_DIR = "handoffs";
+/** Where a handoff's record lives in the project at `root`. */
+declare function handoffPath(root: string, id: string): string;
+/** A record as it is written: stable key order is the caller's (the record is built in one place), two-space
+ *  JSON with a trailing newline, like the other JSON a project keeps. */
+declare function serialiseHandoff(handoff: HandoffFile): string;
+/** The planned write for a record. */
+declare function handoffWrite(root: string, handoff: HandoffFile): PlannedWrite;
+/** Parse a record, or say why it isn't one. */
+declare function parseHandoff(text: string): HandoffFile;
+/** A record that couldn't be read, naming its file. */
+interface HandoffIssue {
+    file: string;
+    message: string;
+}
+/** Every handoff record in the project at `root`, sorted by creation time, plus any that wouldn't parse.
+ *  No folder means no handoffs: every project before this feature. */
+declare function readHandoffs(root: string): {
+    handoffs: HandoffFile[];
+    issues: HandoffIssue[];
+};
+/** One handoff record by id, or undefined when the project has none by that id. Throws if it exists but
+ *  won't parse: a damaged record is a problem to report, not a missing one. */
+declare function readHandoff(root: string, id: string): HandoffFile | undefined;
+/** A source of randomness in [0, 1): `Math.random` by default, seeded in tests. */
+type Random = () => number;
+/** How many body characters codes for `count` lines need: enough that the codes in use fill at most one
+ *  in a thousand of the space, so a mistyped code almost never lands on another line's. At least 3. */
+declare function markerLength(count: number): number;
+/** Issue `count` distinct marker codes (body plus check character), in a random order. */
+declare function issueMarkerCodes(count: number, random?: Random): string[];
+/** A marker as it is printed beside a box. */
+declare function formatMarker(code: string): string;
+/** A handoff id ("H-7Q2K") that `taken` doesn't already use. */
+declare function newHandoffId(taken?: Iterable<string>, random?: Random): string;
+/** A marker read back from a returned document. */
+interface ReadMarker {
+    /** The normalised code (upper case, Crockford substitutions applied). */
+    code: string;
+    /** Whether its check character is right. A wrong one means the marker was damaged. */
+    valid: boolean;
+}
+/** Read a marker from a margin cell's text, leniently: `[#K7Q2M]`, `[ # k7q2m ]`, `[K7Q2M]` all read the
+ *  same, and the Crockford look-alikes (O for 0, I or L for 1) are taken as the digits they resemble.
+ *  Undefined when the text holds no marker at all. */
+declare function readMarker(text: string): ReadMarker | undefined;
+
+/** Which parts of a suggestion no longer match the project (empty: it still applies cleanly). */
+declare function staleParts(s: Suggestion, liveText: string, line: LineBeat | undefined): string[];
+/** An open suggestion, where it is, and whether it still applies. */
+interface OpenSuggestion {
+    suggestion: Suggestion;
+    sceneId?: string;
+    /** Parts that changed since it was made (empty: clean). */
+    stale: string[];
+}
+/** Every open (unresolved) suggestion in the project, optionally only those from one handoff, in scene
+ *  order then by time. One whose line is gone is listed as stale. */
+declare function listOpenSuggestions(loaded: LoadedProject, filter?: {
+    handoff?: string;
+}): OpenSuggestion[];
+/** Accept or reject one suggestion. */
+interface SuggestionDecision {
+    id: string;
+    accept: boolean;
+}
+/** What became of one decision. */
+interface DecisionResult {
+    id: string;
+    outcome: "accepted" | "rejected" | "stale" | "missing" | "resolved-already";
+    /** Why a stale or missing one wasn't applied, in words for the person who asked. */
+    reason?: string;
+}
+interface DecisionPlan {
+    /** Loc, flow, and authoring shard writes, one per touched file, for the caller to commit. */
+    writes: PlannedWrite[];
+    results: DecisionResult[];
+}
+/**
+ * Accept or reject suggestions, planning the writes. Decisions apply in order, so two suggestions on one
+ * line both accepted leaves the second stale (the first changed the text it was made against).
+ */
+declare function applySuggestionDecisions(loaded: LoadedProject, decisions: SuggestionDecision[], opts?: {
+    now?: string;
+    by?: string;
+}): DecisionPlan;
+/** Mark nodes or beats cut (or bring them back), planning the authoring writes, one per scene touched.
+ *  Ids that aren't in the project are skipped and returned. */
+declare function setCut(loaded: LoadedProject, ids: string[], cut: boolean): {
+    writes: PlannedWrite[];
+    unknown: string[];
+};
+
+interface EditableScriptOptions {
+    /** Scene ids to export, in project order. The whole project when absent. */
+    scenes?: string[];
+    /** Who it's going to, shown on the front page and kept in the record. */
+    recipient?: string;
+    /** Notes shown under the node they're on: the `editor` channel's (default) or every classed note. */
+    notes?: "editor" | "all";
+    /** Show each line's writing status in the margin. */
+    status?: boolean;
+    /** A cast page before the script. */
+    cast?: boolean;
+    /** Who is exporting (the record's `createdBy`). */
+    by: string;
+    /** The export time (ISO); now by default. */
+    now?: string;
+    /** Randomness for markers and the handoff id; seeded in tests. */
+    random?: Random;
+}
+interface EditableScript {
+    docx: Buffer;
+    handoff: HandoffFile;
+    /** The handoff record, for the caller to commit through VC with nothing else. */
+    writes: PlannedWrite[];
+}
+/** Export the editable script and plan its handoff record. */
+declare function exportEditableScript(loaded: LoadedProject, opts: EditableScriptOptions): Promise<EditableScript>;
+
+/** One tracked change, as found. */
+interface TrackedChange {
+    kind: "insert" | "delete" | "moveFrom" | "moveTo";
+    author: string;
+    date?: string;
+    text: string;
+}
+/** Text in both views, with what changed and which comments start inside it. */
+interface ReadText {
+    /** Every tracked change accepted, with Patter markup for bold / italic. */
+    proposed: string;
+    /** Every tracked change rejected, with the same markup. */
+    original: string;
+    changes: TrackedChange[];
+    /** Ids of comments whose range starts here (or that point here). */
+    comments: string[];
+    /** Formatting other than bold and italic that was dropped (colour, highlight, size, ...), counted. */
+    droppedFormatting: number;
+}
+/** One editable box, read back. */
+interface ReadBox {
+    kind: "box";
+    /** The marker read from the margin cell; `recovered` when it was only found inside a tracked deletion. */
+    marker?: ReadMarker & {
+        recovered?: boolean;
+    };
+    /** The words: the text cell, its paragraphs joined by a single space. */
+    text: ReadText;
+    /** How many paragraphs the text cell held (more than one: an Enter inside the box). */
+    paragraphs: number;
+    /** The lead cell (cue, direction, or ◇) and the margin cell (tag, status, marker), as plain text. */
+    lead: ReadText;
+    margin: ReadText;
+    /** The whole row was deleted with tracking on. */
+    rowDeleted: boolean;
+    /** The table's left indent in twips (Google writes it as "360.0"), when given. */
+    indent?: number;
+}
+/** An ordinary paragraph, or a table that isn't a box (its text flattened). */
+interface ReadParagraph {
+    kind: "paragraph" | "table";
+    text: ReadText;
+    /** The paragraph style (Heading1, ...), when one is set. */
+    style?: string;
+}
+type ReadItem = ReadBox | ReadParagraph;
+interface ReadComment {
+    id: string;
+    author: string;
+    date?: string;
+    text: string;
+    replies: Array<{
+        author: string;
+        date?: string;
+        text: string;
+    }>;
+}
+interface ReturnedDoc {
+    /** The handoff id from the page header (or, failing that, the front page). */
+    handoffId?: string;
+    /** Body content in document order. */
+    items: ReadItem[];
+    /** Top-level comments; replies hang off their parent. */
+    comments: ReadComment[];
+}
+/** Read a returned editable script. Throws only when the bytes aren't a .docx at all. */
+declare function readEditableDocx(bytes: Buffer | Uint8Array): Promise<ReturnedDoc>;
+
+interface ImportOptions {
+    /** Who is importing (the import log). */
+    by: string;
+    /** The name changes without a recorded author are credited to (the dialog's "Edits by"): the
+     *  handoff's recipient when absent. */
+    as?: string;
+    /** Count curly versus straight quotes and `...` versus `…` as edits (off: they're a tool's habit). */
+    strictQuotes?: boolean;
+    /** Accept the clean suggestions (not stale, no problems) on the way in, instead of leaving them open. */
+    direct?: boolean;
+    /** SHA-256 of the returned file, for the import log. */
+    fileHash: string;
+    now?: string;
+    random?: Random;
+}
+/** Something about the returned file the person importing should know. */
+interface ImportProblem {
+    severity: "warning" | "info";
+    kind: "damaged-marker" | "repaired-marker" | "duplicate-marker" | "missing-box" | "moved" | "placeholders" | "line-gone" | "unknown-speaker" | "added-text" | "context-edited" | "untracked-edits" | "joined-paragraphs" | "dropped-formatting" | "stale";
+    message: string;
+    /** The project line or node it concerns, for "Go to". */
+    anchor?: string;
+    marker?: string;
+}
+interface ImportReport {
+    handoffId?: string;
+    /** Set when nothing was imported, saying why. */
+    refused?: string;
+    counts: {
+        changed: number;
+        unchanged: number;
+        stale: number;
+        comments: number;
+        problems: number;
+    };
+    problems: ImportProblem[];
+}
+interface ImportPlan {
+    report: ImportReport;
+    /** The suggestions and comments this import adds (also inside `writes`). */
+    suggestions: Suggestion[];
+    comments: Comment[];
+    /** Authoring shards (and, with `direct`, the loc and flow shards the accepts touch) plus the handoff
+     *  record with this import logged. Empty when refused. */
+    writes: PlannedWrite[];
+    /** The handoff this file belongs to, when found. */
+    handoff?: HandoffFile;
+}
+/** The share of a handoff's lines that may come back missing or damaged before the file is refused. */
+declare const REFUSE_MISSING_SHARE = 0.25;
+/** Plan an import. Reads the handoff record named in the document from the project. */
+declare function planEditableImport(loaded: LoadedProject, returned: ReturnedDoc, opts: ImportOptions): ImportPlan;
+
+export { AUTHORING_HANDLED, type ApplyStats, type BundlePosture, CONFLICT_SIDECAR, type CharacterReport, type Conflict, type ConflictKind, type CoverageAsyncHooks, type CoverageBeat, type CoverageHooks, type CoverageOptions, type CoverageOrder, type CoverageReport, type DecisionPlan, type DecisionResult, type DocumentManifest, type EditableScript, type EditableScriptOptions, type FormatResult, GAME_SCOPES_OWNER, type GameScopes, type GameScopesIssue, HANDOFF_DIR, type HandoffIssue, type HygieneIssue, type ImportOptions, type ImportPlan, type ImportProblem, type ImportReport, type InitOptions, type InitResult, type InitVcs, type LoadedProject, type LocCatalog, type LocEntry, type LocaleReport, type MergeFileType, type MergeResult, type MergedShard, type OpenSuggestion, PATTER_SCOPES_FILE, PATTER_SCOPES_OWNER, type PinPlan, type PinnedName, type PlannedWrite, type PlayEvent, type PlayOptions, type PlayOutcome, type PlayResult, type ProvenanceCheck, RARE_REACH_PCT, REFUSE_MISSING_SHARE, type Random, type ReadBox, type ReadComment, type ReadItem, type ReadMarker, type ReadParagraph, type ReadText, type ReplaceHit, type ReplaceOptions, type ReplacePlan, type ReportData, type ReportTotals, type ResolveEntry, type ReturnedDoc, SHARD_EXTENSIONS, type SceneReport, type ScriptDoc, type ScriptElement, type SearchFocus, type SuggestionDecision, type TrackedChange, type UnpackMergeResult, type UnpackResult, UnsafeEntryError, UnsupportedMergeError, type ValidateResult, type VoiceLine, type VoiceScript, type VoicedCounts, type WebExport, type WrittenCounts, applyLoc, applySceneOrder, applySuggestionDecisions, applyWrites, bundleOutputPath, catalogToJson, catalogToPo, catalogToXlsx, classesForChannel, defaultGameScopesDir, detectMergeType, discoverGameScopes, drivableScopes, exportEditableScript, extractLoc, findProjectFile, formatMarker, gameScopeTokens, gameScopesCatalogue, gameScopesSnapshot, handoffPath, handoffWrite, hostScopeTokens, issueMarkerCodes, jsonToCatalog, leastReachedFirst, listOpenSuggestions, listProjectTags, loadProject, loadProjectLanding, markerLength, newHandoffId, parseHandoff, patterScopesFile, patterScopesStale, patterScopesWrite, planEditableImport, planPins, planReturnedWorld, planShareScopes, planWorldSave, poToCatalog, previewRegistry, proposeCoverageDrivers, reachabilityIssues, readEditableDocx, readGameScopes, readHandoff, readHandoffs, readMarker, renderCoverageText, renderPlay, renderReportText, resolveDocumentation, resolveStart, runCoverage, runCoverageAsync, 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, serialiseHandoff, setCut, sidecarIssues, staleParts, vcsConfigWrites, voiceScriptToXlsx, worldSettingsScopes, xlsxToCatalog };