@rohal12/spindle 0.52.5 → 0.52.7

package/dist/pkg/headless.js

@@ -946,6 +946,13 @@ var UNCLOSED = -1;
 var MALFORMED = -2;
 /** A frame result: the scan stops at index `s` inside it (`STOPPED - s`). */
 var STOPPED = -3;
+/**
+* The result of a frame that closes at `end`. `bodyStarted`: the code inside
+* started a function or class body. That body replaced the one to come, and
+* is gone once the frame is closed, so after the frame no body is to come —
+* a scan that skips the frame must know, as must the frames around it.
+*/
+var frameEnd = (end, bodyStarted) => end * 2 + +bodyStarted;
 /** The closers whose search for their frame a frame result may depend on. */
 var CLOSERS = [
 	")",
@@ -1178,14 +1185,30 @@ function scan(src, handlers, start, nesting, outer, ctx) {
 	]] : void 0;
 	/**
 	* How many function or class bodies to come the scan has started, and with
-	* `parens`, that count when each open frame opened. Code in a `(…)` or
-	* `[…]` that starts one replaces the one to come, and the new one can't
-	* follow once the frame is closed: none is to come then.
+	* `braces` or `parens`, that count when each open frame opened. Code in a
+	* frame that starts one replaces the one to come, and the new one can't
+	* follow once the frame is closed: none is to come then. A scan skipping
+	* the frame learns this from its result (`frameEnd`, `resume`), and counts
+	* the body as started too, for the frames around it to record.
 	*/
 	let bodyStarts = 0;
-	const startsAt = parens ? [0] : void 0;
+	const startsAt = braces || parens ? [0] : void 0;
 	/** A `(…)` or `[…]` frame result found in `parens`, to skip to. */
 	let parenTo;
+	/** The result of the frame at index `k`, closing at `i`. */
+	const closedAt = (k) => frameEnd(i, startsAt !== void 0 && bodyStarts !== startsAt[k]);
+	/**
+	* Go on after a frame an earlier scan lexed, whose result (`frameEnd`) is
+	* `result`: returns the index it closes at. A body started in it is gone
+	* after it, with the one it replaced.
+	*/
+	function resume(result) {
+		if (result % 2 === 1) {
+			pendingBody = void 0;
+			bodyStarts++;
+		}
+		return Math.floor(result / 2);
+	}
 	/** The closer `c` looked for its frame and found index `k`. */
 	function lookedFor(c, k) {
 		if (!lowest) return;
@@ -1333,8 +1356,8 @@ function scan(src, handlers, start, nesting, outer, ctx) {
 		if (lowest) {
 			for (let j = frames.length - 1; j >= k; j--) foldLowest(j);
 			lowest.length = k;
-			startsAt.length = k;
 		}
+		if (startsAt) startsAt.length = k;
 		frames.length = k;
 		if (stackIds) stackIds.length = k;
 		for (const list of Object.values(closers)) while (list.length && list[list.length - 1] >= k) list.pop();
@@ -1411,6 +1434,18 @@ function scan(src, handlers, start, nesting, outer, ctx) {
 		stmtNext = f.kind === "block";
 		keyNext = f.kind === "object" || f.kind === "class";
 	}
+	/**
+	* Go past frame `f` if an earlier scan lexed it: to just after it, or to
+	* the end of the source when it never closes. Whether it did, or
+	* MALFORMED when that scan found the code malformed.
+	*/
+	function skipLexed(f) {
+		const end = known(f);
+		if (end === void 0) return false;
+		if (end === MALFORMED) return MALFORMED;
+		i = end === UNCLOSED ? src.length : resume(end) + 1;
+		return true;
+	}
 	function openBrace() {
 		let f;
 		if (pendingBody?.depth === frames.length) {
@@ -1454,10 +1489,10 @@ function scan(src, handlers, start, nesting, outer, ctx) {
 			return;
 		}
 		const closed = frames[k];
+		const result = closedAt(k);
 		if (lowest && c !== "}") {
 			for (let j = frames.length - 1; j > k; j--) foldLowest(j);
-			const bodyStarted = bodyStarts !== startsAt[k];
-			recordParen(k, i * 2 + +bodyStarted);
+			recordParen(k, result);
 		}
 		truncate(k);
 		if (c === "]" && !ctx.lookahead) ctx.brackets.set(closed.open, i);
@@ -1466,7 +1501,7 @@ function scan(src, handlers, start, nesting, outer, ctx) {
 			stmtNext = closed.header;
 		} else if (c === "]") endPunct(c, false);
 		else {
-			record(closed, i);
+			record(closed, result);
 			afterBrace(closed);
 		}
 	}
@@ -1568,23 +1603,16 @@ function scan(src, handlers, start, nesting, outer, ctx) {
 			} else if (ch === "`") {
 				literal(ch, i);
 				if (frames.length === 1) return i + 1;
-				record(top(), i);
+				record(top(), closedAt(frames.length - 1));
 				i++;
 				truncate(frames.length - 1);
 				endOperand();
 			} else if (ch === "$" && src.charAt(i + 1) === "{") {
 				const f = frame("expr", "}", i);
 				f.interpolation = true;
-				const end = known(f);
-				if (end === MALFORMED) return malformed();
-				if (end === UNCLOSED) {
-					i = src.length;
-					break;
-				}
-				if (end !== void 0) {
-					i = end + 1;
-					continue;
-				}
+				const skipped = skipLexed(f);
+				if (skipped === MALFORMED) return malformed();
+				if (skipped) continue;
 				literal("${", i);
 				i += 2;
 				nesting++;
@@ -1611,14 +1639,9 @@ function scan(src, handlers, start, nesting, outer, ctx) {
 		if (ch === "`") {
 			endWord();
 			const f = frame("template", "`", i);
-			const end = known(f);
-			if (end === MALFORMED) return malformed();
-			if (end === UNCLOSED) {
-				i = src.length;
-				break;
-			}
-			if (end !== void 0) {
-				i = end + 1;
+			const skipped = skipLexed(f);
+			if (skipped === MALFORMED) return malformed();
+			if (skipped) {
 				endOperand();
 				continue;
 			}
@@ -1637,7 +1660,7 @@ function scan(src, handlers, start, nesting, outer, ctx) {
 			lookedFor("}", k);
 			if (frames[k].interpolation) {
 				endWord();
-				record(frames[k], i);
+				record(frames[k], closedAt(k));
 				truncate(k);
 				nesting--;
 				literal(ch, i);
@@ -1719,7 +1742,7 @@ function scan(src, handlers, start, nesting, outer, ctx) {
 				continue;
 			}
 		}
-		if (ch === outer.closer && frames.length === 1) break;
+		if (ch === outer.closer && (frames.length === 1 || ch === "]" && innermost("]") === 0 && innermost("}") === 0)) break;
 		trackCode(ch);
 		if (skipTo) {
 			const { frame: skipped, end } = skipTo;
@@ -1729,7 +1752,7 @@ function scan(src, handlers, start, nesting, outer, ctx) {
 				i = src.length;
 				break;
 			}
-			i = end;
+			i = resume(end);
 			afterBrace(skipped);
 			i++;
 			continue;
@@ -1747,8 +1770,7 @@ function scan(src, handlers, start, nesting, outer, ctx) {
 				strict.stopped = true;
 				return STOPPED - result;
 			}
-			i = Math.floor(result / 2);
-			if (result % 2 === 1) pendingBody = void 0;
+			i = resume(result);
 			if (skipped.closer === ")") {
 				endPunct(")", skipped.header);
 				stmtNext = skipped.header;
@@ -3679,11 +3701,29 @@ function ExprDisplay({ expression, className, id }) {
 	return /* @__PURE__ */ jsx(Fragment$1, { children: display });
 }
 //#endregion
-//#region src/components/macros/WidgetInvocation.tsx
-function WidgetBody({ body, parentValues, ownKeys }) {
-	const nobr = useContext(NobrContext);
-	const inline = useContext(InlineContext);
-	const raw = useContext(RawTextContext);
+//#region src/hooks/use-render-options.ts
+/**
+* The renderNodes() options of the enclosing content: nobr, inline and raw
+* rendering and the locals in scope. A macro or widget body rendered with
+* them renders as the content around it does.
+*/
+function useRenderOptions() {
+	return {
+		nobr: useContext(NobrContext),
+		inline: useContext(InlineContext),
+		raw: useContext(RawTextContext),
+		locals: useContext(LocalsValuesContext)
+	};
+}
+//#endregion
+//#region src/components/macros/locals-scope.tsx
+/**
+* Render `body` in a new locals scope: the locals of `parentValues`, with
+* `ownKeys` (an iteration's loop variables, a widget's parameters) on top.
+* Locals the body assigns are kept in this scope.
+*/
+function LocalsScope({ body, parentValues, ownKeys }) {
+	const options = useRenderOptions();
 	const [localMutations, setLocalMutations] = useState({});
 	const localState = useMemo(() => createNamespace(parentValues, ownKeys, localMutations), [
 		parentValues,
@@ -3710,29 +3750,22 @@ function WidgetBody({ body, parentValues, ownKeys }) {
 		children: /* @__PURE__ */ jsx(LocalsValuesContext.Provider, {
 			value: localState,
 			children: renderNodes(body, {
-				nobr,
-				inline,
-				raw,
+				...options,
 				locals: localState
 			})
 		})
 	});
 }
+//#endregion
+//#region src/components/macros/WidgetInvocation.tsx
 function WidgetInvocation({ body, params, rawArgs, invocationChildren }) {
-	const parentValues = useContext(LocalsValuesContext);
-	const nobr = useContext(NobrContext);
-	const inline = useContext(InlineContext);
-	const raw = useContext(RawTextContext);
+	const renderOptions = useRenderOptions();
+	const parentValues = renderOptions.locals;
 	const [mergedVars, mergedTemps, mergedLocals, mergedTrans] = useMergedLocals();
 	const childrenValue = invocationChildren?.length ? invocationChildren : null;
 	if (params.length === 0) return /* @__PURE__ */ jsx(WidgetChildrenContext.Provider, {
 		value: childrenValue,
-		children: renderNodes(body, {
-			nobr,
-			inline,
-			raw,
-			locals: parentValues
-		})
+		children: renderNodes(body, renderOptions)
 	});
 	const argExprs = rawArgs ? splitArgs(rawArgs) : [];
 	const values = [];
@@ -3753,7 +3786,7 @@ function WidgetInvocation({ body, params, rawArgs, invocationChildren }) {
 	}, values);
 	return /* @__PURE__ */ jsx(WidgetChildrenContext.Provider, {
 		value: childrenValue,
-		children: /* @__PURE__ */ jsx(WidgetBody, {
+		children: /* @__PURE__ */ jsx(LocalsScope, {
 			body,
 			parentValues,
 			ownKeys
@@ -3958,6 +3991,32 @@ function MacroError({ macro, error }) {
 		children: `{${macro} error${currentSourceLocation()}: ${errorMessage(error)}}`
 	});
 }
+/** Log an error in the macro `{label}` (its name, or name and arguments). */
+function logMacroError(label, error) {
+	console.error(`spindle: Error in {${label}}${currentSourceLocation()}:`, error);
+}
+/**
+* Run `effect` once, during the macro's first render. If it throws, the
+* error is logged under `{macro rawArgs}` and shown in place of the macro
+* from then on; otherwise the macro renders nothing.
+*/
+function useRunOnce(macro, rawArgs, effect) {
+	const failure = useRef();
+	if (failure.current === void 0) {
+		failure.current = null;
+		try {
+			effect();
+		} catch (error) {
+			failure.current = { error };
+			logMacroError(`${macro} ${rawArgs}`, error);
+		}
+	}
+	if (!failure.current) return null;
+	return /* @__PURE__ */ jsx(MacroError, {
+		macro,
+		error: failure.current.error
+	});
+}
 //#endregion
 //#region src/markup/render.tsx
 var defaultUpdater = {
@@ -4327,11 +4386,8 @@ function resolveAttributeValue(name, value, scope, errors) {
 }
 function HtmlNodeRenderer({ node }) {
 	const scope = useTextScope();
-	const nobr = useContext(NobrContext);
-	const locals = useContext(LocalsValuesContext);
-	const inRaw = useContext(RawTextContext);
+	const { nobr, locals, raw: inRaw, inline: parentInline } = useRenderOptions();
 	const inSvg = useContext(SvgContext);
-	const parentInline = useContext(InlineContext);
 	const tag = node.tag.toLowerCase();
 	const isSvgRoot = tag === "svg";
 	const isRawRoot = !inRaw && (isSvgRoot || PREFORMATTED_ELEMENTS.has(tag));
@@ -7494,18 +7550,236 @@ function collectText(nodes) {
 	return nodes.map((n) => n.type === "text" ? n.value : "").join("");
 }
 //#endregion
+//#region src/utils/parse-delay.ts
+/**
+* Parse a delay string into milliseconds.
+* Supports: "2s" → 2000, "500ms" → 500, bare number → ms
+*/
+function parseDelay(str) {
+	const trimmed = str.trim();
+	if (trimmed.endsWith("ms")) return parseFloat(trimmed.slice(0, -2));
+	if (trimmed.endsWith("s")) return parseFloat(trimmed.slice(0, -1)) * 1e3;
+	return parseFloat(trimmed);
+}
+//#endregion
+//#region src/components/macros/macro-args.ts
+/**
+* The macro argument layer: reads a macro's raw argument text into the
+* parameters its definition declares (see ParameterDef), so every macro
+* splits and unquotes its arguments the same way. defineMacro() passes the
+* result to the macro as `ctx.args`.
+*
+* Arguments are read in groups, split at `separator` parameters. A group's
+* `flag` parameters are taken off its start or end first. Its last
+* `expression` or `text` parameter (without one, its last parameter) reads
+* the text the others leave; each parameter before it reads one term from
+* the start, and each after it one term from the end. Terms are separated by
+* whitespace outside literals and brackets (see arg-utils.ts), and a term
+* that follows an operator belongs to the expression before it. A parameter
+* with nothing to read is unset (a flag or separator is false, options are
+* empty).
+*/
+/** The terms of `src`: the runs of text between its depth-0 whitespace. */
+function terms(src) {
+	const spans = [];
+	let start = 0;
+	for (const i of [...topLevelIndices(src, isWhitespace), src.length]) {
+		if (i > start) spans.push([start, i]);
+		start = i + 1;
+	}
+	return spans;
+}
+var slice = (src, [start, end]) => src.slice(start, end);
+/**
+* The value of a `text` argument: one quoted string, or the text with any
+* loose quotes stripped (`"Red` → `Red`).
+*/
+function readText(src) {
+	return readWholeQuoted(src) ?? stripLooseQuotes(src);
+}
+function readValue(param, src) {
+	switch (param.type) {
+		case "string": return readWholeQuoted(src) ?? void 0;
+		case "text": return readText(src);
+		case "names": return src.split(",").map((name) => name.trim());
+		case "delay": return parseDelay(src);
+		case "number": return Number(src);
+		case "options": return readOptions(param.parameters ?? [], src);
+		default: return src;
+	}
+}
+function unset(param) {
+	if (param.type === "flag" || param.type === "separator") return false;
+	return param.type === "options" ? {} : void 0;
+}
+var WORD_RE = /\w+/y;
+var DIGITS_RE = /\d+/y;
+/** Match the sticky regex `re` at `pos`, returning the matched text. */
+function matchAt(re, src, pos) {
+	re.lastIndex = pos;
+	return re.exec(src)?.[0] ?? null;
+}
+/**
+* Read keyword options (`goto "X" priority 5 once`). A keyword takes the
+* quoted string or digit run after it as its value; keywords that aren't
+* declared, and their values, are skipped.
+*/
+function readOptions(params, src) {
+	const options = {};
+	let i = 0;
+	while (i < src.length) {
+		const key = matchAt(WORD_RE, src, i);
+		if (!key) {
+			i = readQuoted(src, i)?.end ?? i + 1;
+			continue;
+		}
+		i += key.length;
+		let val;
+		let j = i;
+		while (j < src.length && isWhitespace(src[j])) j++;
+		if (j > i) {
+			const quoted = readQuoted(src, j);
+			const digits = quoted ? null : matchAt(DIGITS_RE, src, j);
+			if (quoted) {
+				val = quoted.value;
+				i = quoted.end;
+			} else if (digits) {
+				val = digits;
+				i = j + digits.length;
+			}
+		}
+		const param = params.find((p) => p.name === key);
+		if (param?.type === "flag") options[key] = true;
+		else if (param?.type === "number") options[key] = Number(val ?? 0);
+		else if (param) options[key] = val;
+	}
+	return options;
+}
+/** `inline %name` reads a transient variable; `inline % 2` is modulo. */
+var LEADING_OPERATOR_RE = /^(?:[-+*/&|^=<>?:,.]|%(?![A-Za-z_]))/;
+/**
+* The rest of `src` without the flag `word` as its last or first term, or
+* `null` if it has no such flag. Next to a binary operator the word is an
+* operand (`"a" + inline`), not a flag; the closing `/` of a regex literal
+* is not one.
+*/
+function takeFlag(src, word) {
+	const spans = terms(src);
+	if (spans.length < 2) return null;
+	if (slice(src, spans[spans.length - 1]) === word) {
+		const rest = src.slice(0, spans[spans.length - 2][1]);
+		if (!endsWithOperator(rest)) return rest;
+	}
+	if (slice(src, spans[0]) === word) {
+		const rest = src.slice(spans[1][0]);
+		if (!LEADING_OPERATOR_RE.test(rest)) return rest;
+	}
+	return null;
+}
+/**
+* Where the separator `word` splits `src`, as the end of the text before it
+* and the start of the text after it, or `null` if it doesn't. A word is a
+* term with terms on both sides; `=` is an assignment at depth 0, not part
+* of `==` or `!=`.
+*/
+function findSeparator(src, word) {
+	if (word === "=") {
+		const indices = topLevelIndices(src, (ch) => ch === "=");
+		for (let k = 0; k < indices.length; k++) {
+			const i = indices[k];
+			if (src[i + 1] === "=") {
+				k++;
+				continue;
+			}
+			if (src[i - 1] !== "!") return [i, i + 1];
+		}
+		return null;
+	}
+	const spans = terms(src);
+	for (let k = 1; k < spans.length - 1; k++) if (slice(src, spans[k]) === word) return [spans[k - 1][1], spans[k + 1][0]];
+	return null;
+}
+var takesRest = (param) => param.type === void 0 || param.type === "expression" || param.type === "text";
+/** Read the parameters of one group from `src` (`null`: no text) into `args`. */
+function readGroup(params, src, args) {
+	let text = src?.trim() ?? "";
+	for (const flag of params.filter((p) => p.type === "flag")) {
+		const rest = src === null ? null : takeFlag(text, flag.name);
+		args[flag.name] = rest !== null;
+		text = rest ?? text;
+	}
+	const positional = params.filter((p) => p.type !== "flag");
+	if (positional.length === 0) return;
+	const lastText = positional.findIndex((p, i) => takesRest(p) && !positional.slice(i + 1).some(takesRest));
+	const restIndex = lastText < 0 ? positional.length - 1 : lastText;
+	const read = (param, value) => value === "" ? unset(param) : readValue(param, value);
+	if (positional.length === 1) {
+		args[positional[0].name] = read(positional[0], text);
+		return;
+	}
+	const spans = terms(text);
+	let from = 0;
+	let to = spans.length;
+	for (const param of positional.slice(0, restIndex)) args[param.name] = from < to ? read(param, slice(text, spans[from++])) : unset(param);
+	for (const param of positional.slice(restIndex + 1).reverse()) {
+		const value = from < to && !endsWithOperator(text.slice(0, spans[to - 1][0])) ? read(param, slice(text, spans[to - 1])) : void 0;
+		args[param.name] = value ?? unset(param);
+		if (value !== void 0) to--;
+	}
+	const rest = positional[restIndex];
+	args[rest.name] = from < to ? read(rest, text.slice(spans[from][0], spans[to - 1][1])) : unset(rest);
+}
+/** Read `rawArgs` into the declared `parameters` (see above). */
+function parseMacroArgs(rawArgs, parameters) {
+	const args = {};
+	let rest = rawArgs.trim();
+	let groupStart = 0;
+	parameters.forEach((separator, i) => {
+		if (separator.type !== "separator") return;
+		const at = rest === null ? null : findSeparator(rest, separator.name);
+		args[separator.name] = at !== null;
+		const before = at ? rest.slice(0, at[0]) : rest;
+		readGroup(parameters.slice(groupStart, i), before, args);
+		rest = at ? rest.slice(at[1]) : null;
+		groupStart = i + 1;
+	});
+	readGroup(parameters.slice(groupStart), rest, args);
+	return args;
+}
+/**
+* The passage a passage-name argument names: the value of its expression
+* or, when that can't be evaluated (`{goto Bob's room}`), its text.
+*/
+function evaluatePassageName(expr, evaluate) {
+	try {
+		return String(evaluate(expr ?? ""));
+	} catch {
+		return readText(expr ?? "");
+	}
+}
+/**
+* The variable a `storeVar` macro binds: its first term, as written. Custom
+* macros may bind one without declaring parameters.
+*/
+function readBoundVariable(rawArgs) {
+	const src = rawArgs.trim();
+	const first = terms(src)[0];
+	return first ? slice(src, first) : "";
+}
+//#endregion
 //#region src/components/macros/option-utils.ts
+/** `$var "placeholder"`, the arguments of the input macros. */
 function parseVarArgs(rawArgs) {
-	const match = rawArgs.match(/^\s*(["']?\$[\w.]+["']?)\s*(["'].*["'])?\s*$/s);
-	if (!match) return {
-		varName: rawArgs.trim(),
-		placeholder: ""
-	};
-	const varName = match[1].replace(/["']/g, "");
-	const quoted = match[2];
+	const { variable = "", placeholder = "" } = parseMacroArgs(rawArgs, [{
+		name: "variable",
+		type: "variable"
+	}, {
+		name: "placeholder",
+		type: "string"
+	}]);
 	return {
-		varName,
-		placeholder: quoted ? readWholeQuoted(quoted) ?? quoted.slice(1, -1) : ""
+		varName: variable.replace(/["']/g, ""),
+		placeholder
 	};
 }
 /**
@@ -7536,6 +7810,7 @@ var sharedHooks = {
 	useContext
 };
 function defineMacro(config, source = "builtin") {
+	const parameters = config.parameters ?? [];
 	function Wrapper(props) {
 		let className = props.className;
 		let id = props.id;
@@ -7546,18 +7821,13 @@ function defineMacro(config, source = "builtin") {
 			id = resolve(id);
 		}
 		const { update, getValues } = useContext(LocalsUpdateContext);
-		const nobr = useContext(NobrContext);
-		const inline = useContext(InlineContext);
-		const raw = useContext(RawTextContext);
-		const localsValues = useContext(LocalsValuesContext);
+		const renderOptions = useRenderOptions();
 		const renderNodes$1 = (nodes, options) => renderNodes(nodes, {
-			nobr,
-			inline,
-			raw,
-			locals: localsValues,
+			...renderOptions,
 			...options
 		});
 		const ctx = {
+			args: parseMacroArgs(props.rawArgs, parameters),
 			collectText,
 			sourceLocation: currentSourceLocation,
 			parseVarArgs,
@@ -7588,7 +7858,7 @@ function defineMacro(config, source = "builtin") {
 			ctx.evaluate = (expr) => evaluate(expr, merged[0], merged[1], merged[2], merged[3]);
 		}
 		if (config.storeVar) {
-			const firstToken = props.rawArgs.trim().split(/\s+/)[0]?.replace(/["']/g, "") ?? "";
+			const firstToken = readBoundVariable(props.rawArgs).replace(/["']/g, "");
 			if (firstToken.startsWith("%")) return h("span", { class: "error" }, `{${config.name}}: transient variables (%${firstToken.slice(1)}) cannot be bound to input macros`);
 			const varExpr = firstToken.replace(/["']/g, "").replace(/^\$/, "");
 			const segments = varExpr.split(".");
@@ -7605,7 +7875,11 @@ function defineMacro(config, source = "builtin") {
 		return config.render(props, ctx);
 	}
 	registerMacro(config.name, Wrapper);
-	registerMacroText(config.name, config.text);
+	const text = config.text;
+	registerMacroText(config.name, text && ((props, ctx) => text(props, {
+		...ctx,
+		args: parseMacroArgs(props.rawArgs, parameters)
+	})));
 	const isBlock = config.block === true || config.block !== false && (config.subMacros?.length ?? 0) > 0;
 	registerMacroMetadata(config.name, {
 		name: config.name,
@@ -7615,7 +7889,7 @@ function defineMacro(config, source = "builtin") {
 		interpolate: config.interpolate,
 		merged: config.merged,
 		description: config.description,
-		parameters: config.parameters,
+		parameters: config.parameters && [...config.parameters],
 		source
 	});
 	if (config.subMacros) for (const sub of config.subMacros) registerSubMacro(sub);
@@ -8288,29 +8562,24 @@ defineMacro({
 //#region src/components/macros/Set.tsx
 defineMacro({
 	name: "set",
+	parameters: [{
+		name: "code",
+		type: "expression",
+		required: true
+	}],
 	render({ rawArgs }, ctx) {
-		const ran = ctx.hooks.useRef(false);
-		const failure = ctx.hooks.useRef(null);
-		if (!ran.current) {
-			ran.current = true;
-			try {
-				ctx.mutate(rawArgs);
-			} catch (err) {
-				failure.current = { error: err };
-				console.error(`spindle: Error in {set ${rawArgs}}${ctx.sourceLocation()}:`, err);
-			}
-		}
-		if (failure.current) return /* @__PURE__ */ jsx(MacroError, {
-			macro: "set",
-			error: failure.current.error
-		});
-		return null;
+		return useRunOnce("set", rawArgs, () => ctx.mutate(rawArgs));
 	}
 });
 //#endregion
 //#region src/components/macros/Print.tsx
 defineMacro({
 	name: "print",
+	parameters: [{
+		name: "expression",
+		type: "expression",
+		required: true
+	}],
 	interpolate: true,
 	merged: true,
 	render({ rawArgs }, ctx) {
@@ -8338,30 +8607,16 @@ defineMacro({
 * applied, even `undefined`; a first evaluation that throws leaves it unset.
 */
 var UNSET = Symbol("unset");
-function parseComputedArgs(rawArgs) {
-	const trimmed = rawArgs.trim();
-	let depth = 0;
-	for (let i = 0; i < trimmed.length; i++) {
-		const ch = trimmed[i];
-		if (ch === "(" || ch === "[" || ch === "{") depth++;
-		else if (ch === ")" || ch === "]" || ch === "}") depth--;
-		else if (ch === "=" && depth === 0) {
-			if (trimmed[i + 1] === "=") {
-				i++;
-				continue;
-			}
-			if (i > 0 && trimmed[i - 1] === "!") continue;
-			const target = trimmed.slice(0, i).trim();
-			const expr = trimmed.slice(i + 1).trim();
-			if (!target.match(/^[$_@]\w+$/)) throw new Error(`{computed}: target must be $name, _name, or @name, got "${target}"`);
-			checkVariableName(target.slice(1), target);
-			return {
-				target,
-				expr
-			};
-		}
-	}
-	throw new Error(`{computed}: expected "target = expression", got "${rawArgs}"`);
+/** Check the arguments of "target = expression". */
+function assignmentArgs(rawArgs, args) {
+	if (!args["="]) throw new Error(`{computed}: expected "target = expression", got "${rawArgs}"`);
+	const { target = "", expression: expr = "" } = args;
+	if (!target.match(/^[$_@]\w+$/)) throw new Error(`{computed}: target must be $name, _name, or @name, got "${target}"`);
+	checkVariableName(target.slice(1), target);
+	return {
+		target,
+		expr
+	};
 }
 /**
 * Evaluate `expr` against the current values — the store's state and the
@@ -8378,7 +8633,7 @@ function computeAndApply(expr, name, isTemp, isLocal, getLocals, rawArgs, prevRe
 		const { variables, temporary, transient } = readState();
 		newValue = evaluate(expr, variables, temporary, getLocals(), transient);
 	} catch (err) {
-		console.error(`spindle: Error in {computed ${rawArgs}}${currentSourceLocation()}:`, err);
+		logMacroError(`computed ${rawArgs}`, err);
 		return;
 	}
 	if (!deepEqual(prevRef.current, newValue)) {
@@ -8386,7 +8641,7 @@ function computeAndApply(expr, name, isTemp, isLocal, getLocals, rawArgs, prevRe
 		if (isLocal) try {
 			localsUpdate(name, newValue);
 		} catch (err) {
-			console.error(`spindle: Error in {computed ${rawArgs}}${currentSourceLocation()}:`, err);
+			logMacroError(`computed ${rawArgs}`, err);
 		}
 		else {
 			const state = useStoryStore.getState();
@@ -8398,12 +8653,28 @@ function computeAndApply(expr, name, isTemp, isLocal, getLocals, rawArgs, prevRe
 defineMacro({
 	name: "computed",
 	merged: true,
+	parameters: [
+		{
+			name: "target",
+			type: "variable",
+			required: true
+		},
+		{
+			name: "=",
+			type: "separator"
+		},
+		{
+			name: "expression",
+			type: "expression",
+			required: true
+		}
+	],
 	render({ rawArgs }, ctx) {
 		const [mergedVars, mergedTemps, mergedLocals, mergedTrans] = ctx.merged;
 		let target;
 		let expr;
 		try {
-			({target, expr} = parseComputedArgs(rawArgs));
+			({target, expr} = assignmentArgs(rawArgs, ctx.args));
 		} catch (err) {
 			return /* @__PURE__ */ jsx(MacroError, {
 				macro: "computed",
@@ -8415,14 +8686,13 @@ defineMacro({
 		const name = target.slice(1);
 		const localsUpdate = isLocal ? ctx.update : null;
 		const prevOutput = ctx.hooks.useRef(UNSET);
+		const compute = () => computeAndApply(expr, name, isTemp, isLocal, ctx.getValues, rawArgs, prevOutput, localsUpdate);
 		const ran = ctx.hooks.useRef(false);
 		if (!ran.current) {
 			ran.current = true;
-			computeAndApply(expr, name, isTemp, isLocal, ctx.getValues, rawArgs, prevOutput, localsUpdate);
+			compute();
 		}
-		ctx.hooks.useLayoutEffect(() => {
-			computeAndApply(expr, name, isTemp, isLocal, ctx.getValues, rawArgs, prevOutput, localsUpdate);
-		}, [
+		ctx.hooks.useLayoutEffect(compute, [
 			mergedVars,
 			mergedTemps,
 			mergedLocals,
@@ -8433,26 +8703,13 @@ defineMacro({
 });
 //#endregion
 //#region src/components/macros/Meter.tsx
-/**
-* Parse `{meter currentExpr maxExpr ["label"]}`. Arguments are separated by
-* whitespace outside string and template literals and bracket pairs; a
-* trailing standalone `"…"` or `'…'` string is the label mode, with `\"`,
-* `\'` and `\\` escapes. A string after an operator (`$a ?? "5"`) is an
-* operand of the max expression, not the label.
-*/
-function parseMeterArgs(rawArgs) {
-	const tokens = splitTopLevel(rawArgs.trim(), isWhitespace).filter(Boolean);
-	let labelMode = "";
-	const label = tokens.length >= 2 && !endsWithOperator(tokens.slice(0, -1).join(" ")) ? readWholeQuoted(tokens[tokens.length - 1]) : null;
-	if (label !== null) {
-		labelMode = label;
-		tokens.pop();
-	}
-	if (tokens.length < 2) throw new Error("meter requires two arguments: {meter currentExpr maxExpr}");
+/** Check the arguments of `{meter currentExpr maxExpr ["label"]}`. */
+function meterArgs(args) {
+	if (args.current === void 0 || args.max === void 0) throw new Error("meter requires two arguments: {meter currentExpr maxExpr}");
 	return {
-		currentExpr: tokens[0],
-		maxExpr: tokens.slice(1).join(" "),
-		labelMode
+		currentExpr: args.current,
+		maxExpr: args.max,
+		labelMode: args.label ?? ""
 	};
 }
 function formatLabel(current, max, labelMode) {
@@ -8465,9 +8722,25 @@ defineMacro({
 	name: "meter",
 	interpolate: true,
 	merged: true,
-	render({ rawArgs }, ctx) {
+	parameters: [
+		{
+			name: "current",
+			type: "expression",
+			required: true
+		},
+		{
+			name: "max",
+			type: "expression",
+			required: true
+		},
+		{
+			name: "label",
+			type: "string"
+		}
+	],
+	render(_props, ctx) {
 		try {
-			const { currentExpr, maxExpr, labelMode } = parseMeterArgs(rawArgs);
+			const { currentExpr, maxExpr, labelMode } = meterArgs(ctx.args);
 			const current = Number(ctx.evaluate(currentExpr));
 			const max = Number(ctx.evaluate(maxExpr));
 			const pct = max === 0 ? 0 : Math.max(0, Math.min(100, current / max * 100));
@@ -8583,16 +8856,12 @@ function keyOf(val, ancestors) {
 //#endregion
 //#region src/components/macros/For.tsx
 /**
-* Parse for-loop args: "@item, @i of $list" or "@item of $list"
+* Check the arguments of "@item, @i of $list" or "@item of $list".
 */
-function parseForArgs(rawArgs) {
-	const ofIdx = rawArgs.indexOf(" of ");
-	if (ofIdx === -1) throw new Error(`{for} requires "of" keyword: {for ${rawArgs}}`);
-	const varsPart = rawArgs.slice(0, ofIdx).trim();
-	const listExpr = rawArgs.slice(ofIdx + 4).trim();
-	const vars = varsPart.split(",").map((v) => v.trim());
-	const itemVar = vars[0];
-	const indexVar = vars.length > 1 ? vars[1] : null;
+function loopArgs(rawArgs, args) {
+	if (!args.of) throw new Error(`{for} requires "of" keyword: {for ${rawArgs}}`);
+	const [itemVar = "", indexVar = null] = args.variables ?? [];
+	const listExpr = args.list ?? "";
 	if (!itemVar.startsWith("@")) throw new Error(`{for} loop variable must use @ prefix: got "${itemVar}"`);
 	if (indexVar && !indexVar.startsWith("@")) throw new Error(`{for} index variable must use @ prefix: got "${indexVar}"`);
 	checkVariableName(itemVar.slice(1), itemVar);
@@ -8604,50 +8873,18 @@ function parseForArgs(rawArgs) {
 	};
 }
 function ForIteration({ parentValues, itemVar, itemValue, indexVar, indexValue, children }) {
-	const [localMutations, setLocalMutations] = useState(() => ({}));
-	const ownKeys = useMemo(() => ({
-		[itemVar]: itemValue,
-		...indexVar ? { [indexVar]: indexValue } : void 0
-	}), [
-		itemVar,
-		itemValue,
-		indexVar,
-		indexValue
-	]);
-	const localState = useMemo(() => createNamespace(parentValues, ownKeys, localMutations), [
+	return /* @__PURE__ */ jsx(LocalsScope, {
+		body: children,
 		parentValues,
-		ownKeys,
-		localMutations
-	]);
-	const valuesRef = useRef(localState);
-	valuesRef.current = localState;
-	const getValues = useCallback(() => valuesRef.current, []);
-	const update = useCallback((key, value) => {
-		checkVariableName(key, `@${key}`);
-		valuesRef.current = withEntry(valuesRef.current, key, value);
-		setLocalMutations((prev) => ({
-			...prev,
-			[key]: value
-		}));
-	}, []);
-	const updater = useMemo(() => ({
-		update,
-		getValues
-	}), [update, getValues]);
-	const nobr = useContext(NobrContext);
-	const inline = useContext(InlineContext);
-	const raw = useContext(RawTextContext);
-	return /* @__PURE__ */ jsx(LocalsUpdateContext.Provider, {
-		value: updater,
-		children: /* @__PURE__ */ jsx(LocalsValuesContext.Provider, {
-			value: localState,
-			children: renderNodes(children, {
-				nobr,
-				inline,
-				raw,
-				locals: localState
-			})
-		})
+		ownKeys: useMemo(() => ({
+			[itemVar]: itemValue,
+			...indexVar ? { [indexVar]: indexValue } : void 0
+		}), [
+			itemVar,
+			itemValue,
+			indexVar,
+			indexValue
+		])
 	});
 }
 defineMacro({
@@ -8655,21 +8892,29 @@ defineMacro({
 	block: true,
 	interpolate: true,
 	merged: true,
+	parameters: [
+		{
+			name: "variables",
+			type: "names",
+			required: true
+		},
+		{
+			name: "of",
+			type: "separator"
+		},
+		{
+			name: "list",
+			type: "expression",
+			required: true
+		}
+	],
 	render({ rawArgs, children = [] }, ctx) {
 		const parentValues = useContext(LocalsValuesContext);
-		let parsed;
-		try {
-			parsed = parseForArgs(rawArgs);
-		} catch (err) {
-			return /* @__PURE__ */ jsx(MacroError, {
-				macro: "for",
-				error: err
-			});
-		}
-		const { itemVar, indexVar, listExpr } = parsed;
+		let loop;
 		let list;
 		try {
-			const result = ctx.evaluate(listExpr);
+			loop = loopArgs(rawArgs, ctx.args);
+			const result = ctx.evaluate(loop.listExpr);
 			if (!Array.isArray(result)) return /* @__PURE__ */ jsx("span", {
 				class: "error",
 				children: `{for error: expression did not evaluate to an array}`
@@ -8681,6 +8926,7 @@ defineMacro({
 				error: err
 			});
 		}
+		const { itemVar, indexVar } = loop;
 		const content = list.map((item, i) => /* @__PURE__ */ jsx(ForIteration, {
 			parentValues,
 			itemVar,
@@ -8692,7 +8938,7 @@ defineMacro({
 		return ctx.wrap(content);
 	},
 	text({ rawArgs, children = [] }, ctx) {
-		const { itemVar, indexVar, listExpr } = parseForArgs(rawArgs);
+		const { itemVar, indexVar, listExpr } = loopArgs(rawArgs, ctx.args);
 		const list = ctx.evaluate(listExpr);
 		if (!Array.isArray(list)) throw new Error("expression did not evaluate to an array");
 		return list.map((item, i) => ctx.renderText(children, {
@@ -8712,7 +8958,7 @@ defineMacro({
 			try {
 				ctx.mutate(code);
 			} catch (err) {
-				console.error(`spindle: Error in {do}${ctx.sourceLocation()}:`, err);
+				logMacroError("do", err);
 			}
 		}, []);
 		return null;
@@ -8743,27 +8989,20 @@ function liveLocalsView(getValues) {
 	});
 }
 //#endregion
-//#region src/utils/parse-delay.ts
-/**
-* Parse a delay string into milliseconds.
-* Supports: "2s" → 2000, "500ms" → 500, bare number → ms
-*/
-function parseDelay(str) {
-	const trimmed = str.trim();
-	if (trimmed.endsWith("ms")) return parseFloat(trimmed.slice(0, -2));
-	if (trimmed.endsWith("s")) return parseFloat(trimmed.slice(0, -1)) * 1e3;
-	return parseFloat(trimmed);
-}
-//#endregion
 //#region src/components/macros/Repeat.tsx
 var RepeatContext = createContext({ stop: () => {} });
 defineMacro({
 	name: "repeat",
 	block: true,
 	interpolate: true,
-	render({ rawArgs, children = [] }, ctx) {
+	parameters: [{
+		name: "delay",
+		type: "delay",
+		required: true
+	}],
+	render({ children = [] }, ctx) {
 		const { useState, useEffect, useCallback } = ctx.hooks;
-		const delay = parseDelay(rawArgs);
+		const delay = ctx.args.delay ?? 0;
 		const [count, setCount] = useState(0);
 		const [stopped, setStopped] = useState(false);
 		const stop = useCallback(() => setStopped(true), []);
@@ -8810,8 +9049,7 @@ defineMacro({
 */
 function useDetachedBody() {
 	const updater = useContext(LocalsUpdateContext);
-	const nobr = useContext(NobrContext);
-	const inline = useContext(InlineContext);
+	const { nobr, inline } = useRenderOptions();
 	const widgetChildren = useContext(WidgetChildrenContext);
 	const repeat = useContext(RepeatContext);
 	const closeDialog = useContext(DialogCloseContext);
@@ -8854,9 +9092,13 @@ defineMacro({
 	name: "button",
 	block: true,
 	interpolate: true,
+	parameters: [{
+		name: "label",
+		type: "text",
+		required: true
+	}],
 	render({ rawArgs, children = [] }, ctx) {
-		const text = readWholeQuoted(rawArgs.trim()) ?? rawArgs.replace(/^["']|["']$/g, "");
-		const label = ctx.resolve?.(text) ?? rawArgs;
+		const label = ctx.resolve?.(ctx.args.label ?? "") ?? rawArgs;
 		const runBody = useDetachedBody();
 		const handleClick = () => runBody(children);
 		ctx.useAction({
@@ -8876,30 +9118,22 @@ defineMacro({
 });
 //#endregion
 //#region src/components/macros/MacroLink.tsx
-function parseLinkArgs(rawArgs) {
-	const parts = [];
-	const re = /(["'])((?:\\[^]|(?!\1)[^\\])*)\1/g;
-	let m;
-	while ((m = re.exec(rawArgs)) !== null) parts.push(unescapeQuoted(m[2]));
-	if (parts.length >= 2) return {
-		display: parts[0],
-		passage: parts[1]
-	};
-	if (parts.length === 1) return {
-		display: parts[0],
-		passage: null
-	};
-	return {
-		display: rawArgs.trim(),
-		passage: null
-	};
-}
 defineMacro({
 	name: "link",
 	block: true,
 	interpolate: true,
+	parameters: [{
+		name: "text",
+		type: "string",
+		required: true
+	}, {
+		name: "passage",
+		type: "string"
+	}],
 	render({ rawArgs, children = [] }, ctx) {
-		const { display, passage } = parseLinkArgs(rawArgs);
+		const { text } = ctx.args;
+		const display = text ?? rawArgs.trim();
+		const passage = text === void 0 ? null : ctx.args.passage ?? null;
 		const runBody = useDetachedBody();
 		const perform = () => {
 			runBody(children);
@@ -8928,9 +9162,27 @@ defineMacro({
 });
 //#endregion
 //#region src/components/macros/Switch.tsx
+/**
+* The first {case} branch whose value equals `value`, else the {default}
+* branch, else null. Throws what a case expression throws.
+*/
+function selectBranch(value, branches, evaluate) {
+	let defaultBranch = null;
+	for (let i = 1; i < branches.length; i++) {
+		const branch = branches[i];
+		if (branch.rawArgs === "") defaultBranch = branch;
+		else if (value === evaluate(branch.rawArgs)) return branch;
+	}
+	return defaultBranch;
+}
 defineMacro({
 	name: "switch",
 	subMacros: ["case", "default"],
+	parameters: [{
+		name: "expression",
+		type: "expression",
+		required: true
+	}],
 	merged: true,
 	render({ rawArgs, branches = [] }, ctx) {
 		let switchValue;
@@ -8942,35 +9194,20 @@ defineMacro({
 				error: err
 			});
 		}
-		let defaultBranch = null;
-		for (let i = 1; i < branches.length; i++) {
-			const branch = branches[i];
-			if (branch.rawArgs === "") {
-				defaultBranch = branch;
-				continue;
-			}
-			try {
-				const caseValue = ctx.evaluate(branch.rawArgs);
-				if (switchValue === caseValue) return /* @__PURE__ */ jsx(Fragment$1, { children: ctx.renderNodes(branch.children) });
-			} catch (err) {
-				return /* @__PURE__ */ jsx(MacroError, {
-					macro: "case",
-					error: err
-				});
-			}
+		let branch;
+		try {
+			branch = selectBranch(switchValue, branches, ctx.evaluate);
+		} catch (err) {
+			return /* @__PURE__ */ jsx(MacroError, {
+				macro: "case",
+				error: err
+			});
 		}
-		if (defaultBranch) return /* @__PURE__ */ jsx(Fragment$1, { children: ctx.renderNodes(defaultBranch.children) });
-		return null;
+		return branch && /* @__PURE__ */ jsx(Fragment$1, { children: ctx.renderNodes(branch.children) });
 	},
 	text({ rawArgs, branches = [] }, ctx) {
-		const switchValue = ctx.evaluate(rawArgs);
-		let defaultBranch = null;
-		for (let i = 1; i < branches.length; i++) {
-			const branch = branches[i];
-			if (branch.rawArgs === "") defaultBranch = branch;
-			else if (switchValue === ctx.evaluate(branch.rawArgs)) return ctx.renderText(branch.children);
-		}
-		return defaultBranch ? ctx.renderText(defaultBranch.children) : "";
+		const branch = selectBranch(ctx.evaluate(rawArgs), branches, ctx.evaluate);
+		return branch ? ctx.renderText(branch.children) : "";
 	}
 });
 //#endregion
@@ -9030,9 +9267,14 @@ defineMacro({
 	name: "type",
 	block: true,
 	interpolate: true,
-	render({ rawArgs, children = [] }, ctx) {
+	parameters: [{
+		name: "delay",
+		type: "delay",
+		required: true
+	}],
+	render({ children = [] }, ctx) {
 		const { useState, useEffect, useRef } = ctx.hooks;
-		const speed = parseDelay(rawArgs);
+		const speed = ctx.args.delay ?? 0;
 		const containerRef = useRef(null);
 		const [totalChars, setTotalChars] = useState(0);
 		const [visibleChars, setVisibleChars] = useState(0);
@@ -9213,11 +9455,18 @@ defineMacro({
 	name: "dialog",
 	block: true,
 	interpolate: true,
-	render({ rawArgs, children = [] }, ctx) {
+	parameters: [{
+		name: "label",
+		type: "text",
+		required: true
+	}, {
+		name: "noclose",
+		type: "flag"
+	}],
+	render({ children = [] }, ctx) {
 		const [open, setOpen] = ctx.hooks.useState(false);
-		const noclose = /\bnoclose\s*$/.test(rawArgs);
-		const labelRaw = rawArgs.replace(/\bnoclose\s*$/, "").trim();
-		const label = ctx.resolve?.(readWholeQuoted(labelRaw) ?? labelRaw.replace(/^["']|["']$/g, "")) ?? labelRaw;
+		const { noclose } = ctx.args;
+		const label = ctx.resolve(ctx.args.label ?? "");
 		const passageName = ctx.collectText(children).trim().replace(/^["']|["']$/g, "");
 		return /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx("button", {
 			id: ctx.id,
@@ -9624,59 +9873,22 @@ defineMacro({
 });
 //#endregion
 //#region src/components/macros/Include.tsx
-var FLAG = "inline";
-/**
-* Split a standalone `inline` flag off the start or end of the include
-* arguments. The flag only counts outside quotes, brackets, parentheses and
-* braces, separated by whitespace from the target expression, so passage
-* names and expressions containing the word stay intact (#201).
-*/
-function parseIncludeArgs(rawArgs) {
-	const trimmed = rawArgs.trim();
-	const spaces = topLevelIndices(trimmed, isWhitespace);
-	let first = null;
-	let last = null;
-	if (spaces.length > 0) {
-		let s = 0;
-		while (s + 1 < spaces.length && spaces[s + 1] === spaces[s] + 1) s++;
-		first = [spaces[0], spaces[s] + 1];
-		let e = spaces.length - 1;
-		while (e > 0 && spaces[e - 1] === spaces[e] - 1) e--;
-		last = [spaces[e], spaces[spaces.length - 1] + 1];
-	}
-	if (last && last[1] === trimmed.length - 6 && trimmed.endsWith(FLAG)) {
-		const rest = trimmed.slice(0, last[0]);
-		if (!endsWithOperator(rest)) return {
-			nameExpr: rest,
-			inline: true
-		};
-	}
-	if (first && first[0] === 6 && trimmed.startsWith(FLAG)) {
-		const rest = trimmed.slice(first[1]);
-		if (!/^(?:[-+*/&|^=<>?:,.]|%(?![A-Za-z_]))/.test(rest)) return {
-			nameExpr: rest,
-			inline: true
-		};
-	}
-	return {
-		nameExpr: trimmed,
-		inline: false
-	};
-}
 defineMacro({
 	name: "include",
 	interpolate: true,
 	merged: true,
-	render({ rawArgs }, ctx) {
+	parameters: [{
+		name: "inline",
+		type: "flag"
+	}, {
+		name: "passage",
+		type: "expression",
+		required: true
+	}],
+	render(_props, ctx) {
 		const storyData = useStoryStore((s) => s.storyData);
-		const { nameExpr, inline } = parseIncludeArgs(rawArgs);
-		let passageName;
-		try {
-			const result = ctx.evaluate(nameExpr);
-			passageName = String(result);
-		} catch {
-			passageName = nameExpr.replace(/^["']|["']$/g, "");
-		}
+		const { inline } = ctx.args;
+		const passageName = evaluatePassageName(ctx.args.passage, ctx.evaluate);
 		const passage = storyData?.passages.get(passageName);
 		const ast = ctx.hooks.useMemo(() => passage ? buildAST(tokenize(passage.content)) : null, [passage]);
 		if (!storyData) return null;
@@ -9706,16 +9918,14 @@ defineMacro({
 defineMacro({
 	name: "goto",
 	merged: true,
-	render({ rawArgs }, ctx) {
+	parameters: [{
+		name: "passage",
+		type: "expression",
+		required: true
+	}],
+	render(_props, ctx) {
 		ctx.hooks.useLayoutEffect(() => {
-			let passageName;
-			try {
-				const result = ctx.evaluate(rawArgs);
-				passageName = String(result);
-			} catch {
-				passageName = rawArgs.replace(/^["']|["']$/g, "");
-			}
-			useStoryStore.getState().navigate(passageName);
+			useStoryStore.getState().navigate(evaluatePassageName(ctx.args.passage, ctx.evaluate));
 		}, []);
 		return null;
 	}
@@ -9724,124 +9934,90 @@ defineMacro({
 //#region src/components/macros/Unset.tsx
 defineMacro({
 	name: "unset",
+	parameters: [{
+		name: "variable",
+		type: "variable",
+		required: true
+	}],
 	render({ rawArgs }, ctx) {
-		const ran = ctx.hooks.useRef(false);
-		const failure = ctx.hooks.useRef(null);
-		if (!ran.current) {
-			ran.current = true;
+		return useRunOnce("unset", rawArgs, () => {
 			const state = useStoryStore.getState();
-			const name = rawArgs.trim();
-			try {
-				if (name.startsWith("$")) state.deleteVariable(name.slice(1));
-				else if (name.startsWith("_")) state.deleteTemporary(name.slice(1));
-				else if (name.startsWith("%")) state.deleteTransient(name.slice(1));
-				else if (name.startsWith("@")) ctx.update(name.slice(1), void 0);
-				else throw new Error(`{unset} expects a variable ($name, _name, %name, or @name), got "${name}"`);
-			} catch (err) {
-				failure.current = { error: err };
-				console.error(`spindle: Error in {unset ${rawArgs}}${ctx.sourceLocation()}:`, err);
-			}
-		}
-		if (failure.current) return /* @__PURE__ */ jsx(MacroError, {
-			macro: "unset",
-			error: failure.current.error
+			const name = ctx.args.variable ?? "";
+			if (name.startsWith("$")) state.deleteVariable(name.slice(1));
+			else if (name.startsWith("_")) state.deleteTemporary(name.slice(1));
+			else if (name.startsWith("%")) state.deleteTransient(name.slice(1));
+			else if (name.startsWith("@")) ctx.update(name.slice(1), void 0);
+			else throw new Error(`{unset} expects a variable ($name, _name, %name, or @name), got "${name}"`);
 		});
-		return null;
 	}
 });
 //#endregion
+//#region src/components/macros/input-macro.ts
+/**
+* Define a text input macro, `{name $var "placeholder"}`: an `<input>` of
+* `type` (or, without one, a `<textarea>`) bound to the story variable.
+* `toValue` turns what the reader types, or an automation action's value
+* (`undefined` when it has none), into the variable's value: by default,
+* the text.
+*/
+function defineInputMacro(name, type, toValue = (input) => input !== void 0 ? String(input) : "") {
+	defineMacro({
+		name,
+		storeVar: true,
+		parameters: [{
+			name: "variable",
+			type: "variable",
+			required: true
+		}, {
+			name: "placeholder",
+			type: "string"
+		}],
+		render(_props, ctx) {
+			const placeholder = ctx.args.placeholder ?? "";
+			ctx.useAction({
+				type: name,
+				key: `$${ctx.varName}`,
+				authorId: ctx.id,
+				label: placeholder || ctx.varName,
+				variable: ctx.varName,
+				value: ctx.value,
+				perform: (v) => ctx.setValue(toValue(v))
+			});
+			return h(type ? "input" : "textarea", {
+				type,
+				id: ctx.id,
+				class: ctx.cls,
+				value: ctx.value == null ? "" : String(ctx.value),
+				placeholder,
+				onInput: (e) => ctx.setValue(toValue(e.target.value))
+			});
+		}
+	});
+}
+//#endregion
 //#region src/components/macros/Textbox.tsx
-defineMacro({
-	name: "textbox",
-	storeVar: true,
-	render({ rawArgs }, ctx) {
-		const { placeholder } = ctx.parseVarArgs(rawArgs);
-		ctx.useAction({
-			type: "textbox",
-			key: `$${ctx.varName}`,
-			authorId: ctx.id,
-			label: placeholder || ctx.varName,
-			variable: ctx.varName,
-			value: ctx.value,
-			perform: (v) => ctx.setValue(v !== void 0 ? String(v) : "")
-		});
-		return /* @__PURE__ */ jsx("input", {
-			type: "text",
-			id: ctx.id,
-			class: ctx.cls,
-			value: ctx.value == null ? "" : String(ctx.value),
-			placeholder,
-			onInput: (e) => ctx.setValue(e.target.value)
-		});
-	}
-});
+defineInputMacro("textbox", "text");
 //#endregion
 //#region src/components/macros/Numberbox.tsx
-defineMacro({
-	name: "numberbox",
-	storeVar: true,
-	render({ rawArgs }, ctx) {
-		const { placeholder } = ctx.parseVarArgs(rawArgs);
-		ctx.useAction({
-			type: "numberbox",
-			key: `$${ctx.varName}`,
-			authorId: ctx.id,
-			label: placeholder || ctx.varName,
-			variable: ctx.varName,
-			value: ctx.value,
-			perform: (v) => ctx.setValue(v !== void 0 ? Number(v) : 0)
-		});
-		return /* @__PURE__ */ jsx("input", {
-			type: "number",
-			id: ctx.id,
-			class: ctx.cls,
-			value: ctx.value == null ? "" : String(ctx.value),
-			placeholder,
-			onInput: (e) => {
-				const val = e.target.value;
-				ctx.setValue(val === "" ? 0 : Number(val));
-			}
-		});
-	}
-});
+defineInputMacro("numberbox", "number", (v) => v !== void 0 ? Number(v) : 0);
 //#endregion
 //#region src/components/macros/Textarea.tsx
-defineMacro({
-	name: "textarea",
-	storeVar: true,
-	render({ rawArgs }, ctx) {
-		const { placeholder } = ctx.parseVarArgs(rawArgs);
-		ctx.useAction({
-			type: "textarea",
-			key: `$${ctx.varName}`,
-			authorId: ctx.id,
-			label: placeholder || ctx.varName,
-			variable: ctx.varName,
-			value: ctx.value,
-			perform: (v) => ctx.setValue(v !== void 0 ? String(v) : "")
-		});
-		return /* @__PURE__ */ jsx("textarea", {
-			id: ctx.id,
-			class: ctx.cls,
-			value: ctx.value == null ? "" : String(ctx.value),
-			placeholder,
-			onInput: (e) => ctx.setValue(e.target.value)
-		});
-	}
-});
+defineInputMacro("textarea");
 //#endregion
 //#region src/components/macros/Checkbox.tsx
-function parseCheckboxLabel(rawArgs) {
-	const match = rawArgs.match(/^\s*["']?\$?[\w.]+["']?\s+(.+)$/s);
-	if (!match) return "";
-	const rest = match[1].trimEnd() || match[1];
-	return readWholeQuoted(rest) ?? stripLooseQuotes(rest);
-}
 defineMacro({
 	name: "checkbox",
 	storeVar: true,
-	render({ rawArgs }, ctx) {
-		const label = parseCheckboxLabel(rawArgs);
+	parameters: [{
+		name: "variable",
+		type: "variable",
+		required: true
+	}, {
+		name: "label",
+		type: "text"
+	}],
+	render(_props, ctx) {
+		const label = ctx.args.label ?? "";
 		ctx.useAction({
 			type: "checkbox",
 			key: `$${ctx.varName}`,
@@ -9864,38 +10040,28 @@ defineMacro({
 });
 //#endregion
 //#region src/components/macros/Radiobutton.tsx
-function parseRadioArgs(rawArgs) {
-	const head = rawArgs.match(/^\s*["']?\$?[\w.]+["']?\s+/);
-	if (head) {
-		const rest = rawArgs.slice(head[0].length).trim();
-		const value = readQuoted(rest, 0);
-		if (value && (value.end === rest.length || isWhitespace(rest[value.end]))) {
-			const labelRaw = rest.slice(value.end).trim();
-			const label = readWholeQuoted(labelRaw) ?? stripLooseQuotes(labelRaw);
-			return {
-				value: value.value,
-				label
-			};
-		}
-	}
-	const match = rawArgs.match(/^\s*["']?\$?[\w.]+["']?\s+["'](.+?)["']\s+["']?(.+?)["']?\s*$/s);
-	if (!match) {
-		const parts = rawArgs.trim().split(/\s+/).slice(1);
-		return {
-			value: parts[0] ?? "",
-			label: parts.slice(1).join(" ")
-		};
-	}
-	return {
-		value: match[1],
-		label: match[2]
-	};
-}
 defineMacro({
 	name: "radiobutton",
 	storeVar: true,
-	render({ rawArgs }, ctx) {
-		const { value: radioValue, label } = parseRadioArgs(rawArgs);
+	parameters: [
+		{
+			name: "variable",
+			type: "variable",
+			required: true
+		},
+		{
+			name: "value",
+			type: "text",
+			required: true
+		},
+		{
+			name: "label",
+			type: "text"
+		}
+	],
+	render(_props, ctx) {
+		const radioValue = ctx.args.value ?? "";
+		const label = ctx.args.label ?? "";
 		ctx.useAction({
 			type: "radiobutton",
 			key: `$${ctx.varName}:${radioValue}`,
@@ -9923,6 +10089,11 @@ defineMacro({
 	name: "listbox",
 	subMacros: ["option"],
 	storeVar: true,
+	parameters: [{
+		name: "variable",
+		type: "variable",
+		required: true
+	}],
 	render({ children = [] }, ctx) {
 		const options = ctx.extractOptions(children);
 		ctx.useAction({
@@ -9955,6 +10126,11 @@ defineMacro({
 	name: "cycle",
 	block: true,
 	storeVar: true,
+	parameters: [{
+		name: "variable",
+		type: "variable",
+		required: true
+	}],
 	render({ children = [] }, ctx) {
 		const options = ctx.extractOptions(children);
 		const handleClick = () => {
@@ -10191,6 +10367,16 @@ function setCSSProperties(el, config) {
 	el.style.setProperty("--passage-pause", `${config.pause / 1e3}s`);
 }
 /**
+* Set up `containerEl` for an outgoing transition and snapshot the passage
+* it shows, or return null if there is no container or passage.
+*/
+function snapshotPassage(containerEl, config) {
+	if (!containerEl) return null;
+	setCSSProperties(containerEl, config);
+	const passageEl = containerEl.querySelector(".passage");
+	return passageEl ? createSnapshot(passageEl, config.type) : null;
+}
+/**
 * Remove all snapshot elements and crossfading class from a container.
 */
 function cleanupSnapshots(containerEl) {
@@ -10258,18 +10444,12 @@ defineMacro({
 				setDisplayedPassage(currentPassage);
 				return;
 			}
+			const snapshot = config.type === "fade-through" || config.type === "crossfade" ? snapshotPassage(containerEl, config) : null;
+			if (!containerEl || !snapshot) {
+				setDisplayedPassage(currentPassage);
+				return;
+			}
 			if (config.type === "fade-through") {
-				if (!containerEl) {
-					setDisplayedPassage(currentPassage);
-					return;
-				}
-				setCSSProperties(containerEl, config);
-				const passageEl = containerEl.querySelector(".passage");
-				if (!passageEl) {
-					setDisplayedPassage(currentPassage);
-					return;
-				}
-				const snapshot = createSnapshot(passageEl, config.type);
 				containerEl.appendChild(snapshot);
 				setDisplayedPassage("");
 				const incomingDelay = config.duration + config.pause;
@@ -10282,27 +10462,12 @@ defineMacro({
 				}, cleanupDelay)];
 				return;
 			}
-			if (config.type === "crossfade") {
-				if (!containerEl) {
-					setDisplayedPassage(currentPassage);
-					return;
-				}
-				setCSSProperties(containerEl, config);
-				const passageEl = containerEl.querySelector(".passage");
-				if (!passageEl) {
-					setDisplayedPassage(currentPassage);
-					return;
-				}
-				const snapshot = createSnapshot(passageEl, config.type);
-				containerEl.classList.add("passage-container--crossfading");
-				containerEl.appendChild(snapshot);
-				setDisplayedPassage(currentPassage);
-				timeoutsRef.current = [setTimeout(() => {
-					cleanupSnapshots(containerEl);
-				}, config.duration)];
-				return;
-			}
+			containerEl.classList.add("passage-container--crossfading");
+			containerEl.appendChild(snapshot);
 			setDisplayedPassage(currentPassage);
+			timeoutsRef.current = [setTimeout(() => {
+				cleanupSnapshots(containerEl);
+			}, config.duration)];
 		}, [navigationId]);
 		const effectivePassage = renderDeferred ? storyData?.passages.get("StoryLoading") ?? null : displayedPassage ? storyData?.passages.get(displayedPassage) : null;
 		if (!effectivePassage && displayedPassage && !renderDeferred) return /* @__PURE__ */ jsxs("div", {
@@ -10334,87 +10499,46 @@ defineMacro({
 });
 //#endregion
 //#region src/components/macros/Watch.tsx
-var WORD_RE = /\w+/y;
-var DIGITS_RE = /\d+/y;
-/** Match the sticky regex `re` at `pos`, returning the matched text. */
-function matchAt(re, src, pos) {
-	re.lastIndex = pos;
-	return re.exec(src)?.[0] ?? null;
-}
-/**
-* Parse `{watch "condition" keyword value …}`: a quoted condition followed
-* by keyword options (`goto "X"`, `dialog "X"`, `run "X"`, `name "X"`,
-* `priority N`, `once`). Quoted strings accept `\"`, `\'` and `\\` escapes.
-* Returns `null` when the arguments do not start with a quoted condition.
-*/
-function parseWatchArgs(rawArgs) {
-	const raw = rawArgs.trim();
-	const cond = readQuoted(raw, 0);
-	if (!cond) return null;
-	const options = {};
-	let i = cond.end;
-	while (i < raw.length) {
-		const key = matchAt(WORD_RE, raw, i);
-		if (!key) {
-			i = readQuoted(raw, i)?.end ?? i + 1;
-			continue;
-		}
-		i += key.length;
-		let val;
-		let j = i;
-		while (j < raw.length && isWhitespace(raw[j])) j++;
-		if (j > i) {
-			const quoted = readQuoted(raw, j);
-			const digits = quoted ? null : matchAt(DIGITS_RE, raw, j);
-			if (quoted) {
-				val = quoted.value;
-				i = quoted.end;
-			} else if (digits) {
-				val = digits;
-				i = j + digits.length;
-			}
-		}
-		switch (key) {
-			case "goto":
-				options.goto = val;
-				break;
-			case "dialog":
-				options.dialog = val;
-				break;
-			case "run":
-				options.run = val;
-				break;
-			case "name":
-				options.name = val;
-				break;
-			case "priority":
-				options.priority = val ? Number(val) : 0;
-				break;
-			case "once":
-				options.once = true;
-				break;
-		}
-	}
-	return {
-		condition: cond.value,
-		options
-	};
-}
-/**
-* Parse the watcher name of `{unwatch "name"}`: a quoted string, with the
-* same escapes as `{watch}`, or a bare name.
-*/
-function parseUnwatchName(rawArgs) {
-	const raw = rawArgs.trim();
-	return readWholeQuoted(raw) ?? raw.replace(/^['"]|['"]$/g, "");
-}
 defineMacro({
 	name: "watch",
-	render(props, ctx) {
+	parameters: [{
+		name: "condition",
+		type: "string",
+		required: true
+	}, {
+		name: "options",
+		type: "options",
+		parameters: [
+			{
+				name: "goto",
+				type: "string"
+			},
+			{
+				name: "dialog",
+				type: "string"
+			},
+			{
+				name: "run",
+				type: "string"
+			},
+			{
+				name: "name",
+				type: "string"
+			},
+			{
+				name: "priority",
+				type: "number"
+			},
+			{
+				name: "once",
+				type: "flag"
+			}
+		]
+	}],
+	render(_props, ctx) {
 		const { hooks } = ctx;
-		const parsed = parseWatchArgs(props.rawArgs);
-		if (!parsed) return null;
-		const { condition, options } = parsed;
+		const { condition, options } = ctx.args;
+		if (condition === void 0) return null;
 		const registered = hooks.useRef(false);
 		if (!registered.current) {
 			registered.current = true;
@@ -10425,8 +10549,13 @@ defineMacro({
 });
 defineMacro({
 	name: "unwatch",
-	render(props, ctx) {
-		const name = parseUnwatchName(props.rawArgs);
+	parameters: [{
+		name: "name",
+		type: "text",
+		required: true
+	}],
+	render(_props, ctx) {
+		const name = ctx.args.name ?? "";
 		const ran = ctx.hooks.useRef(false);
 		if (!ran.current) {
 			ran.current = true;