@rohal12/spindle 0.59.17 → 0.59.18

package/dist/pkg/story-variables.js

@@ -151,7 +151,11 @@ function lexeme(lex, loc, fields) {
 /** The AST node of a lexeme that stands alone (not a macro or element). */
 function nodeOf(x) {
 	switch (x.lex) {
-		case "text": return {
+		case "text": return x.comment ? {
+			type: "text",
+			value: x.value,
+			comment: true
+		} : {
 			type: "text",
 			value: x.value
 		};
@@ -223,7 +227,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 = [];
@@ -231,7 +235,7 @@ function joinText(items, convert) {
 	const add = (item) => {
 		if (item === null || item === void 0) 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;
@@ -725,7 +729,9 @@ function peg$parse(input, options) {
 		return lexeme("text", location(), { value });
 	}
 	function peg$f41(value) {
-		return lexeme("text", location(), { value });
+		const node = lexeme("text", location(), { value });
+		node.comment = true;
+		return node;
 	}
 	function peg$f42(bs) {
 		return bs.length % 2 === 1;
@@ -10586,70 +10592,6 @@ function evaluatePassageName(expr, evaluate, { storyData, currentPassage }) {
 	if (storyData && !storyData.passages.has(name)) throw noPassageError(name, currentPassage);
 	return name;
 }
-//#endregion
-//#region src/widgets/widget-def.ts
-/**
-* Reading widget definitions without rendering anything: the `{widget}`
-* macro, startup and markup validation (also in tooling) share these.
-*/
-/** A {widget} definition's name, then its `@` parameters. */
-var WIDGET_PARAMETERS = [{
-	name: "name",
-	type: "text",
-	holds: "text",
-	required: true
-}, {
-	name: "parameters",
-	type: "text",
-	holds: "text"
-}];
-/**
-* The widget a {widget} definition's arguments declare: its name and its
-* parameters, the words after it that start with `@` (docs/widgets.md).
-* Other words, such as `$name`, are not parameters.
-*/
-function widgetDef({ name = "", parameters = "" }) {
-	return {
-		name,
-		params: parameters.split(/\s+/).filter((word) => word.startsWith("@"))
-	};
-}
-/** Read the arguments of a {widget} definition (see widgetDef). */
-function parseWidgetDef(rawArgs) {
-	return widgetDef(parseMacroArgs(rawArgs, WIDGET_PARAMETERS));
-}
-/**
-* 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).
-*/
-function blockWidgetNames(passages) {
-	const names = [];
-	for (const passage of passages) {
-		if (passage.name !== "StoryInit" && !passage.tags?.includes("widget")) continue;
-		const open = [];
-		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 {}
-		} else if (token.type === "variable" && token.scope === "local" && token.name === "children" && open.length > 0) open[open.length - 1].isBlock = true;
-	}
-	return names;
-}
 /** The parameters of the built-in sub-macros that take arguments. */
 var SUB_MACRO_PARAMETERS = new Map([["option", [{
 	name: "value",
@@ -10983,6 +10925,214 @@ function collectPassageReferences(src, tokens, parametersOf) {
 	});
 	return refs;
 }
+new NameMap();
+new NameMap();
+new NameSet();
+/**
+* How a macro argument is read (see components/macros/macro-args.ts). Every
+* declared parameter names one: there is no default.
+* Quoted strings accept `\"`, `\'` and `\\` escapes.
+* - `expression`: code, as written.
+* - `statements`: code run as statements (`{set}`), as written.
+* - `passage`: a passage name: a quoted string or an expression, as written.
+* - `variable`: a variable reference such as `$name` or `"$name"`, as written.
+* - `string`: one quoted string; anything else leaves the argument unset.
+* - `text`: one quoted string, or text with any loose quotes stripped.
+* - `names`: a comma-separated list of names (`@item, @i`).
+* - `delay`: a duration (`2s`, `500ms`, `300`) in milliseconds.
+* - `number`: a number.
+* - `flag`: a keyword, the parameter's name, at the start or end; a boolean.
+* - `separator`: a word (`of`) or `=` separating the parameters before it
+*   from those after it; a boolean.
+* - `options`: keywords, the names of its `parameters`, each followed by a
+*   quoted string or a number unless it is a flag.
+*/
+var PARAMETER_TYPES = [
+	"expression",
+	"statements",
+	"passage",
+	"variable",
+	"string",
+	"text",
+	"names",
+	"delay",
+	"number",
+	"flag",
+	"separator",
+	"options"
+];
+/**
+* What the value of a `string` or `text` argument holds, for the check at
+* story start and for tooling (see code-check.ts):
+* - `markup`: markup the macro renders (`{button}`'s label): its markup
+*   is checked.
+* - `text`: plain text the macro uses as written (`{checkbox}`'s label).
+* - `passage`: a passage name (`{watch}`'s `goto`): the passage must exist.
+* - `expression`, `statements`: code (`{watch}`'s condition and `run`): it
+*   is checked as code, and its variable references against the schema.
+*
+* Without it, the argument of a macro with `interpolate` holds `markup`,
+* any other `text`.
+*/
+var STRING_HOLDS = [
+	"markup",
+	"text",
+	"passage",
+	"expression",
+	"statements"
+];
+/**
+* Throw if a parameter `macro` declares (or an option of one) has no type,
+* or one that isn't a ParameterType: arguments are read by their type, and
+* there is no default. Throw too if it declares what it `holds` wrongly.
+*/
+function checkParameterTypes(macro, parameters) {
+	const holdsFix = `Give a \`string\` or \`text\` parameter one of ${STRING_HOLDS.join(", ")} to hold (see docs/custom-macros.md#what-a-string-holds).`;
+	for (const param of parameters) {
+		const type = param.type;
+		if (!PARAMETER_TYPES.includes(type)) throw parameterError(macro, param, type === void 0 ? "has no type" : `has the unknown type ${JSON.stringify(type)}`, `Give it one of the types ${PARAMETER_TYPES.join(", ")} (see docs/custom-macros.md#parameter-types), or declare no parameters and read props.rawArgs.`);
+		const holds = param.holds;
+		if (holds !== void 0 && type !== "string" && type !== "text") throw parameterError(macro, param, `is of the type ${type}, which holds what it is`, holdsFix);
+		if (holds !== void 0 && !STRING_HOLDS.includes(holds)) throw parameterError(macro, param, `holds the unknown ${JSON.stringify(holds)}`, holdsFix);
+		if (param.parameters) checkParameterTypes(macro, param.parameters);
+	}
+}
+/** The error for the parameter `param` of `macro`: what is wrong, and the fix. */
+function parameterError(macro, param, problem, fix) {
+	return /* @__PURE__ */ new Error(`spindle: The parameter "${param.name}" of the macro {${macro}} ${problem}. ${fix}`);
+}
+var metadataRegistry = new NameMap();
+function getMacroRegistry() {
+	return Array.from(metadataRegistry.values());
+}
+//#endregion
+//#region src/widgets/ast-scanner.ts
+/** The declared parameters of the macros registered so far. */
+var registeredParameters = (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, parametersOf) {
+	if (!text.includes("{")) return false;
+	let nodes;
+	try {
+		nodes = parseMarkup(text, { text: true });
+	} catch {
+		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.
+*/
+function tokenTextContainsChildren(token, parametersOf = registeredParameters) {
+	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), in the content and in
+* the attributes and labels that render markup.
+*/
+function astContainsChildren(nodes, parametersOf = registeredParameters) {
+	for (const node of nodes) {
+		if (node.type === "variable" && node.scope === "local" && node.name === "children") return true;
+		if (node.type === "html") {
+			const span = {
+				start: 0,
+				end: 0
+			};
+			if (tokenTextContainsChildren({
+				isClose: false,
+				isSelfClose: false,
+				...node,
+				...span
+			}, parametersOf) || astContainsChildren(node.children, parametersOf)) return true;
+		}
+		if (node.type === "macro") {
+			const span = {
+				start: 0,
+				end: 0
+			};
+			if (tokenTextContainsChildren({
+				isClose: false,
+				...node,
+				...span
+			}, parametersOf) || astContainsChildren(node.children, parametersOf)) return true;
+			if (node.branches) {
+				for (const branch of node.branches) if (astContainsChildren(branch.children, parametersOf)) return true;
+			}
+		}
+	}
+	return false;
+}
+//#endregion
+//#region src/widgets/widget-def.ts
+/**
+* Reading widget definitions without rendering anything: the `{widget}`
+* macro, startup and markup validation (also in tooling) share these.
+*/
+/** A {widget} definition's name, then its `@` parameters. */
+var WIDGET_PARAMETERS = [{
+	name: "name",
+	type: "text",
+	holds: "text",
+	required: true
+}, {
+	name: "parameters",
+	type: "text",
+	holds: "text"
+}];
+/**
+* The widget a {widget} definition's arguments declare: its name and its
+* parameters, the words after it that start with `@` (docs/widgets.md).
+* Other words, such as `$name`, are not parameters.
+*/
+function widgetDef({ name = "", parameters = "" }) {
+	return {
+		name,
+		params: parameters.split(/\s+/).filter((word) => word.startsWith("@"))
+	};
+}
+/** Read the arguments of a {widget} definition (see widgetDef). */
+function parseWidgetDef(rawArgs) {
+	return widgetDef(parseMacroArgs(rawArgs, WIDGET_PARAMETERS));
+}
+/**
+* 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).
+*/
+function blockWidgetNames(passages, parametersOf = registeredParameters) {
+	const names = [];
+	for (const passage of passages) {
+		if (passage.name !== "StoryInit" && !passage.tags?.includes("widget")) continue;
+		const open = [];
+		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 {}
+		} else if (open.length > 0 && (token.type === "variable" && token.scope === "local" && token.name === "children" || tokenTextContainsChildren(token, parametersOf))) open[open.length - 1].isBlock = true;
+	}
+	return names;
+}
 //#endregion
 //#region src/markup/validate.ts
 /**
@@ -11157,83 +11307,6 @@ function validateMarkup(passages, options) {
 	for (const [passage, tokens] of parsed) withParseCache(() => checkTokens(passage, passage.content, tokens, 0, ""));
 	return diagnostics;
 }
-new NameMap();
-new NameMap();
-new NameSet();
-/**
-* How a macro argument is read (see components/macros/macro-args.ts). Every
-* declared parameter names one: there is no default.
-* Quoted strings accept `\"`, `\'` and `\\` escapes.
-* - `expression`: code, as written.
-* - `statements`: code run as statements (`{set}`), as written.
-* - `passage`: a passage name: a quoted string or an expression, as written.
-* - `variable`: a variable reference such as `$name` or `"$name"`, as written.
-* - `string`: one quoted string; anything else leaves the argument unset.
-* - `text`: one quoted string, or text with any loose quotes stripped.
-* - `names`: a comma-separated list of names (`@item, @i`).
-* - `delay`: a duration (`2s`, `500ms`, `300`) in milliseconds.
-* - `number`: a number.
-* - `flag`: a keyword, the parameter's name, at the start or end; a boolean.
-* - `separator`: a word (`of`) or `=` separating the parameters before it
-*   from those after it; a boolean.
-* - `options`: keywords, the names of its `parameters`, each followed by a
-*   quoted string or a number unless it is a flag.
-*/
-var PARAMETER_TYPES = [
-	"expression",
-	"statements",
-	"passage",
-	"variable",
-	"string",
-	"text",
-	"names",
-	"delay",
-	"number",
-	"flag",
-	"separator",
-	"options"
-];
-/**
-* What the value of a `string` or `text` argument holds, for the check at
-* story start and for tooling (see code-check.ts):
-* - `markup`: markup the macro renders (`{button}`'s label): its markup
-*   is checked.
-* - `text`: plain text the macro uses as written (`{checkbox}`'s label).
-* - `passage`: a passage name (`{watch}`'s `goto`): the passage must exist.
-* - `expression`, `statements`: code (`{watch}`'s condition and `run`): it
-*   is checked as code, and its variable references against the schema.
-*
-* Without it, the argument of a macro with `interpolate` holds `markup`,
-* any other `text`.
-*/
-var STRING_HOLDS = [
-	"markup",
-	"text",
-	"passage",
-	"expression",
-	"statements"
-];
-/**
-* Throw if a parameter `macro` declares (or an option of one) has no type,
-* or one that isn't a ParameterType: arguments are read by their type, and
-* there is no default. Throw too if it declares what it `holds` wrongly.
-*/
-function checkParameterTypes(macro, parameters) {
-	const holdsFix = `Give a \`string\` or \`text\` parameter one of ${STRING_HOLDS.join(", ")} to hold (see docs/custom-macros.md#what-a-string-holds).`;
-	for (const param of parameters) {
-		const type = param.type;
-		if (!PARAMETER_TYPES.includes(type)) throw parameterError(macro, param, type === void 0 ? "has no type" : `has the unknown type ${JSON.stringify(type)}`, `Give it one of the types ${PARAMETER_TYPES.join(", ")} (see docs/custom-macros.md#parameter-types), or declare no parameters and read props.rawArgs.`);
-		const holds = param.holds;
-		if (holds !== void 0 && type !== "string" && type !== "text") throw parameterError(macro, param, `is of the type ${type}, which holds what it is`, holdsFix);
-		if (holds !== void 0 && !STRING_HOLDS.includes(holds)) throw parameterError(macro, param, `holds the unknown ${JSON.stringify(holds)}`, holdsFix);
-		if (param.parameters) checkParameterTypes(macro, param.parameters);
-	}
-}
-/** The error for the parameter `param` of `macro`: what is wrong, and the fix. */
-function parameterError(macro, param, problem, fix) {
-	return /* @__PURE__ */ new Error(`spindle: The parameter "${param.name}" of the macro {${macro}} ${problem}. ${fix}`);
-}
-new NameMap();
 //#endregion
 //#region src/utils/namespace.ts
 /** The variable name no namespace can hold. */
@@ -11430,7 +11503,8 @@ function validateStoryMarkup(passages, macros, options = {}) {
 	const list = [...passages];
 	const all = [...macros];
 	const known = /* @__PURE__ */ new Set();
-	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);
@@ -11440,7 +11514,7 @@ function validateStoryMarkup(passages, macros, options = {}) {
 	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/package.json

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

package/src/components/StoryInterface.tsx

@@ -1,7 +1,12 @@
-import { useMemo } from 'preact/hooks';
+import { useLayoutEffect, useMemo } from 'preact/hooks';
 import { useStoryFields } from '../hooks/use-story-fields';
 import { parseMarkup } from '../markup/parse';
-import { renderInlineNodes, NobrContext } from '../markup/render';
+import {
+  renderInlineNodes,
+  InterfaceContext,
+  NobrContext,
+} from '../markup/render';
+import { declareInterfaceMounted } from '../triggers';
 import { errorMessage } from '../utils/error-message';
 
 const DEFAULT_MARKUP =
@@ -26,9 +31,15 @@ export function StoryInterface() {
     }
   }, [markup]);
 
-  return nobr ? (
-    <NobrContext.Provider value={true}>{rendered}</NobrContext.Provider>
-  ) : (
-    rendered
+  useLayoutEffect(declareInterfaceMounted, []);
+
+  return (
+    <InterfaceContext.Provider value={true}>
+      {nobr ? (
+        <NobrContext.Provider value={true}>{rendered}</NobrContext.Provider>
+      ) : (
+        rendered
+      )}
+    </InterfaceContext.Provider>
   );
 }

package/src/components/macros/Watch.tsx

@@ -1,8 +1,10 @@
 import { defineMacro } from '../../define-macro';
 import { FrozenStateContext } from '../../hooks/use-story-fields';
 import { useStoryStore } from '../../store';
+import { InterfaceContext } from '../../markup/render';
 import {
   addMacroTrigger,
+  declareInterfaceWatch,
   removeTrigger,
   subscribeTriggerResets,
   triggerResets,
@@ -50,6 +52,15 @@ defineMacro({
       () => subscribeTriggerResets(() => rerender((n) => n + 1)),
       [],
     );
+    // The interface's watchers are re-registered by a load of a save made
+    // before the interface mounted (#419)
+    const inInterface = hooks.useContext(InterfaceContext);
+    const declaredKey = JSON.stringify([condition, options]);
+    hooks.useLayoutEffect(
+      () =>
+        inInterface ? declareInterfaceWatch(condition, options) : undefined,
+      [inInterface, declaredKey],
+    );
     const registered = hooks.useRef<number | null>(null);
     if (
       registered.current === null ||

package/src/markup/ast.ts

@@ -8,6 +8,8 @@ import { NameSet } from '../utils/macro-names';
 export interface TextNode {
   type: 'text';
   value: string;
+  /** A closed HTML comment: markdown drops it, and so does raw rendering. */
+  comment?: true;
 }
 
 export interface VariableNode extends Selectors {

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).
@@ -710,6 +712,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 +814,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 {