@tikoci/centrs 0.1.4 → 0.1.7

package/src/explain/pathresolve.ts

@@ -90,7 +90,7 @@
  * certainty, because R4 has it REPLACE the context rather than extend it.
  */
 
-import { scopeBlocks, scopeBodies } from "./blocks.ts";
+import { type ScopeBlock, scopeBlocksIn } from "./blocks.ts";
 import { commandVerbIndex } from "./catalog.ts";
 import {
 	type Defect,
@@ -101,13 +101,19 @@ import {
 import { isKnownMenuPath } from "./is-known-menu.ts";
 import {
 	braceStartsStatements,
+	canRetainStatementIndex,
 	hashStartsHardError,
 	scopeNameFromMasked,
 } from "./scope-brace.ts";
 import {
-	maskComments,
+	documentRange,
+	type MaskedRange,
+	nestedRange,
+	rangeAt,
 	type SegmentResult,
 	scanQuotedString,
+	scanStringInterpolation,
+	segmentScopeBody,
 	segmentStatements,
 } from "./segment.ts";
 import { VERBS } from "./verbs.ts";
@@ -159,6 +165,29 @@ function asciiWords(text: string): string[] {
 	return trimmed.length === 0 ? [] : trimmed.split(ASCII_WHITESPACE);
 }
 
+/**
+ * The same words, yielded one at a time.
+ *
+ * For the readers that STOP at the first word which is not a path segment — the
+ * leading run, and the unreadable-menu test. A statement's text carries its
+ * whole nested `do={…}` subtree, so splitting all of it to look at the first
+ * two words was work repeated once per enclosing level (#322). Equivalent to
+ * {@link asciiWords} by construction: a trim followed by a split on runs of
+ * ASCII whitespace is exactly the maximal non-whitespace runs.
+ */
+function* asciiWordsIter(text: string): Generator<string> {
+	let i = 0;
+	while (i < text.length) {
+		if (isAsciiWhitespace(text[i])) {
+			i++;
+			continue;
+		}
+		const start = i;
+		while (i < text.length && !isAsciiWhitespace(text[i])) i++;
+		yield text.slice(start, i);
+	}
+}
+
 function isAbsolutePathToken(token: string): boolean {
 	if (!token.startsWith("/")) return false;
 	const parts = token.split("/").filter(Boolean);
@@ -182,16 +211,87 @@ const MAX_DEPTH = 256;
  * statement must never yield a confident command, so the resolver degrades it
  * to `unresolved` and does not descend into it. Statement-local; the
  * segmenter's document-level defects are surfaced separately on the envelope.
+ *
+ * Reads a RANGE of the document's own comment mask rather than masking the
+ * statement's text, which carries its whole nested subtree (#322).
  */
-function structuralDefect(text: string): string | null {
-	// Mask comments so a `#`-comment `}`/`)` is not counted as a real delimiter.
-	const masked = maskComments(text);
+interface StructuralIndex {
+	wellNested: boolean;
+	hardHashes: number[];
+}
+
+let recentStructuralText: string | undefined;
+let recentStructuralIndex: StructuralIndex | undefined;
+
+function structuralIndex(masked: string): StructuralIndex {
+	if (recentStructuralText === masked && recentStructuralIndex !== undefined)
+		return recentStructuralIndex;
+
+	let wellNested = true;
+	const hardHashes: number[] = [];
 	const openOf: Record<string, string> = { ")": "(", "]": "[", "}": "{" };
 	const stack: { char: string; statements: boolean }[] = [];
 	for (let i = 0; i < masked.length; i++) {
 		const c = masked[i];
 		if (c === '"') {
 			const str = scanQuotedString(masked, i);
+			if (!str.closed) wellNested = false;
+			i = str.end - 1;
+			continue;
+		}
+		if (
+			c === "#" &&
+			hashStartsHardError(masked, i, stack.at(-1)?.statements === false, 0)
+		)
+			hardHashes.push(i);
+		if (c === "(" || c === "[" || c === "{")
+			stack.push({
+				char: c,
+				statements:
+					c === "[" ||
+					(c === "{" &&
+						(stack.at(-1)?.statements ?? true) &&
+						braceStartsStatements(masked, i, 0)),
+			});
+		else if (c === ")" || c === "]" || c === "}") {
+			if (stack.pop()?.char !== openOf[c]) wellNested = false;
+		}
+	}
+	if (stack.length > 0) wellNested = false;
+	const index = { wellNested, hardHashes };
+	if (canRetainStatementIndex(masked)) {
+		recentStructuralText = masked;
+		recentStructuralIndex = index;
+	}
+	return index;
+}
+
+function structuralDefectIn(range: MaskedRange): string | null {
+	// The document mask makes comments opaque before this shared topology pass.
+	const index = structuralIndex(range.masked);
+	if (!index.wellNested) return structuralDefectByScan(range);
+	const defects = index.hardHashes;
+	let lo = 0;
+	let hi = defects.length;
+	while (lo < hi) {
+		const mid = (lo + hi) >>> 1;
+		if ((defects[mid] as number) < range.start) lo = mid + 1;
+		else hi = mid;
+	}
+	const defect = defects[lo];
+	return defect !== undefined && defect < range.end
+		? "structural defect: invalid unquoted hash"
+		: null;
+}
+
+function structuralDefectByScan(range: MaskedRange): string | null {
+	const { masked, start: lo, end: hi } = range;
+	const openOf: Record<string, string> = { ")": "(", "]": "[", "}": "{" };
+	const stack: { char: string; statements: boolean }[] = [];
+	for (let i = lo; i < hi; i++) {
+		const c = masked[i];
+		if (c === '"') {
+			const str = scanQuotedString(masked, i, hi);
 			if (!str.closed)
 				return "structural defect: unbalanced delimiter or string";
 			i = str.end - 1;
@@ -199,7 +299,7 @@ function structuralDefect(text: string): string | null {
 		}
 		if (
 			c === "#" &&
-			hashStartsHardError(masked, i, stack.at(-1)?.statements === false)
+			hashStartsHardError(masked, i, stack.at(-1)?.statements === false, lo)
 		)
 			return "structural defect: invalid unquoted hash";
 		if (c === "(" || c === "[" || c === "{")
@@ -209,7 +309,7 @@ function structuralDefect(text: string): string | null {
 					c === "[" ||
 					(c === "{" &&
 						(stack.at(-1)?.statements ?? true) &&
-						braceStartsStatements(masked, i)),
+						braceStartsStatements(masked, i, lo)),
 			});
 		else if (c === ")" || c === "]" || c === "}") {
 			if (stack.pop()?.char !== openOf[c])
@@ -229,11 +329,14 @@ function structuralDefect(text: string): string | null {
 const CONTEXT_LOST = "context lost to an earlier unreadable statement";
 
 /** R11 — a directive written without its colon, told by its scope block. */
-function isBareDirective(trimmed: string): boolean {
+function isBareDirective(text: string, range: MaskedRange): boolean {
+	const start = trimmedStart(text, 0, text.length);
+	const end = trimmedEnd(text, start, text.length);
+	const trimmed = text.slice(start, end);
 	return (
 		!trimmed.startsWith(":") &&
 		!trimmed.startsWith("/") &&
-		scopeBodies(trimmed).length > 0
+		scopeBlocksIn(nestedRange(range, start, end)).length > 0
 	);
 }
 
@@ -242,9 +345,9 @@ function isBareDirective(trimmed: string): boolean {
  * context? Mirrors `canonicalPath`'s `base` exactly — absolute, `:` directive,
  * or bare directive (R11) all resolve at the root.
  */
-function isContextIndependent(text: string): boolean {
+function isContextIndependent(text: string, range: MaskedRange): boolean {
 	const t = trimAscii(text);
-	return t.startsWith(":") || t.startsWith("/") || isBareDirective(t);
+	return t.startsWith(":") || t.startsWith("/") || isBareDirective(text, range);
 }
 
 /**
@@ -254,9 +357,9 @@ function isContextIndependent(text: string): boolean {
  * at the root but hands its body the context in force (R5), so `:foreach … do={
  * add … }` still depends on an upstream context its own path does not.
  */
-function isBodyContextIndependent(text: string): boolean {
+function isBodyContextIndependent(text: string, range: MaskedRange): boolean {
 	const t = trimAscii(text);
-	return t.startsWith("/") || isBareDirective(t);
+	return t.startsWith("/") || isBareDirective(text, range);
 }
 
 /**
@@ -287,7 +390,7 @@ function isUnreadablePath(text: string): boolean {
 	if (t.length === 0) return false;
 	// A head that is not path-shaped names no menu.
 	if (/^[$[("':]/.test(t)) return false;
-	for (const word of asciiWords(t)) {
+	for (const word of asciiWordsIter(t)) {
 		// Arguments begin: everything before this was readable. A `$` word
 		// STANDING ALONE is a positional operand (`get $item time`), not a path
 		// segment — only a `$` slash-joined inside a word is a menu segment.
@@ -340,12 +443,16 @@ function isUnreadableAbsolute(text: string): boolean {
  * anchors nothing, in EITHER spelling: `statementPath` derives a base from a
  * relative one too (`route/$verb remove [find]` yields `<ctx>/route/$verb`).
  */
-function handsKnownContext(text: string, contextCertain: boolean): boolean {
+function handsKnownContext(
+	text: string,
+	contextCertain: boolean,
+	range: MaskedRange,
+): boolean {
 	// Either spelling of an unreadable menu anchors nothing. `statementPath`
 	// derives a base from a RELATIVE one too (`route/$verb remove [find]` yields
 	// `<ctx>/route/$verb`), so this cannot test only the absolute form.
 	if (isUnreadableAbsolute(text) || isUnreadablePath(text)) return false;
-	return contextCertain || isBodyContextIndependent(text);
+	return contextCertain || isBodyContextIndependent(text, range);
 }
 
 /** A re-constituted `[…]` command substitution (Q3). */
@@ -381,6 +488,30 @@ export interface Resolution {
 	 * {@link Loc}.
 	 */
 	span: Span;
+	/**
+	 * Where {@link inner} itself sits, in the same document byte space.
+	 *
+	 * Not derivable from `span`: the two bracket spellings do not agree on what
+	 * `span` covers. `collectBrackets` spans `[…]`, so `inner` starts one byte
+	 * in; `scanInterpolations` spans `$[…]` **from the sigil** (that `$` is part
+	 * of the substitution), so it starts two. `inner` is also trimmed, so any
+	 * leading whitespace shifts it further right again. A consumer that guessed
+	 * `span.start + 1` therefore read one byte early on every interpolated
+	 * substitution and, finding the text did not match, silently dropped the
+	 * resolution — which is how a `$[…]` inside a string lost its path tokens to
+	 * the string fill (#325). Widens with `span` when interior offsets cannot be
+	 * mapped, so a consumer must still check the slice against `inner`.
+	 */
+	innerSpan: Span;
+}
+
+const resolutionRanges = new WeakMap<Resolution, MaskedRange>();
+
+/** The exact masked view used to read one resolution's inner text. */
+export function rangeForResolution(
+	resolution: Resolution,
+): MaskedRange | undefined {
+	return resolutionRanges.get(resolution);
 }
 
 /** The canonical path of one statement in source order (Q4). */
@@ -505,6 +636,12 @@ interface Located {
 	text: string;
 	span: Span;
 	loc: Loc;
+	/**
+	 * This statement as a range of the document, with the document's comment
+	 * mask. Every reader that would otherwise re-mask `text` — which carries the
+	 * whole nested subtree — takes this instead (#322).
+	 */
+	range: MaskedRange;
 }
 
 /**
@@ -517,6 +654,7 @@ interface Located {
 function locate(
 	segmented: SegmentResult,
 	loc: Loc,
+	parent: MaskedRange | null,
 ): { units: Located[]; defects: Defect[] } {
 	const units = segmented.segments.map((s) => {
 		const span = spanIn(loc, s.start, s.end);
@@ -531,6 +669,15 @@ function locate(
 				loc.base < 0 || !asciiOnly
 					? { base: -1, fallback: span }
 					: { base: loc.base + s.start, fallback: span },
+			// A statement is a range of its parent whenever the parent offered one
+			// AND the text just segmented was pure ASCII — the only case in which
+			// `s.start`/`s.end`, which are analyzed BYTES, are also JS string
+			// indices into it. Decided per level, so one non-ASCII body drops just
+			// its own subtree back to a mask of its own, exactly as before (#322).
+			range:
+				parent !== null && segmented.ascii
+					? nestedRange(parent, s.start, s.end)
+					: documentRange(s.text),
 		};
 	});
 	// STRUCTURAL defects only. `segmentStatements` merges `coordinateDefects`
@@ -553,6 +700,30 @@ function locate(
  */
 const DOCUMENT_LOC: Loc = { base: 0, fallback: { start: 0, end: 0 } };
 
+/**
+ * The document-wide masked range a walk descends through, or null.
+ *
+ * Null for a non-ASCII document: the walk's offsets are analyzed BYTES, and
+ * only in an all-ASCII document is such an offset also a JS string index. There
+ * every level re-derives its own mask, which is what every level did before
+ * (#322) — the anchored reading is a fast path, never a second answer.
+ */
+function rootRange(text: string, segmented: SegmentResult): MaskedRange | null {
+	return segmented.ascii ? documentRange(text, true) : null;
+}
+
+/**
+ * A scope body as a range of the statement that carries it.
+ *
+ * `ScopeBlock.start` is a JS index into the statement's text by construction —
+ * `scopeBlocksIn` walks the mask, which is code-unit-for-code-unit with it — so
+ * this needs no ASCII test of its own. Whether the body's own STATEMENTS may
+ * then be nested is decided by `locate`, against that body's segmentation.
+ */
+function bodyRange(range: MaskedRange, block: ScopeBlock): MaskedRange {
+	return nestedRange(range, block.start, block.start + block.body.length);
+}
+
 /** Q3 — resolve every `[…]` command substitution in `text`. */
 export function resolveDocument(text: string): DocumentAnalysis {
 	// Segment ONCE and hand the result to `locate` — `containsWrite` calls both
@@ -564,7 +735,7 @@ export function resolveDocument(text: string): DocumentAnalysis {
 	// substring's coordinate space.
 	const defects: Defect[] = [...segmented.defects];
 	const resolutions: Resolution[] = [];
-	const top = locate(segmented, DOCUMENT_LOC);
+	const top = locate(segmented, DOCUMENT_LOC, rootRange(text, segmented));
 	defects.push(...top.defects);
 	walk(top.units, "/", resolutions, 0, defects, true);
 	return { resolutions, defects: mergeDefects(defects) };
@@ -581,9 +752,9 @@ function walk(
 	let ctx = context;
 	let certain = contextCertain;
 	for (const unit of units) {
-		const { text, loc } = unit;
+		const { text, loc, range } = unit;
 		// R4 — a menu-navigation statement moves the document context.
-		const nav = menuNavPath(text, ctx);
+		const nav = menuNavPath(text, ctx, range);
 		if (nav !== null) {
 			const relative = !trimAscii(text).startsWith("/");
 			// A `..` read against an unknown context stays unknown; an absolute
@@ -597,26 +768,26 @@ function walk(
 		// bracket path and is not descended. It may have been a navigation, so the
 		// context after it is unknown (Q14 C3b, the same contract the statement
 		// walk applies — these two walks must move in lockstep).
-		if (structuralDefect(text) !== null) {
+		if (structuralDefectIn(range) !== null) {
 			certain = false;
 			continue;
 		}
 		// #235 — a relative bare-word that abstained (neither table) poisons
 		// downstream context, so the next relative statement cannot fabricate.
-		const poisonAbstention = isAbstainedRelativeNav(text, ctx);
+		const poisonAbstention = isAbstainedRelativeNav(text, ctx, range);
 		// R3 — the statement's own path is the context its brackets see.
-		const stmtCtx = statementPath(text, ctx);
+		const stmtCtx = statementPath(text, ctx, range);
 		// Derived BEFORE the poison, from the certainty in force at this statement:
 		// `handsKnownContext` answers about the context this statement HANDS DOWN,
 		// which its own unreadability already governs. An abstained nav poisons
 		// what follows, so its own body must already be uncertain.
 		const stmtCertain = poisonAbstention
 			? false
-			: handsKnownContext(text, certain);
+			: handsKnownContext(text, certain, range);
 		if (isUnreadableAbsolute(text) || poisonAbstention) certain = false;
-		collectBrackets(text, stmtCtx, 0, out, defects, stmtCertain, loc);
+		collectBrackets(range, stmtCtx, 0, out, defects, stmtCertain, loc);
 		// R5 — block bodies inherit the context in force here.
-		for (const block of scopeBlocks(text)) {
+		for (const block of scopeBlocksIn(range)) {
 			if (blockDepth >= MAX_DEPTH) {
 				// The BLOCK that exceeded the limit, not the whole statement —
 				// narrowing regions is what this channel is for.
@@ -627,7 +798,11 @@ function walk(
 				continue;
 			}
 			const bodyLoc = nest(loc, block.start, unit.span);
-			const body = locate(segmentStatements(block.body), bodyLoc);
+			const body = locate(
+				segmentScopeBody(block.body, bodyRange(range, block)),
+				bodyLoc,
+				bodyRange(range, block),
+			);
 			defects.push(...body.defects);
 			walk(body.units, stmtCtx, out, blockDepth + 1, defects, stmtCertain);
 		}
@@ -640,7 +815,7 @@ export function resolveStatements(text: string): StatementAnalysis {
 	// As `resolveDocument`: coordinate facts come from the root only.
 	const defects: Defect[] = [...segmented.defects];
 	const statements: StatementResolution[] = [];
-	const top = locate(segmented, DOCUMENT_LOC);
+	const top = locate(segmented, DOCUMENT_LOC, rootRange(text, segmented));
 	defects.push(...top.defects);
 	walkStatements(top.units, "/", statements, 0, defects, true);
 	return { statements, defects: mergeDefects(defects) };
@@ -657,8 +832,8 @@ function walkStatements(
 	let ctx = context;
 	let certain = contextCertain;
 	for (const unit of units) {
-		const { text, span } = unit;
-		const nav = menuNavPath(text, ctx);
+		const { text, span, range } = unit;
+		const nav = menuNavPath(text, ctx, range);
 		if (nav !== null) {
 			// `..` ascends FROM the context, so it cannot be read while the context
 			// is unknown. A `/`-led navigation (and a bare `/`) REPLACES it (R4) and
@@ -691,7 +866,7 @@ function walkStatements(
 		// Q14 fail-closed — a malformed statement degrades to unresolved and is
 		// not descended; it does not move the context either. It may however have
 		// BEEN a navigation, so what the context now is becomes unknown.
-		const defectReason = structuralDefect(text);
+		const defectReason = structuralDefectIn(range);
 		if (defectReason !== null) {
 			out.push({
 				text,
@@ -708,17 +883,19 @@ function walkStatements(
 		// #235 — a relative bare-word that abstained (neither table) poisons
 		// downstream context. Capture before the push so the current statement's
 		// own `contextCertain` stays true while the following statements lose it.
-		const poisonAbstention = isAbstainedRelativeNav(text, ctx);
+		const poisonAbstention = isAbstainedRelativeNav(text, ctx, range);
 		// Q14 C3b — the cascade. A statement that CONSUMES the context cannot be
 		// resolved against a value the resolver has already admitted it lost.
 		// Applied to the RESOLUTION, not ahead of it, so a statement that would
 		// have refused on its own terms keeps its own — more specific — reason.
-		const resolved = canonicalPath(text, ctx);
+		const resolved = canonicalPath(text, ctx, range);
 		out.push({
 			text,
 			isNav: false,
 			context: ctx,
-			...(resolved.path !== null && !certain && !isContextIndependent(text)
+			...(resolved.path !== null &&
+			!certain &&
+			!isContextIndependent(text, range)
 				? { path: null, unresolved: CONTEXT_LOST }
 				: resolved),
 			contextCertain: certain,
@@ -729,12 +906,12 @@ function walkStatements(
 		// knowable, when the statement spells its path out or is a bare directive,
 		// and unknowable when the statement's own path could not be read. Same
 		// predicate and same order as the bracket walk, per the lockstep rule.
-		const stmtCtx = statementPath(text, ctx);
+		const stmtCtx = statementPath(text, ctx, range);
 		const bodyCertain = poisonAbstention
 			? false
-			: handsKnownContext(text, certain);
+			: handsKnownContext(text, certain, range);
 		if (isUnreadableAbsolute(text) || poisonAbstention) certain = false;
-		for (const block of scopeBlocks(text)) {
+		for (const block of scopeBlocksIn(range)) {
 			if (blockDepth >= MAX_DEPTH) {
 				defects.push({
 					code: "over-depth",
@@ -743,7 +920,11 @@ function walkStatements(
 				continue;
 			}
 			const bodyLoc = nest(unit.loc, block.start, span);
-			const body = locate(segmentStatements(block.body), bodyLoc);
+			const body = locate(
+				segmentScopeBody(block.body, bodyRange(range, block)),
+				bodyLoc,
+				bodyRange(range, block),
+			);
 			defects.push(...body.defects);
 			walkStatements(
 				body.units,
@@ -801,7 +982,11 @@ function walkStatements(
  * now disagree CONFIDENTLY rather than one of them refusing. The same test pins
  * the invariant for both rules.
  */
-function menuNavPath(text: string, ctx: string): string | null {
+function menuNavPath(
+	text: string,
+	ctx: string,
+	range: MaskedRange,
+): string | null {
 	const trimmed = trimAscii(text);
 	if (trimmed === "/") return "/";
 	if (/^\.\.(?:[ \t\r\n]|$)/.test(trimmed)) {
@@ -811,7 +996,7 @@ function menuNavPath(text: string, ctx: string): string | null {
 	}
 	if (!trimmed.startsWith("/")) {
 		// #235 R13 — relative bare-word menu navigation.
-		const reading = readRelativeBare(text, ctx);
+		const reading = readRelativeBare(text, ctx, range);
 		return reading?.kind === "nav" ? reading.path : null;
 	}
 	if (/[=[({"$]/.test(trimmed)) return null;
@@ -856,6 +1041,7 @@ type RelativeBareReading = { kind: "nav"; path: string } | { kind: "abstain" };
 function readRelativeBare(
 	text: string,
 	ctx: string,
+	range: MaskedRange,
 ): RelativeBareReading | null {
 	const trimmed = trimAscii(text);
 	if (
@@ -865,7 +1051,7 @@ function readRelativeBare(
 		trimmed.startsWith("$") ||
 		trimmed.startsWith("[") ||
 		trimmed.startsWith("(") ||
-		isBareDirective(trimmed)
+		isBareDirective(text, range)
 	)
 		return null;
 	// Whitespace and `/` are interchangeable on the device, so the run is read
@@ -893,13 +1079,18 @@ function readRelativeBare(
  * Presence in a table → nav; absence → abstain → poison downstream, so the
  * next relative statement cannot resolve against a context that may have moved.
  */
-function isAbstainedRelativeNav(text: string, ctx: string): boolean {
-	return readRelativeBare(text, ctx)?.kind === "abstain";
+function isAbstainedRelativeNav(
+	text: string,
+	ctx: string,
+	range: MaskedRange,
+): boolean {
+	return readRelativeBare(text, ctx, range)?.kind === "abstain";
 }
 
 function canonicalPath(
 	text: string,
 	ctx: string,
+	range: MaskedRange,
 ): { path: string | null; candidates?: string[]; unresolved?: string } {
 	const t = trimAscii(text);
 	if (t.startsWith("$") || t.startsWith("[") || t.startsWith("("))
@@ -913,10 +1104,11 @@ function canonicalPath(
 	// R11 — a scripting directive written WITHOUT its colon is still at the root.
 	// A statement that carries a SCOPE-valued block is a directive, because no
 	// menu command takes one — a schema-free tell.
-	const bareDirective = isBareDirective(t);
+	const bareDirective = isBareDirective(text, range);
 	// The cascade contract reads this same split to decide which statements may
 	// keep resolving once the context is lost, so both must come from one place.
-	const base = isContextIndependent(t) ? "/" : ctx;
+	const base =
+		t.startsWith(":") || t.startsWith("/") || bareDirective ? "/" : ctx;
 	// R7 — a variable segment anywhere in the leading run leaves the path
 	// unresolved, INCLUDING after a static word. `statementRun` drops the whole
 	// word carrying the variable, so `/ip route/$menu/remove` would otherwise
@@ -950,7 +1142,7 @@ function canonicalPath(
  */
 function statementRun(text: string): string[] {
 	const out: string[] = [];
-	for (const t of asciiWords(text)) {
+	for (const t of asciiWordsIter(text)) {
 		if (t.includes("=") || /^[[({"$:]/.test(t)) break;
 		const parts = t.split("/").filter((p) => p.length > 0);
 		if (parts.length === 0) continue;
@@ -965,22 +1157,22 @@ function statementRun(text: string): string[] {
  * [find …]` that is `/ip/route`: the leading path run minus its last token,
  * which is the verb (Q6's reading, right ~93.7% of the time).
  */
-function statementPath(text: string, ctx: string): string {
+function statementPath(text: string, ctx: string, range: MaskedRange): string {
 	const t = trimAsciiStart(text);
 	// R11 — a bare directive is at the root, so the context it hands its body is
 	// the root too, not `<ctx>/while`.
-	if (isBareDirective(trimAscii(t))) return "/";
+	if (isBareDirective(text, range)) return "/";
 	const lead = leadingRun(text);
 	if (lead.length === 0) return ctx;
 	// Same split `isBodyContextIndependent` reports to the cascade contract.
-	const base = isBodyContextIndependent(t) ? "/" : ctx;
+	const base = t.startsWith("/") ? "/" : ctx;
 	return joinPath(base, lead.slice(0, -1).join("/"));
 }
 
 /** Leading bare/path tokens, stopping at the first argument or group. */
 function leadingRun(text: string): string[] {
 	const out: string[] = [];
-	for (const t of asciiWords(text)) {
+	for (const t of asciiWordsIter(text)) {
 		if (t.includes("=") || /^[[({"$:]/.test(t)) break;
 		for (const part of t.split("/")) if (part.length > 0) out.push(part);
 		if (out.length === 0 && t === "/") out.push("");
@@ -1001,8 +1193,21 @@ function joinPath(base: string, rest: string): string {
 	return `/${stack.join("/")}`;
 }
 
+/**
+ * Q3's bracket scan over one range of a document.
+ *
+ * Reads `range.masked` and never `range.text`: comments hold no valid inner
+ * command (`#` mid-`[…]` is not statement-leading), so an inner command is the
+ * same text in either view, and the recursion already descended into masked
+ * slices before this took a range. What changed is who masks — the caller hands
+ * down the document's one mask instead of each level re-deriving its own over a
+ * subtree an inner level has already read (#322).
+ *
+ * Offsets are absolute, while `loc` stays anchored at the range start, so every
+ * `nest`/`spanIn` here passes a range-relative index.
+ */
 function collectBrackets(
-	text: string,
+	range: MaskedRange,
 	ctx: string,
 	depth: number,
 	out: Resolution[],
@@ -1011,33 +1216,30 @@ function collectBrackets(
 	loc: Loc,
 	inLiteral = false,
 ): void {
+	const { masked, start: lo, end: hi } = range;
 	// Bound the recursion (bracket nesting AND literal-brace descent) so
 	// untrusted deeply nested input abstains instead of overflowing the stack.
 	if (depth >= MAX_DEPTH) {
-		// `text` is empty when the nesting bottoms out on an empty body (`[]`),
-		// which `regionIn` widens rather than emitting a zero-width region.
-		defects.push({ code: "over-depth", ...regionIn(loc, 0, text.length) });
+		// The region is empty when the nesting bottoms out on an empty body
+		// (`[]`), which `regionIn` widens rather than emitting a zero-width one.
+		defects.push({ code: "over-depth", ...regionIn(loc, 0, hi - lo) });
 		return;
 	}
-	// Scan a comment-masked copy so a `#`-comment `[`/`{` is not treated as a
-	// substitution or scope. Comments never hold valid inner commands (`#` mid
-	// `[…]` is not statement-leading), so masked slices equal the originals.
-	const masked = maskComments(text);
-	for (let i = 0; i < masked.length; i++) {
+	for (let i = lo; i < hi; i++) {
 		const c = masked[i];
 		if (c === '"') {
 			// A string is opaque EXCEPT for `$[ … ]` interpolation, a real command
 			// substitution: `:put "$[:pick $ip 0 $n]"` lowers with `/pick` inside
 			// (topic-…/post-0003-snippet-01 @ 7.22.1).
-			const strEnd = stringEnd(masked, i);
+			const strEnd = stringEnd(masked, i, hi);
 			scanInterpolations(
-				masked.slice(i + 1, strEnd),
+				rangeAt(range, i + 1, strEnd),
 				ctx,
 				depth,
 				out,
 				defects,
 				contextCertain,
-				nest(loc, i + 1, loc.fallback),
+				nest(loc, i + 1 - lo, loc.fallback),
 			);
 			i = strEnd;
 			continue;
@@ -1046,69 +1248,98 @@ function collectBrackets(
 			// A literal body is a value (Q2), but can still contain command
 			// substitutions: `{[/terminal/inkey]}` lowers the bracket. Descend for
 			// brackets only; scope bodies are walked by walk().
-			const end = matchDelim(masked, i, "{", "}");
-			const body = masked.slice(i + 1, end);
-			const isScope = !inLiteral && scopeNameFromMasked(masked, i) !== null;
-			if (!isScope && (body.includes("[") || body.includes("{")))
+			const end = matchDelim(masked, i, "{", "}", hi);
+			const isScope = !inLiteral && scopeNameFromMasked(masked, i, lo) !== null;
+			if (!isScope && hasBracketOrBrace(masked, i + 1, end))
 				collectBrackets(
-					body,
+					rangeAt(range, i + 1, end),
 					ctx,
 					depth + 1,
 					out,
 					defects,
 					contextCertain,
-					nest(loc, i + 1, loc.fallback),
+					nest(loc, i + 1 - lo, loc.fallback),
 					true,
 				);
 			i = end;
 			continue;
 		}
 		if (c !== "[") continue;
-		const end = matchDelim(masked, i, "[", "]");
-		const inner = trimAscii(masked.slice(i + 1, end));
+		const end = matchDelim(masked, i, "[", "]", hi);
+		// `inner` is the trimmed region of `masked` starting at i+1; the leading
+		// whitespace trim shifts it further right.
+		const innerAt = trimmedStart(masked, i + 1, end);
+		const innerEnd = trimmedEnd(masked, innerAt, end);
+		const inner = masked.slice(innerAt, innerEnd);
 		// The span covers the whole `[…]`, closing bracket included.
-		out.push({
+		const resolution: Resolution = {
 			...resolveInner(inner, ctx, depth, contextCertain),
-			span: spanIn(loc, i, Math.min(end + 1, text.length)),
-		});
+			span: spanIn(loc, i - lo, Math.min(end + 1, hi) - lo),
+			innerSpan: spanIn(loc, innerAt - lo, innerEnd - lo),
+		};
+		out.push(resolution);
+		resolutionRanges.set(resolution, rangeAt(range, innerAt, innerEnd));
 		// R6 — nested brackets inherit from this one's resolution.
-		const nestedCtx = out[out.length - 1]?.path ?? ctx;
+		const nestedCtx = resolution.path ?? ctx;
 		collectBrackets(
-			inner,
+			rangeAt(range, innerAt, innerEnd),
 			nestedCtx,
 			depth + 1,
 			out,
 			defects,
-			nestedCertainty(out[out.length - 1], contextCertain),
-			// `inner` is the trimmed slice of `masked` starting at i+1; the leading
-			// whitespace trim shifts it further right.
-			nest(
-				loc,
-				i +
-					1 +
-					(masked.slice(i + 1, end).length -
-						trimAsciiStart(masked.slice(i + 1, end)).length),
-				loc.fallback,
-			),
+			nestedCertainty(resolution, contextCertain),
+			nest(loc, innerAt - lo, loc.fallback),
 		);
 		i = end;
 	}
 }
 
+/** First non-ASCII-whitespace index in `[start, end)`, or `end`. */
+function trimmedStart(text: string, start: number, end: number): number {
+	let i = start;
+	while (i < end && isAsciiWhitespace(text[i])) i++;
+	return i;
+}
+
+/** One past the last non-ASCII-whitespace index in `[start, end)`. */
+function trimmedEnd(text: string, start: number, end: number): number {
+	let i = end;
+	while (i > start && isAsciiWhitespace(text[i - 1])) i--;
+	return i;
+}
+
+/** Whether `[start, end)` holds a `[` or a `{` — the literal-descent test. */
+function hasBracketOrBrace(text: string, start: number, end: number): boolean {
+	for (let i = start; i < end; i++) {
+		const c = text[i];
+		if (c === "[" || c === "{") return true;
+	}
+	return false;
+}
+
 /**
  * Index of the closing quote of the string starting at `open`. Delegates to the
  * shared `scanQuotedString`, so a `$[…]` substitution carrying its own string
  * does not end the outer one early and cut `scanInterpolations`' body short
  * (#199).
  */
-function stringEnd(text: string, open: number): number {
-	const str = scanQuotedString(text, open);
-	return str.closed ? str.end - 1 : text.length;
+function stringEnd(
+	text: string,
+	open: number,
+	limit: number = text.length,
+): number {
+	const str = scanQuotedString(text, open, limit);
+	return str.closed ? str.end - 1 : limit;
 }
 
-/** `$[ … ]` command substitutions inside a string body. */
+/**
+ * `$[ … ]` command substitutions inside the string body `[lo, hi)`.
+ *
+ * As {@link collectBrackets}: offsets are absolute into the document mask and
+ * `loc` is anchored at `lo`.
+ */
 function scanInterpolations(
-	body: string,
+	range: MaskedRange,
 	ctx: string,
 	depth: number,
 	out: Resolution[],
@@ -1116,28 +1347,41 @@ function scanInterpolations(
 	contextCertain: boolean,
 	loc: Loc,
 ): void {
-	for (let i = 0; i < body.length - 1; i++) {
-		if (body[i] !== "$" || body[i + 1] !== "[") continue;
-		const end = matchDelim(body, i + 1, "[", "]");
-		const raw = body.slice(i + 2, end);
-		const inner = trimAscii(raw);
-		// Span the `$[…]` from its sigil through the closing bracket.
-		out.push({
-			...resolveInner(inner, ctx, depth, contextCertain),
-			span: spanIn(loc, i, Math.min(end + 1, body.length)),
-		});
-		collectBrackets(
+	const { text, start: lo, end: hi } = range;
+	for (let i = lo; i < hi - 1; i++) {
+		if (text[i] !== "$" || text[i + 1] !== "[") continue;
+		const scanned = scanStringInterpolation(text, i + 1, hi);
+		const end = scanned.end;
+		const innerAt = trimmedStart(text, i + 2, end);
+		const innerEnd = trimmedEnd(text, innerAt, end);
+		const inner = text.slice(innerAt, innerEnd);
+		const innerRange = rangeAt(
+			scanned.range,
+			innerAt - (i + 1),
+			innerEnd - (i + 1),
+		);
+		const maskedInner = innerRange.masked.slice(
+			innerRange.start,
+			innerRange.end,
+		);
+		// Span the `$[…]` from its sigil through the closing bracket; `innerSpan`
+		// is the two-byte-in start that difference makes non-derivable.
+		const resolution: Resolution = {
+			...resolveInner(maskedInner, ctx, depth, contextCertain),
 			inner,
-			out[out.length - 1]?.path ?? ctx,
+			span: spanIn(loc, i - lo, Math.min(end + 1, hi) - lo),
+			innerSpan: spanIn(loc, innerAt - lo, innerEnd - lo),
+		};
+		out.push(resolution);
+		resolutionRanges.set(resolution, innerRange);
+		collectBrackets(
+			innerRange,
+			resolution.path ?? ctx,
 			depth + 1,
 			out,
 			defects,
-			nestedCertainty(out[out.length - 1], contextCertain),
-			nest(
-				loc,
-				i + 2 + (raw.length - trimAsciiStart(raw).length),
-				loc.fallback,
-			),
+			nestedCertainty(resolution, contextCertain),
+			nest(loc, innerAt - lo, loc.fallback),
 		);
 		i = end;
 	}
@@ -1191,7 +1435,7 @@ function resolveInner(
 	ctx: string,
 	depth: number,
 	contextCertain: boolean,
-): Omit<Resolution, "span"> {
+): Omit<Resolution, "span" | "innerSpan"> {
 	const absolute = inner.startsWith("/");
 	const klass = classify(inner, absolute, depth);
 	if (klass === "cli-prompt-artifact")
@@ -1294,7 +1538,7 @@ function classify(inner: string, absolute: boolean, depth: number): string {
 	if (CLI_PROMPT_RE.test(trimAscii(inner))) return "cli-prompt-artifact";
 	if (depth > 0) return "nested-bracket";
 	if (absolute) return "absolute-inner-path";
-	const head = (asciiWords(inner)[0] ?? "").toLowerCase();
+	const head = (asciiWordsIter(inner).next().value ?? "").toLowerCase();
 	if (head.startsWith("$")) return "dynamic-invocation";
 	if (head.startsWith(":")) return "scripting-directive";
 	if (head === "find") return "bare-find";
@@ -1306,12 +1550,13 @@ function matchDelim(
 	start: number,
 	open: string,
 	close: string,
+	limit: number = text.length,
 ): number {
 	let depth = 0;
-	for (let i = start; i < text.length; i++) {
+	for (let i = start; i < limit; i++) {
 		const c = text[i];
 		if (c === '"') {
-			i = scanQuotedString(text, i).end - 1;
+			i = scanQuotedString(text, i, limit).end - 1;
 			continue;
 		}
 		if (c === open) depth++;
@@ -1320,5 +1565,5 @@ function matchDelim(
 			if (depth === 0) return i;
 		}
 	}
-	return text.length;
+	return limit;
 }