@rohal12/spindle 0.50.0 → 0.50.1

package/dist/pkg/story-variables.js

@@ -1,9 +1,767 @@
+//#region src/markup/tokenizer.ts
+/** Tag name must start with a letter (covers standard and custom elements). */
+var VALID_TAG_START = /[a-zA-Z]/;
+/** HTML void elements: never have children or a closing tag. */
+var HTML_VOID_TAGS = new Set([
+	"area",
+	"base",
+	"br",
+	"col",
+	"embed",
+	"hr",
+	"img",
+	"input",
+	"link",
+	"meta",
+	"param",
+	"source",
+	"track",
+	"wbr"
+]);
+/** Macros whose body is JavaScript source, kept verbatim instead of tokenized. */
+var RAW_BODY_MACROS = new Set(["do"]);
+/**
+* Parse a Twine link interior into display and target.
+* Supports: display|target, display->target, target<-display, plain
+*/
+function parseLink(inner) {
+	const pipeIdx = inner.indexOf("|");
+	if (pipeIdx !== -1) return {
+		display: inner.slice(0, pipeIdx).trim(),
+		target: inner.slice(pipeIdx + 1).trim()
+	};
+	const arrowIdx = inner.indexOf("->");
+	if (arrowIdx !== -1) return {
+		display: inner.slice(0, arrowIdx).trim(),
+		target: inner.slice(arrowIdx + 2).trim()
+	};
+	const revIdx = inner.indexOf("<-");
+	if (revIdx !== -1) return {
+		target: inner.slice(0, revIdx).trim(),
+		display: inner.slice(revIdx + 2).trim()
+	};
+	const trimmed = inner.trim();
+	return {
+		display: trimmed,
+		target: trimmed
+	};
+}
+/**
+* Parse a macro opening: extract name and rawArgs.
+* e.g. "set $x = 5" → { name: "set", rawArgs: "$x = 5" }
+* e.g. "/if" → { name: "if", rawArgs: "", isClose: true }
+* e.g. "elseif $x > 3" → { name: "elseif", rawArgs: "$x > 3" }
+*/
+function parseMacroContent(content) {
+	const trimmed = content.trim();
+	const isClose = trimmed.startsWith("/");
+	const rest = isClose ? trimmed.slice(1) : trimmed;
+	const spaceIdx = rest.search(/\s/);
+	if (spaceIdx === -1) return {
+		name: rest,
+		rawArgs: "",
+		isClose
+	};
+	return {
+		name: rest.slice(0, spaceIdx),
+		rawArgs: rest.slice(spaceIdx + 1).trim(),
+		isClose
+	};
+}
+/**
+* Parse CSS selectors: .foo.bar#baz → { className: "foo bar", id: "baz" }
+* Scans .[a-zA-Z0-9_-]+ and #[a-zA-Z0-9_-]+ segments in any order.
+* Returns space-joined class string, last id wins, and position after last segment.
+*/
+function parseSelectors(input, startIdx) {
+	const classes = [];
+	let id = "";
+	let i = startIdx;
+	while (i < input.length && (input[i] === "." || input[i] === "#")) {
+		const prefix = input[i];
+		i++;
+		let name = "";
+		while (i < input.length) if (/[a-zA-Z0-9_-]/.test(input[i])) {
+			name += input[i];
+			i++;
+		} else if (input[i] === "{" && (input[i + 1] === "$" || input[i + 1] === "_" || input[i + 1] === "@")) {
+			const braceStart = i;
+			i += 2;
+			while (i < input.length && /[\w.]/.test(input[i])) i++;
+			if (i < input.length && input[i] === "}") {
+				i++;
+				name += input.slice(braceStart, i);
+			} else {
+				i = braceStart;
+				break;
+			}
+		} else break;
+		if (name) if (prefix === ".") classes.push(name);
+		else id = name;
+	}
+	return {
+		className: classes.join(" "),
+		id,
+		endIdx: i
+	};
+}
+/**
+* Parse HTML attributes from a string starting at position j.
+* Returns the attributes and the position after the last attribute.
+*/
+function parseHtmlAttributes(input, j) {
+	const attributes = {};
+	while (j < input.length) {
+		while (j < input.length && /\s/.test(input[j])) j++;
+		if (j >= input.length || input[j] === ">" || input[j] === "/" && input[j + 1] === ">") break;
+		const attrStart = j;
+		while (j < input.length && /[a-zA-Z0-9_\-:@]/.test(input[j])) j++;
+		const attrName = input.slice(attrStart, j);
+		if (!attrName) break;
+		if (input[j] === "=") {
+			j++;
+			if (input[j] === "\"" || input[j] === "'") {
+				const quote = input[j];
+				j++;
+				const valStart = j;
+				while (j < input.length) {
+					if (input[j] === "{") {
+						const closeIdx = scanBalancedBrace(input, j + 1);
+						if (closeIdx !== -1) {
+							j = closeIdx + 1;
+							continue;
+						}
+					} else if (input[j] === quote) break;
+					j++;
+				}
+				attributes[attrName] = input.slice(valStart, j);
+				if (j < input.length) j++;
+			} else {
+				const valStart = j;
+				while (j < input.length && /[^\s>]/.test(input[j])) j++;
+				attributes[attrName] = input.slice(valStart, j);
+			}
+		} else attributes[attrName] = "";
+	}
+	return {
+		attributes,
+		endIdx: j
+	};
+}
+/**
+* Skip a '…' or "…" string literal opening at i.
+* Returns the index just past the closing quote, or -1 if the string is
+* not closed on the same line (JS strings can't span lines unescaped).
+*/
+function skipQuoted(input, i) {
+	const quote = input[i];
+	let j = i + 1;
+	while (j < input.length) {
+		const c = input[j];
+		if (c === "\\") j += 2;
+		else if (c === quote) return j + 1;
+		else if (c === "\n") return -1;
+		else j++;
+	}
+	return -1;
+}
+/**
+* Skip a `…` template literal opening at i, including ${…} parts.
+* Returns the index just past the closing backtick, or -1 if unclosed.
+*/
+function skipTemplate(input, i) {
+	let j = i + 1;
+	while (j < input.length) {
+		const c = input[j];
+		if (c === "\\") j += 2;
+		else if (c === "`") return j + 1;
+		else if (c === "$" && input[j + 1] === "{") {
+			const closeIdx = scanBalancedBrace(input, j + 2);
+			if (closeIdx === -1) return -1;
+			j = closeIdx + 1;
+		} else j++;
+	}
+	return -1;
+}
+/**
+* A quote directly after a letter/digit is an apostrophe (don't), not a
+* string; after a backslash it is an escaped attribute delimiter (\").
+*/
+var NON_STRING_QUOTE_PREFIX = /[\p{L}\p{N}_\\]/u;
+/**
+* Scan for the balanced closing } starting at position i (just past the {).
+* Braces inside string and template literals are ignored. A quote that
+* can't start a string (apostrophe, escaped, unterminated) counts as text.
+* Returns the index of the closing } or -1 if unbalanced.
+*/
+function scanBalancedBrace(input, i) {
+	let depth = 1;
+	while (i < input.length) {
+		const c = input[i];
+		if (c === "{") depth++;
+		else if (c === "}") {
+			if (--depth === 0) return i;
+		} else if ((c === "\"" || c === "'") && !(i > 0 && NON_STRING_QUOTE_PREFIX.test(input[i - 1]))) {
+			const end = skipQuoted(input, i);
+			if (end !== -1) {
+				i = end;
+				continue;
+			}
+		} else if (c === "`") {
+			const end = skipTemplate(input, i);
+			if (end !== -1) {
+				i = end;
+				continue;
+			}
+		}
+		i++;
+	}
+	return -1;
+}
+/**
+* Single-pass tokenizer for Twine passage content.
+* Recognizes: [[links]], {$variable}, {_temporary}, {macroName args}
+*/
+function tokenize(input) {
+	const tokens = [];
+	let i = 0;
+	let textStart = 0;
+	function flushText(end) {
+		if (end > textStart) tokens.push({
+			type: "text",
+			value: input.slice(textStart, end),
+			start: textStart,
+			end
+		});
+	}
+	/**
+	* After an opening raw-body macro ({do}), emit everything up to the
+	* first {/name} as a single text token so JavaScript source is not
+	* parsed as markup. A literal "{/do}" inside the code would end it early.
+	* Without a closer, nothing is consumed and the AST builder reports it.
+	*/
+	function consumeRawBody(name, isClose) {
+		const lower = name.toLowerCase();
+		if (isClose || !RAW_BODY_MACROS.has(lower)) return;
+		const closeRe = new RegExp(`\\{/${lower}\\s*\\}`, "gi");
+		closeRe.lastIndex = i;
+		const m = closeRe.exec(input);
+		if (!m) return;
+		const closeStart = m.index;
+		const closeEnd = closeStart + m[0].length;
+		flushText(closeStart);
+		tokens.push({
+			type: "macro",
+			...parseMacroContent(input.slice(closeStart + 1, closeEnd - 1)),
+			start: closeStart,
+			end: closeEnd
+		});
+		i = closeEnd;
+		textStart = closeEnd;
+	}
+	while (i < input.length) {
+		if (input[i] === "\\" && (input[i + 1] === "{" || input[i + 1] === "}")) {
+			flushText(i);
+			tokens.push({
+				type: "text",
+				value: input[i + 1],
+				start: i,
+				end: i + 2
+			});
+			i += 2;
+			textStart = i;
+			continue;
+		}
+		if (input[i] === "[" && input[i + 1] === "[") {
+			flushText(i);
+			const start = i;
+			i += 2;
+			let className;
+			let id;
+			if (input[i] === "." || input[i] === "#") {
+				const parsed = parseSelectors(input, i);
+				className = parsed.className || void 0;
+				id = parsed.id || void 0;
+				i = parsed.endIdx;
+				if (input[i] === " ") i++;
+			}
+			let depth = 1;
+			const innerStart = i;
+			while (i < input.length && depth > 0) if (input[i] === "[" && input[i + 1] === "[") {
+				depth++;
+				i += 2;
+			} else if (input[i] === "]" && input[i + 1] === "]") {
+				depth--;
+				if (depth === 0) break;
+				i += 2;
+			} else i++;
+			if (depth !== 0) {
+				i = start + 2;
+				textStart = start;
+				continue;
+			}
+			const inner = input.slice(innerStart, i);
+			i += 2;
+			const { display, target } = parseLink(inner);
+			const linkToken = {
+				type: "link",
+				display,
+				target,
+				start,
+				end: i
+			};
+			if (className) linkToken.className = className;
+			if (id) linkToken.id = id;
+			tokens.push(linkToken);
+			textStart = i;
+			continue;
+		}
+		if (input[i] === "{") {
+			const start = i;
+			let nextChar = input[i + 1];
+			let className;
+			let id;
+			if (nextChar === "." || nextChar === "#") {
+				flushText(i);
+				const parsed = parseSelectors(input, i + 1);
+				className = parsed.className || void 0;
+				id = parsed.id || void 0;
+				let afterSelectors = parsed.endIdx;
+				if (input[afterSelectors] === " ") afterSelectors++;
+				const charAfter = input[afterSelectors];
+				if (charAfter === "$") {
+					i = afterSelectors + 1;
+					const nameStart = i;
+					while (i < input.length && /[\w.]/.test(input[i])) i++;
+					const name = input.slice(nameStart, i);
+					if (input[i] === "}") {
+						i++;
+						const token = {
+							type: "variable",
+							name,
+							scope: "variable",
+							start,
+							end: i
+						};
+						if (className) token.className = className;
+						if (id) token.id = id;
+						tokens.push(token);
+						textStart = i;
+						continue;
+					}
+					const closeIdx$ = scanBalancedBrace(input, nameStart);
+					if (closeIdx$ !== -1) {
+						const expression = input.slice(afterSelectors, closeIdx$);
+						i = closeIdx$ + 1;
+						const token = {
+							type: "expression",
+							expression,
+							start,
+							end: i
+						};
+						if (className) token.className = className;
+						if (id) token.id = id;
+						tokens.push(token);
+						textStart = i;
+						continue;
+					}
+					i = start + 1;
+					textStart = start;
+					continue;
+				}
+				if (charAfter === "_") {
+					i = afterSelectors + 1;
+					const nameStart = i;
+					while (i < input.length && /[\w.]/.test(input[i])) i++;
+					const name = input.slice(nameStart, i);
+					if (input[i] === "}") {
+						i++;
+						const token = {
+							type: "variable",
+							name,
+							scope: "temporary",
+							start,
+							end: i
+						};
+						if (className) token.className = className;
+						if (id) token.id = id;
+						tokens.push(token);
+						textStart = i;
+						continue;
+					}
+					const closeIdx_ = scanBalancedBrace(input, nameStart);
+					if (closeIdx_ !== -1) {
+						const expression = input.slice(afterSelectors, closeIdx_);
+						i = closeIdx_ + 1;
+						const token = {
+							type: "expression",
+							expression,
+							start,
+							end: i
+						};
+						if (className) token.className = className;
+						if (id) token.id = id;
+						tokens.push(token);
+						textStart = i;
+						continue;
+					}
+					i = start + 1;
+					textStart = start;
+					continue;
+				}
+				if (charAfter === "@") {
+					i = afterSelectors + 1;
+					const nameStart = i;
+					while (i < input.length && /[\w.]/.test(input[i])) i++;
+					const name = input.slice(nameStart, i);
+					if (input[i] === "}") {
+						i++;
+						const token = {
+							type: "variable",
+							name,
+							scope: "local",
+							start,
+							end: i
+						};
+						if (className) token.className = className;
+						if (id) token.id = id;
+						tokens.push(token);
+						textStart = i;
+						continue;
+					}
+					const closeIdx_at = scanBalancedBrace(input, nameStart);
+					if (closeIdx_at !== -1) {
+						const expression = input.slice(afterSelectors, closeIdx_at);
+						i = closeIdx_at + 1;
+						const token = {
+							type: "expression",
+							expression,
+							start,
+							end: i
+						};
+						if (className) token.className = className;
+						if (id) token.id = id;
+						tokens.push(token);
+						textStart = i;
+						continue;
+					}
+					i = start + 1;
+					textStart = start;
+					continue;
+				}
+				if (charAfter === "%") {
+					i = afterSelectors + 1;
+					const nameStart = i;
+					while (i < input.length && /[\w.]/.test(input[i])) i++;
+					const name = input.slice(nameStart, i);
+					if (input[i] === "}") {
+						i++;
+						const token = {
+							type: "variable",
+							name,
+							scope: "transient",
+							start,
+							end: i
+						};
+						if (className) token.className = className;
+						if (id) token.id = id;
+						tokens.push(token);
+						textStart = i;
+						continue;
+					}
+					const closeIdx_pct = scanBalancedBrace(input, nameStart);
+					if (closeIdx_pct !== -1) {
+						const expression = input.slice(afterSelectors, closeIdx_pct);
+						i = closeIdx_pct + 1;
+						const token = {
+							type: "expression",
+							expression,
+							start,
+							end: i
+						};
+						if (className) token.className = className;
+						if (id) token.id = id;
+						tokens.push(token);
+						textStart = i;
+						continue;
+					}
+					i = start + 1;
+					textStart = start;
+					continue;
+				}
+				if (charAfter !== void 0 && /[a-zA-Z]/.test(charAfter)) {
+					const contentStart = afterSelectors;
+					const closeIdx = scanBalancedBrace(input, contentStart);
+					if (closeIdx === -1) {
+						i = start + 1;
+						textStart = start;
+						continue;
+					}
+					const content = input.slice(contentStart, closeIdx);
+					i = closeIdx + 1;
+					const { name, rawArgs, isClose } = parseMacroContent(content);
+					const token = {
+						type: "macro",
+						name,
+						rawArgs,
+						isClose,
+						start,
+						end: i
+					};
+					if (className) token.className = className;
+					if (id) token.id = id;
+					tokens.push(token);
+					textStart = i;
+					consumeRawBody(name, isClose);
+					continue;
+				}
+				i = start + 1;
+				textStart = start;
+				continue;
+			}
+			if (nextChar === "$") {
+				flushText(i);
+				i += 2;
+				const nameStart = i;
+				while (i < input.length && /[\w.]/.test(input[i])) i++;
+				const name = input.slice(nameStart, i);
+				if (input[i] === "}") {
+					i++;
+					tokens.push({
+						type: "variable",
+						name,
+						scope: "variable",
+						start,
+						end: i
+					});
+					textStart = i;
+					continue;
+				}
+				const closeIdx = scanBalancedBrace(input, nameStart);
+				if (closeIdx !== -1) {
+					const expression = input.slice(start + 1, closeIdx);
+					i = closeIdx + 1;
+					tokens.push({
+						type: "expression",
+						expression,
+						start,
+						end: i
+					});
+					textStart = i;
+					continue;
+				}
+				i = start + 1;
+				textStart = start;
+				continue;
+			}
+			if (nextChar === "_") {
+				flushText(i);
+				i += 2;
+				const nameStart = i;
+				while (i < input.length && /[\w.]/.test(input[i])) i++;
+				const name = input.slice(nameStart, i);
+				if (input[i] === "}") {
+					i++;
+					tokens.push({
+						type: "variable",
+						name,
+						scope: "temporary",
+						start,
+						end: i
+					});
+					textStart = i;
+					continue;
+				}
+				const closeIdx = scanBalancedBrace(input, nameStart);
+				if (closeIdx !== -1) {
+					const expression = input.slice(start + 1, closeIdx);
+					i = closeIdx + 1;
+					tokens.push({
+						type: "expression",
+						expression,
+						start,
+						end: i
+					});
+					textStart = i;
+					continue;
+				}
+				i = start + 1;
+				textStart = start;
+				continue;
+			}
+			if (nextChar === "@") {
+				flushText(i);
+				i += 2;
+				const nameStart = i;
+				while (i < input.length && /[\w.]/.test(input[i])) i++;
+				const name = input.slice(nameStart, i);
+				if (input[i] === "}") {
+					i++;
+					tokens.push({
+						type: "variable",
+						name,
+						scope: "local",
+						start,
+						end: i
+					});
+					textStart = i;
+					continue;
+				}
+				const closeIdx = scanBalancedBrace(input, nameStart);
+				if (closeIdx !== -1) {
+					const expression = input.slice(start + 1, closeIdx);
+					i = closeIdx + 1;
+					tokens.push({
+						type: "expression",
+						expression,
+						start,
+						end: i
+					});
+					textStart = i;
+					continue;
+				}
+				i = start + 1;
+				textStart = start;
+				continue;
+			}
+			if (nextChar === "%") {
+				flushText(i);
+				i += 2;
+				const nameStart = i;
+				while (i < input.length && /[\w.]/.test(input[i])) i++;
+				const name = input.slice(nameStart, i);
+				if (input[i] === "}") {
+					i++;
+					tokens.push({
+						type: "variable",
+						name,
+						scope: "transient",
+						start,
+						end: i
+					});
+					textStart = i;
+					continue;
+				}
+				const closeIdx = scanBalancedBrace(input, nameStart);
+				if (closeIdx !== -1) {
+					const expression = input.slice(start + 1, closeIdx);
+					i = closeIdx + 1;
+					tokens.push({
+						type: "expression",
+						expression,
+						start,
+						end: i
+					});
+					textStart = i;
+					continue;
+				}
+				i = start + 1;
+				textStart = start;
+				continue;
+			}
+			if (nextChar !== void 0 && (nextChar === "/" || /[a-zA-Z]/.test(nextChar))) {
+				flushText(i);
+				const contentStart = i + 1;
+				const closeIdx = scanBalancedBrace(input, contentStart);
+				if (closeIdx === -1) {
+					i = start + 1;
+					textStart = start;
+					continue;
+				}
+				const content = input.slice(contentStart, closeIdx);
+				i = closeIdx + 1;
+				const { name, rawArgs, isClose } = parseMacroContent(content);
+				tokens.push({
+					type: "macro",
+					name,
+					rawArgs,
+					isClose,
+					start,
+					end: i
+				});
+				textStart = i;
+				consumeRawBody(name, isClose);
+				continue;
+			}
+			i++;
+			continue;
+		}
+		if (input[i] === "<") {
+			const start = i;
+			let j = i + 1;
+			const isClose = input[j] === "/";
+			if (isClose) j++;
+			const tagStart = j;
+			while (j < input.length && /[a-zA-Z0-9-]/.test(input[j])) j++;
+			const tag = input.slice(tagStart, j);
+			const tagLower = tag.toLowerCase();
+			if (tag && VALID_TAG_START.test(tag[0])) if (isClose) {
+				while (j < input.length && /\s/.test(input[j])) j++;
+				if (input[j] === ">") {
+					j++;
+					flushText(start);
+					if (HTML_VOID_TAGS.has(tagLower)) {
+						textStart = j;
+						i = j;
+						continue;
+					}
+					tokens.push({
+						type: "html",
+						tag,
+						attributes: {},
+						isClose: true,
+						isSelfClose: false,
+						start,
+						end: j
+					});
+					textStart = j;
+					i = j;
+					continue;
+				}
+			} else {
+				const parsed = parseHtmlAttributes(input, j);
+				j = parsed.endIdx;
+				let isSelfClose = HTML_VOID_TAGS.has(tagLower);
+				if (input[j] === "/") {
+					isSelfClose = true;
+					j++;
+				}
+				if (input[j] === ">") {
+					j++;
+					flushText(start);
+					tokens.push({
+						type: "html",
+						tag,
+						attributes: parsed.attributes,
+						isClose: false,
+						isSelfClose,
+						start,
+						end: j
+					});
+					textStart = j;
+					i = j;
+					continue;
+				}
+			}
+			i++;
+			continue;
+		}
+		i++;
+	}
+	flushText(input.length);
+	return tokens;
+}
+//#endregion
 //#region src/story-variables.ts
 function declarationRegex(sigil) {
 	const escaped = sigil.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 	return new RegExp(`^${escaped}(\\w+)\\s*=\\s*(.+)$`);
 }
 var VAR_REF_RE = /\$(\w+(?:\.\w+)*)/g;
+/** `{` followed by a sigil starts an interpolation block inside literal text. */
+var INTERP_START_RE = /^[$_@%]\w/;
+/** Quoted first argument of an input macro naming a story variable. */
+var QUOTED_VAR_ARG_RE = /^["']\$(\w+(?:\.\w+)*)["']?$/;
 var FOR_LOCAL_RE = /\{for\s+@(\w+)(?:\s*,\s*@(\w+))?\s+of\b/g;
 var VALID_VAR_TYPES = new Set([
 	"number",
@@ -95,21 +853,155 @@ function validateRef(ref, schema, forLocals) {
 	return null;
 }
 /**
+* Built-in input macros whose first argument names the bound story variable,
+* quoted or not (e.g. `{textbox "$name"}`).
+*/
+var BUILTIN_STORE_VAR_MACROS = [
+	"checkbox",
+	"cycle",
+	"listbox",
+	"numberbox",
+	"radiobutton",
+	"textarea",
+	"textbox"
+];
+/** Report every `$var.path` in a code segment free of strings/comments. */
+function scanRefs(segment, onRef) {
+	for (const match of segment.matchAll(VAR_REF_RE)) onRef(match[1]);
+}
+/** Index of the quote closing the string opened at `start` (or the end). */
+function findClosingQuote(code, start) {
+	const quote = code[start];
+	let i = start + 1;
+	while (i < code.length && code[i] !== quote) i += code[i] === "\\" ? 2 : 1;
+	return Math.min(i, code.length);
+}
+/**
+* Scan literal text (string contents, HTML attribute values) for `{$…}`
+* interpolation blocks, which interpolating macros and HTML attributes
+* resolve at runtime. A bare `$word` in literal text is not a reference.
+*/
+function scanInterpolations(text, onRef) {
+	let i = text.indexOf("{");
+	while (i !== -1) {
+		const next = INTERP_START_RE.test(text.slice(i + 1, i + 3)) ? scanCode(text, i + 1, onRef, true) : i + 1;
+		i = text.indexOf("{", next);
+	}
+}
+/**
+* Scan a template literal starting just after its opening backtick: literal
+* parts are text, `${…}` parts are code. Returns the index just past the
+* closing backtick.
+*/
+function scanTemplate(code, start, onRef) {
+	let i = start;
+	let textStart = start;
+	while (i < code.length) {
+		const ch = code[i];
+		if (ch === "\\") i += 2;
+		else if (ch === "`") {
+			scanInterpolations(code.slice(textStart, i), onRef);
+			return i + 1;
+		} else if (ch === "$" && code[i + 1] === "{") {
+			scanInterpolations(code.slice(textStart, i), onRef);
+			i = textStart = scanCode(code, i + 2, onRef, true);
+		} else i++;
+	}
+	scanInterpolations(code.slice(textStart), onRef);
+	return code.length;
+}
+/**
+* Report `$var` references in JavaScript code. Like the string-aware
+* expression transformer, sigils inside string literals are left alone while
+* template-literal `${…}` parts are code; comments are skipped too. When
+* `nested`, stops at the `}` closing the enclosing block and returns the index
+* just past it.
+*/
+function scanCode(code, start, onRef, nested = false) {
+	let i = start;
+	let segStart = start;
+	let depth = 0;
+	while (i < code.length) {
+		const ch = code[i];
+		const next = code[i + 1];
+		const isComment = ch === "/" && (next === "/" || next === "*");
+		if (ch === "\"" || ch === "'" || ch === "`" || isComment) {
+			scanRefs(code.slice(segStart, i), onRef);
+			if (ch === "`") i = scanTemplate(code, i + 1, onRef);
+			else if (isComment) {
+				const close = code.indexOf(next === "/" ? "\n" : "*/", i + 2);
+				i = close === -1 ? code.length : next === "/" ? close : close + 2;
+			} else {
+				const close = findClosingQuote(code, i);
+				scanInterpolations(code.slice(i + 1, close), onRef);
+				i = Math.min(close + 1, code.length);
+			}
+			segStart = i;
+			continue;
+		}
+		if (nested && ch === "{") depth++;
+		else if (nested && ch === "}" && depth-- === 0) {
+			scanRefs(code.slice(segStart, i), onRef);
+			return i + 1;
+		}
+		i++;
+	}
+	scanRefs(code.slice(segStart), onRef);
+	return code.length;
+}
+/**
+* Report the `$var` references a passage evaluates at runtime: `{$var}`
+* displays, `{$expr}` expressions, macro arguments and `{do}` bodies (as
+* code), quoted variable names bound by input macros, and `{$…}`
+* interpolations in HTML attributes. Prose is literal text and not scanned.
+*/
+function collectPassageRefs(content, storeVarMacros, onRef) {
+	const tokens = tokenize(content);
+	for (let t = 0; t < tokens.length; t++) {
+		const token = tokens[t];
+		if (token.type === "variable") {
+			if (token.scope === "variable" && token.name) onRef(token.name);
+		} else if (token.type === "expression") scanCode(token.expression, 0, onRef);
+		else if (token.type === "html") for (const value of Object.values(token.attributes)) scanInterpolations(value, onRef);
+		else if (token.type === "macro" && !token.isClose) {
+			scanCode(token.rawArgs, 0, onRef);
+			if (storeVarMacros.has(token.name.toLowerCase())) {
+				const first = token.rawArgs.trim().split(/\s+/)[0] ?? "";
+				const quoted = QUOTED_VAR_ARG_RE.exec(first);
+				if (quoted) onRef(quoted[1]);
+			}
+			if (token.name === "do") {
+				let close = t + 1;
+				while (close < tokens.length) {
+					const c = tokens[close];
+					if (c.type === "macro" && c.isClose && c.name === "do") break;
+					close++;
+				}
+				if (close < tokens.length) {
+					scanCode(content.slice(token.end, tokens[close].start), 0, onRef);
+					t = close;
+				}
+			}
+		}
+	}
+}
+/**
 * Scan all passages for $var references, check against schema.
 * Returns list of error messages (empty = valid).
+*
+* `storeVarMacros` lists the input macros whose first argument names a bound
+* variable; it defaults to the built-in ones.
 */
-function validatePassages(passages, schema) {
+function validatePassages(passages, schema, storeVarMacros = BUILTIN_STORE_VAR_MACROS) {
 	const errors = [];
+	const storeVarSet = new Set(Array.from(storeVarMacros, (m) => m.toLowerCase()));
 	for (const [name, passage] of passages) {
 		if (name === "StoryVariables" || name === "StoryTransients") continue;
 		const forLocals = extractForLocals(passage.content);
-		let match;
-		VAR_REF_RE.lastIndex = 0;
-		while ((match = VAR_REF_RE.exec(passage.content)) !== null) {
-			const ref = match[1];
+		collectPassageRefs(passage.content, storeVarSet, (ref) => {
 			const error = validateRef(ref, schema, forLocals);
 			if (error) errors.push(`Passage "${name}": ${error}`);
-		}
+		});
 	}
 	return errors;
 }