@reactra/babel-plugin 0.1.0-alpha.0

package/dist/preprocess/rewriters.js

@@ -0,0 +1,1391 @@
+// Per-keyword rewriters — Compiler §4 Pass 1.1 / DSL v2.
+//
+// Each rewriter consumes a starting token index and emits the spec-exact
+// `__reactra_*__()` marker call. Covers the full 24-keyword surface:
+// component keywords (state/derived/action/resource/effect/mount/ref/view/
+// await/uses/inject/errorBoundary/suspense), store keywords (input/preserved),
+// page keywords (param/query/meta/prefetch/transition), and service keywords
+// (provide/implements).
+import { skipTrivia } from "./lexer.js";
+import { guardTrailingLineComment, readBlockEnd, readBracketEnd, readCommandFetcherEnd, readParenEnd, readOptionalTypeAnnotation, readToStatementEnd, readToStatementEndStrict, slice, } from "./helpers.js";
+// ----------------------------------------------------------------------------
+// Shared helper: build the `__reactra_state__(name, value)` text fragment.
+//
+// Both `rewriteState` and `rewritePreserved` emit a state marker; factoring
+// here prevents the two call-sites from drifting independently (F7).
+// ----------------------------------------------------------------------------
+const emitStateMarker = (name, type, initText) => {
+    const value = type ? `(${initText}) as ${type}` : initText;
+    return `__reactra_state__("${name}", ${value})`;
+};
+// ----------------------------------------------------------------------------
+// state x = init      -> __reactra_state__("x", init)
+// state x: T = init   -> __reactra_state__("x", (init) as T)
+// state x: T          -> __reactra_state__("x", undefined as T | undefined)
+//
+// The no-init form (annotation present, no `=`) is valid per the locked v2
+// grammar (plan/reactra-dsl-v2-surface.md:138). No annotation and no init
+// is still invalid — return null and let the caller error.
+// ----------------------------------------------------------------------------
+export const rewriteState = (tokens, i) => {
+    const stateTok = tokens[i];
+    const nameIdx = skipTrivia(tokens, i + 1);
+    const nameTok = tokens[nameIdx];
+    if (!nameTok || nameTok.kind !== "ident")
+        return null;
+    const { type, next } = readOptionalTypeAnnotation(tokens, nameIdx + 1);
+    const eqIdx = skipTrivia(tokens, next);
+    if (tokens[eqIdx]?.text !== "=") {
+        // No initializer — only legal when a type annotation is present.
+        if (!type)
+            return null;
+        // readOptionalTypeAnnotation may include a trailing `;` in the type text
+        // when the annotation is on a single line and `;` precedes the newline.
+        const cleanType = type.replace(/;$/, "").trim();
+        // Find the last non-trivia token before `next` (the newline) so the span
+        // covers exactly the declaration including any `;` but NOT the trailing `\n`.
+        // This preserves the newline as a statement separator in the output.
+        let endIdx = next - 1;
+        while (endIdx > nameIdx &&
+            (tokens[endIdx]?.kind === "whitespace" ||
+                tokens[endIdx]?.kind === "comment-line" ||
+                tokens[endIdx]?.kind === "comment-block")) {
+            endIdx--;
+        }
+        return {
+            rewrite: {
+                span: { start: stateTok.start, end: tokens[endIdx].end },
+                text: `__reactra_state__("${nameTok.text}", undefined as ${cleanType} | undefined)`,
+            },
+            consumedUpTo: endIdx,
+        };
+    }
+    const initStart = skipTrivia(tokens, eqIdx + 1);
+    const endIdx = readToStatementEndStrict(tokens, initStart, {
+        keyword: "state",
+        name: nameTok.text,
+        startTok: stateTok,
+    });
+    const initText = slice(tokens, initStart, endIdx).trim();
+    return {
+        rewrite: {
+            span: { start: stateTok.start, end: tokens[endIdx].end },
+            text: emitStateMarker(nameTok.text, type ?? null, initText),
+        },
+        consumedUpTo: endIdx,
+    };
+};
+// ----------------------------------------------------------------------------
+// derived d = expr                    -> __reactra_derived__("d", () => (expr))
+// derived d = { …; return v }  (block) -> __reactra_derived__("d", () => (() => { …; return v })())
+// derived d = { a: 1 }         (object) -> __reactra_derived__("d", () => ({ a: 1 }))
+//
+// DSL v3.0 §2.2 (Compiler §4 Pass 1.1): a `{`-prefixed initialiser is a BLOCK when
+// its content contains a top-level `return` keyword or a top-level `;`; otherwise
+// it is an object literal. The block form lowers to an IIFE inside the thunk so
+// hover type = value type (not function), matching F3 of the shadow-fidelity spec.
+// A block body must end with a `return` to produce a value.
+//
+// Top-level detection: scan tokens between the outer `{` and its matching `}` at
+// brace-depth 0. We consider a token top-level when parenthesis/bracket/brace depth
+// is zero relative to the content (the outer braces are excluded). A `return` at
+// depth 0 → block. A `;` at depth 0 → block. Anything else (object properties,
+// arrow functions, template literals etc.) → object literal.
+// ----------------------------------------------------------------------------
+export const rewriteDerived = (tokens, i) => {
+    const startTok = tokens[i];
+    const nameIdx = skipTrivia(tokens, i + 1);
+    const nameTok = tokens[nameIdx];
+    if (!nameTok || nameTok.kind !== "ident")
+        return null;
+    const eqIdx = skipTrivia(tokens, nameIdx + 1);
+    if (tokens[eqIdx]?.text !== "=")
+        return null;
+    const exprStart = skipTrivia(tokens, eqIdx + 1);
+    // If the first token after `=` is `{`, decide block vs object literal.
+    if (tokens[exprStart]?.text === "{") {
+        const braceCloseIdx = readBlockEnd(tokens, exprStart);
+        const inner = tokens.slice(exprStart + 1, braceCloseIdx); // tokens between { and }
+        const isBlock = detectBlockDerived(inner);
+        const innerText = slice(tokens, exprStart + 1, braceCloseIdx - 1).trim();
+        const endIdx = braceCloseIdx;
+        let exprText;
+        if (isBlock) {
+            // Block form → IIFE: `() => (() => { …; return v })()`
+            exprText = `__reactra_derived__("${nameTok.text}", () => (() => { ${innerText} })())`;
+        }
+        else {
+            // Object literal form → wrap in parentheses so `() => ({…})` parses correctly
+            exprText = `__reactra_derived__("${nameTok.text}", () => ({ ${innerText} }))`;
+        }
+        return {
+            rewrite: {
+                span: { start: startTok.start, end: tokens[endIdx].end },
+                text: exprText,
+            },
+            consumedUpTo: endIdx,
+        };
+    }
+    // Non-`{` initialiser: plain expression
+    const endIdx = readToStatementEndStrict(tokens, exprStart, {
+        keyword: "derived",
+        name: nameTok.text,
+        startTok,
+    });
+    const exprText = slice(tokens, exprStart, endIdx).trim();
+    return {
+        rewrite: {
+            span: { start: startTok.start, end: tokens[endIdx].end },
+            text: `__reactra_derived__("${nameTok.text}", () => (${exprText}))`,
+        },
+        consumedUpTo: endIdx,
+    };
+};
+/**
+ * Scan a flat token list (the content between `{` and `}`) and return `true` when
+ * the content is a **statement block** (contains a top-level `return` keyword or a
+ * top-level `;`), or `false` for an object literal.
+ *
+ * "Top-level" means brace/bracket/paren depth = 0 within the inner token list.
+ * Template literals are opaque (lexed as a single token) so their content is not
+ * inspected. Arrow functions (`() => { … }`) contribute nested braces which are
+ * depth > 0 — their `return` / `;` does NOT trigger the block detection.
+ */
+const detectBlockDerived = (inner) => {
+    let depth = 0;
+    for (const tok of inner) {
+        if (tok.kind === "punct") {
+            if (tok.text === "(" || tok.text === "[" || tok.text === "{") {
+                depth++;
+            }
+            else if (tok.text === ")" || tok.text === "]" || tok.text === "}") {
+                depth--;
+            }
+            else if (tok.text === ";" && depth === 0) {
+                return true; // top-level semicolon → statement block
+            }
+        }
+        if (tok.kind === "ident" && tok.text === "return" && depth === 0) {
+            return true; // top-level return → statement block
+        }
+    }
+    return false;
+};
+// ----------------------------------------------------------------------------
+// ref name = init -> __reactra_ref__("name", init)
+// ----------------------------------------------------------------------------
+export const rewriteRef = (tokens, i) => {
+    const startTok = tokens[i];
+    const nameIdx = skipTrivia(tokens, i + 1);
+    const nameTok = tokens[nameIdx];
+    if (!nameTok || nameTok.kind !== "ident")
+        return null;
+    const eqIdx = skipTrivia(tokens, nameIdx + 1);
+    // ref may also appear without an initialiser: `ref formEl` (initial value null)
+    if (tokens[eqIdx]?.text !== "=") {
+        // bare ref declaration
+        return {
+            rewrite: {
+                span: { start: startTok.start, end: nameTok.end },
+                text: `__reactra_ref__("${nameTok.text}", null)`,
+            },
+            consumedUpTo: nameIdx,
+        };
+    }
+    const initStart = skipTrivia(tokens, eqIdx + 1);
+    const endIdx = readToStatementEnd(tokens, initStart);
+    const initText = slice(tokens, initStart, endIdx).trim();
+    return {
+        rewrite: {
+            span: { start: startTok.start, end: tokens[endIdx].end },
+            text: `__reactra_ref__("${nameTok.text}", ${initText})`,
+        },
+        consumedUpTo: endIdx,
+    };
+};
+// ----------------------------------------------------------------------------
+// action f(args) { body }       -> __reactra_action__("f", (args) => { body })
+// action async f(args) { body } -> __reactra_action_async__("f", async (args) => { body })
+// ----------------------------------------------------------------------------
+export const rewriteAction = (tokens, i) => {
+    const startTok = tokens[i];
+    let cursor = skipTrivia(tokens, i + 1);
+    let isAsync = false;
+    if (tokens[cursor]?.text === "async") {
+        isAsync = true;
+        cursor = skipTrivia(tokens, cursor + 1);
+    }
+    const nameTok = tokens[cursor];
+    if (!nameTok || nameTok.kind !== "ident")
+        return null;
+    const parenOpenIdx = skipTrivia(tokens, cursor + 1);
+    if (tokens[parenOpenIdx]?.text !== "(")
+        return null;
+    const parenCloseIdx = readParenEnd(tokens, parenOpenIdx);
+    const args = slice(tokens, parenOpenIdx + 1, parenCloseIdx - 1).trim();
+    const braceOpenIdx = skipTrivia(tokens, parenCloseIdx + 1);
+    if (tokens[braceOpenIdx]?.text !== "{")
+        return null;
+    const braceCloseIdx = readBlockEnd(tokens, braceOpenIdx);
+    const rawBody = slice(tokens, braceOpenIdx + 1, braceCloseIdx - 1);
+    const body = rawBody.trim();
+    const marker = isAsync ? "__reactra_action_async__" : "__reactra_action__";
+    const arrowHead = isAsync ? `async (${args}) => { ` : `(${args}) => { `;
+    const textHead = `${marker}("${nameTok.text}", ${arrowHead}`;
+    // Guard a body whose last line ends in a `//` comment so the appended `})`
+    // isn't commented out (the preprocessor is line-oriented — see helpers).
+    const text = `${textHead}${guardTrailingLineComment(body)} })`;
+    // Sub-map the body so its interior lines map back to their own source line
+    // (#10-followup §8). The body is copied verbatim; only the ends are trimmed,
+    // so a single run from the first non-whitespace char suffices. (The trim joins
+    // the body's FIRST line onto the marker/header line — that one line maps to the
+    // header; lines 2..n map exactly.) The first body token's `.start` is the source
+    // anchor; `rawBody`'s leading whitespace is how much the trim consumed.
+    const bodyTokStart = tokens[braceOpenIdx + 1]?.start ?? tokens[braceOpenIdx].end;
+    const leadingWs = rawBody.length - rawBody.trimStart().length;
+    const srcMap = body.length > 0
+        ? [{ textStart: textHead.length, srcStart: bodyTokStart + leadingWs, length: body.length }]
+        : undefined;
+    return {
+        rewrite: {
+            span: { start: startTok.start, end: tokens[braceCloseIdx].end },
+            text,
+            srcMap,
+        },
+        consumedUpTo: braceCloseIdx,
+    };
+};
+// ----------------------------------------------------------------------------
+// command f(args) { body }  ->  __reactra_command__("f", async (args) => { body })
+// `command` is the single async-WRITE primitive (CQRS twin of `resource`);
+// the block form is implicitly async (it awaits a server write) and lowers to
+// React 19 `useActionState` in Pass 9. The arrow form `command f() => expr`
+// (+ optimistic/invalidate/rollback clauses) is P3 Slice 3 — not yet matched.
+// ----------------------------------------------------------------------------
+export const rewriteCommand = (tokens, i) => {
+    const startTok = tokens[i];
+    const cursor = skipTrivia(tokens, i + 1);
+    const nameTok = tokens[cursor];
+    if (!nameTok || nameTok.kind !== "ident")
+        return null;
+    const parenOpenIdx = skipTrivia(tokens, cursor + 1);
+    if (tokens[parenOpenIdx]?.text !== "(")
+        return null;
+    const parenCloseIdx = readParenEnd(tokens, parenOpenIdx);
+    const args = slice(tokens, parenOpenIdx + 1, parenCloseIdx - 1).trim();
+    const afterParen = skipTrivia(tokens, parenCloseIdx + 1);
+    // Block form: command f(args) { body } -> __reactra_command__ (Slice 1).
+    if (tokens[afterParen]?.text === "{") {
+        const braceOpenIdx = afterParen;
+        const braceCloseIdx = readBlockEnd(tokens, braceOpenIdx);
+        const rawBody = slice(tokens, braceOpenIdx + 1, braceCloseIdx - 1);
+        const body = rawBody.trim();
+        const textHead = `__reactra_command__("${nameTok.text}", async (${args}) => { `;
+        const text = `${textHead}${guardTrailingLineComment(body)} })`;
+        const bodyTokStart = tokens[braceOpenIdx + 1]?.start ?? tokens[braceOpenIdx].end;
+        const leadingWs = rawBody.length - rawBody.trimStart().length;
+        const srcMap = body.length > 0
+            ? [{ textStart: textHead.length, srcStart: bodyTokStart + leadingWs, length: body.length }]
+            : undefined;
+        return {
+            rewrite: { span: { start: startTok.start, end: tokens[braceCloseIdx].end }, text, srcMap },
+            consumedUpTo: braceCloseIdx,
+        };
+    }
+    // Arrow form: command f(args) => fetcher -> __reactra_command_arrow__.
+    // Trailing clauses (optimistic {} / invalidate [] / rollback(e){}) are scanned
+    // after the fetcher, in any order, and collected into a 3rd marker options arg
+    // `{ optimistic: () => {…}, invalidate: [a, b], rollback: (e) => {…} }`.
+    if (tokens[afterParen]?.text === "=") {
+        const gtIdx = skipTrivia(tokens, afterParen + 1);
+        if (tokens[gtIdx]?.text !== ">")
+            return null;
+        const fnStart = skipTrivia(tokens, gtIdx + 1);
+        // Stops at the statement end OR a trailing clause keyword (so a clause is not
+        // swallowed into the fetcher).
+        const fnEnd = readCommandFetcherEnd(tokens, fnStart);
+        const fnText = slice(tokens, fnStart, fnEnd).trim();
+        let lastConsumed = fnEnd;
+        const props = [];
+        // Scan trailing clauses until a non-clause token (or statement end) is hit.
+        for (;;) {
+            const kw = skipTrivia(tokens, lastConsumed + 1);
+            const kwText = tokens[kw]?.text;
+            if (kwText === "optimistic") {
+                const obrace = skipTrivia(tokens, kw + 1);
+                if (tokens[obrace]?.text !== "{")
+                    break;
+                const cbrace = readBlockEnd(tokens, obrace);
+                const body = slice(tokens, obrace + 1, cbrace - 1).trim();
+                props.push(`optimistic: () => { ${guardTrailingLineComment(body)} }`);
+                lastConsumed = cbrace;
+            }
+            else if (kwText === "invalidate") {
+                const obrack = skipTrivia(tokens, kw + 1);
+                if (tokens[obrack]?.text !== "[")
+                    break;
+                const cbrack = readBracketEnd(tokens, obrack);
+                // The names are bare resource identifiers; carried verbatim as an array
+                // expression (parsed, never executed) — Pass 2 reads the identifier names.
+                const names = slice(tokens, obrack, cbrack);
+                props.push(`invalidate: ${names}`);
+                lastConsumed = cbrack;
+            }
+            else if (kwText === "rollback") {
+                const oparen = skipTrivia(tokens, kw + 1);
+                if (tokens[oparen]?.text !== "(")
+                    break;
+                const cparen = readParenEnd(tokens, oparen);
+                const params = slice(tokens, oparen + 1, cparen - 1).trim();
+                const obrace = skipTrivia(tokens, cparen + 1);
+                if (tokens[obrace]?.text !== "{")
+                    break;
+                const cbrace = readBlockEnd(tokens, obrace);
+                const body = slice(tokens, obrace + 1, cbrace - 1).trim();
+                props.push(`rollback: (${params}) => { ${guardTrailingLineComment(body)} }`);
+                lastConsumed = cbrace;
+            }
+            else {
+                break;
+            }
+        }
+        const optsArg = props.length > 0 ? `, { ${props.join(", ")} }` : "";
+        const text = `__reactra_command_arrow__("${nameTok.text}", async (${args}) => (${fnText})${optsArg})`;
+        return {
+            rewrite: { span: { start: startTok.start, end: tokens[lastConsumed].end }, text },
+            consumedUpTo: lastConsumed,
+        };
+    }
+    return null;
+};
+// ----------------------------------------------------------------------------
+// resource r(deps) => fn(deps)
+//   -> __reactra_resource__("r", () => (deps), (deps) => (fn(deps)))
+// resource r(deps) signal => fn(deps, signal)              (improvements #3)
+//   -> __reactra_resource__("r", () => (deps), (deps, { signal }) => (fn(deps, signal)))
+// resource r(deps) cache => fn(deps)                       (compiler stage 3)
+//   -> __reactra_resource__("r", () => (deps), (deps) => (fn(deps)), { cache: true })
+// resource r(deps) signal cache swr retry => fn(deps, signal)
+//   -> __reactra_resource__("r", () => (deps), (deps, { signal }) => (fn(deps, signal)),
+//        { cache: { staleWhileRevalidate: true, ttlMs: 60_000 }, retry: 3 })
+//
+// Modifiers sit between the deps `)` and `=>` in ANY order; order is
+// preserved in source but normalized at emission. All bare (Stage 3 v0 —
+// parameterized `cache(ttl: 60s)` / `retry(5)` is a future grammar
+// extension). The 24-keyword cap is untouched — these are contextual
+// tokens like `signal`, only special in this slot.
+//
+// Modifier defaults (Resource v1 §2):
+//   `cache`  → `cache: true`
+//   `swr`    → `cache: { staleWhileRevalidate: true, ttlMs: 60_000 }`
+//               (swr supersedes a bare `cache` if both are written)
+//   `retry`  → `retry: 3`
+//
+// Architect Q2 Path B is preserved: omitting all opt-ins keeps the emitted
+// useResource call cache-OFF and retry-OFF.
+// ----------------------------------------------------------------------------
+/** A bare identifier / dotted member chain — a constant reference (`MY_TTL`, `cfg.ttl`). */
+const IDENT_OR_MEMBER = /^[A-Za-z_$][\w$]*(\.[A-Za-z_$][\w$]*)*$/;
+/**
+ * Parse a `swr(…)` / `cache(ttl: …)` argument into a millisecond numeric string.
+ * Accepts a bare duration (`30s`, `500ms`, `5m`, `60000`) or a named `ttl: <dur>`;
+ * a unit is `ms` | `s` | `m` (underscores allowed in the number). A bare identifier
+ * / member chain (a constant in scope) passes through. Empty (`swr()`) → undefined,
+ * so the caller uses the default. Anything else — a typo'd unit (`5h`), a decimal
+ * (`1.5s`), whitespace (`30 s`), a non-positive ttl, junk — THROWS a clear compile
+ * error instead of emitting broken TSX (no-DX-surprises; Component DSL §2.4).
+ */
+const parseTtlArg = (inner) => {
+    const raw = inner.trim();
+    const v = raw.includes(":") ? raw.slice(raw.indexOf(":") + 1).trim() : raw;
+    if (v === "")
+        return undefined;
+    const m = /^(\d[\d_]*)(ms|s|m)?$/.exec(v);
+    if (m) {
+        const ms = Number(m[1].replace(/_/g, "")) * (m[2] === "s" ? 1000 : m[2] === "m" ? 60_000 : 1);
+        if (!(ms > 0)) {
+            throw new Error(`[reactra:compile] resource cache ttl must be > 0 (got "${raw}"). Component DSL §2.4.`);
+        }
+        return String(ms);
+    }
+    if (IDENT_OR_MEMBER.test(v))
+        return v;
+    throw new Error(`[reactra:compile] invalid resource cache ttl "${raw}" — expected a duration ` +
+        `(e.g. 30s / 500ms / 5m / 60000) or a constant. Component DSL §2.4.`);
+};
+/**
+ * Validate a `retry(…)` argument: a positive integer count, a constant identifier,
+ * or empty (→ undefined, use the default 3). Anything else (a comma list, a call,
+ * junk) THROWS rather than emit `retry: 1, 2` (two object props → broken TSX).
+ */
+const parseRetryArg = (inner) => {
+    const raw = inner.trim();
+    if (raw === "")
+        return undefined;
+    if (/^\d[\d_]*$/.test(raw))
+        return raw.replace(/_/g, "");
+    if (IDENT_OR_MEMBER.test(raw))
+        return raw;
+    throw new Error(`[reactra:compile] invalid retry argument "${raw}" — expected a count (e.g. 5) ` +
+        `or a constant. Component DSL §2.4.`);
+};
+export const rewriteResource = (tokens, i) => {
+    const startTok = tokens[i];
+    const nameIdx = skipTrivia(tokens, i + 1);
+    const nameTok = tokens[nameIdx];
+    if (!nameTok || nameTok.kind !== "ident")
+        return null;
+    const parenOpenIdx = skipTrivia(tokens, nameIdx + 1);
+    if (tokens[parenOpenIdx]?.text !== "(")
+        return null;
+    const parenCloseIdx = readParenEnd(tokens, parenOpenIdx);
+    const deps = slice(tokens, parenOpenIdx + 1, parenCloseIdx - 1).trim();
+    // Modifier chain: any number of `signal` / `cache` / `swr` / `retry` in any
+    // order, then `=>`. Each is single-use; a duplicate is permitted but harmless
+    // (idempotent flag flip). `swr` / `cache` / `retry` may take a parenthesized
+    // argument (`swr(30s)`, `cache(ttl: 60s)`, `retry(5)`); a bare modifier keeps
+    // its default. Any other ident bails (return null → caller falls back to the
+    // bare identifier, which TypeScript will then flag).
+    let cur = skipTrivia(tokens, parenCloseIdx + 1);
+    let hasSignal = false;
+    let hasCache = false;
+    let hasSwr = false;
+    let hasRetry = false;
+    let cacheTtl;
+    let retryCount;
+    let selectArrow;
+    while (tokens[cur]?.kind === "ident") {
+        const text = tokens[cur].text;
+        if (text === "signal") {
+            hasSignal = true;
+        }
+        else if (text === "select") {
+            const aft = skipTrivia(tokens, cur + 1);
+            if (tokens[aft]?.text !== "(") {
+                throw new Error(`[reactra:compile] \`select\` requires a selector arrow, e.g. \`select(u => u.name)\`. Component DSL §2.4.`);
+            }
+            const close = readParenEnd(tokens, aft);
+            const inner = slice(tokens, aft + 1, close - 1).trim();
+            if (!inner.includes("=>")) {
+                throw new Error(`[reactra:compile] \`select(...)\` must be an arrow function (got "${inner}"). Component DSL §2.4.`);
+            }
+            selectArrow = inner;
+            cur = skipTrivia(tokens, close + 1);
+            continue;
+        }
+        else if (text === "cache" || text === "swr") {
+            if (text === "swr")
+                hasSwr = true;
+            else
+                hasCache = true;
+            const aft = skipTrivia(tokens, cur + 1);
+            if (tokens[aft]?.text === "(") {
+                const close = readParenEnd(tokens, aft);
+                cacheTtl = parseTtlArg(slice(tokens, aft + 1, close - 1));
+                cur = skipTrivia(tokens, close + 1);
+                continue;
+            }
+        }
+        else if (text === "retry") {
+            hasRetry = true;
+            const aft = skipTrivia(tokens, cur + 1);
+            if (tokens[aft]?.text === "(") {
+                const close = readParenEnd(tokens, aft);
+                retryCount = parseRetryArg(slice(tokens, aft + 1, close - 1));
+                cur = skipTrivia(tokens, close + 1);
+                continue;
+            }
+        }
+        else
+            break;
+        cur = skipTrivia(tokens, cur + 1);
+    }
+    if (tokens[cur]?.text !== "=")
+        return null;
+    cur = skipTrivia(tokens, cur + 1);
+    if (tokens[cur]?.text !== ">")
+        return null;
+    const fnStart = skipTrivia(tokens, cur + 1);
+    const endIdx = readToStatementEnd(tokens, fnStart);
+    const fnText = slice(tokens, fnStart, endIdx).trim();
+    // Fetcher params: the deps binding first (if any), then `{ signal }` if the
+    // `signal` token was present. Built as a list so empty deps don't leave a
+    // dangling leading comma (e.g. `resource cart() signal =>` → `({ signal })`).
+    //
+    // When `deps` is a member-expression (e.g. `customer.data?.id`), it cannot be
+    // used directly as a binding-pattern parameter in the fetcher arrow — TypeScript
+    // rejects `(customer.data?.id) => …`. In that case we synthesize `_dep` as the
+    // param name. The fetcher body already references the reactive value directly
+    // (e.g. `api.snap(customer.data?.id)`), so `_dep` is an unused param by design.
+    const isSimpleBinding = /^[A-Za-z_$][\w$]*$/.test(deps);
+    const fetcherDepParam = isSimpleBinding ? deps : "_dep";
+    const fetcherParams = [deps.length > 0 ? fetcherDepParam : "", hasSignal ? "{ signal }" : ""]
+        .filter((p) => p.length > 0)
+        .join(", ");
+    // Stage 3 — opt-ins compile to a 4th argument carrying a ResourceOptions
+    // partial. `swr` supersedes a bare `cache` (swr implies caching). Omitting
+    // ALL opt-ins emits 3 args (matching the Stage 1 / Path B shape), so
+    // backwards-compatibility with the existing AST is exact.
+    const optsParts = [];
+    if (hasSwr) {
+        optsParts.push(`cache: { staleWhileRevalidate: true, ttlMs: ${cacheTtl ?? "60_000"} }`);
+    }
+    else if (hasCache) {
+        // Bare `cache` → cache-by-deps, no TTL. `cache(ttl: D)` → hard-expiry: the
+        // entry is stale past `ttlMs` and the next read refetches (no stale-serve;
+        // that's `swr`). The runtime treats a non-SWR ttl'd stale entry as a miss.
+        optsParts.push(cacheTtl !== undefined ? `cache: { ttlMs: ${cacheTtl} }` : `cache: true`);
+    }
+    if (hasRetry)
+        optsParts.push(`retry: ${retryCount ?? "3"}`);
+    // `select(u => u.name)` → a `select` option (the selector arrow, verbatim). The
+    // handle's `.data` becomes the selector's return; the consumer re-renders only
+    // when the selected slice changes (Resource v1 §2). Wrapped in parens so an
+    // expression-body arrow stays a single expression in the object literal.
+    if (selectArrow !== undefined)
+        optsParts.push(`select: (${selectArrow})`);
+    const optsArg = optsParts.length > 0 ? `, { ${optsParts.join(", ")} }` : ``;
+    return {
+        rewrite: {
+            span: { start: startTok.start, end: tokens[endIdx].end },
+            text: `__reactra_resource__("${nameTok.text}", () => (${deps}), (${fetcherParams}) => (${fnText})${optsArg})`,
+        },
+        consumedUpTo: endIdx,
+    };
+};
+// ----------------------------------------------------------------------------
+// mount   { body } -> __reactra_mount__(() => { body })
+// cleanup { body } -> __reactra_cleanup__(() => { body })
+// effect  { body } -> __reactra_effect__(() => { body })
+// effect on(x) { body } -> __reactra_effect_on__(() => x, () => { body })
+// ----------------------------------------------------------------------------
+export const rewriteBlock = (markerName, tokens, i) => {
+    const startTok = tokens[i];
+    const braceIdx = skipTrivia(tokens, i + 1);
+    if (tokens[braceIdx]?.text !== "{")
+        return null;
+    const closeIdx = readBlockEnd(tokens, braceIdx);
+    const body = slice(tokens, braceIdx + 1, closeIdx - 1).trim();
+    return {
+        rewrite: {
+            span: { start: startTok.start, end: tokens[closeIdx].end },
+            text: `__reactra_${markerName}__(() => { ${guardTrailingLineComment(body)} })`,
+        },
+        consumedUpTo: closeIdx,
+    };
+};
+/**
+ * `effect on(x) { body }` → `__reactra_effect_on__(() => x, () => { body })`
+ *
+ * DSL v3.0: bare `effect {}` is retired (teardown is a `return` inside `mount`
+ * or `effect on`). When the token after `effect` is not `on`, this rewriter
+ * returns `null` — the source is not a DSL construct and falls through as plain JS.
+ */
+export const rewriteEffect = (tokens, i) => {
+    const startTok = tokens[i];
+    const nextIdx = skipTrivia(tokens, i + 1);
+    // `effect on(x) { body }`
+    if (tokens[nextIdx]?.text === "on") {
+        const parenIdx = skipTrivia(tokens, nextIdx + 1);
+        if (tokens[parenIdx]?.text !== "(")
+            return null;
+        const parenCloseIdx = readParenEnd(tokens, parenIdx);
+        const watchExpr = slice(tokens, parenIdx + 1, parenCloseIdx - 1).trim();
+        const braceIdx = skipTrivia(tokens, parenCloseIdx + 1);
+        if (tokens[braceIdx]?.text !== "{")
+            return null;
+        const closeIdx = readBlockEnd(tokens, braceIdx);
+        const body = slice(tokens, braceIdx + 1, closeIdx - 1).trim();
+        return {
+            rewrite: {
+                span: { start: startTok.start, end: tokens[closeIdx].end },
+                text: `__reactra_effect_on__(() => (${watchExpr}), () => { ${guardTrailingLineComment(body)} })`,
+            },
+            consumedUpTo: closeIdx,
+        };
+    }
+    // v3.0: bare `effect {}` is not a DSL form. The caller (preprocess.ts dispatch)
+    // throws R027 before reaching here when `on` is absent — this null is a fallback
+    // for any non-component-body context where `effect` appears without `on`.
+    return null;
+};
+// `view { JSX }` is rewritten by the scope tracker (not as a single keyword
+// rewriter) so that DSL keywords inside the view body — notably
+// `await(r) { } pending { } error(e) { }` — get the chance to rewrite first.
+// See preprocess.ts: open-rewrite happens when view-body is pushed; close-
+// rewrite happens when view-body is popped. The two rewrites combined yield:
+//   view { JSX } -> __reactra_view__(() => (<>JSX</>))
+// ----------------------------------------------------------------------------
+// await(r) { A } pending { B } error(e) { C }
+//   -> {__reactra_await__(() => r, () => (<>A</>), () => (<>B</>), (e) => (<>C</>))}
+//
+// `pending` and `error` are optional. If absent, their slot is `null`.
+//
+// The output is wrapped in `{}` because `await` is legal only in view-body
+// scope (per KEYWORDS_BY_SCOPE), where the surrounding text is a JSX
+// fragment. A bare call expression in JSX text position would be parsed as
+// raw text by Babel — wrapping in `{}` makes it a valid JSXExpressionContainer
+// so Pass 9 codegen can find and rewrite the call.
+// ----------------------------------------------------------------------------
+export const rewriteAwait = (tokens, i) => {
+    const startTok = tokens[i];
+    // Trimmed verbatim slice + the source offset its first kept char came from
+    // (the trim consumes leading whitespace — same anchoring as rewriteAction's
+    // srcMap). Powers the per-block VerbatimRuns below.
+    const trimmedSlice = (openIdx, closeIdx) => {
+        const raw = slice(tokens, openIdx + 1, closeIdx - 1);
+        const anchor = tokens[openIdx + 1]?.start ?? tokens[openIdx].end;
+        return { text: raw.trim(), srcStart: anchor + (raw.length - raw.trimStart().length) };
+    };
+    // resource expression in parens
+    const parenIdx = skipTrivia(tokens, i + 1);
+    if (tokens[parenIdx]?.text !== "(")
+        return null;
+    const parenCloseIdx = readParenEnd(tokens, parenIdx);
+    const resource = trimmedSlice(parenIdx, parenCloseIdx);
+    // success body
+    const bodyOpenIdx = skipTrivia(tokens, parenCloseIdx + 1);
+    if (tokens[bodyOpenIdx]?.text !== "{")
+        return null;
+    const bodyCloseIdx = readBlockEnd(tokens, bodyOpenIdx);
+    const success = trimmedSlice(bodyOpenIdx, bodyCloseIdx);
+    let pending = null;
+    let errorParam = null;
+    let errorBlock = null;
+    let endIdx = bodyCloseIdx;
+    // optional `pending { body }` immediately after
+    const afterBodyIdx = skipTrivia(tokens, bodyCloseIdx + 1);
+    let cursor = afterBodyIdx;
+    if (tokens[cursor]?.text === "pending") {
+        const pBraceIdx = skipTrivia(tokens, cursor + 1);
+        if (tokens[pBraceIdx]?.text === "{") {
+            const pCloseIdx = readBlockEnd(tokens, pBraceIdx);
+            pending = trimmedSlice(pBraceIdx, pCloseIdx);
+            endIdx = pCloseIdx;
+            cursor = skipTrivia(tokens, pCloseIdx + 1);
+        }
+    }
+    // optional `error(e) { body }`
+    if (tokens[cursor]?.text === "error") {
+        const eParenIdx = skipTrivia(tokens, cursor + 1);
+        if (tokens[eParenIdx]?.text === "(") {
+            const eParenCloseIdx = readParenEnd(tokens, eParenIdx);
+            errorParam = slice(tokens, eParenIdx + 1, eParenCloseIdx - 1).trim();
+            const eBraceIdx = skipTrivia(tokens, eParenCloseIdx + 1);
+            if (tokens[eBraceIdx]?.text === "{") {
+                const eCloseIdx = readBlockEnd(tokens, eBraceIdx);
+                errorBlock = trimmedSlice(eBraceIdx, eCloseIdx);
+                endIdx = eCloseIdx;
+            }
+        }
+    }
+    // Build the replacement text incrementally so each verbatim block records a
+    // VerbatimRun (textStart in the replacement, srcStart in the DSL) — these are
+    // what give editor tooling exact positions INSIDE await blocks (the success/
+    // pending/error JSX is user code carried verbatim; everything else here is
+    // synthesized).
+    const srcMap = [];
+    let text = "";
+    const append = (s) => {
+        text += s;
+    };
+    const appendVerbatim = (piece) => {
+        if (piece.text.length > 0) {
+            srcMap.push({ textStart: text.length, srcStart: piece.srcStart, length: piece.text.length });
+        }
+        text += piece.text;
+    };
+    append("{__reactra_await__(() => (");
+    appendVerbatim(resource);
+    append("), () => (<>");
+    appendVerbatim(success);
+    append("</>), ");
+    if (pending !== null) {
+        append("() => (<>");
+        appendVerbatim(pending);
+        append("</>)");
+    }
+    else {
+        append("null");
+    }
+    append(", ");
+    if (errorBlock !== null) {
+        append(`(${errorParam ?? "e"}) => (<>`);
+        appendVerbatim(errorBlock);
+        append("</>)");
+    }
+    else {
+        append("null");
+    }
+    append(")}");
+    return {
+        rewrite: {
+            span: { start: startTok.start, end: tokens[endIdx].end },
+            text,
+            srcMap: srcMap.length > 0 ? srcMap : undefined,
+        },
+        consumedUpTo: endIdx,
+    };
+};
+// ----------------------------------------------------------------------------
+// uses A, B, C -> __reactra_uses__("A", "B", "C")
+// ----------------------------------------------------------------------------
+export const rewriteUses = (tokens, i) => {
+    const startTok = tokens[i];
+    const names = [];
+    let cursor = skipTrivia(tokens, i + 1);
+    while (cursor < tokens.length) {
+        const t = tokens[cursor];
+        if (!t || t.kind !== "ident")
+            break;
+        names.push(t.text);
+        const next = skipTrivia(tokens, cursor + 1);
+        if (tokens[next]?.text === ",") {
+            cursor = skipTrivia(tokens, next + 1);
+            continue;
+        }
+        cursor = next - 1;
+        break;
+    }
+    if (names.length === 0)
+        return null;
+    // endIdx is the last consumed ident; back up to find its end pos
+    let lastIdent = i;
+    let count = 0;
+    for (let j = i + 1; j < tokens.length && count < names.length; j++) {
+        if (tokens[j].kind === "ident") {
+            lastIdent = j;
+            count++;
+        }
+    }
+    return {
+        rewrite: {
+            span: { start: startTok.start, end: tokens[lastIdent].end },
+            text: `__reactra_uses__(${names.map((n) => `"${n}"`).join(", ")})`,
+        },
+        consumedUpTo: lastIdent,
+    };
+};
+// ----------------------------------------------------------------------------
+// `inject` dispatcher (Requirements v14 / backlog 1a — `use` retired). The
+// token after `inject` selects the form:
+//   inject store storeX                    -> __reactra_inject_store__("storeX")
+//   inject store storeX { a, b }           -> __reactra_inject_store__("storeX", { fields: ["a","b"] })
+//   inject store storeX({ k: v })          -> __reactra_inject_store_args__("storeX", { k: v })
+//   inject store storeX({ k: v }) { a, b } -> __reactra_inject_store_args__("storeX", { k: v }, { fields: ["a","b"] })
+//   inject store storeX(key)({ k: v })     -> __reactra_inject_store_keyed__("storeX", key, { k: v })
+//   inject store storeX: T                 -> __reactra_inject_store__("storeX", { typeOverride: "T" })
+//   inject store storeX({ k: v }): T { a } -> __reactra_inject_store_args__("storeX", { k: v }, { typeOverride: "T", fields: ["a"] })
+//   inject service svcX                    -> __reactra_inject__("svcX", { kind: "service" })
+//   inject X from config("K")              -> __reactra_inject__("X", { source: "config" })
+//   inject X: T from inject                -> __reactra_inject__("X", { source: "inject" })
+//   inject X            (no qualifier)     -> __reactra_inject__("X")   (Pass 3a raises SVC015)
+//
+// Object-literal inputs (`{ k: v }`) are emitted verbatim — the value is a
+// route `param`/`query` in scope; whether it's a param or query is resolved by
+// codegen (the lexer-level preprocessor can't know). Field-selection braces
+// drive the destructure (Store §2.5); omitted → namespace binding.
+// ----------------------------------------------------------------------------
+export const rewriteInject = (tokens, i) => {
+    const startTok = tokens[i];
+    const k1 = skipTrivia(tokens, i + 1);
+    const k1Tok = tokens[k1];
+    if (!k1Tok || k1Tok.kind !== "ident")
+        return null;
+    // `inject store ...`
+    if (k1Tok.text === "store")
+        return rewriteInjectStore(tokens, i, k1);
+    // `inject service X [as Y]`
+    if (k1Tok.text === "service") {
+        const nameIdx = skipTrivia(tokens, k1 + 1);
+        const nameTok = tokens[nameIdx];
+        if (!nameTok || nameTok.kind !== "ident")
+            return null;
+        // optional namespace alias `as Y` (Service v2.3 §4.2 — parity with inject store)
+        let alias = null;
+        const afterName = skipTrivia(tokens, nameIdx + 1);
+        if (tokens[afterName]?.text === "as") {
+            const aliasTok = tokens[skipTrivia(tokens, afterName + 1)];
+            if (aliasTok && aliasTok.kind === "ident")
+                alias = aliasTok.text;
+        }
+        const endIdx = readToStatementEnd(tokens, nameIdx);
+        const opts = alias ? `{ kind: "service", alias: "${alias}" }` : `{ kind: "service" }`;
+        return {
+            rewrite: {
+                span: { start: startTok.start, end: tokens[endIdx].end },
+                text: `__reactra_inject__("${nameTok.text}", ${opts})`,
+            },
+            consumedUpTo: endIdx,
+        };
+    }
+    // `inject X [: T] [from <source>]` — name is k1. A `from config(...)` /
+    // `from inject` clause makes the injection explicit (no kind qualifier
+    // required); a bare `inject X` carries no second arg and Pass 3a raises
+    // SVC015.
+    const nameTok = k1Tok;
+    const endIdx = readToStatementEnd(tokens, k1);
+    let source = null;
+    for (let j = k1 + 1; j <= endIdx; j++) {
+        if (tokens[j]?.text === "from") {
+            const srcTok = tokens[skipTrivia(tokens, j + 1)];
+            if (srcTok?.text === "config")
+                source = "config";
+            else if (srcTok?.text === "inject")
+                source = "inject";
+            break;
+        }
+    }
+    const args = source ? `"${nameTok.text}", { source: "${source}" }` : `"${nameTok.text}"`;
+    return {
+        rewrite: {
+            span: { start: startTok.start, end: tokens[endIdx].end },
+            text: `__reactra_inject__(${args})`,
+        },
+        consumedUpTo: endIdx,
+    };
+};
+/**
+ * Parse the store form of `inject` starting at `inject` (index `startIdx`),
+ * with `store` at `storeKwIdx`. Handles optional object-literal inputs
+ * `({...})`, keyed `(key)({...})`, and field-selection braces `{ a, b }`.
+ */
+const rewriteInjectStore = (tokens, startIdx, storeKwIdx) => {
+    const startTok = tokens[startIdx];
+    const nameIdx = skipTrivia(tokens, storeKwIdx + 1);
+    const nameTok = tokens[nameIdx];
+    if (!nameTok || nameTok.kind !== "ident")
+        return null;
+    const storeName = nameTok.text;
+    let cursor = skipTrivia(tokens, nameIdx + 1);
+    let inputsText = null;
+    let keyText = null;
+    let endIdx = nameIdx;
+    // optional `(...)` inputs, or keyed `(key)(...)`
+    if (tokens[cursor]?.text === "(") {
+        const close1 = readParenEnd(tokens, cursor);
+        const group1 = slice(tokens, cursor + 1, close1 - 1).trim();
+        endIdx = close1;
+        const after1 = skipTrivia(tokens, close1 + 1);
+        if (tokens[after1]?.text === "(") {
+            const close2 = readParenEnd(tokens, after1);
+            keyText = group1;
+            inputsText = slice(tokens, after1 + 1, close2 - 1).trim();
+            endIdx = close2;
+            cursor = skipTrivia(tokens, close2 + 1);
+        }
+        else {
+            inputsText = group1;
+            cursor = after1;
+        }
+    }
+    // optional `: Type` override (Store §2.5 / Compiler §4 v14) — sits between the
+    // inputs `)` and the field `{`. Read the type reference up to the top-level
+    // field-opening `{` or statement end, tracking <>/()/[] depth so generics,
+    // tuples, and parenthesised types stay intact (single-`>` angle tracking matches
+    // `readOptionalTypeAnnotation`). Recorded as `typeOverride`; the structural-subset
+    // check (S015) is left to TypeScript via the emitted `useReactraStore<Type>`
+    // generic — not done here. An inline object-literal type at this position is
+    // unsupported in Phase 1 (use a named type, per the architect review).
+    let typeOverride = null;
+    if (tokens[cursor]?.text === ":") {
+        const typeStart = skipTrivia(tokens, cursor + 1);
+        let paren = 0;
+        let bracket = 0;
+        let angle = 0;
+        let last = typeStart - 1;
+        for (let j = typeStart; j < tokens.length; j++) {
+            const t = tokens[j];
+            if (t.kind === "punct") {
+                if (t.text === "(")
+                    paren++;
+                else if (t.text === ")") {
+                    if (paren === 0)
+                        break;
+                    paren--;
+                }
+                else if (t.text === "[")
+                    bracket++;
+                else if (t.text === "]")
+                    bracket--;
+                else if (t.text === "<")
+                    angle++;
+                else if (t.text === ">")
+                    angle = Math.max(0, angle - 1);
+                else if (paren === 0 &&
+                    bracket === 0 &&
+                    angle === 0 &&
+                    (t.text === "{" || t.text === "}" || t.text === ";")) {
+                    break; // field-selection `{`, enclosing-scope `}`, or explicit `;`
+                }
+            }
+            // `inject store X: IFoo as Y` — the alias `as` ends the type annotation
+            // (TS types never contain a bare `as`). Store v4.9 §2.5.
+            if (paren === 0 && bracket === 0 && angle === 0 && t.kind === "ident" && t.text === "as") {
+                break;
+            }
+            if (paren === 0 &&
+                bracket === 0 &&
+                angle === 0 &&
+                t.kind === "whitespace" &&
+                t.text.includes("\n")) {
+                break;
+            }
+            if (t.kind !== "whitespace" && t.kind !== "comment-line" && t.kind !== "comment-block") {
+                last = j;
+            }
+        }
+        if (last >= typeStart) {
+            typeOverride = slice(tokens, typeStart, last).trim();
+            endIdx = last;
+            cursor = skipTrivia(tokens, last + 1);
+        }
+    }
+    // optional namespace alias `as Y` — renames the whole-store binding
+    // (Store v4.9 §2.5). Mirrors ES `import * as Y`.
+    let alias = null;
+    if (tokens[cursor]?.text === "as") {
+        const aliasIdx = skipTrivia(tokens, cursor + 1);
+        const aliasTok = tokens[aliasIdx];
+        if (aliasTok && aliasTok.kind === "ident") {
+            alias = aliasTok.text;
+            endIdx = aliasIdx;
+            cursor = skipTrivia(tokens, aliasIdx + 1);
+        }
+    }
+    let fields = null;
+    if (tokens[cursor]?.text === "{") {
+        const closeBrace = readBlockEnd(tokens, cursor);
+        fields = slice(tokens, cursor + 1, closeBrace - 1)
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean)
+            .map((entry) => {
+            const asParts = entry.split(/\s+as\s+/);
+            if (asParts.length === 2)
+                return { source: asParts[0].trim(), local: asParts[1].trim(), as: true };
+            const colon = entry.indexOf(":");
+            if (colon >= 0)
+                return { source: entry.slice(0, colon).trim(), local: entry.slice(colon + 1).trim() };
+            return { source: entry };
+        });
+        endIdx = closeBrace;
+    }
+    // Trailing options object — unified `{ typeOverride?, fields? }` (Compiler §4
+    // v14). `typeOverride` first to match the spec's marker rows; emitted only when
+    // non-empty so the no-options / fields-only output stays byte-identical.
+    const optionParts = [];
+    if (typeOverride)
+        optionParts.push(`typeOverride: ${JSON.stringify(typeOverride)}`);
+    if (fields && fields.length > 0) {
+        // Bare fields stay plain strings (byte-identical to pre-rename output); a
+        // rename is a `{ source, local }` object (Store v4.7 §2.5 / Compiler §4).
+        const lit = fields
+            .map((f) => f.local != null
+            ? `{ source: "${f.source}", local: "${f.local}"${f.as ? ", as: true" : ""} }`
+            : `"${f.source}"`)
+            .join(", ");
+        optionParts.push(`fields: [${lit}]`);
+    }
+    if (alias)
+        optionParts.push(`alias: ${JSON.stringify(alias)}`);
+    const optionsArg = optionParts.length > 0 ? `{ ${optionParts.join(", ")} }` : null;
+    const inputsObj = inputsText !== null ? (inputsText.length > 0 ? inputsText : "{}") : null;
+    let text;
+    if (keyText !== null) {
+        const parts = [`"${storeName}"`, keyText, inputsObj ?? "{}"];
+        if (optionsArg)
+            parts.push(optionsArg);
+        text = `__reactra_inject_store_keyed__(${parts.join(", ")})`;
+    }
+    else if (inputsObj !== null) {
+        const parts = [`"${storeName}"`, inputsObj];
+        if (optionsArg)
+            parts.push(optionsArg);
+        text = `__reactra_inject_store_args__(${parts.join(", ")})`;
+    }
+    else {
+        const parts = [`"${storeName}"`];
+        if (optionsArg)
+            parts.push(optionsArg);
+        text = `__reactra_inject_store__(${parts.join(", ")})`;
+    }
+    return {
+        rewrite: { span: { start: startTok.start, end: tokens[endIdx].end }, text },
+        consumedUpTo: endIdx,
+    };
+};
+// ----------------------------------------------------------------------------
+// provide X with Y -> __reactra_provide__("X", Y)
+// ----------------------------------------------------------------------------
+export const rewriteProvide = (tokens, i) => {
+    const startTok = tokens[i];
+    const nameIdx = skipTrivia(tokens, i + 1);
+    const nameTok = tokens[nameIdx];
+    if (!nameTok || nameTok.kind !== "ident")
+        return null;
+    const withIdx = skipTrivia(tokens, nameIdx + 1);
+    if (tokens[withIdx]?.text !== "with")
+        return null;
+    const valueStart = skipTrivia(tokens, withIdx + 1);
+    const endIdx = readToStatementEnd(tokens, valueStart);
+    const valueText = slice(tokens, valueStart, endIdx).trim();
+    return {
+        rewrite: {
+            span: { start: startTok.start, end: tokens[endIdx].end },
+            text: `__reactra_provide__("${nameTok.text}", ${valueText})`,
+        },
+        consumedUpTo: endIdx,
+    };
+};
+// ----------------------------------------------------------------------------
+// param X: T              -> __reactra_param__("X")
+// query X: T = default    -> __reactra_query__("X", default)
+// query X: T              -> __reactra_query__("X")
+// ----------------------------------------------------------------------------
+export const rewriteParam = (tokens, i) => {
+    const startTok = tokens[i];
+    const nameIdx = skipTrivia(tokens, i + 1);
+    const nameTok = tokens[nameIdx];
+    if (!nameTok || nameTok.kind !== "ident")
+        return null;
+    // The `: T` annotation is intentionally NOT threaded: route params are always
+    // `string` at runtime (the matched-route invariant — `__route.params` is
+    // `Record<string, string>`, and Pass 9 emits no coercion), so projecting a
+    // non-string declared type in the shadow would be a runtime-contradicting lie.
+    // The shadow types every param `string` (honest); `: number` etc. surfaces as a
+    // type error on number ops, nudging the author to coerce. R026 still applies.
+    const endIdx = readToStatementEndStrict(tokens, nameIdx, {
+        keyword: "param",
+        name: nameTok.text,
+        startTok,
+    });
+    return {
+        rewrite: {
+            span: { start: startTok.start, end: tokens[endIdx].end },
+            text: `__reactra_param__("${nameTok.text}")`,
+        },
+        consumedUpTo: endIdx,
+    };
+};
+export const rewriteQuery = (tokens, i) => {
+    const startTok = tokens[i];
+    const nameIdx = skipTrivia(tokens, i + 1);
+    const nameTok = tokens[nameIdx];
+    if (!nameTok || nameTok.kind !== "ident")
+        return null;
+    // Optional `?` for optional fields
+    let cursor = nameIdx + 1;
+    if (tokens[skipTrivia(tokens, cursor)]?.text === "?") {
+        cursor = skipTrivia(tokens, cursor) + 1;
+    }
+    // Optional `: T` annotation — captured (not discarded) so the compiler can
+    // coerce the raw URL string to the declared type at read time (#5c-typed
+    // runtime coercion). The type text is threaded as a string-literal arg.
+    const { type, next } = readOptionalTypeAnnotation(tokens, cursor);
+    cursor = skipTrivia(tokens, next);
+    // Strip any trailing `;` that readOptionalTypeAnnotation may include when the
+    // annotation is on a single line and `;` precedes the newline (same issue as
+    // rewriteState — the `;` is captured in the type text).
+    let typeText = type !== undefined && type.trim().length > 0 ? type.replace(/;$/, "").trim() : "string";
+    // Custom parser: `query foo: T from parseFoo` (Router §3.1). The type reader
+    // doesn't stop at `from`, so it captures `T from parseFoo` — split the trailing
+    // ` from <ident>` back off (a TS type never contains a bare `from` keyword).
+    let fromParser;
+    const fromMatch = /^([\s\S]*?)\s+from\s+([A-Za-z_$][\w$]*)$/.exec(typeText);
+    if (fromMatch) {
+        typeText = fromMatch[1].trim() || "string";
+        fromParser = fromMatch[2];
+    }
+    let defaultText;
+    if (tokens[cursor]?.text === "=") {
+        const valueStart = skipTrivia(tokens, cursor + 1);
+        const valueEnd = readToStatementEndStrict(tokens, valueStart, {
+            keyword: "query",
+            name: nameTok.text,
+            startTok,
+        });
+        defaultText = slice(tokens, valueStart, valueEnd).trim();
+        cursor = valueEnd;
+    }
+    else {
+        cursor = readToStatementEndStrict(tokens, nameIdx, {
+            keyword: "query",
+            name: nameTok.text,
+            startTok,
+        });
+    }
+    // Emit `__reactra_query__("name", "<type>"[, default[, parser]])`. The type is
+    // JSON-stringified so an enum like `"a" | "b"` survives as a safe string
+    // literal. Pass-2 reads arg[1]=type, arg[2]=default, arg[3]=custom parser
+    // (a bare identifier — a function in scope). When a parser is present without a
+    // default, arg[2] is the `undefined` placeholder so the parser stays at arg[3].
+    const argParts = [`"${nameTok.text}"`, JSON.stringify(typeText)];
+    if (fromParser) {
+        argParts.push(defaultText ?? "undefined", fromParser);
+    }
+    else if (defaultText !== undefined) {
+        argParts.push(defaultText);
+    }
+    const args = argParts.join(", ");
+    return {
+        rewrite: {
+            span: { start: startTok.start, end: tokens[cursor].end },
+            text: `__reactra_query__(${args})`,
+        },
+        consumedUpTo: cursor,
+    };
+};
+// ----------------------------------------------------------------------------
+// meta { K: V; ... } -> __reactra_meta__({ K: V, ... })
+// ----------------------------------------------------------------------------
+export const rewriteMeta = (tokens, i) => {
+    const startTok = tokens[i];
+    const braceIdx = skipTrivia(tokens, i + 1);
+    if (tokens[braceIdx]?.text !== "{")
+        return null;
+    const closeIdx = readBlockEnd(tokens, braceIdx);
+    // Convert `K: V;` separators to commas. Simple heuristic: replace `;` at top
+    // level inside the object literal with `,`. We do this on the raw text.
+    const inner = slice(tokens, braceIdx + 1, closeIdx - 1);
+    const normalised = inner.replace(/;\s*$/gm, ",").replace(/;/g, ",").trim();
+    return {
+        rewrite: {
+            span: { start: startTok.start, end: tokens[closeIdx].end },
+            text: `__reactra_meta__({ ${normalised} })`,
+        },
+        consumedUpTo: closeIdx,
+    };
+};
+// ----------------------------------------------------------------------------
+// prefetch on TRIGGER -> __reactra_prefetch__("TRIGGER")
+// prefetch none       -> __reactra_prefetch__("none")
+// ----------------------------------------------------------------------------
+export const rewritePrefetch = (tokens, i) => {
+    const startTok = tokens[i];
+    let cursor = skipTrivia(tokens, i + 1);
+    if (tokens[cursor]?.text === "on") {
+        cursor = skipTrivia(tokens, cursor + 1);
+    }
+    const trigger = tokens[cursor];
+    if (!trigger || trigger.kind !== "ident")
+        return null;
+    return {
+        rewrite: {
+            span: { start: startTok.start, end: trigger.end },
+            text: `__reactra_prefetch__("${trigger.text}")`,
+        },
+        consumedUpTo: cursor,
+    };
+};
+// ----------------------------------------------------------------------------
+// input X: T              -> __reactra_input__("X")
+// input X?: T             -> __reactra_input__("X", { optional: true })
+// input X: T = default    -> __reactra_input__("X", { default })
+//
+// Store-body only. The TS annotation `: T` passes through to the sidecar
+// metadata in Compiler §6; the marker carries only the runtime-needed bits.
+// ----------------------------------------------------------------------------
+export const rewriteInput = (tokens, i) => {
+    const startTok = tokens[i];
+    const nameIdx = skipTrivia(tokens, i + 1);
+    const nameTok = tokens[nameIdx];
+    if (!nameTok || nameTok.kind !== "ident")
+        return null;
+    // Detect optional marker `?`
+    let cursor = nameIdx + 1;
+    let isOptional = false;
+    const afterName = skipTrivia(tokens, cursor);
+    if (tokens[afterName]?.text === "?") {
+        isOptional = true;
+        cursor = afterName + 1;
+    }
+    // Optional type annotation — captured (not discarded) and threaded into the
+    // marker's options object as `tsType` for the shadow emitter (Run 2 / D3).
+    // Pass-9 ignores it (store inputs lower structurally), so emission is unchanged.
+    const { type, next } = readOptionalTypeAnnotation(tokens, cursor);
+    const tsType = type !== undefined && type.trim().length > 0 ? type.replace(/;$/, "").trim() : undefined;
+    cursor = skipTrivia(tokens, next);
+    // Optional default
+    let defaultText;
+    let endIdx = nameIdx;
+    if (tokens[cursor]?.text === "=") {
+        const valueStart = skipTrivia(tokens, cursor + 1);
+        endIdx = readToStatementEndStrict(tokens, valueStart, {
+            keyword: "input",
+            name: nameTok.text,
+            startTok,
+        });
+        defaultText = slice(tokens, valueStart, endIdx).trim();
+    }
+    else {
+        endIdx = readToStatementEndStrict(tokens, nameIdx, {
+            keyword: "input",
+            name: nameTok.text,
+            startTok,
+        });
+    }
+    // Assemble the options object, threading `tsType` last when present.
+    const opts = [];
+    if (isOptional)
+        opts.push("optional: true");
+    else if (defaultText !== undefined)
+        opts.push(`default: ${defaultText}`);
+    if (tsType)
+        opts.push(`tsType: ${JSON.stringify(tsType)}`);
+    const args = opts.length > 0 ? `"${nameTok.text}", { ${opts.join(", ")} }` : `"${nameTok.text}"`;
+    return {
+        rewrite: {
+            span: { start: startTok.start, end: tokens[endIdx].end },
+            text: `__reactra_input__(${args})`,
+        },
+        consumedUpTo: endIdx,
+    };
+};
+// ----------------------------------------------------------------------------
+// preserved state X = init -> __reactra_state__("X", init); __reactra_preserved__("X")
+//
+// DSL v3.0 §6 (Store spec §6): `preserved` is now an inline modifier on a single
+// `state` declaration. One field per line; multi-declarator comma lists are DROPPED
+// (S012 is structurally impossible — no comma-list to parse). Both the state binding
+// AND the preserved marker are emitted in the same rewrite so Pass 2 sees them as
+// a paired sequence. The initialiser follows `=`; an optional `: T` annotation is
+// consumed (moved into the state cast per the state rewriter convention).
+//
+// Store-body only. The literal word `state` follows `preserved` as a modifier.
+// ----------------------------------------------------------------------------
+export const rewritePreserved = (tokens, i) => {
+    const startTok = tokens[i];
+    // expect literal `state` after `preserved`
+    const stateIdx = skipTrivia(tokens, i + 1);
+    if (tokens[stateIdx]?.text !== "state")
+        return null;
+    // Read the single field name
+    const nameIdx = skipTrivia(tokens, stateIdx + 1);
+    const nameTok = tokens[nameIdx];
+    if (!nameTok || nameTok.kind !== "ident")
+        return null;
+    // Optional `: T` type annotation
+    const { type, next } = readOptionalTypeAnnotation(tokens, nameIdx + 1);
+    // Required `= init` initialiser
+    const eqIdx = skipTrivia(tokens, next);
+    if (tokens[eqIdx]?.text !== "=")
+        return null;
+    const initStart = skipTrivia(tokens, eqIdx + 1);
+    const endIdx = readToStatementEnd(tokens, initStart);
+    const initText = slice(tokens, initStart, endIdx).trim();
+    const name = nameTok.text;
+    // Emit BOTH the state binding and the preserved marker as a single rewrite.
+    // Pass 2 reads them in sequence: the state marker registers the field, then the
+    // preserved marker tags it. This keeps the emission byte-identical to the prior
+    // separate `state X` + `preserved state X` pair.
+    return {
+        rewrite: {
+            span: { start: startTok.start, end: tokens[endIdx].end },
+            text: `${emitStateMarker(name, type ?? null, initText)}; __reactra_preserved__("${name}")`,
+        },
+        consumedUpTo: endIdx,
+    };
+};
+// ----------------------------------------------------------------------------
+// errorBoundary(e) { JSX } -> __reactra_error_boundary__((e) => (<>JSX</>))
+//
+// Component-body only. Provides a React ErrorBoundary fallback scoped to
+// this component's children. See Component DSL v2 §7.2.
+// ----------------------------------------------------------------------------
+export const rewriteErrorBoundary = (tokens, i) => {
+    const startTok = tokens[i];
+    const parenIdx = skipTrivia(tokens, i + 1);
+    if (tokens[parenIdx]?.text !== "(")
+        return null;
+    const parenCloseIdx = readParenEnd(tokens, parenIdx);
+    const errorParam = slice(tokens, parenIdx + 1, parenCloseIdx - 1).trim();
+    const braceIdx = skipTrivia(tokens, parenCloseIdx + 1);
+    if (tokens[braceIdx]?.text !== "{")
+        return null;
+    const closeIdx = readBlockEnd(tokens, braceIdx);
+    const body = slice(tokens, braceIdx + 1, closeIdx - 1).trim();
+    return {
+        rewrite: {
+            span: { start: startTok.start, end: tokens[closeIdx].end },
+            text: `__reactra_error_boundary__((${errorParam || "e"}) => (<>${body}</>))`,
+        },
+        consumedUpTo: closeIdx,
+    };
+};
+// ----------------------------------------------------------------------------
+// suspense { JSX } -> __reactra_suspense__(() => (<>JSX</>))
+//
+// Component-body only. Provides a route/component-scoped Suspense fallback.
+// See Component DSL v2 §7.3.
+// ----------------------------------------------------------------------------
+export const rewriteSuspense = (tokens, i) => {
+    const startTok = tokens[i];
+    const braceIdx = skipTrivia(tokens, i + 1);
+    if (tokens[braceIdx]?.text !== "{")
+        return null;
+    const closeIdx = readBlockEnd(tokens, braceIdx);
+    const body = slice(tokens, braceIdx + 1, closeIdx - 1).trim();
+    return {
+        rewrite: {
+            span: { start: startTok.start, end: tokens[closeIdx].end },
+            text: `__reactra_suspense__(() => (<>${body}</>))`,
+        },
+        consumedUpTo: closeIdx,
+    };
+};
+// ----------------------------------------------------------------------------
+// transition NAME           -> __reactra_transition__("NAME")
+// transition NAME for Yms   -> __reactra_transition__("NAME", Y)
+//
+// NAME may be a hyphenated identifier like `slide-left`, `slide-right`,
+// `slide-up`, `slide-down`, etc. The lexer tokenises `slide-left` as
+// `slide` + `-` + `left`, so we greedy-consume `(- ident)*` after the
+// first ident to assemble the full transition name.
+// ----------------------------------------------------------------------------
+export const rewriteTransition = (tokens, i) => {
+    const startTok = tokens[i];
+    const nameIdx = skipTrivia(tokens, i + 1);
+    const nameTok = tokens[nameIdx];
+    if (!nameTok || nameTok.kind !== "ident")
+        return null;
+    // Assemble hyphenated name: `slide` + `-` + `left` -> "slide-left"
+    let nameText = nameTok.text;
+    let endIdx = nameIdx;
+    let lookahead = nameIdx + 1;
+    while (lookahead < tokens.length) {
+        const dashCandidate = tokens[lookahead];
+        if (!dashCandidate)
+            break;
+        if (dashCandidate.kind === "punct" && dashCandidate.text === "-") {
+            const after = tokens[lookahead + 1];
+            if (after && after.kind === "ident") {
+                nameText += `-${after.text}`;
+                endIdx = lookahead + 1;
+                lookahead = endIdx + 1;
+                continue;
+            }
+        }
+        break;
+    }
+    let duration;
+    const forIdx = skipTrivia(tokens, endIdx + 1);
+    if (tokens[forIdx]?.text === "for") {
+        const numIdx = skipTrivia(tokens, forIdx + 1);
+        const numTok = tokens[numIdx];
+        if (numTok && numTok.kind === "number") {
+            // Number token may be "300ms" — strip trailing units
+            duration = numTok.text.replace(/[^\d]/g, "");
+            endIdx = numIdx;
+        }
+    }
+    const args = duration ? `"${nameText}", ${duration}` : `"${nameText}"`;
+    return {
+        rewrite: {
+            span: { start: startTok.start, end: tokens[endIdx].end },
+            text: `__reactra_transition__(${args})`,
+        },
+        consumedUpTo: endIdx,
+    };
+};
+//# sourceMappingURL=rewriters.js.map