yarn-spinner-runner-ts 0.1.2 → 0.1.4

package/src/runtime/commands.ts

@@ -29,6 +29,14 @@ export function parseCommand(content: string): ParsedCommand {
     const char = trimmed[i];
 
     if ((char === '"' || char === "'") && !inQuotes) {
+      // If we have accumulated non-quoted content (e.g. a function name and "(")
+      // push it as its own part before entering quoted mode. This prevents the
+      // surrounding text from being merged into the quoted content when we
+      // later push the quoted value.
+      if (current.trim()) {
+        parts.push(current.trim());
+        current = "";
+      }
       inQuotes = true;
       quoteChar = char;
       continue;
@@ -36,8 +44,11 @@ export function parseCommand(content: string): ParsedCommand {
 
     if (char === quoteChar && inQuotes) {
       inQuotes = false;
+      // Preserve the surrounding quotes in the parsed part so callers that
+      // reassemble the expression (e.g. declare handlers) keep string literals
+      // intact instead of losing quote characters.
+      parts.push(quoteChar + current + quoteChar);
       quoteChar = "";
-      parts.push(current);
       current = "";
       continue;
     }
@@ -129,11 +140,13 @@ export class CommandHandler {
     this.register("declare", (args, evaluator) => {
       if (!evaluator) return;
       if (args.length < 3) return; // name, '=', expr
+      
       const varNameRaw = args[0];
       let exprParts = args.slice(1);
       if (exprParts[0] === "=") exprParts = exprParts.slice(1);
       const expr = exprParts.join(" ");
       
+      
       const key = varNameRaw.startsWith("$") ? varNameRaw.slice(1) : varNameRaw;
       
       // Check if expression is "smart" (contains operators, comparisons, or variable references)

package/src/runtime/results.ts

@@ -1,8 +1,10 @@
+import type { MarkupParseResult } from "../markup/types.js";
 export type TextResult = {
   type: "text";
   text: string;
   speaker?: string;
   tags?: string[];
+  markup?: MarkupParseResult;
   nodeCss?: string; // Node-level CSS from &css{} header
   scene?: string; // Scene name from node header
   isDialogueEnd: boolean;
@@ -10,7 +12,7 @@ export type TextResult = {
 
 export type OptionsResult = {
   type: "options";
-  options: { text: string; tags?: string[]; css?: string }[];
+  options: { text: string; tags?: string[]; css?: string; markup?: MarkupParseResult }[];
   nodeCss?: string; // Node-level CSS from &css{} header
   scene?: string; // Scene name from node header
   isDialogueEnd: boolean;

package/src/runtime/runner.ts

@@ -1,4 +1,5 @@
 import type { IRProgram, IRInstruction, IRNode, IRNodeGroup } from "../compile/ir";
+import type { MarkupParseResult, MarkupSegment, MarkupWrapper } from "../markup/types.js";
 import type { RuntimeResult } from "./results.js";
 import { ExpressionEvaluator } from "./evaluator.js";
 import { CommandHandler, parseCommand } from "./commands.js";
@@ -9,6 +10,7 @@ export interface RunnerOptions {
   functions?: Record<string, (...args: unknown[]) => unknown>;
   handleCommand?: (command: string, parsed?: ReturnType<typeof parseCommand>) => void;
   commandHandler?: CommandHandler;
+  onStoryEnd?: (payload: { variables: Readonly<Record<string, unknown>>; storyEnd: true }) => void;
 }
 
 const globalOnceSeen = new Set<string>();
@@ -22,6 +24,8 @@ export class YarnRunner {
   private readonly commandHandler: CommandHandler;
   private readonly evaluator: ExpressionEvaluator;
   private readonly onceSeen = globalOnceSeen;
+  private readonly onStoryEnd?: RunnerOptions["onStoryEnd"];
+  private storyEnded = false;
   private readonly nodeGroupOnceSeen = globalNodeGroupOnceSeen;
   private readonly visitCounts: Record<string, number> = {};
 
@@ -94,6 +98,7 @@ export class YarnRunner {
       ...(opts.functions ?? {}),
     } as Record<string, (...args: unknown[]) => unknown>;
     this.handleCommand = opts.handleCommand;
+    this.onStoryEnd = opts.onStoryEnd;
     this.evaluator = new ExpressionEvaluator(this.variables, this.functions, this.program.enums);
     this.commandHandler = opts.commandHandler ?? new CommandHandler(this.variables);
     this.nodeTitle = opts.startAt;
@@ -205,15 +210,152 @@ export class YarnRunner {
     this.step();
   }
 
-  private interpolate(text: string): string {
-    return text.replace(/\{([^}]+)\}/g, (_m, expr) => {
+  private interpolate(text: string, markup?: MarkupParseResult): { text: string; markup?: MarkupParseResult } {
+    const evaluateExpression = (expr: string): string => {
       try {
-        const val = this.evaluator.evaluateExpression(String(expr));
-        return String(val ?? "");
+        const value = this.evaluator.evaluateExpression(expr.trim());
+        if (value === null || value === undefined) {
+          return "";
+        }
+        return String(value);
       } catch {
         return "";
       }
-    });
+    };
+
+    if (!markup) {
+      const interpolated = text.replace(/\{([^}]+)\}/g, (_m, expr) => evaluateExpression(expr));
+      return { text: interpolated };
+    }
+
+    const segments = markup.segments.filter((segment) => !segment.selfClosing);
+    const getWrappersAt = (index: number): MarkupWrapper[] => {
+      for (const segment of segments) {
+        if (segment.start <= index && index < segment.end) {
+          return segment.wrappers.map((wrapper) => ({
+            name: wrapper.name,
+            type: wrapper.type,
+            properties: { ...wrapper.properties },
+          }));
+        }
+      }
+      if (segments.length === 0) {
+        return [];
+      }
+      if (index > 0) {
+        return getWrappersAt(index - 1);
+      }
+      return segments[0].wrappers.map((wrapper) => ({
+        name: wrapper.name,
+        type: wrapper.type,
+        properties: { ...wrapper.properties },
+      }));
+    };
+
+    const resultChars: string[] = [];
+    const newSegments: MarkupSegment[] = [];
+    let currentSegment: MarkupSegment | null = null;
+
+    const wrappersEqual = (a: MarkupWrapper[], b: MarkupWrapper[]) => {
+      if (a.length !== b.length) return false;
+      for (let i = 0; i < a.length; i++) {
+        const wa = a[i];
+        const wb = b[i];
+        if (wa.name !== wb.name || wa.type !== wb.type) return false;
+        const keysA = Object.keys(wa.properties);
+        const keysB = Object.keys(wb.properties);
+        if (keysA.length !== keysB.length) return false;
+        for (const key of keysA) {
+          if (wa.properties[key] !== wb.properties[key]) return false;
+        }
+      }
+      return true;
+    };
+
+    const flushSegment = () => {
+      if (currentSegment) {
+        newSegments.push(currentSegment);
+        currentSegment = null;
+      }
+    };
+
+    const appendCharWithWrappers = (char: string, wrappers: MarkupWrapper[]) => {
+      const index = resultChars.length;
+      resultChars.push(char);
+      const wrappersCopy = wrappers.map((wrapper) => ({
+        name: wrapper.name,
+        type: wrapper.type,
+        properties: { ...wrapper.properties },
+      }));
+      if (currentSegment && wrappersEqual(currentSegment.wrappers, wrappersCopy)) {
+        currentSegment.end = index + 1;
+      } else {
+        flushSegment();
+        currentSegment = { start: index, end: index + 1, wrappers: wrappersCopy };
+      }
+    };
+
+    const appendStringWithWrappers = (value: string, wrappers: MarkupWrapper[]) => {
+      if (!value) {
+        flushSegment();
+        return;
+      }
+      for (const ch of value) {
+        appendCharWithWrappers(ch, wrappers);
+      }
+    };
+
+    let i = 0;
+    while (i < text.length) {
+      const char = text[i];
+      if (char === '{') {
+        const close = text.indexOf('}', i + 1);
+        if (close === -1) {
+          appendCharWithWrappers(char, getWrappersAt(Math.max(0, Math.min(i, text.length - 1))));
+          i += 1;
+          continue;
+        }
+        const expr = text.slice(i + 1, close);
+        const evaluated = evaluateExpression(expr);
+        const wrappers = getWrappersAt(Math.max(0, Math.min(i, text.length - 1)));
+        appendStringWithWrappers(evaluated, wrappers);
+        i = close + 1;
+        continue;
+      }
+      appendCharWithWrappers(char, getWrappersAt(i));
+      i += 1;
+    }
+
+    flushSegment();
+    const interpolatedText = resultChars.join('');
+    const normalizedMarkup = this.normalizeMarkupResult({ text: interpolatedText, segments: newSegments });
+    return { text: interpolatedText, markup: normalizedMarkup };
+  }
+
+  private normalizeMarkupResult(result: MarkupParseResult): MarkupParseResult | undefined {
+    if (!result) return undefined;
+    if (result.segments.length === 0) {
+      return undefined;
+    }
+    const hasFormatting = result.segments.some(
+      (segment) => segment.wrappers.length > 0 || segment.selfClosing
+    );
+    if (!hasFormatting) {
+      return undefined;
+    }
+    return {
+      text: result.text,
+      segments: result.segments.map((segment) => ({
+        start: segment.start,
+        end: segment.end,
+        wrappers: segment.wrappers.map((wrapper) => ({
+          name: wrapper.name,
+          type: wrapper.type,
+          properties: { ...wrapper.properties },
+        })),
+        selfClosing: segment.selfClosing,
+      })),
+    };
   }
 
   private resumeBlock(): boolean {
@@ -229,9 +371,11 @@ export class YarnRunner {
         return true;
       }
       switch (ins.op) {
-        case "line":
-          this.emit({ type: "text", text: this.interpolate(ins.text), speaker: ins.speaker, tags: ins.tags, isDialogueEnd: false });
+        case "line": {
+          const { text: interpolatedText, markup: interpolatedMarkup } = this.interpolate(ins.text, ins.markup);
+          this.emit({ type: "text", text: interpolatedText, speaker: ins.speaker, tags: ins.tags, markup: interpolatedMarkup, isDialogueEnd: false });
           return true;
+        }
         case "command": {
           try {
             const parsed = parseCommand(ins.content);
@@ -244,7 +388,7 @@ export class YarnRunner {
           return true;
         }
         case "options": {
-          this.emit({ type: "options", options: ins.options.map((o) => ({ text: o.text, tags: o.tags })), isDialogueEnd: false });
+          this.emit({ type: "options", options: ins.options.map((o) => ({ text: o.text, tags: o.tags, markup: o.markup })), isDialogueEnd: false });
           return true;
         }
         case "if": {
@@ -294,9 +438,11 @@ export class YarnRunner {
       }
       this.ip++;
       switch (ins.op) {
-        case "line":
-          this.emit({ type: "text", text: this.interpolate(ins.text), speaker: ins.speaker, tags: ins.tags, nodeCss: resolved.css, scene: resolved.scene, isDialogueEnd: this.lookaheadIsEnd() });
+        case "line": {
+          const { text: interpolatedText, markup: interpolatedMarkup } = this.interpolate(ins.text, ins.markup);
+          this.emit({ type: "text", text: interpolatedText, speaker: ins.speaker, tags: ins.tags, markup: interpolatedMarkup, nodeCss: resolved.css, scene: resolved.scene, isDialogueEnd: this.lookaheadIsEnd() });
           return;
+        }
         case "command": {
           try {
             const parsed = parseCommand(ins.content);
@@ -327,7 +473,7 @@ export class YarnRunner {
           continue;
         }
         case "options": {
-          this.emit({ type: "options", options: ins.options.map((o: { text: string; tags?: string[]; css?: string }) => ({ text: o.text, tags: o.tags, css: o.css })), nodeCss: resolved.css, scene: resolved.scene, isDialogueEnd: this.lookaheadIsEnd() });
+          this.emit({ type: "options", options: ins.options.map((o: { text: string; tags?: string[]; css?: string; markup?: MarkupParseResult }) => ({ text: o.text, tags: o.tags, css: o.css, markup: o.markup })), nodeCss: resolved.css, scene: resolved.scene, isDialogueEnd: this.lookaheadIsEnd() });
           return;
         }
         case "if": {
@@ -368,10 +514,12 @@ export class YarnRunner {
       const ins = tempNode.instructions[idx++];
       if (!ins) break;
       switch (ins.op) {
-        case "line":
-          this.emit({ type: "text", text: ins.text, speaker: ins.speaker, isDialogueEnd: false });
+        case "line": {
+          const { text: interpolatedText, markup: interpolatedMarkup } = this.interpolate(ins.text, ins.markup);
+          this.emit({ type: "text", text: interpolatedText, speaker: ins.speaker, markup: interpolatedMarkup, isDialogueEnd: false });
           restore();
           return;
+        }
         case "command":
           try {
             const parsed = parseCommand(ins.content);
@@ -384,7 +532,7 @@ export class YarnRunner {
           restore();
           return;
         case "options":
-          this.emit({ type: "options", options: ins.options.map((o) => ({ text: o.text })), isDialogueEnd: false });
+          this.emit({ type: "options", options: ins.options.map((o) => ({ text: o.text, markup: o.markup })), isDialogueEnd: false });
           // Maintain context that options belong to main node at ip-1
           restore();
           return;
@@ -445,6 +593,14 @@ export class YarnRunner {
   private emit(res: RuntimeResult) {
     this.currentResult = res;
     this.history.push(res);
+    if (res.isDialogueEnd && !this.storyEnded && this.callStack.length === 0) {
+      this.storyEnded = true;
+      if (this.onStoryEnd) {
+        // Create a readonly copy of the variables
+        const variablesCopy = Object.freeze({ ...this.variables });
+        this.onStoryEnd({ storyEnd: true, variables: variablesCopy });
+      }
+    }
     // If we ended a detour node, return to caller after emitting last result
     // Position is restored here, but we wait for next advance() to continue
     if (res.isDialogueEnd && this.callStack.length > 0) {

package/src/tests/custom_functions.test.ts

@@ -0,0 +1,140 @@
+import { test } from "node:test";
+import { strictEqual, ok, match } from "node:assert";
+import { parseYarn, compile } from "../index.js";
+import { YarnRunner } from "../runtime/runner.js";
+
+test("custom functions", () => {
+  const yarnText = `
+title: CustomFuncs
+---
+<<declare $doubled = multiply(2, 3)>>
+<<declare $concatenated = concat("Hello", " World")>>
+<<declare $power = pow(2, 3)>>
+<<declare $conditionalValue = ifThen(true, "yes", "no")>>
+Result: {$doubled}, {$concatenated}, {$power}, {$conditionalValue}
+===
+`;
+
+  const ast = parseYarn(yarnText);
+  const program = compile(ast);
+  const runner = new YarnRunner(program, {
+    startAt: "CustomFuncs",
+    functions: {
+      multiply: (a: unknown, b: unknown) => Number(a) * Number(b),
+      concat: (a: unknown, b: unknown) => String(a) + String(b),
+      pow: (base: unknown, exp: unknown) => Math.pow(Number(base), Number(exp)),
+      ifThen: (cond: unknown, yes: unknown, no: unknown) => Boolean(cond) ? yes : no,
+    },
+  });
+
+  // Need to advance past declare commands and get to the text line
+  for (let i = 0; i < 4; i++) {
+    runner.advance();
+  }
+  strictEqual(runner.currentResult?.type, "text");
+  if (runner.currentResult?.type === "text") {
+    const fullText = (runner.currentResult.speaker ? `${runner.currentResult.speaker}: ` : "") + runner.currentResult.text;
+    strictEqual(fullText, "Result: 6, Hello World, 8, yes");
+  }
+});
+
+test("custom functions with type coercion", () => {
+  const yarnText = `
+title: TypeCoercion
+---
+<<declare $numFromStr = multiply("2", "3")>>
+<<declare $concatNums = concat(123, 456)>>
+<<declare $boolStr = ifThen("true", 1, 0)>>
+Result: {$numFromStr}, {$concatNums}, {$boolStr}
+===
+`;
+
+  const ast = parseYarn(yarnText);
+  const program = compile(ast);
+  const runner = new YarnRunner(program, {
+    startAt: "TypeCoercion",
+    functions: {
+      multiply: (a: unknown, b: unknown) => Number(a) * Number(b),
+      concat: (a: unknown, b: unknown) => String(a) + String(b),
+      ifThen: (cond: unknown, yes: unknown, no: unknown) => Boolean(cond) ? yes : no,
+    },
+  });
+
+  // Need to advance past declare commands and get to the text line
+  for (let i = 0; i < 3; i++) {
+    runner.advance();
+  }
+  strictEqual(runner.currentResult?.type, "text");
+  if (runner.currentResult?.type === "text") {
+    const fullText = (runner.currentResult.speaker ? `${runner.currentResult.speaker}: ` : "") + runner.currentResult.text;
+    strictEqual(fullText, "Result: 6, 123456, 1");
+  }
+});
+
+test("custom functions error handling", () => {
+  const yarnText = `
+title: ErrorHandling
+---
+<<declare $result = safeDivide(10, 0)>>
+Result: {$result}
+===
+`;
+
+  const ast = parseYarn(yarnText);
+  const program = compile(ast);
+  const runner = new YarnRunner(program, {
+    startAt: "ErrorHandling",
+    functions: {
+      safeDivide: (a: unknown, b: unknown) => {
+        const numerator = Number(a);
+        const denominator = Number(b);
+        return denominator === 0 ? "Cannot divide by zero" : numerator / denominator;
+      },
+    },
+  });
+
+  // Advance until we reach a text result (some commands emit immediately)
+  for (let i = 0; i < 10 && runner.currentResult?.type !== "text"; i++) {
+    runner.advance();
+  }
+  strictEqual(runner.currentResult?.type, "text");
+  if (runner.currentResult?.type === "text") {
+    const fullText = (runner.currentResult.speaker ? `${runner.currentResult.speaker}: ` : "") + runner.currentResult.text;
+    strictEqual(fullText, "Result: Cannot divide by zero");
+  }
+});
+
+test("custom functions alongside built-in functions", () => {
+  const yarnText = `
+title: MixedFunctions
+---
+<<declare $random = random()>>
+<<declare $doubled = multiply($random, 2)>>
+<<declare $formatted = format_number($doubled)>>
+Result: {$formatted}
+===
+`;
+
+  const ast = parseYarn(yarnText);
+  const program = compile(ast);
+  const runner = new YarnRunner(program, {
+    startAt: "MixedFunctions",
+    functions: {
+      multiply: (a: unknown, b: unknown) => Number(a) * Number(b),
+      format_number: (n: unknown) => Number(n).toFixed(2),
+    },
+  });
+
+  // Need to advance past declare commands and get to the text line
+  for (let i = 0; i < 3; i++) {
+    runner.advance();
+  }
+  strictEqual(runner.currentResult?.type, "text");
+  if (runner.currentResult?.type === "text") {
+    const fullText = (runner.currentResult.speaker ? `${runner.currentResult.speaker}: ` : "") + runner.currentResult.text;
+    const resultNumber = parseFloat(fullText.replace("Result: ", ""));
+    ok(resultNumber >= 0);
+    ok(resultNumber <= 2);
+    match(fullText, /Result: \d+\.\d{2}/);
+  }
+});

package/src/tests/markup.test.ts

@@ -0,0 +1,62 @@
+import { test } from "node:test";
+import { strictEqual, ok } from "node:assert";
+import { parseMarkup } from "../markup/parser.js";
+import type { MarkupParseResult } from "../markup/types.js";
+
+test("parseMarkup handles default HTML tags", () => {
+  const result = parseMarkup("This is [b]bold[/b] and [em]emphasized[/em].");
+
+  strictEqual(result.text, "This is bold and emphasized.");
+  const bold = findSegment(result, "bold");
+  ok(bold, "Expected bold segment");
+  strictEqual(bold.wrappers.length, 1);
+  strictEqual(bold.wrappers[0].name, "b");
+  strictEqual(bold.wrappers[0].type, "default");
+
+  const em = findSegment(result, "emphasized");
+  ok(em, "Expected em segment");
+  strictEqual(em.wrappers[0].name, "em");
+  strictEqual(em.wrappers[0].type, "default");
+});
+
+test("parseMarkup exposes custom tags with properties", () => {
+  const result = parseMarkup("Say [wave speed=2 tone=\"high\"]hello[/wave]!");
+  strictEqual(result.text, "Say hello!");
+
+  const segment = findSegment(result, "hello");
+  ok(segment, "Expected wave segment");
+  const wrapper = segment.wrappers.find((w) => w.name === "wave");
+  ok(wrapper, "Expected wave wrapper");
+  strictEqual(wrapper.type, "custom");
+  strictEqual(wrapper.properties.speed, 2);
+  strictEqual(wrapper.properties.tone, "high");
+});
+
+test("parseMarkup handles self-closing tags", () => {
+  const result = parseMarkup("[pause length=500/] Ready.");
+  strictEqual(result.text, " Ready.");
+  ok(
+    result.segments.some(
+      (seg) => seg.selfClosing && seg.wrappers.some((wrapper) => wrapper.name === "pause")
+    ),
+    "Expected self closing pause marker"
+  );
+});
+
+test("parseMarkup respects nomarkup blocks and escaping", () => {
+  const result = parseMarkup(`[nomarkup][b] raw [/b][/nomarkup] and \\[escaped\\]`);
+  strictEqual(result.text, "[b] raw [/b] and [escaped]");
+  ok(
+    result.segments.every((segment) => segment.wrappers.length === 0),
+    "Expected no wrappers when using nomarkup and escaping"
+  );
+});
+
+function findSegment(result: MarkupParseResult, target: string) {
+  return result.segments.find((segment) => {
+    if (segment.selfClosing) return false;
+    const text = result.text.slice(segment.start, segment.end);
+    return text === target;
+  });
+}
+

package/src/tests/nodes_lines.test.ts

@@ -1,5 +1,5 @@
 import { test } from "node:test";
-import { strictEqual } from "node:assert";
+import { strictEqual, ok } from "node:assert";
 import { parseYarn, compile, YarnRunner } from "../index.js";
 
 test("nodes and lines delivery", () => {
@@ -25,3 +25,37 @@ Narrator: Line two
 });
 
 
+
+
+test("markup parsing propagates to runtime", () => {
+  const script = `
+title: Start
+---
+Narrator: Plain [b]bold[/b] [wave speed=2]custom[/wave]
+===
+  `;
+
+  const doc = parseYarn(script);
+  const ir = compile(doc);
+  const runner = new YarnRunner(ir, { startAt: "Start" });
+
+  const result = runner.currentResult;
+  ok(result && result.type === "text", "Expected text result with markup");
+  ok(result?.markup, "Expected markup data to be present");
+  const markup = result!.markup!;
+  strictEqual(markup.text, "Plain bold custom");
+
+  const boldSegment = markup.segments.find((segment) =>
+    segment.wrappers.some((wrapper) => wrapper.name === "b" && wrapper.type === "default")
+  );
+  ok(boldSegment, "Expected bold segment");
+  strictEqual(markup.text.slice(boldSegment!.start, boldSegment!.end), "bold");
+
+  const customSegment = markup.segments.find((segment) =>
+    segment.wrappers.some((wrapper) => wrapper.name === "wave" && wrapper.type === "custom")
+  );
+  ok(customSegment, "Expected custom segment");
+  const waveWrapper = customSegment!.wrappers.find((wrapper) => wrapper.name === "wave");
+  ok(waveWrapper);
+  strictEqual(waveWrapper!.properties.speed, 2);
+});

package/src/tests/options.test.ts

@@ -1,5 +1,5 @@
 import { test } from "node:test";
-import { strictEqual } from "node:assert";
+import { strictEqual, ok } from "node:assert";
 import { parseYarn, compile, YarnRunner } from "../index.js";
 
 test("options selection", () => {
@@ -32,3 +32,41 @@ Narrator: Choose one
 });
 
 
+
+
+test("option markup is exposed", () => {
+  const script = `
+title: Start
+---
+Narrator: Choose
+-> [b]Bold[/b]
+    Narrator: Bold
+-> [wave intensity=5]Custom[/wave]
+    Narrator: Custom
+===
+  `;
+
+  const doc = parseYarn(script);
+  const ir = compile(doc);
+  const runner = new YarnRunner(ir, { startAt: "Start" });
+
+  runner.advance(); // move to options
+  const result = runner.currentResult;
+  ok(result && result.type === "options", "Expected options result");
+  const options = result!.options;
+  ok(options[0].markup, "Expected markup on first option");
+  ok(options[1].markup, "Expected markup on second option");
+  const boldMarkup = options[0].markup!;
+  strictEqual(boldMarkup.text, "Bold");
+  ok(
+    boldMarkup.segments.some((segment) =>
+      segment.wrappers.some((wrapper) => wrapper.name === "b" && wrapper.type === "default")
+    ),
+    "Expected bold wrapper"
+  );
+  const customWrapper = options[1].markup!.segments
+    .flatMap((segment) => segment.wrappers)
+    .find((wrapper) => wrapper.name === "wave");
+  ok(customWrapper, "Expected custom wrapper on second option");
+  strictEqual(customWrapper!.properties.intensity, 5);
+});

package/src/tests/story_end.test.ts

@@ -0,0 +1,42 @@
+import { test } from "node:test";
+import { ok, strictEqual } from "node:assert";
+import { parseYarn, compile, YarnRunner } from "../index.js";
+
+test("onStoryEnd receives variables snapshot", () => {
+  const script = `
+title: Start
+---
+Narrator: Beginning
+<<set $score = 42>>
+Narrator: Done
+===
+`;
+  let payload: { variables: Readonly<Record<string, unknown>>; storyEnd: true } | undefined;
+  const doc = parseYarn(script);
+  const ir = compile(doc);
+  const runner = new YarnRunner(ir, {
+    startAt: "Start",
+    onStoryEnd: (info) => {
+      payload = info;
+    },
+  });
+
+  let result = runner.currentResult;
+  ok(result && result.type === "text");
+
+  runner.advance();
+  result = runner.currentResult;
+  ok(result && result.type === "command");
+
+  runner.advance();
+  result = runner.currentResult;
+  ok(result && result.type === "text");
+
+  runner.advance();
+  result = runner.currentResult;
+  ok(result && result.isDialogueEnd === true);
+
+  strictEqual(payload?.storyEnd, true);
+  const variables = payload?.variables ?? {};
+  strictEqual((variables as Record<string, unknown>)["score"], 42);
+});