@flare-engine/dialogue 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { Signal } from '@flare-engine/events';
-
+import { Signal } from "@flare-engine/events";
+//#region src/graph.d.ts
 /**
  * Dialogue graph data types.
  *
@@ -13,117 +13,134 @@ import { Signal } from '@flare-engine/events';
  * Graphs are plain JSON — no classes, no runtime coupling.
  */
 interface LineNode {
-    readonly kind: 'line';
-    /** Speaker name / id. */
-    readonly speaker: string;
-    /**
-     * Optional portrait key resolved by the UI layer to an avatar image /
-     * shape / atlas frame. The dialogue runtime is portrait-agnostic — it
-     * forwards the key via `DialogueLineEvent.speakerPortraitKey`.
-     */
-    readonly speakerPortraitKey?: string;
-    /** Text template. Supports `{var}` interpolation via the runner's variable bag. */
-    readonly text: string;
-    /** Next node id, or null to end. */
-    readonly next: string | null;
+  readonly kind: 'line';
+  /** Speaker name / id. */
+  readonly speaker: string;
+  /**
+   * Optional portrait key resolved by the UI layer to an avatar image /
+   * shape / atlas frame. The dialogue runtime is portrait-agnostic — it
+   * forwards the key via `DialogueLineEvent.speakerPortraitKey`.
+   */
+  readonly speakerPortraitKey?: string;
+  /** Text template. Supports `{var}` interpolation via the runner's variable bag. */
+  readonly text: string;
+  /** Next node id, or null to end. */
+  readonly next: string | null;
 }
 interface ChoiceOption {
-    /** Display text. Supports `{var}` interpolation. */
-    readonly text: string;
-    /** Node id to jump to when selected. */
-    readonly next: string;
-    /** Optional condition key — option is hidden when condition returns false. */
-    readonly condition?: string;
+  /** Display text. Supports `{var}` interpolation. */
+  readonly text: string;
+  /** Node id to jump to when selected. */
+  readonly next: string;
+  /** Optional condition key — option is hidden when condition returns false. */
+  readonly condition?: string;
 }
 interface ChoiceNode {
-    readonly kind: 'choice';
-    /** Optional prompt text before the choices. */
-    readonly prompt?: string;
-    /** Speaker for the prompt, if any. */
-    readonly speaker?: string;
-    readonly options: readonly ChoiceOption[];
+  readonly kind: 'choice';
+  /** Optional prompt text before the choices. */
+  readonly prompt?: string;
+  /** Speaker for the prompt, if any. */
+  readonly speaker?: string;
+  readonly options: readonly ChoiceOption[];
 }
 interface BranchArm {
-    /** Condition key evaluated by the runner's condition resolver. */
-    readonly condition: string;
-    /** Node id to jump to when condition is true. */
-    readonly next: string;
+  /** Condition key evaluated by the runner's condition resolver. */
+  readonly condition: string;
+  /** Node id to jump to when condition is true. */
+  readonly next: string;
 }
 interface BranchNode {
-    readonly kind: 'branch';
-    readonly arms: readonly BranchArm[];
-    /** Fallback node id if no arm matches. Null → end. */
-    readonly fallback: string | null;
+  readonly kind: 'branch';
+  readonly arms: readonly BranchArm[];
+  /** Fallback node id if no arm matches. Null → end. */
+  readonly fallback: string | null;
 }
 interface ActionNode {
-    readonly kind: 'action';
-    /** Callback key. Runner looks this up in the action registry. */
-    readonly action: string;
-    /** Next node id after the action fires. */
-    readonly next: string | null;
+  readonly kind: 'action';
+  /** Callback key. Runner looks this up in the action registry. */
+  readonly action: string;
+  /** Next node id after the action fires. */
+  readonly next: string | null;
 }
 interface EndNode {
-    readonly kind: 'end';
+  readonly kind: 'end';
 }
 type DialogueNode = LineNode | ChoiceNode | BranchNode | ActionNode | EndNode;
 interface DialogueGraph {
-    /** Unique graph identifier. */
-    readonly id: string;
-    /** Node id to start from. */
-    readonly start: string;
-    /** All nodes keyed by id. */
-    readonly nodes: Record<string, DialogueNode>;
+  /** Unique graph identifier. */
+  readonly id: string;
+  /** Node id to start from. */
+  readonly start: string;
+  /** All nodes keyed by id. */
+  readonly nodes: Record<string, DialogueNode>;
 }
 declare function createDialogueGraph(id: string, start: string, nodes: Record<string, DialogueNode>): DialogueGraph;
 declare function getNode(graph: DialogueGraph, nodeId: string): DialogueNode | undefined;
-
-/**
- * Dialogue runner — walks a DialogueGraph, evaluating conditions,
- * interpolating variables, and emitting signals for each step.
- */
-
+//#endregion
+//#region src/runner.d.ts
+type DialogueErrorCode = 'missing-node' | 'cycle';
+declare class DialogueError extends Error {
+  readonly code: DialogueErrorCode;
+  /** Source node whose transition triggered the error (or the entry id when there is no source). */
+  readonly nodeId: string;
+  /** 'missing-node': the target id that could not be resolved. */
+  readonly missingId?: string;
+  /** 'cycle': the node-id chain walked before the step budget was exceeded. */
+  readonly chain?: readonly string[];
+  constructor(code: DialogueErrorCode, message: string, detail: {
+    nodeId: string;
+    missingId?: string;
+    chain?: readonly string[];
+  });
+}
 type ConditionResolver = (key: string) => boolean;
 type ActionHandler = (key: string) => void | Promise<void>;
 type VariableBag = Record<string, string | number>;
 interface DialogueLineEvent {
-    readonly speaker: string;
-    /** Optional portrait key forwarded verbatim from the source LineNode. */
-    readonly speakerPortraitKey?: string;
-    readonly text: string;
-    readonly nodeId: string;
+  readonly speaker: string;
+  /** Optional portrait key forwarded verbatim from the source LineNode. */
+  readonly speakerPortraitKey?: string;
+  readonly text: string;
+  readonly nodeId: string;
 }
 interface DialogueChoiceEvent {
-    readonly prompt: string | undefined;
-    readonly speaker: string | undefined;
-    readonly options: readonly ActiveOption[];
-    readonly nodeId: string;
+  readonly prompt: string | undefined;
+  readonly speaker: string | undefined;
+  readonly options: readonly ActiveOption[];
+  readonly nodeId: string;
 }
 interface ActiveOption {
-    readonly index: number;
-    readonly text: string;
-    readonly next: string;
+  readonly index: number;
+  readonly text: string;
+  readonly next: string;
 }
 type DialogueRunnerState = 'idle' | 'running' | 'waiting-choice' | 'ended';
 declare function interpolate(template: string, vars: VariableBag): string;
 interface DialogueRunner {
-    readonly onLine: Signal<DialogueLineEvent>;
-    readonly onChoice: Signal<DialogueChoiceEvent>;
-    readonly onAction: Signal<string>;
-    readonly onEnd: Signal<string>;
-    readonly state: DialogueRunnerState;
-    readonly currentNodeId: string | null;
-    readonly graphId: string | null;
-    start(graph: DialogueGraph, variables?: VariableBag): void;
-    advance(): void;
-    selectChoice(index: number): void;
-    stop(): void;
+  readonly onLine: Signal<DialogueLineEvent>;
+  readonly onChoice: Signal<DialogueChoiceEvent>;
+  readonly onAction: Signal<string>;
+  readonly onEnd: Signal<string>;
+  readonly state: DialogueRunnerState;
+  readonly currentNodeId: string | null;
+  readonly graphId: string | null;
+  start(graph: DialogueGraph, variables?: VariableBag): void;
+  advance(): void;
+  selectChoice(index: number): void;
+  stop(): void;
 }
 interface DialogueRunnerOptions {
-    conditions?: ConditionResolver;
-    actions?: ActionHandler;
+  conditions?: ConditionResolver;
+  actions?: ActionHandler;
+  /**
+   * Invoked on a recoverable dialogue error — currently a transition to a
+   * missing node. Default (no hook): logs a console.warn, then ends.
+   */
+  onError?: (err: DialogueError) => void;
 }
 declare function createDialogueRunner(options?: DialogueRunnerOptions): DialogueRunner;
-
+//#endregion
+//#region src/text-reveal.d.ts
 /**
  * Text-over-time reveal hook for dialogue lines.
  *
@@ -132,24 +149,25 @@ declare function createDialogueRunner(options?: DialogueRunnerOptions): Dialogue
  * Supports per-character speed, instant-complete, and pause-on-punctuation.
  */
 interface TextRevealState {
-    /** Full text being revealed. */
-    readonly fullText: string;
-    /** Characters revealed so far. */
-    visibleText: string;
-    /** Whether the full text has been revealed. */
-    complete: boolean;
-    /** Internal fractional character cursor. */
-    _cursor: number;
+  /** Full text being revealed. */
+  readonly fullText: string;
+  /** Characters revealed so far. */
+  visibleText: string;
+  /** Whether the full text has been revealed. */
+  complete: boolean;
+  /** Internal fractional character cursor. */
+  _cursor: number;
 }
 interface TextRevealOptions {
-    /** Characters per second. Default: 30. */
-    speed?: number;
-    /** Extra delay (in seconds) after punctuation (.!?). Default: 0.15. */
-    punctuationDelay?: number;
+  /** Characters per second. Default: 30. */
+  speed?: number;
+  /** Extra delay (in seconds) after punctuation (.!?). Default: 0.15. */
+  punctuationDelay?: number;
 }
 declare function createTextReveal(text: string): TextRevealState;
 declare function updateTextReveal(state: TextRevealState, dt: number, options?: TextRevealOptions): void;
 declare function completeTextReveal(state: TextRevealState): void;
 declare function resetTextReveal(state: TextRevealState, newText?: string): void;
-
-export { type ActionHandler, type ActionNode, type ActiveOption, type BranchArm, type BranchNode, type ChoiceNode, type ChoiceOption, type ConditionResolver, type DialogueChoiceEvent, type DialogueGraph, type DialogueLineEvent, type DialogueNode, type DialogueRunner, type DialogueRunnerOptions, type DialogueRunnerState, type EndNode, type LineNode, type TextRevealOptions, type TextRevealState, type VariableBag, completeTextReveal, createDialogueGraph, createDialogueRunner, createTextReveal, getNode, interpolate, resetTextReveal, updateTextReveal };
+//#endregion
+export { type ActionHandler, type ActionNode, type ActiveOption, type BranchArm, type BranchNode, type ChoiceNode, type ChoiceOption, type ConditionResolver, type DialogueChoiceEvent, DialogueError, type DialogueErrorCode, type DialogueGraph, type DialogueLineEvent, type DialogueNode, type DialogueRunner, type DialogueRunnerOptions, type DialogueRunnerState, type EndNode, type LineNode, type TextRevealOptions, type TextRevealState, type VariableBag, completeTextReveal, createDialogueGraph, createDialogueRunner, createTextReveal, getNode, interpolate, resetTextReveal, updateTextReveal };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/graph.ts","../src/runner.ts","../src/text-reveal.ts"],"mappings":";;;;;;;;;;;;;;UAeiB;WACN;;WAEA;;;;;;WAMA;;WAEA;;WAEA;;UAGM;;WAEN;;WAEA;;WAEA;;UAGM;WACN;;WAEA;;WAEA;WACA,kBAAkB;;UAGZ;;WAEN;;WAEA;;UAGM;WACN;WACA,eAAe;;WAEf;;UAGM;WACN;;WAEA;;WAEA;;UAGM;WACN;;KAGC,eAAe,WAAW,aAAa,aAAa,aAAa;UAI5D;;WAEN;;WAEA;;WAEA,OAAO,eAAe;;iBAGjB,oBACd,YACA,eACA,OAAO,eAAe,gBACrB;iBAIa,QAAQ,OAAO,eAAe,iBAAiB;;;KCrFnD;cAEC,sBAAsB;WACxB,MAAM;;WAEN;;WAEA;;WAEA;cAGP,MAAM,mBACN,iBACA;IAAU;IAAgB;IAAoB;;;KAatC,qBAAqB;KACrB,iBAAiB,uBAAuB;KACxC,cAAc;UAET;WACN;;WAEA;WACA;WACA;;UAGM;WACN;WACA;WACA,kBAAkB;WAClB;;UAGM;WACN;WACA;WACA;;KAGC;iBAII,YAAY,kBAAkB,MAAM;UASnC;WACN,QAAQ,OAAO;WACf,UAAU,OAAO;WACjB,UAAU;WACV,OAAO;WAEP,OAAO;WACP;WACA;EAET,MAAM,OAAO,eAAe,YAAY;EACxC;EACA,aAAa;EACb;;UAGe;EACf,aAAa;EACb,UAAU;;;;;EAKV,WAAW,KAAK;;iBAKF,qBAAqB,UAAU,wBAAwB;;;;;;;;;;UC9FtD;;WAEN;;EAET;;EAEA;;EAEA;;UAGe;;EAEf;;EAEA;;iBAUc,iBAAiB,eAAe;iBAOhC,iBACd,OAAO,iBACP,YACA,UAAU;iBA8BI,mBAAmB,OAAO;iBAM1B,gBAAgB,OAAO,iBAAiB"}