@autoview/cli 0.1.0

package/src/orchestrate/orchestrateAutoViewRender.ts

@@ -0,0 +1,1117 @@
+import { OpenApi } from "@typia/interface";
+import { IAutoViewEndpoint, toEndpoints } from "../utils";
+import { IAgenticaController, IAgenticaHistoryJson } from "@agentica/core";
+import {
+  AutoBeAutoViewRenderPageEvent,
+} from "../typings";
+import { IPointer, Singleton } from "tstl";
+import ts from "typescript";
+import typia, { ILlmApplication } from "typia";
+import { v7 } from "uuid";
+
+import { AutoViewSystemPromptConstant } from "../constants/AutoViewSystemPromptConstant";
+import { IAutoViewAgentContext } from "../context/IAutoViewAgentContext";
+import { IAutoViewProductPlan } from "./structures/IAutoViewProductPlan";
+import { IAutoViewRenderApplication } from "./structures/IAutoViewRenderApplication";
+import { IAutoViewSdkMap } from "./structures/IAutoViewSdkMap";
+import { HistoryMessage } from "./utils/HistoryMessage";
+import {
+  describeEndpointPropsShape,
+  describeRequestBodyHint,
+} from "./utils/describeEndpointPropsShape";
+import { describeEndpointRequestBodyShape } from "./utils/describeEndpointRequestBodyShape";
+import { describeEndpointResponseShape } from "./utils/describeEndpointResponseShape";
+import { executeCachedBatch } from "./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;
+
+/**
+ * Phase 4 of the AutoView agent — Render.
+ *
+ * Generates one TSX page per screen in {@link IAutoViewProductPlan} via parallel
+ * LLM calls. Each call returns the complete page source; the orchestrator runs
+ * it through TypeScript's parser and, on syntax failure, re-invokes the model
+ * with the diagnostic. Pages that still fail after {@link MAX_PARSE_RETRIES}
+ * retries are replaced with an inline error placeholder so the wider project
+ * keeps compiling.
+ *
+ * Returns a `path → content` patch keyed by the screen file path
+ * (`app/.../page.tsx`) that the orchestrator merges into the scaffold output
+ * before the `autoViewComplete` event.
+ */
+export interface IAutoViewRenderOutput {
+  /** `app/.../page.tsx` → TSX source for every rendered screen. */
+  files: Record<string, string>;
+
+  /** Per-screen render metadata, consumed by the Review phase. */
+  screens: IAutoViewRenderOutput.IScreenReport[];
+}
+
+export namespace IAutoViewRenderOutput {
+  export interface IScreenReport {
+    pagePath: string;
+    uiPattern: string;
+    actor: string;
+    rationale: string;
+    attempts: number;
+    ok: boolean;
+    /**
+     * Parser diagnostic when `ok === false`. Empty string when the page
+     * rendered cleanly.
+     */
+    diagnostic: string;
+  }
+}
+
+export async function orchestrateAutoViewRender(
+  ctx: IAutoViewAgentContext,
+  props: {
+    document: OpenApi.IDocument;
+    sdkMap: IAutoViewSdkMap;
+    productPlan: IAutoViewProductPlan;
+    designTheme: string;
+    step: number;
+  },
+): Promise<IAutoViewRenderOutput> {
+  const total = props.productPlan.screens.length;
+  const completed = { value: 0 };
+  const files: Record<string, string> = {};
+  const screens: IAutoViewRenderOutput.IScreenReport[] = [];
+  // 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;
+  await executeCachedBatch(
+    semaphoreCap,
+    props.productPlan.screens.map((screen) => async (promptCacheKey) => {
+      const counter = new Singleton(() => ++completed.value);
+      const result = await 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 as string,
+        actor: screen.actor,
+        rationale: result.rationale,
+        attempts: result.attempts,
+        ok: result.ok,
+        diagnostic: result.diagnostic,
+      });
+
+      ctx.dispatch({
+        type: "autoViewRenderPage",
+        id: v7(),
+        created_at: new Date().toISOString(),
+        step: props.step,
+        total,
+        completed: counter.get(),
+        pagePath: screen.path,
+        uiPattern: screen.uiPattern as string,
+        attempts: result.attempts,
+        ok: result.ok,
+        tokenUsage: result.tokenUsage,
+        metric: result.metric,
+      } satisfies AutoBeAutoViewRenderPageEvent);
+    }),
+  );
+
+  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.
+ */
+export async function rerenderScreenForTypecheck(
+  ctx: IAutoViewAgentContext,
+  args: {
+    screen: IAutoViewProductPlan.IScreen;
+    document: OpenApi.IDocument;
+    sdkMap: IAutoViewSdkMap;
+    designTheme: string;
+    promptCacheKey: string;
+    allScreenPaths: readonly string[];
+    previousTsx: string;
+    typecheckErrors: ITypecheckErrorLine[];
+  },
+): Promise<{ tsx: string; ok: boolean; diagnostic: string } | null> {
+  const relevantOperations = toEndpoints(args.document).filter((op) =>
+    args.screen.endpoints.includes((op.accessor ?? []).join(".")),
+  );
+
+  let previousTsx = args.previousTsx;
+  let lastParseError: string | null = null;
+  let attempt = 0;
+  for (; attempt <= MAX_PARSE_RETRIES; attempt++) {
+    const pointer: IPointer<IAutoViewRenderApplication.IProps | null> = {
+      value: null,
+    };
+    const histories =
+      attempt === 0
+        ? buildTypecheckRetryHistories({
+            ...args,
+            relevantOperations,
+            previousTsx,
+            typecheckErrors: args.typecheckErrors,
+          })
+        : buildRetryHistories({
+            ...args,
+            relevantOperations,
+            lastTsx: previousTsx,
+            lastError: 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 {
+      await 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 =
+      autoWrapNullishCoalescingMix(pointer.value.tsx) ?? pointer.value.tsx;
+    const parseError = findSyntaxError(candidate);
+    if (parseError === null) {
+      return {
+        tsx: candidate,
+        ok: true,
+        diagnostic: "",
+      };
+    }
+    previousTsx = candidate;
+    lastParseError = parseError;
+  }
+  return null;
+}
+
+/* -------------------------------------------------------------------------- */
+/* per-screen render with parser-driven retry                                 */
+/* -------------------------------------------------------------------------- */
+
+interface IRenderResult {
+  tsx: string;
+  rationale: string;
+  attempts: number;
+  ok: boolean;
+  /** Parser diagnostic when `ok === false`; empty string otherwise. */
+  diagnostic: string;
+  /**
+   * The TSX the LLM emitted on the final attempt — preserved even when the page
+   * fell back to the placeholder so the operator can inspect what the model
+   * kept trying. Empty string when `ok === true` (the shipped `tsx` is already
+   * the LLM's last attempt).
+   */
+  lastAttemptTsx: string;
+  tokenUsage: AutoBeAutoViewRenderPageEvent["tokenUsage"];
+  metric: AutoBeAutoViewRenderPageEvent["metric"];
+}
+
+async function renderOneScreen(
+  ctx: IAutoViewAgentContext,
+  args: {
+    screen: IAutoViewProductPlan.IScreen;
+    document: OpenApi.IDocument;
+    sdkMap: IAutoViewSdkMap;
+    designTheme: string;
+    promptCacheKey: string;
+    allScreenPaths: readonly string[];
+  },
+): Promise<IRenderResult> {
+  // Restrict the SDK context to the schemas the screen actually
+  // composes; the full document would blow the prompt budget on
+  // larger projects.
+  const relevantOperations = toEndpoints(args.document).filter((op) =>
+    args.screen.endpoints.includes((op.accessor ?? []).join(".")),
+  );
+
+  let lastTsx: string | null = null;
+  let lastError: string | null = null;
+  let lastRationale: string = "";
+  let attempts = 0;
+  let lastTokenUsage: AutoBeAutoViewRenderPageEvent["tokenUsage"] | null = null;
+  let lastMetric: AutoBeAutoViewRenderPageEvent["metric"] | null = null;
+
+  for (let attempt = 0; attempt <= MAX_PARSE_RETRIES; attempt++) {
+    attempts = attempt + 1;
+    const pointer: IPointer<IAutoViewRenderApplication.IProps | null> = {
+      value: null,
+    };
+    const histories =
+      attempt === 0
+        ? buildInitialHistories({ ...args, relevantOperations })
+        : buildRetryHistories({
+            ...args,
+            relevantOperations,
+            lastTsx: lastTsx ?? "",
+            lastError: 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 } = await 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 =
+      autoWrapNullishCoalescingMix(pointer.value.tsx) ?? 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 ?? "no rendering"),
+    rationale: lastRationale,
+    attempts,
+    ok: false,
+    diagnostic: lastError ?? "model did not call renderPage",
+    lastAttemptTsx: lastTsx ?? "",
+    tokenUsage: lastTokenUsage ?? zeroTokenUsage(),
+    metric: lastMetric ?? zeroMetric(),
+  };
+}
+
+function zeroTokenUsage(): AutoBeAutoViewRenderPageEvent["tokenUsage"] {
+  return {
+    total: 0,
+    input: { total: 0, cached: 0 },
+    output: {
+      total: 0,
+      reasoning: 0,
+      accepted_prediction: 0,
+      rejected_prediction: 0,
+    },
+  };
+}
+
+function zeroMetric(): AutoBeAutoViewRenderPageEvent["metric"] {
+  return {
+    attempt: 0,
+    success: 0,
+    invalidJson: 0,
+    validationFailure: 0,
+    consent: 0,
+  };
+}
+
+/* -------------------------------------------------------------------------- */
+/* prompt history builders                                                    */
+/* -------------------------------------------------------------------------- */
+
+type ConversateHistory =
+  | IAgenticaHistoryJson.ISystemMessage
+  | IAgenticaHistoryJson.IAssistantMessage;
+
+function buildInitialHistories(args: {
+  screen: IAutoViewProductPlan.IScreen;
+  sdkMap: IAutoViewSdkMap;
+  designTheme: string;
+  document: OpenApi.IDocument;
+  relevantOperations: IAutoViewEndpoint[];
+  allScreenPaths: readonly string[];
+}): ConversateHistory[] {
+  // 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) => {
+      const accessor = (op.accessor ?? []).join(".");
+      const propsShape = 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) => {
+      const hint = describeRequestBodyHint(op, args.document);
+      if (hint.length === 0) return null;
+      const accessor = (op.accessor ?? []).join(".");
+      return `- \`${accessor}\` → ${hint}`;
+    })
+    .filter((line): line is string => 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) => {
+      const accessor = (op.accessor ?? []).join(".");
+      const shape = 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) => {
+      const shape = describeEndpointRequestBodyShape(op, args.document);
+      if (shape === null) return null;
+      const accessor = (op.accessor ?? []).join(".");
+      return `### \`api.functional.${accessor}\` body shape\n\n\`\`\`ts\n${shape}\n\`\`\``;
+    })
+    .filter((line): line is string => line !== null)
+    .join("\n\n");
+
+  return [
+    HistoryMessage.system(AutoViewSystemPromptConstant.AUTOVIEW_RENDER),
+    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(
+        args.sdkMap.actors.find((a) => a.name === args.screen.actor) ?? null,
+        null,
+        2,
+      )}
+      \`\`\`
+    `,
+  ];
+}
+
+function buildRetryHistories(args: {
+  screen: IAutoViewProductPlan.IScreen;
+  sdkMap: IAutoViewSdkMap;
+  designTheme: string;
+  document: OpenApi.IDocument;
+  relevantOperations: IAutoViewEndpoint[];
+  allScreenPaths: readonly string[];
+  lastTsx: string;
+  lastError: string;
+}): ConversateHistory[] {
+  return [
+    ...buildInitialHistories(args),
+    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: {
+  screen: IAutoViewProductPlan.IScreen;
+  sdkMap: IAutoViewSdkMap;
+  designTheme: string;
+  document: OpenApi.IDocument;
+  relevantOperations: IAutoViewEndpoint[];
+  allScreenPaths: readonly string[];
+  previousTsx: string;
+  typecheckErrors: ITypecheckErrorLine[];
+}): ConversateHistory[] {
+  const lines = args.typecheckErrors
+    .map((e) => `- L${e.line}:${e.column} \`${e.code}\` — ${e.message}`)
+    .join("\n");
+  return [
+    ...buildInitialHistories(args),
+    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.
+    `,
+  ];
+}
+
+/**
+ * Tsc diagnostic line carried into the typecheck retry prompt. Mirrors the
+ * shape {@link FrontendTypecheckSession} produces but only the fields the prompt
+ * actually needs, so the orchestrator can adapt other compilers in the future
+ * without touching this history builder.
+ */
+export interface ITypecheckErrorLine {
+  line: number;
+  column: number;
+  code: string;
+  message: string;
+}
+
+/**
+ * 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: {
+  screen: IAutoViewProductPlan.IScreen;
+  sdkMap: IAutoViewSdkMap;
+  designTheme: string;
+  document: OpenApi.IDocument;
+  relevantOperations: IAutoViewEndpoint[];
+  allScreenPaths: readonly string[];
+  previousTsx: string;
+  runtimeErrors: IRuntimeErrorLine[];
+}): ConversateHistory[] {
+  const lines = args.runtimeErrors
+    .map((e) => `- \`${e.type}\` — ${e.message}`)
+    .join("\n");
+  return [
+    ...buildInitialHistories(args),
+    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.
+    `,
+  ];
+}
+
+/**
+ * Runtime diagnostic carried into the audit retry prompt. Subset of
+ * `IRuntimeAuditDiagnostic` from `auditFrontendRuntime` — the prompt only needs
+ * the type label and the message.
+ */
+export interface IRuntimeErrorLine {
+  type: "console" | "pageerror" | "navigation";
+  message: string;
+}
+
+/**
+ * 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.
+ */
+export async function rerenderScreenForRuntime(
+  ctx: IAutoViewAgentContext,
+  args: {
+    screen: IAutoViewProductPlan.IScreen;
+    document: OpenApi.IDocument;
+    sdkMap: IAutoViewSdkMap;
+    designTheme: string;
+    promptCacheKey: string;
+    allScreenPaths: readonly string[];
+    previousTsx: string;
+    runtimeErrors: IRuntimeErrorLine[];
+  },
+): Promise<{ tsx: string; ok: boolean; diagnostic: string } | null> {
+  const relevantOperations = toEndpoints(args.document).filter((op) =>
+    args.screen.endpoints.includes((op.accessor ?? []).join(".")),
+  );
+
+  let previousTsx = args.previousTsx;
+  let lastParseError: string | null = null;
+  for (let attempt = 0; attempt <= MAX_PARSE_RETRIES; attempt++) {
+    const pointer: IPointer<IAutoViewRenderApplication.IProps | null> = {
+      value: null,
+    };
+    const histories =
+      attempt === 0
+        ? buildRuntimeRetryHistories({
+            ...args,
+            relevantOperations,
+            previousTsx,
+            runtimeErrors: args.runtimeErrors,
+          })
+        : buildRetryHistories({
+            ...args,
+            relevantOperations,
+            lastTsx: previousTsx,
+            lastError: 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 {
+      await 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 =
+      autoWrapNullishCoalescingMix(pointer.value.tsx) ?? 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: string): string {
+  // 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: Array<[RegExp, string]> = [
+    [
+      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: string): string | null {
+  const source = ts.createSourceFile(
+    "Page.tsx",
+    code,
+    ts.ScriptTarget.ES2022,
+    /*setParentNodes*/ true,
+    ts.ScriptKind.TSX,
+  );
+
+  let changed = false;
+  const isNullish = (n: ts.Node): boolean =>
+    ts.isBinaryExpression(n) &&
+    n.operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken;
+  const isLogical = (n: ts.Node): boolean =>
+    ts.isBinaryExpression(n) &&
+    (n.operatorToken.kind === ts.SyntaxKind.BarBarToken ||
+      n.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken);
+
+  const transformer: ts.TransformerFactory<ts.SourceFile> = (context) => {
+    const visit: ts.Visitor = (node) => {
+      const visited = ts.visitEachChild(node, visit, context);
+      if (!ts.isBinaryExpression(visited)) return visited;
+
+      const wrap = (child: ts.Expression): ts.Expression => {
+        changed = true;
+        return ts.factory.createParenthesizedExpression(child);
+      };
+
+      const op = visited.operatorToken.kind;
+      if (
+        op === ts.SyntaxKind.BarBarToken ||
+        op === ts.SyntaxKind.AmpersandAmpersandToken
+      ) {
+        return ts.factory.updateBinaryExpression(
+          visited,
+          isNullish(visited.left) ? wrap(visited.left) : visited.left,
+          visited.operatorToken,
+          isNullish(visited.right) ? wrap(visited.right) : visited.right,
+        );
+      }
+      if (op === ts.SyntaxKind.QuestionQuestionToken) {
+        return ts.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) => ts.visitNode(root, visit) as ts.SourceFile;
+  };
+
+  const result = ts.transform(source, [transformer]);
+  const printer = ts.createPrinter({
+    newLine: ts.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: string): string | null {
+  const source = ts.createSourceFile(
+    "Page.tsx",
+    code,
+    ts.ScriptTarget.ES2022,
+    /*setParentNodes*/ false,
+    ts.ScriptKind.TSX,
+  );
+  const diagnostics: readonly ts.Diagnostic[] =
+    (source as unknown as { parseDiagnostics?: ts.Diagnostic[] })
+      .parseDiagnostics ?? [];
+  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.
+ */
+export function screenPathToFile(routePath: string): string {
+  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.
+ */
+export function fileToScreenPath(filePath: string): string | null {
+  if (filePath === "app/page.tsx") return "/";
+  const match = /^app\/(.+)\/page\.tsx$/.exec(filePath);
+  if (match === null) return null;
+  return `/${match[1]}`;
+}
+
+function buildPlaceholderPage(
+  screen: IAutoViewProductPlan.IScreen,
+  reason: string,
+): string {
+  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: {
+  build: (next: IAutoViewRenderApplication.IProps) => void;
+}): IAgenticaController.IClass {
+  const application: ILlmApplication =
+    typia.llm.application<IAutoViewRenderApplication>();
+
+  return {
+    protocol: "class",
+    name: "autoViewRenderPage",
+    application,
+    execute: {
+      renderPage: (next) => {
+        props.build(next);
+      },
+    } satisfies IAutoViewRenderApplication,
+  };
+}