yarn-spinner-runner-ts 0.1.0

package/docs/options.md

@@ -0,0 +1,45 @@
+## Options (Yarn Spinner)
+
+Source: [docs.yarnspinner.dev — Options](https://docs.yarnspinner.dev/write-yarn-scripts/scripting-fundamentals/options)
+
+### What it covers
+- **Options**: player choices written as lines prefixed with `->`.
+- **Grouping**: options that appear consecutively (uninterrupted by non-indented lines) are delivered together.
+- **Indented content**: lines under an option run only when that option is selected.
+- **Nested options**: options can nest under options.
+
+### Basic options
+```yarn
+title: Start
+---
+Navigator: We're arriving before we left.
+-> Captain: Let's alter our trajectory and break this loop!
+-> Captain: We must complete the cycle.
+===
+```
+
+### Options with lines
+```yarn
+title: Start
+---
+-> Captain: Let's alter our trajectory and break this loop!
+    Navigator: Risky, Captain.
+-> Captain: We must complete the cycle.
+    Navigator: Then we're doomed to repeat this moment.
+===
+```
+
+### Nested options
+```yarn
+title: Start
+---
+-> Captain: Change course!
+    Navigator: Understood.
+    -> Captain: Do it now!
+        Navigator: Aye.
+    -> Captain: On second thought...
+        Navigator: Standing by.
+===
+```
+
+

package/docs/saliency.md

@@ -0,0 +1,25 @@
+## Saliency (Yarn Spinner)
+
+Source: [docs.yarnspinner.dev — Saliency](https://docs.yarnspinner.dev/write-yarn-scripts/advanced-scripting/saliency)
+
+### What it covers
+- Mechanisms to score and choose among multiple narrative candidates.
+- Authoring patterns to influence scoring with variables/tags.
+
+### Example (conceptual)
+```yarn
+title: Candidate_A
+---
+// Conditions/tags make this salient when player is low health
+Narrator: You look hurt. Rest a moment.
+===
+
+title: Candidate_B
+---
+Narrator: The path ahead is clear.
+===
+```
+
+Selection between candidates is driven by your saliency system configuration.
+
+

package/docs/scenes-actors-setup.md

@@ -0,0 +1,195 @@
+# Scene and Actor Setup Guide
+
+This guide explains how to configure scenes and actors for the dialogue system.
+
+## Overview
+
+Scenes provide visual backgrounds and actor images for dialogue. Actors are characters that appear when they speak. The configuration uses YAML format with two separate sections: `scenes` and `actors`.
+
+## Configuration Format
+
+Create a YAML file with the following structure:
+
+```yaml
+scenes:
+  scene1: https://example.com/background1.jpg
+  scene2: https://example.com/background2.jpg
+  
+actors:
+  user: https://example.com/user.png
+  Narrator: https://example.com/narrator.png
+  npc: https://example.com/npc.png
+```
+
+## Scenes
+
+### Simple Scene (Background Only)
+
+The simplest format is just the background image URL:
+
+```yaml
+scenes:
+  scene1: https://example.com/background1.jpg
+```
+
+This creates a scene named `scene1` with the specified background. All global actors will be available in this scene.
+
+### Scene with Custom Actors
+
+You can override global actors per scene:
+
+```yaml
+scenes:
+  scene1:
+    background: https://example.com/background1.jpg
+    actors:
+      special_npc:
+        image: https://example.com/special-npc.png
+```
+
+This creates `scene1` with a custom background and includes a scene-specific actor `special_npc` in addition to all global actors.
+
+### Scene Structure
+
+- **scene name** (key): The identifier used in Yarn scripts (e.g., `scene: scene1`)
+- **background** (string): URL or path to the background image
+- **actors** (object, optional): Scene-specific actors that override or extend global actors
+
+## Actors
+
+### Global Actors
+
+Global actors are available in all scenes:
+
+```yaml
+actors:
+  user: https://example.com/user.png
+  Narrator: https://example.com/narrator.png
+  npc: https://example.com/npc.png
+```
+
+### Actor Configuration
+
+Actors can be defined in two ways:
+
+**Shorthand** (direct URL):
+```yaml
+actors:
+  user: https://example.com/user.png
+```
+
+**Full format** (object):
+```yaml
+actors:
+  user:
+    image: https://example.com/user.png
+```
+
+Both formats are equivalent. The object format allows for future extension with additional actor properties.
+
+## Using Scenes in Yarn Scripts
+
+Add a `scene:` header to any node to activate that scene:
+
+```yarn
+title: Start
+scene: scene1
+---
+Narrator: Welcome to the adventure!
+User: Let's begin!
+===
+```
+
+### Scene Persistence
+
+Once a scene is set, the background persists across nodes until a new scene is specified. If a node doesn't have a `scene:` header, the previous scene continues to be used.
+
+## Actor Display
+
+### When Actors Appear
+
+- Actors appear only when they are speaking
+- Actor images are matched by name (case-insensitive)
+- The speaking actor's image appears at the top center of the scene
+- If no matching actor is found in the scene configuration, only the text is shown
+
+### Actor Matching
+
+Actor names in the Yarn script are matched against actor names in the scene configuration:
+
+```yarn
+Narrator: This is the narrator speaking.
+```
+
+This matches an actor named `Narrator`, `narrator`, or any case variation in your scene config.
+
+## Example Configuration
+
+```yaml
+scenes:
+  intro:
+    background: /assets/backgrounds/intro.jpg
+  forest:
+    background: /assets/backgrounds/forest.jpg
+    actors:
+      guide:
+        image: /assets/actors/guide.png
+  
+actors:
+  user: /assets/actors/user.png
+  Narrator: /assets/actors/narrator.png
+  merchant: /assets/actors/merchant.png
+```
+
+In this example:
+- `intro` scene uses the intro background and all global actors (user, Narrator, merchant)
+- `forest` scene uses the forest background, includes all global actors, plus a scene-specific `guide` actor
+
+## Yarn Script Example
+
+```yarn
+title: Intro
+scene: intro
+---
+Narrator: Welcome to the adventure!
+User: I'm ready to begin!
+===
+
+title: Forest
+scene: forest
+---
+Narrator: You enter the mysterious forest.
+Guide: Let me show you the way.
+User: Thank you, guide!
+===
+```
+
+## Image Requirements
+
+- **Background images**: Should be high resolution (recommended: 1920x1080 or higher) as they fill the entire scene
+- **Actor images**: Should be transparent PNGs with the character visible in the frame (recommended: 800x1200 or similar portrait aspect)
+- Images can be:
+  - Local paths: `/assets/images/character.png`
+  - Absolute URLs: `https://example.com/image.jpg`
+  - Relative URLs: `../images/background.png`
+
+## CSS Styling
+
+All dialogue elements use CSS classes prefixed with `yd-` for easy customization:
+
+- `.yd-scene` - Scene background container
+- `.yd-actor` - Actor image
+- `.yd-dialogue-box` - Dialogue box container
+- `.yd-text-box` - Text dialogue content
+- `.yd-options-box` - Options container
+
+You can override these styles in your own CSS to customize the appearance.
+
+## Tips
+
+1. **Reuse actors**: Define common actors globally so they're available in all scenes
+2. **Scene-specific actors**: Use scene-specific actors for characters that only appear in certain scenes
+3. **Background persistence**: Scenes persist until changed, so you don't need to repeat `scene:` in every node
+4. **Case sensitivity**: Actor names are matched case-insensitively, but scene names are case-sensitive
+5. **Image loading**: Use optimized images (WebP or compressed PNG/JPG) for better performance
+

package/docs/scenes.md

@@ -0,0 +1,64 @@
+# Scene System
+
+The scene system provides visual backgrounds and actor images for dialogue scenes.
+
+> 📖 **Detailed Setup Guide**: See [Scenes and Actors Setup](./scenes-actors-setup.md) for complete configuration instructions.
+
+## Quick Overview
+
+Scenes and actors are configured separately in YAML:
+
+```yaml
+scenes:
+  scene1: https://example.com/background1.jpg
+  
+actors:
+  user: https://example.com/user.png
+  Narrator: https://example.com/narrator.png
+```
+
+## Features
+
+1. **Background Transitions**: When a scene changes, the background smoothly fades from the old to the new image.
+2. **Persistent Backgrounds**: Once a scene is set, the background persists until a new scene is specified.
+3. **Actor Images**: Only the speaking actor's image appears at the top center of the scene.
+4. **Fallback**: If no scene is specified or an actor has no image, the system falls back to text-only display.
+
+## Using Scenes in Yarn Scripts
+
+Add a `scene:` header to any node:
+
+```yarn
+title: Start
+scene: scene1
+---
+Narrator: Welcome to the adventure!
+User: Let's begin!
+===
+```
+
+## Integration
+
+Pass scene configuration to `DialogueView`:
+
+```tsx
+import { DialogueView } from "yarn-spinner-ts";
+import { parseScenes } from "yarn-spinner-ts";
+
+const scenes = parseScenes(sceneYamlText);
+
+<DialogueView result={result} onAdvance={advance} scenes={scenes} />
+```
+
+## CSS Classes
+
+All dialogue elements use CSS classes prefixed with `yd-`:
+
+- `.yd-scene` - Scene background container
+- `.yd-actor` - Actor image (top center)
+- `.yd-dialogue-box` - Dialogue box container
+- `.yd-text-box` - Text dialogue content
+- `.yd-options-box` - Options container
+
+Customize these in your CSS to match your game's style.
+

package/docs/shadow-lines.md

@@ -0,0 +1,18 @@
+## Shadow Lines (Yarn Spinner)
+
+Source: [docs.yarnspinner.dev — Shadow Lines](https://docs.yarnspinner.dev/write-yarn-scripts/advanced-scripting/shadow-lines)
+
+### What it covers
+- Author alternative versions of lines (e.g., localized/variant lines) without changing IDs.
+- Useful for VO/loc updates while preserving references.
+
+### Example (conceptual)
+```yarn
+title: Start
+---
+Narrator: Primary line content.
+// Shadow line variants are managed by tooling to swap text without new IDs.
+===
+```
+
+

package/docs/smart-variables.md

@@ -0,0 +1,19 @@
+## Smart Variables (Yarn Spinner)
+
+Source: [docs.yarnspinner.dev — Smart Variables](https://docs.yarnspinner.dev/write-yarn-scripts/scripting-fundamentals/smart-variables)
+
+### What it covers
+- Variables that reference game-side data or computed values.
+- Enable referencing properties without manual syncing.
+
+### Example (conceptual)
+```yarn
+title: HUD
+---
+Player: Health is {player.health} and gold is {player.gold}.
+===
+```
+
+Implementation details depend on the host engine (Unity/Godot/Unreal) binding.
+
+

package/docs/storylets-and-saliency-a-primer.md

@@ -0,0 +1,14 @@
+## Storylets & Saliency — A Primer (Yarn Spinner)
+
+Source: [docs.yarnspinner.dev — Storylets & Saliency: A Primer](https://docs.yarnspinner.dev/write-yarn-scripts/advanced-scripting/storylets-and-saliency-a-primer)
+
+### What it covers
+- The concept of storylets: small, modular narrative units.
+- **Saliency**: scoring/selecting which content to present next based on context.
+- How these ideas support dynamic narrative selection.
+
+### Key ideas
+- Author self-contained nodes with clear entry conditions.
+- Use variables, tags, and conditions to influence selection.
+
+

package/docs/tags-metadata.md

@@ -0,0 +1,18 @@
+## Tags & Metadata (Yarn Spinner)
+
+Source: [docs.yarnspinner.dev — Tags & Metadata](https://docs.yarnspinner.dev/write-yarn-scripts/advanced-scripting/tags-metadata)
+
+### What it covers
+- Attach tags/metadata to lines or nodes for tooling and runtime behavior.
+- Drive VO, animation, or analytics pipelines with tagged content.
+
+### Example (conceptual)
+```yarn
+title: Start
+---
+// Tags may be set in headers or editor UIs; usage varies by tooling.
+Narrator: This line might carry a "vo=Line_001" tag.
+===
+```
+
+

package/eslint.config.cjs

@@ -0,0 +1,33 @@
+// ESLint v9 flat config
+const js = require("@eslint/js");
+const tsParser = require("@typescript-eslint/parser");
+const tsPlugin = require("@typescript-eslint/eslint-plugin");
+
+module.exports = [
+  {
+    ignores: ["dist/**", "node_modules/**", "examples/**", "src/examples/**", "src/tests/**"],
+  },
+  {
+    files: ["src/**/*.ts", "src/**/*.tsx"],
+    languageOptions: {
+      parser: tsParser,
+      ecmaVersion: "latest",
+      sourceType: "module",
+      globals: {
+        console: "readonly",
+      },
+    },
+    plugins: {
+      "@typescript-eslint": tsPlugin,
+    },
+    rules: {
+      ...js.configs.recommended.rules,
+      ...tsPlugin.configs.recommended.rules,
+      "@typescript-eslint/explicit-module-boundary-types": "off",
+      "@typescript-eslint/no-explicit-any": "off",
+      "no-console": ["warn", { allow: ["warn", "error", "assert", "log"] }],
+    },
+  },
+];
+
+

package/examples/browser/README.md

@@ -0,0 +1,40 @@
+# Browser Demo
+
+This is a browser-based demo of the Yarn Spinner dialogue system.
+
+## Running the Demo
+
+1. Install dependencies (if not already done):
+   ```bash
+   npm install
+   ```
+
+2. Start the development server:
+   ```bash
+   npm run demo
+   ```
+
+   This will start a Vite dev server at `http://localhost:3000` and open it in your browser.
+
+3. Build for production:
+   ```bash
+   npm run demo:build
+   ```
+
+   The built files will be in `dist-demo/`.
+
+## Features Demonstrated
+
+- Visual novel-style dialogue UI
+- Click-to-continue text display
+- Interactive option selection
+- CSS styling support for options
+- Speaker names
+- Real-time Yarn script editing
+
+## Customization
+
+Edit `src/react/DialogueExample.tsx` to change the default Yarn script or customize the UI.
+
+Edit `src/react/DialogueView.tsx` to change the dialogue box styling and behavior.
+

package/examples/browser/index.html

@@ -0,0 +1,23 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>NarraLeaf-React Dialogue Demo</title>
+  <style>
+    * {
+      margin: 0;
+      padding: 0;
+      box-sizing: border-box;
+    }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif;
+    }
+  </style>
+</head>
+<body>
+  <div id="root"></div>
+  <script type="module" src="/main.tsx"></script>
+</body>
+</html>
+

package/examples/browser/main.tsx

@@ -0,0 +1,16 @@
+import React from "react";
+import { createRoot } from "react-dom/client";
+import { DialogueExample } from "../../src/react/DialogueExample.js";
+
+const rootEl = document.getElementById("root");
+if (!rootEl) {
+  throw new Error("Root element not found");
+}
+
+const root = createRoot(rootEl);
+root.render(
+  <React.StrictMode>
+    <DialogueExample />
+  </React.StrictMode>
+);
+

package/examples/browser/vite.config.ts

@@ -0,0 +1,22 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import path from "path";
+
+export default defineConfig({
+  plugins: [react()],
+  root: "examples/browser",
+  resolve: {
+    alias: {
+      "yarn-spinner-ts": path.resolve(__dirname, "../src"),
+    },
+  },
+  build: {
+    outDir: "../../dist-demo",
+    emptyOutDir: true,
+  },
+  server: {
+    port: 3000,
+    open: true,
+  },
+});
+

package/examples/react/DialogueExample.tsx

@@ -0,0 +1,2 @@
+export { DialogueExample } from "../../src/react/DialogueExample.js";
+

package/examples/react/DialogueView.tsx

@@ -0,0 +1,2 @@
+export { DialogueView } from "../../src/react/DialogueView.js";
+

package/examples/react/useYarnRunner.tsx

@@ -0,0 +1,2 @@
+export { useYarnRunner } from "../../src/react/useYarnRunner.js";
+

package/examples/scenes/scenes.yaml

@@ -0,0 +1,10 @@
+scene1:
+  background: /assets/backgrounds/start.png
+  actors:
+    user:
+      image: /assets/actors/user.png
+    narrator:
+      image: /assets/actors/narrator.png
+    npc:
+      image: /assets/actors/npc.png
+

package/examples/yarn/full_featured.yarn

@@ -0,0 +1,43 @@
+title: Start
+---
+<<declare $score = 0>>
+Narrator: Welcome to the comprehensive Yarn test.
+<<set $score = 7>>
+<<if $score > 10>>
+    Narrator: High score branch.
+<<elseif $score > 5>>
+    Narrator: Medium score branch.
+<<else>>
+    Narrator: Low score branch.
+<<endif>>
+
+<<once>>
+    Narrator: This once block should only appear the first time.
+<<endonce>>
+
+-> Take the main path
+    Narrator: Proceeding on the main path.
+    <<jump NextScene>>
+-> Explore a detour
+    Narrator: Let's explore a detour first.
+    <<detour AsideInfo>>
+    Narrator: Back from detour.
+    <<jump NextScene>>
+===
+
+title: NextScene
+---
+Narrator: You have arrived in the next scene.
+-> Ask about features
+    Player: What can this system do?
+    Narrator: It supports options, conditions, once, jump, and detour.
+-> Finish
+    Narrator: Ending the scene.
+===
+
+title: AsideInfo
+---
+Narrator: This is detour content.
+===
+
+

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "yarn-spinner-runner-ts",
+  "version": "0.1.0",
+  "private": false,
+  "description": "TypeScript parser, compiler, and runtime for Yarn Spinner 3.x with React adapter",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rimraf dist",
+    "dev": "tsc -w -p tsconfig.json",
+    "lint": "eslint \"src/**/*.ts\" \"src/**/*.tsx\"",
+    "pretest": "npm run build",
+    "test": "node --test --enable-source-maps \"dist/tests/**/*.test.js\" \"dist/tests/index.test.js\"",
+    "demo": "vite --config examples/browser/vite.config.ts --host 0.0.0.0",
+    "demo:build": "vite build --config examples/browser/vite.config.ts"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "keywords": [
+    "yarn-spinner",
+    "dialogue",
+    "parser",
+    "compiler",
+    "react"
+  ],
+  "dependencies": {
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.4",
+    "@types/js-yaml": "^4.0.9",
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "@eslint/js": "^9.12.0",
+    "@typescript-eslint/parser": "^8.8.1",
+    "@typescript-eslint/eslint-plugin": "^8.8.1",
+    "@vitejs/plugin-react": "^4.3.1",
+    "eslint": "^9.12.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.6.3",
+    "vite": "^5.4.3"
+  }
+}
+