@rohal12/spindle 0.46.0 → 0.48.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rohal12/spindle",
-  "version": "0.46.0",
+  "version": "0.48.0",
   "type": "module",
   "description": "A Preact-based story format for Twine 2.",
   "license": "Unlicense",

package/src/components/Passage.tsx

@@ -1,10 +1,17 @@
-import { useMemo, useEffect, useState } from 'preact/hooks';
+import {
+  useMemo,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from 'preact/hooks';
 import { tokenize } from '../markup/tokenizer';
 import { buildAST } from '../markup/ast';
 import { renderNodes, NobrContext } from '../markup/render';
 import { useStoryStore } from '../store';
 import type { Passage as PassageData } from '../parser';
 import { sourceLocationOf } from '../utils/source-location';
+import { emitFromRender } from '../event-emitter';
 
 export function renderPassageContent(passage: PassageData) {
   const tokens = tokenize(passage.content);
@@ -90,10 +97,21 @@ export function Passage({ passage, dataTransition }: PassageProps) {
     }
   }, [doneReady, donePassage?.content]);
 
+  // Signal that this passage's DOM is committed (after descendants' layout
+  // effects, before paint). Runs once per mount: PassageDisplay keys the
+  // Passage so every navigation that shows a passage mounts a new one.
+  const elRef = useRef<HTMLDivElement>(null);
+  useLayoutEffect(() => {
+    if (elRef.current) {
+      emitFromRender('passagerender', passage.name, elRef.current);
+    }
+  }, [passage.name]);
+
   const nobr = passage.tags.includes('nobr');
 
   const inner = (
     <div
+      ref={elRef}
       class="passage"
       data-passage={passage.name}
       data-tags={passage.tags.join(' ')}

package/src/components/PassageDialog.tsx

@@ -1,9 +1,10 @@
 import { createContext } from 'preact';
-import { useCallback, useMemo, useRef } from 'preact/hooks';
+import { useCallback, useLayoutEffect, useMemo, useRef } from 'preact/hooks';
 import { tokenize } from '../markup/tokenizer';
 import { buildAST } from '../markup/ast';
 import { renderNodes } from '../markup/render';
 import { useStoryStore } from '../store';
+import { emitFromRender } from '../event-emitter';
 
 export const DialogCloseContext = createContext<(() => void) | null>(null);
 
@@ -59,6 +60,14 @@ export function PassageDialog({
     }
   }, [markup]);
 
+  // Signal that the dialog's DOM is committed (once per open).
+  const panelRef = useRef<HTMLDivElement>(null);
+  useLayoutEffect(() => {
+    if (panelRef.current) {
+      emitFromRender('dialogrender', passageName ?? '', panelRef.current);
+    }
+  }, []);
+
   const handleBackdrop = (e: MouseEvent) => {
     if (!dismissible) return;
     if ((e.target as HTMLElement).classList.contains('dialog-overlay')) {
@@ -74,7 +83,10 @@ export function PassageDialog({
         class="dialog-overlay"
         onClick={handleBackdrop}
       >
-        <div class={cls}>
+        <div
+          ref={panelRef}
+          class={cls}
+        >
           {showCloseButton && (
             <button
               class="dialog-close"

package/src/event-emitter.ts

@@ -14,6 +14,8 @@ type EventMap = {
   afterload: (slot: string | undefined) => void;
   beforenavigate: (passageName: string) => void;
   afternavigate: (to: string, from: string) => void;
+  passagerender: (passage: string, element: HTMLElement) => void;
+  dialogrender: (passage: string, element: HTMLElement) => void;
 };
 
 export type StoryEvent = keyof EventMap;
@@ -30,6 +32,8 @@ const VALID_EVENTS = new Set<string>([
   'afterload',
   'beforenavigate',
   'afternavigate',
+  'passagerender',
+  'dialogrender',
 ]);
 
 // Each event key maps to a Set of callbacks.
@@ -65,6 +69,26 @@ export function emit<E extends StoryEvent>(
   }
 }
 
+/**
+ * Emit an event from inside a render commit (layout effect). A throwing
+ * handler is logged instead of propagating into Preact and breaking the
+ * render; the remaining handlers still run.
+ */
+export function emitFromRender<E extends StoryEvent>(
+  event: E,
+  ...args: Parameters<EventMap[E]>
+): void {
+  const set = listeners.get(event);
+  if (!set) return;
+  for (const cb of [...set]) {
+    try {
+      (cb as Function)(...args);
+    } catch (err) {
+      console.error(`spindle: Error in ${event} handler:`, err);
+    }
+  }
+}
+
 /** Test-only: clear all listeners. */
 export function resetEmitter(): void {
   listeners = new Map();

package/src/index.tsx

@@ -3,7 +3,11 @@ import { App } from './components/App';
 import { parseStoryData } from './parser';
 import { useStoryStore, enterRuntimePhase } from './store';
 import { emit } from './event-emitter';
-import { installStoryAPI, getReadyPromise } from './story-api';
+import {
+  installStoryAPI,
+  getReadyPromise,
+  setDeclaredVariables,
+} from './story-api';
 import { resetIdCounters } from './action-registry';
 import { executeStoryInit } from './story-init';
 import { checkTriggers, reinitTriggerState } from './triggers';
@@ -118,6 +122,7 @@ function boot() {
   }
 
   defaults = extractDefaults(schema);
+  setDeclaredVariables(Object.keys(defaults), Object.keys(transientDefaults));
 
   useStoryStore.getState().init(storyData, defaults, transientDefaults);
 

package/src/story-api.ts

@@ -232,11 +232,63 @@ export interface StoryAPI {
   };
 }
 
+// Names declared in StoryVariables / StoryTransients, registered at boot.
+// null until a schema is registered (e.g. unit tests that init the store
+// directly), in which case Story.set() does not check names.
+let declaredVariables: ReadonlySet<string> | null = null;
+let declaredTransients: ReadonlySet<string> | null = null;
+const warnedUndeclared = new Set<string>();
+
+/** Register the declared variable names so Story.set() can flag typos. */
+export function setDeclaredVariables(
+  variables: Iterable<string>,
+  transients: Iterable<string> = [],
+): void {
+  declaredVariables = new Set(variables);
+  declaredTransients = new Set(transients);
+  warnedUndeclared.clear();
+}
+
+/** Test-only: forget the registered declarations. */
+export function _resetDeclaredVariables(): void {
+  declaredVariables = null;
+  declaredTransients = null;
+  warnedUndeclared.clear();
+}
+
+/**
+ * Split an API variable name into namespace and key. Accepts the bare name
+ * (`hp`), the `$` sigil authors use in passages (`$hp`), and `%` for
+ * transients (`%npcs`). Dot-paths are kept in the key.
+ */
+function parseName(name: string): {
+  isTransient: boolean;
+  key: string;
+} {
+  if (name.startsWith('%')) return { isTransient: true, key: name.slice(1) };
+  if (name.startsWith('$')) return { isTransient: false, key: name.slice(1) };
+  return { isTransient: false, key: name };
+}
+
+function warnIfUndeclared(isTransient: boolean, key: string): void {
+  const declared = isTransient ? declaredTransients : declaredVariables;
+  if (!declared) return;
+  const root = key.split('.')[0]!;
+  if (declared.has(root)) return;
+  const label = (isTransient ? '%' : '$') + root;
+  if (warnedUndeclared.has(label)) return;
+  warnedUndeclared.add(label);
+  const where = isTransient ? 'StoryTransients' : 'StoryVariables';
+  console.warn(
+    `spindle: Story.set() wrote ${label}, which is not declared in ${where}. Passages cannot reference it; check the name or declare it.`,
+  );
+}
+
 /** Set a single variable, resolving dot-paths if present. */
 function setOne(name: string, value: unknown): void {
-  const isTransient = name.startsWith('%');
-  const key = isTransient ? name.slice(1) : name;
+  const { isTransient, key } = parseName(name);
   const namespace = isTransient ? 'transient' : 'variables';
+  warnIfUndeclared(isTransient, key);
 
   if (key.includes('.')) {
     useStoryStore.setState((state) => {
@@ -255,8 +307,7 @@ function setOne(name: string, value: unknown): void {
 function createStoryAPI(): StoryAPI {
   return {
     get(name: string): unknown {
-      const isTransient = name.startsWith('%');
-      const key = isTransient ? name.slice(1) : name;
+      const { isTransient, key } = parseName(name);
       const store = isTransient
         ? useStoryStore.getState().transient
         : useStoryStore.getState().variables;

package/types/index.d.ts

@@ -138,6 +138,18 @@ export interface StoryEventMap {
   afterload: (slot: string | undefined) => void;
   beforenavigate: (passageName: string) => void;
   afternavigate: (to: string, from: string) => void;
+  /**
+   * A passage's `.passage` element was committed to the DOM (first render,
+   * navigation, back/forward, restart, load). Fires after the transition
+   * mounts the new passage, before paint.
+   */
+  passagerender: (passage: string, element: HTMLElement) => void;
+  /**
+   * A dialog was opened and its `.dialog-panel` element committed to the DOM.
+   * `passage` is the dialog's passage name (empty for built-in dialogs
+   * without one).
+   */
+  dialogrender: (passage: string, element: HTMLElement) => void;
 }
 
 /** Event name that can be passed to `Story.on()`. */