@rohal12/spindle 0.52.9 → 0.54.0

package/src/components/RuntimeErrors.tsx

@@ -0,0 +1,46 @@
+import { useEffect, useState } from 'preact/hooks';
+import {
+  dismissRuntimeError,
+  getRuntimeErrors,
+  subscribeRuntimeErrors,
+} from '../runtime-errors';
+
+/**
+ * The runtime errors shown on the page (see showRuntimeError): one banner
+ * each, announced to screen readers (role="alert"), until the player
+ * dismisses it. Style them with the `spindle-error-banner` classes.
+ */
+export function RuntimeErrors() {
+  const [errors, setErrors] = useState(getRuntimeErrors);
+  useEffect(() => {
+    setErrors(getRuntimeErrors());
+    return subscribeRuntimeErrors(() => setErrors(getRuntimeErrors()));
+  }, []);
+
+  if (errors.length === 0) return null;
+  return (
+    <div class="spindle-error-banners">
+      {errors.map((e) => (
+        <div
+          key={e.id}
+          class="spindle-error-banner"
+          role="alert"
+        >
+          <span class="spindle-error-banner-context">{e.context}</span>{' '}
+          <span class="spindle-error-banner-message">{e.message}</span>
+          {e.count > 1 && (
+            <span class="spindle-error-banner-count">{` (×${e.count})`}</span>
+          )}
+          <button
+            type="button"
+            class="spindle-error-banner-dismiss"
+            aria-label="Dismiss"
+            onClick={() => dismissRuntimeError(e.id)}
+          >
+            ✕
+          </button>
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/components/StoryInterface.tsx

@@ -1,7 +1,6 @@
 import { useMemo } from 'preact/hooks';
 import { useStoryFields } from '../hooks/use-story-fields';
-import { tokenize } from '../markup/tokenizer';
-import { buildAST } from '../markup/ast';
+import { parseMarkup } from '../markup/parse';
 import { renderInlineNodes, NobrContext } from '../markup/render';
 import { errorMessage } from '../utils/error-message';
 
@@ -18,8 +17,7 @@ export function StoryInterface() {
 
   const rendered = useMemo(() => {
     try {
-      const tokens = tokenize(markup);
-      const ast = buildAST(tokens);
+      const ast = parseMarkup(markup);
       return <>{renderInlineNodes(ast)}</>;
     } catch (err) {
       return (

package/src/components/macros/Computed.tsx

@@ -4,6 +4,7 @@ import { readState } from '../../execute-mutation';
 import { deepEqual } from '../../structural';
 import { defineMacro } from '../../define-macro';
 import { MacroError, logMacroError } from './MacroError';
+import { currentSourceLocation } from '../../utils/source-location';
 import { checkVariableName } from '../../utils/namespace';
 
 /**
@@ -54,13 +55,15 @@ function computeAndApply(
   prevRef: { current: unknown },
   localsUpdate: ((key: string, value: unknown) => void) | null,
 ): void {
+  // Before evaluating: the expression may navigate away from this passage
+  const location = currentSourceLocation();
   let newValue: unknown;
   try {
     // In program order, also when mutation code sets this off
     const { variables, temporary, transient } = readState();
     newValue = evaluate(expr, variables, temporary, getLocals(), transient);
   } catch (err) {
-    logMacroError(`computed ${rawArgs}`, err);
+    logMacroError(`computed ${rawArgs}`, err, location);
     return;
   }
 
@@ -70,7 +73,7 @@ function computeAndApply(
       try {
         localsUpdate!(name, newValue);
       } catch (err) {
-        logMacroError(`computed ${rawArgs}`, err);
+        logMacroError(`computed ${rawArgs}`, err, location);
       }
     } else {
       const state = useStoryStore.getState();

package/src/components/macros/Do.tsx

@@ -5,14 +5,16 @@ defineMacro({
   name: 'do',
   block: true,
   render({ children = [] }, ctx) {
-    // The tokenizer keeps the body verbatim as a single text node
+    // The parser keeps the body verbatim as a single text node
     const code = ctx.collectText(children);
 
     ctx.hooks.useLayoutEffect(() => {
+      // Before the code runs: it may navigate away from this passage
+      const location = ctx.sourceLocation();
       try {
         ctx.mutate(code);
       } catch (err) {
-        logMacroError('do', err);
+        logMacroError('do', err, location);
       }
     }, []);
 

package/src/components/macros/Goto.tsx

@@ -1,6 +1,7 @@
 import { useStoryStore } from '../../store';
 import { defineMacro } from '../../define-macro';
 import { evaluatePassageName } from './macro-args';
+import { logMacroError } from './MacroError';
 
 defineMacro({
   name: 'goto',
@@ -8,9 +9,18 @@ defineMacro({
   parameters: [{ name: 'passage', type: 'expression', required: true }],
   render(_props, ctx) {
     ctx.hooks.useLayoutEffect(() => {
-      useStoryStore
-        .getState()
-        .navigate(evaluatePassageName(ctx.args.passage, ctx.evaluate!));
+      // Reported like an error in {do}: thrown out of an effect, it would
+      // abort the rest of the render's effects (e.g. the session could not
+      // be written because the state holds a function). The location is
+      // this passage's, taken before navigating away from it
+      const location = ctx.sourceLocation();
+      try {
+        useStoryStore
+          .getState()
+          .navigate(evaluatePassageName(ctx.args.passage, ctx.evaluate!));
+      } catch (err) {
+        logMacroError('goto', err, location);
+      }
     }, []);
 
     return null;

package/src/components/macros/Include.tsx

@@ -1,7 +1,6 @@
 import { useStoryStore } from '../../store';
 import { useStoryFields } from '../../hooks/use-story-fields';
-import { tokenize } from '../../markup/tokenizer';
-import { buildAST } from '../../markup/ast';
+import { parseMarkup } from '../../markup/parse';
 import { NobrContext } from '../../markup/render';
 import { defineMacro } from '../../define-macro';
 import { evaluatePassageName } from './macro-args';
@@ -28,7 +27,7 @@ defineMacro({
     // included passage changes, while re-renders of the same passage keep
     // its macros mounted (#175).
     const ast = ctx.hooks.useMemo(
-      () => (passage ? buildAST(tokenize(passage.content)) : null),
+      () => (passage ? parseMarkup(passage.content) : null),
       [passage],
     );
 

package/src/components/macros/MacroError.tsx

@@ -19,12 +19,18 @@ export function MacroError({
   );
 }
 
-/** Log an error in the macro `{label}` (its name, or name and arguments). */
-export function logMacroError(label: string, error: unknown): void {
-  console.error(
-    `spindle: Error in {${label}}${currentSourceLocation()}:`,
-    error,
-  );
+/**
+ * Log an error in the macro `{label}` (its name, or name and arguments) at
+ * `location`, the source location of the macro's passage. Take it before
+ * running the code that failed (see currentSourceLocation): code that
+ * navigates changes the current passage.
+ */
+export function logMacroError(
+  label: string,
+  error: unknown,
+  location: string = currentSourceLocation(),
+): void {
+  console.error(`spindle: Error in {${label}}${location}:`, error);
 }
 
 /**
@@ -38,11 +44,12 @@ export function useRunOnce(macro: string, rawArgs: string, effect: () => void) {
   const failure = useRef<{ error: unknown } | null>();
   if (failure.current === undefined) {
     failure.current = null;
+    const location = currentSourceLocation();
     try {
       effect();
     } catch (error) {
       failure.current = { error };
-      logMacroError(`${macro} ${rawArgs}`, error);
+      logMacroError(`${macro} ${rawArgs}`, error, location);
     }
   }
 

package/src/components/macros/SaveManager.tsx

@@ -17,7 +17,7 @@ import {
   renameSave,
   exportSave,
   importSave,
-  deserializePayload,
+  decodeSavePayload,
   saveWithHooks,
   type PlaythroughGroup,
 } from '../../saves/save-manager';
@@ -160,7 +160,7 @@ export function SaveManagerContent() {
       // Stored records hold serialized variables; the store expects live
       // ones. The game moves to the save's playthrough.
       loadFromPayload(
-        deserializePayload(save.payload),
+        decodeSavePayload(save.payload),
         undefined,
         save.meta.playthroughId,
       );

package/src/components/macros/VarDisplay.tsx

@@ -3,7 +3,7 @@ import { useContext } from 'preact/hooks';
 import { LocalsValuesContext } from '../../markup/render';
 import { useInterpolate } from '../../hooks/use-interpolate';
 import { ownValue, variableNameError } from '../../utils/namespace';
-import { SCOPE_SIGILS } from '../../markup/tokenizer';
+import { SCOPE_SIGILS } from '../../markup/tokens';
 import type { VariableNode } from '../../markup/ast';
 import { display, wrapContent } from './display';
 

package/src/components/macros/Widget.tsx

@@ -4,39 +4,11 @@ import { registerBlockMacro, type ASTNode } from '../../markup/ast';
 import { defineMacro } from '../../define-macro';
 import { checkVariableName } from '../../utils/namespace';
 import { MacroError } from './MacroError';
-import { parseMacroArgs } from './macro-args';
-import type { MacroArgs } from '../../registry';
-
-/** A {widget} definition's name, then its `@` parameters. */
-const WIDGET_PARAMETERS = [
-  { name: 'name', type: 'text', required: true },
-  { name: 'parameters', type: 'expression' },
-] as const;
-
-interface WidgetDef {
-  name: string;
-  params: string[];
-}
-
-/**
- * The widget a {widget} definition's arguments declare: its name and its
- * parameters, the words after it that start with `@` (docs/widgets.md).
- * Other words, such as `$name`, are not parameters.
- */
-function widgetDef({
-  name = '',
-  parameters = '',
-}: MacroArgs<typeof WIDGET_PARAMETERS>): WidgetDef {
-  return {
-    name,
-    params: parameters.split(/\s+/).filter((word) => word.startsWith('@')),
-  };
-}
-
-/** Read the arguments of a {widget} definition (see widgetDef). */
-export function parseWidgetDef(rawArgs: string): WidgetDef {
-  return widgetDef(parseMacroArgs(rawArgs, WIDGET_PARAMETERS));
-}
+import {
+  WIDGET_PARAMETERS,
+  widgetDef,
+  type WidgetDef,
+} from '../../widgets/widget-def';
 
 /**
  * Register the widget a definition declares, with its body. Widgets whose

package/src/index.tsx

@@ -1,6 +1,6 @@
 import { render } from 'preact';
 import { App } from './components/App';
-import { parseStoryData } from './parser';
+import { parseStoryData, type StoryData } from './parser';
 import { useStoryStore, enterRuntimePhase } from './store';
 import {
   installStoryAPI,
@@ -16,10 +16,17 @@ import {
   validatePassages,
   extractDefaults,
 } from './story-variables';
-import { getMacroRegistry } from './registry';
-import { tokenize } from './markup/tokenizer';
-import { buildAST, registerBlockMacro } from './markup/ast';
-import { parseWidgetDef, registerWidgetDef } from './components/macros/Widget';
+import { getMacro, getMacroRegistry, isSubMacro } from './registry';
+import { getWidget } from './widgets/widget-registry';
+import {
+  formatDiagnostic,
+  validateMarkup,
+  type MarkupPassage,
+} from './markup/validate';
+import { blockWidgetNames, parseWidgetDef } from './widgets/widget-def';
+import { parseMarkup } from './markup/parse';
+import { registerBlockMacro } from './markup/ast';
+import { registerWidgetDef } from './components/macros/Widget';
 import { errorMessage } from './utils/error-message';
 import type { ASTNode } from './markup/ast';
 import './macros/register-builtins';
@@ -45,10 +52,36 @@ function renderErrors(root: HTMLElement, errors: string[]) {
   root.appendChild(container);
 }
 
+/** Show the validation errors instead of the story, and stop booting. */
+function stopWithErrors(errors: string[]): never {
+  const root = document.getElementById('root');
+  if (root) renderErrors(root, errors);
+  throw new Error(
+    `spindle: ${errors.length} validation error(s):\n${errors.join('\n')}`,
+  );
+}
+
+/**
+ * The markup errors (malformed markup, unknown macros) of the passages for
+ * which `only` holds, with the macros and widgets known now.
+ */
+function markupErrors(
+  storyData: StoryData,
+  only: (passage: MarkupPassage) => boolean,
+): string[] {
+  return validateMarkup(storyData.passages.values(), {
+    isKnownMacro: (name) =>
+      !!getMacro(name) || isSubMacro(name) || !!getWidget(name),
+    macroNames: getMacroRegistry().map((m) => m.name),
+    only,
+  }).map(formatDiagnostic);
+}
+
 /**
  * Boot Spindle in the current document: parse `<tw-storydata>`, install the
- * `Story` API, run author JavaScript, validate `StoryVariables`, run
- * `StoryInit`, and render into `#root`. Dispatches `:storyready` when the
+ * `Story` API, run author JavaScript, validate `StoryVariables` and
+ * `StoryInit`'s markup, run `StoryInit`, validate the other passages' markup
+ * (with the macros StoryInit defined), and render into `#root`. Dispatches `:storyready` when the
  * first passage is shown. Call once per page (module state is global).
  * The browser story format calls it from `main.tsx`.
  */
@@ -101,7 +134,18 @@ export function boot() {
   const storeVarMacros = getMacroRegistry()
     .filter((m) => m.storeVar)
     .map((m) => m.name);
+  // Pass 1: Register the block widgets as block macros BEFORE any passage
+  // is parsed (validation and StoryInit included), so that passages
+  // invoking block widgets and widget bodies using other block widgets
+  // parse correctly regardless of passage or definition order.
+  for (const name of blockWidgetNames(storyData.passages.values())) {
+    registerBlockMacro(name);
+  }
+
   const errors = validatePassages(storyData.passages, schema, storeVarMacros);
+  // StoryInit's markup must be valid before it runs; the other passages are
+  // validated once it has run, as it may define macros (see below).
+  errors.push(...markupErrors(storyData, (p) => p.name === 'StoryInit'));
 
   // Parse StoryTransients (optional — no error if missing)
   let transientDefaults: Record<string, unknown> = {};
@@ -124,13 +168,7 @@ export function boot() {
     transientDefaults = extractDefaults(transientSchema);
   }
 
-  if (errors.length > 0) {
-    const root = document.getElementById('root');
-    if (root) renderErrors(root, errors);
-    throw new Error(
-      `spindle: ${errors.length} validation error(s):\n${errors.join('\n')}`,
-    );
-  }
+  if (errors.length > 0) stopWithErrors(errors);
 
   defaults = extractDefaults(schema);
   setDeclaredVariables(Object.keys(defaults), Object.keys(transientDefaults));
@@ -140,36 +178,18 @@ export function boot() {
   // Enter runtime phase — handlers registered from here on are cleaned on restart
   enterRuntimePhase();
 
-  // Pass 1: Pre-scan StoryInit and all widget passages to discover block
-  // widgets. Register them as block macros BEFORE any tokenize/buildAST
-  // calls (StoryInit's included), so that passages invoking block widgets
-  // and widget bodies using other block widgets parse correctly regardless
-  // of passage or definition order.
-  const blockWidgetPattern =
-    /\{widget\s+["']?(\w+)["']?[^}]*\}([\s\S]*?)\{\/widget\}/g;
-  for (const [passageName, passage] of storyData.passages) {
-    if (passageName === 'StoryInit' || passage.tags.includes('widget')) {
-      let match;
-      while ((match = blockWidgetPattern.exec(passage.content)) !== null) {
-        const name = match[1]!;
-        const body = match[2]!;
-        if (/\{@children\}/.test(body)) {
-          registerBlockMacro(name);
-        }
-      }
-      blockWidgetPattern.lastIndex = 0;
-    }
-  }
-
   // Run StoryInit, restore the session if the page was refreshed, and fire
   // storyinit after all state is settled (defaults + StoryInit + session)
   initializeStory(loadSession(storyData.ifid));
 
+  // Every other passage's markup, now that StoryInit may have defined macros
+  const markup = markupErrors(storyData, (p) => p.name !== 'StoryInit');
+  if (markup.length > 0) stopWithErrors(markup);
+
   // Pass 2: Full parse and register widgets from passages tagged "widget"
   for (const [, passage] of storyData.passages) {
     if (passage.tags.includes('widget')) {
-      const widgetTokens = tokenize(passage.content);
-      const widgetAST = buildAST(widgetTokens);
+      const widgetAST = parseMarkup(passage.content);
       for (const node of widgetAST) {
         if (node.type === 'macro' && node.name === 'widget' && node.rawArgs) {
           // Read and registered as the {widget} macro does

package/src/interpolation.ts

@@ -3,7 +3,7 @@
  * and macro labels resolve the inline markup of passage text (variables,
  * expressions, macros, widgets) to a string.
  *
- * Such a value is parsed with the passage tokenizer in text mode, so `{…}`
+ * Such a value is parsed with the passage parser in text mode, so `{…}`
  * means the same as in passage text, and its AST is evaluated directly to a
  * string rather than rendered: the result is ready during the render that
  * needs it (so it goes through the usual attribute handling, boolean
@@ -17,11 +17,10 @@ import { evaluate } from './expression';
 import {
   SCOPE_SIGILS,
   SIGIL_SCOPES,
-  tokenize,
   type VariableScope,
-} from './markup/tokenizer';
+} from './markup/tokens';
 import type { Sigil } from './js-lexer';
-import { buildAST } from './markup/ast';
+import { parseMarkup } from './markup/parse';
 import type { ASTNode, MacroNode, TextNode } from './markup/ast';
 import { getMacro, getMacroText, isSubMacro } from './registry';
 import type { MacroTextContext } from './registry';
@@ -76,7 +75,7 @@ export function parseText(template: string): ParsedText {
   let parsed = parseCache.get(template);
   if (parsed === undefined) {
     try {
-      parsed = { nodes: buildAST(tokenize(template, { text: true })) };
+      parsed = { nodes: parseMarkup(template, { text: true }) };
     } catch (error) {
       parsed = { error };
     }