@rohal12/spindle 0.59.15 → 0.59.17

package/src/story-variables.ts

@@ -68,18 +68,30 @@ const PRIMITIVE_SAMPLES: Partial<Record<VarType, object>> = {
   boolean: Object(false),
 };
 
-function inferSchema(value: unknown): FieldSchema {
+/**
+ * The schema of a default value. An object met again (a backreference, a
+ * shared subtree) has the schema made for it the first time, so a cyclic
+ * default gives a schema that refers to itself instead of recursing forever.
+ */
+function inferSchema(
+  value: unknown,
+  seen = new Map<object, FieldSchema>(),
+): FieldSchema {
   if (Array.isArray(value)) {
     return { type: 'array' };
   }
   // A default of null means "nothing yet"; the value may later be anything
   if (value === null) return { type: 'null' };
   if (typeof value === 'object') {
+    const known = seen.get(value);
+    if (known) return known;
     const fields = new Map<string, FieldSchema>();
+    const schema: FieldSchema = { type: 'object', fields };
+    seen.set(value, schema);
     for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
-      fields.set(key, inferSchema(val));
+      fields.set(key, inferSchema(val, seen));
     }
-    return { type: 'object', fields };
+    return schema;
   }
   const jsType = typeof value;
   if (!VALID_VAR_TYPES.has(jsType)) {

package/src/structural.ts

@@ -859,6 +859,28 @@ function setEntryValue(
   return true;
 }
 
+/**
+ * The own enumerable fields of a Map, Set, Date or RegExp (an instance of a
+ * registered subclass may hold some besides its built-in content, #412);
+ * none for any other value.
+ */
+function builtinFields(value: object): string[] {
+  return value instanceof Map ||
+    value instanceof Set ||
+    value instanceof Date ||
+    value instanceof RegExp
+    ? extraKeys(value)
+    : [];
+}
+
+/** Whether `x` and `y` are built-ins of one class that may hold fields. */
+function sameBuiltin(x: object, y: object): boolean {
+  return (
+    Object.getPrototypeOf(x) === Object.getPrototypeOf(y) &&
+    (builtinFields(x).length > 0 || builtinFields(y).length > 0)
+  );
+}
+
 /**
  * Every path each object (or array, or other value) of `root` is at, the
  * first appearance first, in depth-first order. Plain objects and arrays are
@@ -888,12 +910,17 @@ function objectPaths(
     all.set(value, [at]);
     if (isMergeable(value) || Array.isArray(value)) {
       walk(value as Record<string, unknown>, at);
-    } else if (entries && entryChildren(value)) {
-      collections.push([value, at]);
+    } else {
+      walk(value as Record<string, unknown>, at, builtinFields(value));
+      if (entries && entryChildren(value)) collections.push([value, at]);
     }
   }
-  function walk(node: Record<string, unknown>, path: string[]): void {
-    for (const key of Object.keys(node)) {
+  function walk(
+    node: Record<string, unknown>,
+    path: string[],
+    keys: string[] = Object.keys(node),
+  ): void {
+    for (const key of keys) {
       const value = node[key];
       if (!isObjectValue(value)) continue;
       const at = [...path, key];
@@ -963,12 +990,16 @@ function aliasMoved(
     for (const [segment, a] of xs) {
       if (held.has(segment)) pairs.push([segment, a, held.get(segment)]);
     }
-  } else if ((isMergeable(x) || Array.isArray(x)) && mergesWith(x, y, true)) {
-    for (const key of Object.keys(y)) {
-      if (hasOwn(x, key)) {
-        pairs.push([key, (x as any)[key], (y as any)[key]]);
-      }
-    }
+  }
+  // The properties both hold: of objects that merge, and the fields of a
+  // built-in subclass instance besides its entries (#412)
+  const keys = mergesWith(x, y, true)
+    ? Object.keys(y)
+    : sameBuiltin(x, y)
+      ? builtinFields(y)
+      : [];
+  for (const key of keys) {
+    if (hasOwn(x, key)) pairs.push([key, (x as any)[key], (y as any)[key]]);
   }
   return pairs.some(([segment, a, b]) => {
     if (!isObjectValue(a) || !isObjectValue(b)) return false;
@@ -1002,7 +1033,9 @@ export function aliasChanges(
     a: Record<string, unknown>,
     path: string[],
   ): void {
-    for (const key of Object.keys(a)) {
+    for (const key of Array.isArray(a) || isMergeable(a)
+      ? Object.keys(a)
+      : builtinFields(a)) {
       if (!hasOwn(b, key)) continue;
       const x = b[key];
       const y = a[key];
@@ -1023,8 +1056,8 @@ export function aliasChanges(
       // Only paths that are first appearances are entered: elsewhere the
       // contents are those of the object met first.
       if (
-        (isMergeable(x) || Array.isArray(x)) &&
-        mergesWith(x, y, true) &&
+        (((isMergeable(x) || Array.isArray(x)) && mergesWith(x, y, true)) ||
+          sameBuiltin(x, y)) &&
         pathKey(isAt) === k &&
         pathKey(wasAt) === k
       ) {

package/src/triggers.ts

@@ -1,6 +1,7 @@
 import { evaluate } from './expression';
 import { executeMutation, readState } from './execute-mutation';
 import { useStoryStore } from './store';
+import { createListeners } from './utils/listeners';
 
 export interface WatchOptions {
   goto?: string;
@@ -301,9 +302,25 @@ export function reinitTriggerState(): void {
  */
 export function resetTriggers(): void {
   triggers = [];
+  resets++;
   closeAllOpenDialogs();
+  resetListeners.notify();
 }
 
+let resets = 0;
+const resetListeners = createListeners();
+
+/** How many times resetTriggers has forgotten every watcher. */
+export function triggerResets(): number {
+  return resets;
+}
+
+/**
+ * Call `listener` after each resetTriggers (a restart): a {watch} that stays
+ * mounted, in the story interface, registers its watcher again (#402).
+ */
+export const subscribeTriggerResets = resetListeners.subscribe;
+
 export function subscribeTriggerDialogs(cb: () => void): () => void {
   dialogNotify = cb;
   // Flush any queued dialogs

package/src/utils/control-edits.ts

@@ -1,48 +1,99 @@
+import { createContext } from 'preact';
+import { readState } from '../execute-mutation';
+import { diffPaths } from '../structural';
 import { getByPath } from './object-path';
+import type { VariableNamespaces } from '../store';
 
 /**
- * Records the edits a reader made through a control bound to a story
- * variable (`{textbox}`, `{checkbox}`, ...). {for} tells these apart from a
- * list that is replaced: typing into a control inside an iteration changes
- * its item, but must not remount the iteration and drop the control's focus.
+ * Records the edits made to the items of a list from inside a {for}
+ * iteration, which {for} tells apart from a list that is replaced:
+ *
+ * - a reader editing a variable through a control (`{textbox}`,
+ *   `{checkbox}`, ...): typing into a control inside an iteration changes
+ *   its item, but must not remount the iteration and drop the control's
+ *   focus (#369);
+ * - mutation code an iteration runs as it renders (`{set $party[@i].hp +=
+ *   1}`): remounting would run the iteration's mount-only macros, and so the
+ *   write, again for every write it makes (#400).
+ *
  * An edit is attributed to the variable path it wrote, so a replacement made
- * elsewhere (a watcher reacting to the edit) still remounts.
+ * elsewhere (a watcher reacting to the edit, a button outside the loop)
+ * still remounts.
  */
 let version = 0;
-const MAX_LOG = 256;
-const log: { version: number; segments: readonly string[] }[] = [];
+const MAX_LOG = 4096;
+/** Edits in the order made: paths below the namespaces (`['variables', 'a']`). */
+const log: { version: number; path: readonly string[] }[] = [];
 
-export function noteControlEdit(segments: readonly string[]): void {
-  log.push({ version: ++version, segments });
+function note(path: readonly string[]): void {
+  log.push({ version: ++version, path });
   if (log.length > MAX_LOG) log.shift();
 }
 
+/** Note an edit a control made to the story variable at `segments`. */
+export function noteControlEdit(segments: readonly string[]): void {
+  note(['variables', ...segments]);
+}
+
+/**
+ * Whether mutation code runs inside a {for} iteration: {for} provides true
+ * around its iterations, and the writes of such code are noted as edits of
+ * the items they reach (see runAsItemEdit).
+ */
+export const ItemEditContext = createContext(false);
+
+const NAMESPACES = ['variables', 'temporary', 'transient'] as const;
+
+/** Run `run`, noting each variable path it changes as an edit. */
+export function runAsItemEdit(run: () => void): void {
+  const before = readState();
+  try {
+    run();
+  } finally {
+    const after = readState();
+    for (const ns of NAMESPACES) {
+      if (before[ns] === after[ns]) continue;
+      for (const { path } of diffPaths(before[ns], after[ns], true)) {
+        note([ns, ...path]);
+      }
+    }
+  }
+}
+
 export function controlEditVersion(): number {
   return version;
 }
 
 /**
- * Whether an edit since `since` wrote inside `item`, element `index` of
- * `list`: the path leads through the item (compared by reference in
- * `variables`), or, for a primitive item, ends at its slot in the list.
+ * A test of whether an edit made since `since` wrote inside `item`, element
+ * `index` of `list`: the path leads through the item (compared by reference
+ * in `state`), or, for a primitive item, ends at its slot in the list.
  */
-export function editedItem(
+export function editedItems(
   since: number,
-  variables: object,
-  list: readonly unknown[],
-  item: unknown,
-  index: number,
-): boolean {
-  return log.some(({ version: v, segments }) => {
-    if (v <= since) return false;
-    if (typeof item === 'object' && item !== null) {
-      return segments.some(
-        (_, n) => getByPath(variables, segments.slice(0, n + 1)) === item,
-      );
-    }
-    return (
-      segments[segments.length - 1] === String(index) &&
-      getByPath(variables, segments.slice(0, -1)) === list
-    );
-  });
+  state: VariableNamespaces,
+): (list: readonly unknown[], item: unknown, index: number) => boolean {
+  // The objects the paths lead through, and the keys they end at
+  const through = new Set<unknown>();
+  const ends = new Map<unknown, Set<string>>();
+  for (let i = log.length - 1; i >= 0 && log[i]!.version > since; i--) {
+    const { path } = log[i]!;
+    let node: unknown = state;
+    path.forEach((seg, n) => {
+      if (n === path.length - 1 && node !== null && typeof node === 'object') {
+        const keys = ends.get(node) ?? new Set<string>();
+        keys.add(seg);
+        ends.set(node, keys);
+      }
+      node =
+        node !== null && typeof node === 'object'
+          ? getByPath(node, [seg])
+          : undefined;
+      if (node !== null && typeof node === 'object') through.add(node);
+    });
+  }
+  return (list, item, index) =>
+    typeof item === 'object' && item !== null
+      ? through.has(item)
+      : ends.get(list)?.has(String(index)) === true;
 }

package/src/utils/listeners.ts

@@ -0,0 +1,23 @@
+/**
+ * A set of listeners to call when something happens: `subscribe` adds one and
+ * returns the function that removes it, `notify` calls each one. A listener
+ * removed or added while they are called is called or not as the set was
+ * when `notify` started.
+ */
+export function createListeners(): {
+  subscribe: (listener: () => void) => () => void;
+  notify: () => void;
+} {
+  const listeners = new Set<() => void>();
+  return {
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    notify() {
+      for (const listener of [...listeners]) listener();
+    },
+  };
+}

package/src/utils/object-path.ts

@@ -1,4 +1,5 @@
-import { current as draftState, isDraft } from 'immer';
+import { current as draftState, isDraft, original } from 'immer';
+import { registeredClassName } from '../class-registry';
 import { hasOwn } from './namespace';
 import { atomicName } from './value-kinds';
 
@@ -17,7 +18,18 @@ export function getByPath(obj: object, segments: readonly string[]): unknown {
     if (seg in Object.prototype && !hasOwn(Object(current), seg)) {
       return undefined;
     }
-    current = (current as Record<string, unknown>)[seg];
+    const holder = current as Record<string, unknown>;
+    current = holder[seg];
+    // An Immer draft of a Map or Set does not carry the own properties of a
+    // registered subclass instance: they are those of its base (#412)
+    if (
+      current === undefined &&
+      isDraft(holder) &&
+      (holder instanceof Map || holder instanceof Set)
+    ) {
+      const base = original(holder) as Record<string, unknown> | undefined;
+      if (base && hasOwn(base, seg)) current = base[seg];
+    }
   }
   return current;
 }
@@ -74,10 +86,12 @@ export interface SetByPathOptions {
  * written in place.
  *
  * The path goes through own properties of plain objects, class instances
- * and arrays (by index); anything else throws a TypeError rather than
- * writing where no clone or save would see it: an inherited property such
- * as a method counts as missing, and Map, Set, Date and RegExp values and
- * other keys of arrays are refused, as is a "__proto__" segment.
+ * and arrays (by index), and, outside a draft, any key of an instance of a
+ * registered subclass of a built-in (#408); anything else throws a
+ * TypeError rather than writing where no clone or save would see it: an
+ * inherited property such as a method counts as missing, and Map, Set,
+ * Date and RegExp values and other keys of arrays are refused, as is a
+ * "__proto__" segment.
  */
 export function setByPath(
   root: Record<string, unknown>,
@@ -134,13 +148,21 @@ function checkSegments(segments: readonly string[]): void {
   }
 }
 
-/** Throw unless `holder` can take `key` as story state (see setByPath). */
+/**
+ * Throw unless `holder` can take `key` as story state (see setByPath). An
+ * instance of a registered subclass of a built-in keeps its own fields
+ * through clones and saves, so it takes any key (#408) when written in
+ * place: a draft of one, or one a draft shares, is refused as other
+ * built-ins are, and the caller writes the whole value instead.
+ */
 function checkHolder(
   holder: object,
   key: string,
   segments: readonly string[],
   depth: number,
+  inPlace: boolean,
 ): void {
+  if (inPlace && registeredClassName(holder) !== undefined) return;
   const builtin = builtinName(holder);
   const kind =
     builtin ?? (Array.isArray(holder) && !isArrayKey(key) ? 'an array' : '');
@@ -167,7 +189,7 @@ function walkToParent(
   let current: Record<string, unknown> = root;
   for (let i = 0; i < segments.length - 1; i++) {
     const seg = segments[i]!;
-    checkHolder(current, seg, segments, i);
+    checkHolder(current, seg, segments, i, !copyOnWrite);
     // An inherited property (a method, "constructor") counts as missing
     let next = hasOwn(current, seg) ? current[seg] : undefined;
     if (next == null || typeof next !== 'object') {
@@ -189,6 +211,7 @@ function walkToParent(
     segments[segments.length - 1]!,
     segments,
     segments.length - 1,
+    !copyOnWrite,
   );
   return current;
 }

package/src/utils/stable-key.ts

@@ -1,28 +1,37 @@
 import { registeredClassName } from '../class-registry';
-import { mapEntries, setMembers } from './value-kinds';
+import { extraKeys, mapEntries, setMembers } from './value-kinds';
 
 /**
  * Content-derived string key for a value, used to remount components when
  * the value's contents change (e.g. {for} iterations, #45).
  *
- * JSON-compatible values (strings, finite numbers, booleans, null, arrays and
- * plain objects of those) produce exactly their `JSON.stringify` output. Other
- * values get distinct, unambiguous markers so their contents are reflected
- * too: Map and Set entries (nested at any depth), Date, RegExp, BigInt,
- * undefined, NaN/±Infinity, symbols (by description), functions (by name)
- * and registered class instances. A hole in an array reads as undefined.
- * Cyclic references become a back-reference marker instead of throwing,
- * and the function never throws.
+ * A tree of JSON-compatible values (strings, finite numbers, booleans, null,
+ * arrays and plain objects of those) produces exactly its `JSON.stringify`
+ * output. Other values get distinct, unambiguous markers so their contents
+ * are reflected too: Map and Set entries (nested at any depth), Date,
+ * RegExp, BigInt, undefined, NaN/±Infinity, symbols (by description),
+ * functions (by name) and registered class instances, with the class name
+ * and, for a subclass of a built-in, its own fields (#407). A hole in an
+ * array reads as undefined.
+ *
+ * An object met again, through a cycle or a second reference to it, is a
+ * marker naming where it was first met rather than another copy of its
+ * contents, so the key grows with the objects a value holds, not with the
+ * paths to them (#406). The function never throws.
  */
 export function stableKey(value: unknown): string {
   try {
-    return keyOf(value, []);
+    return keyOf(value, new Map());
   } catch {
     return '<unkeyable>';
   }
 }
 
-function keyOf(val: unknown, ancestors: object[]): string {
+/**
+ * The key of `val`. `seen` numbers the objects keyed so far, in the order
+ * they were first met.
+ */
+function keyOf(val: unknown, seen: Map<object, number>): string {
   switch (typeof val) {
     case 'string':
       return JSON.stringify(val);
@@ -46,42 +55,62 @@ function keyOf(val: unknown, ancestors: object[]): string {
   if (val === null) return 'null';
 
   const obj = val as object;
-  const depth = ancestors.indexOf(obj);
-  if (depth !== -1) return `<cycle ${ancestors.length - depth}>`;
+  const first = seen.get(obj);
+  if (first !== undefined) return `<ref ${first}>`;
 
-  // Read with the built-in methods: a subclass may override them
-  if (val instanceof Date) return `Date(${Date.prototype.getTime.call(val)})`;
-  if (val instanceof RegExp) {
-    return `RegExp(${RegExp.prototype.toString.call(val)}@${val.lastIndex})`;
-  }
+  const className = registeredClassName(obj);
+  const named = (key: string) =>
+    className === undefined ? key : `Class(${JSON.stringify(className)})${key}`;
+  // The own fields of a registered subclass of a built-in, which clones and
+  // saves keep with its contents
+  const withFields = (key: string) => {
+    const keys = className === undefined ? [] : extraKeys(obj);
+    return named(keys.length ? `${key}${fieldsOf(obj, keys, seen)}` : key);
+  };
 
-  ancestors.push(obj);
-  try {
-    if (Array.isArray(val)) {
-      // Array.from reads a hole as undefined (map would skip it, giving
-      // `[,]` the key of `[]`): as JSON.stringify, a key does not tell a
-      // hole from an undefined element (deepEqual does)
-      return `[${Array.from(val, (v) => keyOf(v, ancestors)).join(',')}]`;
-    }
-    if (val instanceof Map) {
-      const entries = [...mapEntries(val)].map(
-        ([k, v]) => `[${keyOf(k, ancestors)},${keyOf(v, ancestors)}]`,
-      );
-      return `Map[${entries.join(',')}]`;
-    }
-    if (val instanceof Set) {
-      return `Set[${[...setMembers(val)].map((v) => keyOf(v, ancestors)).join(',')}]`;
+  // Read with the built-in methods: a subclass may override them. A Date or
+  // RegExp holds no other value, so it needs no number unless it has fields.
+  if (val instanceof Date || val instanceof RegExp) {
+    if (className !== undefined && extraKeys(obj).length) {
+      seen.set(obj, seen.size);
     }
+    return withFields(
+      val instanceof Date
+        ? `Date(${Date.prototype.getTime.call(val)})`
+        : `RegExp(${RegExp.prototype.toString.call(val)}@${val.lastIndex})`,
+    );
+  }
 
-    const record = obj as Record<string, unknown>;
-    const body = Object.keys(record)
-      .map((k) => `${JSON.stringify(k)}:${keyOf(record[k], ancestors)}`)
-      .join(',');
-    const className = registeredClassName(obj);
-    return className === undefined
-      ? `{${body}}`
-      : `Class(${JSON.stringify(className)}){${body}}`;
-  } finally {
-    ancestors.pop();
+  seen.set(obj, seen.size);
+  if (Array.isArray(val)) {
+    // Array.from reads a hole as undefined (map would skip it, giving
+    // `[,]` the key of `[]`): as JSON.stringify, a key does not tell a
+    // hole from an undefined element (deepEqual does)
+    return withFields(`[${Array.from(val, (v) => keyOf(v, seen)).join(',')}]`);
+  }
+  if (val instanceof Map) {
+    const entries = Array.from(
+      mapEntries(val),
+      ([k, v]) => `[${keyOf(k, seen)},${keyOf(v, seen)}]`,
+    );
+    return withFields(`Map[${entries.join(',')}]`);
   }
+  if (val instanceof Set) {
+    const members = Array.from(setMembers(val), (v) => keyOf(v, seen));
+    return withFields(`Set[${members.join(',')}]`);
+  }
+  return named(fieldsOf(obj, Object.keys(obj), seen));
+}
+
+/** `{"key":value,...}` for the `keys` of `obj`. */
+function fieldsOf(
+  obj: object,
+  keys: readonly string[],
+  seen: Map<object, number>,
+): string {
+  const record = obj as Record<string, unknown>;
+  const body = keys.map(
+    (k) => `${JSON.stringify(k)}:${keyOf(record[k], seen)}`,
+  );
+  return `{${body.join(',')}}`;
 }

package/types/index.d.ts

@@ -866,7 +866,10 @@ export interface StoryAPI {
   /** Set a one-time transition for the next navigation only. Pass `null` to clear. */
   setNextTransition(config: TransitionConfig | null): void;
 
-  /** Defer initial passage rendering until `ready()` is called. */
+  /**
+   * Defer initial passage rendering until `ready()` is called. Calling it
+   * again before `ready()` keeps the one deferral: a single `ready()` ends it.
+   */
   deferRender(): void;
 
   /** Unblock deferred rendering (call after `deferRender()`). */

package/types/tooling.d.ts

@@ -111,7 +111,11 @@ export type VarType =
 /** Inferred shape of a declared variable (or one of its object fields). */
 export interface FieldSchema {
   type: VarType;
-  /** Field schemas, only present for objects. */
+  /**
+   * Field schemas, only present for objects. An object the default refers
+   * to more than once has one schema, so a cyclic default (`node.self =
+   * node`) gives a schema that refers to itself.
+   */
   fields?: Map<string, FieldSchema>;
 }