@rohal12/spindle 0.59.17 → 0.59.19

package/src/markup/render.tsx

@@ -44,6 +44,8 @@ export const LocalsValuesContext =
   createContext<Record<string, unknown>>(EMPTY_NAMESPACE);
 export const LocalsUpdateContext = createContext<LocalsUpdater>(defaultUpdater);
 export const NobrContext = createContext(false);
+/** Whether the markup is the story interface, which stays mounted (#419). */
+export const InterfaceContext = createContext(false);
 /**
  * True while rendering inside an inline HTML element (e.g. `<span>`), where
  * block-level markdown and `<p>` wrappers would produce invalid HTML (#220).
@@ -82,6 +84,27 @@ const SvgContext = createContext(false);
 
 const SVG_NAMESPACE = 'http://www.w3.org/2000/svg';
 
+/**
+ * Elements whose children must be elements of particular types: markdown
+ * paragraphs between them would pull the children out of the structure (#423).
+ * Text between the children, when it is only whitespace, is dropped.
+ */
+const STRUCTURAL_ELEMENTS = new Set([
+  'table',
+  'thead',
+  'tbody',
+  'tfoot',
+  'tr',
+  'colgroup',
+  'ul',
+  'ol',
+  'menu',
+  'dl',
+  'select',
+  'optgroup',
+  'datalist',
+]);
+
 /** Elements whose content is literal text, not markdown. */
 const PREFORMATTED_ELEMENTS = new Set(['pre', 'textarea', 'style']);
 export const WidgetChildrenContext = createContext<WidgetChildren | null>(null);
@@ -691,16 +714,22 @@ function HtmlNodeRenderer({ node }: { node: HtmlNode }) {
         tag === 'details' ? leadingSummaryIndex(node.children) : -1;
       const body = (nodes: ASTNode[]) =>
         renderNodes(nodes, { nobr, locals, inline: isInline });
-      children =
-        summaryAt === -1 ? (
-          body(node.children)
-        ) : (
-          <>
-            {body(node.children.slice(0, summaryAt))}
-            {renderSingleNode(node.children[summaryAt]!)}
-            {body(node.children.slice(summaryAt + 1))}
-          </>
-        );
+      const structural =
+        STRUCTURAL_ELEMENTS.has(tag) &&
+        node.children.every((n) => n.type !== 'text' || n.value.trim() === '');
+      children = structural ? (
+        node.children
+          .filter((n) => n.type !== 'text')
+          .map((n) => renderSingleNode(n))
+      ) : summaryAt === -1 ? (
+        body(node.children)
+      ) : (
+        <>
+          {body(node.children.slice(0, summaryAt))}
+          {renderSingleNode(node.children[summaryAt]!)}
+          {body(node.children.slice(summaryAt + 1))}
+        </>
+      );
       if (isInline !== parentInline) {
         children = (
           <InlineContext.Provider value={isInline}>
@@ -710,6 +739,12 @@ function HtmlNodeRenderer({ node }: { node: HtmlNode }) {
       }
     }
   }
+  // The content of a foreignObject is HTML again, with HTML attributes
+  if (inSvg && tag === 'foreignobject' && children) {
+    children = (
+      <SvgContext.Provider value={false}>{children}</SvgContext.Provider>
+    );
+  }
   let element = h(node.tag, props, children);
   if (isSvgRoot && !inSvg) {
     element = <SvgContext.Provider value={true}>{element}</SvgContext.Provider>;
@@ -806,7 +841,7 @@ function renderMacro(node: MacroNode, key: string) {
  */
 function renderSingleNode(node: ASTNode): preact.ComponentChildren {
   // Authored text outside markdown still has its character references decoded
-  if (node.type === 'text') return decodeText(node.value);
+  if (node.type === 'text') return node.comment ? null : decodeText(node.value);
   const key = nodeKey(node);
   switch (node.type) {
     case 'variable':

package/src/markup/spindle.peggy

@@ -104,7 +104,7 @@ function lexeme(lex, loc, fields) {
 function nodeOf(x) {
   switch (x.lex) {
     case 'text':
-      return { type: 'text', value: x.value };
+      return x.comment ? { type: 'text', value: x.value, comment: true } : { type: 'text', value: x.value };
     case 'link':
       return withSelectors({ type: 'macro', name: 'link', rawArgs: quoteArg(x.display) + ' ' + quoteArg(x.target), children: [] }, x);
     case 'variable':
@@ -137,7 +137,7 @@ function tokenOf(x) {
 
 /**
  * Flatten items (lexemes, nodes, arrays of them, nulls) and join adjacent
- * text, except escaped braces, which stay a text item of their own.
+ * text, except escaped braces and comments, which stay a text item of their own.
  */
 function joinText(items, convert) {
   const out = [];
@@ -145,7 +145,7 @@ function joinText(items, convert) {
   const add = (item) => {
     if (item === null || item === undefined) return;
     if (Array.isArray(item)) return item.forEach(add);
-    if (item.lex === 'text' && !item.escape && last && last.lex === 'text' && !last.escape && last.end === item.start) {
+    if (item.lex === 'text' && !item.escape && !item.comment && last && last.lex === 'text' && !last.escape && !last.comment && last.end === item.start) {
       last.value += item.value;
       last.end = item.end;
       return;
@@ -332,7 +332,9 @@ TextRun
  */
 Comment
   = value:$("<!--" (">" / "->" / (!"-->" .)* "-->")) {
-      return lexeme('text', location(), { value });
+      const node = lexeme('text', location(), { value });
+      node.comment = true;
+      return node;
     }
 
 /**

package/src/saves/format.ts

@@ -175,7 +175,9 @@ function isPayload(value: unknown): value is Record<string, unknown> {
     isCountsMap(value.visitCounts) &&
     isCountsMap(value.renderCounts) &&
     isOptionalPRNGSnapshot(value.prng) &&
-    isWatchers(value.watchers)
+    isWatchers(value.watchers) &&
+    (value.interfaceWatchers === undefined ||
+      typeof value.interfaceWatchers === 'boolean')
   );
 }
 

package/src/saves/types.ts

@@ -28,6 +28,11 @@ export interface SavePayload {
   prng?: PRNGSnapshot | null;
   /** The {watch} macro watchers registered (absent in older saves). */
   watchers?: SavedWatcher[];
+  /**
+   * Whether the story interface had mounted when the save was made, so that
+   * `watchers` includes its {watch} macros (absent in older saves).
+   */
+  interfaceWatchers?: boolean;
 }
 
 export interface SaveMeta {

package/src/store.ts

@@ -23,6 +23,7 @@ import {
   resetTriggers,
   checkTriggersOnNavigation,
   restoreMacroWatchers,
+  interfaceMounted,
   savedMacroWatchers,
   reinitTriggerState,
 } from './triggers';
@@ -307,6 +308,7 @@ function persistSession(get: () => StoryState): { error: unknown } | undefined {
     renderCounts,
     prng: snapshotPRNG(),
     watchers: savedMacroWatchers(),
+    interfaceWatchers: interfaceMounted(),
   });
 }
 
@@ -576,10 +578,18 @@ function knownPlaythroughId(): string {
  * switch establishes.
  */
 export function resolvePlaythroughId(): Promise<string> {
+  if (leavingPlaythrough) return leavingPlaythrough;
   const current = knownPlaythroughId();
   return playthroughSetup.then((established) => current || established);
 }
 
+/**
+ * While the `beforeload` handlers of a load from a slot run, the playthrough
+ * the game is leaving: the saves they issue describe that game, though the
+ * load has already switched to the save's playthrough (#416).
+ */
+let leavingPlaythrough: Promise<string> | null = null;
+
 function setPlaythroughId(id: string): void {
   if (useStoryStore.getState().playthroughId === id) return;
   useStoryStore.setState((state) => {
@@ -661,6 +671,8 @@ let latestStateApplied = 0;
 
 /** The number of the slot load that is calling loadFromPayload. */
 let slotLoadApplying: number | null = null;
+/** The playthrough the slot load calling loadFromPayload leaves. */
+let slotLoadLeaving: Promise<string> | null = null;
 
 /** A replacement of the game state applied at its call. */
 function replaceStateNow(): void {
@@ -1529,6 +1541,7 @@ export const useStoryStore = create<StoryState>()(
           // A restart, boot or direct load issued after this one won
           if (latestStateApplied > replacement) return;
           slotLoadApplying = replacement;
+          slotLoadLeaving = previous;
           get().loadFromPayload(loaded.payload, slot);
         }),
         'spindle: failed to load save',
@@ -1679,6 +1692,7 @@ export const useStoryStore = create<StoryState>()(
         renderCounts: { ...renderCounts },
         prng: snapshotPRNG(),
         watchers: savedMacroWatchers(),
+        interfaceWatchers: interfaceMounted(),
       };
     },
 
@@ -1698,6 +1712,8 @@ export const useStoryStore = create<StoryState>()(
     ) => {
       const applying = slotLoadApplying;
       slotLoadApplying = null;
+      const leaving = slotLoadLeaving;
+      slotLoadLeaving = null;
       const replacement = applying ?? ++stateReplacementsIssued;
       if (payload.history.length === 0) {
         console.warn('loadFromPayload: rejecting payload with empty history');
@@ -1708,7 +1724,12 @@ export const useStoryStore = create<StoryState>()(
       assertPassagesExist(get().storyData, payload);
       applyReplacement(replacement);
 
-      emit('beforeload', slot);
+      leavingPlaythrough = leaving;
+      try {
+        emit('beforeload', slot);
+      } finally {
+        leavingPlaythrough = null;
+      }
 
       // Loading a save moves the game to the save's playthrough, after the
       // `beforeload` handlers (whose saves belong to the game being left).
@@ -1769,7 +1790,9 @@ export const useStoryStore = create<StoryState>()(
       // The watchers of the loaded game (a payload without any, from an
       // older version, leaves the registered ones), then: loaded state is
       // not a change watchers react to
-      if (payload.watchers) restoreMacroWatchers(payload.watchers);
+      if (payload.watchers) {
+        restoreMacroWatchers(payload.watchers, payload.interfaceWatchers);
+      }
       reinitTriggerState();
 
       // The next navigate() diffs from the snapshot recorded for the current

package/src/structural.ts

@@ -13,6 +13,7 @@ import { registeredClassName } from './class-registry';
 import { hasOwn, setOwn } from './utils/namespace';
 import { deleteByPath, getByPath, setByPath } from './utils/object-path';
 import {
+  ERROR_HIDDEN_KEYS,
   collectionSize,
   extraKeys,
   isAtomic,
@@ -54,9 +55,6 @@ function builtinLike<C extends object>(
   return empty;
 }
 
-/** 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 {

package/src/tooling.ts

@@ -97,7 +97,10 @@ export function validateStoryMarkup(
   const list = [...passages];
   const all = [...macros];
   const known = new Set<string>();
-  const blocks = new Set(blockWidgetNames(list).map((n) => n.toLowerCase()));
+  const parametersOf = parameterLookup(all);
+  const blocks = new Set(
+    blockWidgetNames(list, parametersOf).map((n) => n.toLowerCase()),
+  );
   for (const macro of all) {
     const name = macro.name.toLowerCase();
     known.add(name);
@@ -107,7 +110,7 @@ export function validateStoryMarkup(
   return validateMarkup(list, {
     isKnownMacro: (name) => known.has(name),
     macroNames: known,
-    parametersOf: parameterLookup(all),
+    parametersOf,
     isBlockMacro: (name) =>
       blocks.has(name.toLowerCase()) || isBlockMacro(name),
     checkPassageNames: options.checkPassageNames,

package/src/triggers.ts

@@ -134,16 +134,62 @@ export function savedMacroWatchers(): SavedWatcher[] {
     .map((t) => ({ condition: t.condition, options: { ...t.options } }));
 }
 
+/**
+ * The {watch} macros of the story interface that are mounted, and how many
+ * interfaces are: the interface mounts once the game has started, so a save
+ * made earlier (in StoryInit) holds none of its watchers.
+ */
+const interfaceWatches = new Set<SavedWatcher>();
+let interfacesMounted = 0;
+
+/** Record a mounted interface {watch}; call the result when it unmounts. */
+export function declareInterfaceWatch(
+  condition: string,
+  options: WatchOptions,
+): () => void {
+  const declared: SavedWatcher = { condition, options };
+  interfaceWatches.add(declared);
+  return () => {
+    interfaceWatches.delete(declared);
+  };
+}
+
+/** Record a mounted story interface; call the result when it unmounts. */
+export function declareInterfaceMounted(): () => void {
+  interfacesMounted++;
+  return () => {
+    interfacesMounted--;
+  };
+}
+
+/**
+ * Whether the story interface has mounted, so that its watchers are among
+ * `savedMacroWatchers()`: a save records it (see restoreMacroWatchers).
+ */
+export function interfaceMounted(): boolean {
+  return interfacesMounted > 0;
+}
+
 /**
  * Make the {watch} macro watchers those of a loaded game: the ones of
  * `watchers` replace the registered ones (watchers added by Story.watch
- * code stay). The passage shown mounts its own {watch} macros again.
+ * code stay). The passage shown mounts its own {watch} macros again. A save
+ * made before the story interface mounted (`interfaceSaved` false) cannot
+ * hold its watchers, so the ones of the mounted interface stay; in a later
+ * save a missing one was removed by `once` or {unwatch}, and stays so.
  */
-export function restoreMacroWatchers(watchers: readonly SavedWatcher[]): void {
+export function restoreMacroWatchers(
+  watchers: readonly SavedWatcher[],
+  interfaceSaved?: boolean,
+): void {
   triggers = triggers.filter((t) => t.macroKey === undefined);
   for (const { condition, options } of watchers) {
     addMacroTrigger(condition, options);
   }
+  if (interfaceSaved !== false) return;
+  for (const { condition, options } of interfaceWatches) {
+    addMacroTrigger(condition, options);
+  }
 }
 
 export function removeTrigger(name: string): void {

package/src/utils/stable-key.ts

@@ -1,5 +1,14 @@
+import { hasOwn } from './namespace';
 import { registeredClassName } from '../class-registry';
-import { extraKeys, mapEntries, setMembers } from './value-kinds';
+import {
+  ERROR_HIDDEN_KEYS,
+  extraKeys,
+  isBoxed,
+  isTemporal,
+  mapEntries,
+  setMembers,
+  toStringTag,
+} from './value-kinds';
 
 /**
  * Content-derived string key for a value, used to remount components when
@@ -11,8 +20,11 @@ import { extraKeys, mapEntries, setMembers } from './value-kinds';
  * 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.
+ * and, for a subclass of a built-in, its own fields (#407). The atomic
+ * built-ins (see isAtomic) have their contents in the key: the bytes of a
+ * buffer, the place of a view in its buffer, the text of a URL or
+ * URLSearchParams, the class, message, cause and errors of an Error, the
+ * value of a boxed primitive (#418). 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
@@ -88,6 +100,8 @@ function keyOf(val: unknown, seen: Map<object, number>): string {
     // hole from an undefined element (deepEqual does)
     return withFields(`[${Array.from(val, (v) => keyOf(v, seen)).join(',')}]`);
   }
+  const atomic = atomicKey(obj, seen);
+  if (atomic !== undefined) return named(atomic);
   if (val instanceof Map) {
     const entries = Array.from(
       mapEntries(val),
@@ -102,6 +116,46 @@ function keyOf(val: unknown, seen: Map<object, number>): string {
   return named(fieldsOf(obj, Object.keys(obj), seen));
 }
 
+/**
+ * The key of an atomic built-in other than a Map, Set, Date or RegExp (see
+ * isAtomic), or undefined for any other object. Read with the built-in
+ * methods, as a subclass may override them.
+ */
+function atomicKey(obj: object, seen: Map<object, number>): string | undefined {
+  if (obj instanceof ArrayBuffer) {
+    return `ArrayBuffer[${new Uint8Array(obj).join(',')}]`;
+  }
+  if (ArrayBuffer.isView(obj)) {
+    // A view is its place in its buffer, which other views can share
+    return `${toStringTag(obj)}(${obj.byteOffset},${obj.byteLength},${keyOf(obj.buffer, seen)})`;
+  }
+  let key: string;
+  if (obj instanceof URL) {
+    key = `URL(${JSON.stringify(Object.getOwnPropertyDescriptor(URL.prototype, 'href')!.get!.call(obj))})`;
+  } else if (obj instanceof URLSearchParams) {
+    key = `URLSearchParams(${JSON.stringify(URLSearchParams.prototype.toString.call(obj))})`;
+  } else if (isBoxed(obj)) {
+    key = `${toStringTag(obj)}(${keyOf((obj as Number).valueOf(), seen)})`;
+  } else if (isTemporal(obj)) {
+    key = `${toStringTag(obj)}(${JSON.stringify(String(obj))})`;
+  } else if (obj instanceof Error) {
+    const record = obj as unknown as Record<string, unknown>;
+    const held = ERROR_HIDDEN_KEYS.filter((k) => hasOwn(obj, k)).map(
+      (k) => `${k}:${keyOf(record[k], seen)}`,
+    );
+    const proto = Object.getPrototypeOf(obj) as {
+      constructor?: unknown;
+    } | null;
+    const ctor = proto?.constructor;
+    const name = typeof ctor === 'function' ? ctor.name : '';
+    key = `Error(${JSON.stringify(name)},${held.join(',')})`;
+  } else {
+    return undefined;
+  }
+  const keys = Object.keys(obj);
+  return keys.length ? `${key}${fieldsOf(obj, keys, seen)}` : key;
+}
+
 /** `{"key":value,...}` for the `keys` of `obj`. */
 function fieldsOf(
   obj: object,

package/src/utils/value-kinds.ts

@@ -46,6 +46,9 @@ export function atomicName(value: object): string | undefined {
   return `${/^[AEIOU]/.test(tag) ? 'an' : 'a'} ${tag}`;
 }
 
+/** Own keys of an error that are not enumerable but are data. */
+export const ERROR_HIDDEN_KEYS = ['message', 'cause', 'errors'] as const;
+
 /** Whether `key` is an index of an array element. */
 const isIndexKey = (key: string): boolean =>
   key !== '4294967295' && String(Number(key) >>> 0) === key;

package/src/widgets/ast-scanner.ts

@@ -1,10 +1,61 @@
 import type { ASTNode } from '../markup/ast';
+import type { Token } from '../markup/tokens';
+import { codeAndText, parameterLookup, type ParametersOf } from '../code-check';
+import { parseMarkup } from '../markup/parse';
+import { getMacroRegistry } from '../registry';
+
+/** The declared parameters of the macros registered so far. */
+export const registeredParameters: ParametersOf = (name) =>
+  parameterLookup(getMacroRegistry())(name);
+
+/**
+ * Whether the text of an attribute value or macro label renders a
+ * `{@children}`: it is markup, parsed as the renderer parses it.
+ */
+function textContainsChildren(
+  text: string,
+  parametersOf: ParametersOf,
+): boolean {
+  if (!text.includes('{')) return false;
+  let nodes: ASTNode[];
+  try {
+    nodes = parseMarkup(text, { text: true });
+  } catch {
+    // The renderer reports the markup that does not parse
+    return false;
+  }
+  return astContainsChildren(nodes, parametersOf);
+}
+
+/**
+ * Whether a tag renders a `{@children}` in an attribute value or a macro
+ * argument that holds markup (`<span title="{@children}">`,
+ * `{button "{@children}"}`). Literal arguments and code are not markup.
+ */
+export function tokenTextContainsChildren(
+  token: Token,
+  parametersOf: ParametersOf = registeredParameters,
+): boolean {
+  for (const piece of codeAndText('', [token], parametersOf)) {
+    if (
+      piece.kind === 'text' &&
+      textContainsChildren(piece.text, parametersOf)
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
 
 /**
  * Recursively scan an AST node array for a VariableNode
- * with scope 'local' and name 'children' (@children).
+ * with scope 'local' and name 'children' (@children), in the content and in
+ * the attributes and labels that render markup.
  */
-export function astContainsChildren(nodes: ASTNode[]): boolean {
+export function astContainsChildren(
+  nodes: ASTNode[],
+  parametersOf: ParametersOf = registeredParameters,
+): boolean {
   for (const node of nodes) {
     if (
       node.type === 'variable' &&
@@ -13,14 +64,33 @@ export function astContainsChildren(nodes: ASTNode[]): boolean {
     ) {
       return true;
     }
-    if (node.type === 'html' && astContainsChildren(node.children)) {
-      return true;
+    if (node.type === 'html') {
+      const span = { start: 0, end: 0 };
+      const tag: Token = {
+        isClose: false,
+        isSelfClose: false,
+        ...node,
+        ...span,
+      };
+      if (
+        tokenTextContainsChildren(tag, parametersOf) ||
+        astContainsChildren(node.children, parametersOf)
+      ) {
+        return true;
+      }
     }
     if (node.type === 'macro') {
-      if (astContainsChildren(node.children)) return true;
+      const span = { start: 0, end: 0 };
+      const tag: Token = { isClose: false, ...node, ...span };
+      if (
+        tokenTextContainsChildren(tag, parametersOf) ||
+        astContainsChildren(node.children, parametersOf)
+      ) {
+        return true;
+      }
       if (node.branches) {
         for (const branch of node.branches) {
-          if (astContainsChildren(branch.children)) return true;
+          if (astContainsChildren(branch.children, parametersOf)) return true;
         }
       }
     }

package/src/widgets/widget-def.ts

@@ -5,6 +5,8 @@
 import { parseMacroArgs } from '../components/macros/macro-args';
 import type { MacroArgs } from '../registry';
 import { tokenizeMarkupTolerant } from '../markup/parse';
+import type { ParametersOf } from '../code-check';
+import { registeredParameters, tokenTextContainsChildren } from './ast-scanner';
 
 /** A {widget} definition's name, then its `@` parameters. */
 export const WIDGET_PARAMETERS = [
@@ -49,6 +51,7 @@ export function parseWidgetDef(rawArgs: string): WidgetDef {
  */
 export function blockWidgetNames(
   passages: Iterable<{ name: string; tags?: string[]; content: string }>,
+  parametersOf: ParametersOf = registeredParameters,
 ): string[] {
   const names: string[] = [];
   for (const passage of passages) {
@@ -71,10 +74,11 @@ export function blockWidgetNames(
           // The {widget} macro reports a definition it cannot read
         }
       } else if (
-        token.type === 'variable' &&
-        token.scope === 'local' &&
-        token.name === 'children' &&
-        open.length > 0
+        open.length > 0 &&
+        ((token.type === 'variable' &&
+          token.scope === 'local' &&
+          token.name === 'children') ||
+          tokenTextContainsChildren(token, parametersOf))
       ) {
         open[open.length - 1]!.isBlock = true;
       }