@rohal12/spindle 0.52.8 → 0.53.0

package/src/components/macros/Do.tsx

@@ -9,10 +9,12 @@ defineMacro({
     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);
+        logMacroError('do', err, location);
       }
     }, []);
 

package/src/components/macros/Goto.tsx

@@ -1,6 +1,7 @@
 import { useStoryStore } from '../../store';
 import { defineMacro } from '../../define-macro';
 import { evaluatePassageName } from './macro-args';
+import { logMacroError } from './MacroError';
 
 defineMacro({
   name: 'goto',
@@ -8,9 +9,18 @@ defineMacro({
   parameters: [{ name: 'passage', type: 'expression', required: true }],
   render(_props, ctx) {
     ctx.hooks.useLayoutEffect(() => {
-      useStoryStore
-        .getState()
-        .navigate(evaluatePassageName(ctx.args.passage, ctx.evaluate!));
+      // Reported like an error in {do}: thrown out of an effect, it would
+      // abort the rest of the render's effects (e.g. the session could not
+      // be written because the state holds a function). The location is
+      // this passage's, taken before navigating away from it
+      const location = ctx.sourceLocation();
+      try {
+        useStoryStore
+          .getState()
+          .navigate(evaluatePassageName(ctx.args.passage, ctx.evaluate!));
+      } catch (err) {
+        logMacroError('goto', err, location);
+      }
     }, []);
 
     return null;

package/src/components/macros/MacroError.tsx

@@ -19,12 +19,18 @@ export function MacroError({
   );
 }
 
-/** Log an error in the macro `{label}` (its name, or name and arguments). */
-export function logMacroError(label: string, error: unknown): void {
-  console.error(
-    `spindle: Error in {${label}}${currentSourceLocation()}:`,
-    error,
-  );
+/**
+ * Log an error in the macro `{label}` (its name, or name and arguments) at
+ * `location`, the source location of the macro's passage. Take it before
+ * running the code that failed (see currentSourceLocation): code that
+ * navigates changes the current passage.
+ */
+export function logMacroError(
+  label: string,
+  error: unknown,
+  location: string = currentSourceLocation(),
+): void {
+  console.error(`spindle: Error in {${label}}${location}:`, error);
 }
 
 /**
@@ -38,11 +44,12 @@ export function useRunOnce(macro: string, rawArgs: string, effect: () => void) {
   const failure = useRef<{ error: unknown } | null>();
   if (failure.current === undefined) {
     failure.current = null;
+    const location = currentSourceLocation();
     try {
       effect();
     } catch (error) {
       failure.current = { error };
-      logMacroError(`${macro} ${rawArgs}`, error);
+      logMacroError(`${macro} ${rawArgs}`, error, location);
     }
   }
 

package/src/components/macros/SaveManager.tsx

@@ -17,7 +17,7 @@ import {
   renameSave,
   exportSave,
   importSave,
-  deserializePayload,
+  decodeSavePayload,
   saveWithHooks,
   type PlaythroughGroup,
 } from '../../saves/save-manager';
@@ -160,7 +160,7 @@ export function SaveManagerContent() {
       // Stored records hold serialized variables; the store expects live
       // ones. The game moves to the save's playthrough.
       loadFromPayload(
-        deserializePayload(save.payload),
+        decodeSavePayload(save.payload),
         undefined,
         save.meta.playthroughId,
       );

package/src/markup/render.tsx

@@ -1,4 +1,4 @@
-import { createContext } from 'preact';
+import { createContext, type RefObject } from 'preact';
 import { useContext, useLayoutEffect, useRef } from 'preact/hooks';
 import { VarDisplay } from '../components/macros/VarDisplay';
 import { ExprDisplay } from '../components/macros/ExprDisplay';
@@ -63,6 +63,8 @@ export const RawTextContext = createContext(false);
  */
 const SvgContext = createContext(false);
 
+const SVG_NAMESPACE = 'http://www.w3.org/2000/svg';
+
 /** Elements whose content is literal text, not markdown. */
 const PREFORMATTED_ELEMENTS = new Set(['pre', 'textarea']);
 export const WidgetChildrenContext = createContext<ASTNode[] | null>(null);
@@ -139,31 +141,59 @@ function expandPlaceholderText(
   );
 }
 
+/** An attribute: its name, value and value as written (see splitAttributes). */
+type Attribute = [name: string, value: string, written: string];
+
 /**
- * An element whose attributes contain placeholders (a variable in image alt
- * text or a link title). Each such attribute is evaluated as text against
- * the store and locals, so it follows its variables as the component would.
+ * An element of markdown output whose attributes contain placeholders (a
+ * variable in image alt text or a link title). Each such attribute is
+ * evaluated as text against the store and locals, so it follows its
+ * variables as the component would.
  */
 function PlaceholderAttributes({
   tag,
-  props,
   attributes,
+  placeholders,
+  svg,
   children,
 }: {
   tag: string;
-  props: Record<string, string>;
-  attributes: Record<string, ASTNode[]>;
+  attributes: Attribute[];
+  placeholders: Record<string, ASTNode[]>;
+  svg: boolean;
   children: preact.ComponentChildren[];
 }) {
   const scope = useTextScope();
-  const resolved: Record<string, string> = { ...props };
   const errors: AttributeError[] = [];
-  for (const [name, nodes] of Object.entries(attributes)) {
+  const resolved = attributes.map(([name, value, written]): Attribute => {
+    const nodes = placeholders[name];
+    if (!nodes) return [name, value, written];
     const result = renderText(nodes, scope);
-    resolved[name] = result.text;
     for (const error of result.errors) errors.push([name, error]);
-  }
-  return withAttributeErrors(errors, h(tag, resolved, ...children));
+    return [name, result.text, written];
+  });
+  const { props, direct } = splitAttributes(resolved, svg);
+  const ref = useDirectAttributes(direct);
+  return withAttributeErrors(
+    errors,
+    h(tag, ref ? { ...props, ref } : props, ...children),
+  );
+}
+
+/** An element of markdown output with attributes to set directly. */
+function DirectAttributes({
+  tag,
+  props,
+  direct,
+  children,
+}: {
+  tag: string;
+  props: Record<string, unknown>;
+  direct: [string, string][];
+  children: preact.ComponentChildren[];
+}) {
+  const ref = useDirectAttributes(direct);
+  return h(tag, { ...props, ref }, ...children);
 }
 
 /** An error met while evaluating the named attribute. */
@@ -201,6 +231,19 @@ function placeholderIndex(node: Node | null, ph: Placeholders): number {
   return parseInt(value.slice(prefix.length), 10);
 }
 
+/**
+ * Parse HTML into nodes without side effects. The content of a `<template>`
+ * belongs to a document with no browsing context, so parsing it fetches no
+ * images and media, runs no inline event handlers (`<img onerror>`) and
+ * constructs no custom elements. A detached `<div>` belongs to the page's
+ * document, which does all of these while parsing.
+ */
+export function parseHtmlInert(html: string): DocumentFragment {
+  const template = document.createElement('template');
+  template.innerHTML = html;
+  return template.content;
+}
+
 /**
  * Convert an HTML string (from micromark) to Preact VNodes,
  * replacing placeholder elements with pre-rendered components.
@@ -212,14 +255,15 @@ function htmlToPreact(
   ph: Placeholders,
   unwrapParagraphs = false,
 ): preact.ComponentChildren {
-  const temp = document.createElement('div');
-  temp.innerHTML = html.trim();
+  const content = parseHtmlInert(html.trim());
   if (unwrapParagraphs) {
-    for (const p of Array.from(temp.querySelectorAll(':scope > p'))) {
-      p.replaceWith(...Array.from(p.childNodes));
+    for (const child of Array.from(content.childNodes)) {
+      if (child.nodeType === Node.ELEMENT_NODE && child.nodeName === 'P') {
+        (child as Element).replaceWith(...Array.from(child.childNodes));
+      }
     }
   }
-  const children = Array.from(temp.childNodes).map((child, i) =>
+  const children = Array.from(content.childNodes).map((child, i) =>
     convertDomNode(child, i, ph),
   );
   return <>{children}</>;
@@ -252,17 +296,17 @@ function convertDomNode(
       return ph.components[idx];
     }
 
-    // Convert attributes
-    const props: Record<string, string> = {};
-    let withPlaceholders: Record<string, ASTNode[]> | undefined;
-    for (const attr of Array.from(el.attributes)) {
-      const parts = splitPlaceholderText(attr.value, ph);
-      if (parts.every((part) => typeof part === 'string')) {
-        props[attr.name] = attr.value;
-        continue;
-      }
-      withPlaceholders ??= {};
-      withPlaceholders[attr.name] = parts.map(
+    // Convert attributes, as author HTML's (see splitAttributes): markdown
+    // output holds raw HTML the passage tokenizer didn't take as a tag
+    const svg = el.namespaceURI === SVG_NAMESPACE;
+    const attributes: Attribute[] = [];
+    let placeholders: Record<string, ASTNode[]> | undefined;
+    for (const { name, value } of Array.from(el.attributes)) {
+      attributes.push([name, value, value]);
+      const parts = splitPlaceholderText(value, ph);
+      if (parts.every((part) => typeof part === 'string')) continue;
+      placeholders ??= {};
+      placeholders[name] = parts.map(
         (part): ASTNode =>
           typeof part === 'string'
             ? { type: 'text', value: part }
@@ -275,13 +319,26 @@ function convertDomNode(
       convertDomNode(child, i, ph),
     );
 
-    if (withPlaceholders) {
+    if (placeholders) {
       return (
         <PlaceholderAttributes
+          key={key}
+          tag={tag}
+          attributes={attributes}
+          placeholders={placeholders}
+          svg={svg}
+          children={children}
+        />
+      );
+    }
+    const { props, direct } = splitAttributes(attributes, svg);
+    if (direct.length > 0) {
+      return (
+        <DirectAttributes
           key={key}
           tag={tag}
           props={props}
-          attributes={withPlaceholders}
+          direct={direct}
           children={children}
         />
       );
@@ -395,9 +452,8 @@ function setRawAttribute(el: Element, name: string, value: string) {
     el.setAttribute(name, value);
     return;
   }
-  const template = document.createElement('template');
-  template.innerHTML = `<i ${name}=""></i>`;
-  const parsed = (template.content.firstChild as Element).attributes[0];
+  const parsed = (parseHtmlInert(`<i ${name}=""></i>`).firstChild as Element)
+    .attributes[0];
   if (!parsed) return;
   const attr = parsed.cloneNode() as Attr;
   attr.value = value;
@@ -422,7 +478,7 @@ function setRawAttribute(el: Element, name: string, value: string) {
  * `className` into `class`) are set directly instead.
  */
 function splitAttributes(
-  attributes: [name: string, value: string, written: string][],
+  attributes: Attribute[],
   svg: boolean,
 ): { props: Record<string, unknown>; direct: [string, string][] } {
   const props: Record<string, unknown> = {};
@@ -447,6 +503,27 @@ function splitAttributes(
   return { props, direct };
 }
 
+/**
+ * Set the attributes `splitAttributes` leaves to set directly on the element
+ * given the returned ref (none if there are none), and remove them again
+ * when they change.
+ */
+function useDirectAttributes(
+  direct: [string, string][],
+): RefObject<Element> | undefined {
+  const elementRef = useRef<Element>(null);
+  const directKey = JSON.stringify(direct);
+  useLayoutEffect(() => {
+    const el = elementRef.current;
+    if (!el || direct.length === 0) return;
+    for (const [name, value] of direct) setRawAttribute(el, name, value);
+    return () => {
+      for (const [name] of direct) el.removeAttribute(name);
+    };
+  }, [directKey]);
+  return direct.length > 0 ? elementRef : undefined;
+}
+
 const decodedAttributeText = new Map<string, string>();
 
 /**
@@ -457,10 +534,10 @@ function decodeAttributeText(text: string): string {
   if (!text.includes('&')) return text;
   let decoded = decodedAttributeText.get(text);
   if (decoded === undefined) {
-    const template = document.createElement('template');
-    template.innerHTML = `<i title="${text.replace(/"/g, '&quot;')}"></i>`;
+    const html = `<i title="${text.replace(/"/g, '&quot;')}"></i>`;
     decoded =
-      (template.content.firstChild as Element).getAttribute('title') ?? text;
+      (parseHtmlInert(html).firstChild as Element).getAttribute('title') ??
+      text;
     decodedAttributeText.set(text, decoded);
   }
   return decoded;
@@ -532,24 +609,11 @@ function HtmlNodeRenderer({ node }: { node: HtmlNode }) {
   const isRawRoot = !inRaw && (isSvgRoot || PREFORMATTED_ELEMENTS.has(tag));
   const errors: AttributeError[] = [];
   const resolved = Object.entries(node.attributes).map(
-    ([k, v]): [string, string, string] => [
-      k,
-      resolveAttributeValue(k, v, scope, errors),
-      v,
-    ],
+    ([k, v]): Attribute => [k, resolveAttributeValue(k, v, scope, errors), v],
   );
   const { props, direct } = splitAttributes(resolved, inSvg || isSvgRoot);
-  const elementRef = useRef<Element>(null);
-  const directKey = JSON.stringify(direct);
-  useLayoutEffect(() => {
-    const el = elementRef.current;
-    if (!el || direct.length === 0) return;
-    for (const [name, value] of direct) setRawAttribute(el, name, value);
-    return () => {
-      for (const [name] of direct) el.removeAttribute(name);
-    };
-  }, [directKey]);
-  if (direct.length > 0) props.ref = elementRef;
+  const ref = useDirectAttributes(direct);
+  if (ref) props.ref = ref;
   const isInline = INLINE_ELEMENTS.has(tag);
   // Inside SVG and preformatted elements, skip markdown processing entirely
   // (see RawTextContext).

package/src/parser.ts

@@ -1,3 +1,6 @@
+import { tokenize } from './markup/tokenizer';
+import { isCodeAttribute, splitSigilTemplate } from './markup/code-attributes';
+
 export interface Passage {
   pid: number;
   name: string;
@@ -18,25 +21,128 @@ export interface StoryData {
   userScript: string;
 }
 
+const HTML_NAMESPACE = 'http://www.w3.org/1999/xhtml';
+
+/** HTML elements written without content or end tag, as innerHTML does. */
+const VOID_ELEMENTS = new Set([
+  'area',
+  'base',
+  'basefont',
+  'bgsound',
+  'br',
+  'col',
+  'embed',
+  'frame',
+  'hr',
+  'img',
+  'input',
+  'keygen',
+  'link',
+  'meta',
+  'param',
+  'source',
+  'track',
+  'wbr',
+]);
+
 /**
- * Decode the HTML entities that browsers use when serializing innerHTML.
- * &amp; is decoded last to avoid double-decoding (e.g. &amp;lt; → &lt;, not <).
+ * The passage markup in the nodes of passage data.
+ *
+ * A compiler that HTML-escapes passage text (Twine, Tweego) leaves a text
+ * node whose text is the markup; a no-break space in it is U+00A0, which
+ * innerHTML writes as `&nbsp;`. One that doesn't escape it leaves the
+ * browser's parse of it, whose elements are written back as markup here.
+ * innerHTML did that too, but its escaping can't be undone: a `"` in an
+ * attribute value is written `&quot;`, and decoding that ends the value
+ * early, while text it leaves unescaped (in `<style>`, comments) would be
+ * decoded wrongly.
  */
-function decodeHtmlEntities(html: string): string {
-  return html
-    .replace(/&lt;/g, '<')
-    .replace(/&gt;/g, '>')
-    .replace(/&quot;/g, '"')
-    .replace(/&#39;/g, "'")
-    .replace(/&amp;/g, '&');
+function passageMarkup(parent: ParentNode): string {
+  let markup = '';
+  for (const node of Array.from(parent.childNodes)) {
+    if (node.nodeType === Node.TEXT_NODE) {
+      markup += (node as Text).data;
+    } else if (node.nodeType === Node.COMMENT_NODE) {
+      markup += `<!--${(node as Comment).data}-->`;
+    } else if (node.nodeType === Node.ELEMENT_NODE) {
+      markup += elementMarkup(node as Element);
+    }
+  }
+  return markup;
+}
+
+/** An element of passage data as markup (see passageMarkup). */
+function elementMarkup(el: Element): string {
+  const name = el.localName;
+  let markup = `<${name}`;
+  for (const attr of Array.from(el.attributes)) {
+    markup += ` ${attr.name}=${quoteAttribute(attr.name, attr.value)}`;
+  }
+  markup += '>';
+  if (el.namespaceURI === HTML_NAMESPACE && VOID_ELEMENTS.has(name)) {
+    return markup;
+  }
+  const content =
+    name === 'template' ? (el as HTMLTemplateElement).content : el;
+  return `${markup}${passageMarkup(content)}</${name}>`;
+}
+
+/**
+ * An attribute value quoted so that the passage tokenizer reads it back:
+ * in double quotes, else single ones, else with the double quotes in its
+ * text written as `&quot;`, which rendering decodes. Quotes inside markup in
+ * the value (`{print "a"}`) are code, and don't end it.
+ */
+function quoteAttribute(name: string, value: string): string {
+  const code = isCodeAttribute(name);
+  const probe = code ? 'on' : 'a';
+  const readsBack = (quoted: string) => {
+    const tokens = tokenize(`<i ${probe}=${quoted}>`);
+    const tag = tokens[0];
+    return (
+      tokens.length === 1 &&
+      tag?.type === 'html' &&
+      tag.attributes[probe] === quoted.slice(1, -1)
+    );
+  };
+  return (
+    [`"${value}"`, `'${value}'`].find(readsBack) ??
+    `"${escapeTextQuotes(value, code)}"`
+  );
+}
+
+/**
+ * `value` with the double quotes in its text written as `&quot;`, but not
+ * those in markup (`{print "a"}`) or, in a code attribute, in sigil
+ * references (see splitSigilTemplate), which are code.
+ */
+function escapeTextQuotes(value: string, code: boolean): string {
+  const escape = (text: string) => text.replace(/"/g, '&quot;');
+  if (code) {
+    return splitSigilTemplate(value)
+      .map((part) =>
+        'text' in part
+          ? escape(part.text)
+          : 'expr' in part
+            ? `{${part.expr}}`
+            : part.verbatim,
+      )
+      .join('');
+  }
+  return tokenize(value, { text: true })
+    .map((token) => {
+      const source = value.slice(token.start, token.end);
+      return token.type === 'text' ? escape(source) : source;
+    })
+    .join('');
 }
 
 /**
  * Parse <tw-storydata> and all <tw-passagedata> elements from the DOM.
  *
- * Uses innerHTML + entity decoding instead of textContent so that HTML
- * tags inside passage markup (e.g. <div> inside {button}) are preserved
- * regardless of whether the compiler HTML-encoded them.
+ * Passage content is read with passageMarkup instead of textContent, so
+ * that HTML tags inside passage markup (e.g. <div> inside {button}) are
+ * preserved whether or not the compiler HTML-encoded them.
  */
 export function parseStoryData(): StoryData {
   const storyEl = document.querySelector('tw-storydata');
@@ -67,7 +173,7 @@ export function parseStoryData(): StoryData {
     const tags = (el.getAttribute('tags') || '')
       .split(/\s+/)
       .filter((t) => t.length > 0);
-    const content = decodeHtmlEntities(el.innerHTML);
+    const content = passageMarkup(el);
 
     const metadata: Record<string, string> = {};
     const skipAttrs = new Set(['pid', 'name', 'tags']);

package/src/runtime-errors.ts

@@ -0,0 +1,65 @@
+// Runtime errors shown to the player on the page (see RuntimeErrors), for
+// errors that would otherwise only reach the browser console.
+
+import { errorMessage } from './utils/error-message';
+
+/** A runtime error shown on the page until the player dismisses it. */
+export interface RuntimeError {
+  /** Identifies the entry, for dismissing it. */
+  id: number;
+  /** What failed, for the player (e.g. "Could not save the game…"). */
+  context: string;
+  /** The error message, without the "spindle: " prefix. */
+  message: string;
+  /** How often the same error happened since it was shown. */
+  count: number;
+}
+
+let errors: readonly RuntimeError[] = [];
+let nextId = 1;
+const listeners = new Set<() => void>();
+
+function update(next: readonly RuntimeError[]): void {
+  errors = next;
+  for (const listener of listeners) listener();
+}
+
+/**
+ * Show `error` on the page, after `context` (what failed). The same error
+ * again, while it is shown, counts up instead of adding an entry. Logging
+ * it to the console is up to the caller.
+ */
+export function showRuntimeError(context: string, error: unknown): void {
+  const message = errorMessage(error).replace(/^spindle: /, '');
+  const same = errors.find(
+    (e) => e.context === context && e.message === message,
+  );
+  update(
+    same
+      ? errors.map((e) => (e === same ? { ...e, count: e.count + 1 } : e))
+      : [...errors, { id: nextId++, context, message, count: 1 }],
+  );
+}
+
+/** Remove the shown error `id`. */
+export function dismissRuntimeError(id: number): void {
+  update(errors.filter((e) => e.id !== id));
+}
+
+/** Remove every shown error. */
+export function clearRuntimeErrors(): void {
+  if (errors.length) update([]);
+}
+
+/** The errors shown now, oldest first. */
+export function getRuntimeErrors(): readonly RuntimeError[] {
+  return errors;
+}
+
+/** Call `listener` whenever the shown errors change; returns unsubscribe. */
+export function subscribeRuntimeErrors(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}