yarn-spinner-runner-ts 0.1.0

package/dist/tests/index.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.js","sourceRoot":"","sources":["../../src/tests/index.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE7D,IAAI,CAAC,6BAA6B,EAAE,GAAG,EAAE;IACvC,MAAM,QAAQ,GAAG;;;;;;;;;CASlB,CAAC;IAEA,MAAM,GAAG,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;IAChC,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACxB,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;IAExD,MAAM,EAAE,GAAG,MAAM,CAAC,aAAc,CAAC;IACjC,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC7B,MAAM,CAAC,OAAO,EAAE,CAAC;IACjB,MAAM,EAAE,GAAG,MAAM,CAAC,aAAc,CAAC;IACjC,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAChC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAClB,MAAM,EAAE,GAAG,MAAM,CAAC,aAAc,CAAC;IACjC,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC7B,IAAI,EAAE,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QACvB,WAAW,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,IAAI,CAAC,CAAC;IAClD,CAAC;AACH,CAAC,CAAC,CAAC"}

package/dist/tests/jump_detour.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/jump_detour.test.js

@@ -0,0 +1,47 @@
+import { test } from "node:test";
+import { strictEqual } from "node:assert";
+import { parseYarn, compile, YarnRunner } from "../index.js";
+test("jump and detour", () => {
+    const script = `
+title: Start
+---
+Narrator: Go to Next
+<<jump Next>>
+===
+
+title: Next
+---
+Narrator: In Next
+<<detour Aside>>
+Narrator: Back from Aside
+===
+
+title: Aside
+---
+Narrator: Inside Aside
+===
+`;
+    const doc = parseYarn(script);
+    const ir = compile(doc);
+    const runner = new YarnRunner(ir, { startAt: "Start" });
+    const a = runner.currentResult;
+    strictEqual(a.type, "text");
+    if (a.type === "text")
+        strictEqual(/Go to Next/.test(a.text), true, "Expect first line");
+    runner.advance(); // executes jump, should produce Next's first line
+    const b = runner.currentResult;
+    strictEqual(b.type, "text");
+    if (b.type === "text")
+        strictEqual(/In Next/.test(b.text), true, "Expect Next node line");
+    runner.advance(); // should detour into Aside and emit its first line
+    const c = runner.currentResult;
+    strictEqual(c.type, "text");
+    if (c.type === "text")
+        strictEqual(/Inside Aside/.test(c.text), true, "Expect detour content");
+    runner.advance(); // should return from detour and continue
+    const d = runner.currentResult;
+    strictEqual(d.type, "text");
+    if (d.type === "text")
+        strictEqual(/Back from Aside/.test(d.text), true, "Expect return from detour");
+});
+//# sourceMappingURL=jump_detour.test.js.map

package/dist/tests/jump_detour.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jump_detour.test.js","sourceRoot":"","sources":["../../src/tests/jump_detour.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE7D,IAAI,CAAC,iBAAiB,EAAE,GAAG,EAAE;IAC3B,MAAM,MAAM,GAAG;;;;;;;;;;;;;;;;;;CAkBhB,CAAC;IAEA,MAAM,GAAG,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;IAC9B,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACxB,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;IAExD,MAAM,CAAC,GAAG,MAAM,CAAC,aAAc,CAAC;IAChC,WAAW,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC5B,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM;QAAE,WAAW,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,mBAAmB,CAAC,CAAC;IACzF,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,kDAAkD;IACpE,MAAM,CAAC,GAAG,MAAM,CAAC,aAAc,CAAC;IAChC,WAAW,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC5B,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM;QAAE,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,uBAAuB,CAAC,CAAC;IAC1F,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,mDAAmD;IACrE,MAAM,CAAC,GAAG,MAAM,CAAC,aAAc,CAAC;IAChC,WAAW,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC5B,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM;QAAE,WAAW,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,uBAAuB,CAAC,CAAC;IAC/F,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,yCAAyC;IAC3D,MAAM,CAAC,GAAG,MAAM,CAAC,aAAc,CAAC;IAChC,WAAW,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC5B,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM;QAAE,WAAW,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,2BAA2B,CAAC,CAAC;AACxG,CAAC,CAAC,CAAC"}

package/dist/tests/nodes_lines.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/nodes_lines.test.js

@@ -0,0 +1,23 @@
+import { test } from "node:test";
+import { strictEqual } from "node:assert";
+import { parseYarn, compile, YarnRunner } from "../index.js";
+test("nodes and lines delivery", () => {
+    const script = `
+title: Start
+---
+Narrator: Line one
+Narrator: Line two
+===
+`;
+    const doc = parseYarn(script);
+    const ir = compile(doc);
+    const runner = new YarnRunner(ir, { startAt: "Start" });
+    strictEqual(runner.currentResult?.type, "text", "Expected first result to be text");
+    strictEqual(runner.currentResult?.text.includes("Line one"), true, "Expected 'Line one'");
+    runner.advance();
+    strictEqual(runner.currentResult?.type, "text", "Should still be text");
+    strictEqual(runner.currentResult?.text.includes("Line two"), true, "Expected 'Line two'");
+    runner.advance();
+    strictEqual(runner.currentResult?.isDialogueEnd, true, "Expected dialogue end after lines");
+});
+//# sourceMappingURL=nodes_lines.test.js.map

package/dist/tests/nodes_lines.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodes_lines.test.js","sourceRoot":"","sources":["../../src/tests/nodes_lines.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE7D,IAAI,CAAC,0BAA0B,EAAE,GAAG,EAAE;IACpC,MAAM,MAAM,GAAG;;;;;;CAMhB,CAAC;IAEA,MAAM,GAAG,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;IAC9B,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACxB,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;IAExD,WAAW,CAAC,MAAM,CAAC,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,kCAAkC,CAAC,CAAC;IACpF,WAAW,CAAC,MAAM,CAAC,aAAa,EAAE,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,qBAAqB,CAAC,CAAC;IAC1F,MAAM,CAAC,OAAO,EAAE,CAAC;IACjB,WAAW,CAAC,MAAM,CAAC,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,sBAAsB,CAAC,CAAC;IACxE,WAAW,CAAC,MAAM,CAAC,aAAa,EAAE,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,qBAAqB,CAAC,CAAC;IAC1F,MAAM,CAAC,OAAO,EAAE,CAAC;IACjB,WAAW,CAAC,MAAM,CAAC,aAAa,EAAE,aAAa,EAAE,IAAI,EAAE,mCAAmC,CAAC,CAAC;AAC9F,CAAC,CAAC,CAAC"}

package/dist/tests/once.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/once.test.js

@@ -0,0 +1,29 @@
+import { test } from "node:test";
+import { strictEqual } from "node:assert";
+import { parseYarn, compile, YarnRunner } from "../index.js";
+test("once block behavior", () => {
+    const script = `
+title: Start
+---
+<<once>>
+    Narrator: One time only
+<<endonce>>
+Narrator: Always
+===
+`;
+    const doc = parseYarn(script);
+    const ir = compile(doc);
+    // First run
+    let runner = new YarnRunner(ir, { startAt: "Start" });
+    const a = runner.currentResult;
+    strictEqual(a.type, "text");
+    if (a.type === "text")
+        strictEqual(/One time only/.test(a.text), true, "Expect once block content on first run");
+    runner.advance();
+    const b = runner.currentResult;
+    strictEqual(b.type, "text");
+    if (b.type === "text")
+        strictEqual(/Always/.test(b.text), true, "Expect always line after once");
+    // Note: persistence of once across sessions depends on integration; not asserting second run behavior here.
+});
+//# sourceMappingURL=once.test.js.map

package/dist/tests/once.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"once.test.js","sourceRoot":"","sources":["../../src/tests/once.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE7D,IAAI,CAAC,qBAAqB,EAAE,GAAG,EAAE;IAC/B,MAAM,MAAM,GAAG;;;;;;;;CAQhB,CAAC;IAEA,MAAM,GAAG,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;IAC9B,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAExB,YAAY;IACZ,IAAI,MAAM,GAAG,IAAI,UAAU,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;IACtD,MAAM,CAAC,GAAG,MAAM,CAAC,aAAc,CAAC;IAChC,WAAW,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC5B,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM;QAAE,WAAW,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,wCAAwC,CAAC,CAAC;IACjH,MAAM,CAAC,OAAO,EAAE,CAAC;IACjB,MAAM,CAAC,GAAG,MAAM,CAAC,aAAc,CAAC;IAChC,WAAW,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC5B,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM;QAAE,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,+BAA+B,CAAC,CAAC;IAEjG,4GAA4G;AAC9G,CAAC,CAAC,CAAC"}

package/dist/tests/options.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/options.test.js

@@ -0,0 +1,32 @@
+import { test } from "node:test";
+import { strictEqual } from "node:assert";
+import { parseYarn, compile, YarnRunner } from "../index.js";
+test("options selection", () => {
+    const script = `
+title: Start
+---
+Narrator: Choose one
+-> A
+    Narrator: Picked A
+-> B
+    Narrator: Picked B
+===
+`;
+    const doc = parseYarn(script);
+    const ir = compile(doc);
+    const runner = new YarnRunner(ir, { startAt: "Start" });
+    const a = runner.currentResult;
+    strictEqual(a.type, "text", "Expected intro text");
+    runner.advance();
+    const b = runner.currentResult;
+    strictEqual(b.type, "options", "Expected options after intro");
+    if (b.type === "options")
+        strictEqual(b.options.length, 2, "Should have 2 options");
+    // choose B (index 1)
+    runner.advance(1);
+    const c = runner.currentResult;
+    strictEqual(c.type, "text", "Should be text after selection");
+    if (c.type === "text")
+        strictEqual(c.text.includes("Picked B"), true, "Expected body of option B");
+});
+//# sourceMappingURL=options.test.js.map

package/dist/tests/options.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.test.js","sourceRoot":"","sources":["../../src/tests/options.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE7D,IAAI,CAAC,mBAAmB,EAAE,GAAG,EAAE;IAC7B,MAAM,MAAM,GAAG;;;;;;;;;CAShB,CAAC;IAEA,MAAM,GAAG,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;IAC9B,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACxB,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;IAExD,MAAM,CAAC,GAAG,MAAM,CAAC,aAAc,CAAC;IAChC,WAAW,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,qBAAqB,CAAC,CAAC;IACnD,MAAM,CAAC,OAAO,EAAE,CAAC;IACjB,MAAM,CAAC,GAAG,MAAM,CAAC,aAAc,CAAC;IAChC,WAAW,CAAC,CAAC,CAAC,IAAI,EAAE,SAAS,EAAE,8BAA8B,CAAC,CAAC;IAC/D,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS;QAAE,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,uBAAuB,CAAC,CAAC;IACpF,qBAAqB;IACrB,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAClB,MAAM,CAAC,GAAG,MAAM,CAAC,aAAc,CAAC;IAChC,WAAW,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,gCAAgC,CAAC,CAAC;IAC9D,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM;QAAE,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,2BAA2B,CAAC,CAAC;AACrG,CAAC,CAAC,CAAC"}

package/dist/tests/variables_flow_cmds.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/variables_flow_cmds.test.js

@@ -0,0 +1,30 @@
+import { test } from "node:test";
+import { strictEqual } from "node:assert";
+import { parseYarn, compile, YarnRunner } from "../index.js";
+test("variables, flow control, and commands", () => {
+    const script = `
+title: Start
+---
+<<set $score to 10>>
+<<if $score >= 10>>
+    Narrator: High
+<<else>>
+    Narrator: Low
+<<endif>>
+===
+`;
+    const doc = parseYarn(script);
+    const ir = compile(doc);
+    const runner = new YarnRunner(ir, { startAt: "Start" });
+    // After command, expect if-branch 'High'
+    // First result should be command emission
+    const a = runner.currentResult;
+    strictEqual(a.type, "command", "First result should be command");
+    runner.advance();
+    const b = runner.currentResult;
+    strictEqual(b.type, "text", "Should be text after command");
+    if (b.type === "text")
+        strictEqual(/High/.test(b.text), true, "Expected High branch");
+    strictEqual(runner.getVariable("score"), 10, "Variable should be set");
+});
+//# sourceMappingURL=variables_flow_cmds.test.js.map

package/dist/tests/variables_flow_cmds.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"variables_flow_cmds.test.js","sourceRoot":"","sources":["../../src/tests/variables_flow_cmds.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE7D,IAAI,CAAC,uCAAuC,EAAE,GAAG,EAAE;IACjD,MAAM,MAAM,GAAG;;;;;;;;;;CAUhB,CAAC;IAEA,MAAM,GAAG,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;IAC9B,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACxB,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;IAExD,yCAAyC;IACzC,0CAA0C;IAC1C,MAAM,CAAC,GAAG,MAAM,CAAC,aAAc,CAAC;IAChC,WAAW,CAAC,CAAC,CAAC,IAAI,EAAE,SAAS,EAAE,gCAAgC,CAAC,CAAC;IACjE,MAAM,CAAC,OAAO,EAAE,CAAC;IACjB,MAAM,CAAC,GAAG,MAAM,CAAC,aAAc,CAAC;IAChC,WAAW,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,8BAA8B,CAAC,CAAC;IAC5D,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM;QAAE,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,sBAAsB,CAAC,CAAC;IACtF,WAAW,CAAC,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,EAAE,EAAE,wBAAwB,CAAC,CAAC;AACzE,CAAC,CAAC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,3 @@
+export type { YarnDocument, YarnNode, Statement, Line, Command, OptionGroup, Option, IfBlock, OnceBlock, Jump, Detour } from "./model/ast";
+export type { IRProgram, IRNode, IRInstruction } from "./compile/ir";
+export type { RuntimeResult, TextResult, OptionsResult, CommandResult } from "./runtime/results";

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/docs/commands.md

@@ -0,0 +1,21 @@
+## Commands (Yarn Spinner)
+
+Source: [docs.yarnspinner.dev — Commands](https://docs.yarnspinner.dev/write-yarn-scripts/scripting-fundamentals/commands)
+
+### What it covers
+- Inline instructions to the host game/engine using `<<command ...>>`.
+- Often used to trigger animations, SFX, gameplay events, or state changes.
+
+### Examples
+```yarn
+title: Start
+---
+Narrator: Opening the door.
+<<play_sfx name="door_open">>
+<<animate target="Door" action="Open">>
+===
+```
+
+Exact command names and parameters are defined by your game integration.
+
+

package/docs/compatibility-checklist.md

@@ -0,0 +1,77 @@
+# Yarn Spinner Compatibility Checklist
+
+This document tracks compatibility with the official Yarn Spinner documentation.
+
+## ✅ Implemented Features
+
+### Variables
+- ✅ Variable storage (numbers, strings, booleans)
+- ✅ `<<set>>` command
+- ✅ Basic operators: `==`, `!=`, `>`, `<`, `<=`, `>=`, `&&`, `||`, `!`
+- ✅ Variable usage in condition expressions
+- ✅ Implicit variable declaration (when not declared, defaults to 0/false/"")
+
+### Flow Control
+- ✅ `{if condition}...{endif}` blocks (using `{if}` syntax instead of `<<if>>`)
+- ✅ `{else if condition}` branches
+- ✅ `{else}` branches
+- ✅ Condition evaluation in if/elseif
+
+## ❌ Missing Features
+
+### Variables
+1. **`<<declare>>` command** - Not implemented
+   - Docs: `<<declare $playerName = "Reginald the Wizard">>`
+   - Status: Missing
+
+2. **Variable substitution in lines** - Not implemented
+   - Docs: `The value is {$variableName}.`
+   - Status: Variables are stored but not substituted into line text at runtime
+
+3. **`<<set>>` with `to` keyword** - Partially supported
+   - Docs: `<<set $greeting to "Hello, Yarn!">>`
+   - Status: Currently supports `<<set var value>>` or `<<set var = value>>`, but not `to` keyword
+
+4. **Math expressions in `<<set>>`** - Partially supported
+   - Docs: `<<set $x = 2 + 1>>`
+   - Status: Value is parsed but expressions aren't evaluated (e.g., `"2 + 1"` stored as string, not `3`)
+
+5. **Additional operator aliases** - Missing
+   - Docs support: `eq`, `is`, `neq`, `gt`, `lt`, `lte`, `gte`, `xor`, `not`, `and`, `or`
+   - Status: We support: `==`, `!=`, `>`, `<`, `<=`, `>=`, `&&`, `||`, `!`
+   - Missing: `eq`, `is`, `neq`, `gt`, `lt`, `lte`, `gte`, `xor`, `not`, `and`, `or` aliases
+
+6. **Type conversion functions** - Not implemented
+   - Docs: `string()`, `number()`, `bool()` functions
+   - Status: Missing
+
+7. **`$` prefix for variables** - Not enforced
+   - Docs: Variables should start with `$` (e.g., `$gold`)
+   - Status: We accept variables without `$` prefix
+
+### Flow Control
+8. **Conditional options** - Not implemented
+   - Docs: `-> Option text <<if $reputation > 10>>`
+   - Status: Options can't have conditions attached
+
+9. **`<<if>>` command blocks** - Different syntax
+   - Docs: `<<if condition>>...<<endif>>`
+   - Status: We use `{if condition}...{endif}` (inline markup) instead
+   - Note: This is a valid alternative syntax, just different from docs
+
+## Recommendations
+
+To improve compatibility, consider implementing:
+
+1. **Variable substitution** (`{$var}`) - High priority
+2. **Math expressions in `<<set>>`** - High priority
+3. **Conditional options** - Medium priority
+4. **`<<declare>>` command** - Medium priority
+5. **Operator aliases** (`eq`, `gt`, etc.) - Low priority
+6. **Type conversion functions** - Low priority
+
+## Syntax Differences
+
+- **If blocks**: We use `{if}...{endif}` instead of `<<if>>...<<endif>>`
+  - This is valid Yarn syntax, just a different style
+

package/docs/css-attribute.md

@@ -0,0 +1,47 @@
+## Custom CSS Attribute (&css{})
+
+This project adds a custom `&css{}` attribute to Yarn scripts to carry UI styles to consumers (e.g., React components).
+
+### Node-level CSS
+
+Attach a CSS block to a node header value by starting it with `&css{` and closing it with `}`. The block may span multiple lines until the closing brace, and must appear before the `---` line.
+
+```yarn
+title: Scene2
+style: &css{
+  backgroundColor: red;
+  color: white;
+  fontFamily: "Arial", sans-serif;
+}
+---
+Narrator: Hello!
+===
+```
+
+Parsed into `YarnNode.css` and propagated to IR (`IRNode.css`).
+
+### Option-level CSS (inline)
+
+Append an inline `&css{...}` to an option text to style that option.
+
+```yarn
+-> Option 1 &css{backgroundColor: blue; color: white;}
+    Narrator: You chose option 1.
+-> Option 2 &css{backgroundColor: green; color: black;}
+    Narrator: You chose option 2.
+```
+
+Parsed into `Option.css`, passed through IR, and emitted at runtime on `options` results:
+
+```ts
+if (result.type === "options") {
+  // result.options[i].css contains the inline CSS string
+}
+```
+
+### Notes
+
+- The CSS content is treated as a raw string (not parsed). Use a simple `property: value;` format that your UI layer can interpret.
+- This feature is additive and does not affect core Yarn semantics.
+
+

package/docs/detour.md

@@ -0,0 +1,24 @@
+## Detour Command (Yarn Spinner)
+
+Source: [docs.yarnspinner.dev — Detour](https://docs.yarnspinner.dev/write-yarn-scripts/scripting-fundamentals/detour)
+
+### What it covers
+- **`<<detour NodeTitle>>`**: temporarily visit another node and return when it finishes.
+- Useful for side conversations, tooltips, or contextual asides.
+
+### Example
+```yarn
+title: Main
+---
+Narrator: Before we continue, a quick aside.
+<<detour Aside>>
+Narrator: Back to the main thread.
+===
+
+title: Aside
+---
+Narrator: Here's some extra info.
+===
+```
+
+

package/docs/enums.md

@@ -0,0 +1,25 @@
+## Enums (Yarn Spinner)
+
+Source: [docs.yarnspinner.dev — Enums](https://docs.yarnspinner.dev/write-yarn-scripts/scripting-fundamentals/enums)
+
+### What it covers
+- Define named sets of values for clarity and safety.
+- Compare enum values in conditions and assignments.
+
+### Example
+```yarn
+title: Setup
+---
+<<declare Mood = enum { Happy, Neutral, Sad }>>
+<<set currentMood = Mood.Happy>>
+===
+
+title: Check
+---
+{if currentMood == Mood.Happy}
+    NPC: Great to see you!
+{endif}
+===
+```
+
+

package/docs/flow-control.md

@@ -0,0 +1,25 @@
+## Flow Control (Yarn Spinner)
+
+Source: [docs.yarnspinner.dev — Flow Control](https://docs.yarnspinner.dev/write-yarn-scripts/scripting-fundamentals/flow-control)
+
+### What it covers
+- Conditional blocks with `{if}`, `{else if}`, `{else}`, `{endif}`.
+- Loops and structural control features provided by Yarn (engine-dependent usage).
+- Combining flow with variables and options.
+
+### Example
+```yarn
+title: Start
+---
+<<set affinity = 3>>
+{if affinity >= 5}
+    NPC: We're close friends.
+{else if affinity >= 2}
+    NPC: We're friendly enough.
+{else}
+    NPC: Do I know you?
+{endif}
+===
+```
+
+

package/docs/functions.md

@@ -0,0 +1,20 @@
+## Functions (Yarn Spinner)
+
+Source: [docs.yarnspinner.dev — Functions](https://docs.yarnspinner.dev/write-yarn-scripts/scripting-fundamentals/functions)
+
+### What it covers
+- Use functions in expressions for calculations and queries.
+- Custom functions can be exposed by the host game.
+
+### Examples
+```yarn
+title: Start
+---
+<<set total = add(2, 3)>>
+Narrator: The total is {total}.
+===
+```
+
+Function names/arity/behavior depend on your integration’s function bindings.
+
+

package/docs/jumps.md

@@ -0,0 +1,24 @@
+## Jump Command (Yarn Spinner)
+
+Source: [docs.yarnspinner.dev — Jump Command](https://docs.yarnspinner.dev/write-yarn-scripts/scripting-fundamentals/jumps)
+
+### What it covers
+- **`<<jump NodeTitle>>`**: transfer execution to another node by title.
+- Visualized in graph views as an arrow to the target node.
+- Works across files; node titles must be unique in the project.
+
+### Example
+```yarn
+title: Start
+---
+Narrator: Proceeding to the next scene.
+<<jump NextScene>>
+===
+
+title: NextScene
+---
+Narrator: We are in the next scene.
+===
+```
+
+

package/docs/line-groups.md

@@ -0,0 +1,21 @@
+## Line Groups (Yarn Spinner)
+
+Source: [docs.yarnspinner.dev — Line Groups](https://docs.yarnspinner.dev/write-yarn-scripts/scripting-fundamentals/line-groups)
+
+### What it covers
+- Group related lines for localization, organization, or metadata.
+- Often used to assign tags or manage VO/loc pipelines.
+
+### Example (conceptual)
+```yarn
+title: Start
+---
+// Lines here can be assigned to a group via editor metadata.
+Narrator: Grouped line A.
+Narrator: Grouped line B.
+===
+```
+
+Details vary by tooling (e.g., Yarn Spinner Editor/VS Code integration).
+
+

package/docs/lines-nodes-and-options.md

@@ -0,0 +1,30 @@
+## Nodes and Lines (Yarn Spinner)
+
+Source: [docs.yarnspinner.dev — Nodes and Lines](https://docs.yarnspinner.dev/write-yarn-scripts/scripting-fundamentals/lines-nodes-and-options)
+
+### What it covers
+- **Nodes**: titled containers for dialogue. Headers above `---`, body between `---` and `===`.
+- **Lines**: dialogue or narration lines emitted to the game one at a time.
+- **Character prefix**: `Name: Dialogue` marks the speaking character.
+- **Node rules**: titles start with a letter; letters/numbers/underscores only; no `.`.
+
+### Basic structure
+```yarn
+title: Start
+---
+Narrator: Hi, I'm the narrator for the documentation!
+===
+```
+
+### Character speaking vs narration
+```yarn
+This is a line of dialogue, without a character name.
+Speaker: This is another line said by a character called "Speaker".
+```
+
+### Tips
+- Use multiple nodes to manage long or branching stories.
+- Additional headers (e.g., `color:`, `group:`) organize nodes in editors.
+- The game decides how to render each delivered line.
+
+

package/docs/logic-and-variables.md

@@ -0,0 +1,25 @@
+## Logic and Variables (Yarn Spinner)
+
+Source: [docs.yarnspinner.dev — Logic and Variables](https://docs.yarnspinner.dev/write-yarn-scripts/scripting-fundamentals/logic-and-variables)
+
+### What it covers
+- Declaring and using variables; reading and writing from the game.
+- Basic expressions for conditions and assignments.
+- Interpolating values in lines.
+
+### Examples
+```yarn
+title: Start
+---
+<<set hasKey = true>>
+<<set score = 10 + 5>>
+
+{if hasKey}
+    Narrator: You unlock the door. Score: {score}
+{else}
+    Narrator: The door is locked.
+{endif}
+===
+```
+
+

package/docs/markup.md

@@ -0,0 +1,19 @@
+## Markup (Yarn Spinner)
+
+Source: [docs.yarnspinner.dev — Markup](https://docs.yarnspinner.dev/write-yarn-scripts/advanced-scripting/markup)
+
+### What it covers
+- Rich text features embedded in lines (emphasis, links, inline commands).
+- Parsed and passed to the host for rendering.
+
+### Example
+```yarn
+title: Start
+---
+Narrator: This is *italic*, this is **bold**, and this is a [link](game:codex/entry1).
+===
+```
+
+Supported markup and rendering vary by integration.
+
+

package/docs/node-groups.md

@@ -0,0 +1,13 @@
+## Node Groups (Yarn Spinner)
+
+Source: [docs.yarnspinner.dev — Node Groups](https://docs.yarnspinner.dev/write-yarn-scripts/advanced-scripting/node-groups)
+
+### What it covers
+- Organize nodes into higher-level groups for structure and navigation.
+- Helpful in large projects for editor graph organization and categorization.
+
+### Usage
+- Assign `group:` headers in nodes to categorize.
+- Use editor features to visualize and manage grouped nodes.
+
+

package/docs/once.md

@@ -0,0 +1,21 @@
+## Once (Yarn Spinner)
+
+Source: [docs.yarnspinner.dev — Once](https://docs.yarnspinner.dev/write-yarn-scripts/scripting-fundamentalsendonce)
+
+### What it covers
+- Ensure a section runs only the first time it’s reached.
+- Useful for tutorials, first-time greetings, unique rewards.
+
+### Example
+```yarn
+title: Start
+---
+<<once>>
+    Guide: Welcome! This shows only once.
+<<endonce>>
+
+Guide: This shows every time.
+===
+```
+
+