yarn-spinner-runner-ts 0.1.2-b → 0.1.3

package/docs/actor-transition.md

@@ -0,0 +1,34 @@
+## Actor Image Transitions (React)
+
+`DialogueScene` cross-fades speaker portraits whenever a new line is delivered. The blend speed is configurable so you can match the feel of your UI.
+
+### Configuring the transition
+
+- `DialogueScene` accepts an `actorTransitionDuration` prop (milliseconds).
+- `DialogueView` forwards the same prop so you can set it once at the top level.
+- Default is `350` ms; smaller values snap faster, larger values linger.
+
+```tsx
+<DialogueView
+  result={result}
+  onAdvance={advance}
+  scenes={scenes}
+  actorTransitionDuration={900}
+/>
+```
+
+### How it works
+
+- The duration is exposed to CSS as the `--yd-actor-transition` custom property on the scene container.
+- `dialogue.css` reads that variable in the `transition` for `.yd-actor`, so any value you pass updates both fade-in and fade-out timing while keeping the easing curve.
+- Portraits cross-fade: the outgoing image fades out while the incoming image fades in.
+
+### Tips
+
+- Long transitions (e.g., 2000 ms) work best when dialogue advances slowly; otherwise use shorter timings to avoid sluggish portraits.
+- If an actor image fails to load, the component logs a warning and keeps the previous portrait visible.
+- Combine with `enableTypingAnimation` to align text pacing with portrait changes.
+
+### Testing
+
+- Animation timing changes are mostly visual. After adjusting durations, run `npm test` and manually confirm the fade still feels right in the browser demo.

package/docs/markup.md

@@ -1,19 +1,34 @@
-## 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.
-
-
+## Markup (Yarn Spinner)
+
+Source: [docs.yarnspinner.dev � Markup](https://docs.yarnspinner.dev/write-yarn-scripts/advanced-scripting/markup)
+
+### Supported formatting
+
+The runtime now parses Yarn Spinner markup and surfaces it through `TextResult.markup` and option metadata. The React components (`DialogueView`, `TypingText`, and the option buttons) render this markup automatically.
+
+- The following tags map directly to native HTML elements: `b`, `strong`, `em`, `small`, `sub`, `sup`, `ins`, `del`, and `mark`.
+- Any other markup tag is rendered as a `<span>` with the class `yd-markup-<tagName>` so you can style or animate it via CSS.
+- Markup attributes are exposed as `data-markup-*` attributes on the rendered element. For example `[wave speed=2]` renders `<span class="yd-markup-wave" data-markup-speed="2">`.
+
+### Example
+
+```yarn
+title: Start
+---
+Narrator: Plain [b]bold[/b] [wave speed=2]custom[/wave]
+===
+```
+
+The React renderer produces:
+
+```html
+Plain <b>bold</b> <span class="yd-markup-wave" data-markup-speed="2">custom</span>
+```
+
+### Integration notes
+
+- Markup data is available on `TextResult.markup` and on each option entry (`result.options[i].markup`).
+- `TypingText` respects markup while animating, so formatting stays intact during the typewriter effect.
+- When a markup tag is not recognised, it remains in the output (as a span) rather than being stripped, so you can add custom CSS in your host application.
+
+For the full markup vocabulary see the official Yarn Spinner documentation.

package/docs/scenes-actors-setup.md

@@ -112,6 +112,7 @@ Once a scene is set, the background persists across nodes until a new scene is s
 - 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
+- The portrait transition duration defaults to 350 ms and can be adjusted by passing `actorTransitionDuration` (in milliseconds) to either `<DialogueScene />` or `<DialogueView />`
 
 ### Actor Matching
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yarn-spinner-runner-ts",
-  "version": "0.1.2-b",
+  "version": "0.1.3",
   "private": false,
   "description": "TypeScript parser, compiler, and runtime for Yarn Spinner 3.x with React adapter [NPM package](https://www.npmjs.com/package/yarn-spinner-runner-ts)",
   "license": "MIT",

package/src/compile/compiler.ts

@@ -44,7 +44,7 @@ export function compile(doc: YarnDocument, opts: CompileOptions = {}): IRProgram
           case "Line":
             {
               const line = s as Line;
-              block.push({ op: "line", speaker: line.speaker, text: line.text, tags: ensureLineId(line.tags) });
+              block.push({ op: "line", speaker: line.speaker, text: line.text, tags: ensureLineId(line.tags), markup: line.markup });
             }
             break;
           case "Command":
@@ -72,7 +72,7 @@ export function compile(doc: YarnDocument, opts: CompileOptions = {}): IRProgram
             }
             block.push({
               op: "options",
-              options: s.options.map((o: Option) => ({ text: o.text, tags: ensureLineId(o.tags), css: (o as any).css, block: emitBlock(o.body) })),
+              options: s.options.map((o: Option) => ({ text: o.text, tags: ensureLineId(o.tags), css: (o as any).css, markup: o.markup, block: emitBlock(o.body) })),
             });
             break;
           }
@@ -114,7 +114,7 @@ export function compile(doc: YarnDocument, opts: CompileOptions = {}): IRProgram
               case "Line":
                 {
                   const line = s as Line;
-                  block.push({ op: "line", speaker: line.speaker, text: line.text, tags: ensureLineId(line.tags) });
+                  block.push({ op: "line", speaker: line.speaker, text: line.text, tags: ensureLineId(line.tags), markup: line.markup });
                 }
                 break;
               case "Command":
@@ -141,7 +141,7 @@ export function compile(doc: YarnDocument, opts: CompileOptions = {}): IRProgram
                 }
                 block.push({
                   op: "options",
-                  options: s.options.map((o: Option) => ({ text: o.text, tags: ensureLineId(o.tags), css: (o as any).css, block: emitBlock(o.body) })),
+                  options: s.options.map((o: Option) => ({ text: o.text, tags: ensureLineId(o.tags), css: (o as any).css, markup: o.markup, block: emitBlock(o.body) })),
                 });
                 break;
               }

package/src/compile/ir.ts

@@ -1,3 +1,4 @@
+import type { MarkupParseResult } from "../markup/types.js";
 export type IRProgram = {
   enums: Record<string, string[]>; // enum name -> cases
   nodes: Record<string, IRNode | IRNodeGroup>; // can be single node or group
@@ -17,11 +18,11 @@ export type IRNodeGroup = {
 };
 
 export type IRInstruction =
-  | { op: "line"; speaker?: string; text: string; tags?: string[] }
+  | { op: "line"; speaker?: string; text: string; tags?: string[]; markup?: MarkupParseResult }
   | { op: "command"; content: string }
   | { op: "jump"; target: string }
   | { op: "detour"; target: string }
-  | { op: "options"; options: Array<{ text: string; tags?: string[]; css?: string; block: IRInstruction[] }> }
+  | { op: "options"; options: Array<{ text: string; tags?: string[]; css?: string; markup?: MarkupParseResult; block: IRInstruction[] }> }
   | { op: "if"; branches: Array<{ condition: string | null; block: IRInstruction[] }> }
   | { op: "once"; id: string; block: IRInstruction[] };
 

package/src/index.ts

@@ -3,6 +3,8 @@ export * from "./parse/lexer.js";
 export * from "./parse/parser.js";
 export * from "./compile/ir.js";
 export * from "./compile/compiler.js";
+export * from "./markup/types.js";
+export * from "./markup/parser.js";
 export * from "./runtime/results.js";
 export * from "./runtime/evaluator.js";
 export * from "./runtime/commands.js";
@@ -14,4 +16,5 @@ export * from "./react/useYarnRunner.js";
 export * from "./react/DialogueView.js";
 export * from "./react/DialogueExample.js";
 export * from "./react/DialogueScene.js";
+export * from "./react/MarkupRenderer.js";
 

package/src/markup/parser.ts

@@ -0,0 +1,372 @@
+import type { MarkupParseResult, MarkupSegment, MarkupValue, MarkupWrapper } from "./types.js";
+
+const DEFAULT_HTML_TAGS = new Set(["b", "em", "small", "strong", "sub", "sup", "ins", "del", "mark"]);
+
+interface StackEntry {
+  name: string;
+  type: MarkupWrapper["type"];
+  properties: Record<string, MarkupValue>;
+  originalText: string;
+}
+
+interface ParsedTag {
+  kind: "open" | "close" | "self";
+  name: string;
+  properties: Record<string, MarkupValue>;
+}
+
+const SELF_CLOSING_SPACE_REGEX = /\s+\/$/;
+const ATTRIBUTE_REGEX =
+  /^([a-zA-Z_][a-zA-Z0-9_-]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"']+)))?/;
+
+export function parseMarkup(input: string): MarkupParseResult {
+  const segments: MarkupSegment[] = [];
+  const stack: StackEntry[] = [];
+  const chars: string[] = [];
+  let currentSegment: MarkupSegment | null = null;
+  let nomarkupDepth = 0;
+
+  const pushSegment = (segment: MarkupSegment) => {
+    if (segment.selfClosing || segment.end > segment.start) {
+      segments.push(segment);
+    }
+  };
+
+  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 flushCurrentSegment = () => {
+    if (currentSegment) {
+      segments.push(currentSegment);
+      currentSegment = null;
+    }
+  };
+
+  const cloneWrappers = (): MarkupWrapper[] =>
+    stack.map((entry) => ({
+      name: entry.name,
+      type: entry.type,
+      properties: { ...entry.properties },
+    }));
+
+  const appendChar = (char: string) => {
+    const index = chars.length;
+    chars.push(char);
+    const wrappers = cloneWrappers();
+    if (currentSegment && wrappersEqual(currentSegment.wrappers, wrappers)) {
+      currentSegment.end = index + 1;
+    } else {
+      flushCurrentSegment();
+      currentSegment = {
+        start: index,
+        end: index + 1,
+        wrappers,
+      };
+    }
+  };
+
+  const appendLiteral = (literal: string) => {
+    for (const ch of literal) {
+      appendChar(ch);
+    }
+  };
+
+  const parseTag = (contentRaw: string): ParsedTag | null => {
+    let content = contentRaw.trim();
+    if (!content) return null;
+
+    if (content.startsWith("/")) {
+      const name = content.slice(1).trim().toLowerCase();
+      if (!name) return null;
+      return { kind: "close", name, properties: {} };
+    }
+
+    let kind: ParsedTag["kind"] = "open";
+    if (content.endsWith("/")) {
+      content = content.replace(SELF_CLOSING_SPACE_REGEX, "").trim();
+      if (content.endsWith("/")) {
+        content = content.slice(0, -1).trim();
+      }
+      kind = "self";
+    }
+
+    const nameMatch = content.match(/^([a-zA-Z_][a-zA-Z0-9_-]*)/);
+    if (!nameMatch) return null;
+    const name = nameMatch[1].toLowerCase();
+    let rest = content.slice(nameMatch[0].length).trim();
+
+    const properties: Record<string, MarkupValue> = {};
+    while (rest.length > 0) {
+      const attrMatch = rest.match(ATTRIBUTE_REGEX);
+      if (!attrMatch) {
+        break;
+      }
+      const [, keyRaw, doubleQuoted, singleQuoted, bare] = attrMatch;
+      const key = keyRaw.toLowerCase();
+      let value: MarkupValue = true;
+      const rawValue = doubleQuoted ?? singleQuoted ?? bare;
+      if (rawValue !== undefined) {
+        value = parseAttributeValue(rawValue);
+      }
+      properties[key] = value;
+      rest = rest.slice(attrMatch[0].length).trim();
+    }
+
+    return { kind, name, properties };
+  };
+
+  const parseAttributeValue = (raw: string): MarkupValue => {
+    const trimmed = raw.trim();
+    if (/^(true|false)$/i.test(trimmed)) {
+      return /^true$/i.test(trimmed);
+    }
+    if (/^[+-]?\d+(\.\d+)?$/.test(trimmed)) {
+      const num = Number(trimmed);
+      if (!Number.isNaN(num)) {
+        return num;
+      }
+    }
+    return trimmed;
+  };
+
+  const handleSelfClosing = (tag: ParsedTag) => {
+    const wrapper: MarkupWrapper = {
+      name: tag.name,
+      type: DEFAULT_HTML_TAGS.has(tag.name) ? "default" : "custom",
+      properties: tag.properties,
+    };
+    const position = chars.length;
+    pushSegment({
+      start: position,
+      end: position,
+      wrappers: [wrapper],
+      selfClosing: true,
+    });
+  };
+
+  let i = 0;
+  while (i < input.length) {
+    const char = input[i];
+    if (char === "\\" && i + 1 < input.length) {
+      const next = input[i + 1];
+      if (next === "[" || next === "]" || next === "\\") {
+        appendChar(next);
+        i += 2;
+        continue;
+      }
+    }
+
+    if (char === "[") {
+      const closeIndex = findClosingBracket(input, i + 1);
+      if (closeIndex === -1) {
+        appendChar(char);
+        i += 1;
+        continue;
+      }
+      const content = input.slice(i + 1, closeIndex);
+      const originalText = input.slice(i, closeIndex + 1);
+
+      const parsed = parseTag(content);
+      if (!parsed) {
+        appendLiteral(originalText);
+        i = closeIndex + 1;
+        continue;
+      }
+
+      if (parsed.name === "nomarkup") {
+        if (parsed.kind === "open") {
+          nomarkupDepth += 1;
+        } else if (parsed.kind === "close" && nomarkupDepth > 0) {
+          nomarkupDepth -= 1;
+        }
+        i = closeIndex + 1;
+        continue;
+      }
+
+      if (nomarkupDepth > 0) {
+        appendLiteral(originalText);
+        i = closeIndex + 1;
+        continue;
+      }
+
+      if (parsed.kind === "open") {
+        const entry: StackEntry = {
+          name: parsed.name,
+          type: DEFAULT_HTML_TAGS.has(parsed.name) ? "default" : "custom",
+          properties: parsed.properties,
+          originalText,
+        };
+        stack.push(entry);
+        flushCurrentSegment();
+        i = closeIndex + 1;
+        continue;
+      }
+
+      if (parsed.kind === "self") {
+        handleSelfClosing(parsed);
+        i = closeIndex + 1;
+        continue;
+      }
+
+      // closing tag
+      if (stack.length === 0) {
+        appendLiteral(originalText);
+        i = closeIndex + 1;
+        continue;
+      }
+      const top = stack[stack.length - 1];
+      if (top.name === parsed.name) {
+        flushCurrentSegment();
+        stack.pop();
+        i = closeIndex + 1;
+        continue;
+      }
+      // mismatched closing; treat as literal
+      appendLiteral(originalText);
+      i = closeIndex + 1;
+      continue;
+    }
+
+    appendChar(char);
+    i += 1;
+  }
+
+  flushCurrentSegment();
+
+  // If any tags remain open, treat them as literal text appended at end
+  while (stack.length > 0) {
+    const entry = stack.pop()!;
+    appendLiteral(entry.originalText);
+  }
+  flushCurrentSegment();
+
+  const text = chars.join("");
+  return {
+    text,
+    segments: mergeSegments(segments, text.length),
+  };
+}
+
+function mergeSegments(segments: MarkupSegment[], textLength: number): MarkupSegment[] {
+  const sorted = [...segments].sort((a, b) => a.start - b.start || a.end - b.end);
+  const merged: MarkupSegment[] = [];
+  let last: MarkupSegment | null = null;
+
+  for (const seg of sorted) {
+    if (seg.start === seg.end && !seg.selfClosing) {
+      continue;
+    }
+    if (last && !seg.selfClosing && last.end === seg.start && wrappersMatch(last.wrappers, seg.wrappers)) {
+      last.end = seg.end;
+    } else {
+      last = {
+        start: seg.start,
+        end: seg.end,
+        wrappers: seg.wrappers,
+        selfClosing: seg.selfClosing,
+      };
+      merged.push(last);
+    }
+  }
+
+  if (merged.length === 0 && textLength > 0) {
+    merged.push({
+      start: 0,
+      end: textLength,
+      wrappers: [],
+    });
+  }
+
+  return merged;
+}
+
+function wrappersMatch(a: MarkupWrapper[], b: MarkupWrapper[]): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i].name !== b[i].name || a[i].type !== b[i].type) return false;
+    const keysA = Object.keys(a[i].properties);
+    const keysB = Object.keys(b[i].properties);
+    if (keysA.length !== keysB.length) return false;
+    for (const key of keysA) {
+      if (a[i].properties[key] !== b[i].properties[key]) return false;
+    }
+  }
+  return true;
+}
+
+function findClosingBracket(text: string, start: number): number {
+  for (let i = start; i < text.length; i++) {
+    if (text[i] === "]") {
+      let backslashCount = 0;
+      let j = i - 1;
+      while (j >= 0 && text[j] === "\\") {
+        backslashCount++;
+        j--;
+      }
+      if (backslashCount % 2 === 0) {
+        return i;
+      }
+    }
+  }
+  return -1;
+}
+
+export function sliceMarkup(result: MarkupParseResult, start: number, end?: number): MarkupParseResult {
+  const textLength = result.text.length;
+  const sliceStart = Math.max(0, Math.min(start, textLength));
+  const sliceEnd = end === undefined ? textLength : Math.max(sliceStart, Math.min(end, textLength));
+  const slicedSegments: MarkupSegment[] = [];
+
+  for (const seg of result.segments) {
+    const segStart = Math.max(seg.start, sliceStart);
+    const segEnd = Math.min(seg.end, sliceEnd);
+    if (seg.selfClosing) {
+      if (segStart >= sliceStart && segStart <= sliceEnd) {
+        slicedSegments.push({
+          start: segStart - sliceStart,
+          end: segStart - sliceStart,
+          wrappers: seg.wrappers,
+          selfClosing: true,
+        });
+      }
+      continue;
+    }
+    if (segEnd <= segStart) continue;
+    slicedSegments.push({
+      start: segStart - sliceStart,
+      end: segEnd - sliceStart,
+      wrappers: seg.wrappers.map((wrapper) => ({
+        name: wrapper.name,
+        type: wrapper.type,
+        properties: { ...wrapper.properties },
+      })),
+    });
+  }
+
+  if (slicedSegments.length === 0 && sliceEnd - sliceStart > 0) {
+    slicedSegments.push({
+      start: 0,
+      end: sliceEnd - sliceStart,
+      wrappers: [],
+    });
+  }
+
+  return {
+    text: result.text.slice(sliceStart, sliceEnd),
+    segments: mergeSegments(slicedSegments, sliceEnd - sliceStart),
+  };
+}
+

package/src/markup/types.ts

@@ -0,0 +1,22 @@
+export type MarkupValue = string | number | boolean;
+
+export type MarkupWrapperType = "default" | "custom";
+
+export interface MarkupWrapper {
+  name: string;
+  type: MarkupWrapperType;
+  properties: Record<string, MarkupValue>;
+}
+
+export interface MarkupSegment {
+  start: number;
+  end: number;
+  wrappers: MarkupWrapper[];
+  selfClosing?: boolean;
+}
+
+export interface MarkupParseResult {
+  text: string;
+  segments: MarkupSegment[];
+}
+

package/src/model/ast.ts

@@ -36,12 +36,15 @@ export type Statement =
   | Detour
   | EnumBlock;
 
-export interface Line {
-  type: "Line";
-  speaker?: string;
-  text: string;
-  tags?: string[];
-}
+import type { MarkupParseResult } from "../markup/types.js";
+
+export interface Line {
+  type: "Line";
+  speaker?: string;
+  text: string;
+  tags?: string[];
+  markup?: MarkupParseResult;
+}
 
 export interface Command {
   type: "Command";
@@ -63,13 +66,14 @@ export interface OptionGroup {
   options: Option[];
 }
 
-export interface Option {
-  type: "Option";
-  text: string;
-  body: Statement[]; // executed if chosen
-  tags?: string[];
-  css?: string; // Custom CSS style for option
-}
+export interface Option {
+  type: "Option";
+  text: string;
+  body: Statement[]; // executed if chosen
+  tags?: string[];
+  css?: string; // Custom CSS style for option
+  markup?: MarkupParseResult;
+}
 
 export interface IfBlock {
   type: "If";