yarn-spinner-runner-ts 0.1.2 → 0.1.4-a

package/src/react/DialogueScene.tsx

@@ -1,4 +1,4 @@
-import React, { useState, useEffect } from "react";
+import React, { useState, useEffect, useMemo, useRef } from "react";
 import type { SceneCollection, SceneConfig } from "../scene/types.js";
 // Note: CSS is imported in the browser demo entry point (examples/browser/main.tsx)
 // This prevents Node.js from trying to resolve CSS imports during tests
@@ -8,25 +8,59 @@ export interface DialogueSceneProps {
   speaker?: string;
   scenes: SceneCollection;
   className?: string;
+  actorTransitionDuration?: number;
 }
 
 /**
  * Visual scene component that displays background and actor images
  */
-export function DialogueScene({ sceneName, speaker, scenes, className }: DialogueSceneProps) {
+export function DialogueScene({
+  sceneName,
+  speaker,
+  scenes,
+  className,
+  actorTransitionDuration = 350,
+}: DialogueSceneProps) {
+
   const [currentBackground, setCurrentBackground] = useState<string | null>(null);
   const [backgroundOpacity, setBackgroundOpacity] = useState(1);
   const [nextBackground, setNextBackground] = useState<string | null>(null);
   const [lastSceneName, setLastSceneName] = useState<string | undefined>(undefined);
   const [lastSpeaker, setLastSpeaker] = useState<string | undefined>(undefined);
+  const [activeActor, setActiveActor] = useState<{ name: string; image: string } | null>(null);
+  const [previousActor, setPreviousActor] = useState<{ name: string; image: string } | null>(null);
+  const [currentActorVisible, setCurrentActorVisible] = useState(false);
+  const [previousActorVisible, setPreviousActorVisible] = useState(false);
+  const previousActorTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   
   // Get scene config - use last scene if current node has no scene
   const activeSceneName = sceneName || lastSceneName;
   const sceneConfig: SceneConfig | undefined = activeSceneName ? scenes.scenes[activeSceneName] : undefined;
   const backgroundImage = sceneConfig?.background;
 
-  // Get all actors from the current scene
-  const sceneActors = sceneConfig ? Object.keys(sceneConfig.actors) : [];
+  const activeSpeakerName = speaker || lastSpeaker;
+
+  const resolvedActor = useMemo(() => {
+    if (!sceneConfig || !activeSpeakerName) {
+      return null;
+    }
+
+    const actorEntries = Object.entries(sceneConfig.actors);
+    const matchingActor = actorEntries.find(
+      ([actorName]) => actorName.toLowerCase() === activeSpeakerName.toLowerCase()
+    );
+
+    if (!matchingActor) {
+      return null;
+    }
+
+    const [actorName, actorConfig] = matchingActor;
+    if (!actorConfig?.image) {
+      return null;
+    }
+
+    return { name: actorName, image: actorConfig.image };
+  }, [sceneConfig, activeSpeakerName]);
   
   // Track last speaker - update when speaker is provided, keep when undefined
   useEffect(() => {
@@ -64,18 +98,95 @@ export function DialogueScene({ sceneName, speaker, scenes, className }: Dialogu
     // Never clear background - keep it until a new one is explicitly set
   }, [backgroundImage, currentBackground, sceneName, lastSceneName]);
 
+  // Handle actor portrait transitions (cross-fade between speakers)
+  useEffect(() => {
+    let fadeOutTimeout: ReturnType<typeof setTimeout> | null = null;
+
+    setActiveActor((currentActor) => {
+      const currentImage = currentActor?.image ?? null;
+      const currentName = currentActor?.name ?? null;
+      const nextImage = resolvedActor?.image ?? null;
+      const nextName = resolvedActor?.name ?? null;
+
+      if (currentImage === nextImage && currentName === nextName) {
+        return currentActor;
+      }
+
+      if (currentActor) {
+        setPreviousActor(currentActor);
+        setPreviousActorVisible(true);
+        fadeOutTimeout = setTimeout(() => {
+          setPreviousActorVisible(false);
+        }, 0);
+      } else {
+        setPreviousActor(null);
+        setPreviousActorVisible(false);
+      }
+
+      setCurrentActorVisible(false);
+
+      return resolvedActor;
+    });
+
+    return () => {
+      if (fadeOutTimeout !== null) {
+        clearTimeout(fadeOutTimeout);
+      }
+    };
+  }, [resolvedActor]);
+
+  useEffect(() => {
+    if (!activeActor) {
+      return;
+    }
+
+    const fadeInTimeout = setTimeout(() => {
+      setCurrentActorVisible(true);
+    }, 0);
+
+    return () => {
+      clearTimeout(fadeInTimeout);
+    };
+  }, [activeActor]);
+
+  // Remove previous actor once fade-out completes
+  useEffect(() => {
+    if (!previousActor) {
+      return;
+    }
+
+    if (previousActorTimeoutRef.current) {
+      clearTimeout(previousActorTimeoutRef.current);
+    }
+
+    previousActorTimeoutRef.current = setTimeout(() => {
+      setPreviousActor(null);
+      previousActorTimeoutRef.current = null;
+    }, actorTransitionDuration);
+
+    return () => {
+      if (previousActorTimeoutRef.current) {
+        clearTimeout(previousActorTimeoutRef.current);
+        previousActorTimeoutRef.current = null;
+      }
+    };
+  }, [previousActor, actorTransitionDuration]);
+
   // Default background color when no scene
   const defaultBgColor = "rgba(26, 26, 46, 1)"; // Dark blue-purple
+  const handleActorImageError = (actorName: string, imageUrl: string) => () => {
+    console.error(`Failed to load actor image for ${actorName}:`, imageUrl);
+  };
 
-  return (
-    <div
-      className={`yd-scene ${className || ""}`}
-      style={{
-        backgroundColor: currentBackground ? undefined : defaultBgColor,
-        backgroundImage: currentBackground ? `url(${currentBackground})` : undefined,
-        opacity: backgroundOpacity,
-      }}
-    >
+  const sceneStyle: React.CSSProperties & { ["--yd-actor-transition"]: string } = {
+    backgroundColor: currentBackground ? undefined : defaultBgColor,
+    backgroundImage: currentBackground ? `url(${currentBackground})` : undefined,
+    opacity: backgroundOpacity,
+    ["--yd-actor-transition"]: `${Math.max(actorTransitionDuration, 0)}ms`,
+  };
+
+  return (
+    <div className={`yd-scene ${className || ""}`} style={sceneStyle}>
       {/* Next background (during transition) */}
       {nextBackground && (
         <div
@@ -87,37 +198,25 @@ export function DialogueScene({ sceneName, speaker, scenes, className }: Dialogu
         />
       )}
 
-      {/* Actor image - show only the speaking actor, aligned to top */}
-      {sceneConfig && (speaker || lastSpeaker) && (() => {
-        // Use current speaker if available, otherwise use last speaker to keep image visible
-        const activeSpeaker = speaker || lastSpeaker;
-        
-        // Type guard: ensure activeSpeaker is defined
-        if (!activeSpeaker) return null;
-        
-        // Find the actor that matches the speaker (case-insensitive)
-        const speakingActorName = sceneActors.find(
-          actorName => actorName.toLowerCase() === activeSpeaker.toLowerCase()
-        );
-        
-        if (!speakingActorName) return null;
-        
-        const actorConfig = sceneConfig.actors[speakingActorName];
-        if (!actorConfig?.image) return null;
-
-        return (
-          <img
-            key={speakingActorName}
-            className="yd-actor"
-            src={actorConfig.image}
-            alt={speakingActorName}
-            onError={(e) => {
-              console.error(`Failed to load actor image for ${speakingActorName}:`, actorConfig.image, e);
-            }}
-          />
-        );
-      })()}
+      {/* Actor portraits with cross-fade */}
+      {previousActor && (
+        <img
+          key={`${previousActor.name}-previous`}
+          className={`yd-actor yd-actor--previous ${previousActorVisible ? "yd-actor--visible" : ""}`}
+          src={previousActor.image}
+          alt={previousActor.name}
+          onError={handleActorImageError(previousActor.name, previousActor.image)}
+        />
+      )}
+      {activeActor && (
+        <img
+          key={`${activeActor.name}-current`}
+          className={`yd-actor yd-actor--current ${currentActorVisible ? "yd-actor--visible" : ""}`}
+          src={activeActor.image}
+          alt={activeActor.name}
+          onError={handleActorImageError(activeActor.name, activeActor.image)}
+        />
+      )}
     </div>
   );
 }
-

package/src/react/DialogueView.tsx

@@ -1,15 +1,33 @@
-import React from "react";
-import type { RuntimeResult } from "../runtime/results.js";
+import React, { useRef, useEffect, useState } from "react";
 import { DialogueScene } from "./DialogueScene.js";
 import type { SceneCollection } from "../scene/types.js";
+import { TypingText } from "./TypingText.js";
+import { useYarnRunner } from "./useYarnRunner.js";
+import { MarkupRenderer } from "./MarkupRenderer.js";
 // Note: CSS is imported in the browser demo entry point (examples/browser/main.tsx)
 // This prevents Node.js from trying to resolve CSS imports during tests
 
+import type { IRProgram } from "../compile/ir.js";
+
 export interface DialogueViewProps {
-  result: RuntimeResult | null;
-  onAdvance: (optionIndex?: number) => void;
+  program: IRProgram;
+  startNode?: string;
   className?: string;
   scenes?: SceneCollection;
+  actorTransitionDuration?: number;
+  // Custom functions and callbacks
+  functions?: Record<string, (...args: unknown[]) => unknown>;
+  onStoryEnd?: (info: { variables: Readonly<Record<string, unknown>>; storyEnd: true }) => void;
+  // Typing animation options
+  enableTypingAnimation?: boolean;
+  typingSpeed?: number;
+  showTypingCursor?: boolean;
+  cursorCharacter?: string;
+  // Auto-advance after typing completes
+  autoAdvanceAfterTyping?: boolean;
+  autoAdvanceDelay?: number; // Delay in ms after typing completes before auto-advancing
+  // Pause before advance
+  pauseBeforeAdvance?: number; // Delay in ms before advancing when clicking (0 = no pause)
 }
 
 // Helper to parse CSS string into object
@@ -69,11 +87,68 @@ function parseCss(cssStr: string | undefined): React.CSSProperties {
   return styles;
 }
 
-export function DialogueView({ result, onAdvance, className, scenes }: DialogueViewProps) {
+export function DialogueView({
+  program,
+  startNode = "Start",
+  className,
+  scenes,
+  actorTransitionDuration = 350,
+  functions,
+  onStoryEnd,
+  enableTypingAnimation = false,
+  typingSpeed = 50, // Characters per second (50 cps = ~20ms per character)
+  showTypingCursor = true,
+  cursorCharacter = "|",
+  autoAdvanceAfterTyping = false,
+  autoAdvanceDelay = 500,
+  pauseBeforeAdvance = 0,
+}: DialogueViewProps) {
+  const { result, advance } = useYarnRunner(program, {
+    startAt: startNode,
+    functions,
+    variables: {},
+    onStoryEnd,
+  });
   const sceneName = result?.type === "text" || result?.type === "options" ? result.scene : undefined;
   const speaker = result?.type === "text" ? result.speaker : undefined;
   const sceneCollection = scenes || { scenes: {} };
 
+  const [typingComplete, setTypingComplete] = useState(false);
+  const [currentTextKey, setCurrentTextKey] = useState(0);
+  const [skipTyping, setSkipTyping] = useState(false);
+  const advanceTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Reset typing completion when text changes
+  useEffect(() => {
+    if (result?.type === "text") {
+      setTypingComplete(false);
+      setSkipTyping(false);
+      setCurrentTextKey((prev) => prev + 1); // Force re-render of TypingText
+    }
+    // Cleanup any pending advance timeouts when text changes
+    return () => {
+      if (advanceTimeoutRef.current) {
+        clearTimeout(advanceTimeoutRef.current);
+        advanceTimeoutRef.current = null;
+      }
+    };
+  }, [result?.type === "text" ? result.text : null]);
+
+  // Handle auto-advance after typing completes
+  useEffect(() => {
+    if (
+      autoAdvanceAfterTyping &&
+      typingComplete &&
+      result?.type === "text" &&
+      !result.isDialogueEnd
+    ) {
+      const timer = setTimeout(() => {
+        advance();
+      }, autoAdvanceDelay);
+      return () => clearTimeout(timer);
+    }
+  }, [autoAdvanceAfterTyping, typingComplete, result, advance, autoAdvanceDelay]);
+
   if (!result) {
     return (
       <div className={`yd-empty ${className || ""}`}>
@@ -84,13 +159,56 @@ export function DialogueView({ result, onAdvance, className, scenes }: DialogueV
 
   if (result.type === "text") {
     const nodeStyles = parseCss(result.nodeCss);
+    const displayText = result.text || "\u00A0";
+    const shouldShowContinue = !result.isDialogueEnd && !enableTypingAnimation;
+
+    // Handle story end and call onStoryEnd if provided
+    if (result.isDialogueEnd && onStoryEnd && 'variables' in result) {
+      onStoryEnd({ 
+        variables: result.variables as Readonly<Record<string, unknown>>, 
+        storyEnd: true 
+      });
+    }
+
+    const handleClick = () => {
+      if (result.isDialogueEnd) return;
+      
+      // If typing is in progress, skip it; otherwise advance
+      if (enableTypingAnimation && !typingComplete) {
+        // Skip typing animation
+        setSkipTyping(true);
+        setTypingComplete(true);
+      } else {
+        // Clear any pending timeout
+        if (advanceTimeoutRef.current) {
+          clearTimeout(advanceTimeoutRef.current);
+          advanceTimeoutRef.current = null;
+        }
+
+        // Apply pause before advance if configured
+        if (pauseBeforeAdvance > 0) {
+          advanceTimeoutRef.current = setTimeout(() => {
+            advance();
+            advanceTimeoutRef.current = null;
+          }, pauseBeforeAdvance);
+        } else {
+          advance();
+        }
+      }
+    };
+
     return (
       <div className="yd-container">
-        <DialogueScene sceneName={sceneName} speaker={speaker} scenes={sceneCollection} />
+        <DialogueScene
+          sceneName={sceneName}
+          speaker={speaker}
+          scenes={sceneCollection}
+          actorTransitionDuration={actorTransitionDuration}
+        />
         <div
           className={`yd-dialogue-box ${result.isDialogueEnd ? "yd-text-box-end" : ""} ${className || ""}`}
           style={nodeStyles} // Only apply dynamic node CSS
-          onClick={() => !result.isDialogueEnd && onAdvance()}
+          onClick={handleClick}
         >
           <div className="yd-text-box">
             {result.speaker && (
@@ -99,9 +217,22 @@ export function DialogueView({ result, onAdvance, className, scenes }: DialogueV
               </div>
             )}
             <p className={`yd-text ${result.speaker ? "yd-text-with-speaker" : ""}`}>
-              {result.text || "\u00A0"}
+              {enableTypingAnimation ? (
+                <TypingText
+                  key={currentTextKey}
+                  text={displayText}
+                  markup={result.markup}
+                  typingSpeed={typingSpeed}
+                  showCursor={showTypingCursor}
+                  cursorCharacter={cursorCharacter}
+                  disabled={skipTyping}
+                  onComplete={() => setTypingComplete(true)}
+                />
+              ) : (
+                <MarkupRenderer text={displayText} markup={result.markup} />
+              )}
             </p>
-            {!result.isDialogueEnd && (
+            {shouldShowContinue && (
               <div className="yd-continue">
                 ▼
               </div>
@@ -116,7 +247,12 @@ export function DialogueView({ result, onAdvance, className, scenes }: DialogueV
     const nodeStyles = parseCss(result.nodeCss);
     return (
       <div className="yd-container">
-        <DialogueScene sceneName={sceneName} speaker={speaker} scenes={sceneCollection} />
+        <DialogueScene
+          sceneName={sceneName}
+          speaker={speaker}
+          scenes={sceneCollection}
+          actorTransitionDuration={actorTransitionDuration}
+        />
         <div className={`yd-options-container ${className || ""}`}>
           <div className="yd-options-box" style={nodeStyles}>
             <div className="yd-options-title">Choose an option:</div>
@@ -127,10 +263,10 @@ export function DialogueView({ result, onAdvance, className, scenes }: DialogueV
                   <button
                     key={index}
                     className="yd-option-button"
-                    onClick={() => onAdvance(index)}
+                    onClick={() => advance(index)}
                     style={optionStyles} // Only apply dynamic option CSS
                   >
-                    {option.text}
+                    <MarkupRenderer text={option.text} markup={option.markup} />
                   </button>
                 );
               })}
@@ -145,9 +281,9 @@ export function DialogueView({ result, onAdvance, className, scenes }: DialogueV
   if (result.type === "command") {
     // Auto-advance commands after a brief moment
     React.useEffect(() => {
-      const timer = setTimeout(() => onAdvance(), 50);
+      const timer = setTimeout(() => advance(), 50);
       return () => clearTimeout(timer);
-    }, [result.command, onAdvance]);
+    }, [result.command, advance]);
 
     return (
       <div className={`yd-command ${className || ""}`}>

package/src/react/MarkupRenderer.tsx

@@ -0,0 +1,110 @@
+import React from "react";
+import type { MarkupParseResult, MarkupWrapper } from "../markup/types.js";
+
+const DEFAULT_HTML_TAGS = new Set(["b", "em", "small", "strong", "sub", "sup", "ins", "del", "mark"]);
+
+interface RenderPiece {
+  text: string;
+  wrappers: MarkupWrapper[];
+  key: string;
+  selfClosing?: boolean;
+}
+
+interface MarkupRendererProps {
+  text: string;
+  markup?: MarkupParseResult;
+  length?: number;
+}
+
+export function MarkupRenderer({ text, markup, length }: MarkupRendererProps) {
+  const maxLength = length ?? text.length;
+  if (!markup || markup.segments.length === 0) {
+    return <>{text.slice(0, maxLength)}</>;
+  }
+
+  const pieces: RenderPiece[] = [];
+  const limit = Math.max(0, Math.min(maxLength, markup.text.length));
+
+  markup.segments.forEach((segment, index) => {
+    if (segment.selfClosing) {
+      if (segment.start <= limit) {
+        pieces.push({
+          text: "",
+          wrappers: segment.wrappers,
+          selfClosing: true,
+          key: `self-${index}`,
+        });
+      }
+      return;
+    }
+    const start = Math.max(0, Math.min(segment.start, limit));
+    const end = Math.max(start, Math.min(segment.end, limit));
+    if (end <= start) {
+      return;
+    }
+    const segmentText = markup.text.slice(start, end);
+    pieces.push({
+      text: segmentText,
+      wrappers: segment.wrappers,
+      key: `seg-${index}-${start}-${end}`,
+    });
+  });
+
+  if (pieces.length === 0) {
+    return <>{text.slice(0, maxLength)}</>;
+  }
+
+  return (
+    <>
+      {pieces.map((piece, pieceIndex) => renderPiece(piece, pieceIndex))}
+    </>
+  );
+}
+
+function renderPiece(piece: RenderPiece, pieceIndex: number): React.ReactNode {
+  const baseKey = `${piece.key}-${pieceIndex}`;
+
+  if (piece.selfClosing) {
+    return piece.wrappers.reduceRight<React.ReactNode>(
+      (child, wrapper, wrapperIndex) => createWrapperElement(wrapper, `${baseKey}-wrapper-${wrapperIndex}`, child),
+      null
+    );
+  }
+
+  const content = piece.wrappers.reduceRight<React.ReactNode>(
+    (child, wrapper, wrapperIndex) => createWrapperElement(wrapper, `${baseKey}-wrapper-${wrapperIndex}`, child),
+    piece.text
+  );
+
+  return <React.Fragment key={baseKey}>{content}</React.Fragment>;
+}
+
+function createWrapperElement(
+  wrapper: MarkupWrapper,
+  key: string,
+  children: React.ReactNode
+): React.ReactElement {
+  const tagName = DEFAULT_HTML_TAGS.has(wrapper.name) ? wrapper.name : "span";
+  const className =
+    wrapper.type === "custom" ? `yd-markup-${sanitizeClassName(wrapper.name)}` : undefined;
+
+  const dataAttributes: Record<string, string> = {};
+  for (const [propertyName, value] of Object.entries(wrapper.properties)) {
+    dataAttributes[`data-markup-${propertyName}`] = String(value);
+  }
+
+  return React.createElement(
+    tagName,
+    {
+      key,
+      className,
+      ...dataAttributes,
+    },
+    children
+  );
+}
+
+function sanitizeClassName(name: string): string {
+  return name.toLowerCase().replace(/[^a-z0-9_-]/g, "-");
+}
+

package/src/react/TypingText.tsx

@@ -0,0 +1,127 @@
+import React, { useState, useEffect, useRef } from "react";
+import type { MarkupParseResult } from "../markup/types.js";
+import { MarkupRenderer } from "./MarkupRenderer.js";
+
+export interface TypingTextProps {
+  text: string;
+  markup?: MarkupParseResult;
+  typingSpeed?: number;
+  showCursor?: boolean;
+  cursorCharacter?: string;
+  cursorBlinkDuration?: number;
+  cursorClassName?: string;
+  className?: string;
+  onComplete?: () => void;
+  disabled?: boolean;
+}
+
+export function TypingText({
+  text,
+  markup,
+  typingSpeed = 100,
+  showCursor = true,
+  cursorCharacter = "|",
+  cursorBlinkDuration = 530,
+  cursorClassName = "",
+  className = "",
+  onComplete,
+  disabled = false,
+}: TypingTextProps) {
+  const [displayedLength, setDisplayedLength] = useState(disabled ? text.length : 0);
+  const [cursorVisible, setCursorVisible] = useState(true);
+  const cursorIntervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const typingTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const onCompleteRef = useRef(onComplete);
+  
+  useEffect(() => {
+    onCompleteRef.current = onComplete;
+  }, [onComplete]);
+
+  // Handle cursor blinking
+  useEffect(() => {
+    if (!showCursor || disabled) {
+      return;
+    }
+    cursorIntervalRef.current = setInterval(() => {
+      setCursorVisible((prev) => !prev);
+    }, cursorBlinkDuration);
+    return () => {
+      if (cursorIntervalRef.current) {
+        clearInterval(cursorIntervalRef.current);
+      }
+    };
+  }, [showCursor, cursorBlinkDuration, disabled]);
+
+  // Handle typing animation
+  useEffect(() => {
+    if (disabled) {
+      setDisplayedLength(text.length);
+      if (onCompleteRef.current && text.length > 0) {
+        onCompleteRef.current();
+      }
+      return;
+    }
+
+    // Reset when text changes
+    setDisplayedLength(0);
+
+    if (text.length === 0) {
+      if (onCompleteRef.current) {
+        onCompleteRef.current();
+      }
+      return;
+    }
+
+    let index = 0;
+    const typeNextCharacter = () => {
+      if (index < text.length) {
+        index += 1;
+        setDisplayedLength(index);
+        if (typingSpeed <= 0) {
+          requestAnimationFrame(typeNextCharacter);
+        } else {
+          typingTimeoutRef.current = setTimeout(typeNextCharacter, typingSpeed);
+        }
+      } else if (onCompleteRef.current) {
+        onCompleteRef.current();
+      }
+    };
+
+    if (typingSpeed <= 0) {
+      requestAnimationFrame(typeNextCharacter);
+    } else {
+      typingTimeoutRef.current = setTimeout(typeNextCharacter, typingSpeed);
+    }
+
+    return () => {
+      if (typingTimeoutRef.current) {
+        clearTimeout(typingTimeoutRef.current);
+      }
+    };
+  }, [text, disabled, typingSpeed]);
+
+  const visibleLength = markup ? Math.min(displayedLength, markup.text.length) : Math.min(displayedLength, text.length);
+
+  return (
+    <span className={className}>
+      <span>
+        {markup ? (
+          <MarkupRenderer text={text} markup={markup} length={visibleLength} />
+        ) : (
+          text.slice(0, visibleLength)
+        )}
+      </span>
+      {showCursor && !disabled && (
+        <span
+          className={`yd-typing-cursor ${cursorClassName}`}
+          style={{
+            opacity: cursorVisible ? 1 : 0,
+            transition: `opacity ${cursorBlinkDuration / 2}ms ease-in-out`,
+          }}
+        >
+          {cursorCharacter}
+        </span>
+      )}
+    </span>
+  );
+}