@rohal12/spindle 0.58.0 → 0.59.1

package/src/store.ts

@@ -120,7 +120,10 @@ let lastNavigationVars: Namespace = createNamespace();
  * object) or deleted. A recorded value is a deep copy, so that changing a
  * live value in place (a class instance is not frozen) cannot change
  * history; instances of unregistered classes are kept, as the store keeps
- * them (a save then refuses them).
+ * them (a save then refuses them). The copies are made together, so what
+ * variables share (an object, a cycle) stays shared in them, and a variable
+ * left as it is that shares with a replaced one is recorded again, to share
+ * with its copy.
  */
 function computeVarPatches(
   prev: Record<string, unknown>,
@@ -132,13 +135,32 @@ function computeVarPatches(
     // whose inherited `constructor` is no variable
     if (!hasOwn(curr, key)) forward.push({ key, deleted: true });
   }
+  const seen = new Map<object, object>();
+  const record = (key: string) =>
+    forward.push({
+      key,
+      deleted: false,
+      value: deepClone(curr[key], { keepUnregistered: true, seen }),
+    });
+  const unchanged: string[] = [];
   for (const key of Object.keys(curr)) {
-    if (!hasOwn(prev, key) || !Object.is(prev[key], curr[key])) {
-      forward.push({
-        key,
-        deleted: false,
-        value: deepClone(curr[key], { keepUnregistered: true }),
-      });
+    if (!hasOwn(prev, key) || !Object.is(prev[key], curr[key])) record(key);
+    else if (typeof curr[key] === 'object' && curr[key] !== null) {
+      unchanged.push(key);
+    }
+  }
+  // Probe an unchanged variable with a copy of its own: it shares with a
+  // recorded one if the copy meets an object already copied
+  for (let found = seen.size > 0; found; ) {
+    found = false;
+    for (const key of unchanged) {
+      const probe = new Map<object, object>();
+      deepClone(curr[key], { keepUnregistered: true, seen: probe });
+      if (![...probe.keys()].some((object) => seen.has(object))) continue;
+      record(key);
+      unchanged.splice(unchanged.indexOf(key), 1);
+      found = true;
+      break;
     }
   }
   return { forward };

package/src/story-variables.ts

@@ -9,7 +9,12 @@ import {
   scanStringLiteral,
   type JsGoal,
 } from './js-lexer';
-import { argPieces, parseOrError, withParseCache } from './code-check';
+import {
+  argPieces,
+  parseOrError,
+  withParseCache,
+  type ParametersOf,
+} from './code-check';
 import { getMacroParameters, type ParameterDef } from './registry';
 import { NOT_MARKUP } from './markup/validate';
 import { createNamespace, variableNameError } from './utils/namespace';
@@ -47,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']);
 
@@ -125,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.
@@ -148,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]!;
@@ -156,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}`;
@@ -246,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,
@@ -264,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. */
@@ -273,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,
     {
@@ -283,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);
 }
 
 /**
@@ -334,25 +295,30 @@ function collectPassageRefs(
   );
 }
 
-/** The declared parameters of a macro, if it has any. */
-type ParametersOf = (macro: string) => readonly ParameterDef[] | undefined;
-
 /**
- * Report the references in the code that a macro's quoted arguments hold,
- * the condition and `run` action of `{watch}`: the argument scan sees only
- * the strings.
+ * 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) 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`. */
@@ -375,13 +341,14 @@ 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);
 
       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') {
@@ -426,12 +393,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;
 }

package/src/tooling.ts

@@ -11,8 +11,11 @@ import {
 } from './markup/validate';
 import { isBlockMacro } from './markup/ast';
 import { tokenizeMarkupTolerant } from './markup/parse';
-import { collectPassageReferences, type PassageReference } from './code-check';
-import { subMacroParameters } from './components/macros/option-utils';
+import {
+  collectPassageReferences,
+  parameterLookup,
+  type PassageReference,
+} from './code-check';
 import { blockWidgetNames } from './widgets/widget-def';
 import type { ParameterDef } from './registry';
 
@@ -71,8 +74,13 @@ export interface ToolingMacro {
   name: string;
   block: boolean;
   subMacros: string[];
-  /** Its declared parameters: their types tell which arguments are code. */
+  /**
+   * Its declared parameters: their types tell which arguments are code, and
+   * what a `string` or `text` argument holds (see ParameterDef.holds).
+   */
   parameters?: readonly ParameterDef[];
+  /** Whether it resolves markup: its strings hold markup by default. */
+  interpolate?: boolean;
 }
 
 /**
@@ -87,20 +95,19 @@ export function validateStoryMarkup(
   options: ValidateMarkupOptions = {},
 ): MarkupDiagnostic[] {
   const list = [...passages];
+  const all = [...macros];
   const known = new Set<string>();
-  const parameters = new Map<string, readonly ParameterDef[] | undefined>();
   const blocks = new Set(blockWidgetNames(list).map((n) => n.toLowerCase()));
-  for (const macro of macros) {
+  for (const macro of all) {
     const name = macro.name.toLowerCase();
     known.add(name);
-    parameters.set(name, macro.parameters);
     for (const sub of macro.subMacros) known.add(sub.toLowerCase());
     if (macro.block) blocks.add(name);
   }
   return validateMarkup(list, {
     isKnownMacro: (name) => known.has(name),
     macroNames: known,
-    parametersOf: (name) => parameters.get(name),
+    parametersOf: parameterLookup(all),
     isBlockMacro: (name) =>
       blocks.has(name.toLowerCase()) || isBlockMacro(name),
     checkPassageNames: options.checkPassageNames,
@@ -116,14 +123,6 @@ export function collectStoryPassageReferences(
   source: string,
   macros: Iterable<ToolingMacro>,
 ): PassageReference[] {
-  const parameters = new Map<string, readonly ParameterDef[] | undefined>();
-  for (const macro of macros) {
-    parameters.set(macro.name.toLowerCase(), macro.parameters);
-  }
   const { tokens } = tokenizeMarkupTolerant(source);
-  return collectPassageReferences(
-    source,
-    tokens,
-    (name) => parameters.get(name.toLowerCase()) ?? subMacroParameters(name),
-  );
+  return collectPassageReferences(source, tokens, parameterLookup(macros));
 }

package/src/widgets/widget-def.ts

@@ -7,8 +7,8 @@ import type { MacroArgs } from '../registry';
 
 /** A {widget} definition's name, then its `@` parameters. */
 export const WIDGET_PARAMETERS = [
-  { name: 'name', type: 'text', required: true },
-  { name: 'parameters', type: 'text' },
+  { name: 'name', type: 'text', holds: 'text', required: true },
+  { name: 'parameters', type: 'text', holds: 'text' },
 ] as const;
 
 export interface WidgetDef {

package/types/index.d.ts

@@ -272,6 +272,27 @@ export type ParameterType =
   | 'separator'
   | 'options';
 
+/**
+ * What the value of a `string` or `text` argument holds, for the check at
+ * story start and for tooling:
+ * - `markup`: markup the macro renders (`{button}`'s label): its markup
+ *   is checked.
+ * - `text`: plain text the macro uses as written (`{checkbox}`'s label).
+ * - `passage`: a passage name (`{watch}`'s `goto`): the passage must exist.
+ * - `expression`, `statements`: code (`{watch}`'s condition and `run`): it
+ *   is checked as code, and its variable references against the schema.
+ *
+ * Without it, the argument of a macro with `interpolate` holds `markup`,
+ * any other `text`.
+ * @see {@link ../../src/registry.ts} for the implementation.
+ */
+export type StringHolds =
+  | 'markup'
+  | 'text'
+  | 'passage'
+  | 'expression'
+  | 'statements';
+
 /**
  * Parameter metadata for a macro definition.
  * @see {@link ../../src/registry.ts} for the implementation.
@@ -282,6 +303,8 @@ export interface ParameterDef {
   description?: string;
   /** How the argument is read: required, there is no default. */
   type: ParameterType;
+  /** What a `string` or `text` argument holds (see StringHolds). */
+  holds?: StringHolds;
   /** The options of an `options` parameter. */
   parameters?: readonly ParameterDef[];
 }

package/types/tooling.d.ts

@@ -30,12 +30,34 @@ export type ParameterType =
   | 'separator'
   | 'options';
 
+/**
+ * What the value of a `string` or `text` argument holds, for the check at
+ * story start and for tooling:
+ * - `markup`: markup the macro renders (`{button}`'s label): its markup
+ *   is checked.
+ * - `text`: plain text the macro uses as written (`{checkbox}`'s label).
+ * - `passage`: a passage name (`{watch}`'s `goto`): the passage must exist.
+ * - `expression`, `statements`: code (`{watch}`'s condition and `run`): it
+ *   is checked as code, and its variable references against the schema.
+ *
+ * Without it, the argument of a macro with `interpolate` holds `markup`,
+ * any other `text`.
+ */
+export type StringHolds =
+  | 'markup'
+  | 'text'
+  | 'passage'
+  | 'expression'
+  | 'statements';
+
 export interface ParameterDef {
   name: string;
   required?: boolean;
   description?: string;
   /** How the argument is read: required, there is no default. */
   type: ParameterType;
+  /** What a `string` or `text` argument holds (see StringHolds). */
+  holds?: StringHolds;
   /** The options of an `options` parameter. */
   parameters?: readonly ParameterDef[];
 }
@@ -285,6 +307,9 @@ export interface LinkToken extends TokenSpan, Selectors {
   type: 'link';
   display: string;
   target: string;
+  /** Where the target is written, from `targetStart` to `targetEnd`. */
+  targetStart: number;
+  targetEnd: number;
 }
 
 export interface MacroToken extends TokenSpan, Selectors {
@@ -465,8 +490,9 @@ export interface PassageReference {
  * The passages the markup of `source` names, in source order: `[[…]]` links,
  * the passage of `{goto}`, `{include}` and `{link}` (and of macros that
  * declare a `passage` argument), the `goto` and `dialog` actions of
- * `{watch}` and the body of `{dialog}`. Malformed tags are skipped, so
- * half-typed markup reads.
+ * `{watch}` (and the `string` and `text` arguments of macros that declare
+ * they hold a passage name) and the body of `{dialog}`. Malformed tags are
+ * skipped, so half-typed markup reads.
  */
 export declare function collectPassageReferences(
   source: string,