@rohal12/spindle 0.59.8 → 0.59.10

package/package.json

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

package/src/class-registry.ts

@@ -51,7 +51,9 @@ export function clearRegistry(): void {
 //   with its message, cause, errors and own enumerable keys (not its stack);
 // - `S`: a symbol from the global registry (Symbol.for);
 // - `K`: a plain object holding a one-character key that JSON escapes (see
-//   GUARD_V8_KEYS).
+//   GUARD_V8_KEYS);
+// - `R`: a RegExp whose lastIndex is not zero (the scanning cursor of a
+//   global or sticky pattern), with its source, flags and lastIndex.
 //
 // Everything else is refused when saving, with the path to the value:
 // functions, unique symbols, symbol keys, instances of unregistered classes,
@@ -61,6 +63,7 @@ const CLASS_PREFIX = 'c:';
 const ERROR_PREFIX = 'E:';
 const SYMBOL_TAG = 'S';
 const KEYS_TAG = 'K';
+const REGEXP_TAG = 'R';
 
 /**
  * Work around Chromium issue 521080746 (V8 in Chrome/Chromium 14x-153+,
@@ -167,6 +170,9 @@ function reducers(): Record<string, (value: unknown) => unknown> {
     const key = Symbol.keyFor(v);
     return key !== undefined && [key];
   };
+  out[REGEXP_TAG] = (v) =>
+    v instanceof RegExp &&
+    v.lastIndex !== 0 && [v.source, v.flags, v.lastIndex];
   if (GUARD_V8_KEYS) {
     out[KEYS_TAG] = (v) => {
       if (!isObject(v) || Object.getPrototypeOf(v) !== Object.prototype) {
@@ -264,6 +270,21 @@ function reviverFor(key: string | symbol) {
     };
   }
   if (key === KEYS_TAG) return reviveKeyed;
+  if (key === REGEXP_TAG) {
+    return (data: unknown) => {
+      if (
+        !Array.isArray(data) ||
+        typeof data[0] !== 'string' ||
+        typeof data[1] !== 'string' ||
+        !Number.isSafeInteger(data[2])
+      ) {
+        throw new TypeError('spindle: Malformed regular expression');
+      }
+      const re = new RegExp(data[0], data[1]);
+      re.lastIndex = data[2] as number;
+      return re;
+    };
+  }
   if (key.startsWith(CLASS_PREFIX)) {
     return reviveClass(key.slice(CLASS_PREFIX.length));
   }

package/src/components/PassageDialog.tsx

@@ -83,9 +83,9 @@ export function PassageDialog({
 
   const handleBackdrop = (e: MouseEvent) => {
     if (!dismissible) return;
-    if ((e.target as HTMLElement).classList.contains('dialog-overlay')) {
-      stableOnClose();
-    }
+    // Only a click on this overlay itself: a nested dialog's backdrop click
+    // bubbles through the outer overlay, whose target is not its own.
+    if (e.target === e.currentTarget) stableOnClose();
   };
 
   const cls = panelClass ? `dialog-panel ${panelClass}` : 'dialog-panel';
@@ -105,6 +105,7 @@ export function PassageDialog({
         >
           {showCloseButton && (
             <button
+              type="button"
               class="dialog-close"
               aria-label="Close"
               onClick={stableOnClose}

package/src/components/macros/Button.tsx

@@ -26,6 +26,7 @@ defineMacro({
 
     return (
       <button
+        type="button"
         id={ctx.id}
         class={ctx.cls}
         onClick={handleClick}

package/src/components/macros/Cycle.tsx

@@ -32,6 +32,7 @@ defineMacro({
 
     return (
       <button
+        type="button"
         id={ctx.id}
         class={ctx.cls}
         onClick={handleClick}

package/src/components/macros/Dialog.tsx

@@ -22,6 +22,7 @@ defineMacro({
     return (
       <>
         <button
+          type="button"
           id={ctx.id}
           class={ctx.cls}
           onClick={() => setOpen(true)}

package/src/components/macros/Do.tsx

@@ -1,5 +1,5 @@
 import { defineMacro } from '../../define-macro';
-import { logMacroError } from './MacroError';
+import { useRunOnce } from './MacroError';
 
 defineMacro({
   name: 'do',
@@ -8,16 +8,8 @@ defineMacro({
     // The parser keeps the body verbatim as a single text node
     const code = ctx.collectText(children);
 
-    ctx.hooks.useLayoutEffect(() => {
-      // Before the code runs: it may navigate away from this passage
-      const location = ctx.sourceLocation();
-      try {
-        ctx.mutate(code);
-      } catch (err) {
-        logMacroError('do', err, location);
-      }
-    }, []);
-
-    return null;
+    // During the first render, like {set}: the macros after it in the
+    // passage run later and see its writes (a layout effect ran after them).
+    return useRunOnce('do', '', () => ctx.mutate(code));
   },
 });

package/src/components/macros/MacroError.tsx

@@ -49,7 +49,7 @@ export function useRunOnce(macro: string, rawArgs: string, effect: () => void) {
       effect();
     } catch (error) {
       failure.current = { error };
-      logMacroError(`${macro} ${rawArgs}`, error, location);
+      logMacroError(`${macro} ${rawArgs}`.trim(), error, location);
     }
   }
 

package/src/components/macros/MenubarButtons.tsx

@@ -63,6 +63,7 @@ export function defineMenubarAction(config: MenubarActionConfig) {
       return (
         <>
           <button
+            type="button"
             id={ctx.id}
             class={cls}
             onClick={perform}

package/src/components/macros/PassageDisplay.tsx

@@ -1,6 +1,15 @@
-import { useRef, useEffect, useCallback, useState } from 'preact/hooks';
-import { useStoryStore } from '../../store';
-import { useStoryFields } from '../../hooks/use-story-fields';
+import {
+  useRef,
+  useEffect,
+  useLayoutEffect,
+  useCallback,
+  useState,
+} from 'preact/hooks';
+import { useStoryStore, type StoryState } from '../../store';
+import {
+  useStoryFields,
+  FrozenStateContext,
+} from '../../hooks/use-story-fields';
 import { Passage, renderPassageContent } from '../Passage';
 import { defineMacro } from '../../define-macro';
 import { resolveTransition, type ResolvedTransition } from '../../transition';
@@ -8,7 +17,7 @@ import { resolveTransition, type ResolvedTransition } from '../../transition';
 /**
  * Create a snapshot clone of a .passage element for outgoing transitions.
  * - Strips `id` attributes from the clone tree
- * - Disables interaction (pointer-events, user-select)
+ * - Disables interaction (pointer-events, user-select, inert, aria-hidden)
  * - Pauses/mutes any <audio>/<video>
  * - Adds `.passage-snapshot` class and `data-transition` attribute
  */
@@ -28,6 +37,10 @@ function createSnapshot(
   // Disable interaction
   clone.style.pointerEvents = 'none';
   clone.style.userSelect = 'none';
+  // Visual only: out of the tab order and the accessibility tree, and its
+  // controls (copied with their inline handlers) can not be activated
+  clone.setAttribute('inert', '');
+  clone.setAttribute('aria-hidden', 'true');
 
   // Pause/mute media
   const mediaEls = clone.querySelectorAll('audio, video');
@@ -122,6 +135,13 @@ defineMacro({
     // Track previous history length to detect restart/load
     const prevHistoryLenRef = useRef(0);
 
+    const displayedId = displayed.id;
+    const isOutgoing = useCallback(
+      (state: StoryState) => state.navigationId !== displayedId,
+      [displayedId],
+    );
+    const lastElement = useRef<preact.VNode | null>(null);
+
     // Container ref for snapshot insertion
     const containerRef = useRef<HTMLDivElement>(null);
 
@@ -261,6 +281,22 @@ defineMacro({
       // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [navigationId]);
 
+    // A new passage opens at its beginning, not where the previous one was
+    // scrolled to (#354). The page keeps its position on first display
+    // (a refresh restores it) and when the beginning is already in view.
+    const shownId = displayedPassage && !renderDeferred ? displayed.id : null;
+    const lastShownId = useRef(shownId);
+    useLayoutEffect(() => {
+      if (shownId === null) return; // between passages of a transition
+      const previous = lastShownId.current;
+      lastShownId.current = shownId;
+      if (previous === null || previous === shownId) return;
+      const el = containerRef.current?.querySelector('.passage');
+      if (el && el.getBoundingClientRect().top < 0) {
+        el.scrollIntoView?.({ block: 'start' });
+      }
+    }, [shownId]);
+
     // When render is deferred, show StoryLoading passage or nothing
     const effectivePassage = renderDeferred
       ? (storyData?.passages.get('StoryLoading') ?? null)
@@ -278,6 +314,23 @@ defineMacro({
 
     const readyPassage = storyData?.passages.get('PassageReady');
 
+    // Between a navigation and the commit of its passage, the old passage is
+    // still mounted. It must not execute against the destination's state, so
+    // it keeps the element and the state it last rendered with (#352).
+    const outgoing = !renderDeferred && displayed.id !== navigationId;
+    const passageElement =
+      outgoing && lastElement.current
+        ? lastElement.current
+        : effectivePassage && (
+            <Passage
+              passage={effectivePassage}
+              key={renderDeferred ? 'loading' : `nav-${displayed.id}`}
+              dataTransition={renderDeferred ? 'none' : resolvedTypeRef.current}
+              navigationId={renderDeferred ? undefined : displayed.id}
+            />
+          );
+    lastElement.current = passageElement || null;
+
     return (
       <div
         id={ctx.id ?? 'story'}
@@ -295,13 +348,10 @@ defineMacro({
           class="passage-container"
           ref={containerRef}
         >
-          {effectivePassage && (
-            <Passage
-              passage={effectivePassage}
-              key={renderDeferred ? 'loading' : `nav-${displayed.id}`}
-              dataTransition={renderDeferred ? 'none' : resolvedTypeRef.current}
-              navigationId={renderDeferred ? undefined : displayed.id}
-            />
+          {passageElement && (
+            <FrozenStateContext.Provider value={isOutgoing}>
+              {passageElement}
+            </FrozenStateContext.Provider>
           )}
         </div>
       </div>

package/src/components/macros/SaveManager.tsx

@@ -21,6 +21,7 @@ import {
   saveWithHooks,
   type PlaythroughGroup,
 } from '../../saves/save-manager';
+import { getBackendType } from '../../saves/storage';
 import { DialogCloseContext } from '../PassageDialog';
 import { defineMacro } from '../../define-macro';
 import { errorMessage } from '../../utils/error-message';
@@ -71,10 +72,15 @@ export function SaveManagerContent() {
       'loadFromPayload',
     );
   const ifid = storyData?.ifid ?? '';
+  // Saves held in memory only (no browser storage is available) are lost
+  // when the page is reloaded or closed: told to the player, who can export
+  const [temporary, setTemporary] = useState(false);
 
   const refresh = useCallback(async () => {
     if (!ifid) return;
     const data = await getSavesGrouped(ifid);
+    // After the read: the storage in use is known by now
+    setTemporary(getBackendType() === 'memory');
     setGroups(data);
     setLoading(false);
   }, [ifid]);
@@ -131,7 +137,7 @@ export function SaveManagerContent() {
         // Queued now, in call order with other storage operations
         return createSave(ifid, playthrough, payload);
       });
-      showStatus('Save created');
+      showStatus(temporary ? 'Save created (temporary)' : 'Save created');
       await refresh();
     } catch {
       showStatus('Failed to create save', 'error');
@@ -276,12 +282,14 @@ export function SaveManagerContent() {
         <div class="saves-header-left">
           <div class="saves-mode-toggle">
             <button
+              type="button"
               class={mode === 'save' ? 'active' : ''}
               onClick={() => setMode('save')}
             >
               Save
             </button>
             <button
+              type="button"
               class={mode === 'load' ? 'active' : ''}
               onClick={() => setMode('load')}
             >
@@ -291,8 +299,19 @@ export function SaveManagerContent() {
         </div>
       </div>
 
+      {temporary && (
+        <div
+          class="saves-notice"
+          role="status"
+        >
+          Saves can not be kept in this browser: they are lost when the page is
+          reloaded or closed. Export a save to keep it.
+        </div>
+      )}
+
       <div class="saves-toolbar">
         <button
+          type="button"
           class="saves-toolbar-button"
           onClick={handleImport}
         >
@@ -376,6 +395,7 @@ export function SaveManagerContent() {
                         <div class="save-slot-actions">
                           {mode === 'save' ? (
                             <button
+                              type="button"
                               class="save-slot-action primary"
                               onClick={() => handleOverwrite(save.meta.id)}
                             >
@@ -383,6 +403,7 @@ export function SaveManagerContent() {
                             </button>
                           ) : (
                             <button
+                              type="button"
                               class="save-slot-action primary"
                               onClick={() => handleLoad(save)}
                             >
@@ -390,18 +411,21 @@ export function SaveManagerContent() {
                             </button>
                           )}
                           <button
+                            type="button"
                             class="save-slot-action"
                             onClick={() => handleRenameStart(save)}
                           >
                             Rename
                           </button>
                           <button
+                            type="button"
                             class="save-slot-action"
                             onClick={() => handleExport(save.meta.id)}
                           >
                             Export
                           </button>
                           <button
+                            type="button"
                             class="save-slot-action danger"
                             onClick={() => handleDelete(save.meta.id)}
                           >
@@ -413,6 +437,7 @@ export function SaveManagerContent() {
 
                     {mode === 'save' && isCurrentPt && (
                       <button
+                        type="button"
                         class="save-slot-new"
                         onClick={handleNewSave}
                       >
@@ -432,6 +457,7 @@ export function SaveManagerContent() {
             <div class="playthrough-group">
               <div class="playthrough-saves">
                 <button
+                  type="button"
                   class="save-slot-new"
                   onClick={handleNewSave}
                 >

package/src/components/macros/Type.tsx

@@ -1,15 +1,54 @@
 import { defineMacro } from '../../define-macro';
 import { DELAY_PARAMETER } from './macro-args';
 
+/**
+ * The clip-path that shows the first `count` characters of `root`'s text in
+ * reading order: the boxes the browser laid out for them, each wrapped line
+ * as far as its last revealed character, as one path in the coordinates of
+ * `inner`'s box. Undefined where there is no layout to measure.
+ */
+function revealedPath(
+  root: HTMLElement,
+  inner: HTMLElement,
+  count: number,
+): string | undefined {
+  const range = document.createRange();
+  if (!range.getClientRects) return undefined;
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+  let left = count;
+  let end: { node: Node; offset: number } | undefined;
+  for (let n = walker.nextNode(); n && left > 0; n = walker.nextNode()) {
+    const length = n.nodeValue?.length ?? 0;
+    end = { node: n, offset: Math.min(left, length) };
+    left -= length;
+  }
+  if (!end) return 'inset(0 100% 0 0)';
+  range.setStart(root, 0);
+  range.setEnd(end.node, end.offset);
+  const rects = range.getClientRects();
+  if (rects.length === 0) return undefined;
+  const origin = inner.getBoundingClientRect();
+  let path = '';
+  for (const r of Array.from(rects)) {
+    if (r.width === 0 && r.height === 0) continue;
+    const x = (r.left - origin.left).toFixed(2);
+    const y = (r.top - origin.top).toFixed(2);
+    path += `M${x} ${y}h${r.width.toFixed(2)}v${r.height.toFixed(2)}h-${r.width.toFixed(2)}z`;
+  }
+  return path ? `path("${path}")` : undefined;
+}
+
 defineMacro({
   name: 'type',
   block: true,
   interpolate: true,
   parameters: [DELAY_PARAMETER],
   render({ children = [] }, ctx) {
-    const { useState, useEffect, useRef } = ctx.hooks;
+    const { useState, useEffect, useLayoutEffect, useRef } = ctx.hooks;
     const speed = ctx.args.delay ?? 0;
     const containerRef = useRef<HTMLSpanElement>(null);
+    const innerRef = useRef<HTMLSpanElement>(null);
+    const [clip, setClip] = useState<string | undefined>();
     const [totalChars, setTotalChars] = useState(0);
     const [visibleChars, setVisibleChars] = useState(0);
     const visibleCharsRef = useRef(0);
@@ -44,6 +83,21 @@ defineMacro({
 
     const done = visibleChars >= totalChars && totalChars > 0;
 
+    // Clip to the characters revealed so far, as laid out: remeasured when
+    // the count changes and when the width the text wraps in does.
+    useLayoutEffect(() => {
+      const root = containerRef.current;
+      const inner = innerRef.current;
+      if (!root || !inner || totalChars === 0 || done) {
+        setClip(undefined);
+        return;
+      }
+      const measure = () => setClip(revealedPath(root, inner, visibleChars));
+      measure();
+      window.addEventListener('resize', measure);
+      return () => window.removeEventListener('resize', measure);
+    }, [visibleChars, totalChars, done]);
+
     const cls = [
       'macro-type',
       done ? 'macro-type-done' : '',
@@ -57,19 +111,14 @@ defineMacro({
         id={ctx.id}
         class={cls}
         ref={containerRef}
-        style={{
-          clipPath: totalChars > 0 && !done ? undefined : undefined,
-        }}
       >
         <span
+          ref={innerRef}
           class="macro-type-inner"
           style={{
             display: 'inline',
             visibility: totalChars === 0 ? 'hidden' : 'visible',
-            clipPath:
-              totalChars > 0 && !done
-                ? `inset(0 ${((totalChars - visibleChars) / totalChars) * 100}% 0 0)`
-                : undefined,
+            clipPath: clip,
           }}
         >
           {ctx.renderInlineNodes(children)}

package/src/components/macros/WidgetInvocation.tsx

@@ -15,13 +15,32 @@ interface WidgetInvocationProps {
   params: string[];
   rawArgs?: string;
   invocationChildren?: ASTNode[];
+  className?: string;
+  id?: string;
 }
 
-export function WidgetInvocation({
+export function WidgetInvocation(props: WidgetInvocationProps) {
+  const { className, id } = props;
+  const content = <WidgetContent {...props} />;
+  // Invocation selectors (`{.badge#hero Stats}`) need an element to land on.
+  if (!className && !id) return content;
+  return (
+    <span
+      class={className}
+      id={id}
+    >
+      {content}
+    </span>
+  );
+}
+
+function WidgetContent({
   body,
   params,
   rawArgs,
   invocationChildren,
+  className,
+  id,
 }: WidgetInvocationProps) {
   const renderOptions = useRenderOptions();
   const parentValues = renderOptions.locals;

package/src/components/macros/detached-body.tsx

@@ -10,16 +10,20 @@ import {
 } from '../../markup/render';
 import type { ASTNode } from '../../markup/ast';
 import { useRenderOptions } from '../../hooks/use-render-options';
+import { FrozenStateContext } from '../../hooks/use-story-fields';
 import { liveLocalsView } from '../../utils/live-locals';
 import { runWithCommittedMutations } from '../../execute-mutation';
 import { RepeatContext } from './Repeat';
 import { DialogCloseContext } from '../PassageDialog';
 
+const frozenAlways = () => true;
+
 /**
  * Return a function that runs a macro body once, outside the passage tree:
  * it renders `children` into a detached node, so the body's macros ({set},
  * {if}, {goto}, ...) fire their side effects through the normal Preact
- * pipeline. Used by {button} and {link} on click. The body stays mounted
+ * pipeline. Used by {button} and {link} on click. The body's state is frozen
+ * once it has rendered, so it runs once per click. It stays mounted
  * until the owning macro unmounts (its passage changes, say), so work it
  * starts in an effect, such as the timer of a {timed} or {repeat}, can
  * finish; the passage leaving cancels it.
@@ -58,21 +62,23 @@ export function useDetachedBody(): (children: ASTNode[]) => void {
     const locals = liveLocalsView(updater.getValues);
     const container = document.createElement('div');
     render(
-      <LocalsUpdateContext.Provider value={updater}>
-        <LocalsValuesContext.Provider value={locals}>
-          <NobrContext.Provider value={nobr}>
-            <InlineContext.Provider value={inline}>
-              <WidgetChildrenContext.Provider value={widgetChildren}>
-                <RepeatContext.Provider value={repeat}>
-                  <DialogCloseContext.Provider value={closeDialog}>
-                    {renderNodes(children, { nobr, inline, locals })}
-                  </DialogCloseContext.Provider>
-                </RepeatContext.Provider>
-              </WidgetChildrenContext.Provider>
-            </InlineContext.Provider>
-          </NobrContext.Provider>
-        </LocalsValuesContext.Provider>
-      </LocalsUpdateContext.Provider>,
+      <FrozenStateContext.Provider value={frozenAlways}>
+        <LocalsUpdateContext.Provider value={updater}>
+          <LocalsValuesContext.Provider value={locals}>
+            <NobrContext.Provider value={nobr}>
+              <InlineContext.Provider value={inline}>
+                <WidgetChildrenContext.Provider value={widgetChildren}>
+                  <RepeatContext.Provider value={repeat}>
+                    <DialogCloseContext.Provider value={closeDialog}>
+                      {renderNodes(children, { nobr, inline, locals })}
+                    </DialogCloseContext.Provider>
+                  </RepeatContext.Provider>
+                </WidgetChildrenContext.Provider>
+              </InlineContext.Provider>
+            </NobrContext.Provider>
+          </LocalsValuesContext.Provider>
+        </LocalsUpdateContext.Provider>
+      </FrozenStateContext.Provider>,
       container,
     );
     mounted.current.push(container);

package/src/components/macros/input-macro.ts

@@ -59,14 +59,29 @@ export function defineInputMacro(
         perform: (v) => ctx.setValue!(toValue(v)),
       });
 
+      // What the reader last typed. A number input reports an unfinished
+      // number ("-", "2e") as an empty value, so the text is kept for as
+      // long as it still converts to the variable's value, instead of being
+      // replaced by that value on every keystroke (#353).
+      const typed = ctx.hooks.useRef<string | null>(null);
+      const shown =
+        typed.current !== null &&
+        toValue(typed.current) === ctx.value &&
+        type === 'number'
+          ? typed.current
+          : display(ctx.value);
+
       return h(type ? 'input' : 'textarea', {
         type,
         id: ctx.id,
         class: ctx.cls,
-        value: display(ctx.value),
+        value: shown,
         placeholder,
-        onInput: (e: Event) =>
-          ctx.setValue!(toValue((e.target as HTMLInputElement).value)),
+        onInput: (e: Event) => {
+          const text = (e.target as HTMLInputElement).value;
+          typed.current = text;
+          ctx.setValue!(toValue(text));
+        },
       });
     },
   });

package/src/hooks/use-merged-locals.ts

@@ -12,14 +12,17 @@ export function useMergedLocals(): readonly [
   Record<string, unknown>,
   Record<string, unknown>,
 ] {
-  const { variables, temporary, transient } = useStoryFields(
+  // renderCounts is read by rendered()/hasRendered() inside expressions, so
+  // it re-renders them (and renews the tuple) when an inclusion mounts.
+  const { variables, temporary, transient, renderCounts } = useStoryFields(
     'variables',
     'temporary',
     'transient',
+    'renderCounts',
   );
   const localsValues = useContext(LocalsValuesContext);
 
   return useMemo(() => {
     return [variables, temporary, localsValues, transient] as const;
-  }, [variables, temporary, localsValues, transient]);
+  }, [variables, temporary, localsValues, transient, renderCounts]);
 }