@rohal12/spindle 0.51.4 → 0.52.0

package/src/story-api.ts

@@ -18,20 +18,12 @@ import type {
 import {
   setTitleGenerator,
   getStorageInfo as _getStorageInfo,
-  clearGameData as _clearGameData,
-  clearAllData as _clearAllData,
-  deletePlaythroughData,
-  populateKnownSaves,
 } from './saves/save-manager';
 import { getBackendType } from './saves/storage';
 import { registerClass } from './class-registry';
-import {
-  frozenCopy,
-  getActiveMutationScope,
-  mirrorWriteToActiveScopes,
-  runWithCommittedMutations,
-} from './execute-mutation';
+import { frozenCopy, getActiveMutationScope } from './execute-mutation';
 import { getByPath, setByPath } from './utils/object-path';
+import { checkVariableName } from './utils/namespace';
 import { defineMacro } from './define-macro';
 import type { MacroDefinition } from './define-macro';
 import { getMacroRegistry as _getMacroRegistry } from './registry';
@@ -85,8 +77,9 @@ let variableChangedSubActive = false;
 function ensureVariableChangedSubscription(): void {
   if (variableChangedSubActive) return;
   variableChangedSubActive = true;
-  let prevVars = { ...useStoryStore.getState().variables };
-  let prevTrans = { ...useStoryStore.getState().transient };
+  // Store namespaces are immutable snapshots: keep the references
+  let prevVars = useStoryStore.getState().variables;
+  let prevTrans = useStoryStore.getState().transient;
   useStoryStore.subscribe((state) => {
     const changed: Record<string, { from: unknown; to: unknown }> = {};
     let hasChanges = false;
@@ -115,8 +108,8 @@ function ensureVariableChangedSubscription(): void {
       }
     }
 
-    prevVars = { ...state.variables };
-    prevTrans = { ...state.transient };
+    prevVars = state.variables;
+    prevTrans = state.transient;
     if (hasChanges) {
       emit('variableChanged', changed);
     }
@@ -237,15 +230,17 @@ export function _resetDeclaredVariables(): void {
 /**
  * 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.
+ * transients (`%npcs`). Dot-paths are kept in the key. A variable named
+ * `__proto__` throws a TypeError (see utils/namespace.ts).
  */
 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 };
+  const isTransient = name.startsWith('%');
+  const key = isTransient || name.startsWith('$') ? name.slice(1) : name;
+  checkVariableName(key.split('.')[0]!, name);
+  return { isTransient, key };
 }
 
 function warnIfUndeclared(isTransient: boolean, key: string): void {
@@ -301,51 +296,36 @@ function createStoryAPI(): StoryAPI {
         const { isTransient, key } = parseName(name);
         warnIfUndeclared(isTransient, key);
       }
-      // One store update for all keys, so watchers see them together
+      // One store update for all keys, so watchers see them together. Made
+      // while mutation code runs ({do}, ctx.mutate, watcher run actions), it
+      // follows the code's own pending writes (program order, #215): see
+      // routeStoreUpdate.
       useStoryStore.getState().updateVariables((draft) => {
         for (const [k, v] of entries) setOne(draft, k, v);
-        // Mutation code running now ({do}, ctx.mutate, watcher run actions)
-        // works on copies of the namespaces and commits the paths it changed
-        // when it finishes. Apply the write to those copies too, so the code
-        // sees it and its commit keeps it in program order (#215). This runs
-        // inside the update, before watchers it triggers write.
-        for (const [k, v] of entries) {
-          const { isTransient, key } = parseName(k);
-          mirrorWriteToActiveScopes(
-            draft,
-            isTransient ? 'transient' : 'variables',
-            key.split('.'),
-            v,
-          );
-        }
       });
     },
 
-    // Called from running mutation code, these commit the code's writes so
-    // far before they record, replace or save state, and the code goes on
-    // from the state they leave (see runWithCommittedMutations).
+    // Called from running mutation code, these store actions commit the
+    // code's writes so far before they record, replace or save state, and
+    // the code goes on from the state they leave (see storyStateGuard).
     goto(passageName: string): void {
-      runWithCommittedMutations(() =>
-        useStoryStore.getState().navigate(passageName),
-      );
+      useStoryStore.getState().navigate(passageName);
     },
 
     back(): void {
-      runWithCommittedMutations(() => useStoryStore.getState().goBack());
+      useStoryStore.getState().goBack();
     },
 
     forward(): void {
-      runWithCommittedMutations(() => useStoryStore.getState().goForward());
+      useStoryStore.getState().goForward();
     },
 
     restart(): void {
-      runWithCommittedMutations(() => useStoryStore.getState().restart());
+      useStoryStore.getState().restart();
     },
 
     save(slot?: string, custom?: Record<string, unknown>): Promise<void> {
-      return runWithCommittedMutations(() =>
-        useStoryStore.getState().save(slot, custom),
-      );
+      return useStoryStore.getState().save(slot, custom);
     },
 
     load(slot?: string): Promise<void> {
@@ -483,32 +463,16 @@ function createStoryAPI(): StoryAPI {
         return { usage: 0, quota: 0, estimateSupported: false };
       },
 
-      async clearGameData(): Promise<void> {
-        const ifid = useStoryStore.getState().storyData?.ifid;
-        if (!ifid) return;
-        await _clearGameData(ifid);
-        useStoryStore.setState((state) => {
-          state.knownSaves = {};
-        });
-        useStoryStore.getState().restart();
+      clearGameData(): Promise<void> {
+        return useStoryStore.getState().clearGameData();
       },
 
-      async clearAllData(): Promise<void> {
-        await _clearAllData();
-        useStoryStore.setState((state) => {
-          state.knownSaves = {};
-        });
-        useStoryStore.getState().restart();
+      clearAllData(): Promise<void> {
+        return useStoryStore.getState().clearAllData();
       },
 
-      async deletePlaythrough(playthroughId: string): Promise<void> {
-        const { storyData } = useStoryStore.getState();
-        if (!storyData) return;
-        await deletePlaythroughData(storyData.ifid, playthroughId);
-        const known = await populateKnownSaves(storyData.ifid);
-        useStoryStore.setState((state) => {
-          state.knownSaves = known;
-        });
+      deletePlaythrough(playthroughId: string): Promise<void> {
+        return useStoryStore.getState().deletePlaythrough(playthroughId);
       },
 
       get backend() {

package/src/story-init.ts

@@ -47,7 +47,7 @@ export function executeStoryInit() {
     document.body.appendChild(container);
     storyInitContainer = container;
     render(
-      h(() => renderNodes(ast) as any, null),
+      h(() => renderNodes(ast), null),
       container,
     );
 

package/src/story-variables.ts

@@ -1,5 +1,9 @@
 import type { Passage } from './parser';
-import { tokenize } from './markup/tokenizer';
+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';
 
 export type VarType = 'number' | 'string' | 'boolean' | 'array' | 'object';
 
@@ -17,9 +21,8 @@ function declarationRegex(sigil: string): RegExp {
   const escaped = sigil.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
   return new RegExp(`^${escaped}(\\w+)\\s*=\\s*(.+)$`);
 }
-const VAR_REF_RE = /\$(\w+(?:\.\w+)*)/g;
-/** `{` followed by a sigil starts an interpolation block inside literal text. */
-const INTERP_START_RE = /^[$_@%]\w/;
+/** A `$name` reference with its dot path, at a `$` the lexer found. */
+const VAR_PATH_RE = /\$(\w+(?:\.\w+)*)/y;
 /** Quoted first argument of an input macro naming a story variable. */
 const QUOTED_VAR_ARG_RE = /^["']\$(\w+(?:\.\w+)*)["']?$/;
 const FOR_LOCAL_RE = /\{for\s+@(\w+)(?:\s*,\s*@(\w+))?\s+of\b/g;
@@ -77,12 +80,17 @@ 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)`,
+      );
+    }
     let value: unknown;
     try {
       value = new Function('return (' + expr + ')')();
     } catch (err) {
       throw new Error(
-        `${passageName}: Failed to evaluate "${sigil}${name} = ${expr}": ${err instanceof Error ? err.message : err}`,
+        `${passageName}: Failed to evaluate "${sigil}${name} = ${expr}": ${errorMessage(err)}`,
       );
     }
 
@@ -90,9 +98,7 @@ export function parseStoryVariables(
     try {
       fieldSchema = inferSchema(value);
     } catch (err) {
-      throw new Error(
-        `${passageName}: ${err instanceof Error ? err.message : err}`,
-      );
+      throw new Error(`${passageName}: ${errorMessage(err)}`);
     }
     schema.set(name, { ...fieldSchema, name, default: value });
   }
@@ -128,6 +134,10 @@ 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)`;
+  }
+
   // Skip for-loop locals
   if (forLocals.has(rootName)) return null;
 
@@ -187,107 +197,81 @@ const BUILTIN_STORE_VAR_MACROS: readonly string[] = [
 
 type RefCallback = (ref: string) => void;
 
-/** Report every `$var.path` in a code segment free of strings/comments. */
-function scanRefs(segment: string, onRef: RefCallback): void {
-  for (const match of segment.matchAll(VAR_REF_RE)) onRef(match[1]!);
-}
-
-/** Index of the quote closing the string opened at `start` (or the end). */
-function findClosingQuote(code: string, start: number): number {
-  const quote = code[start];
-  let i = start + 1;
-  while (i < code.length && code[i] !== quote) {
-    i += code[i] === '\\' ? 2 : 1;
-  }
-  return Math.min(i, code.length);
-}
+const NO_STORE_VAR_MACROS: ReadonlySet<string> = new Set();
 
 /**
- * Scan literal text (string contents, HTML attribute values) for `{$…}`
- * interpolation blocks, which interpolating macros and HTML attributes
- * resolve at runtime. A bare `$word` in literal text is not a reference.
+ * Scan the value of a code attribute (`onclick`, see isCodeAttribute) for
+ * the `{$…}` references resolved in it; its other braces are code.
  */
-function scanInterpolations(text: string, onRef: RefCallback): void {
-  let i = text.indexOf('{');
-  while (i !== -1) {
-    const next = INTERP_START_RE.test(text.slice(i + 1, i + 3))
-      ? scanCode(text, i + 1, onRef, true)
-      : i + 1;
-    i = text.indexOf('{', next);
+function scanSigilReferences(value: string, onRef: RefCallback): void {
+  for (const part of splitSigilTemplate(value)) {
+    if ('expr' in part) scanCode(part.expr, onRef);
   }
 }
 
 /**
- * Scan a template literal starting just after its opening backtick: literal
- * parts are text, `${…}` parts are code. Returns the index just past the
- * closing backtick.
+ * Scan literal text (string contents, HTML attribute values) for the markup
+ * that labels and HTML attributes evaluate at runtime: `{$…}` displays,
+ * expressions and macros, read as in passage text. A bare `$word` in
+ * literal text is not a reference.
  */
-function scanTemplate(code: string, start: number, onRef: RefCallback): number {
-  let i = start;
-  let textStart = start;
-  while (i < code.length) {
-    const ch = code[i];
-    if (ch === '\\') {
-      i += 2;
-    } else if (ch === '`') {
-      scanInterpolations(code.slice(textStart, i), onRef);
-      return i + 1;
-    } else if (ch === '$' && code[i + 1] === '{') {
-      scanInterpolations(code.slice(textStart, i), onRef);
-      i = textStart = scanCode(code, i + 2, onRef, true);
-    } else {
-      i++;
-    }
-  }
-  scanInterpolations(code.slice(textStart), onRef);
-  return code.length;
+function scanInterpolations(
+  text: string,
+  onRef: RefCallback,
+  storeVarMacros: ReadonlySet<string> = NO_STORE_VAR_MACROS,
+): void {
+  if (!text.includes('{')) return;
+  collectTokenRefs(text, tokenize(text, { text: true }), storeVarMacros, onRef);
 }
 
 /**
- * Report `$var` references in JavaScript code. Like the string-aware
- * expression transformer, sigils inside string literals are left alone while
- * template-literal `${…}` parts are code; comments are skipped too. When
- * `nested`, stops at the `}` closing the enclosing block and returns the index
- * just past it.
+ * Report `$var` references in JavaScript code, lexed as the expression
+ * engine lexes it (`lexJs`): references in code, but none inside string or
+ * regex literals or comments, nor property names (`a.$b`, `{ $b: 1 }`).
+ * The text of string and template literals is scanned for the markup that
+ * labels evaluate (`{$…}`); the `${…}` parts of template literals are code.
  */
 function scanCode(
   code: string,
-  start: number,
   onRef: RefCallback,
-  nested = false,
-): number {
-  let i = start;
-  let segStart = start;
-  let depth = 0;
-  while (i < code.length) {
-    const ch = code[i];
-    const next = code[i + 1];
-    const isComment = ch === '/' && (next === '/' || next === '*');
-    if (ch === '"' || ch === "'" || ch === '`' || isComment) {
-      scanRefs(code.slice(segStart, i), onRef);
-      if (ch === '`') {
-        i = scanTemplate(code, i + 1, onRef);
-      } else if (isComment) {
-        const close = code.indexOf(next === '/' ? '\n' : '*/', i + 2);
-        i = close === -1 ? code.length : next === '/' ? close : close + 2;
-      } else {
-        const close = findClosingQuote(code, i);
-        scanInterpolations(code.slice(i + 1, close), onRef);
-        i = Math.min(close + 1, code.length);
-      }
-      segStart = i;
-      continue;
-    }
-    if (nested && ch === '{') {
-      depth++;
-    } else if (nested && ch === '}' && depth-- === 0) {
-      scanRefs(code.slice(segStart, i), onRef);
-      return i + 1;
-    }
-    i++;
-  }
-  scanRefs(code.slice(segStart), onRef);
-  return code.length;
+  goal: JsGoal = 'expression',
+): void {
+  /** Open template literals: their text so far, null in an interpolation. */
+  const templates: { nesting: number; text: string | null }[] = [];
+  lexJs(
+    code,
+    {
+      variable(sigil, _name, index) {
+        if (sigil !== '$') return;
+        VAR_PATH_RE.lastIndex = index;
+        onRef(VAR_PATH_RE.exec(code)![1]!);
+      },
+      literal(text, _index, nesting) {
+        const template = templates[templates.length - 1];
+        if (template?.nesting === nesting) {
+          if (template.text === null) {
+            // The `}` ending an interpolation: back to the template's text
+            template.text = '';
+          } else if (text === '`' || text === '${') {
+            scanInterpolations(template.text, onRef);
+            if (text === '`') templates.pop();
+            else template.text = null;
+          } else {
+            template.text += text;
+          }
+        } else if (text === '`') {
+          templates.push({ nesting, text: '' });
+        } else if (text[0] === '"' || text[0] === "'") {
+          const { closed } = scanStringLiteral(text, 0);
+          scanInterpolations(text.slice(1, closed ? -1 : undefined), onRef);
+        }
+        // Regex literals and comments hold no references
+      },
+    },
+    goal,
+  );
+  // An unterminated template literal's text
+  for (const t of templates) if (t.text) scanInterpolations(t.text, onRef);
 }
 
 /**
@@ -301,19 +285,29 @@ function collectPassageRefs(
   storeVarMacros: ReadonlySet<string>,
   onRef: RefCallback,
 ): void {
-  const tokens = tokenize(content);
+  collectTokenRefs(content, tokenize(content), storeVarMacros, onRef);
+}
+
+/** Report the `$var` references in the tokens of `content`. */
+function collectTokenRefs(
+  content: string,
+  tokens: Token[],
+  storeVarMacros: ReadonlySet<string>,
+  onRef: RefCallback,
+): void {
   for (let t = 0; t < tokens.length; t++) {
     const token = tokens[t]!;
     if (token.type === 'variable') {
       if (token.scope === 'variable' && token.name) onRef(token.name);
     } else if (token.type === 'expression') {
-      scanCode(token.expression, 0, onRef);
+      scanCode(token.expression, onRef);
     } else if (token.type === 'html') {
-      for (const value of Object.values(token.attributes)) {
-        scanInterpolations(value, onRef);
+      for (const [name, value] of Object.entries(token.attributes)) {
+        if (isCodeAttribute(name)) scanSigilReferences(value, onRef);
+        else scanInterpolations(value, onRef, storeVarMacros);
       }
     } else if (token.type === 'macro' && !token.isClose) {
-      scanCode(token.rawArgs, 0, onRef);
+      scanCode(token.rawArgs, onRef);
 
       if (storeVarMacros.has(token.name.toLowerCase())) {
         const first = token.rawArgs.trim().split(/\s+/)[0] ?? '';
@@ -331,7 +325,8 @@ function collectPassageRefs(
           close++;
         }
         if (close < tokens.length) {
-          scanCode(content.slice(token.end, tokens[close]!.start), 0, onRef);
+          const body = content.slice(token.end, tokens[close]!.start);
+          scanCode(body, onRef, 'statements');
           t = close;
         }
       }
@@ -374,12 +369,13 @@ export function validatePassages(
 }
 
 /**
- * Extract default values from the schema as a plain object.
+ * Extract default values from the schema as a record without a prototype,
+ * like the namespaces it initializes (see utils/namespace.ts).
  */
 export function extractDefaults(
   schema: Map<string, VariableSchema>,
 ): Record<string, unknown> {
-  const defaults: Record<string, unknown> = {};
+  const defaults = createNamespace();
   for (const [name, varSchema] of schema) {
     defaults[name] = varSchema.default;
   }

package/src/triggers.ts

@@ -1,5 +1,5 @@
 import { evaluate } from './expression';
-import { executeMutation, runWithCommittedMutations } from './execute-mutation';
+import { executeMutation, readState } from './execute-mutation';
 import { useStoryStore } from './store';
 
 export interface WatchOptions {
@@ -46,8 +46,9 @@ interface DialogHostCallbacks {
 }
 let dialogHostCallbacks: DialogHostCallbacks | null = null;
 
+/** A condition's value in program order (see readState). */
 function evalCondition(condition: string): boolean {
-  const state = useStoryStore.getState();
+  const state = readState();
   try {
     return !!evaluate(
       condition,
@@ -150,9 +151,9 @@ function fireTrigger(trigger: Trigger): void {
 
   if (options.goto) {
     // A watcher fired by a Story.set in running code navigates after that
-    // code's writes so far, so they are part of the moment it leaves.
-    const passage = options.goto;
-    runWithCommittedMutations(() => useStoryStore.getState().navigate(passage));
+    // code's writes so far, so they are part of the moment it leaves (the
+    // store commits them first).
+    useStoryStore.getState().navigate(options.goto);
   }
 }
 

package/src/utils/error-message.ts

@@ -0,0 +1,12 @@
+/**
+ * The message to show for a caught value. Anything can be thrown, not only
+ * Errors: an Error gives its message, a string is its own message, and any
+ * other value gives `fallback` when one is passed, else its string form
+ * (never `undefined`). An empty message also gives `fallback`, or for an
+ * Error its string form (e.g. "Error").
+ */
+export function errorMessage(err: unknown, fallback?: string): string {
+  if (err instanceof Error) return err.message || fallback || String(err);
+  if (typeof err === 'string' && err !== '') return err;
+  return fallback ?? String(err);
+}

package/src/utils/live-locals.ts

@@ -1,3 +1,5 @@
+import { createNamespace, ownValue } from './namespace';
+
 /**
  * Read-only view of a locals scope that always reflects its current values.
  *
@@ -9,9 +11,14 @@
 export function liveLocalsView(
   getValues: () => Record<string, unknown>,
 ): Record<string, unknown> {
-  return new Proxy({} as Record<string, unknown>, {
-    get: (_, key) => (typeof key === 'string' ? getValues()[key] : undefined),
-    has: (_, key) => key in getValues(),
+  // No prototype and own entries only, like every namespace (see
+  // utils/namespace.ts)
+  return new Proxy(createNamespace(), {
+    get: (_, key) =>
+      typeof key === 'string' ? ownValue(getValues(), key) : undefined,
+    has: (_, key) =>
+      typeof key === 'string' &&
+      Object.prototype.hasOwnProperty.call(getValues(), key),
     ownKeys: () => Reflect.ownKeys(getValues()),
     getOwnPropertyDescriptor: (_, key) => {
       const desc = Object.getOwnPropertyDescriptor(getValues(), key);

package/src/utils/namespace.ts

@@ -0,0 +1,71 @@
+/**
+ * Variable namespaces: the records holding $story variables, _temporary
+ * variables, %transient variables and @locals, keyed by variable name.
+ *
+ * They have no prototype, so every name is plain storage: a variable may be
+ * called `constructor`, `toString` or `hasOwnProperty`, and reading one
+ * that was never set gives undefined rather than an Object.prototype
+ * member. The one name they cannot hold is `__proto__`: story state (and so
+ * saves) never holds a property by that name, and on an ordinary object
+ * writing it would replace the prototype instead of storing a value. It is
+ * refused wherever a variable name enters (checkVariableName).
+ */
+
+export type Namespace = Record<string, unknown>;
+
+/** The variable name no namespace can hold. */
+export const RESERVED_NAME = '__proto__';
+
+/**
+ * Throw a TypeError if `name` (without its sigil) cannot be a variable
+ * name. `label` is the name as the author wrote it (e.g. `$__proto__`).
+ */
+export function checkVariableName(name: string, label = name): void {
+  if (name === RESERVED_NAME) {
+    throw new TypeError(
+      `spindle: "${label}" cannot be used as a variable name (${RESERVED_NAME} is reserved)`,
+    );
+  }
+}
+
+/** A namespace with no prototype holding the own entries of `sources`. */
+export function createNamespace(
+  ...sources: readonly (object | null | undefined)[]
+): Namespace {
+  const ns = Object.create(null) as Namespace;
+  for (const source of sources) {
+    if (!source) continue;
+    for (const key of Object.keys(source)) {
+      ns[key] = (source as Namespace)[key];
+    }
+  }
+  return ns;
+}
+
+/** Whether `value` is an object with no prototype. */
+export const isNamespace = (value: object): boolean =>
+  Object.getPrototypeOf(value) === null;
+
+/** `ns` itself if it has no prototype, else a namespace copy of it. */
+export const asNamespace = (ns: Namespace): Namespace =>
+  isNamespace(ns) ? ns : createNamespace(ns);
+
+/** A namespace copy of `ns` with `key` set to `value`. */
+export function withEntry(
+  ns: Namespace,
+  key: string,
+  value: unknown,
+): Namespace {
+  const next = createNamespace(ns);
+  next[key] = value;
+  return next;
+}
+
+/** An empty namespace that cannot change. */
+export const EMPTY_NAMESPACE: Namespace = Object.freeze(createNamespace());
+
+/** `ns[key]` if `ns` holds it as an own property, else undefined. */
+export const ownValue = (ns: object, key: string): unknown =>
+  Object.prototype.hasOwnProperty.call(ns, key)
+    ? (ns as Namespace)[key]
+    : undefined;