@rohal12/spindle 0.58.0 → 0.59.1

package/package.json

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

package/src/automation/runner.ts

@@ -8,6 +8,7 @@ import type {
 import type { StoryAPI } from '../story-api';
 import type { StoryAction } from '../action-registry';
 import { errorMessage } from '../utils/error-message';
+import { deepEqual } from '../structural';
 
 export interface RunOptions {
   onStep?: (stepIndex: number, step: AutomationStep) => void;
@@ -88,7 +89,7 @@ async function executeStep(
     if (assert.variables) {
       for (const [key, expected] of Object.entries(assert.variables)) {
         const actual = story.get(key);
-        if (actual !== expected) {
+        if (!deepEqual(actual, expected)) {
           errors.push({
             step: index,
             message: `Variable "${key}": expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`,

package/src/code-check.ts

@@ -8,18 +8,20 @@
  * - `{$…}` expressions, and `{do}` bodies (statements);
  * - the conditions of `{if}`, `{elseif}` and `{case}`;
  * - macro arguments whose declared parameter type is `expression`,
- *   `statements` or `passage`, built-in and custom macros alike; the
- *   condition and `run` action of `{watch}`, code in quoted strings;
+ *   `statements` or `passage`, built-in and custom macros alike, and the
+ *   `string` and `text` arguments that hold code (ParameterDef.holds: the
+ *   condition and `run` action of `{watch}`);
  * - the `{$…}` references in attributes holding code (`onclick`).
  *
- * Text that may hold markup is found in quoted labels (arguments of type
- * `text` and `string`) and HTML attribute values; the check reads its
- * markup in turn.
+ * Text that may hold markup is found in the `string` and `text` arguments
+ * that hold markup (labels such as `{button}`'s) and HTML attribute values;
+ * the check reads its markup in turn.
  *
  * Passage names written out are found in links (`[[Go->Hall]]`), in
  * `passage` arguments that are one quoted string (`{goto "Hall"}`), in the
- * passage of `{link}`, the `goto` and `dialog` actions of `{watch}` and the
- * body of `{dialog}`; the check looks each one up.
+ * `string` and `text` arguments that hold a passage name (the `goto` and
+ * `dialog` actions of `{watch}`) and in the body of `{dialog}`; the check
+ * looks each one up.
  *
  * The arguments of macros that declare no parameters may be anything:
  * they are not checked.
@@ -28,13 +30,16 @@ import type { Token } from './markup/tokens';
 import { isCodeAttribute, splitSigilTemplate } from './markup/code-attributes';
 import { CodeSyntaxError, parseCode, type JsGoal } from './js-lexer';
 import type { ParsedCode } from './js-lexer';
-import type { ParameterDef } from './registry';
+import type { ParameterDef, StringHolds } from './registry';
 import {
   MacroArgumentError,
   parseMacroArgs,
   passageTarget,
+  type ArgSpans,
   type PassageTarget,
 } from './components/macros/macro-args';
+import { subMacroParameters } from './components/macros/option-utils';
+import { NameMap } from './utils/macro-names';
 
 /** While a pass runs: the code it parsed so far, by goal and source. */
 let parses: Map<string, ParsedCode | CodeSyntaxError> | null = null;
@@ -79,7 +84,10 @@ export interface CodePiece {
   goal: JsGoal;
   /** The markup it is in, for the error: `{print $a +}`. */
   label: string;
-  /** Whether it names a passage: a `passage` argument. */
+  /**
+   * Whether it names a passage: a `passage` argument that is an
+   * expression (one that is a string literal is a PassagePiece).
+   */
   passage?: boolean;
   /** Whether it is the code in a quoted string, as in `{watch}`. */
   inString?: boolean;
@@ -94,7 +102,7 @@ export interface PassagePiece {
   offset: number;
   /** The markup it is in, for the error: `[[Go->Hall]]`. */
   label: string;
-  /** How much of the markup is the name, as written. */
+  /** How much of the markup is the name, as written (quotes included). */
   length: number;
   /** The macro it is the argument of; `link` for `[[…]]` links. */
   macro: string;
@@ -121,30 +129,78 @@ export interface TextPiece {
 /** Macros whose whole argument text is one expression: branch conditions. */
 const CONDITION_MACROS = new Set(['if', 'elseif', 'case']);
 
-/** Code inside the quoted strings of a macro's arguments, by parameter. */
-const CODE_IN_STRINGS: ReadonlyMap<string, Record<string, JsGoal>> = new Map([
-  ['watch', { condition: 'expression', run: 'statements' }],
-]);
+/** Block macros whose body is the name of a passage. */
+const PASSAGE_BODIES = new Set(['dialog']);
 
-/** The `string` parameters of a macro that name a passage. */
-const PASSAGE_STRINGS: ReadonlyMap<string, readonly string[]> = new Map([
-  ['watch', ['goto', 'dialog']],
-]);
+type Piece = CodePiece | TextPiece | PassagePiece | ArgumentErrorPiece;
+
+/** The declared parameters of a macro, if it has any. */
+export type ParametersOf = (
+  macro: string,
+) => readonly ParameterDef[] | undefined;
+
+/** What the argument check needs to know of a macro (see MacroMetadata). */
+export interface MacroParameters {
+  name: string;
+  parameters?: readonly ParameterDef[];
+  interpolate?: boolean;
+}
 
 /**
- * The `text` and `string` parameters of a macro that the runtime keeps as
- * written, not as markup: an option's value, the name of a watcher.
+ * `params` with each `string` and `text` parameter (options too) saying
+ * what it holds: what it declares, else `holds`.
  */
-const LITERAL_STRINGS: ReadonlyMap<string, readonly string[]> = new Map([
-  ['option', ['value']],
-  ['watch', ['name']],
-  ['unwatch', ['name']],
-]);
+function withHolds(
+  params: readonly ParameterDef[],
+  holds: StringHolds,
+): readonly ParameterDef[] {
+  return params.map((param) => {
+    if (param.parameters) {
+      return { ...param, parameters: withHolds(param.parameters, holds) };
+    }
+    const isString = param.type === 'string' || param.type === 'text';
+    return isString && !param.holds ? { ...param, holds } : param;
+  });
+}
 
-/** Block macros whose body is the name of a passage. */
-const PASSAGE_BODIES = new Set(['dialog']);
+/**
+ * The declared parameters of `macros`, by name in any case, and of the
+ * built-in sub-macros (`{option}`): what the story-start check, reference
+ * collection and tooling read arguments by. Each `string` and `text`
+ * parameter says what it holds: what it declares, else `markup` for a macro
+ * with `interpolate` (which can resolve markup) and `text` for any other.
+ */
+export function parameterLookup(
+  macros: Iterable<MacroParameters>,
+): ParametersOf {
+  const parameters = new NameMap<readonly ParameterDef[]>();
+  for (const { name, parameters: params, interpolate } of macros) {
+    if (params)
+      parameters.set(name, withHolds(params, holdsByDefault(interpolate)));
+  }
+  return (name) => {
+    let params = parameters.get(name);
+    if (!params) {
+      const sub = subMacroParameters(name);
+      if (sub) parameters.set(name, (params = withHolds(sub, 'text')));
+    }
+    return params;
+  };
+}
 
-type Piece = CodePiece | TextPiece | PassagePiece | ArgumentErrorPiece;
+/** What a `string` or `text` argument holds when its parameter doesn't say. */
+const holdsByDefault = (interpolate: boolean | undefined): StringHolds =>
+  interpolate ? 'markup' : 'text';
+
+/** Whether a parameter in `params` (options too) holds code in a string. */
+export function holdsCode(params: readonly ParameterDef[]): boolean {
+  return params.some(
+    (p) =>
+      p.holds === 'expression' ||
+      p.holds === 'statements' ||
+      (!!p.parameters && holdsCode(p.parameters)),
+  );
+}
 
 /** The goal of the code an argument of this type holds, if it is code. */
 function codeGoal(param: ParameterDef): JsGoal | undefined {
@@ -155,6 +211,15 @@ function codeGoal(param: ParameterDef): JsGoal | undefined {
   return undefined;
 }
 
+/**
+ * What a `string` or `text` argument holds: what its parameter says (see
+ * parameterLookup), else markup, which is checked.
+ */
+function stringHolds(param: ParameterDef): StringHolds | undefined {
+  if (param.type !== 'string' && param.type !== 'text') return undefined;
+  return param.holds ?? 'markup';
+}
+
 /**
  * The code and the markup-holding text in `tokens`, the tokens of `src`.
  * `parametersOf` gives the declared parameters of a macro, if it has any.
@@ -162,7 +227,7 @@ function codeGoal(param: ParameterDef): JsGoal | undefined {
 export function* codeAndText(
   src: string,
   tokens: readonly Token[],
-  parametersOf: (macro: string) => readonly ParameterDef[] | undefined,
+  parametersOf: ParametersOf,
 ): Generator<Piece> {
   /** The index of the closing tag of the `name` macro opened at `t`. */
   const closeOf = (t: number, name: string) =>
@@ -179,8 +244,8 @@ export function* codeAndText(
       yield {
         kind: 'passage',
         name: token.target,
-        offset: locate(src, token.target, token.start),
-        length: token.target.length,
+        offset: token.targetStart,
+        length: token.targetEnd - token.targetStart,
         macro: 'link',
         label: src.slice(token.start, token.end),
       };
@@ -193,9 +258,11 @@ export function* codeAndText(
         label: `{${token.expression}}`,
       };
     } else if (token.type === 'html') {
+      // The values are the source text between their quotes, in order
+      let cursor = token.start;
       for (const [name, value] of Object.entries(token.attributes)) {
-        // The value is the source text between its quotes
-        const at = locate(src, value, token.start);
+        const at = locate(src, value, cursor);
+        cursor = at + value.length;
         if (!isCodeAttribute(name)) {
           yield {
             kind: 'text',
@@ -242,12 +309,12 @@ export function* codeAndText(
         const body = tokens.slice(t + 1, close);
         if (close > t + 1 && body.every((b) => b.type === 'text')) {
           const text = src.slice(token.end, tokens[close]!.start);
-          const passage = text.trim().replace(/^["']|["']$/g, '');
+          const written = text.trim();
           yield {
             kind: 'passage',
-            name: passage,
-            offset: locate(src, passage, token.end),
-            length: passage.length,
+            name: written.replace(/^["']|["']$/g, ''),
+            offset: token.end + text.indexOf(written),
+            length: written.length,
             macro: name,
             label: src.slice(token.start, token.end),
           };
@@ -255,7 +322,9 @@ export function* codeAndText(
       }
       if (!args) continue;
       const label = `{${token.name} ${args}}`;
-      const argsAt = locate(src, args, token.start + 1);
+      // The arguments end the tag, but for the whitespace before its }
+      const tag = src.slice(token.start, token.end - 1);
+      const argsAt = token.start + tag.trimEnd().length - args.length;
       if (CONDITION_MACROS.has(name)) {
         yield {
           kind: 'code',
@@ -281,18 +350,15 @@ export function* argPieces(
   label: string,
 ): Generator<Piece> {
   let values: Record<string, unknown>;
+  const spans: ArgSpans = new Map();
   try {
-    values = parseMacroArgs(args, params) as Record<string, unknown>;
+    values = parseMacroArgs(args, params, spans) as Record<string, unknown>;
   } catch (error) {
     if (!(error instanceof MacroArgumentError)) throw error;
     yield { kind: 'argument-error', message: error.message, offset, label };
     return;
   }
-  const key = macro.toLowerCase();
-  const inStrings = CODE_IN_STRINGS.get(key) ?? {};
-  const passageStrings = PASSAGE_STRINGS.get(key) ?? [];
-  const literalStrings = LITERAL_STRINGS.get(key) ?? [];
-  let cursor = 0;
+  const name = macro.toLowerCase();
   /** The pieces of the parameters `list`, with their values in `from`. */
   function* visit(
     list: readonly ParameterDef[],
@@ -307,58 +373,70 @@ export function* argPieces(
         );
         continue;
       }
-      if (typeof value !== 'string' || !value.trim()) continue;
-      const at = locate(args, value, cursor);
-      if (at >= cursor) cursor = at + value.length;
-      const goal = codeGoal(param) ?? inStrings[param.name];
+      const span = spans.get(param);
+      if (typeof value !== 'string' || !value.trim() || !span) continue;
+      const [start, end] = span;
+      const written = args.slice(start, end);
+      /** The name as written (quotes included), at the argument. */
+      const passage = (passageName: string): PassagePiece => ({
+        kind: 'passage',
+        name: passageName,
+        offset: offset + start,
+        length: end - start,
+        macro: name,
+        label,
+      });
+      const goal = codeGoal(param);
+      if (param.type === 'passage') {
+        // A name written out, else an expression naming one
+        const target = passageTarget(value);
+        if (target.kind === 'name') {
+          yield passage(target.name);
+          continue;
+        }
+      }
       if (goal) {
         const piece: CodePiece = {
           kind: 'code',
           code: value,
-          offset: offset + at,
+          offset: offset + start,
           goal,
           label,
         };
         if (param.type === 'passage') {
           piece.passage = true;
-          piece.macro = macro.toLowerCase();
+          piece.macro = name;
         }
-        if (!codeGoal(param)) piece.inString = true;
         yield piece;
+        continue;
       }
-      // A passage written out: a quoted `passage` argument, or a string
-      const written = param.type === 'passage' ? value.trim() : value;
-      const target =
-        param.type === 'passage'
-          ? passageTarget(value)
-          : passageStrings.includes(param.name)
-            ? ({ kind: 'name', name: value } as const)
-            : null;
-      if (target?.kind === 'name') {
+      // The value of a string is inside its quotes
+      const at =
+        offset + start + (value !== written && /^["']/.test(written) ? 1 : 0);
+      const holds = stringHolds(param);
+      if (holds === 'expression' || holds === 'statements') {
         yield {
-          kind: 'passage',
-          name: target.name,
-          offset: offset + at + value.indexOf(written),
-          length: written.length,
-          macro: macro.toLowerCase(),
+          kind: 'code',
+          code: value,
+          offset: at,
+          goal: holds,
           label,
+          inString: true,
         };
-      }
-      if (
-        !goal &&
-        (param.type === 'text' || param.type === 'string') &&
-        !literalStrings.includes(param.name)
-      ) {
+      } else if (holds === 'passage') {
+        yield passage(value);
+      } else if (holds === 'markup') {
         yield {
           kind: 'text',
           text: value,
-          offset: offset + at,
+          offset: at,
           where: `In the ${param.name} of {${macro}}: `,
         };
       }
     }
   }
-  yield* visit(params, values);
+  // Options are visited in metadata order, which is not the order written
+  yield* [...visit(params, values)].sort((a, b) => a.offset - b.offset);
 }
 
 /**
@@ -387,14 +465,15 @@ export interface PassageReference {
  * The passages the markup `src` (with the `tokens` it tokenizes to) names:
  * `[[…]]` links, the passage argument of `{goto}`, `{include}` and `{link}`
  * (and of macros that declare one), the `goto` and `dialog` actions of
- * `{watch}` and the body of `{dialog}`, in source order. A name written out
- * is a literal; the others are expressions, which name a passage when they
- * run.
+ * `{watch}` (and the `string` and `text` arguments of macros that declare
+ * they hold one) and the body of `{dialog}`, in source order. A name written
+ * out is a literal; the others are expressions, which name a passage when
+ * they run.
  */
 export function collectPassageReferences(
   src: string,
   tokens: readonly Token[],
-  parametersOf: (macro: string) => readonly ParameterDef[] | undefined,
+  parametersOf: ParametersOf,
 ): PassageReference[] {
   const refs: PassageReference[] = [];
   for (const piece of codeAndText(src, tokens, parametersOf)) {
@@ -408,15 +487,11 @@ export function collectPassageReferences(
     } else if (piece.kind === 'code' && piece.passage) {
       refs.push({
         macro: piece.macro!,
-        target: passageTarget(piece.code),
+        target: { kind: 'expression', expression: piece.code },
         start: piece.offset,
         end: piece.offset + piece.code.length,
       });
     }
   }
-  return refs.filter(
-    (ref, i) =>
-      refs.findIndex((r) => r.start === ref.start && r.macro === ref.macro) ===
-      i,
-  );
+  return refs;
 }

package/src/components/macros/Button.tsx

@@ -5,7 +5,9 @@ defineMacro({
   name: 'button',
   block: true,
   interpolate: true,
-  parameters: [{ name: 'label', type: 'text', required: true }],
+  parameters: [
+    { name: 'label', type: 'text', holds: 'markup', required: true },
+  ],
   render({ rawArgs, children = [] }, ctx) {
     const label = ctx.resolve?.(ctx.args.label ?? '') ?? rawArgs;
     const runBody = useDetachedBody();

package/src/components/macros/Checkbox.tsx

@@ -4,7 +4,10 @@ import { VARIABLE_PARAMETER, useVariableAction } from './input-macro';
 defineMacro({
   name: 'checkbox',
   storeVar: true,
-  parameters: [VARIABLE_PARAMETER, { name: 'label', type: 'text' }],
+  parameters: [
+    VARIABLE_PARAMETER,
+    { name: 'label', type: 'text', holds: 'text' },
+  ],
   render(_props, ctx) {
     const label = ctx.args.label ?? '';
 

package/src/components/macros/Dialog.tsx

@@ -6,7 +6,7 @@ defineMacro({
   block: true,
   interpolate: true,
   parameters: [
-    { name: 'label', type: 'text', required: true },
+    { name: 'label', type: 'text', holds: 'markup', required: true },
     { name: 'noclose', type: 'flag' },
   ],
   render({ children = [] }, ctx) {

package/src/components/macros/MacroLink.tsx

@@ -12,11 +12,12 @@ defineMacro({
   // {link "text" passage} or {link "text"}; the passage is a quoted name or
   // an expression, as in {goto}.
   parameters: [
-    { name: 'text', type: 'string', required: true },
+    { name: 'text', type: 'string', holds: 'markup', required: true },
     { name: 'passage', type: 'passage' },
   ],
   render({ children = [] }, ctx) {
-    const display = ctx.args.text ?? '';
+    // The label is markup: resolved once, for the element and its action
+    const display = ctx.resolve?.(ctx.args.text ?? '') ?? '';
     let passage: string | null = null;
     // Boxed: anything can be thrown, including null and other falsy values
     let failure: { error: unknown } | undefined;

package/src/components/macros/Meter.tsx

@@ -40,11 +40,15 @@ defineMacro({
   parameters: [
     { name: 'current', type: 'expression', required: true },
     { name: 'max', type: 'expression', required: true },
-    { name: 'label', type: 'string' },
+    { name: 'label', type: 'string', holds: 'markup' },
   ],
   render(_props, ctx) {
     try {
-      const { currentExpr, maxExpr, labelMode } = meterArgs(ctx.args);
+      const { currentExpr, maxExpr, labelMode } = meterArgs({
+        ...ctx.args,
+        // The label is markup: resolved before reading none, % or a unit
+        label: ctx.resolve?.(ctx.args.label),
+      });
       const current = Number(ctx.evaluate!(currentExpr));
       const max = Number(ctx.evaluate!(maxExpr));
       const pct =

package/src/components/macros/Radiobutton.tsx

@@ -6,8 +6,8 @@ defineMacro({
   storeVar: true,
   parameters: [
     VARIABLE_PARAMETER,
-    { name: 'value', type: 'text', required: true },
-    { name: 'label', type: 'text' },
+    { name: 'value', type: 'text', holds: 'text', required: true },
+    { name: 'label', type: 'text', holds: 'text' },
   ],
   render(_props, ctx) {
     const radioValue = ctx.args.value ?? '';

package/src/components/macros/Watch.tsx

@@ -5,15 +5,20 @@ defineMacro({
   name: 'watch',
   // {watch "condition" goto "X" dialog "X" run "X" name "X" priority N once}
   parameters: [
-    { name: 'condition', type: 'string', required: true },
+    {
+      name: 'condition',
+      type: 'string',
+      holds: 'expression',
+      required: true,
+    },
     {
       name: 'options',
       type: 'options',
       parameters: [
-        { name: 'goto', type: 'string' },
-        { name: 'dialog', type: 'string' },
-        { name: 'run', type: 'string' },
-        { name: 'name', type: 'string' },
+        { name: 'goto', type: 'string', holds: 'passage' },
+        { name: 'dialog', type: 'string', holds: 'passage' },
+        { name: 'run', type: 'string', holds: 'statements' },
+        { name: 'name', type: 'string', holds: 'text' },
         { name: 'priority', type: 'number' },
         { name: 'once', type: 'flag' },
       ],
@@ -41,7 +46,7 @@ defineMacro({
 
 defineMacro({
   name: 'unwatch',
-  parameters: [{ name: 'name', type: 'text', required: true }],
+  parameters: [{ name: 'name', type: 'text', holds: 'text', required: true }],
   render(_props, ctx) {
     const name = ctx.args.name ?? '';
 

package/src/components/macros/arg-utils.ts

@@ -69,43 +69,6 @@ export function readWholeQuoted(src: string): string | null {
   return quoted && quoted.end === src.length ? quoted.value : null;
 }
 
-const JS_SIMPLE_ESCAPES: Record<string, string> = {
-  n: '\n',
-  t: '\t',
-  r: '\r',
-  b: '\b',
-  f: '\f',
-  v: '\v',
-  '0': '\0',
-};
-
-/** Undo every escape of a JavaScript string literal's body. */
-function decodeJsEscapes(body: string): string {
-  return body.replace(
-    /\\(?:u\{([0-9a-fA-F]+)\}|u([0-9a-fA-F]{4})|x([0-9a-fA-F]{2})|(\r\n|[\n\r\u2028\u2029])|([\s\S]))/g,
-    (_, braced, unicode, hex, lineBreak, other: string | undefined) => {
-      if (lineBreak !== undefined) return '';
-      const code = braced ?? unicode ?? hex;
-      if (code !== undefined) {
-        const point = parseInt(code, 16);
-        return point <= 0x10ffff ? String.fromCodePoint(point) : '';
-      }
-      return JS_SIMPLE_ESCAPES[other!] ?? other!;
-    },
-  );
-}
-
-/**
- * The value of `src` when it is exactly one `"…"` or `'…'` string, read as
- * the JavaScript literal it is (`"\u0048all"` is `Hall`), otherwise `null`.
- * `readWholeQuoted` keeps other escapes as written, for labels and code.
- */
-export function readWholeJsString(src: string): string | null {
-  const quoted = readQuoted(src, 0);
-  if (!quoted || quoted.end !== src.length) return null;
-  return decodeJsEscapes(src.slice(1, -1));
-}
-
 /**
  * Strip an optional quote from each end of an unquoted-or-loosely-quoted
  * argument (`"Red`, `Red'`), leaving at least one character. This is the

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

@@ -46,7 +46,10 @@ export function defineInputMacro(
   defineMacro({
     name,
     storeVar: true,
-    parameters: [VARIABLE_PARAMETER, { name: 'placeholder', type: 'string' }],
+    parameters: [
+      VARIABLE_PARAMETER,
+      { name: 'placeholder', type: 'string', holds: 'text' },
+    ],
     render(_props, ctx) {
       const placeholder = ctx.args.placeholder ?? '';