@rohal12/spindle 0.52.9 → 0.54.0

package/src/structural.ts

@@ -2,12 +2,21 @@
 // and merging the differences between two versions of a value. Mutation
 // commits, history and save hooks all go through these, so they agree on
 // what a change is.
+//
+// They handle the value types a save holds (see serialize() in
+// class-registry.ts): plain and prototype-less objects, arrays (holes kept),
+// registered class instances, Date, RegExp, Map, Set, typed arrays,
+// ArrayBuffer, DataView, URL, URLSearchParams, boxed primitives, errors and
+// Temporal values, with shared references and cycles.
 
 import { registeredClassName } from './class-registry';
 import { hasOwn, setOwn } from './utils/namespace';
 import { deleteByPath, getByPath, setByPath } from './utils/object-path';
+import { isAtomic, isBoxed, isTemporal } from './utils/value-kinds';
 
-// --- Deep Clone ---
+export { isAtomic };
+
+// --- Value kinds ---
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   if (typeof value !== 'object' || value === null) return false;
@@ -15,6 +24,11 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
   return proto === Object.prototype || proto === null;
 }
 
+/** Own keys of an error that are not enumerable but are data. */
+const ERROR_HIDDEN_KEYS = ['message', 'cause', 'errors'] as const;
+
+// --- Deep Clone ---
+
 export interface DeepCloneOptions {
   /**
    * Return instances of unregistered classes (DOM nodes, promises, other
@@ -24,31 +38,85 @@ export interface DeepCloneOptions {
   keepUnregistered?: boolean;
 }
 
+type TypedArrayCtor = new (
+  buffer: ArrayBufferLike,
+  byteOffset: number,
+  length: number,
+) => ArrayBufferView;
+
 export function deepClone<T>(value: T, options: DeepCloneOptions = {}): T {
   const 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 => {
+    seen.set(obj, copy);
+    return copy;
+  };
+
+  /** Copy the own (enumerable) keys of `obj` into `copy`. */
+  function copyKeys(obj: object, copy: object): object {
+    for (const key of Object.keys(obj)) {
+      setOwn(copy, key, clone((obj as Record<string, unknown>)[key]));
+    }
+    return copy;
+  }
+
+  function cloneBuiltin(val: object): object | undefined {
+    if (val instanceof Date) return keep(val, new Date(val.getTime()));
+    if (val instanceof RegExp) {
+      return keep(val, new RegExp(val.source, val.flags));
+    }
+    if (val instanceof ArrayBuffer) return keep(val, val.slice(0));
+    if (ArrayBuffer.isView(val)) {
+      // The buffer through the copies, so views of one buffer share it
+      const buffer = clone(val.buffer) as ArrayBuffer;
+      if (val instanceof DataView) {
+        return keep(val, new DataView(buffer, val.byteOffset, val.byteLength));
+      }
+      const ctor = val.constructor as TypedArrayCtor;
+      const length = (val as unknown as { length: number }).length;
+      return keep(val, new ctor(buffer, val.byteOffset, length));
+    }
+    if (val instanceof URL) return keep(val, new URL(val.href));
+    if (val instanceof URLSearchParams) {
+      return keep(val, new URLSearchParams(val));
+    }
+    if (isBoxed(val)) return keep(val, Object((val as Number).valueOf()));
+    if (isTemporal(val)) return val;
+    if (val instanceof Error) {
+      // Keeps its class (built-in, or a registered or other subclass)
+      const copy = keep(val, Object.create(Object.getPrototypeOf(val)));
+      for (const key of [...ERROR_HIDDEN_KEYS, 'stack']) {
+        if (hasOwn(val, key)) {
+          Object.defineProperty(copy, key, {
+            value: clone((val as unknown as Record<string, unknown>)[key]),
+            writable: true,
+            configurable: true,
+          });
+        }
+      }
+      return copyKeys(val, copy);
+    }
+    return undefined;
+  }
+
   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);
+      // Holes stay holes
+      const arr = keep(obj, new Array(val.length) as unknown[]);
       for (let i = 0; i < val.length; i++) {
-        arr[i] = clone(val[i]);
+        if (i in val) arr[i] = clone(val[i]);
       }
       return arr;
     }
 
     if (val instanceof Map) {
-      const copy = new Map();
-      seen.set(obj, copy);
+      const copy = keep(obj, new Map());
       for (const [k, v] of val) {
         copy.set(clone(k), clone(v));
       }
@@ -56,30 +124,29 @@ export function deepClone<T>(value: T, options: DeepCloneOptions = {}): T {
     }
 
     if (val instanceof Set) {
-      const copy = new Set();
-      seen.set(obj, copy);
+      const copy = keep(obj, new Set());
       for (const v of val) {
         copy.add(clone(v));
       }
       return copy;
     }
 
+    const builtin = cloneBuiltin(obj);
+    if (builtin !== undefined) return builtin;
+
     // A registered class instance keeps its class, and a plain object its
     // prototype (which may be null). An instance of an unregistered class
     // is treated as plain, unless it is kept by reference.
     const keepsProto =
       registeredClassName(obj) !== undefined || isPlainObject(val);
     if (!keepsProto && options.keepUnregistered) return val;
-    const copy = (
+    const copy = keep(
+      obj,
       keepsProto
         ? 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 copyKeys(obj, copy);
   }
 
   return clone(value) as T;
@@ -88,27 +155,179 @@ export function deepClone<T>(value: T, options: DeepCloneOptions = {}): 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).
+ * Structural equality over the value types deepClone() supports, nested at
+ * any depth and with cycles. Objects must have the same prototype. Map and
+ * Set entries are compared in insertion order, so reordering one is a
+ * change. Arrays are compared by length and index; a hole differs from an
+ * undefined element. Errors are compared by class, message, cause, errors
+ * and own keys (not their stack).
  */
 export function deepEqual(a: unknown, b: unknown): boolean {
-  return equal(a, b, new Map());
+  return equal(a, b, loosePairs());
 }
 
 /**
- * `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.
+ * Called on meeting the pair (a, b) of objects to compare: true when the
+ * pair is already being compared (a cycle: assume it equal), false when it
+ * cannot be equal, undefined to compare it.
  */
-function equal(
-  a: unknown,
-  b: unknown,
-  assumed: Map<object, Set<object>>,
-): boolean {
-  if (Object.is(a, b)) return true;
+type Pairs = ((a: object, b: object) => boolean | undefined) & {
+  /** Identical objects are paired and compared too, not taken as equal. */
+  strict?: boolean;
+};
+
+/**
+ * Pairs for deepEqual(). Every object may pair with several others, since
+ * cycles of different lengths can still unfold to the same value, and
+ * shared references may equal distinct copies.
+ */
+function loosePairs(): Pairs {
+  const assumed = new Map<object, Set<object>>();
+  return (a, b) => {
+    const pairs = assumed.get(a);
+    if (pairs?.has(b)) return true;
+    if (pairs) pairs.add(b);
+    else assumed.set(a, new Set([b]));
+    return undefined;
+  };
+}
+
+/**
+ * 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.
+ */
+function strictPairs(): Pairs {
+  const ab = new Map<object, object>();
+  const ba = new Map<object, object>();
+  const pairs: 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);
+    return undefined;
+  };
+  pairs.strict = true;
+  return pairs;
+}
+
+/**
+ * Whether `a` and `b` are equal as deepEqual() has it and also share
+ * references at the same places (a save of one loads as the other).
+ */
+export function deepEqualStrict(a: unknown, b: unknown): boolean {
+  return equal(a, b, strictPairs());
+}
+
+/**
+ * `curr` with each part that equals (see deepEqualStrict) the part of
+ * `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.
+ */
+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 (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);
+      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];
+      }
+      return out;
+    }
+    if (mergesWith(p, c, false)) {
+      const out = Object.create(Object.getPrototypeOf(c) as object | null);
+      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]);
+      }
+      return out;
+    }
+    done.set(c, c);
+    return c;
+  }
+  return share(prev, curr) as T;
+}
+
+const isObjectValue = (v: unknown): v is object =>
+  typeof v === 'object' && v !== null;
+
+function equalBytes(a: ArrayBufferView | ArrayBuffer, b: typeof a): boolean {
+  const x = ArrayBuffer.isView(a)
+    ? new Uint8Array(a.buffer, a.byteOffset, a.byteLength)
+    : new Uint8Array(a);
+  const y = ArrayBuffer.isView(b)
+    ? new Uint8Array(b.buffer, b.byteOffset, b.byteLength)
+    : new Uint8Array(b as ArrayBuffer);
+  if (x.length !== y.length) return false;
+  for (let i = 0; i < x.length; i++) if (x[i] !== y[i]) return false;
+  return true;
+}
+
+/** Equality of the content of atomic built-ins (see isAtomic) but Map/Set. */
+function equalBuiltin(
+  a: object,
+  b: object,
+  assumed: Pairs,
+): 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 (a instanceof URL || a instanceof URLSearchParams) {
+    return String(a) === String(b);
+  }
+  if (isBoxed(a)) {
+    return Object.is((a as Number).valueOf(), (b as Number).valueOf());
+  }
+  if (isTemporal(a)) return String(a) === String(b);
+  if (a instanceof Error) {
+    return (
+      ERROR_HIDDEN_KEYS.every(
+        (key) =>
+          hasOwn(a, key) === hasOwn(b, key) &&
+          equal(
+            (a as unknown as Record<string, unknown>)[key],
+            (b as unknown as Record<string, unknown>)[key],
+            assumed,
+          ),
+      ) && equalKeys(a, b, assumed)
+    );
+  }
+  return undefined;
+}
+
+function equalKeys(a: object, b: object, assumed: Pairs): boolean {
+  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;
+}
+
+/** `assumed` tracks the pairs of objects met (see Pairs). */
+function equal(a: unknown, b: unknown, assumed: Pairs): boolean {
+  if (Object.is(a, b) && !(assumed.strict && isObjectValue(a))) return true;
   if (
     a === null ||
     b === null ||
@@ -118,13 +337,9 @@ function equal(
     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]));
+  const met = assumed(a, b);
+  if (met !== undefined) return met;
 
-  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;
@@ -140,42 +355,36 @@ function equal(
     return true;
   }
 
+  const builtin = equalBuiltin(a, b, assumed);
+  if (builtin !== undefined) return builtin;
+
   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;
+      if (i in a !== i in bc || !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;
+  return equalKeys(a, b, assumed);
 }
 
 // --- Structural diff ---
 
 /**
  * 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).
+ * class instances. Arrays and atomic built-ins (Map, Set, Date, typed
+ * arrays, errors..., see isAtomic) are values that are replaced as a whole,
+ * since their elements have no stable identity to merge by (a shift moves
+ * every index) or their content is not in their keys.
  */
 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)
+    !isAtomic(value)
   );
 }
 

package/src/styles.css

@@ -118,6 +118,51 @@ tw-storydata {
   background: rgba(239, 83, 80, 0.1);
 }
 
+/* Runtime errors shown on the page (see src/components/RuntimeErrors.tsx) */
+.spindle-error-banners {
+  position: fixed;
+  top: 0.75em;
+  left: 50%;
+  z-index: 300;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5em;
+  width: min(42em, calc(100% - 1.5em));
+  transform: translateX(-50%);
+}
+
+.spindle-error-banner {
+  position: relative;
+  padding: 0.75em 2.75em 0.75em 1em;
+  border: 1px solid #ef5350;
+  border-radius: 4px;
+  background: #2b1a1e;
+  color: #ffcdd2;
+  font-size: 0.9em;
+  line-height: 1.5;
+  box-shadow: 0 2px 12px rgba(0, 0, 0, 0.5);
+}
+
+.spindle-error-banner-message {
+  font-family: monospace;
+  color: #ef9a9a;
+}
+
+.spindle-error-banner-dismiss {
+  position: absolute;
+  top: 0.5em;
+  right: 0.5em;
+  background: transparent;
+  border: none;
+  color: inherit;
+  font-size: 1em;
+  cursor: pointer;
+}
+
+.spindle-error-banner-dismiss:hover {
+  color: #fff;
+}
+
 .loading {
   text-align: center;
   padding: 2em;

package/src/tooling.ts

@@ -0,0 +1,50 @@
+/**
+ * What the tooling entry point (`@rohal12/spindle/tooling`) bundles as
+ * dist/pkg/story-variables.js: the StoryVariables parser and the markup
+ * validator, with no Preact or DOM dependencies. pkg/tooling.js re-exports
+ * them, binding the validator to its macro metadata.
+ */
+import {
+  validateMarkup,
+  type MarkupDiagnostic,
+  type MarkupPassage,
+} from './markup/validate';
+import { isBlockMacro } from './markup/ast';
+import { blockWidgetNames } from './widgets/widget-def';
+
+export { parseStoryVariables } from './story-variables';
+export { formatDiagnostic } from './markup/validate';
+export type { MarkupDiagnostic, MarkupPassage } from './markup/validate';
+
+/** What tooling knows about a macro (see MacroMetadata). */
+export interface ToolingMacro {
+  name: string;
+  block: boolean;
+  subMacros: string[];
+}
+
+/**
+ * Validate the markup of a story's passages as Spindle does when the story
+ * starts, against the given macros (built-in and user-defined): malformed
+ * markup and unknown macros, with their passage, line and column.
+ */
+export function validateStoryMarkup(
+  passages: Iterable<MarkupPassage>,
+  macros: Iterable<ToolingMacro>,
+): MarkupDiagnostic[] {
+  const list = [...passages];
+  const known = new Set<string>();
+  const blocks = new Set(blockWidgetNames(list).map((n) => n.toLowerCase()));
+  for (const macro of macros) {
+    const name = macro.name.toLowerCase();
+    known.add(name);
+    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,
+    isBlockMacro: (name) =>
+      blocks.has(name.toLowerCase()) || isBlockMacro(name),
+  });
+}

package/src/types-drift-check.ts

@@ -21,7 +21,19 @@ import type {
   MacroProps as PublishedMacroProps,
   ASTNode as PublishedASTNode,
 } from '../types/index';
-import type { parseStoryVariables as PublishedParse } from '../types/tooling';
+import type {
+  parseStoryVariables as PublishedParse,
+  formatDiagnostic as PublishedFormatDiagnostic,
+  MarkupDiagnostic as PublishedMarkupDiagnostic,
+  MarkupPassage as PublishedMarkupPassage,
+  validateMarkup as PublishedValidateMarkup,
+} from '../types/tooling';
+import type {
+  formatDiagnostic as SourceFormatDiagnostic,
+  MarkupDiagnostic as SourceMarkupDiagnostic,
+  MarkupPassage as SourceMarkupPassage,
+  validateStoryMarkup as SourceValidateStoryMarkup,
+} from './tooling';
 import type { bootStory as PublishedBootStory } from '../types/headless';
 
 /** What the source declares, by published name. */
@@ -30,6 +42,11 @@ interface Source {
   // Tooling entry point (`@rohal12/spindle/tooling`): the parser that
   // dist/pkg/tooling.js re-exports.
   parseStoryVariables: typeof SourceParse;
+  // Its markup validator (pkg/tooling.js binds validateStoryMarkup to the
+  // macro metadata, so validateMarkup itself takes only the passages).
+  MarkupPassage: SourceMarkupPassage;
+  MarkupDiagnostic: SourceMarkupDiagnostic;
+  formatDiagnostic: typeof SourceFormatDiagnostic;
   // Custom macro API: the MacroContext/MacroDefinition defineMacro()
   // actually passes and accepts.
   MacroContext: SourceMacroContext;
@@ -44,6 +61,9 @@ interface Source {
 interface Published {
   StoryAPI: PublishedAPI;
   parseStoryVariables: typeof PublishedParse;
+  MarkupPassage: PublishedMarkupPassage;
+  MarkupDiagnostic: PublishedMarkupDiagnostic;
+  formatDiagnostic: typeof PublishedFormatDiagnostic;
   MacroContext: PublishedMacroContext;
   MacroDefinition: PublishedMacroDefinition;
   MacroProps: PublishedMacroProps;
@@ -90,3 +110,10 @@ const _exampleMacro: PublishedMacroDefinition = {
     );
   },
 };
+
+// pkg/tooling.js's validateMarkup is validateStoryMarkup bound to the macro
+// metadata.
+declare const validateStoryMarkup: typeof SourceValidateStoryMarkup;
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _validateMarkup: typeof PublishedValidateMarkup = (passages) =>
+  validateStoryMarkup(passages, []);

package/src/utils/object-path.ts

@@ -1,5 +1,6 @@
-import { isDraft } from 'immer';
+import { current as draftState, isDraft } from 'immer';
 import { hasOwn } from './namespace';
+import { atomicName } from './value-kinds';
 
 /**
  * Traverse dot-path segments on an object and return the nested value.
@@ -29,22 +30,13 @@ const isArrayKey = (key: string): boolean =>
  * Built-ins whose content is not their properties: a property written into
  * one would be dropped by clones and saves (and by Immer, for Map and Set).
  */
-const builtinName = (value: object): string | undefined =>
-  value instanceof Map
-    ? 'a Map'
-    : value instanceof Set
-      ? 'a Set'
-      : value instanceof Date
-        ? 'a Date'
-        : value instanceof RegExp
-          ? 'a RegExp'
-          : undefined;
+const builtinName = atomicName;
 
 /**
  * Shallow copy that keeps the prototype, so a registered class instance
  * stays an instance of its class (with the same own keys deepClone copies).
  */
-function shallowCopy(value: object): Record<string, unknown> {
+export function shallowCopy(value: object): Record<string, unknown> {
   const copy = Array.isArray(value)
     ? []
     : (Object.create(Object.getPrototypeOf(value) as object | null) as object);
@@ -120,6 +112,15 @@ export function deleteByPath(
     return;
   }
   const parent = walkToParent(root, segments, false);
+  if (Array.isArray(parent) && isDraft(parent) && segments.length > 1) {
+    // Immer turns `delete` of an array element into writing undefined: to
+    // leave a hole, as `delete` does, put in a copy of the array with one
+    const copy = (draftState(parent) as unknown[]).slice();
+    delete copy[Number(last)];
+    const holder = walkToParent(root, segments.slice(0, -1), false);
+    holder[segments[segments.length - 2]!] = copy;
+    return;
+  }
   delete parent[last];
 }
 

package/src/utils/stable-key.ts

@@ -55,7 +55,8 @@ function keyOf(val: unknown, ancestors: object[]): string {
   try {
     if (Array.isArray(val)) {
       // Array.from reads a hole as undefined (map would skip it, giving
-      // `[,]` the key of `[]`), matching deepClone, which fills holes.
+      // `[,]` 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) {