@autoview/cli 0.1.0

package/lib/orchestrate/orchestrateAutoViewRender.js

@@ -0,0 +1,943 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.orchestrateAutoViewRender = orchestrateAutoViewRender;
+exports.rerenderScreenForTypecheck = rerenderScreenForTypecheck;
+exports.rerenderScreenForRuntime = rerenderScreenForRuntime;
+exports.screenPathToFile = screenPathToFile;
+exports.fileToScreenPath = fileToScreenPath;
+const __typia_transform__validateReport = __importStar(require("typia/lib/internal/_validateReport"));
+const __typia_transform__llmApplicationFinalize = __importStar(require("typia/lib/internal/_llmApplicationFinalize"));
+const utils_1 = require("../utils");
+const tstl_1 = require("tstl");
+const typescript_1 = __importDefault(require("typescript"));
+const typia_1 = __importDefault(require("typia"));
+const uuid_1 = require("uuid");
+const HistoryMessage_1 = require("./utils/HistoryMessage");
+const describeEndpointPropsShape_1 = require("./utils/describeEndpointPropsShape");
+const describeEndpointRequestBodyShape_1 = require("./utils/describeEndpointRequestBodyShape");
+const describeEndpointResponseShape_1 = require("./utils/describeEndpointResponseShape");
+const executeCachedBatch_1 = require("./utils/executeCachedBatch");
+// Five tries (one initial + four retries). The earlier limit of two
+// retries silently dropped landing pages with multiple orthogonal
+// defects — TC39 mix, unclosed JSX, regex escapes — because the model
+// only managed to fix the first issue per attempt. Five tries gives
+// the retry loop enough budget to converge on common LLM mistakes
+// without ballooning per-page latency past ~30s.
+const MAX_PARSE_RETRIES = 4;
+function orchestrateAutoViewRender(ctx, props) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const total = props.productPlan.screens.length;
+        const completed = { value: 0 };
+        const files = {};
+        const screens = [];
+        // Pre-compute the list of frontend routes the plan declared so the
+        // render prompt can teach the LLM which `<Link href=...>` targets
+        // actually exist. Without this the model routinely linked to SDK
+        // accessor paths (`/shoppings/customers/systematic/channels`) that
+        // 404 the moment the user clicks them.
+        const allScreenPaths = props.productPlan.screens.map((s) => s.path);
+        const semaphoreCap = typeof ctx.vendor.semaphore === "number"
+            ? ctx.vendor.semaphore
+            : ctx.vendor.semaphore !== undefined
+                ? ctx.vendor.semaphore.max()
+                : 8;
+        yield (0, executeCachedBatch_1.executeCachedBatch)(semaphoreCap, props.productPlan.screens.map((screen) => (promptCacheKey) => __awaiter(this, void 0, void 0, function* () {
+            const counter = new tstl_1.Singleton(() => ++completed.value);
+            const result = yield renderOneScreen(ctx, {
+                screen,
+                document: props.document,
+                sdkMap: props.sdkMap,
+                designTheme: props.designTheme,
+                promptCacheKey,
+                allScreenPaths,
+            });
+            const filePath = screenPathToFile(screen.path);
+            files[filePath] = result.tsx;
+            // Preserve the LLM's final raw attempt next to the wiki when the
+            // page fell back to the placeholder. Without this the operator
+            // (and future render-prompt iterations) cannot see what the model
+            // actually emitted — only the placeholder text — so the same
+            // class of defect keeps recurring across archives.
+            if (!result.ok && result.lastAttemptTsx.length > 0) {
+                const slug = screen.path.replace(/[^A-Za-z0-9]+/g, "_").replace(/^_+|_+$/g, "") ||
+                    "root";
+                files[`wiki/render-failed/${slug}.tsx`] = result.lastAttemptTsx;
+            }
+            screens.push({
+                pagePath: screen.path,
+                uiPattern: screen.uiPattern,
+                actor: screen.actor,
+                rationale: result.rationale,
+                attempts: result.attempts,
+                ok: result.ok,
+                diagnostic: result.diagnostic,
+            });
+            ctx.dispatch({
+                type: "autoViewRenderPage",
+                id: (0, uuid_1.v7)(),
+                created_at: new Date().toISOString(),
+                step: props.step,
+                total,
+                completed: counter.get(),
+                pagePath: screen.path,
+                uiPattern: screen.uiPattern,
+                attempts: result.attempts,
+                ok: result.ok,
+                tokenUsage: result.tokenUsage,
+                metric: result.metric,
+            });
+        })));
+        return { files, screens };
+    });
+}
+/**
+ * Re-render a single screen after the typecheck phase reported diagnostics on
+ * its file. Reuses the parser-driven retry loop inside the per-screen render —
+ * the first attempt uses {@link buildTypecheckRetryHistories} (which surfaces
+ * the diagnostics + previous TSX), and any subsequent retries fall back to
+ * {@link buildRetryHistories} so the model still benefits from the deterministic
+ * `??`/`||` auto-fix and the syntax retry budget.
+ *
+ * Returns `null` when the model could not produce parser-valid TSX after the
+ * full retry budget; the caller should leave the existing (broken) file in
+ * place and report the failure so the operator still gets some output.
+ */
+function rerenderScreenForTypecheck(ctx, args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const relevantOperations = (0, utils_1.toEndpoints)(args.document).filter((op) => { var _a; return args.screen.endpoints.includes(((_a = op.accessor) !== null && _a !== void 0 ? _a : []).join(".")); });
+        let previousTsx = args.previousTsx;
+        let lastParseError = null;
+        let attempt = 0;
+        for (; attempt <= MAX_PARSE_RETRIES; attempt++) {
+            const pointer = {
+                value: null,
+            };
+            const histories = attempt === 0
+                ? buildTypecheckRetryHistories(Object.assign(Object.assign({}, args), { relevantOperations,
+                    previousTsx, typecheckErrors: args.typecheckErrors }))
+                : buildRetryHistories(Object.assign(Object.assign({}, args), { relevantOperations, lastTsx: previousTsx, lastError: lastParseError !== null && lastParseError !== void 0 ? lastParseError : "" }));
+            const userMessage = attempt === 0
+                ? `Fix the typecheck errors on ${args.screen.path}. Re-emit the entire page TSX with the corrections. Call \`renderPage\` once.`
+                : `The corrected attempt failed TypeScript parsing: ${lastParseError}. Regenerate the entire page TSX with the fix applied.`;
+            try {
+                yield ctx.conversate({
+                    source: "autoViewRenderPage",
+                    target: args.screen.path,
+                    controller: createController({
+                        build: (next) => {
+                            pointer.value = next;
+                        },
+                    }),
+                    enforceFunctionCall: true,
+                    promptCacheKey: args.promptCacheKey,
+                    histories,
+                    userMessage,
+                });
+            }
+            catch (error) {
+                // Vendor-side failure during the typecheck-driven retry. Don't let
+                // it reject the whole retry batch — record and retry, falling
+                // through to `null` if the budget runs out so the caller keeps the
+                // previously-rendered (typecheck-broken) file instead of aborting
+                // the entire run.
+                lastParseError = error instanceof Error ? error.message : String(error);
+                continue;
+            }
+            if (pointer.value === null) {
+                // Model refused to call renderPage on this attempt — escalate to
+                // the parser-retry pathway with the previous TSX still in scope.
+                lastParseError = "model did not call renderPage";
+                continue;
+            }
+            const candidate = (_a = autoWrapNullishCoalescingMix(pointer.value.tsx)) !== null && _a !== void 0 ? _a : pointer.value.tsx;
+            const parseError = findSyntaxError(candidate);
+            if (parseError === null) {
+                return {
+                    tsx: candidate,
+                    ok: true,
+                    diagnostic: "",
+                };
+            }
+            previousTsx = candidate;
+            lastParseError = parseError;
+        }
+        return null;
+    });
+}
+function renderOneScreen(ctx, args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        // Restrict the SDK context to the schemas the screen actually
+        // composes; the full document would blow the prompt budget on
+        // larger projects.
+        const relevantOperations = (0, utils_1.toEndpoints)(args.document).filter((op) => { var _a; return args.screen.endpoints.includes(((_a = op.accessor) !== null && _a !== void 0 ? _a : []).join(".")); });
+        let lastTsx = null;
+        let lastError = null;
+        let lastRationale = "";
+        let attempts = 0;
+        let lastTokenUsage = null;
+        let lastMetric = null;
+        for (let attempt = 0; attempt <= MAX_PARSE_RETRIES; attempt++) {
+            attempts = attempt + 1;
+            const pointer = {
+                value: null,
+            };
+            const histories = attempt === 0
+                ? buildInitialHistories(Object.assign(Object.assign({}, args), { relevantOperations }))
+                : buildRetryHistories(Object.assign(Object.assign({}, args), { relevantOperations, lastTsx: lastTsx !== null && lastTsx !== void 0 ? lastTsx : "", lastError: lastError !== null && lastError !== void 0 ? lastError : "" }));
+            const userMessage = attempt === 0
+                ? `Render the page for ${args.screen.path} (${args.screen.uiPattern}). Call \`renderPage\` once.`
+                : `The previous attempt failed TypeScript parsing: ${lastError}. Regenerate the entire page TSX with the fix applied. Pay attention to: escaping \`/\` inside regex literals as \`\\/\`, wrapping mixed \`??\` and \`||\` with parentheses, and closing every \`{\` opened inside JSX.`;
+            try {
+                const { metric, tokenUsage } = yield ctx.conversate({
+                    source: "autoViewRenderPage",
+                    target: args.screen.path,
+                    controller: createController({
+                        build: (next) => {
+                            pointer.value = next;
+                        },
+                    }),
+                    enforceFunctionCall: true,
+                    promptCacheKey: args.promptCacheKey,
+                    histories,
+                    userMessage,
+                });
+                lastTokenUsage = tokenUsage;
+                lastMetric = metric;
+            }
+            catch (error) {
+                // Vendor-side failure (connection drop / undici `terminated`, 5xx,
+                // rate limit). On larger SDKs the per-screen render fan-out keeps
+                // dozens of LLM calls in flight and one dropped socket would
+                // otherwise reject the whole `executeCachedBatch` and abort every
+                // other screen mid-flight. Treat it like a failed attempt: record
+                // the reason, let the retry loop try again, and fall back to the
+                // placeholder if the budget runs out — the project still ships.
+                lastError =
+                    error instanceof Error
+                        ? `vendor error: ${error.message}`
+                        : `vendor error: ${String(error)}`;
+                continue;
+            }
+            if (pointer.value === null) {
+                // No function call. Treat as fatal — break to the placeholder.
+                break;
+            }
+            // Deterministic auto-fix: LLMs reliably re-emit `a ?? b || c` /
+            // `a || b ?? c` even with hard rules in the prompt. Walk the AST,
+            // parenthesize every nullish-coalescing branch nested inside a
+            // logical-or / logical-and (and vice versa), and re-check. This
+            // costs zero extra LLM calls and turns a guaranteed placeholder
+            // into a working page.
+            const candidate = (_a = autoWrapNullishCoalescingMix(pointer.value.tsx)) !== null && _a !== void 0 ? _a : pointer.value.tsx;
+            lastTsx = candidate;
+            lastRationale = pointer.value.rationale;
+            const parseError = findSyntaxError(candidate);
+            if (parseError === null) {
+                return {
+                    tsx: candidate,
+                    rationale: lastRationale,
+                    attempts,
+                    ok: true,
+                    diagnostic: "",
+                    lastAttemptTsx: "",
+                    tokenUsage: lastTokenUsage,
+                    metric: lastMetric,
+                };
+            }
+            lastError = parseError;
+        }
+        // Exhausted retries — ship a placeholder so the rest of the project
+        // still compiles. Surface the reason inline.
+        return {
+            tsx: buildPlaceholderPage(args.screen, lastError !== null && lastError !== void 0 ? lastError : "no rendering"),
+            rationale: lastRationale,
+            attempts,
+            ok: false,
+            diagnostic: lastError !== null && lastError !== void 0 ? lastError : "model did not call renderPage",
+            lastAttemptTsx: lastTsx !== null && lastTsx !== void 0 ? lastTsx : "",
+            tokenUsage: lastTokenUsage !== null && lastTokenUsage !== void 0 ? lastTokenUsage : zeroTokenUsage(),
+            metric: lastMetric !== null && lastMetric !== void 0 ? lastMetric : zeroMetric(),
+        };
+    });
+}
+function zeroTokenUsage() {
+    return {
+        total: 0,
+        input: { total: 0, cached: 0 },
+        output: {
+            total: 0,
+            reasoning: 0,
+            accepted_prediction: 0,
+            rejected_prediction: 0,
+        },
+    };
+}
+function zeroMetric() {
+    return {
+        attempt: 0,
+        success: 0,
+        invalidJson: 0,
+        validationFailure: 0,
+        consent: 0,
+    };
+}
+function buildInitialHistories(args) {
+    var _a;
+    // Deterministic per-endpoint `props` shape. The LLM has repeatedly
+    // flattened body fields into the top level of `props` (e.g.
+    // `index(connection, { limit: 24 })` instead of
+    // `index(connection, { body: { limit: 24 } })`), which makes the
+    // simulator return a masked 400 and the page renders the empty
+    // state. Pre-computing the exact shape kills that whole class of
+    // defect at zero LLM cost. Parameterless endpoints render as
+    // `(connection)` because the Nestia SDK omits the second arg
+    // entirely when there are no path params or body — emitting
+    // `(connection, {})` here teaches the LLM a signature that fails
+    // `npm run typecheck` with "Expected 1 arguments, but got 2".
+    const propsSignatures = args.relevantOperations
+        .map((op) => {
+        var _a;
+        const accessor = ((_a = op.accessor) !== null && _a !== void 0 ? _a : []).join(".");
+        const propsShape = (0, describeEndpointPropsShape_1.describeEndpointPropsShape)(op);
+        const signature = propsShape === "{}"
+            ? `api.functional.${accessor}(connection)`
+            : `api.functional.${accessor}(connection, ${propsShape})`;
+        return `- \`${signature}\``;
+    })
+        .join("\n");
+    // Per-endpoint required-fields hint + sample body literal. Stops the
+    // model from sending `{ body: {} }` to endpoints with required fields
+    // (cart create, etc.) — which used to come back as a typia validation
+    // 400 the user sees as "Unable to load …" with no actionable signal.
+    const bodyHints = args.relevantOperations
+        .map((op) => {
+        var _a;
+        const hint = (0, describeEndpointPropsShape_1.describeRequestBodyHint)(op, args.document);
+        if (hint.length === 0)
+            return null;
+        const accessor = ((_a = op.accessor) !== null && _a !== void 0 ? _a : []).join(".");
+        return `- \`${accessor}\` → ${hint}`;
+    })
+        .filter((line) => line !== null)
+        .join("\n");
+    // Per-endpoint return-type shape, fully expanded one or two levels. The LLM
+    // has the raw OpenAPI JSON below, but routinely invents plausible-sounding
+    // properties (`auth.member.email` on an `IAuthorized` whose real shape is
+    // `{ id, created_at, token }`). Spelling out the actual fields up front
+    // anchors the render against the SDK return type instead of the model's
+    // domain priors.
+    const responseShapes = args.relevantOperations
+        .map((op) => {
+        var _a;
+        const accessor = ((_a = op.accessor) !== null && _a !== void 0 ? _a : []).join(".");
+        const shape = (0, describeEndpointResponseShape_1.describeEndpointResponseShape)(op, args.document);
+        return `### \`api.functional.${accessor}\` → Promise<${shape}>`;
+    })
+        .join("\n\n");
+    // Symmetric input-side expansion. The one-line `bodyHints` block above shows
+    // required keys + a sample literal but stops short of nested union / array
+    // shapes, which is exactly where the LLM hallucinates (sort grammars as
+    // `{ field, direction }[]` instead of `("created_at.asc" | ...)[]`, or
+    // invented top-level `title` fields on search request types). Surfacing the
+    // full body shape closes that gap without changing any other prompt
+    // mechanics.
+    const requestShapes = args.relevantOperations
+        .map((op) => {
+        var _a;
+        const shape = (0, describeEndpointRequestBodyShape_1.describeEndpointRequestBodyShape)(op, args.document);
+        if (shape === null)
+            return null;
+        const accessor = ((_a = op.accessor) !== null && _a !== void 0 ? _a : []).join(".");
+        return `### \`api.functional.${accessor}\` body shape\n\n\`\`\`ts\n${shape}\n\`\`\``;
+    })
+        .filter((line) => line !== null)
+        .join("\n\n");
+    return [
+        HistoryMessage_1.HistoryMessage.system("<!--\nfilename: AUTOVIEW_RENDER.md\n-->\nYou are the Render phase of the AutoView agent.\n\nYou receive one screen from the product plan and produce a complete,\nrunnable Next.js page (TSX) that composes the SDK endpoints listed for\nthat screen into a single coherent UI. You are not redesigning the\nproduct, choosing the actor, or inventing endpoints \u2014 those decisions\nwere already made by the Product Plan phase. You translate the plan\ninto TSX.\n\n## Stack\n\n- Next.js 15 App Router. Output a single TSX file with `export default\n  function Page()`.\n- React 18 client component by default. Start the file with\n  `\"use client\";` because every page calls the SDK from the browser.\n- shadcn/ui primitives, already vendored under `@/components/ui/*`.\n  Common primitives available: `Button`, `Card` (with `CardHeader`,\n  `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`),\n  `Input`, `Label`, `Table` (`TableHeader`, `TableBody`, `TableHead`,\n  `TableRow`, `TableCell`, `TableCaption`), `Dialog`, `Sheet`,\n  `Tabs`, `Select`, `Pagination`, `Badge`, `Skeleton`. Compose them.\n- Tailwind utilities for layout and spacing. The CSS variables behind\n  shadcn (`--background`, `--foreground`, `--primary`, \u2026) are\n  configured in `globals.css`. Stick to the design tokens unless the\n  design theme asks for otherwise.\n- TypeScript strict. No `any` cast that isn't justified by the SDK\n  surface. Use the SDK's exported types directly.\n\n## SDK access\n\nThe bundled SDK adapter exposes the AutoBE-generated API like this:\n\n```ts\nimport api from \"@/src/api\";\nimport { connection } from \"@/src/lib/connection\";\n```\n\nEvery accessor takes **`(connection, props)`**. The shape of `props` is\nfixed by Nestia and **must** match the operation's path parameters and\nrequest body. Getting this wrong is the single most common AutoView\nruntime defect, so read this section carefully before writing any\nfetch.\n\n### Nestia `props` shape \u2014 derive it from the operation, never guess\n\nFor each operation listed in the screen's `endpoints`, the operation\npayload (passed to you in the prompt) carries `parameters` (path\nparameters) and `requestBody` (body schema). Translate them into\n`props` deterministically:\n\n| Operation shape                                               | `props` shape                                  |\n| ------------------------------------------------------------- | ---------------------------------------------- |\n| Path parameters only (GET / DELETE, e.g. `at`, `erase`)       | `{ paramA, paramB }`                           |\n| Body only (POST / PATCH / PUT at root, e.g. `index`, `create` at `/sales`) | `{ body: { ... } }`                            |\n| Path + body (PUT / PATCH / POST under `/.../:id`)             | `{ id, body: { ... } }`                        |\n| Multiple path params + body                                   | `{ saleId, questionId, body: { ... } }`        |\n| No params, no body                                            | `{}` (rare; only when `parameters` is empty AND `requestBody` is `null`) |\n\nConcrete examples that match the real shopping SDK exactly:\n\n```ts\n// PATCH /sales (list). `requestBody` is `IShoppingSale.IRequest`,\n// `parameters` is empty \u2192 wrap the search fields under `body`.\nconst sales = await api.functional.shoppings.customers.sales.index(\n  connection,\n  { body: { page: 1, limit: 24, search: { title: \"macbook\" } } },\n);\n\n// GET /sales/:id. `parameters` has `id`, `requestBody` is null \u2192\n// pass the path param at the top level, no `body`.\nconst sale = await api.functional.shoppings.customers.sales.at(\n  connection,\n  { id: saleId },\n);\n\n// POST /sales/:saleId/reviews. `parameters` has `saleId`,\n// `requestBody` is `IShoppingReview.ICreate` \u2192 both at the top.\nconst review = await api.functional.shoppings.customers.sales.reviews.create(\n  connection,\n  { saleId, body: { score: 5, title: \"great\", body: \"loved it\" } },\n);\n```\n\n**Never** put body fields at the top level of `props`. Writing\n`api.functional.sales.index(connection, { limit: 24 })` looks intuitive\nbut passes `undefined` as `props.body`; in simulate mode the SDK's\ntypia.assert rejects the call, the simulator returns a 400 error\nmasked as the success Response shape, and the UI silently renders the\nempty state because `.data` ends up as an error object whose `.length`\nis undefined. Always wrap.\n\nLikewise, **never** pass `{}` (or `{ body: {} }`) to an endpoint whose\n`requestBody` schema declares required fields. The prompt context\nincludes a \"Body required-fields hint\" block that lists every required\nkey per endpoint plus a sample literal \u2014 copy the sample shape as the\nstarting `body` and only override the fields you actually need:\n\n- `cart create` requires `commodity_ids` and `pseudos` \u2014 pass\n  `{ body: { commodity_ids: [], pseudos: [] } }` when the user has not\n  added anything yet, then mutate as they click \"Add to cart\". Never\n  send an empty body that fails validation immediately on mount.\n- List endpoints (`index`) with required `page` / `limit` \u2014 pass\n  `{ body: { page: 1, limit: 24 } }`. Even when you do not want a\n  filter, the body has to satisfy the schema.\n\nIf a required field is genuinely unknown at the call site (e.g. an\nopaque id the user has not selected yet), do not issue the SDK call \u2014\ngate it behind the user action that produces the id, and render an\ninformative empty state until then.\n\nUse exactly the accessor paths listed in the screen's `endpoints` array\n\u2014 do not invent helpers or new accessors. The connection has\n`simulate: true` wired by default, so the calls will work offline.\n\n## Data fetching\n\n- `useEffect` + `useState`. Each `endpoints[]` entry maps to one async\n  call. Run them in parallel with `Promise.all` unless one depends on\n  another.\n- Always handle four states: `loading`, `error`, `empty`, and `data`.\n  Show a `Skeleton` block during loading, a destructive `Card` for\n  errors with a `Retry` button, an empty state with a one-line\n  explanation when the list comes back empty, and the real UI when\n  data is present.\n- Surface server error messages from `instanceof HttpError`-style\n  catches. Never silently swallow.\n\n### Use SDK types directly \u2014 infer them, never hand-write them\n\nThe SDK's returned objects are typia-validated and exactly match the\ngenerated types. When `simulate: true`, `typia.random<T>()` produces\nmocks that follow those types byte-for-byte. The trap is that AutoBE's\nOpenAPI inverter sometimes emits the page shape as a **monomorphized**\ntype (e.g. `IPageIShoppingSale.ISummary`) instead of a generic\n`IPage<T>`. Importing `IPage` and writing `IPage<IShoppingSale.ISummary>`\nwill compile but `IPage` resolves to an empty namespace at runtime, so\n`useState<IPage<...> | null>(null)` produces a mock whose `.data`\nfield is `undefined` and the page crashes with\n`.filter is not a function`.\n\nThe bulletproof pattern is to let TypeScript infer the response type\nfrom the SDK function itself, not to hand-write the type name:\n\n```ts\ntype SalesResponse = Awaited<\n  ReturnType<typeof api.functional.shoppings.customers.sales.index>\n>;\nconst [sales, setSales] = useState<SalesResponse | null>(null);\n// ...\nuseEffect(() => {\n  api.functional.shoppings.customers.sales\n    .index(connection, { body: { page: 1, limit: 24 } })\n    .then(setSales);\n}, []);\n// `sales.data` is now correctly typed as `IShoppingSale.ISummary[]`\n// regardless of whether the SDK names the page `IPage<T>` or\n// `IPageIShoppingSale.ISummary`.\n```\n\nUse the `Awaited<ReturnType<typeof api.functional.xxx>>` pattern for\nevery SDK call \u2014 list endpoints and detail endpoints alike. It is\nrobust against the inverter's naming choices.\n\nOther ironclad rules:\n\n- Do not hand-type the response as `IPage<X>` unless you have\n  confirmed via the inference pattern that the SDK actually exposes\n  that generic. In most AutoBE-generated archives it does not.\n- Never widen with `as AnyPage<T>` / `as Record<string, unknown>` /\n  `as { data?: T[] }` etc. Broad casts lose the type and push you\n  into runtime guard code that crashes when the mock shape does not\n  match your guess.\n- Never write fallback chains like\n  `page?.data ?? page?.items ?? page?.rows ?? []`. The SDK never\n  returns `items` or `rows` \u2014 only `data`. The fallback only fires\n  when your type assumption is already wrong, and it hides the real\n  defect behind a `.filter is not a function` runtime error.\n- Never wrap a response in a helper that returns `unknown[]`. Type\n  the state with the inferred response type and call\n  `.data.filter(...)` / `.data.map(...)` directly.\n- Never write `as never`, `as unknown as X`, or `as any` to push a\n  value past the type checker. These casts lie about the SDK shape\n  and always break at runtime. The only allowed escape is `as const`\n  on inline literals.\n- Never combine optional chaining with a direct method call:\n  `sale?.units.find(...)`, `cart?.items.map(...)`, `page?.data.reduce(...)`.\n  When `sale` is `undefined` the whole expression evaluates to\n  `undefined`, but TypeScript stops checking the `.units` access at\n  the `?.` and lets the `.find` slip through. At runtime the page\n  crashes with `Cannot read properties of undefined (reading 'find')`\n  even though `tsc --noEmit` was green. The two safe shapes are\n  `(sale?.units ?? []).find(...)` (when you want the empty fallback)\n  and `sale?.units?.find(...)` (when you want the whole expression\n  to short-circuit to `undefined`). Use the empty-array form for any\n  array you immediately render or count; use the `?.` form when the\n  result feeds another optional chain. The same rule covers\n  `.map / .filter / .reduce / .some / .every / .forEach / .slice /\n  .sort / .at` on arrays and `Object.keys / Object.entries /\n  Object.values` on objects: `(obj?.things ?? {})` before\n  `Object.keys`.\n- The same rule applies to **multi-step** property chains:\n  `order?.summary.ticket_payments[0]` crashes when `summary` is\n  `undefined` because the optional chain stops at `order?.` and the\n  `.summary.ticket_payments[0]` access slips through. Apply `?.` to\n  every nullable hop, not just the first: write\n  `order?.summary?.ticket_payments?.[0]` (note the `?.[` for the\n  index), or guard the parent once with\n  `const summary = order?.summary; if (summary === undefined) return \u2026;`\n  before the array read. The runtime audit catches dozens of these\n  per shopping run when the rule is only applied to the first hop.\n- Never call a `setState` (`setX(...)`, `dispatch(...)`,\n  `useTransition` start, etc.) directly inside the render body. React\n  throws \"Cannot update a component while rendering a different\n  component\" and the page crashes after the first render. Common\n  triggers and fixes:\n  - Computing derived state? Use `useMemo`, not `setState` inside the\n    body.\n  - Reacting to a prop change? Use `useEffect(() => { setX(...); },\n    [prop])`.\n  - Bailing out early on bad data? Render a fallback `<>...</>`\n    directly \u2014 do **not** call `setError(...)` mid-render.\n  - Need to sync with an external store? Use `useSyncExternalStore`\n    or move the side effect into `useEffect`.\n  Setter calls are always either inside an event handler, inside a\n  `useEffect` (or its return), or inside a `useMemo`/`useCallback`\n  dependency-aware factory \u2014 never at the top level of the component\n  function.\n\nIf the screen's accessor returns a single object (not a page), the\nsame inference pattern works \u2014 `type SaleResponse = Awaited<ReturnType<\ntypeof api.functional.shoppings.customers.sales.at>>` and\n`useState<SaleResponse | null>(null)`.\n\n### Retry, refetch, and pagination handlers must produce new values\n\nState setters in click handlers must change the state. Patterns like\n`onClick={() => setPage((p) => p)}` or `onClick={() => setData(data)}`\ndo nothing \u2014 the user clicks \"Retry\" and the page does not reset.\nConcrete rules:\n\n- Retry buttons reset to the initial state and re-run the load\n  effect: `setError(null); setLoading(true); setPage(1); refresh();`.\n- Pagination buttons update to the new page: `setPage(page + 1)` /\n  `setPage(page - 1)`. Never `setPage((p) => p)`.\n- Refresh / refetch buttons should trigger the same `useEffect` that\n  the initial load uses \u2014 either via a bumped `refreshKey` state or a\n  dedicated `refresh()` callback.\n\n## Rendering SDK objects \u2014 never dump, always pick named fields\n\nThe SDK returns typed objects. Render only the fields you can name\nfrom the operation's `responseBody` and the schema (`name`, `title`,\n`code`, `nickname`, `status`, `price`, `summary`, `created_at`, \u2026). If\nyou do not know which field to show, choose `name ?? title ?? code ??\nid` and stop \u2014 never reach for the whole object.\n\n**Strict ban on object dumps in JSX**. The model has a strong tendency\nto escape unknown shapes by writing `{JSON.stringify(item)}` (or\n`item.toString()`, or `<pre>{JSON.stringify(item, null, 2)}</pre>`)\nstraight into a `Card` / `TableCell` / `div`. This is forbidden in\nevery form, including:\n\n- `<div>{JSON.stringify(channel)}</div>`\n- `<TableCell>{JSON.stringify(sale).slice(0, 60)}</TableCell>`\n- `<pre>{JSON.stringify(channel, null, 2)}</pre>`\n- `<span>{String(item)}</span>` for any non-primitive `item`\n- `{`${item.id}: ${JSON.stringify(item)}`}`\n\nThe rendered page is a product surface, not a debug view. A page that\ndumps JSON looks broken even when the data flowed correctly.\n\nAllowed substitutes when the data is unfamiliar mock content:\n\n- Pick the most identifying string field from the schema (`name`,\n  `title`, `nickname`, `code`) and show that.\n- If multiple objects share the same shape, render them in a `Table`\n  with one column per known field plus a trailing \"Details\" link that\n  navigates to the detail page declared in the product plan.\n- For truly opaque payloads (rare; only when the schema is `unknown`\n  or `Record<string, never>`), render a single muted line such as\n  \"Imported entry \u00B7 click Inspect to view raw fields\" rather than the\n  JSON itself.\n\n**Long string overflow**. Mock data from `typia.random()` regularly\nproduces 50+ character UUIDs, slugs, and base64-like values for `code`\n/ `name` / `description` fields. Every string element you render from\nthe SDK must be wrapped with overflow controls so it cannot blow out\nthe column:\n\n- Single-line cells / headers: add `truncate` (single line, ellipsis).\n- Multi-line descriptions: add `line-clamp-2` or `line-clamp-3`.\n- Free-form text inside cards: add `break-words` so long words wrap.\n- Inside `<TableCell>`: combine `max-w-xs truncate` (or wider) so the\n  table layout stays within the container.\n\nSkipping these classes produces the \"horizontal scroll bar of doom\"\nthat pushes the search bar and pagination buttons off-screen.\n\n## Routing\n\n- Dynamic params come from `useParams()` from `next/navigation`.\n- Internal navigation uses `Link` from `next/link` or\n  `useRouter().push()`. No external links unless the SDK returns them\n  explicitly.\n\n## Responsive shape\n\n- Mobile-first. The page must be usable at 360px width.\n- Use Tailwind responsive prefixes (`sm:`, `md:`, `lg:`) when laying\n  out grids, tables, or sidebars.\n- Tables collapse to stacked cards on `sm` and below for shopping /\n  catalog-style flows; admin tables can stay tabular if the design\n  theme says enterprise.\n\n## Forms\n\n- `react-hook-form` is available \u2014 use it for any input with two or\n  more fields. Wire `Input` / `Select` / `Label` to the form state.\n- Validate on submit, not on every keystroke (avoid flicker).\n- Disable the submit button while the SDK call is in flight.\n- Toast the result with a `Card` or inline `Badge` rather than\n  `alert()`.\n\n## What the produced TSX MUST contain\n\n- `\"use client\";` at the top.\n- A single default export named `Page`.\n- All imports resolved against `@/...` (alias for repo root) or\n  `next/*`.\n- Real data wiring through the listed SDK endpoints, not fake static\n  arrays.\n- All four UI states (loading / error / empty / data).\n- Tailwind classes that satisfy the design theme. Empty design theme\n  means prototype-first, content-first defaults.\n\n## What you must NOT produce\n\n- Do not invent SDK accessors. Use what `endpoints[]` declares.\n- Do not flatten request bodies into the top level of `props`. List\n  endpoints take `{ body: { page, limit, search, sort } }`, not\n  `{ page, limit, search, sort }`. Passing the flat shape causes the\n  simulator to return a masked 400 and the page renders the empty\n  state instead of data \u2014 see the \"Nestia `props` shape\" subsection.\n- Do not pass an empty `{}` to a list endpoint. List endpoints have a\n  required `body`; the minimum is `{ body: { page: 1, limit: 24 } }`.\n- Do not dump SDK objects with `JSON.stringify(item)`,\n  `String(item)`, `item.toString()`, or `<pre>{JSON.stringify(item,\n  null, 2)}</pre>` inside JSX. The page is a product surface, not a\n  debug view \u2014 see the \"Rendering SDK objects\" section above for the\n  allowed alternatives.\n- Do not omit overflow controls on SDK-derived strings. Every\n  `<TableCell>` / `<div>` / `<span>` that prints a mock string needs\n  `truncate`, `line-clamp-N`, or `break-words` so a 60-character UUID\n  cannot push the layout off-screen.\n- Do not import shadcn primitives the project does not ship. Stick to\n  the list above.\n- Do not declare local `AnyPage<T>` / `AnyResponse` aliases or\n  `getItems()` helpers \u2014 see the \"Use SDK types directly\" rule above.\n  Import the SDK type and reach into `.data` straight away.\n- Do not write `as never`, `as any`, or `as unknown as X`. These casts\n  silently break the SDK type contract and crash at runtime. The one\n  allowed escape is `as const` on inline literals.\n- Do not write identity state updates like `setPage((p) => p)` or\n  `setData(data)` in retry / refetch / pagination handlers. Every\n  setter call must produce a new value \u2014 see the \"Retry, refetch,\n  and pagination\" rules under Data fetching.\n- Do not write `a ?? b || c` or `a || b ?? c`. TC39 forbids mixing\n  `??` with `||` / `&&` without parentheses, and the parser will\n  reject the page. If you really need both, parenthesize explicitly:\n  `(a ?? b) || c`. Same rule applies inside JSX attribute values.\n  Easier: **avoid `??` in any expression that already contains `||`\n  or `&&`**. Use a ternary instead (e.g.\n  `(a !== null && a !== undefined) ? a : (b || c)`) or just chain\n  `||` everywhere. The retry loop will not save you here; pages that\n  mix `??` with `||` consistently get dropped to an error\n  placeholder.\n- Do not link to backend / SDK accessor paths from `<Link>` or\n  `router.push()`. Those paths (e.g.\n  `/shoppings/customers/systematic/channels`, `/shoppings/customers/sales/:id`)\n  are HTTP endpoints, not Next.js routes. The product plan lists\n  every real frontend route in `screen.path`. Use only those \u2014\n  `/catalog`, `/cart`, `/orders/[id]`, `/admin`, etc. Internal links\n  to anything else 404 the moment a user clicks them.\n- Do not render `<Image />` from `next/image` for URLs the SDK\n  returns. The SDK mocks emit arbitrary hostnames and the optimizer\n  rejects them. Use a plain `<img />` tag for SDK-provided URLs, or\n  pass `unoptimized` on the `<Image />` element.\n- Do not write Korean.\n- Do not output anything except the function-call payload.\n\n## Output\n\nCall `renderPage` exactly once with the complete TSX source code as a\nsingle string. The orchestrator runs the result through the TypeScript\nparser; if it fails, you will be invoked again with the diagnostic and\na chance to repair it. Take the repair seriously \u2014 the most common LLM\nerrors are `??` mixed with `||` without parentheses, regex literals\nwith unescaped slashes, and unclosed JSX expression braces." /* AutoViewSystemPromptConstant.AUTOVIEW_RENDER */),
+        HistoryMessage_1.HistoryMessage.assistant `
+      Here is the screen to render and everything you need to compose
+      it.
+
+      ## Screen
+
+      \`\`\`json
+      ${JSON.stringify(args.screen, null, 2)}
+      \`\`\`
+
+      ## Allowed internal route paths (use only these in \`<Link href=...>\` / \`router.push()\`)
+
+      ${args.allScreenPaths.map((p) => `- \`${p}\``).join("\n")}
+
+      ## SDK call signatures (use these \`props\` shapes verbatim)
+
+      ${propsSignatures}
+
+      ## Body required-fields hint (start each \`body: { ... }\` with at least these keys)
+
+      ${bodyHints.length > 0 ? bodyHints : "(no endpoints with a request body)"}
+
+      ## SDK return type shapes (use these exact field names + nesting — do not invent properties)
+
+      ${responseShapes.length > 0 ? responseShapes : "(no endpoints with a response body)"}
+
+      ## SDK request body shapes (use these exact field names + nesting — do not invent properties)
+
+      ${requestShapes.length > 0 ? requestShapes : "(no endpoints with a request body)"}
+
+      ## SDK endpoints used by this screen (full operation payloads)
+
+      \`\`\`json
+      ${JSON.stringify(args.relevantOperations, null, 2)}
+      \`\`\`
+
+      ## Design theme
+
+      ${args.designTheme.length > 0 ? args.designTheme : "(none — prototype-first, content-first defaults)"}
+
+      ## Actor context (from the SDK map)
+
+      \`\`\`json
+      ${JSON.stringify((_a = args.sdkMap.actors.find((a) => a.name === args.screen.actor)) !== null && _a !== void 0 ? _a : null, null, 2)}
+      \`\`\`
+    `,
+    ];
+}
+function buildRetryHistories(args) {
+    return [
+        ...buildInitialHistories(args),
+        HistoryMessage_1.HistoryMessage.assistant `
+      My previous attempt failed TypeScript syntax check.
+
+      ## Previous TSX
+
+      \`\`\`tsx
+      ${args.lastTsx}
+      \`\`\`
+
+      ## Syntax error reported by the compiler
+
+      \`\`\`
+      ${args.lastError}
+      \`\`\`
+    `,
+    ];
+}
+/**
+ * History builder for the typecheck-driven retry pass. Differs from
+ * {@link buildRetryHistories} in that it lists every `tsc --noEmit` diagnostic
+ * on this file (not a single parser error) and explicitly anchors the LLM to
+ * the SDK-shape sections from the initial history — the typical failure mode is
+ * the model inventing property names that look plausible against domain priors
+ * instead of reading the schema we already spelled out.
+ */
+function buildTypecheckRetryHistories(args) {
+    const lines = args.typecheckErrors
+        .map((e) => `- L${e.line}:${e.column} \`${e.code}\` — ${e.message}`)
+        .join("\n");
+    return [
+        ...buildInitialHistories(args),
+        HistoryMessage_1.HistoryMessage.assistant `
+      My previous attempt compiled cleanly but failed \`tsc --noEmit\` against
+      the assembled project. The errors all anchor on the SDK boundary — they
+      are caused by accessing properties, calling functions, or passing values
+      whose shape does not match what the SDK actually exposes.
+
+      ## Previous TSX
+
+      \`\`\`tsx
+      ${args.previousTsx}
+      \`\`\`
+
+      ## TypeScript errors on this file
+
+      ${lines}
+
+      Re-emit the entire page TSX with these errors fixed. Use only field
+      names and call signatures that match the "SDK return type shapes" and
+      "SDK request body shapes" sections above — do not invent properties,
+      do not assume snake_case when the schema uses camelCase, and do not add
+      a second argument to a parameterless endpoint.
+    `,
+    ];
+}
+/**
+ * History builder for the Phase 6 runtime-driven retry pass. The Playwright
+ * audit captures console errors, uncaught page exceptions, and navigation
+ * failures that the parser + typecheck gates cannot see — typically
+ * `obj?.array.method(...)` undefined-access on simulator data, react render
+ * crashes against missing optional fields, or hydration mismatches. Surfacing
+ * the captured messages back into the render prompt lets the LLM rewrite the
+ * page against the actual failure mode instead of guessing.
+ */
+function buildRuntimeRetryHistories(args) {
+    const lines = args.runtimeErrors
+        .map((e) => `- \`${e.type}\` — ${e.message}`)
+        .join("\n");
+    return [
+        ...buildInitialHistories(args),
+        HistoryMessage_1.HistoryMessage.assistant `
+      My previous attempt typechecked cleanly but crashed at runtime when
+      Playwright loaded it under \`next dev\` (simulator mode). The errors
+      below are the live console / uncaught exception / navigation
+      diagnostics — typescript could not see them because the access pattern
+      uses optional chaining that short-circuits past the unsafe call site.
+
+      ## Previous TSX
+
+      \`\`\`tsx
+      ${args.previousTsx}
+      \`\`\`
+
+      ## Runtime errors on this page
+
+      ${lines}
+
+      Re-emit the entire page TSX with these errors fixed. Common causes:
+      - \`obj?.array.method(...)\` — fix by writing \`(obj?.array ?? []).method(...)\`
+        or \`obj?.array?.method(...)\` so the short-circuit covers the call.
+      - Property access on a value that can be \`null\`/\`undefined\` in
+        simulator data — narrow with explicit guards before reading.
+      - Components that crash on empty arrays — render an empty state when
+        the SDK returns \`[]\`.
+      Use only field names and shapes from the "SDK return type shapes" and
+      "SDK request body shapes" sections above. Do not invent properties.
+    `,
+    ];
+}
+/**
+ * Re-render a single screen after the Phase 6 runtime audit reported broken
+ * navigation / console / pageerror diagnostics on its page. Identical
+ * retry-loop shape to {@link rerenderScreenForTypecheck}: the first attempt uses
+ * {@link buildRuntimeRetryHistories} (which surfaces the live runtime errors +
+ * previous TSX) and any subsequent retries fall back to
+ * {@link buildRetryHistories} so the parser-driven safety net still applies.
+ *
+ * Returns `null` when the model could not produce parser-valid TSX after the
+ * full retry budget; the caller should leave the existing (broken) file in
+ * place.
+ */
+function rerenderScreenForRuntime(ctx, args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const relevantOperations = (0, utils_1.toEndpoints)(args.document).filter((op) => { var _a; return args.screen.endpoints.includes(((_a = op.accessor) !== null && _a !== void 0 ? _a : []).join(".")); });
+        let previousTsx = args.previousTsx;
+        let lastParseError = null;
+        for (let attempt = 0; attempt <= MAX_PARSE_RETRIES; attempt++) {
+            const pointer = {
+                value: null,
+            };
+            const histories = attempt === 0
+                ? buildRuntimeRetryHistories(Object.assign(Object.assign({}, args), { relevantOperations,
+                    previousTsx, runtimeErrors: args.runtimeErrors }))
+                : buildRetryHistories(Object.assign(Object.assign({}, args), { relevantOperations, lastTsx: previousTsx, lastError: lastParseError !== null && lastParseError !== void 0 ? lastParseError : "" }));
+            const userMessage = attempt === 0
+                ? `Fix the runtime errors on ${args.screen.path}. Re-emit the entire page TSX with the corrections. Call \`renderPage\` once.`
+                : `The corrected attempt failed TypeScript parsing: ${lastParseError}. Regenerate the entire page TSX with the fix applied.`;
+            try {
+                yield ctx.conversate({
+                    source: "autoViewRenderPage",
+                    target: args.screen.path,
+                    controller: createController({
+                        build: (next) => {
+                            pointer.value = next;
+                        },
+                    }),
+                    enforceFunctionCall: true,
+                    promptCacheKey: args.promptCacheKey,
+                    histories,
+                    userMessage,
+                });
+            }
+            catch (error) {
+                // Vendor-side failure during the runtime-driven retry. Same policy
+                // as the typecheck retry: record, retry, and fall through to `null`
+                // so the caller keeps the previous file rather than aborting.
+                lastParseError = error instanceof Error ? error.message : String(error);
+                continue;
+            }
+            if (pointer.value === null) {
+                lastParseError = "model did not call renderPage";
+                continue;
+            }
+            const candidate = (_a = autoWrapNullishCoalescingMix(pointer.value.tsx)) !== null && _a !== void 0 ? _a : pointer.value.tsx;
+            const parseError = findSyntaxError(candidate);
+            if (parseError === null) {
+                return { tsx: candidate, ok: true, diagnostic: "" };
+            }
+            previousTsx = candidate;
+            lastParseError = parseError;
+        }
+        return null;
+    });
+}
+/* -------------------------------------------------------------------------- */
+/* syntax validation                                                          */
+/* -------------------------------------------------------------------------- */
+/**
+ * Run the rendered TSX through TypeScript's tolerant parser plus a focused
+ * regex for `??` / `||` mixing — the model's most common grammar error that the
+ * parser flags only post-parse.
+ */
+/**
+ * Walk the TypeScript AST and parenthesize every `??` branch that sits directly
+ * inside a `||` / `&&` expression, and vice versa. TC39 forbids mixing the two
+ * without explicit parens, and even with the prompt rule the model keeps
+ * re-emitting `a ?? b || c`. Doing it deterministically after the LLM call
+ * costs no extra inference and avoids the retry budget being burned on
+ * grammar-only defects.
+ *
+ * Returns the rewritten source when at least one fix landed, `null` when
+ * nothing needed changing or the rewrite failed validation (so the caller can
+ * fall back to the original text).
+ */
+const NULLISH_MIX_REGEX = /\?\?[^()?|]{0,400}\|\||\|\|[^()|?]{0,400}\?\?|\?\?[^()?&]{0,400}&&|&&[^()&?]{0,400}\?\?/;
+/**
+ * Last-resort textual rewrite for the cases the AST visitor below cannot reach
+ * (parser bails out at the diagnostic, printer optimizes the parens away,
+ * etc.). Iteratively wraps every `??`-pair adjacent to a `||` or `&&` token.
+ * Pattern recognizes identifiers, dotted property access, subscript access,
+ * function calls with no nested parens, and template literals — enough to
+ * handle the LLM's typical landing-page expressions.
+ *
+ * Conservative on purpose: complex expressions where the operands cross parens
+ * or another operator are left alone, so the retry loop still has the original
+ * code to repair from.
+ */
+function regexWrapNullishMix(code) {
+    // An "atom" the wrapper is comfortable picking up as one of the
+    // `??` operands. Covers:
+    //   - identifiers and dotted chains (`obj.foo.bar`)
+    //   - optional chains (`obj?.foo?.bar`)
+    //   - subscript access (`arr[i]`, single-level)
+    //   - balanced function calls (`fn(...)`, single nesting level)
+    //   - type-cast wrappers (`(value as Type)` and `(value as Type).prop`)
+    //   - string / number / boolean / null literals
+    //   - empty / shallow array / object literals (`[]`, `{}`)
+    // Anything more exotic falls back to the AST visitor or the retry
+    // budget — but this covers ~95% of LLM-generated landing-page code.
+    const ID = String.raw `[A-Za-z_$][\w$]*`;
+    const CAST = String.raw `\(\s*${ID}(?:\.${ID})*\s+as\s+[A-Za-z_$][\w$<>.,\s\[\]?|&]*?\s*\)`;
+    const LITERAL = String.raw `"[^"\n]{0,80}"|'[^'\n]{0,80}'|\d+(?:\.\d+)?|true|false|null|undefined|\[\s*\]|\{\s*\}`;
+    const HEAD = String.raw `(?:${LITERAL}|${CAST}|${ID})`;
+    const TAIL = String.raw `(?:\??\.${ID}|\[[^\[\]\n]{1,80}\]|\([^()\n]{0,200}\))*`;
+    const ATOM = `${HEAD}${TAIL}`;
+    const pairs = [
+        [
+            new RegExp(`(?<![\\w(])(${ATOM}\\s*\\?\\?\\s*${ATOM})(\\s*(?:\\|\\||&&))`, "g"),
+            "($1)$2",
+        ],
+        [
+            new RegExp(`((?:\\|\\||&&)\\s*)(${ATOM}\\s*\\?\\?\\s*${ATOM})(?![\\w)])`, "g"),
+            "$1($2)",
+        ],
+    ];
+    let prev = "";
+    let curr = code;
+    let iterations = 0;
+    while (prev !== curr && iterations < 10) {
+        prev = curr;
+        for (const [re, replacement] of pairs) {
+            curr = curr.replace(re, replacement);
+        }
+        iterations++;
+    }
+    return curr;
+}
+function autoWrapNullishCoalescingMix(code) {
+    const source = typescript_1.default.createSourceFile("Page.tsx", code, typescript_1.default.ScriptTarget.ES2022, 
+    /*setParentNodes*/ true, typescript_1.default.ScriptKind.TSX);
+    let changed = false;
+    const isNullish = (n) => typescript_1.default.isBinaryExpression(n) &&
+        n.operatorToken.kind === typescript_1.default.SyntaxKind.QuestionQuestionToken;
+    const isLogical = (n) => typescript_1.default.isBinaryExpression(n) &&
+        (n.operatorToken.kind === typescript_1.default.SyntaxKind.BarBarToken ||
+            n.operatorToken.kind === typescript_1.default.SyntaxKind.AmpersandAmpersandToken);
+    const transformer = (context) => {
+        const visit = (node) => {
+            const visited = typescript_1.default.visitEachChild(node, visit, context);
+            if (!typescript_1.default.isBinaryExpression(visited))
+                return visited;
+            const wrap = (child) => {
+                changed = true;
+                return typescript_1.default.factory.createParenthesizedExpression(child);
+            };
+            const op = visited.operatorToken.kind;
+            if (op === typescript_1.default.SyntaxKind.BarBarToken ||
+                op === typescript_1.default.SyntaxKind.AmpersandAmpersandToken) {
+                return typescript_1.default.factory.updateBinaryExpression(visited, isNullish(visited.left) ? wrap(visited.left) : visited.left, visited.operatorToken, isNullish(visited.right) ? wrap(visited.right) : visited.right);
+            }
+            if (op === typescript_1.default.SyntaxKind.QuestionQuestionToken) {
+                return typescript_1.default.factory.updateBinaryExpression(visited, isLogical(visited.left) ? wrap(visited.left) : visited.left, visited.operatorToken, isLogical(visited.right) ? wrap(visited.right) : visited.right);
+            }
+            return visited;
+        };
+        return (root) => typescript_1.default.visitNode(root, visit);
+    };
+    const result = typescript_1.default.transform(source, [transformer]);
+    const printer = typescript_1.default.createPrinter({
+        newLine: typescript_1.default.NewLineKind.LineFeed,
+        removeComments: false,
+    });
+    let printed = changed ? printer.printFile(result.transformed[0]) : code;
+    result.dispose();
+    // Fallback for cases the AST visitor cannot reach (TS parser bails
+    // out at the diagnostic, the printer optimizes the parens away,
+    // etc.). Iteratively wrap remaining `?? ||` / `?? &&` pairs with a
+    // textual rewrite limited to atomic operands. Brute force but
+    // reliable for the LLM's typical landing-page expressions.
+    if (NULLISH_MIX_REGEX.test(printed)) {
+        const swept = regexWrapNullishMix(printed);
+        if (swept !== printed) {
+            printed = swept;
+            changed = true;
+        }
+    }
+    if (!changed)
+        return null;
+    // Safety net: only return the rewrite when it actually clears the
+    // grammar-error regex. If both AST and the textual fallback gave up,
+    // leave the original alone so the retry loop still has a shot.
+    if (NULLISH_MIX_REGEX.test(printed)) {
+        return null;
+    }
+    return printed;
+}
+function findSyntaxError(code) {
+    var _a;
+    const source = typescript_1.default.createSourceFile("Page.tsx", code, typescript_1.default.ScriptTarget.ES2022, 
+    /*setParentNodes*/ false, typescript_1.default.ScriptKind.TSX);
+    const diagnostics = (_a = source
+        .parseDiagnostics) !== null && _a !== void 0 ? _a : [];
+    if (diagnostics.length > 0) {
+        const first = diagnostics[0];
+        const message = typeof first.messageText === "string"
+            ? first.messageText
+            : first.messageText.messageText;
+        if (first.start !== undefined) {
+            const { line, character } = source.getLineAndCharacterOfPosition(first.start);
+            // Line + column alone is not enough for the model to fix the
+            // error — it cannot see the source, so it tends to repeat the
+            // same defect. Include a small slice of the surrounding code so
+            // the retry attempt has concrete context.
+            const lines = code.split("\n");
+            const start = Math.max(0, line - 2);
+            const end = Math.min(lines.length, line + 3);
+            const snippet = lines
+                .slice(start, end)
+                .map((text, idx) => {
+                const lineNo = start + idx + 1;
+                const marker = lineNo === line + 1 ? ">" : " ";
+                return `${marker} ${lineNo.toString().padStart(4, " ")} | ${text}`;
+            })
+                .join("\n");
+            return `Line ${line + 1}, column ${character + 1}: ${message}\n\n${snippet}`;
+        }
+        return message;
+    }
+    if (NULLISH_MIX_REGEX.test(code)) {
+        return "Mixing `??` with `||` / `&&` is a TC39 grammar error — wrap the nullish-coalescing branch in parentheses (e.g. `(a ?? b) || c`).";
+    }
+    return null;
+}
+/* -------------------------------------------------------------------------- */
+/* path mapping + placeholder fallback                                        */
+/* -------------------------------------------------------------------------- */
+/**
+ * Map a planner-emitted screen path (`/`, `/cart`, `/todos/[id]/edit`) to the
+ * Next.js app-router file the scaffold writes for it. Exposed so the
+ * typecheck-driven retry loop can look up which screen owns a given broken file
+ * and re-render it directly.
+ */
+function screenPathToFile(routePath) {
+    const trimmed = routePath.replace(/^\/+/, "").replace(/\/+$/, "");
+    if (trimmed.length === 0)
+        return "app/page.tsx";
+    return `app/${trimmed}/page.tsx`;
+}
+/**
+ * Inverse of {@link screenPathToFile}. Returns `null` when the path does not
+ * match the `app/.../page.tsx` shape the scaffold writes — e.g. for shared
+ * components or wiki files, which are not screen-owned and therefore cannot be
+ * fixed by re-rendering a single screen.
+ */
+function fileToScreenPath(filePath) {
+    if (filePath === "app/page.tsx")
+        return "/";
+    const match = /^app\/(.+)\/page\.tsx$/.exec(filePath);
+    if (match === null)
+        return null;
+    return `/${match[1]}`;
+}
+function buildPlaceholderPage(screen, reason) {
+    const title = JSON.stringify(screen.title);
+    const purpose = JSON.stringify(screen.purpose);
+    const pattern = JSON.stringify(screen.uiPattern);
+    const actor = JSON.stringify(screen.actor);
+    const endpointsArrayLit = JSON.stringify(screen.endpoints);
+    const reasonLit = JSON.stringify(reason);
+    return `"use client";
+
+// AutoView Render: this page failed to generate cleanly after the
+// retry budget. The placeholder keeps \`next build\` green; check
+// \`wiki/sdk-feedback.md\` for the root cause.
+
+export default function Page() {
+  const endpoints: readonly string[] = ${endpointsArrayLit};
+  return (
+    <main className="container mx-auto py-10">
+      <p className="text-xs uppercase tracking-wide text-destructive">
+        AutoView render failed · {${pattern}}
+      </p>
+      <h1 className="mt-2 text-3xl font-bold tracking-tight">{${title}}</h1>
+      <p className="mt-3 text-muted-foreground">{${purpose}}</p>
+      <p className="mt-2 text-xs text-muted-foreground">
+        Actor: <span className="font-mono">{${actor}}</span>
+      </p>
+      {endpoints.length > 0 ? (
+        <div className="mt-4 rounded-md border bg-muted/30 p-3">
+          <p className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+            Planned SDK endpoints
+          </p>
+          <ul className="mt-2 space-y-1 text-xs font-mono">
+            {endpoints.map((accessor) => (
+              <li key={accessor}>{accessor}</li>
+            ))}
+          </ul>
+        </div>
+      ) : null}
+      <details className="mt-6 rounded-lg border border-destructive/40 bg-destructive/5 p-4">
+        <summary className="cursor-pointer text-sm font-medium text-destructive">Show parser diagnostic</summary>
+        <pre className="mt-2 whitespace-pre-wrap text-xs text-muted-foreground">{${reasonLit}}</pre>
+      </details>
+    </main>
+  );
+}
+`;
+}
+/* -------------------------------------------------------------------------- */
+/* controller wiring                                                          */
+/* -------------------------------------------------------------------------- */
+function createController(props) {
+    const application = __typia_transform__llmApplicationFinalize._llmApplicationFinalize({
+        functions: [
+            {
+                name: "renderPage",
+                parameters: {
+                    description: "Current Type: {@link IAutoViewRenderApplication.IProps}",
+                    type: "object",
+                    properties: {
+                        rationale: {
+                            description: "One-line rationale explaining the rendering choices for this screen \u2014\nwhich shadcn primitives were composed, why pagination vs. infinite\nscroll, etc. Surfaced in the `autoViewRenderPage` event so the operator\ncan audit decisions without reading every TSX file.",
+                            type: "string"
+                        },
+                        tsx: {
+                            description: "Complete TSX source for the page. Starts with `\"use client\";` and exports\na single default `Page` function.",
+                            type: "string"
+                        }
+                    },
+                    required: [
+                        "rationale",
+                        "tsx"
+                    ],
+                    additionalProperties: false,
+                    $defs: {}
+                },
+                description: "Emit the complete TSX source for one Next.js page.\n\nCall this exactly once per screen. The returned source must include `\"use\nclient\";`, a single default `Page` export, every import the file uses, and\nexplicit handling of the four UI states (loading / error / empty / data).",
+                validate: (() => { const _io0 = input => "string" === typeof input.rationale && "string" === typeof input.tsx; const _vo0 = (input, _path, _exceptionable = true) => ["string" === typeof input.rationale || _report(_exceptionable, {
+                        path: _path + ".rationale",
+                        expected: "string",
+                        value: input.rationale
+                    }), "string" === typeof input.tsx || _report(_exceptionable, {
+                        path: _path + ".tsx",
+                        expected: "string",
+                        value: input.tsx
+                    })].every(flag => flag); const __is = input => "object" === typeof input && null !== input && _io0(input); let errors; let _report; return input => {
+                    if (false === __is(input)) {
+                        errors = [];
+                        _report = __typia_transform__validateReport._validateReport(errors);
+                        ((input, _path, _exceptionable = true) => ("object" === typeof input && null !== input || _report(true, {
+                            path: _path + "",
+                            expected: "IAutoViewRenderApplication.IProps",
+                            value: input
+                        })) && _vo0(input, _path + "", true) || _report(true, {
+                            path: _path + "",
+                            expected: "IAutoViewRenderApplication.IProps",
+                            value: input
+                        }))(input, "$input", true);
+                        const success = 0 === errors.length;
+                        return success ? {
+                            success,
+                            data: input
+                        } : {
+                            success,
+                            errors,
+                            data: input
+                        };
+                    }
+                    return {
+                        success: true,
+                        data: input
+                    };
+                }; })()
+            }
+        ]
+    });
+    return {
+        protocol: "class",
+        name: "autoViewRenderPage",
+        application,
+        execute: {
+            renderPage: (next) => {
+                props.build(next);
+            },
+        },
+    };
+}
+//# sourceMappingURL=orchestrateAutoViewRender.js.map