@rohal12/spindle 0.59.13 → 0.59.15

package/src/markup/render.tsx

@@ -1,5 +1,5 @@
 import { createContext, type RefObject } from 'preact';
-import { useContext, useLayoutEffect, useRef } from 'preact/hooks';
+import { useContext, useLayoutEffect, useRef, useState } from 'preact/hooks';
 import { VarDisplay } from '../components/macros/VarDisplay';
 import { ExprDisplay } from '../components/macros/ExprDisplay';
 import { WidgetInvocation } from '../components/macros/WidgetInvocation';
@@ -9,6 +9,7 @@ import { markdownToHtml } from './markdown';
 import { h } from 'preact';
 import type { ASTNode, HtmlNode, MacroNode } from './ast';
 import { useTextScope } from '../hooks/use-interpolate';
+import type { WidgetChildren } from '../interpolation';
 import { useRenderOptions } from '../hooks/use-render-options';
 import {
   hasInterpolation,
@@ -57,6 +58,22 @@ export const InlineContext = createContext(false);
  */
 export const RawTextContext = createContext(false);
 
+/**
+ * The view content is rendered in: '' for the story interface, and an id of
+ * its own for each passage and dialog on display (see useViewScope). The
+ * radiobuttons of a variable form a native group within their view only:
+ * one group across views would let a dialog's checked button uncheck the
+ * passage's when it mounts (#396).
+ */
+export const ViewScopeContext = createContext('');
+
+let viewScopes = 0;
+
+/** A new view scope (see ViewScopeContext), kept while mounted. */
+export function useViewScope(): string {
+  return useState(() => `v${++viewScopes}`)[0];
+}
+
 /**
  * True inside an `<svg>` element. SVG attributes are case-sensitive and have
  * no live form properties, so they are set as written (see splitAttributes).
@@ -67,7 +84,7 @@ const SVG_NAMESPACE = 'http://www.w3.org/2000/svg';
 
 /** Elements whose content is literal text, not markdown. */
 const PREFORMATTED_ELEMENTS = new Set(['pre', 'textarea', 'style']);
-export const WidgetChildrenContext = createContext<ASTNode[] | null>(null);
+export const WidgetChildrenContext = createContext<WidgetChildren | null>(null);
 
 /**
  * Components rendered for the non-text nodes of one renderNodes() call. Each
@@ -708,10 +725,16 @@ function HtmlNodeRenderer({ node }: { node: HtmlNode }) {
 }
 
 function ChildrenSlot() {
-  const childrenAST = useContext(WidgetChildrenContext);
+  const children = useContext(WidgetChildrenContext);
   const renderOptions = useRenderOptions();
-  if (!childrenAST || childrenAST.length === 0) return null;
-  return <>{renderNodes(childrenAST, renderOptions)}</>;
+  if (!children) return null;
+  // The children render with the widget's locals, but a {@children} among
+  // them forwards the enclosing widget's children (#386).
+  return (
+    <WidgetChildrenContext.Provider value={children.outer}>
+      {renderNodes(children.nodes, renderOptions)}
+    </WidgetChildrenContext.Provider>
+  );
 }
 
 /**

package/src/markup/spindle.peggy

@@ -31,6 +31,11 @@ const BRANCH_PARENT = { elseif: 'if', else: 'if', case: 'switch', default: 'swit
 const BRANCHING = new Set(['if', 'switch', 'timed']);
 const LINK_SEPARATORS = [['|', false], ['->', false], ['<-', true]];
 const NO_SELECTORS = {};
+/**
+ * A CommonMark email autolink, `<` an address `>` (without braces, which
+ * are markup), as markdown reads one.
+ */
+const EMAIL_AUTOLINK = /^<[a-zA-Z0-9.!#$%&'*+/=?^_`|~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*>$/;
 
 /**
  * A link's display text and target, from its text `inner` (at `at` in the
@@ -235,6 +240,7 @@ Item
   / Escape
   / Comment
   / LinkLexeme
+  / EmailAutolink
   / HtmlElement
   / VoidCloser
   / Value
@@ -294,6 +300,7 @@ TokenItem
   / Escape
   / Comment
   / LinkLexeme
+  / EmailAutolink
   / &{ return !textMode; } tag:HtmlOpen { return tag; }
   / &{ return !textMode; } tag:HtmlClose { return VOID_TAGS.has(tag.lower) ? null : tag; }
   / Value
@@ -429,6 +436,15 @@ MacroName
 
 // -------------------------------------------------------------------- HTML
 
+/**
+ * An email autolink (`<support@example.com>`), text that markdown makes a
+ * link: not an element `<support>` with an attribute `@example.com` (#395).
+ */
+EmailAutolink
+  = value:$("<" [a-zA-Z0-9.!#$%&'*+/=?^_`|~-]+ "@" [a-zA-Z0-9.-]+ ">")
+    &{ return EMAIL_AUTOLINK.test(value); }
+    { return lexeme('text', location(), { value }); }
+
 /** A redundant closer of a void element (</br>), which is dropped. */
 VoidCloser
   = &{ return !textMode; } tag:HtmlClose &{ return VOID_TAGS.has(tag.lower); } { return null; }

package/src/store.ts

@@ -444,6 +444,16 @@ function startVariables(defaults: Record<string, unknown>): Namespace {
   return initialVars;
 }
 
+/**
+ * Fresh transient variables from their declared defaults (init, restart,
+ * load). Transients are never saved, so an instance of an unregistered
+ * class (an engine, a library object) is kept as it is, as mutation code
+ * keeps it (#321): a copy would lose its class and methods (#398).
+ */
+function freshTransients(defaults: Record<string, unknown>): Namespace {
+  return createNamespace(deepClone(defaults, { keepUnregistered: true }));
+}
+
 /**
  * Enter the start passage with `variables`, as the only history moment
  * (init, restart). Call it inside a store update.
@@ -457,7 +467,7 @@ function enterStart(
   state.currentPassage = passage;
   state.navigationId++;
   state.variables = variables;
-  state.transient = createNamespace(deepClone(transientDefaults));
+  state.transient = freshTransients(transientDefaults);
   state.temporary = createNamespace();
   state.history = [{ passage, timestamp: Date.now() }];
   state.historyIndex = 0;
@@ -1719,7 +1729,7 @@ export const useStoryStore = create<StoryState>()(
         state.visitCounts = createCounts(payload.visitCounts);
         state.renderCounts = createCounts(payload.renderCounts);
         state.temporary = createNamespace();
-        state.transient = createNamespace(deepClone(get().transientDefaults));
+        state.transient = freshTransients(get().transientDefaults);
       });
 
       // The watchers of the loaded game (a payload without any, from an

package/src/structural.ts

@@ -12,7 +12,17 @@
 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';
+import {
+  collectionSize,
+  extraKeys,
+  isAtomic,
+  isBoxed,
+  isTemporal,
+  mapEntries,
+  mapGet,
+  mapSet,
+  setMembers,
+} from './utils/value-kinds';
 
 export { isAtomic };
 
@@ -24,6 +34,26 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
   return proto === Object.prototype || proto === null;
 }
 
+/**
+ * `empty`, a new built-in (an Array, Map, Set, Date or RegExp) standing for
+ * `obj`, made like it: an instance of a registered subclass keeps its class
+ * and its extra keys (#391, #393), with the values `value` gives for them;
+ * other built-ins are plain. `made` gets it before its keys are filled, so
+ * that cycles through it find it.
+ */
+function builtinLike<C extends object>(
+  obj: object,
+  empty: C,
+  made: (copy: C) => void,
+  value: (key: string) => unknown,
+): C {
+  made(empty);
+  if (registeredClassName(obj) === undefined) return empty;
+  Object.setPrototypeOf(empty, Object.getPrototypeOf(obj) as object);
+  for (const key of extraKeys(obj)) setOwn(empty, key, value(key));
+  return empty;
+}
+
 /** Own keys of an error that are not enumerable but are data. */
 const ERROR_HIDDEN_KEYS = ['message', 'cause', 'errors'] as const;
 
@@ -83,11 +113,17 @@ export function deepClone<T>(value: T, options: DeepCloneOptions = {}): T {
   }
 
   function cloneBuiltin(val: object): object | undefined {
-    if (val instanceof Date) return keep(val, new Date(val.getTime()));
+    // Read with the built-in getters: a subclass may override them
+    if (val instanceof Date) {
+      return builtin(val, new Date(Date.prototype.getTime.call(val)));
+    }
     if (val instanceof RegExp) {
-      const copy = new RegExp(val.source, val.flags);
+      const copy = new RegExp(
+        Reflect.get(RegExp.prototype, 'source', val) as string,
+        Reflect.get(RegExp.prototype, 'flags', val) as string,
+      );
       copy.lastIndex = val.lastIndex; // the scanning cursor of g/y patterns
-      return keep(val, copy);
+      return builtin(val, copy);
     }
     if (val instanceof ArrayBuffer) return keep(val, val.slice(0));
     if (ArrayBuffer.isView(val)) {
@@ -131,6 +167,15 @@ export function deepClone<T>(value: T, options: DeepCloneOptions = {}): T {
       : copy;
   }
 
+  /** `empty`, made the copy of the built-in `obj` (see builtinLike). */
+  const builtin = <C extends object>(obj: object, empty: C): C =>
+    builtinLike(
+      obj,
+      empty,
+      (copy) => keep(obj, copy),
+      (key) => clone((obj as Record<string, unknown>)[key]),
+    );
+
   function clone(val: unknown): unknown {
     if (val === null || typeof val !== 'object') return val;
 
@@ -139,27 +184,33 @@ export function deepClone<T>(value: T, options: DeepCloneOptions = {}): T {
 
     if (Array.isArray(val)) {
       // Holes stay holes
-      const arr = keep(obj, new Array(val.length) as unknown[]);
+      const arr = builtin(obj, new Array(val.length) as unknown[]);
       for (let i = 0; i < val.length; i++) {
         if (i in val) arr[i] = clone(val[i]);
       }
       return arr;
     }
 
+    // Read and filled with the built-in methods: a subclass may override
+    // them (see mapEntries)
     if (val instanceof Map) {
-      const copy = keep(obj, new Map());
-      for (const [k, v] of val) copy.set(settled(clone(k), k), clone(v));
+      const copy = builtin(obj, new Map());
+      for (const [k, v] of mapEntries(val)) {
+        Map.prototype.set.call(copy, settled(clone(k), k), clone(v));
+      }
       return copy;
     }
 
     if (val instanceof Set) {
-      const copy = keep(obj, new Set());
-      for (const v of val) copy.add(settled(clone(v), v));
+      const copy = builtin(obj, new Set());
+      for (const v of setMembers(val)) {
+        Set.prototype.add.call(copy, settled(clone(v), v));
+      }
       return copy;
     }
 
-    const builtin = cloneBuiltin(obj);
-    if (builtin !== undefined) return builtin;
+    const copied = cloneBuiltin(obj);
+    if (copied !== undefined) return copied;
 
     // A registered class instance keeps its class, and a plain object its
     // prototype (which may be null). An instance of an unregistered class
@@ -295,15 +346,23 @@ export function shareEqual<T>(prev: unknown, curr: T): T {
     if (placed !== undefined) return placed;
     if (!isObjectValue(p)) return fresh(c);
     if (reuse(p, c)) return p;
+    const pr = p as Record<string, unknown>;
+    const cr = c as Record<string, unknown>;
+    /** What the result holds at `key` of `c`. */
+    const shareKey = (key: string) =>
+      share(hasOwn(pr, key) ? pr[key] : undefined, cr[key]);
+    /** `empty`, made the result for the collection `c` (see builtinLike). */
+    const collection = <C extends object>(empty: C): C =>
+      builtinLike(c, empty, (out) => done.set(c, out), shareKey);
     if (c instanceof Map && p instanceof Map) {
-      const out = new Map();
-      done.set(c, out);
-      for (const [k, v] of c) out.set(fresh(k), share(p.get(k), v));
+      const out = collection(new Map());
+      for (const [k, v] of mapEntries(c)) {
+        Map.prototype.set.call(out, fresh(k), share(mapGet(p, k), v));
+      }
       return out;
     }
     if (Array.isArray(c) && Array.isArray(p)) {
-      const out = new Array(c.length) as unknown[];
-      done.set(c, out);
+      const out = collection(new Array(c.length) as unknown[]);
       for (let i = 0; i < c.length; i++) {
         if (i in c) out[i] = share(p[i], c[i]);
       }
@@ -312,10 +371,7 @@ export function shareEqual<T>(prev: unknown, curr: T): T {
     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, share(hasOwn(p, key) ? p[key] : undefined, cr[key]));
-      }
+      for (const key of Object.keys(cr)) setOwn(out, key, shareKey(key));
       return out;
     }
     return fresh(c);
@@ -344,9 +400,20 @@ function equalBuiltin(
   b: object,
   assumed: Pairs,
 ): boolean | undefined {
-  if (a instanceof Date) return Object.is(a.getTime(), (b as Date).getTime());
+  if (a instanceof Date) {
+    const time = Date.prototype.getTime;
+    return (
+      Object.is(time.call(a), time.call(b as Date)) &&
+      equalExtraKeys(a, b, assumed)
+    );
+  }
   if (a instanceof RegExp) {
-    return String(a) === String(b) && a.lastIndex === (b as RegExp).lastIndex;
+    const text = RegExp.prototype.toString;
+    return (
+      text.call(a) === text.call(b as RegExp) &&
+      a.lastIndex === (b as RegExp).lastIndex &&
+      equalExtraKeys(a, b, assumed)
+    );
   }
   if (ArrayBuffer.isView(a)) {
     // A view is its place in its backing buffer, and the whole buffer (which
@@ -382,17 +449,42 @@ function equalBuiltin(
   return undefined;
 }
 
-function equalKeys(a: object, b: object, assumed: Pairs): boolean {
+function equalKeys(
+  a: object,
+  b: object,
+  assumed: Pairs,
+  keysOf: (o: object) => string[] = Object.keys,
+): 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;
+  const keys = keysOf(ao);
+  if (keys.length !== keysOf(bo).length) return false;
   for (const key of keys) {
     if (!hasOwn(bo, key) || !equal(ao[key], bo[key], assumed)) return false;
   }
   return true;
 }
 
+/** Built-in prototypes (see builtinLike), whose instances hold no extra keys. */
+const BUILTIN_PROTOS: ReadonlySet<object | null> = new Set([
+  Array.prototype,
+  Map.prototype,
+  Set.prototype,
+  Date.prototype,
+  RegExp.prototype,
+]);
+
+/**
+ * Equality of the extra keys (see extraKeys) of two built-ins of one
+ * class: those of a subclass instance are part of its value.
+ */
+function equalExtraKeys(a: object, b: object, assumed: Pairs): boolean {
+  return (
+    BUILTIN_PROTOS.has(Object.getPrototypeOf(a) as object | null) ||
+    equalKeys(a, b, assumed, extraKeys)
+  );
+}
+
 /** `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;
@@ -410,9 +502,9 @@ function equal(a: unknown, b: unknown, assumed: Pairs): boolean {
 
   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();
+    if (collectionSize(a) !== collectionSize(bc)) return false;
+    const ai = a instanceof Map ? mapEntries(a) : setMembers(a);
+    const bi = bc instanceof Map ? mapEntries(bc) : setMembers(bc);
     for (
       let x = ai.next(), y = bi.next();
       !x.done;
@@ -420,7 +512,7 @@ function equal(a: unknown, b: unknown, assumed: Pairs): boolean {
     ) {
       if (!equal(x.value, y.value, assumed)) return false;
     }
-    return true;
+    return equalExtraKeys(a, b, assumed);
   }
 
   const builtin = equalBuiltin(a, b, assumed);
@@ -432,7 +524,7 @@ function equal(a: unknown, b: unknown, assumed: Pairs): boolean {
     for (let i = 0; i < a.length; i++) {
       if (i in a !== i in bc || !equal(a[i], bc[i], assumed)) return false;
     }
-    return true;
+    return equalExtraKeys(a, b, assumed);
   }
 
   return equalKeys(a, b, assumed);
@@ -466,7 +558,11 @@ export function mergesWith(
   arrays: boolean,
 ): a is Record<string, unknown> {
   if (arrays && (Array.isArray(a) || Array.isArray(b))) {
-    return Array.isArray(a) && Array.isArray(b);
+    return (
+      Array.isArray(a) &&
+      Array.isArray(b) &&
+      Object.getPrototypeOf(a) === Object.getPrototypeOf(b)
+    );
   }
   return (
     isMergeable(a) &&
@@ -698,13 +794,15 @@ function entryChildren(value: object): [string, unknown][] | undefined {
   const children: [string, unknown][] = [];
   if (value instanceof Map) {
     let index = 0;
-    for (const [k, v] of value) {
+    for (const [k, v] of mapEntries(value)) {
       children.push([entryKey('k', index), k], [entryKey('v', index), v]);
       index++;
     }
   } else if (value instanceof Set) {
     let index = 0;
-    for (const member of value) children.push([entryKey('s', index++), member]);
+    for (const member of setMembers(value)) {
+      children.push([entryKey('s', index++), member]);
+    }
   } else if (value instanceof Error) {
     for (const key of ['cause', 'errors'] as const) {
       if (hasOwn(value, key)) {
@@ -755,8 +853,9 @@ function setEntryValue(
   const holder = getByEntryPath(root, path.slice(0, -1));
   const match = /^\0v(\d+)$/.exec(path[path.length - 1]!);
   if (!(holder instanceof Map) || !match) return false;
-  const key = [...holder.keys()][Number(match[1])];
-  holder.set(key, value);
+  const entry = [...mapEntries(holder)][Number(match[1])];
+  if (!entry) return false;
+  mapSet(holder, entry[0], value);
   return true;
 }
 
@@ -857,7 +956,8 @@ function aliasMoved(
   if (xs && ys) {
     if (Object.getPrototypeOf(x) !== Object.getPrototypeOf(y)) return false;
     if (x instanceof Map || x instanceof Set) {
-      if (x.size !== (y as Map<unknown, unknown>).size) return false;
+      const ySize = collectionSize(y as Map<unknown, unknown>);
+      if (collectionSize(x) !== ySize) return false;
     }
     const held = new Map(ys);
     for (const [segment, a] of xs) {

package/src/triggers.ts

@@ -294,10 +294,14 @@ export function reinitTriggerState(): void {
   }
 }
 
+/**
+ * Forget every watcher and close every dialog on display, whoever opened it
+ * (restart): a `{dialog}` or menubar dialog of the story interface, which
+ * stays mounted, would otherwise stay open over the new game (#397).
+ */
 export function resetTriggers(): void {
   triggers = [];
-  dialogQueue = [];
-  dialogHostCallbacks?.closeAll();
+  closeAllOpenDialogs();
 }
 
 export function subscribeTriggerDialogs(cb: () => void): () => void {

package/src/utils/stable-key.ts

@@ -1,4 +1,5 @@
 import { registeredClassName } from '../class-registry';
+import { mapEntries, setMembers } from './value-kinds';
 
 /**
  * Content-derived string key for a value, used to remount components when
@@ -48,8 +49,11 @@ function keyOf(val: unknown, ancestors: object[]): string {
   const depth = ancestors.indexOf(obj);
   if (depth !== -1) return `<cycle ${ancestors.length - depth}>`;
 
-  if (val instanceof Date) return `Date(${val.getTime()})`;
-  if (val instanceof RegExp) return `RegExp(${String(val)}@${val.lastIndex})`;
+  // 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})`;
+  }
 
   ancestors.push(obj);
   try {
@@ -60,13 +64,13 @@ function keyOf(val: unknown, ancestors: object[]): string {
       return `[${Array.from(val, (v) => keyOf(v, ancestors)).join(',')}]`;
     }
     if (val instanceof Map) {
-      const entries = [...val].map(
+      const entries = [...mapEntries(val)].map(
         ([k, v]) => `[${keyOf(k, ancestors)},${keyOf(v, ancestors)}]`,
       );
       return `Map[${entries.join(',')}]`;
     }
     if (val instanceof Set) {
-      return `Set[${[...val].map((v) => keyOf(v, ancestors)).join(',')}]`;
+      return `Set[${[...setMembers(val)].map((v) => keyOf(v, ancestors)).join(',')}]`;
     }
 
     const record = obj as Record<string, unknown>;

package/src/utils/value-kinds.ts

@@ -1,6 +1,8 @@
 // Kinds of story values that structural operations (clone, equality, merge)
 // and property paths treat as a whole, by their content.
 
+import { isDraft } from 'immer';
+
 export const toStringTag = (value: object): string =>
   Object.prototype.toString.call(value).slice(8, -1);
 
@@ -43,3 +45,57 @@ export function atomicName(value: object): string | undefined {
   const tag = value instanceof Error ? 'Error' : toStringTag(value);
   return `${/^[AEIOU]/.test(tag) ? 'an' : 'a'} ${tag}`;
 }
+
+/** Whether `key` is an index of an array element. */
+const isIndexKey = (key: string): boolean =>
+  key !== '4294967295' && String(Number(key) >>> 0) === key;
+
+/**
+ * The own enumerable string keys of a collection (an Array, Map or Set) that
+ * are not its elements: what an instance of a subclass may hold besides
+ * them.
+ */
+export function extraKeys(collection: object): string[] {
+  const keys = Object.keys(collection);
+  return Array.isArray(collection) ? keys.filter((k) => !isIndexKey(k)) : keys;
+}
+
+// A subclass of Map or Set may override how it is iterated, read or written
+// (an inventory that iterates only the items on hand). What it holds is in
+// its built-in slots, so structural operations read and write those with the
+// built-in methods (#391, #394). An Immer draft keeps its entries in its own
+// state instead, so it is read through its methods.
+
+/** The entries of a Map, as the built-in iterator gives them. */
+export function mapEntries<K, V>(map: Map<K, V>): MapIterator<[K, V]> {
+  return isDraft(map)
+    ? map.entries()
+    : (Map.prototype.entries.call(map) as MapIterator<[K, V]>);
+}
+
+/** The members of a Set, as the built-in iterator gives them. */
+export function setMembers<T>(set: Set<T>): SetIterator<T> {
+  return isDraft(set)
+    ? set.values()
+    : (Set.prototype.values.call(set) as SetIterator<T>);
+}
+
+/** The number of entries of a Map or members of a Set. */
+export function collectionSize(
+  collection: Map<unknown, unknown> | Set<unknown>,
+) {
+  if (isDraft(collection)) return collection.size;
+  const proto = collection instanceof Map ? Map.prototype : Set.prototype;
+  return Reflect.get(proto, 'size', collection) as number;
+}
+
+/** The value a Map holds for `key`. */
+export function mapGet<K, V>(map: Map<K, V>, key: K): V | undefined {
+  return isDraft(map) ? map.get(key) : Map.prototype.get.call(map, key);
+}
+
+/** Make a Map hold `value` for `key`. */
+export function mapSet<K, V>(map: Map<K, V>, key: K, value: V): void {
+  if (isDraft(map)) map.set(key, value);
+  else Map.prototype.set.call(map, key, value);
+}

package/src/widgets/widget-def.ts

@@ -4,6 +4,7 @@
  */
 import { parseMacroArgs } from '../components/macros/macro-args';
 import type { MacroArgs } from '../registry';
+import { tokenizeMarkupTolerant } from '../markup/parse';
 
 /** A {widget} definition's name, then its `@` parameters. */
 export const WIDGET_PARAMETERS = [
@@ -36,20 +37,15 @@ export function parseWidgetDef(rawArgs: string): WidgetDef {
   return widgetDef(parseMacroArgs(rawArgs, WIDGET_PARAMETERS));
 }
 
-/**
- * A definition: its arguments (read like a {widget} macro's, see
- * parseWidgetDef) and its body. Macro names are not case-sensitive.
- */
-const WIDGET_DEFINITION = /\{widget\s+([^}]*)\}([\s\S]*?)\{\/widget\}/gi;
-
-/** `{@children}`, also with selectors such as `{.highlight @children}`. */
-const CHILDREN_PLACEHOLDER = /\{[^{}]*@children\s*\}/;
-
 /**
  * The names of the block widgets (those whose body renders `{@children}`)
  * that StoryInit and the passages tagged `widget` define. They must be
  * known as block macros before any passage is parsed, so that passages
  * invoking them nest their content whatever the passage order.
+ *
+ * The passages are read as flat tokens, which need no block macros to be
+ * known, so a `{@children}` in an HTML comment or in a `{do}` body is text
+ * here as it is to the parser, and does not make a block widget (#387).
  */
 export function blockWidgetNames(
   passages: Iterable<{ name: string; tags?: string[]; content: string }>,
@@ -59,12 +55,28 @@ export function blockWidgetNames(
     if (passage.name !== 'StoryInit' && !passage.tags?.includes('widget')) {
       continue;
     }
-    for (const match of passage.content.matchAll(WIDGET_DEFINITION)) {
-      if (!CHILDREN_PLACEHOLDER.test(match[2]!)) continue;
-      try {
-        names.push(parseWidgetDef(match[1]!).name);
-      } catch {
-        // The {widget} macro reports a definition it cannot read
+    // The open definitions: their arguments, and whether a slot was seen
+    const open: { rawArgs: string; isBlock: boolean }[] = [];
+    for (const token of tokenizeMarkupTolerant(passage.content).tokens) {
+      if (token.type === 'macro' && token.name.toLowerCase() === 'widget') {
+        if (!token.isClose) {
+          open.push({ rawArgs: token.rawArgs, isBlock: false });
+          continue;
+        }
+        const def = open.pop();
+        if (!def?.isBlock) continue;
+        try {
+          names.push(parseWidgetDef(def.rawArgs).name);
+        } catch {
+          // The {widget} macro reports a definition it cannot read
+        }
+      } else if (
+        token.type === 'variable' &&
+        token.scope === 'local' &&
+        token.name === 'children' &&
+        open.length > 0
+      ) {
+        open[open.length - 1]!.isBlock = true;
       }
     }
   }

package/types/index.d.ts

@@ -794,7 +794,9 @@ export interface StoryAPI {
   /**
    * Register a class so its instances keep their class through clones,
    * history, saves and loads. A save refuses instances of classes that are
-   * not registered.
+   * not registered. A class may extend Array, Map, Set, Date, RegExp or
+   * Error; one extending another built-in whose value a save cannot hold (a
+   * typed array, URL, Promise...) throws.
    */
   registerClass(name: string, ctor: new (...args: any[]) => any): void;