@rohal12/spindle 0.52.2 → 0.52.3

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/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/settings.ts

@@ -1,5 +1,5 @@
 import { useStoryStore } from './store';
-import { createNamespace, ownValue } from './utils/namespace';
+import { createNamespace, hasOwn, ownValue } from './utils/namespace';
 
 export interface ToggleConfig {
   label: string;
@@ -76,29 +76,30 @@ function loadFromStorage(): void {
   }
 }
 
+/** Register a setting, starting from its default unless it has a value. */
+function define(name: string, def: SettingDef): void {
+  definitions.set(name, def);
+  if (!hasOwn(values, name)) values[name] = def.config.default;
+  loadFromStorage();
+}
+
+/** The value of setting `name` if it has the type of `fallback`, else that. */
+function valueOf<T>(name: string, fallback: T): T {
+  const v = ownValue(values, name);
+  return typeof v === typeof fallback ? (v as T) : fallback;
+}
+
 export const settings = {
   addToggle(name: string, config: ToggleConfig): void {
-    definitions.set(name, { type: 'toggle', config });
-    if (!Object.prototype.hasOwnProperty.call(values, name)) {
-      values[name] = config.default;
-    }
-    loadFromStorage();
+    define(name, { type: 'toggle', config });
   },
 
   addList(name: string, config: ListConfig): void {
-    definitions.set(name, { type: 'list', config });
-    if (!Object.prototype.hasOwnProperty.call(values, name)) {
-      values[name] = config.default;
-    }
-    loadFromStorage();
+    define(name, { type: 'list', config });
   },
 
   addRange(name: string, config: RangeConfig): void {
-    definitions.set(name, { type: 'range', config });
-    if (!Object.prototype.hasOwnProperty.call(values, name)) {
-      values[name] = config.default;
-    }
-    loadFromStorage();
+    define(name, { type: 'range', config });
   },
 
   get(name: string): unknown {
@@ -106,18 +107,15 @@ export const settings = {
   },
 
   getToggle(name: string): boolean {
-    const v = ownValue(values, name);
-    return typeof v === 'boolean' ? v : false;
+    return valueOf(name, false);
   },
 
   getList(name: string): string {
-    const v = ownValue(values, name);
-    return typeof v === 'string' ? v : '';
+    return valueOf(name, '');
   },
 
   getRange(name: string): number {
-    const v = ownValue(values, name);
-    return typeof v === 'number' ? v : 0;
+    return valueOf(name, 0);
   },
 
   set(name: string, value: unknown): void {

package/src/store.ts

@@ -62,11 +62,12 @@ import {
 } from './execute-mutation';
 import {
   checkVariableName,
+  createCounts,
   createNamespace,
   isNamespace,
+  type Counts,
   type Namespace,
 } from './utils/namespace';
-import { createCounts, type Counts } from './utils/counts';
 
 enablePatches();
 // Story state holds Map and Set values: Immer must be able to draft them

package/src/story-api.ts

@@ -23,8 +23,8 @@ import { getBackendType } from './saves/storage';
 import { registerClass } from './class-registry';
 import { frozenCopy, getActiveMutationScope } from './execute-mutation';
 import { getByPath, setByPath } from './utils/object-path';
-import { checkVariableName } from './utils/namespace';
-import { countOf } from './utils/counts';
+import { changedNames, checkVariableName, ownValue } from './utils/namespace';
+import { countQueries, currentPassage, previousPassage } from './expression';
 import { defineMacro } from './define-macro';
 import type { MacroDefinition } from './define-macro';
 import { getMacroRegistry as _getMacroRegistry } from './registry';
@@ -83,35 +83,24 @@ function ensureVariableChangedSubscription(): void {
   let prevTrans = useStoryStore.getState().transient;
   useStoryStore.subscribe((state) => {
     const changed: Record<string, { from: unknown; to: unknown }> = {};
-    let hasChanges = false;
-
-    // Check $variables
-    const allVarKeys = new Set([
-      ...Object.keys(prevVars),
-      ...Object.keys(state.variables),
-    ]);
-    for (const key of allVarKeys) {
-      if (state.variables[key] !== prevVars[key]) {
-        changed[key] = { from: prevVars[key], to: state.variables[key] };
-        hasChanges = true;
+    const collect = (
+      prev: Record<string, unknown>,
+      next: Record<string, unknown>,
+      prefix: string,
+    ) => {
+      for (const key of changedNames(prev, next)) {
+        changed[prefix + key] = {
+          from: ownValue(prev, key),
+          to: ownValue(next, key),
+        };
       }
-    }
-
-    // Check %transient
-    const allTransKeys = new Set([
-      ...Object.keys(prevTrans),
-      ...Object.keys(state.transient),
-    ]);
-    for (const key of allTransKeys) {
-      if (state.transient[key] !== prevTrans[key]) {
-        changed[`%${key}`] = { from: prevTrans[key], to: state.transient[key] };
-        hasChanges = true;
-      }
-    }
+    };
+    collect(prevVars, state.variables, '');
+    collect(prevTrans, state.transient, '%');
 
     prevVars = state.variables;
     prevTrans = state.transient;
-    if (hasChanges) {
+    if (Object.keys(changed).length > 0) {
       emit('variableChanged', changed);
     }
   });
@@ -271,6 +260,8 @@ function setOne(draft: VariableNamespaces, name: string, value: unknown): void {
 }
 
 function createStoryAPI(): StoryAPI {
+  const visits = countQueries(() => useStoryStore.getState().visitCounts);
+  const renders = countQueries(() => useStoryStore.getState().renderCounts);
   return {
     get(name: string): unknown {
       const { isTransient, key } = parseName(name);
@@ -284,7 +275,7 @@ function createStoryAPI(): StoryAPI {
       const namespace = isTransient ? source.transient : source.variables;
       const value = key.includes('.')
         ? getByPath(namespace, key.split('.'))
-        : namespace[key];
+        : ownValue(namespace, key);
       return scope ? frozenCopy(value) : value;
     },
 
@@ -357,55 +348,16 @@ function createStoryAPI(): StoryAPI {
       return useStoryStore.getState().importSave(data, slot);
     },
 
-    visited(name?: string): number {
-      const state = useStoryStore.getState();
-      return countOf(state.visitCounts, name ?? state.currentPassage);
-    },
-
-    hasVisited(name?: string): boolean {
-      return this.visited(name) > 0;
-    },
-
-    hasVisitedAny(...names: string[]): boolean {
-      const { visitCounts } = useStoryStore.getState();
-      return names.some((n) => countOf(visitCounts, n) > 0);
-    },
-
-    hasVisitedAll(...names: string[]): boolean {
-      const { visitCounts } = useStoryStore.getState();
-      return names.every((n) => countOf(visitCounts, n) > 0);
-    },
-
-    rendered(name?: string): number {
-      const state = useStoryStore.getState();
-      return countOf(state.renderCounts, name ?? state.currentPassage);
-    },
-
-    hasRendered(name?: string): boolean {
-      return this.rendered(name) > 0;
-    },
-
-    hasRenderedAny(...names: string[]): boolean {
-      const { renderCounts } = useStoryStore.getState();
-      return names.some((n) => countOf(renderCounts, n) > 0);
-    },
-
-    hasRenderedAll(...names: string[]): boolean {
-      const { renderCounts } = useStoryStore.getState();
-      return names.every((n) => countOf(renderCounts, n) > 0);
-    },
-
-    currentPassage(): Passage | undefined {
-      const state = useStoryStore.getState();
-      return state.storyData?.passages.get(state.currentPassage);
-    },
-
-    previousPassage(): Passage | undefined {
-      const state = useStoryStore.getState();
-      if (state.historyIndex <= 0) return undefined;
-      const prevName = state.history[state.historyIndex - 1]?.passage;
-      return prevName ? state.storyData?.passages.get(prevName) : undefined;
-    },
+    visited: visits.count,
+    hasVisited: visits.has,
+    hasVisitedAny: visits.any,
+    hasVisitedAll: visits.all,
+    rendered: renders.count,
+    hasRendered: renders.has,
+    hasRenderedAny: renders.any,
+    hasRenderedAll: renders.all,
+    currentPassage,
+    previousPassage,
 
     get title(): string {
       return useStoryStore.getState().storyData?.name || '';

package/src/story-variables.ts

@@ -3,7 +3,7 @@ import { tokenize, type Token } from './markup/tokenizer';
 import { isCodeAttribute, splitSigilTemplate } from './markup/code-attributes';
 import { errorMessage } from './utils/error-message';
 import { lexJs, scanStringLiteral, type JsGoal } from './js-lexer';
-import { createNamespace, RESERVED_NAME } from './utils/namespace';
+import { createNamespace, variableNameError } from './utils/namespace';
 
 export type VarType = 'number' | 'string' | 'boolean' | 'array' | 'object';
 
@@ -80,11 +80,8 @@ export function parseStoryVariables(
     }
 
     const [, name, expr] = match as [string, string, string];
-    if (name === RESERVED_NAME) {
-      throw new Error(
-        `${passageName}: "${sigil}${name}" cannot be used as a variable name (${RESERVED_NAME} is reserved)`,
-      );
-    }
+    const nameError = variableNameError(name, sigil + name);
+    if (nameError) throw new Error(`${passageName}: ${nameError}`);
     let value: unknown;
     try {
       value = new Function('return (' + expr + ')')();
@@ -134,9 +131,8 @@ function validateRef(
   const parts = ref.split('.');
   const rootName = parts[0]!;
 
-  if (rootName === RESERVED_NAME) {
-    return `"$${rootName}" cannot be used as a variable name (${RESERVED_NAME} is reserved)`;
-  }
+  const nameError = variableNameError(rootName, '$' + rootName);
+  if (nameError) return nameError;
 
   // Skip for-loop locals
   if (forLocals.has(rootName)) return null;

package/src/utils/live-locals.ts

@@ -1,4 +1,4 @@
-import { createNamespace, ownValue } from './namespace';
+import { createNamespace, hasOwn, ownValue } from './namespace';
 
 /**
  * Read-only view of a locals scope that always reflects its current values.
@@ -16,9 +16,7 @@ export function liveLocalsView(
   return new Proxy(createNamespace(), {
     get: (_, key) =>
       typeof key === 'string' ? ownValue(getValues(), key) : undefined,
-    has: (_, key) =>
-      typeof key === 'string' &&
-      Object.prototype.hasOwnProperty.call(getValues(), key),
+    has: (_, key) => typeof key === 'string' && hasOwn(getValues(), key),
     ownKeys: () => Reflect.ownKeys(getValues()),
     getOwnPropertyDescriptor: (_, key) => {
       const desc = Object.getOwnPropertyDescriptor(getValues(), key);