@rohal12/spindle 0.52.2 → 0.52.4

package/package.json

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

package/src/components/App.tsx

@@ -1,13 +1,16 @@
 import { useEffect } from 'preact/hooks';
 import { useStoryStore } from '../store';
+import { useStoryFields } from '../hooks/use-story-fields';
 import { NobrContext } from '../markup/render';
 import { StoryInterface } from './StoryInterface';
 import { TriggerDialogHost } from './TriggerDialogHost';
 
 export function App() {
-  const storyData = useStoryStore((s) => s.storyData);
-  const currentPassage = useStoryStore((s) => s.currentPassage);
-  const nobr = useStoryStore((s) => s.nobr);
+  const { storyData, currentPassage, nobr } = useStoryFields(
+    'storyData',
+    'currentPassage',
+    'nobr',
+  );
 
   useEffect(() => {
     const onKeyDown = (e: KeyboardEvent) => {

package/src/components/macros/ExprDisplay.tsx

@@ -1,8 +1,6 @@
-import { useContext } from 'preact/hooks';
-import { useStoryStore } from '../../store';
 import { evaluate } from '../../expression';
-import { LocalsValuesContext } from '../../markup/render';
 import { useInterpolate } from '../../hooks/use-interpolate';
+import { useMergedLocals } from '../../hooks/use-merged-locals';
 
 interface ExprDisplayProps {
   expression: string;
@@ -14,10 +12,7 @@ export function ExprDisplay({ expression, className, id }: ExprDisplayProps) {
   const resolve = useInterpolate();
   className = resolve(className);
   id = resolve(id);
-  const localsValues = useContext(LocalsValuesContext);
-  const variables = useStoryStore((s) => s.variables);
-  const temporary = useStoryStore((s) => s.temporary);
-  const transient = useStoryStore((s) => s.transient);
+  const [variables, temporary, localsValues, transient] = useMergedLocals();
 
   let display: string;
   try {

package/src/components/macros/MenubarButtons.tsx

@@ -1,5 +1,6 @@
 import { useState } from 'preact/hooks';
 import { useStoryStore } from '../../store';
+import { useStoryFields } from '../../hooks/use-story-fields';
 import { settings } from '../../settings';
 import { defineMacro } from '../../define-macro';
 import { PassageDialog } from '../PassageDialog';
@@ -108,13 +109,10 @@ defineMenubarAction({
   name: 'quicksave',
   label: 'QuickSave',
   actionType: 'save',
-  setup: () => ({
-    perform: useStoryStore((s) => s.save),
-    title: hotkeyTitle(
-      'Quick Save',
-      useStoryStore((s) => s.quickSaveKey),
-    ),
-  }),
+  setup: () => {
+    const { save, quickSaveKey } = useStoryFields('save', 'quickSaveKey');
+    return { perform: save, title: hotkeyTitle('Quick Save', quickSaveKey) };
+  },
 });
 
 defineMenubarAction({
@@ -123,14 +121,17 @@ defineMenubarAction({
   actionType: 'load',
   confirm: 'Load saved game? Current progress will be lost.',
   setup: () => {
-    const load = useStoryStore((s) => s.load);
-    const hasSave = useStoryStore((s) => s.hasSave);
-    const key = useStoryStore((s) => s.quickLoadKey);
-    useStoryStore((s) => s.knownSaves);
+    // knownSaves: re-render when the saves change, as hasSave() reads them
+    const { load, hasSave, quickLoadKey } = useStoryFields(
+      'load',
+      'hasSave',
+      'quickLoadKey',
+      'knownSaves',
+    );
     return {
       perform: () => load(),
       disabled: !hasSave(),
-      title: hotkeyTitle('Quick Load', key),
+      title: hotkeyTitle('Quick Load', quickLoadKey),
     };
   },
 });

package/src/components/macros/PassageDisplay.tsx

@@ -1,5 +1,6 @@
 import { useRef, useEffect, useCallback, useState } from 'preact/hooks';
 import { useStoryStore } from '../../store';
+import { useStoryFields } from '../../hooks/use-story-fields';
 import { Passage, renderPassageContent } from '../Passage';
 import { defineMacro } from '../../define-macro';
 import { resolveTransition, type ResolvedTransition } from '../../transition';
@@ -69,10 +70,13 @@ defineMacro({
   name: 'passage',
   interpolate: true,
   render(_props, ctx) {
-    const currentPassage = useStoryStore((s) => s.currentPassage);
-    const navigationId = useStoryStore((s) => s.navigationId);
-    const storyData = useStoryStore((s) => s.storyData);
-    const renderDeferred = useStoryStore((s) => s.renderDeferred);
+    const { currentPassage, navigationId, storyData, renderDeferred } =
+      useStoryFields(
+        'currentPassage',
+        'navigationId',
+        'storyData',
+        'renderDeferred',
+      );
 
     // Render-gating: displayed controls which passage is visually shown.
     // The store updates immediately, but the visual swap is deferred by the

package/src/components/macros/SaveManager.tsx

@@ -6,6 +6,7 @@ import {
   useContext,
 } from 'preact/hooks';
 import { useStoryStore, resolvePlaythroughId } from '../../store';
+import { useStoryFields } from '../../hooks/use-story-fields';
 import { isSaveExport, type SaveRecord } from '../../saves/types';
 import {
   getSavesGrouped,
@@ -61,10 +62,13 @@ export function SaveManagerContent() {
 
   const closeDialog = useContext(DialogCloseContext);
 
-  const storyData = useStoryStore((s) => s.storyData);
-  const playthroughId = useStoryStore((s) => s.playthroughId);
-  const beginSave = useStoryStore((s) => s.beginSave);
-  const loadFromPayload = useStoryStore((s) => s.loadFromPayload);
+  const { storyData, playthroughId, beginSave, loadFromPayload } =
+    useStoryFields(
+      'storyData',
+      'playthroughId',
+      'beginSave',
+      'loadFromPayload',
+    );
   const ifid = storyData?.ifid ?? '';
 
   const refresh = useCallback(async () => {

package/src/components/macros/VarDisplay.tsx

@@ -2,7 +2,7 @@ import { useStoryStore } from '../../store';
 import { useContext } from 'preact/hooks';
 import { LocalsValuesContext } from '../../markup/render';
 import { useInterpolate } from '../../hooks/use-interpolate';
-import { RESERVED_NAME, ownValue } from '../../utils/namespace';
+import { ownValue, variableNameError } from '../../utils/namespace';
 
 const SIGILS = {
   variable: '$',
@@ -11,6 +11,12 @@ const SIGILS = {
   transient: '%',
 } as const;
 
+const STORE_NAMESPACES = {
+  variable: 'variables',
+  temporary: 'temporary',
+  transient: 'transient',
+} as const;
+
 interface VarDisplayProps {
   name: string;
   scope: 'variable' | 'temporary' | 'local' | 'transient';
@@ -27,20 +33,13 @@ export function VarDisplay({ name, scope, className, id }: VarDisplayProps) {
   const root = parts[0]!;
   // Own entries only, as the expression engine reads them
   const storeValue = useStoryStore((s) =>
-    scope === 'variable'
-      ? ownValue(s.variables, root)
-      : scope === 'temporary'
-        ? ownValue(s.temporary, root)
-        : scope === 'transient'
-          ? ownValue(s.transient, root)
-          : undefined,
+    scope === 'local' ? undefined : ownValue(s[STORE_NAMESPACES[scope]], root),
   );
 
-  if (root === RESERVED_NAME) {
+  const nameError = variableNameError(root, SIGILS[scope] + root);
+  if (nameError) {
     return (
-      <span class="error">
-        {`{${SIGILS[scope]}${name} error: "${SIGILS[scope]}${root}" cannot be used as a variable name (${RESERVED_NAME} is reserved)}`}
-      </span>
+      <span class="error">{`{${SIGILS[scope]}${name} error: ${nameError}}`}</span>
     );
   }
 

package/src/components/macros/Widget.tsx

@@ -5,12 +5,20 @@ import { defineMacro } from '../../define-macro';
 import { checkVariableName } from '../../utils/namespace';
 import { MacroError } from './MacroError';
 
-function parseWidgetDef(rawArgs: string): { name: string; params: string[] } {
-  const tokens = rawArgs.trim().split(/\s+/);
-  const name = tokens[0]!.replace(/["']/g, '');
-  const params = tokens.slice(1).filter((t) => t.startsWith('@'));
-  for (const param of params) checkVariableName(param.slice(1), param);
-  return { name, params };
+/**
+ * Read the arguments of a {widget} definition: its name (quotes dropped)
+ * and its parameters, the words after it that start with one of the
+ * characters of `sigils`.
+ */
+export function parseWidgetDef(
+  rawArgs: string,
+  sigils = '@',
+): { name: string; params: string[] } {
+  const [first, ...rest] = rawArgs.trim().split(/\s+/);
+  return {
+    name: first!.replace(/["']/g, ''),
+    params: rest.filter((word) => sigils.includes(word[0]!)),
+  };
 }
 
 defineMacro({
@@ -20,7 +28,10 @@ defineMacro({
     let parsed: ReturnType<typeof parseWidgetDef> | undefined;
     let error: unknown;
     try {
-      parsed = parseWidgetDef(rawArgs);
+      // Refuse `@` parameters that no namespace can hold
+      const def = parseWidgetDef(rawArgs);
+      for (const param of def.params) checkVariableName(param.slice(1), param);
+      parsed = def;
     } catch (err) {
       error = err;
     }

package/src/event-emitter.ts

@@ -57,16 +57,22 @@ export function on<E extends StoryEvent>(
   };
 }
 
-export function emit<E extends StoryEvent>(
-  event: E,
-  ...args: Parameters<EventMap[E]>
+/** Call `call` with each listener of `event`. */
+function forEachListener(
+  event: StoryEvent,
+  call: (cb: Function) => void,
 ): void {
   const set = listeners.get(event);
   if (!set) return;
   // Snapshot to tolerate unsubscription during iteration
-  for (const cb of [...set]) {
-    (cb as Function)(...args);
-  }
+  for (const cb of [...set]) call(cb);
+}
+
+export function emit<E extends StoryEvent>(
+  event: E,
+  ...args: Parameters<EventMap[E]>
+): void {
+  forEachListener(event, (cb) => cb(...args));
 }
 
 /**
@@ -78,15 +84,13 @@ 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]) {
+  forEachListener(event, (cb) => {
     try {
-      (cb as Function)(...args);
+      cb(...args);
     } catch (err) {
       console.error(`spindle: Error in ${event} handler:`, err);
     }
-  }
+  });
 }
 
 /** Test-only: clear all listeners. */

package/src/expression.ts

@@ -5,12 +5,13 @@ import { random, randomInt } from './prng';
 import { lexJs, type JsGoal, type Sigil } from './js-lexer';
 import {
   EMPTY_NAMESPACE,
-  RESERVED_NAME,
   asNamespace,
+  countOf,
   isNamespace,
+  variableNameError,
+  type Counts,
   type Namespace,
 } from './utils/namespace';
-import { countOf, type Counts } from './utils/counts';
 
 interface ExpressionFns {
   currentPassage: () => Passage | undefined;
@@ -73,11 +74,8 @@ export function transform(expr: string, goal: JsGoal = 'expression'): string {
         result += text;
       },
       variable(sigil, name) {
-        if (name === RESERVED_NAME) {
-          throw new SyntaxError(
-            `spindle: "${sigil}${name}" cannot be used as a variable name (${RESERVED_NAME} is reserved)`,
-          );
-        }
+        const error = variableNameError(name, sigil + name);
+        if (error) throw new SyntaxError(`spindle: ${error}`);
         // `typeof%x` needs a space once `%x` turns into an identifier.
         if (IDENT_END_RE.test(result.slice(-2))) result += ' ';
         result += `${NAMESPACES[sigil]}["${name}"]`;
@@ -116,6 +114,35 @@ function getOrCompile(key: string, body: string): CompiledExpression {
   return fn;
 }
 
+/** The passage being shown. */
+export function currentPassage(): Passage | undefined {
+  const s = useStoryStore.getState();
+  return s.storyData?.passages.get(s.currentPassage);
+}
+
+/** The passage shown before the current one in history. */
+export function previousPassage(): Passage | undefined {
+  const s = useStoryStore.getState();
+  if (s.historyIndex <= 0) return undefined;
+  const prevName = s.history[s.historyIndex - 1]?.passage;
+  return prevName ? s.storyData?.passages.get(prevName) : undefined;
+}
+
+/**
+ * visited()/rendered() and their has-forms, counting in the counters
+ * `counts()` returns. A missing name means the current passage.
+ */
+export function countQueries(counts: () => Counts) {
+  const count = (name?: string): number =>
+    countOf(counts(), name ?? useStoryStore.getState().currentPassage);
+  return {
+    count,
+    has: (name?: string): boolean => count(name) > 0,
+    any: (...names: string[]): boolean => names.some((n) => count(n) > 0),
+    all: (...names: string[]): boolean => names.every((n) => count(n) > 0),
+  };
+}
+
 let cachedFns: ExpressionFns | null = null;
 let cachedVisitCounts: Counts | null = null;
 let cachedRenderCounts: Counts | null = null;
@@ -132,44 +159,19 @@ export function buildExpressionFns() {
     return cachedFns;
   }
 
-  const visited = (name?: string): number =>
-    countOf(visitCounts, name ?? useStoryStore.getState().currentPassage);
-  const hasVisited = (name?: string): boolean => visited(name) > 0;
-  const hasVisitedAny = (...names: string[]): boolean =>
-    names.some((n) => visited(n) > 0);
-  const hasVisitedAll = (...names: string[]): boolean =>
-    names.every((n) => visited(n) > 0);
-
-  const rendered = (name?: string): number =>
-    countOf(renderCounts, name ?? useStoryStore.getState().currentPassage);
-  const hasRendered = (name?: string): boolean => rendered(name) > 0;
-  const hasRenderedAny = (...names: string[]): boolean =>
-    names.some((n) => rendered(n) > 0);
-  const hasRenderedAll = (...names: string[]): boolean =>
-    names.every((n) => rendered(n) > 0);
-
-  const currentPassage = (): Passage | undefined => {
-    const s = useStoryStore.getState();
-    return s.storyData?.passages.get(s.currentPassage);
-  };
-  const previousPassage = (): Passage | undefined => {
-    const s = useStoryStore.getState();
-    if (s.historyIndex <= 0) return undefined;
-    const prevName = s.history[s.historyIndex - 1]?.passage;
-    return prevName ? s.storyData?.passages.get(prevName) : undefined;
-  };
-
+  const visits = countQueries(() => visitCounts);
+  const renders = countQueries(() => renderCounts);
   cachedFns = {
     currentPassage,
     previousPassage,
-    visited,
-    hasVisited,
-    hasVisitedAny,
-    hasVisitedAll,
-    rendered,
-    hasRendered,
-    hasRenderedAny,
-    hasRenderedAll,
+    visited: visits.count,
+    hasVisited: visits.has,
+    hasVisitedAny: visits.any,
+    hasVisitedAll: visits.all,
+    rendered: renders.count,
+    hasRendered: renders.has,
+    hasRenderedAny: renders.any,
+    hasRenderedAll: renders.all,
     random,
     randomInt,
   };

package/src/hooks/use-merged-locals.ts

@@ -1,5 +1,5 @@
 import { useContext, useMemo } from 'preact/hooks';
-import { useStoryStore } from '../store';
+import { useStoryFields } from './use-story-fields';
 import { LocalsValuesContext } from '../markup/render';
 
 /**
@@ -12,9 +12,11 @@ export function useMergedLocals(): readonly [
   Record<string, unknown>,
   Record<string, unknown>,
 ] {
-  const variables = useStoryStore((s) => s.variables);
-  const temporary = useStoryStore((s) => s.temporary);
-  const transient = useStoryStore((s) => s.transient);
+  const { variables, temporary, transient } = useStoryFields(
+    'variables',
+    'temporary',
+    'transient',
+  );
   const localsValues = useContext(LocalsValuesContext);
 
   return useMemo(() => {

package/src/hooks/use-story-fields.ts

@@ -0,0 +1,19 @@
+import { useRef } from 'preact/hooks';
+import { shallow } from 'zustand/vanilla/shallow';
+import { useStoryStore, type StoryState } from '../store';
+
+/**
+ * Story state fields `keys`, re-rendering when any of them changes (as one
+ * useStoryStore() selector per field would). The result keeps its identity
+ * while the fields don't change, as the store's snapshot must.
+ */
+export function useStoryFields<K extends keyof StoryState>(
+  ...keys: K[]
+): Pick<StoryState, K> {
+  const prev = useRef<Pick<StoryState, K>>();
+  return useStoryStore((s) => {
+    const next = {} as Pick<StoryState, K>;
+    for (const key of keys) next[key] = s[key];
+    return shallow(prev.current, next) ? prev.current! : (prev.current = next);
+  });
+}

package/src/index.tsx

@@ -21,6 +21,7 @@ import { tokenize } from './markup/tokenizer';
 import { buildAST, registerBlockMacro } from './markup/ast';
 import { registerWidget } from './widgets/widget-registry';
 import { astContainsChildren } from './widgets/ast-scanner';
+import { parseWidgetDef } from './components/macros/Widget';
 import { errorMessage } from './utils/error-message';
 import type { ASTNode } from './markup/ast';
 import './macros/register-builtins';
@@ -173,14 +174,10 @@ export function boot() {
       const widgetAST = buildAST(widgetTokens);
       for (const node of widgetAST) {
         if (node.type === 'macro' && node.name === 'widget' && node.rawArgs) {
-          const tokens2 = node.rawArgs.trim().split(/\s+/);
-          const widgetName = tokens2[0]!.replace(/["']/g, '');
-          const params = tokens2
-            .slice(1)
-            .filter(
-              (t) =>
-                t.startsWith('$') || t.startsWith('_') || t.startsWith('@'),
-            );
+          const { name: widgetName, params } = parseWidgetDef(
+            node.rawArgs,
+            '$_@',
+          );
           const children = node.children as ASTNode[];
           const isBlock = astContainsChildren(children);
           try {

package/src/interpolation.ts

@@ -14,7 +14,13 @@
  * string, so it is reported instead of being run or shown as source.
  */
 import { evaluate } from './expression';
-import { tokenize } from './markup/tokenizer';
+import {
+  SCOPE_SIGILS,
+  SIGIL_SCOPES,
+  tokenize,
+  type VariableScope,
+} from './markup/tokenizer';
+import type { Sigil } from './js-lexer';
 import { buildAST } from './markup/ast';
 import type { ASTNode, MacroNode, TextNode } from './markup/ast';
 import { getMacro, getMacroText, isSubMacro } from './registry';
@@ -116,15 +122,6 @@ function display(value: unknown): string {
   return value == null ? '' : String(value);
 }
 
-type VariableKind = 'variable' | 'temporary' | 'local' | 'transient';
-
-const KIND_SIGILS = {
-  variable: '$',
-  temporary: '_',
-  local: '@',
-  transient: '%',
-} as const;
-
 /**
  * The value of a variable reference (`name` without its sigil, with an
  * optional dot path), as `{$name}` shows it in passage text (see
@@ -133,12 +130,12 @@ const KIND_SIGILS = {
  */
 function resolveVariable(
   scope: TextScope,
-  kind: VariableKind,
+  kind: VariableScope,
   name: string,
 ): unknown {
   const parts = name.split('.');
   const root = parts[0]!;
-  checkVariableName(root, KIND_SIGILS[kind] + root);
+  checkVariableName(root, SCOPE_SIGILS[kind] + root);
   const store =
     kind === 'variable'
       ? scope.variables
@@ -210,12 +207,16 @@ class TextEvaluator {
   }
 
   /** A variable reference, or '' and an error if it can't be one. */
-  private variable(kind: VariableKind, name: string, scope: TextScope): string {
+  private variable(
+    kind: VariableScope,
+    name: string,
+    scope: TextScope,
+  ): string {
     try {
       return display(resolveVariable(scope, kind, name));
     } catch (error) {
       // Reported as passage text reports it: `{$__proto__ error: …}`
-      this.errors.push({ macro: KIND_SIGILS[kind] + name, error });
+      this.errors.push({ macro: SCOPE_SIGILS[kind] + name, error });
       return '';
     }
   }
@@ -341,13 +342,6 @@ export function interpolateText(
   return renderText(parsed.nodes, scope);
 }
 
-const SIGIL_KINDS = {
-  $: 'variable',
-  _: 'temporary',
-  '@': 'local',
-  '%': 'transient',
-} as const;
-
 /**
  * Resolve the sigil references in the value of a code attribute (see
  * isCodeAttribute): `{$x}`, `{_x.y}`, `{$n + 1}`. Everything else, other
@@ -367,7 +361,7 @@ export function interpolateCode(
     } else if ('verbatim' in part) {
       text += part.verbatim;
     } else if (/^[$_@%][\w.]+$/.test(part.expr)) {
-      const kind = SIGIL_KINDS[part.expr[0] as keyof typeof SIGIL_KINDS];
+      const kind = SIGIL_SCOPES[part.expr[0] as Sigil];
       try {
         text += display(resolveVariable(scope, kind, part.expr.slice(1)));
       } catch (error) {

package/src/js-lexer.ts

@@ -145,15 +145,14 @@ function scanRegex(
   };
   let i = start + 1;
   while (i < src.length) {
+    // Unterminated at the end of the line: leave the rest to the parser
+    const lineEnd = regexLineEnd(src, i);
+    if (lineEnd !== -1) return done(lineEnd, false);
     const c = src.charAt(i);
     if (c === '\\') {
-      // An escaped line break ends the line, and the regex, too
-      if (LINE_TERMINATOR_RE.test(src.charAt(i + 1))) return done(i + 1, false);
       i += 2;
       continue;
     }
-    // Unterminated at the end of the line: leave the rest to the parser
-    if (LINE_TERMINATOR_RE.test(c)) return done(i, false);
     if (c === '[') {
       // A class, where `/` does not close
       i = scanRegexClass(src, i, cache);
@@ -191,16 +190,17 @@ function scanRegexClass(
   const opens = [open];
   let i = open + 1;
   while (i < src.length) {
+    const lineEnd = regexLineEnd(src, i);
+    if (lineEnd !== -1) {
+      i = lineEnd;
+      break;
+    }
     const c = src.charAt(i);
     if (c === '\\') {
-      if (LINE_TERMINATOR_RE.test(src.charAt(i + 1))) {
-        i++;
-        break;
-      }
       i += 2;
       continue;
     }
-    if (c === ']' || LINE_TERMINATOR_RE.test(c)) break;
+    if (c === ']') break;
     if (c === '[' && cache) opens.push(i);
     i++;
   }
@@ -209,6 +209,17 @@ function scanRegexClass(
   return i;
 }
 
+/**
+ * Index of the line break at `i`, escaped (`\` then a line break) or not,
+ * where a regex literal or class ends unterminated; -1 if there is none.
+ */
+function regexLineEnd(src: string, i: number): number {
+  const c = src.charAt(i);
+  if (LINE_TERMINATOR_RE.test(c)) return i;
+  if (c === '\\' && LINE_TERMINATOR_RE.test(src.charAt(i + 1))) return i + 1;
+  return -1;
+}
+
 /**
  * The next index from `from` on where `find` matches (-1 for none), for
  * searches from increasing positions: a search from within the stretch the