@rohal12/spindle 0.59.0 → 0.59.2

package/src/story-variables.ts

@@ -11,7 +11,6 @@ import {
 } from './js-lexer';
 import {
   argPieces,
-  holdsCode,
   parseOrError,
   withParseCache,
   type ParametersOf,
@@ -53,7 +52,6 @@ function declarationRegex(sigil: string): RegExp {
 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;
 
 const VALID_VAR_TYPES = new Set<string>(['number', 'string', 'boolean']);
 
@@ -131,22 +129,6 @@ export function parseStoryVariables(
   return schema;
 }
 
-/**
- * Extract for-loop local variable names from passage content.
- * `{for @item of ...}` → "item"
- * `{for @index, @item of ...}` → "index", "item"
- */
-function extractForLocals(content: string): Set<string> {
-  const locals = new Set<string>();
-  let match: RegExpExecArray | null;
-  FOR_LOCAL_RE.lastIndex = 0;
-  while ((match = FOR_LOCAL_RE.exec(content)) !== null) {
-    locals.add(match[1]!);
-    if (match[2]) locals.add(match[2]!);
-  }
-  return locals;
-}
-
 /**
  * Validate a single variable reference path (e.g. "player.health") against
  * the schema. Returns an error message or null if valid.
@@ -154,7 +136,6 @@ function extractForLocals(content: string): Set<string> {
 function validateRef(
   ref: string,
   schema: Map<string, VariableSchema>,
-  forLocals: Set<string>,
 ): string | null {
   const parts = ref.split('.');
   const rootName = parts[0]!;
@@ -162,9 +143,6 @@ function validateRef(
   const nameError = variableNameError(rootName, '$' + rootName);
   if (nameError) return nameError;
 
-  // Skip for-loop locals
-  if (forLocals.has(rootName)) return null;
-
   const rootSchema = schema.get(rootName);
   if (!rootSchema) {
     return `Undeclared variable: $${ref}`;
@@ -252,8 +230,9 @@ function scanInterpolations(
  * 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.
+ * The text of string and template literals is not scanned: a string in code
+ * is literal text unless a macro argument that holds markup is read as such
+ * (see scanArgs); the `${…}` parts of template literals are code.
  */
 function scanCode(
   code: string,
@@ -270,7 +249,6 @@ function scanCode(
     VAR_PATH_RE.lastIndex = ref.start;
     onRef(VAR_PATH_RE.exec(code)![1]!);
   }
-  for (const text of parsed.strings) scanInterpolations(text, onRef);
 }
 
 /** `scanCode` for code acorn can't parse: lexed leniently. */
@@ -279,8 +257,6 @@ function scanCodeLeniently(
   onRef: RefCallback,
   goal: JsGoal,
 ): void {
-  /** Open template literals: their text so far, null in an interpolation. */
-  const templates: { nesting: number; text: string | null }[] = [];
   lexJs(
     code,
     {
@@ -289,32 +265,11 @@ function scanCodeLeniently(
         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
-      },
+      // Strings, regex literals and comments hold no references
+      literal() {},
     },
     goal,
   );
-  // An unterminated template literal's text
-  for (const t of templates) if (t.text) scanInterpolations(t.text, onRef);
 }
 
 /**
@@ -341,22 +296,29 @@ function collectPassageRefs(
 }
 
 /**
- * Report the references in the code that a macro's quoted arguments hold
- * (see ParameterDef.holds), the condition and `run` action of `{watch}`:
- * the argument scan sees only the strings. Only the macros that declare
- * code in a string have their arguments read.
+ * Report the references in the arguments of a macro by what its parameters
+ * say each holds (see ParameterDef.holds): code is scanned as code and
+ * markup as markup, but literal text (a placeholder, a passage name) holds
+ * none. A macro without declared parameters, or arguments that do not
+ * parse, are scanned as code.
  */
-function scanStringCode(
+function scanArgs(
   token: Extract<Token, { type: 'macro' }>,
   params: readonly ParameterDef[] | undefined,
   onRef: RefCallback,
 ): void {
-  if (!params || !token.rawArgs || !holdsCode(params)) return;
-  for (const piece of argPieces(token.rawArgs, 0, params, token.name, '')) {
-    if (piece.kind === 'code' && piece.inString) {
-      scanCode(piece.code, onRef, piece.goal);
+  if (!token.rawArgs) return;
+  if (params) {
+    const pieces = [...argPieces(token.rawArgs, 0, params, token.name, '')];
+    if (!pieces.some((piece) => piece.kind === 'argument-error')) {
+      for (const piece of pieces) {
+        if (piece.kind === 'code') scanCode(piece.code, onRef, piece.goal);
+        else if (piece.kind === 'text') scanInterpolations(piece.text, onRef);
+      }
+      return;
     }
   }
+  scanCode(token.rawArgs, onRef);
 }
 
 /** Report the `$var` references in the tokens of `content`. */
@@ -371,6 +333,8 @@ function collectTokenRefs(
     const token = tokens[t]!;
     if (token.type === 'variable') {
       if (token.scope === 'variable' && token.name) onRef(token.name);
+    } else if (token.type === 'link') {
+      scanInterpolations(token.display, onRef);
     } else if (token.type === 'expression') {
       scanCode(token.expression, onRef);
     } else if (token.type === 'html') {
@@ -379,22 +343,32 @@ function collectTokenRefs(
         else scanInterpolations(value, onRef, storeVarMacros);
       }
     } else if (token.type === 'macro' && !token.isClose) {
-      scanCode(token.rawArgs, onRef);
-      scanStringCode(token, parametersOf(token.name), onRef);
+      scanArgs(token, parametersOf(token.name), onRef);
+      // Selectors (`{.{$cls} button}`) are interpolated when rendered
+      if (token.className) scanInterpolations(token.className, onRef);
+      if (token.id) scanInterpolations(token.id, onRef);
 
       if (storeVarMacros.has(token.name.toLowerCase())) {
         const first = token.rawArgs.trim().split(/\s+/)[0] ?? '';
         const quoted = QUOTED_VAR_ARG_RE.exec(first);
         if (quoted) onRef(quoted[1]!);
+        // Unquoted, the variable is an argument of no declared role
+        else if (!/^["'`]/.test(first)) scanCode(first, onRef);
       }
 
-      if (token.name === 'do') {
+      if (token.name.toLowerCase() === 'do') {
         // A {do} body is JavaScript: scan its source text as code, however
         // the markup tokens split it up.
         let close = t + 1;
         while (close < tokens.length) {
           const c = tokens[close]!;
-          if (c.type === 'macro' && c.isClose && c.name === 'do') break;
+          if (
+            c.type === 'macro' &&
+            c.isClose &&
+            c.name.toLowerCase() === 'do'
+          ) {
+            break;
+          }
           close++;
         }
         if (close < tokens.length) {
@@ -430,12 +404,11 @@ export function validatePassages(
     // Don't validate the declarations or the SaveTitle code themselves
     if (NOT_MARKUP.has(name)) continue;
 
-    const forLocals = extractForLocals(passage.content);
     collectPassageRefs(
       passage.content,
       storeVarSet,
       (ref) => {
-        const error = validateRef(ref, schema, forLocals);
+        const error = validateRef(ref, schema);
         if (error) {
           errors.push(`Passage "${name}": ${error}`);
         }

package/src/structural.ts

@@ -36,6 +36,12 @@ export interface DeepCloneOptions {
    * plain object, which would lose their prototype and identity.
    */
   keepUnregistered?: boolean;
+  /**
+   * The copies made so far, by original. Values copied with one map share
+   * their references: an object met again, in the same value or another,
+   * is the copy already made. The map is filled as values are copied.
+   */
+  seen?: Map<object, object>;
 }
 
 type TypedArrayCtor = new (
@@ -45,7 +51,7 @@ type TypedArrayCtor = new (
 ) => ArrayBufferView;
 
 export function deepClone<T>(value: T, options: DeepCloneOptions = {}): T {
-  const seen = new Map<object, object>();
+  const seen = options.seen ?? new Map<object, object>();
 
   /** Record `copy` as the copy of `obj` before its contents are copied. */
   const keep = <C extends object>(obj: object, copy: C): C => {
@@ -53,11 +59,20 @@ export function deepClone<T>(value: T, options: DeepCloneOptions = {}): T {
     return copy;
   };
 
-  /** Copy the own (enumerable) keys of `obj` into `copy`. */
+  /**
+   * Copy the own (enumerable) keys of `obj` into `copy`, symbol keys too: a
+   * save refuses them, which a copy must not hide.
+   */
   function copyKeys(obj: object, copy: object): object {
     for (const key of Object.keys(obj)) {
       setOwn(copy, key, clone((obj as Record<string, unknown>)[key]));
     }
+    for (const sym of Object.getOwnPropertySymbols(obj)) {
+      if (!Object.prototype.propertyIsEnumerable.call(obj, sym)) continue;
+      (copy as Record<symbol, unknown>)[sym] = clone(
+        (obj as Record<symbol, unknown>)[sym],
+      );
+    }
     return copy;
   }
 
@@ -195,20 +210,25 @@ function loosePairs(): Pairs {
 /**
  * Pairs that also require the same reference structure: each object of one
  * value pairs with exactly one of the other, so shared references and
- * cycles are shared at the same places.
+ * cycles are shared at the same places. `ab` and `ba` hold the pairs (and
+ * may hold some already); those made are listed in `added`.
  */
-function strictPairs(): Pairs {
-  const ab = new Map<object, object>();
-  const ba = new Map<object, object>();
-  const pairs: Pairs = (a, b) => {
+function strictPairs(
+  ab = new Map<object, object>(),
+  ba = new Map<object, object>(),
+): Pairs & { added: [object, object][] } {
+  const added: [object, object][] = [];
+  const pairs = ((a, b) => {
     const known = ab.get(a);
     if (known !== undefined) return known === b;
     if (ba.has(b)) return false;
     ab.set(a, b);
     ba.set(b, a);
+    added.push([a, b]);
     return undefined;
-  };
+  }) as Pairs & { added: [object, object][] };
   pairs.strict = true;
+  pairs.added = added;
   return pairs;
 }
 
@@ -225,28 +245,55 @@ export function deepEqualStrict(a: unknown, b: unknown): boolean {
  * `prev` at the same place replaced by `prev`'s: the history moments of a
  * save then share what did not change between them, which a save stores
  * once. Containers on the way to a change are copied; neither value is
- * changed. Shared references and cycles within `curr` stay so.
+ * changed. The result has the reference structure of `curr`: what `curr`
+ * shares or cycles through stays so, and what it does not share stays
+ * apart, whichever parts are reused.
  */
 export function shareEqual<T>(prev: unknown, curr: T): T {
-  const done = new Map<object, unknown>();
-  function share(p: unknown, c: unknown): unknown {
-    if (p === c || !isObjectValue(c) || !isObjectValue(p)) return c;
-    if (done.has(c)) return done.get(c);
-    if (deepEqualStrict(p, c)) {
-      done.set(c, p);
-      return p;
+  if (!isObjectValue(prev) || !isObjectValue(curr)) return curr;
+  /** The object of the result standing for each object of `curr` met. */
+  const done = new Map<object, object>();
+  /** The object of `curr` each object of `prev` in the result stands for. */
+  const used = new Map<object, object>();
+
+  /** `value` for the result: copied, as far as it is not met already. */
+  const fresh = <V>(value: V): V =>
+    isObjectValue(value)
+      ? deepClone(value, { keepUnregistered: true, seen: done })
+      : value;
+
+  /**
+   * Whether `p` and `c` are equal and so can stand for each other, which
+   * needs each object in them to stand for one object only, in the whole
+   * result. Then every pair of objects they hold is placed in the result.
+   */
+  function reuse(p: object, c: object): boolean {
+    const pairs = strictPairs(used, done);
+    if (equal(p, c, pairs)) return true;
+    for (const [a, b] of pairs.added) {
+      used.delete(a);
+      done.delete(b);
     }
+    return false;
+  }
+
+  function share(p: unknown, c: unknown): unknown {
+    if (!isObjectValue(c)) return c;
+    const placed = done.get(c);
+    if (placed !== undefined) return placed;
+    if (!isObjectValue(p)) return fresh(c);
+    if (reuse(p, c)) return p;
     if (c instanceof Map && p instanceof Map) {
       const out = new Map();
       done.set(c, out);
-      for (const [k, v] of c) out.set(k, p.has(k) ? share(p.get(k), v) : v);
+      for (const [k, v] of c) out.set(fresh(k), share(p.get(k), v));
       return out;
     }
     if (Array.isArray(c) && Array.isArray(p)) {
       const out = new Array(c.length) as unknown[];
       done.set(c, out);
       for (let i = 0; i < c.length; i++) {
-        if (i in c) out[i] = i < p.length ? share(p[i], c[i]) : c[i];
+        if (i in c) out[i] = share(p[i], c[i]);
       }
       return out;
     }
@@ -255,12 +302,11 @@ export function shareEqual<T>(prev: unknown, curr: T): T {
       done.set(c, out);
       const cr = c as Record<string, unknown>;
       for (const key of Object.keys(cr)) {
-        setOwn(out, key, hasOwn(p, key) ? share(p[key], cr[key]) : cr[key]);
+        setOwn(out, key, share(hasOwn(p, key) ? p[key] : undefined, cr[key]));
       }
       return out;
     }
-    done.set(c, c);
-    return c;
+    return fresh(c);
   }
   return share(prev, curr) as T;
 }
@@ -288,9 +334,17 @@ function equalBuiltin(
 ): boolean | undefined {
   if (a instanceof Date) return Object.is(a.getTime(), (b as Date).getTime());
   if (a instanceof RegExp) return String(a) === String(b);
-  if (ArrayBuffer.isView(a) || a instanceof ArrayBuffer) {
-    return equalBytes(a, b as ArrayBuffer);
+  if (ArrayBuffer.isView(a)) {
+    // A view is its place in its backing buffer, and the whole buffer (which
+    // other views can share): equal only if both match.
+    const v = b as ArrayBufferView;
+    return (
+      a.byteOffset === v.byteOffset &&
+      a.byteLength === v.byteLength &&
+      equal(a.buffer, v.buffer, assumed)
+    );
   }
+  if (a instanceof ArrayBuffer) return equalBytes(a, b as ArrayBuffer);
   if (a instanceof URL || a instanceof URLSearchParams) {
     return String(a) === String(b);
   }
@@ -475,7 +529,17 @@ export function keyChanges(
 
 /** A write to one property path of an object, or its deletion. */
 export type PathChange =
-  | { path: string[]; deleted: false; value: unknown }
+  | {
+      path: string[];
+      deleted: false;
+      value: unknown;
+      /**
+       * Set where the value is the same content as before and only which
+       * object the path refers to changed (see aliasChanges), so a store
+       * holding equal content there still takes the write.
+       */
+      alias?: true;
+    }
   | { path: string[]; deleted: true };
 
 /**
@@ -514,6 +578,130 @@ export function diffPaths(
   return changes;
 }
 
+export const pathKey = (path: readonly string[]): string =>
+  JSON.stringify(path);
+
+/** Whether `path`, or one of its ancestors, is one of `keys`. */
+export function underChange(
+  path: readonly string[],
+  keys: ReadonlySet<string>,
+): boolean {
+  for (let n = 1; n <= path.length; n++) {
+    if (keys.has(pathKey(path.slice(0, n)))) return true;
+  }
+  return false;
+}
+
+/**
+ * Where each object (or array, or other value) of `root` first appears, in
+ * depth-first order. Plain objects are entered; arrays and other values are
+ * leaves. A path at or below one of `skip` is left out.
+ */
+function firstPaths(
+  root: Record<string, unknown>,
+  skip: ReadonlySet<string> = new Set(),
+): Map<object, string[]> {
+  const found = new Map<object, string[]>();
+  (function walk(node: Record<string, unknown>, path: string[]): void {
+    for (const key of Object.keys(node)) {
+      const value = node[key];
+      if (!isObjectValue(value) || found.has(value)) continue;
+      const at = [...path, key];
+      if (skip.has(pathKey(at))) continue;
+      found.set(value, at);
+      if (isMergeable(value)) walk(value, at);
+    }
+  })(root, []);
+  return found;
+}
+
+/**
+ * The paths whose object is another one in the references of `after` than in
+ * `before`, as to where its first appearance is: `$a = $b` makes `a` another
+ * name for the object of `b` even where both hold equal content, and a
+ * `diffPaths` over the content finds nothing. Only paths both hold an object
+ * at are reported, parents before children; each is a write of the object
+ * `after` holds.
+ */
+export function aliasChanges(
+  before: Record<string, unknown>,
+  after: Record<string, unknown>,
+): PathChange[] {
+  const earlier = firstPaths(before);
+  const later = firstPaths(after);
+  const changes: PathChange[] = [];
+  (function walk(
+    b: Record<string, unknown>,
+    a: Record<string, unknown>,
+    path: string[],
+  ): void {
+    for (const key of Object.keys(a)) {
+      if (!hasOwn(b, key)) continue;
+      const x = b[key];
+      const y = a[key];
+      if (!isObjectValue(x) || !isObjectValue(y)) continue;
+      const at = [...path, key];
+      const wasAt = earlier.get(x)!;
+      const isAt = later.get(y)!;
+      const k = pathKey(at);
+      if (pathKey(wasAt) !== pathKey(isAt)) {
+        changes.push({ path: at, deleted: false, value: y, alias: true });
+      }
+      // Only paths that are first appearances are entered: elsewhere the
+      // contents are those of the object met first.
+      if (
+        isMergeable(x) &&
+        mergesWith(x, y, false) &&
+        pathKey(isAt) === k &&
+        pathKey(wasAt) === k
+      ) {
+        walk(x, y as Record<string, unknown>, at);
+      }
+    }
+  })(before, after, []);
+  return changes;
+}
+
+/**
+ * Where the objects of `source` are, other than at or below the paths of
+ * `changes` (which write something new there), for `existingObjects`.
+ */
+export function locateObjects(
+  source: Record<string, unknown>,
+  changes: readonly PathChange[],
+): Map<object, string[]> {
+  return firstPaths(source, new Set(changes.map((c) => pathKey(c.path))));
+}
+
+/**
+ * A map for `deepClone`'s `seen`: an object of the source `paths` locate
+ * (see locateObjects) is copied as the object at the same path in `target`,
+ * so a value that refers to an object the store holds refers to it again
+ * after the copy, not to a copy of it. Objects are looked up in `target`
+ * when met, not up front.
+ */
+export function existingObjects(
+  paths: ReadonlyMap<object, string[]>,
+  target: Record<string, unknown>,
+): Map<object, object> {
+  return new (class extends Map<object, object> {
+    override has(obj: object): boolean {
+      if (super.has(obj)) return true;
+      const path = paths.get(obj);
+      if (!path) return false;
+      const found = getByPath(target, path);
+      const like =
+        isObjectValue(found) &&
+        (Array.isArray(found)
+          ? Array.isArray(obj)
+          : Object.getPrototypeOf(found) === Object.getPrototypeOf(obj));
+      if (!like) return false;
+      super.set(obj, found as object);
+      return true;
+    }
+  })();
+}
+
 /** Whether `target` already holds what `change` would write. */
 export function isApplied(
   target: Record<string, unknown>,

package/src/triggers.ts

@@ -305,15 +305,35 @@ export function registerDialogHost(callbacks: DialogHostCallbacks): () => void {
   };
 }
 
+/**
+ * The dialogs on display, bottom first, whoever opened them: the trigger
+ * host, `{dialog}` or a menubar button (each PassageDialog registers itself
+ * while mounted), as the function that closes each.
+ */
+const openDialogs: Array<() => void> = [];
+
+/** Register a displayed dialog; returns the function that unregisters it. */
+export function registerOpenDialog(close: () => void): () => void {
+  openDialogs.push(close);
+  return () => {
+    const i = openDialogs.lastIndexOf(close);
+    if (i >= 0) openDialogs.splice(i, 1);
+  };
+}
+
+/** Close the topmost dialog. */
 export function closeCurrentDialog(): void {
-  dialogHostCallbacks?.close();
+  const top = openDialogs[openDialogs.length - 1];
+  if (top) top();
+  else dialogHostCallbacks?.close();
 }
 
 export function closeAllOpenDialogs(): void {
   clearDialogQueue();
+  for (const close of [...openDialogs].reverse()) close();
   dialogHostCallbacks?.closeAll();
 }
 
 export function isDialogShowing(): boolean {
-  return dialogHostCallbacks?.isOpen() ?? false;
+  return openDialogs.length > 0 || (dialogHostCallbacks?.isOpen() ?? false);
 }

package/src/utils/uuid.ts

@@ -0,0 +1,18 @@
+/**
+ * A random UUID (v4). `crypto.randomUUID` exists only in secure contexts, so
+ * on a plain HTTP origin the ID is built from `crypto.getRandomValues`.
+ */
+export function randomUUID(): string {
+  if (typeof crypto.randomUUID === 'function') return crypto.randomUUID();
+  const bytes = crypto.getRandomValues(new Uint8Array(16));
+  bytes[6] = (bytes[6]! & 0x0f) | 0x40;
+  bytes[8] = (bytes[8]! & 0x3f) | 0x80;
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0'));
+  return [
+    hex.slice(0, 4).join(''),
+    hex.slice(4, 6).join(''),
+    hex.slice(6, 8).join(''),
+    hex.slice(8, 10).join(''),
+    hex.slice(10).join(''),
+  ].join('-');
+}