yarn-spinner-runner-ts 0.1.4 → 0.1.5

package/src/react/useYarnRunner.tsx

@@ -1,35 +1,102 @@
-import { useState, useCallback, useRef } from "react";
-import { YarnRunner, type RunnerOptions } from "../runtime/runner.js";
-import type { IRProgram } from "../compile/ir.js";
-import type { RuntimeResult } from "../runtime/results.js";
-
-export function useYarnRunner(
-  program: IRProgram,
-  options: RunnerOptions
-): {
-  result: RuntimeResult | null;
-  advance: (optionIndex?: number) => void;
-  runner: YarnRunner;
-} {
-  const runnerRef = useRef<YarnRunner | null>(null);
-  const [result, setResult] = useState<RuntimeResult | null>(null);
-
-  // Initialize runner only once
-  if (!runnerRef.current) {
-    runnerRef.current = new YarnRunner(program, options);
-    setResult(runnerRef.current.currentResult);
-  }
-
-  const runner = runnerRef.current;
-
-  const advance = useCallback(
-    (optionIndex?: number) => {
-      runner.advance(optionIndex);
-      setResult(runner.currentResult);
-    },
-    [runner]
-  );
-
-  return { result, advance, runner };
-}
+import { useState, useCallback, useRef, useEffect } from "react";
+import { YarnRunner, type RunnerOptions } from "../runtime/runner.js";
+import type { IRProgram } from "../compile/ir.js";
+import type { RuntimeResult } from "../runtime/results.js";
+
+function haveFunctionsChanged(
+  prev: RunnerOptions["functions"],
+  next: RunnerOptions["functions"]
+): boolean {
+  const prevFns = prev ?? {};
+  const nextFns = next ?? {};
+
+  const prevKeys = Object.keys(prevFns);
+  const nextKeys = Object.keys(nextFns);
+
+  if (prevKeys.length !== nextKeys.length) {
+    return true;
+  }
+
+  for (const key of prevKeys) {
+    if (!Object.prototype.hasOwnProperty.call(nextFns, key) || prevFns[key] !== nextFns[key]) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function haveVariablesChanged(
+  prev: RunnerOptions["variables"],
+  next: RunnerOptions["variables"]
+): boolean {
+  const prevVars = prev ?? {};
+  const nextVars = next ?? {};
+  return JSON.stringify(prevVars) !== JSON.stringify(nextVars);
+}
+
+export function useYarnRunner(
+  program: IRProgram,
+  options: RunnerOptions
+): {
+  result: RuntimeResult | null;
+  advance: (optionIndex?: number) => void;
+  runner: YarnRunner;
+} {
+  const runnerRef = useRef<YarnRunner | null>(null);
+  const optionsRef = useRef(options);
+  const programRef = useRef(program);
+  const [result, setResult] = useState<RuntimeResult | null>(() => {
+    const runner = new YarnRunner(program, options);
+    runnerRef.current = runner;
+    optionsRef.current = options;
+    programRef.current = program;
+    return runner.currentResult;
+  });
+
+  useEffect(() => {
+    const prevProgram = programRef.current;
+    const prevOptions = optionsRef.current;
+
+    const programChanged = prevProgram !== program;
+    const functionsChanged = haveFunctionsChanged(prevOptions?.functions, options.functions);
+    const startNodeChanged = prevOptions?.startAt !== options.startAt;
+    const variablesChanged = haveVariablesChanged(prevOptions?.variables, options.variables);
+    const handlersChanged =
+      prevOptions?.handleCommand !== options.handleCommand ||
+      prevOptions?.commandHandler !== options.commandHandler ||
+      prevOptions?.onStoryEnd !== options.onStoryEnd;
+
+    if (
+      !runnerRef.current ||
+      programChanged ||
+      functionsChanged ||
+      startNodeChanged ||
+      variablesChanged ||
+      handlersChanged
+    ) {
+      const runner = new YarnRunner(program, options);
+      runnerRef.current = runner;
+      setResult(runner.currentResult);
+    }
+
+    programRef.current = program;
+    optionsRef.current = options;
+  }, [program, options]);
+
+  const advance = useCallback((optionIndex?: number) => {
+    const runner = runnerRef.current;
+    if (!runner) {
+      return;
+    }
+    runner.advance(optionIndex);
+    setResult(runner.currentResult);
+  }, []);
+
+  return {
+    result,
+    advance,
+    runner: runnerRef.current as YarnRunner,
+  };
+}
 

package/src/runtime/evaluator.ts

@@ -110,20 +110,21 @@ export class ExpressionEvaluator {
 
   private evaluateComparison(expr: string): boolean {
     // Match comparison operators (avoid matching !=, <=, >=)
-    const match = expr.match(/^(.+?)\s*(===|!==|<=|>=|<|>)\s*(.+)$/);
-    if (!match) throw new Error(`Invalid comparison: ${expr}`);
-
-    const [, left, op, right] = match;
-    const leftVal = this.evaluateExpression(left.trim());
-    const rightVal = this.evaluateExpression(right.trim());
-
-    switch (op) {
-      case "===":
-      case "==":
-        return this.deepEquals(leftVal, rightVal);
-      case "!==":
-      case "!=":
-        return !this.deepEquals(leftVal, rightVal);
+    const match = expr.match(/^(.+?)\s*(===|==|!==|!=|=|<=|>=|<|>)\s*(.+)$/);
+    if (!match) throw new Error(`Invalid comparison: ${expr}`);
+
+    const [, left, rawOp, right] = match;
+    const op = rawOp === "=" ? "==" : rawOp;
+    const leftVal = this.evaluateExpression(left.trim());
+    const rightVal = this.evaluateExpression(right.trim());
+
+    switch (op) {
+      case "===":
+      case "==":
+        return this.deepEquals(leftVal, rightVal);
+      case "!==":
+      case "!=":
+        return !this.deepEquals(leftVal, rightVal);
       case "<":
         return Number(leftVal) < Number(rightVal);
       case ">":

package/src/runtime/runner.ts

@@ -1,4 +1,4 @@
-import type { IRProgram, IRInstruction, IRNode, IRNodeGroup } from "../compile/ir";
+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";
@@ -16,7 +16,16 @@ export interface RunnerOptions {
 const globalOnceSeen = new Set<string>();
 const globalNodeGroupOnceSeen = new Set<string>(); // Track "once" nodes in groups: "title#index"
 
-export class YarnRunner {
+type CompiledOption = {
+  text: string;
+  tags?: string[];
+  css?: string;
+  markup?: MarkupParseResult;
+  condition?: string;
+  block: IRInstruction[];
+};
+
+export class YarnRunner {
   private readonly program: IRProgram;
   private readonly variables: Record<string, unknown>;
   private readonly functions: Record<string, (...args: unknown[]) => unknown>;
@@ -27,7 +36,8 @@ export class YarnRunner {
   private readonly onStoryEnd?: RunnerOptions["onStoryEnd"];
   private storyEnded = false;
   private readonly nodeGroupOnceSeen = globalNodeGroupOnceSeen;
-  private readonly visitCounts: Record<string, number> = {};
+  private readonly visitCounts: Record<string, number> = {};
+  private pendingOptions: CompiledOption[] | null = null;
 
   private nodeTitle: string;
   private ip = 0; // instruction pointer within node
@@ -189,22 +199,20 @@ export class YarnRunner {
     this.nodeGroupOnceSeen.add(onceKey);
   }
 
-  advance(optionIndex?: number) {
-    // If awaiting option selection, consume chosen option by pushing its block
-    if (this.currentResult?.type === "options") {
-      if (optionIndex == null) throw new Error("Option index required");
-      // Resolve to actual node (handles groups)
-      const node = this.resolveNode(this.nodeTitle);
-      // We encoded options at ip-1; locate it
-      const ins = node.instructions[this.ip - 1];
-      if (ins?.op !== "options") throw new Error("Invalid options state");
-      const chosen = ins.options[optionIndex];
-      if (!chosen) throw new Error("Invalid option index");
-      // Push a block frame that we will resume across advances
-      this.callStack.push({ kind: "block", title: this.nodeTitle, ip: this.ip, block: chosen.block, idx: 0 });
-      if (this.resumeBlock()) return;
-      return;
-    }
+  advance(optionIndex?: number) {
+    // If awaiting option selection, consume chosen option by pushing its block
+    if (this.currentResult?.type === "options") {
+      if (optionIndex == null) throw new Error("Option index required");
+      const options = this.pendingOptions;
+      if (!options) throw new Error("Invalid options state");
+      const chosen = options[optionIndex];
+      if (!chosen) throw new Error("Invalid option index");
+      // Push a block frame that we will resume across advances
+      this.callStack.push({ kind: "block", title: this.nodeTitle, ip: this.ip, block: chosen.block, idx: 0 });
+      this.pendingOptions = null;
+      if (this.resumeBlock()) return;
+      return;
+    }
     // If we have a pending block, resume it first
     if (this.resumeBlock()) return;
     this.step();
@@ -387,10 +395,22 @@ export class YarnRunner {
           this.emit({ type: "command", command: ins.content, isDialogueEnd: false });
           return true;
         }
-        case "options": {
-          this.emit({ type: "options", options: ins.options.map((o) => ({ text: o.text, tags: o.tags, markup: o.markup })), isDialogueEnd: false });
-          return true;
-        }
+        case "options": {
+          const available = this.filterOptions(ins.options);
+          if (available.length === 0) {
+            continue;
+          }
+          this.pendingOptions = available;
+          this.emit({
+            type: "options",
+            options: available.map((o) => {
+              const { text: interpolatedText, markup: interpolatedMarkup } = this.interpolate(o.text, o.markup);
+              return { text: interpolatedText, tags: o.tags, markup: interpolatedMarkup };
+            }),
+            isDialogueEnd: false,
+          });
+          return true;
+        }
         case "if": {
           const branch = ins.branches.find((b) => (b.condition ? this.evaluator.evaluate(b.condition) : true));
           if (branch) {
@@ -472,10 +492,24 @@ export class YarnRunner {
           // resolveNode will handle node groups
           continue;
         }
-        case "options": {
-          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 "options": {
+          const available = this.filterOptions(ins.options);
+          if (available.length === 0) {
+            continue;
+          }
+          this.pendingOptions = available;
+          this.emit({
+            type: "options",
+            options: available.map((o) => {
+              const { text: interpolatedText, markup: interpolatedMarkup } = this.interpolate(o.text, o.markup);
+              return { text: interpolatedText, tags: o.tags, css: o.css, markup: interpolatedMarkup };
+            }),
+            nodeCss: resolved.css,
+            scene: resolved.scene,
+            isDialogueEnd: this.lookaheadIsEnd(),
+          });
+          return;
+        }
         case "if": {
           const branch = ins.branches.find((b: { condition: string | null; block: IRInstruction[] }) => (b.condition ? this.evaluator.evaluate(b.condition) : true));
           if (branch) {
@@ -531,11 +565,24 @@ export class YarnRunner {
           this.emit({ type: "command", command: ins.content, isDialogueEnd: false });
           restore();
           return;
-        case "options":
-          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;
+        case "options": {
+          const available = this.filterOptions(ins.options);
+          if (available.length === 0) {
+            continue;
+          }
+          this.pendingOptions = available;
+          this.emit({
+            type: "options",
+            options: available.map((o) => {
+              const { text: interpolatedText, markup: interpolatedMarkup } = this.interpolate(o.text, o.markup);
+              return { text: interpolatedText, markup: interpolatedMarkup };
+            }),
+            isDialogueEnd: false,
+          });
+          // Maintain context that options belong to main node at ip-1
+          restore();
+          return;
+        }
         case "if": {
           const branch = ins.branches.find((b) => (b.condition ? this.evaluator.evaluate(b.condition) : true));
           if (branch) {
@@ -572,11 +619,29 @@ export class YarnRunner {
         }
       }
     }
-    // Block produced no output; resume
-    restore();
-    this.step();
-  }
-
+    // Block produced no output; resume
+    restore();
+    this.step();
+  }
+
+  private filterOptions(options: CompiledOption[]): CompiledOption[] {
+    const available: CompiledOption[] = [];
+    for (const option of options) {
+      if (!option.condition) {
+        available.push(option);
+        continue;
+      }
+      try {
+        if (this.evaluator.evaluate(option.condition)) {
+          available.push(option);
+        }
+      } catch {
+        // Treat errors as false conditions
+      }
+    }
+    return available;
+  }
+
   private lookaheadIsEnd(): boolean {
     // Check if current node has more emit-worthy instructions
     const node = this.resolveNode(this.nodeTitle);

package/src/tests/dialogue_view.test.tsx

@@ -0,0 +1,26 @@
+import { test } from "node:test";
+import { ok } from "node:assert";
+import React from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { parseYarn } from "../parse/parser.js";
+import { compile } from "../compile/compiler.js";
+import { DialogueView } from "../react/DialogueView.js";
+
+test("DialogueView renders initial variables provided via props", () => {
+  const yarn = `
+title: Start
+---
+Narrator: Hello {$playerName}!
+===`;
+
+  const program = compile(parseYarn(yarn));
+
+  const html = renderToStaticMarkup(
+    <DialogueView program={program} startNode="Start" variables={{ playerName: "V" }} />
+  );
+
+  ok(
+    html.includes("Hello V"),
+    "Expected rendered dialogue to include the interpolated variable value from props"
+  );
+});

package/src/tests/markup.test.ts

@@ -43,6 +43,23 @@ test("parseMarkup handles self-closing tags", () => {
   );
 });
 
+test("parseMarkup handles br line breaks", () => {
+  const result = parseMarkup("Line one[br]Line two[/br][br/]Line three");
+  strictEqual(result.text, "Line oneLine twoLine three");
+
+  const brSegments = result.segments.filter(
+    (segment) => segment.selfClosing && segment.wrappers.some((wrapper) => wrapper.name === "br")
+  );
+
+  strictEqual(brSegments.length, 2);
+  ok(
+    brSegments.every((segment) =>
+      segment.wrappers.some((wrapper) => wrapper.name === "br" && wrapper.type === "default")
+    ),
+    "Expected br wrappers to use default HTML type"
+  );
+});
+
 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]");
@@ -59,4 +76,3 @@ function findSegment(result: MarkupParseResult, target: string) {
     return text === target;
   });
 }
-

package/src/tests/options.test.ts

@@ -34,39 +34,209 @@ 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);
-});
+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);
+});
+
+test("option text interpolates variables", () => {
+  const script = `
+title: Start
+---
+<<set $cost to 150>>
+<<set $bribe to 300>>
+Narrator: Decide
+-> Pay {$cost}
+    Narrator: Paid
+ -> Haggle {$bribe}
+    Narrator: Haggle
+===
+`;
+
+  const doc = parseYarn(script);
+  const ir = compile(doc);
+  const runner = new YarnRunner(ir, { startAt: "Start" });
+
+  // First result is command for set
+  const initial = runner.currentResult;
+  strictEqual(initial?.type, "command", "Expected first <<set>> to emit a command result");
+  runner.advance(); // second <<set>> command
+  runner.advance(); // move to narration
+  runner.advance(); // move to options
+
+  const result = runner.currentResult;
+  if (!result || result.type !== "options") {
+    throw new Error("Expected to land on options");
+  }
+  const [pay, haggle] = result.options;
+  strictEqual(pay.text, "Pay 150", "Should replace placeholder with variable value");
+  strictEqual(haggle.text, "Haggle 300", "Should evaluate expressions inside placeholders");
+});
+
+test("conditional options respect once blocks and if statements", () => {
+  const script = `
+title: Start
+---
+<<declare $secret = false>>
+Narrator: Boot
+<<once>>
+    <<set $secret = true>>
+<<endonce>>
+Narrator: Menu
+<<if $secret>>
+    -> Secret Option
+        Narrator: Secret taken
+        <<set $secret = false>>
+        <<jump Start>>
+<<endif>>
+-> Regular Option
+    Narrator: Regular taken
+    <<jump Start>>
+===
+`;
+
+  const doc = parseYarn(script);
+  const ir = compile(doc);
+  const runner = new YarnRunner(ir, { startAt: "Start" });
+
+  const nextOptions = () => {
+    let guard = 25;
+    while (guard-- > 0) {
+      const result = runner.currentResult;
+      if (!result) throw new Error("Expected runtime result");
+      if (result.type === "options") {
+        return result;
+      }
+      runner.advance();
+    }
+    throw new Error("Failed to reach options result");
+  };
+
+  const secretMenu = nextOptions();
+  strictEqual(secretMenu.options.length, 1, "First pass should expose the conditional secret option");
+  strictEqual(secretMenu.options[0].text, "Secret Option");
+
+  // Consume the secret option to flip the flag off
+  runner.advance(0);
+
+  const fallbackMenu = nextOptions();
+  strictEqual(fallbackMenu.options.length, 1, "After the secret path is used, only the regular option should remain");
+  strictEqual(fallbackMenu.options[0].text, "Regular Option");
+});
+
+test("options allow space-indented bodies", () => {
+  const script = `
+title: Start
+---
+-> Pay
+  <<jump Pay>>
+-> Run
+  <<jump Run>>
+===
+
+title: Pay
+---
+Narrator: Pay branch
+===
+
+title: Run
+---
+Narrator: Run branch
+===
+`;
+
+  const doc = parseYarn(script);
+  const ir = compile(doc);
+  const runner = new YarnRunner(ir, { startAt: "Start" });
+
+  const initial = runner.currentResult;
+  if (initial?.type !== "options") {
+    runner.advance();
+  }
+  const optionsResult = runner.currentResult;
+  strictEqual(optionsResult?.type, "options", "Expected to reach options");
+  if (optionsResult?.type !== "options") throw new Error("Options not emitted");
+  strictEqual(optionsResult.options.length, 2, "Space indents should still group options together");
+  strictEqual(optionsResult.options[0].text, "Pay");
+  strictEqual(optionsResult.options[1].text, "Run");
+});
+
+test("inline [if] option condition filters options", () => {
+  const script = `
+title: StartFalse
+---
+<<declare $flag = false>>
+-> Hidden [if $flag]
+    Narrator: Hidden
+-> Visible
+    Narrator: Visible
+===
+
+title: StartTrue
+---
+<<declare $flag = true>>
+-> Hidden [if $flag]
+    Narrator: Hidden
+-> Visible
+    Narrator: Visible
+===
+`;
+
+  const doc = parseYarn(script);
+  const ir = compile(doc);
+
+  const getOptions = (startNode: string) => {
+    const runner = new YarnRunner(ir, { startAt: startNode });
+    let guard = 25;
+    while (guard-- > 0) {
+      const result = runner.currentResult;
+      if (!result) break;
+      if (result.type === "options") {
+        return { runner, options: result };
+      }
+      runner.advance();
+    }
+    throw new Error("Failed to reach options");
+  };
+
+  const { options: optionsFalse } = getOptions("StartFalse");
+  strictEqual(optionsFalse.options.length, 1, "Hidden option should be filtered out when condition is false");
+  strictEqual(optionsFalse.options[0].text, "Visible");
+
+  const { options: optionsTrue } = getOptions("StartTrue");
+  strictEqual(optionsTrue.options.length, 2, "Both options should appear when condition is true");
+  strictEqual(optionsTrue.options[0].text, "Hidden");
+  strictEqual(optionsTrue.options[1].text, "Visible");
+});