@rohal12/spindle 0.52.3 → 0.52.5

package/package.json

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

package/src/class-registry.ts

@@ -1,5 +1,11 @@
 // Class registry for preserving class instances across clone/save/load cycles.
 
+import { setOwn } from './structural';
+import { hasOwn } from './utils/namespace';
+
+// Copying and comparing story values live with the structural diff
+export { deepClone, deepEqual, type DeepCloneOptions } from './structural';
+
 type Constructor = new (...args: any[]) => any;
 
 const registry = new Map<string, Constructor>();
@@ -33,188 +39,6 @@ export function clearRegistry(): void {
   ctorToName.clear();
 }
 
-// --- Deep Clone ---
-
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  if (typeof value !== 'object' || value === null) return false;
-  const proto = Object.getPrototypeOf(value);
-  return proto === Object.prototype || proto === null;
-}
-
-/**
- * Set an own enumerable property. A "__proto__" key is defined as an own
- * property (as JSON.parse does) instead of replacing the prototype.
- */
-function setOwn(target: object, key: string, value: unknown): void {
-  if (key === '__proto__') {
-    Object.defineProperty(target, key, {
-      value,
-      enumerable: true,
-      writable: true,
-      configurable: true,
-    });
-  } else {
-    (target as Record<string, unknown>)[key] = value;
-  }
-}
-
-export interface DeepCloneOptions {
-  /**
-   * Return instances of unregistered classes (DOM nodes, promises, other
-   * library objects) by reference instead of copying their own keys into a
-   * plain object, which would lose their prototype and identity.
-   */
-  keepUnregistered?: boolean;
-}
-
-export function deepClone<T>(value: T, options: DeepCloneOptions = {}): T {
-  const seen = new Map<object, object>();
-
-  function clone(val: unknown): unknown {
-    if (val === null || typeof val !== 'object') return val;
-
-    const obj = val as object;
-    if (seen.has(obj)) return seen.get(obj);
-
-    if (val instanceof Date) return new Date(val.getTime()) as unknown;
-    if (val instanceof RegExp)
-      return new RegExp(val.source, val.flags) as unknown;
-
-    if (Array.isArray(val)) {
-      const arr: unknown[] = [];
-      seen.set(obj, arr);
-      for (let i = 0; i < val.length; i++) {
-        arr[i] = clone(val[i]);
-      }
-      return arr;
-    }
-
-    if (val instanceof Map) {
-      const copy = new Map();
-      seen.set(obj, copy);
-      for (const [k, v] of val) {
-        copy.set(clone(k), clone(v));
-      }
-      return copy;
-    }
-
-    if (val instanceof Set) {
-      const copy = new Set();
-      seen.set(obj, copy);
-      for (const v of val) {
-        copy.add(clone(v));
-      }
-      return copy;
-    }
-
-    // Registered class instance
-    const name = registeredClassName(obj);
-    if (name !== undefined) {
-      const copy = Object.create(Object.getPrototypeOf(obj)) as Record<
-        string,
-        unknown
-      >;
-      seen.set(obj, copy);
-      for (const key of Object.keys(obj)) {
-        setOwn(copy, key, clone((obj as Record<string, unknown>)[key]));
-      }
-      return copy;
-    }
-
-    // Plain object (or unregistered class — treat as plain). A plain object
-    // keeps its prototype, which may be null.
-    const plain = isPlainObject(val);
-    if (!plain && options.keepUnregistered) return val;
-    const copy = (
-      plain ? Object.create(Object.getPrototypeOf(obj) as object | null) : {}
-    ) as Record<string, unknown>;
-    seen.set(obj, copy);
-    for (const key of Object.keys(obj)) {
-      setOwn(copy, key, clone((obj as Record<string, unknown>)[key]));
-    }
-    return copy;
-  }
-
-  return clone(value) as T;
-}
-
-// --- Deep Equal ---
-
-/**
- * Structural equality over the value types deepClone() supports: primitives,
- * arrays, plain objects, class instances, Date, RegExp, Map and Set (nested
- * at any depth). Map and Set entries are compared in insertion order. Arrays
- * are compared by length and index, so a hole equals an undefined element
- * (deepClone() and save/load turn holes into undefined elements).
- */
-export function deepEqual(a: unknown, b: unknown): boolean {
-  return equal(a, b, new Map());
-}
-
-/**
- * `assumed` holds the pairs already being compared: meeting one again (a
- * cycle) assumes it equal. Every object may pair with several others, since
- * cycles of different lengths can still unfold to the same value.
- */
-function equal(
-  a: unknown,
-  b: unknown,
-  assumed: Map<object, Set<object>>,
-): boolean {
-  if (Object.is(a, b)) return true;
-  if (
-    a === null ||
-    b === null ||
-    typeof a !== 'object' ||
-    typeof b !== 'object'
-  ) {
-    return false;
-  }
-  if (Object.getPrototypeOf(a) !== Object.getPrototypeOf(b)) return false;
-  const pairs = assumed.get(a);
-  if (pairs?.has(b)) return true;
-  if (pairs) pairs.add(b);
-  else assumed.set(a, new Set([b]));
-
-  if (a instanceof Date) return Object.is(a.getTime(), (b as Date).getTime());
-  if (a instanceof RegExp) return String(a) === String(b);
-  if (a instanceof Map || a instanceof Set) {
-    const bc = b as Map<unknown, unknown> | Set<unknown>;
-    if (a.size !== bc.size) return false;
-    const ai = a.entries();
-    const bi = bc.entries();
-    for (
-      let x = ai.next(), y = bi.next();
-      !x.done;
-      x = ai.next(), y = bi.next()
-    ) {
-      if (!equal(x.value, y.value, assumed)) return false;
-    }
-    return true;
-  }
-
-  if (Array.isArray(a)) {
-    const bc = b as unknown[];
-    if (a.length !== bc.length) return false;
-    for (let i = 0; i < a.length; i++) {
-      if (!equal(a[i], bc[i], assumed)) return false;
-    }
-    return true;
-  }
-
-  const ao = a as Record<string, unknown>;
-  const bo = b as Record<string, unknown>;
-  const keys = Object.keys(ao);
-  if (keys.length !== Object.keys(bo).length) return false;
-  for (const key of keys) {
-    if (!hasOwn(bo, key) || !equal(ao[key], bo[key], assumed)) return false;
-  }
-  return true;
-}
-
-const hasOwn = (obj: object, key: string): boolean =>
-  Object.prototype.hasOwnProperty.call(obj, key);
-
 // --- Serialize ---
 
 const CLASS_TAG = '__spindle_class__';

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/execute-mutation.ts

@@ -9,9 +9,18 @@ import {
 import { useStoryStore } from './store';
 import type { StoryState, VariableNamespaces } from './store';
 import { execute } from './expression';
-import { deepClone, deepEqual } from './class-registry';
-import { deleteByPath, getByPath, setByPath } from './utils/object-path';
-import { asNamespace } from './utils/namespace';
+import {
+  applyChange,
+  deepClone,
+  deepEqual,
+  diffPaths,
+  isApplied,
+  isMergeable,
+  mergeKeys,
+  type PathChange,
+} from './structural';
+import { getByPath } from './utils/object-path';
+import { asNamespace, hasOwn } from './utils/namespace';
 
 type NamespaceName = keyof VariableNamespaces;
 
@@ -21,11 +30,6 @@ const NAMESPACES: readonly NamespaceName[] = [
   'transient',
 ];
 
-/** A write to one property path of a namespace, or its deletion. */
-type PathChange =
-  | { path: string[]; deleted: false; value: unknown }
-  | { path: string[]; deleted: true };
-
 /**
  * The state of one executing mutation. The code reads and writes `work`.
  * `base` is what `work` started as, with every write made elsewhere during
@@ -76,80 +80,6 @@ export function frozenCopy<T>(value: T): T {
   return freeze(cloneValue(value), true);
 }
 
-/**
- * Objects merged property by property: plain objects and (registered)
- * class instances. Arrays, Map, Set, Date and RegExp are values that are
- * replaced as a whole, since their elements have no stable identity to
- * merge by (a shift moves every index).
- */
-export function isMergeable(value: unknown): value is Record<string, unknown> {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    !Array.isArray(value) &&
-    !(value instanceof Map) &&
-    !(value instanceof Set) &&
-    !(value instanceof Date) &&
-    !(value instanceof RegExp)
-  );
-}
-
-const hasOwn = (obj: object, key: string): boolean =>
-  Object.prototype.hasOwnProperty.call(obj, key);
-
-/** Collect the property paths where `work` differs from `base`. */
-function diff(
-  base: Record<string, unknown>,
-  work: Record<string, unknown>,
-  path: string[],
-  changes: PathChange[],
-  ancestors: Set<object>,
-): void {
-  // Stop at cycles; shared (non-cyclic) references are visited per path.
-  if (ancestors.has(work)) return;
-  ancestors.add(work);
-  for (const key of Object.keys(work)) {
-    const b = base[key];
-    const w = work[key];
-    if (!hasOwn(base, key)) {
-      changes.push({ path: [...path, key], deleted: false, value: w });
-    } else if (Object.is(b, w)) {
-      // The same value (an untouched subtree of an Immer update)
-      continue;
-    } else if (
-      isMergeable(b) &&
-      isMergeable(w) &&
-      Object.getPrototypeOf(b) === Object.getPrototypeOf(w)
-    ) {
-      diff(b, w, [...path, key], changes, ancestors);
-    } else if (!deepEqual(b, w)) {
-      changes.push({ path: [...path, key], deleted: false, value: w });
-    }
-  }
-  for (const key of Object.keys(base)) {
-    if (!hasOwn(work, key))
-      changes.push({ path: [...path, key], deleted: true });
-  }
-  ancestors.delete(work);
-}
-
-/** Whether `ns` already holds what `change` would write. */
-function isApplied(ns: Record<string, unknown>, change: PathChange): boolean {
-  const parent = getByPath(ns, change.path.slice(0, -1));
-  if (parent === null || typeof parent !== 'object') return change.deleted;
-  const key = change.path[change.path.length - 1]!;
-  if (!hasOwn(parent, key)) return change.deleted;
-  return (
-    !change.deleted &&
-    deepEqual((parent as Record<string, unknown>)[key], change.value)
-  );
-}
-
-function applyChange(ns: Record<string, unknown>, change: PathChange): void {
-  if (change.deleted) deleteByPath(ns, change.path);
-  else setByPath(ns, change.path, change.value);
-}
-
 /**
  * Apply a write that reached the store while mutations execute to their
  * `work` and `base` copies (see MutationScope), so the code sees it and
@@ -381,11 +311,9 @@ function commitScopes(commits: readonly Commit[]): void {
   const all = commits.map(({ scope, keepRunning }) => ({
     scope,
     keepRunning,
-    changes: NAMESPACES.map((ns) => {
-      const list: PathChange[] = [];
-      diff(scope.base[ns], scope.work[ns], [], list, new Set());
-      return [ns, list] as const;
-    }),
+    changes: NAMESPACES.map(
+      (ns) => [ns, diffPaths(scope.base[ns], scope.work[ns])] as const,
+    ),
   }));
   const changed = all.filter(({ changes }) =>
     changes.some(([, list]) => list.length > 0),
@@ -450,16 +378,8 @@ const running = (): Commit[] =>
 function resync(scope: MutationScope): void {
   const state = useStoryStore.getState();
   for (const ns of NAMESPACES) {
-    const work = scope.work[ns];
-    const stored = state[ns];
-    for (const key of Object.keys(work)) {
-      if (!hasOwn(stored, key)) delete work[key];
-    }
-    for (const key of Object.keys(stored)) {
-      if (!hasOwn(work, key) || !deepEqual(work[key], stored[key])) {
-        work[key] = deepClone(stored[key]);
-      }
-    }
+    // Root by root: a root that differs is replaced with a copy of the store's
+    mergeKeys(scope.work[ns], scope.work[ns], state[ns]);
   }
   scope.base = cloneNamespaces(state);
 }

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