@autoview/cli 0.1.0

package/src/orchestrate/utils/renderResourcePage.ts

@@ -0,0 +1,1624 @@
+import { OpenApi } from "@typia/interface";
+
+import {
+  extractFields,
+  extractFieldsFromSchema,
+  findCollectionField,
+  IFieldSpec,
+  imageFieldOf,
+  resolveProperties,
+  titleFieldOf,
+} from "../../utils/extractFields";
+import { IAutoViewEndpoint } from "../../utils/toEndpoints";
+import { IAutoViewProductPlan } from "../structures/IAutoViewProductPlan";
+
+/**
+ * Deterministic page generator — the replacement for the LLM Render phase.
+ *
+ * Given one planned screen and the operations it composes, emit a complete,
+ * runnable `page.tsx` that wires the typed SDK call to one of the universal
+ * `Resource*` components (table / detail / form / landing). The component set is
+ * static (shipped in the template); this only produces the thin per-route page:
+ *
+ * - column / field metadata baked from {@link extractFields} (every property of
+ *   the row / response / request type → one column / row / input — dense and
+ *   complete by construction, never an LLM-chosen subset),
+ * - a typed SDK call whose `props` argument is cast to
+ *   `Parameters<typeof api.functional.X.method>[1]` so the generated project
+ *   typechecks against Nestia's exact generated types without this generator
+ *   needing to import them.
+ *
+ * Same swagger → same pages, every run. No LLM, no retries, no typecheck
+ * roulette.
+ */
+export function renderResourcePage(
+  screen: IAutoViewProductPlan.IScreen,
+  endpoints: IAutoViewEndpoint[],
+  document: OpenApi.IDocument,
+  allScreens: IAutoViewProductPlan.IScreen[],
+): string {
+  switch (screen.uiPattern) {
+    case "landing":
+      return renderLanding(screen, allScreens, endpoints, document);
+    case "table":
+      return renderTable(screen, endpoints, document, allScreens);
+    case "catalog":
+      return renderCatalog(screen, endpoints, document, allScreens);
+    case "detail":
+      return renderDetail(screen, endpoints, document, allScreens);
+    case "form":
+      return renderForm(screen, endpoints, document);
+    default:
+      // dashboard / wizard not modeled deterministically yet — fall back to a
+      // table off the primary endpoint so the screen still shows real data.
+      return renderTable(screen, endpoints, document, allScreens);
+  }
+}
+
+/* -------------------------------------------------------------------------- */
+/* shared helpers                                                             */
+/* -------------------------------------------------------------------------- */
+
+const lit = (value: unknown): string => JSON.stringify(value);
+
+/** A JS property name reachable with dot notation. */
+const JS_IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+/**
+ * Emit a member access that is valid even when the key is not a JS identifier.
+ * Inline response collections key the array off whatever the API named it, and
+ * real swaggers use names like `1-clicks` (DigitalOcean) that nestia sanitizes
+ * in the SDK accessor (`_1_clicks`) but that survive verbatim as the response
+ * object key (`res["1_clicks"]`). Dot access there is a hard syntax error, so
+ * fall back to bracket access for any non-identifier key.
+ */
+function memberOf(base: string, key: string): string {
+  return JS_IDENT.test(key) ? `${base}.${key}` : `${base}[${lit(key)}]`;
+}
+
+/** Turn an accessor segment (`cancel`, `bulkErase`) into a button label. */
+function titleizeSegment(segment: string): string {
+  const spaced = segment
+    .replace(/[_-]+/g, " ")
+    .replace(/([a-z])([A-Z])/g, "$1 $2");
+  return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+
+/** Primary operation for a screen = the first accessor in `endpoints`. */
+function primaryOp(
+  screen: IAutoViewProductPlan.IScreen,
+  endpoints: IAutoViewEndpoint[],
+): IAutoViewEndpoint | null {
+  const primary = screen.endpoints[0];
+  if (primary === undefined) return null;
+  return (
+    endpoints.find((op) => op.accessor.join(".") === primary) ?? null
+  );
+}
+
+/** Field names that identify a record — shown first in a dense table. */
+const LABEL_NAMES = new Set([
+  "name",
+  "title",
+  "label",
+  "code",
+  "nickname",
+  "email",
+  "status",
+  "state",
+  "type",
+]);
+
+/** Column display rank: readable scalars first, heavy nested shapes last. */
+function columnRank(f: IFieldSpec): number {
+  const n = f.name.toLowerCase();
+  if (LABEL_NAMES.has(n)) return 0;
+  if (n === "id" || n.endsWith("_id")) return 1;
+  if (f.kind === "enum" || f.kind === "boolean") return 2;
+  if (f.kind === "number") return 3;
+  if (f.kind === "string") return 4; // includes dates
+  // ref / object / array / union / unknown — the noisy `{…}` / count cells last.
+  return 6;
+}
+
+/**
+ * Order table columns so the human-readable fields (name, status, code, id,
+ * enums, dates) come first and the heavy nested shapes (refs, objects, arrays)
+ * trail at the end. Stable within a rank, so the swagger's field order is kept
+ * as the tiebreaker. Keeps EVERY column (density) but makes the left edge — what
+ * the user sees without scrolling — the useful part.
+ */
+function orderColumns(fields: IFieldSpec[]): IFieldSpec[] {
+  return fields
+    .map((f, i) => ({ f, i }))
+    .sort((a, b) => columnRank(a.f) - columnRank(b.f) || a.i - b.i)
+    .map((x) => x.f);
+}
+
+/** Subset of a field spec carried into the page as a `ColumnSpec` literal. */
+/** A type name's base, dropping the variant suffix: `IShoppingSale.ISummary`
+ *  → `IShoppingSale`, so a ref field's variant still resolves to its resource. */
+function baseTypeName(name: string): string {
+  return name.split(".")[0] ?? name;
+}
+
+/**
+ * Map a record TYPE to the list route whose detail screen renders it, so a ref
+ * field holding that type can link to its detail page. Built from the detail
+ * screens' primary response types — purely structural, no domain knowledge.
+ */
+function resourceLinkIndex(
+  allScreens: IAutoViewProductPlan.IScreen[],
+  endpoints: IAutoViewEndpoint[],
+): Map<string, string> {
+  const index = new Map<string, string>();
+  for (const s of allScreens) {
+    if (s.uiPattern !== "detail") continue;
+    const typeName = primaryOp(s, endpoints)?.responseBody?.typeName;
+    if (typeName === undefined) continue;
+    const base = s.path.replace(/\/\[[^\]]+\]$/, ""); // /sales/[id] → /sales
+    // Only top-level resources: a nested detail's base still carries unfilled
+    // parent brackets (`/channels/[channelsId]/categories`), which would make
+    // `${base}/${id}` a broken bracket href. Link only to clean routes.
+    if (base.includes("[")) continue;
+    const key = baseTypeName(typeName);
+    if (!index.has(key)) index.set(key, base);
+  }
+  return index;
+}
+
+function toColumnSpec(
+  f: IFieldSpec,
+  linkIndex?: Map<string, string>,
+): Record<string, unknown> {
+  const spec: Record<string, unknown> = { name: f.name, kind: f.kind };
+  if (f.format !== undefined) spec.format = f.format;
+  if (f.ref !== undefined) spec.ref = f.ref;
+  if (f.itemKind !== undefined) spec.itemKind = f.itemKind;
+  if (f.enumValues !== undefined) spec.enumValues = f.enumValues;
+  // A ref whose type resolves to a browsable resource becomes a link to that
+  // resource's detail (`/sellers/${value.id}`). Skipped for catalog cards
+  // (which are already wrapped in a link) by not passing an index there.
+  if (linkIndex !== undefined && f.kind === "ref" && f.ref !== undefined) {
+    const base = linkIndex.get(baseTypeName(f.ref));
+    if (base !== undefined) spec.hrefBase = base;
+  }
+  return spec;
+}
+
+function toFieldInput(f: IFieldSpec): Record<string, unknown> {
+  return { ...toColumnSpec(f), required: f.required };
+}
+
+/** A runtime default literal for a required field, so live calls don't 400. */
+function defaultLiteralForField(f: IFieldSpec): string {
+  switch (f.kind) {
+    case "number":
+      return "0";
+    case "boolean":
+      return "false";
+    case "enum":
+      return f.enumValues && f.enumValues.length > 0
+        ? lit(f.enumValues[0])
+        : '""';
+    case "string":
+      return '""';
+    case "array":
+      return "[]";
+    default:
+      return "{}";
+  }
+}
+
+/** Required-field defaults for a named component schema, as an object literal. */
+function bodyDefaultsLiteral(typeName: string, doc: OpenApi.IDocument): string {
+  const required = extractFields(typeName, doc).filter((f) => f.required);
+  if (required.length === 0) return "{}";
+  const parts = required.map(
+    (f) => `${lit(f.name)}: ${defaultLiteralForField(f)}`,
+  );
+  return `{ ${parts.join(", ")} }`;
+}
+
+/** A default literal for a query schema property. */
+function defaultFromSchema(
+  schema: OpenApi.IJsonSchema,
+  doc?: OpenApi.IDocument,
+): string {
+  // A schema-declared `default` wins — it is the value the API author intended
+  // (e.g. petstore's `status` defaults to `available`), and a missing query
+  // param the server treats as required would otherwise 400.
+  const declared = (schema as { default?: unknown }).default;
+  if (declared !== undefined) return lit(declared as string | number | boolean);
+  // A bare `const` (a single-value enum / discriminant, `{ const: "pending" }`)
+  // is itself the concrete value.
+  if ("const" in schema)
+    return lit((schema as { const: string | number | boolean }).const);
+  if ("$ref" in schema && typeof schema.$ref === "string") {
+    // Resolve a named enum/type so its value can be read, when we have the doc.
+    const target = doc?.components?.schemas?.[schema.$ref.split("/").pop() ?? ""];
+    return target !== undefined ? defaultFromSchema(target, doc) : "{}";
+  }
+  if ("oneOf" in schema && Array.isArray(schema.oneOf)) {
+    // upgradeDocument normalizes a string enum into `oneOf: [{ const }, …]` —
+    // the first non-null const is a safe concrete value.
+    for (const branch of schema.oneOf) {
+      if (branch && "const" in branch) return lit(branch.const);
+    }
+    return "{}";
+  }
+  if (!("type" in schema)) return "{}";
+  switch (schema.type) {
+    case "boolean":
+      return "false";
+    case "integer":
+    case "number":
+      return "0";
+    case "string": {
+      const enumValues = (schema as { enum?: Array<string | number> }).enum;
+      if (Array.isArray(enumValues) && enumValues.length > 0)
+        return lit(enumValues[0]);
+      return '""';
+    }
+    case "array":
+      return "[]";
+    default:
+      return "{}";
+  }
+}
+
+/** True when a property carries a usable default-ish value (default or enum). */
+function hasUsableDefault(schema: OpenApi.IJsonSchema): boolean {
+  if ((schema as { default?: unknown }).default !== undefined) return true;
+  if ("const" in schema) return true;
+  const enumValues = (schema as { enum?: unknown[] }).enum;
+  if (Array.isArray(enumValues) && enumValues.length > 0) return true;
+  if ("oneOf" in schema && Array.isArray(schema.oneOf))
+    return schema.oneOf.some((b) => b && "const" in b);
+  return false;
+}
+
+/**
+ * Default literal for an SDK call's `query` object. Resolves `$ref` / `allOf`
+ * (nestia promotes a query into a named component like `IApiX.GetQuery`, so the
+ * schema is a `$ref` with no inline `properties`), then fills every property
+ * that is REQUIRED or carries a schema default. The latter matters because a
+ * spec-optional param with a `default` is often server-required (petstore's
+ * `status`) — sending it keeps the list call from 400-ing on first load.
+ */
+function queryDefaultsLiteral(
+  schema: OpenApi.IJsonSchema,
+  doc: OpenApi.IDocument,
+): string {
+  const { properties, required } = resolveProperties(schema, doc);
+  const requiredSet = new Set(required);
+  const parts: string[] = [];
+  for (const [name, prop] of Object.entries(properties)) {
+    if (!requiredSet.has(name) && !hasUsableDefault(prop)) continue;
+    parts.push(`${lit(name)}: ${defaultFromSchema(prop, doc)}`);
+  }
+  return parts.length > 0 ? `{ ${parts.join(", ")} }` : "{}";
+}
+
+/**
+ * Build the `props` object literal for an SDK call.
+ *
+ * - path parameters reference the `const <name>` variables the page declares
+ *   from `useParams()`,
+ * - `query` / `body` are filled with required-field defaults (or, for a form,
+ *   the live `values` object),
+ *
+ * Returns `null` when the operation takes neither params, query, nor body — the
+ * caller then emits `fn(connection)` with no second argument (Nestia drops it).
+ */
+function buildProps(
+  op: IAutoViewEndpoint,
+  doc: OpenApi.IDocument,
+  opts: { bodyExpr?: string } = {},
+): string | null {
+  const parts: string[] = [];
+  for (const p of op.parameters) parts.push(`${p.name}: ${p.name}`);
+  if (op.query !== null) parts.push(`query: ${queryDefaultsLiteral(op.query, doc)}`);
+  if (op.requestBody !== null) {
+    parts.push(
+      `body: ${opts.bodyExpr ?? bodyDefaultsLiteral(op.requestBody.typeName, doc)}`,
+    );
+  }
+  return parts.length > 0 ? `{ ${parts.join(", ")} }` : null;
+}
+
+/**
+ * `api.functional.<accessor>(connection[, props])`. The props argument is cast
+ * through `unknown` to `Parameters<typeof fn>[1]` — a path param sourced from
+ * `useParams()` is a string, while the SDK may type an id as `number`, and a
+ * form body is a `Record`, while the SDK types it as a specific interface.
+ * Casting through `unknown` guarantees the generated project compiles against
+ * ANY swagger's exact Nestia types; the values themselves are schema-correct
+ * (numeric params are coerced with `Number(...)`, bodies use schema defaults).
+ */
+function buildCall(op: IAutoViewEndpoint, props: string | null): string {
+  const fn = `api.functional.${op.accessor.join(".")}`;
+  if (props === null) return `${fn}(connection)`;
+  return `${fn}(connection, (${props}) as unknown as Parameters<typeof ${fn}>[1])`;
+}
+
+/** Dynamic route segment names in path order: `/sales/[id]/questions` → ["id"]. */
+function routeParamNames(routePath: string): string[] {
+  return [...routePath.matchAll(/\[([^\]]+)\]/g)].map((m) => m[1]!);
+}
+
+/**
+ * Map each of an operation's path params to a route segment, aligned to the
+ * TAIL of the route. The route segment name and the SDK param name can differ —
+ * the route is `/sales/[id]/questions` while the SDK function expects `saleId` —
+ * so we map by position rather than by name. Tail-alignment matters when the
+ * screen route carries more `[segment]`s than the op has params: a resource may
+ * be nested under an ancestor it does not parametrize (GitHub's flat
+ * `/projects/columns/{column_id}` rendered under
+ * `/projects/[projectsId]/columns/[columnsId]`). The op's own params are always
+ * the DEEPEST segments, so the leading ancestor segments are the unmapped ones —
+ * never the op's id, which would otherwise be sourced from the wrong segment.
+ */
+function paramSourceMap(
+  op: IAutoViewEndpoint,
+  routePath: string,
+): Map<string, string> {
+  const routeNames = routeParamNames(routePath);
+  const offset = Math.max(0, routeNames.length - op.parameters.length);
+  const map = new Map<string, string>();
+  op.parameters.forEach((p, i) =>
+    map.set(p.name, routeNames[offset + i] ?? p.name),
+  );
+  return map;
+}
+
+/** Path param names typed as `integer`/`number` by the schema (so the page
+ * coerces them with `Number(...)`, not `String(...)` — DigitalOcean and many
+ * real APIs use numeric ids, which `typia.assert` rejects as strings). */
+function numericParams(ops: readonly IAutoViewEndpoint[]): Set<string> {
+  const set = new Set<string>();
+  for (const op of ops) {
+    for (const p of op.parameters) {
+      const type = (p.schema as { type?: unknown }).type;
+      if (type === "integer" || type === "number") set.add(p.name);
+    }
+  }
+  return set;
+}
+
+/** `const <opParam> = <Number|String>(params.<routeSegmentAtSamePosition>)`. */
+function declareParams(
+  names: readonly string[],
+  source: Map<string, string>,
+  numeric: Set<string>,
+): string {
+  return names
+    .map((n) => {
+      const src = `(params as Record<string, unknown>).${source.get(n) ?? n}`;
+      return numeric.has(n)
+        ? `  const ${n} = Number(${src});`
+        : `  const ${n} = String(${src} ?? "");`;
+    })
+    .join("\n");
+}
+
+/** Declarations sourcing every path param of `op` from the route, by position. */
+function paramDeclarations(op: IAutoViewEndpoint, routePath: string): string {
+  if (op.parameters.length === 0) return "";
+  return declareParams(
+    op.parameters.map((p) => p.name),
+    paramSourceMap(op, routePath),
+    numericParams([op]),
+  );
+}
+
+/**
+ * Rewrite a route's `[segment]` brackets into `${var}` interpolations, where
+ * `var` is the page's declared variable that sources that segment. Used to build
+ * hrefs (edit link, row → detail, parent → child) — the route segment is named
+ * by the canonical scheme (`[salesId]`) while the page variable is the SDK param
+ * (`saleId`), so we map back through the same positional source map.
+ */
+function substituteRouteParams(
+  routePath: string,
+  op: IAutoViewEndpoint,
+): string {
+  const inverse = new Map<string, string>();
+  for (const [opParam, src] of paramSourceMap(op, routePath)) {
+    inverse.set(src, opParam);
+  }
+  return routePath.replace(/\[([^\]]+)\]/g, (_, seg: string) => {
+    const mapped = inverse.get(seg);
+    // A mapped segment interpolates the page's declared op-param variable. An
+    // UNMAPPED segment (a hierarchy ancestor the op does not parametrize) has no
+    // such variable — emitting the bare segment name would reference an
+    // undeclared identifier (a tsc error). Read it straight from `useParams()`
+    // instead, so the href always carries a real value. `params` is in scope
+    // wherever a route has `[segment]`s (see `needsParams`).
+    return mapped !== undefined
+      ? "${" + mapped + "}"
+      : "${String((params as Record<string, unknown>)[" + lit(seg) + '] ?? "")}';
+  });
+}
+
+/**
+ * A `router.push` / `Link` target built ENTIRELY from `useParams()` — every
+ * `[segment]` reads its value off the route params. Used for the
+ * navigate-to-ancestor-list redirect after a delete, where the remaining
+ * segments are all ancestors (the entity's own id was stripped) whose values
+ * live in `params`, not in any declared op variable. Returns a string literal
+ * when the path has no dynamic segment, a template literal otherwise.
+ */
+function routeHrefFromParams(routePath: string): string {
+  if (!routePath.includes("[")) return lit(routePath);
+  const body = routePath.replace(
+    /\[([^\]]+)\]/g,
+    (_, seg: string) =>
+      "${String((params as Record<string, unknown>)[" + lit(seg) + '] ?? "")}',
+  );
+  return "`" + body + "`";
+}
+
+/* -------------------------------------------------------------------------- */
+/* table                                                                      */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Top-level response fields from the best available source: the named type, or
+ * the raw inline `responseSchema` when the named type is empty/dead (nestia's
+ * dead `*.GetResponse` ref) or absent entirely (a purely inline response).
+ */
+function responseTopFields(
+  op: IAutoViewEndpoint,
+  doc: OpenApi.IDocument,
+): IFieldSpec[] {
+  const named =
+    op.responseBody !== null ? extractFields(op.responseBody.typeName, doc) : [];
+  if (named.length > 0) return named;
+  return op.responseSchema !== null
+    ? extractFieldsFromSchema(op.responseSchema, doc)
+    : [];
+}
+
+/**
+ * The browsable ROW collection a response carries, or `null` for a single object
+ * / void. Shared by the screen classifier (list vs detail) and the table
+ * renderer so they never disagree. Recognizes a bare array, a generically named
+ * wrapper (`data`/`entries`), a wrapper named after the resource
+ * (`{ droplets: [...] }`, DigitalOcean), and an element that is a `$ref` type OR
+ * an INLINE object (DO's droplet shape is inline).
+ */
+export function responseCollection(
+  op: IAutoViewEndpoint,
+  doc: OpenApi.IDocument,
+): { field: string | null; columns: IFieldSpec[] } | null {
+  if (op.responseBody !== null && op.responseBody.isArray) {
+    const columns = extractFields(op.responseBody.typeName, doc);
+    return columns.length > 0 ? { field: null, columns } : null;
+  }
+  const top = responseTopFields(op, doc);
+  if (top.length === 0) return null;
+  const dataField =
+    findCollectionField(top) ?? top.find((f) => f.kind === "array");
+  if (dataField !== undefined) {
+    const columns =
+      dataField.ref !== undefined
+        ? extractFields(dataField.ref, doc) // named element type
+        : (dataField.itemFields ?? []); // inline element
+    if (columns.length > 0) return { field: dataField.name, columns };
+  }
+  return null; // a single object, not a collection
+}
+
+/**
+ * Resolve a list endpoint's table columns + the JS expression that reads the row
+ * array off the response. accessExpr always guards null/non-array so the
+ * simulator omitting the field cannot crash the table on `rows.length`.
+ */
+function tableResponse(
+  op: IAutoViewEndpoint,
+  doc: OpenApi.IDocument,
+): { columns: IFieldSpec[]; accessExpr: string } {
+  const collection = responseCollection(op, doc);
+  if (collection !== null) {
+    return {
+      columns: collection.columns,
+      accessExpr:
+        collection.field === null
+          ? "(Array.isArray(res) ? res : [])"
+          : `(${memberOf("res", collection.field)} ?? [])`,
+    };
+  }
+  // Single object — show it as a one-row table (or empty when there is nothing).
+  const top = responseTopFields(op, doc);
+  return top.length > 0
+    ? { columns: top, accessExpr: "(res ? [res] : [])" }
+    : { columns: [], accessExpr: "[]" };
+}
+
+/** Page size for the generated pager — also the "is there a next page?" guess. */
+const PAGE_SIZE = 20;
+const PAGE_NAMES = new Set(["page", "offset", "skip", "page_number"]);
+const LIMIT_NAMES = new Set([
+  "limit",
+  "per_page",
+  "page_size",
+  "pagesize",
+  "size",
+  "take",
+]);
+const SEARCH_NAMES = new Set([
+  "search",
+  "q",
+  "keyword",
+  "query",
+  "search_text",
+  "term",
+]);
+
+interface IReqField {
+  name: string;
+  location: "query" | "body";
+}
+interface IListControls {
+  page?: IReqField & { offsetBased: boolean };
+  limit?: IReqField;
+  search?: IReqField;
+}
+
+/**
+ * A schema's effective primitive type, unwrapping the nullable form
+ * `upgradeDocument` produces (`oneOf: [{ type: "null" }, { type: "integer" }]`)
+ * — so a `page?: number | null` param is still seen as a number.
+ */
+function effectiveType(schema: OpenApi.IJsonSchema): unknown {
+  if ("oneOf" in schema && Array.isArray(schema.oneOf)) {
+    const real = schema.oneOf.filter(
+      (b) => (b as { type?: unknown }).type !== "null",
+    );
+    if (real.length === 1) return (real[0] as { type?: unknown }).type;
+  }
+  return (schema as { type?: unknown }).type;
+}
+
+/** Numeric? a param whose effective type is integer/number. */
+function isNumericSchema(schema: OpenApi.IJsonSchema): boolean {
+  const t = effectiveType(schema);
+  return t === "integer" || t === "number";
+}
+
+/** True when a schema is (possibly nullable) plain string — not an object. */
+function isStringSchema(schema: OpenApi.IJsonSchema): boolean {
+  return effectiveType(schema) === "string";
+}
+
+/**
+ * The list-control params an endpoint exposes — a page/offset, a page size, and
+ * a text search — found across its query AND request body. Lets the table wire
+ * real pagination + search to whatever the swagger calls them (`page`/`offset`,
+ * `limit`/`per_page`, `search`/`q`), in either location. Search is only taken
+ * when it is a plain string param (shopping's object-shaped `search` is skipped).
+ */
+function requestControls(
+  op: IAutoViewEndpoint,
+  doc: OpenApi.IDocument,
+): IListControls {
+  const fields: Array<IReqField & { schema: OpenApi.IJsonSchema }> = [];
+  if (op.query !== null) {
+    for (const [name, schema] of Object.entries(
+      resolveProperties(op.query, doc).properties,
+    ))
+      fields.push({ name, location: "query", schema });
+  }
+  if (op.requestBody !== null) {
+    const comp = (doc.components?.schemas ?? {})[op.requestBody.typeName];
+    if (comp !== undefined) {
+      for (const [name, schema] of Object.entries(
+        resolveProperties(comp, doc).properties,
+      ))
+        fields.push({ name, location: "body", schema });
+    }
+  }
+  const controls: IListControls = {};
+  for (const f of fields) {
+    const lower = f.name.toLowerCase();
+    if (
+      controls.page === undefined &&
+      PAGE_NAMES.has(lower) &&
+      isNumericSchema(f.schema)
+    ) {
+      controls.page = {
+        name: f.name,
+        location: f.location,
+        offsetBased: lower === "offset" || lower === "skip",
+      };
+    } else if (
+      controls.limit === undefined &&
+      LIMIT_NAMES.has(lower) &&
+      isNumericSchema(f.schema)
+    ) {
+      controls.limit = { name: f.name, location: f.location };
+    } else if (
+      controls.search === undefined &&
+      SEARCH_NAMES.has(lower) &&
+      isStringSchema(f.schema)
+    ) {
+      controls.search = { name: f.name, location: f.location };
+    }
+  }
+  return controls;
+}
+
+function renderTable(
+  screen: IAutoViewProductPlan.IScreen,
+  endpoints: IAutoViewEndpoint[],
+  doc: OpenApi.IDocument,
+  allScreens: IAutoViewProductPlan.IScreen[],
+): string {
+  const op = primaryOp(screen, endpoints);
+  if (op === null) return renderLanding(screen, allScreens, endpoints, doc);
+
+  const { columns: rawColumns, accessExpr } = tableResponse(op, doc);
+  const columns = orderColumns(rawColumns);
+  const linkIndex = resourceLinkIndex(allScreens, endpoints);
+  const columnsLit = `[\n${columns
+    .map((c) => `  ${lit(toColumnSpec(c, linkIndex))}`)
+    .join(",\n")}\n]`;
+
+  // `|| path has [segment]`: even when this list op takes no path param, an
+  // ancestor segment in the route is read from `useParams()` to build row/child
+  // hrefs (see substituteRouteParams), so `params` must be declared.
+  const needsParams =
+    op.parameters.length > 0 || screen.path.includes("[");
+  const controls = requestControls(op, doc);
+  const hasPage = controls.page !== undefined;
+  const hasSearch = controls.search !== undefined;
+  const hasControls = hasPage || hasSearch;
+
+  // Build the SDK call. With pagination/search, merge the page/search STATE into
+  // the request (query or body — wherever the param lives); otherwise the plain
+  // schema defaults.
+  let call: string;
+  if (hasControls) {
+    const pageValue = controls.page
+      ? controls.page.offsetBased
+        ? "(page - 1) * PAGE_SIZE"
+        : "page"
+      : null;
+    const overridesFor = (loc: "query" | "body"): string[] => {
+      const out: string[] = [];
+      if (controls.page?.location === loc && pageValue !== null)
+        out.push(`${lit(controls.page.name)}: ${pageValue}`);
+      if (controls.limit?.location === loc)
+        out.push(`${lit(controls.limit.name)}: PAGE_SIZE`);
+      if (controls.search?.location === loc)
+        out.push(`${lit(controls.search.name)}: search`);
+      return out;
+    };
+    const parts: string[] = op.parameters.map((p) => `${p.name}: ${p.name}`);
+    if (op.query !== null) {
+      const defaults = queryDefaultsLiteral(op.query, doc);
+      const ov = overridesFor("query");
+      parts.push(
+        `query: ${ov.length > 0 ? `{ ...${defaults}, ${ov.join(", ")} }` : defaults}`,
+      );
+    }
+    if (op.requestBody !== null) {
+      const defaults = bodyDefaultsLiteral(op.requestBody.typeName, doc);
+      const ov = overridesFor("body");
+      parts.push(
+        `body: ${ov.length > 0 ? `{ ...${defaults}, ${ov.join(", ")} }` : defaults}`,
+      );
+    }
+    call = buildCall(op, parts.length > 0 ? `{ ${parts.join(", ")} }` : null);
+  } else {
+    call = buildCall(op, buildProps(op, doc));
+  }
+
+  // A nested sub-collection (e.g. `/sales/{saleId}/reviews`) whose route does
+  // not carry those path params cannot be fetched standalone — firing the call
+  // with empty ids would 400/404 and show a scary error card. Render the schema
+  // (dense column headers — still on-target for "complete tables") with an
+  // honest empty state, and skip the doomed fetch entirely.
+  const unsatisfiable = needsParams && !screen.path.includes("[");
+  if (unsatisfiable) {
+    const parents = op.parameters.map((p) => p.name).join(", ");
+    return renderStaticTable(
+      screen,
+      columnsLit,
+      `This is a nested collection — it needs a parent (${parents}). Open the parent record to view its ${screen.title.toLowerCase()}.`,
+    );
+  }
+
+  // Row → detail link, when a detail screen exists for this resource. The
+  // parent segments of the list route (`/sales/[salesId]/questions`) are
+  // substituted with the page's param vars; the row's own id is appended.
+  const detailScreen = allScreens.find(
+    (s) => s.uiPattern === "detail" && s.path.startsWith(`${screen.path}/[`),
+  );
+  const rowBase = substituteRouteParams(screen.path, op);
+  const rowHref = detailScreen
+    ? `\n      rowHref={(row) => {\n        const id = row.id;\n        return id === undefined || id === null ? null : ${"`"}${rowBase}/${"${String(id)}"}${"`"};\n      }}`
+    : "";
+
+  const paramHook = needsParams
+    ? `  const params = useParams();\n${paramDeclarations(op, screen.path)}\n`
+    : "";
+  const depExtra = [hasPage ? "page" : null, hasSearch ? "search" : null]
+    .filter((s): s is string => s !== null)
+    .join(", ");
+  const baseDeps = needsParams
+    ? `tick, ${op.parameters.map((p) => p.name).join(", ")}`
+    : "tick";
+  const effectDeps = `[${baseDeps}${depExtra ? `, ${depExtra}` : ""}]`;
+
+  // Typing a search resets to page 1 so results start from the top.
+  const searchHandler = hasPage
+    ? "(v) => { setPage(1); setSearch(v); }"
+    : "(v) => setSearch(v)";
+  const searchProp = hasSearch
+    ? `\n      search={{ value: search, onChange: ${searchHandler} }}`
+    : "";
+  const paginationProp = hasPage
+    ? `\n      pagination={{ page, onPrev: () => setPage((p) => Math.max(1, p - 1)), onNext: () => setPage((p) => p + 1), hasNext }}`
+    : "";
+
+  return [
+    `"use client";`,
+    ``,
+    `import * as React from "react";`,
+    needsParams ? `import { useParams } from "next/navigation";` : null,
+    ``,
+    `import api from "@/src/lib/api";`,
+    `import { connection } from "@/src/lib/connection";`,
+    `import { ResourceTable } from "@/components/auto/ResourceTable";`,
+    `import type { ColumnSpec } from "@/components/auto/types";`,
+    ``,
+    `const COLUMNS: ColumnSpec[] = ${columnsLit};`,
+    hasControls ? `const PAGE_SIZE = ${PAGE_SIZE};` : null,
+    ``,
+    `export default function Page() {`,
+    paramHook ? paramHook : null,
+    `  const [rows, setRows] = React.useState<readonly unknown[]>([]);`,
+    `  const [loading, setLoading] = React.useState(true);`,
+    `  const [error, setError] = React.useState<string | null>(null);`,
+    `  const [tick, setTick] = React.useState(0);`,
+    hasPage ? `  const [page, setPage] = React.useState(1);` : null,
+    hasPage ? `  const [hasNext, setHasNext] = React.useState(false);` : null,
+    hasSearch ? `  const [search, setSearch] = React.useState("");` : null,
+    ``,
+    `  React.useEffect(() => {`,
+    `    let alive = true;`,
+    `    setLoading(true);`,
+    `    setError(null);`,
+    `    ${call}`,
+    `      .then((res) => {`,
+    `        if (!alive) return;`,
+    `        const data = ${accessExpr} as readonly unknown[];`,
+    `        setRows(data);`,
+    hasPage ? `        setHasNext(data.length >= PAGE_SIZE);` : null,
+    `      })`,
+    `      .catch((e) => {`,
+    `        if (alive) setError(e instanceof Error ? e.message : String(e));`,
+    `      })`,
+    `      .finally(() => {`,
+    `        if (alive) setLoading(false);`,
+    `      });`,
+    `    return () => {`,
+    `      alive = false;`,
+    `    };`,
+    `  }, ${effectDeps});`,
+    ``,
+    `  return (`,
+    `    <ResourceTable`,
+    `      title=${lit(screen.title)}`,
+    `      description=${lit(screen.purpose)}`,
+    `      columns={COLUMNS}`,
+    `      rows={rows}`,
+    `      loading={loading}`,
+    `      error={error}`,
+    `      onRetry={() => setTick((t) => t + 1)}${rowHref}${searchProp}${paginationProp}`,
+    `    />`,
+    `  );`,
+    `}`,
+    ``,
+  ]
+    .filter((line): line is string => line !== null)
+    .join("\n");
+}
+
+/**
+ * A table that shows its schema (column headers) but fetches nothing — used for
+ * nested sub-collections that cannot be loaded without a parent selection. Keeps
+ * the endpoint visible as a real screen with dense headers and an honest empty
+ * state, instead of a broken error card from a doomed fetch.
+ */
+function renderStaticTable(
+  screen: IAutoViewProductPlan.IScreen,
+  columnsLit: string,
+  hint: string,
+): string {
+  return [
+    `"use client";`,
+    ``,
+    `import * as React from "react";`,
+    ``,
+    `import { ResourceTable } from "@/components/auto/ResourceTable";`,
+    `import type { ColumnSpec } from "@/components/auto/types";`,
+    ``,
+    `const COLUMNS: ColumnSpec[] = ${columnsLit};`,
+    ``,
+    `export default function Page() {`,
+    `  return (`,
+    `    <ResourceTable`,
+    `      title=${lit(screen.title)}`,
+    `      description=${lit(screen.purpose)}`,
+    `      columns={COLUMNS}`,
+    `      rows={[]}`,
+    `      loading={false}`,
+    `      error={null}`,
+    `      emptyHint=${lit(hint)}`,
+    `    />`,
+    `  );`,
+    `}`,
+    ``,
+  ].join("\n");
+}
+
+/* -------------------------------------------------------------------------- */
+/* catalog                                                                    */
+/* -------------------------------------------------------------------------- */
+
+/** Secondary columns shown under a catalog card's title. */
+const CATALOG_META_LIMIT = 4;
+
+/**
+ * Catalog (card grid) page — same fetch scaffold as the table, but renders
+ * `CatalogGrid` with an image + title + a few meta fields baked from the schema.
+ * Reached only for collections the plan flagged as image+title bearing; falls
+ * back to a table if the signals are somehow absent or the list needs a parent.
+ */
+function renderCatalog(
+  screen: IAutoViewProductPlan.IScreen,
+  endpoints: IAutoViewEndpoint[],
+  doc: OpenApi.IDocument,
+  allScreens: IAutoViewProductPlan.IScreen[],
+): string {
+  const op = primaryOp(screen, endpoints);
+  if (op === null) return renderTable(screen, endpoints, doc, allScreens);
+
+  const { columns: rawColumns, accessExpr } = tableResponse(op, doc);
+  const columns = orderColumns(rawColumns);
+  const image = imageFieldOf(columns);
+  const title = titleFieldOf(columns);
+  // `|| path has [segment]`: even when this list op takes no path param, an
+  // ancestor segment in the route is read from `useParams()` to build row/child
+  // hrefs (see substituteRouteParams), so `params` must be declared.
+  const needsParams =
+    op.parameters.length > 0 || screen.path.includes("[");
+  // Missing signal or a nested list that needs a parent → the table renderer
+  // handles both (dense columns + honest empty state) better than a broken grid.
+  if (
+    image === undefined ||
+    title === undefined ||
+    (needsParams && !screen.path.includes("["))
+  ) {
+    return renderTable(screen, endpoints, doc, allScreens);
+  }
+
+  const meta = columns
+    .filter((c) => c.name !== image.name && c.name !== title.name)
+    .slice(0, CATALOG_META_LIMIT);
+  const specLit = lit({
+    imageField: image.name,
+    imageIsArray: image.kind === "array",
+    titleField: title.name,
+    meta: meta.map((c) => toColumnSpec(c)),
+  });
+
+  const call = buildCall(op, buildProps(op, doc));
+
+  const detailScreen = allScreens.find(
+    (s) => s.uiPattern === "detail" && s.path.startsWith(`${screen.path}/[`),
+  );
+  const rowBase = substituteRouteParams(screen.path, op);
+  const rowHref = detailScreen
+    ? `\n      rowHref={(row) => {\n        const id = row.id;\n        return id === undefined || id === null ? null : ${"`"}${rowBase}/${"${String(id)}"}${"`"};\n      }}`
+    : "";
+
+  const paramHook = needsParams
+    ? `  const params = useParams();\n${paramDeclarations(op, screen.path)}\n`
+    : "";
+  const effectDeps = needsParams
+    ? `[tick, ${op.parameters.map((p) => p.name).join(", ")}]`
+    : "[tick]";
+
+  return [
+    `"use client";`,
+    ``,
+    `import * as React from "react";`,
+    needsParams ? `import { useParams } from "next/navigation";` : null,
+    ``,
+    `import api from "@/src/lib/api";`,
+    `import { connection } from "@/src/lib/connection";`,
+    `import { CatalogGrid } from "@/components/auto/CatalogGrid";`,
+    `import type { CatalogSpec } from "@/components/auto/CatalogGrid";`,
+    ``,
+    `const SPEC: CatalogSpec = ${specLit};`,
+    ``,
+    `export default function Page() {`,
+    paramHook ? paramHook : null,
+    `  const [rows, setRows] = React.useState<readonly unknown[]>([]);`,
+    `  const [loading, setLoading] = React.useState(true);`,
+    `  const [error, setError] = React.useState<string | null>(null);`,
+    `  const [tick, setTick] = React.useState(0);`,
+    ``,
+    `  React.useEffect(() => {`,
+    `    let alive = true;`,
+    `    setLoading(true);`,
+    `    setError(null);`,
+    `    ${call}`,
+    `      .then((res) => {`,
+    `        if (!alive) return;`,
+    `        setRows(${accessExpr} as readonly unknown[]);`,
+    `      })`,
+    `      .catch((e) => {`,
+    `        if (alive) setError(e instanceof Error ? e.message : String(e));`,
+    `      })`,
+    `      .finally(() => {`,
+    `        if (alive) setLoading(false);`,
+    `      });`,
+    `    return () => {`,
+    `      alive = false;`,
+    `    };`,
+    `  }, ${effectDeps});`,
+    ``,
+    `  return (`,
+    `    <CatalogGrid`,
+    `      title=${lit(screen.title)}`,
+    `      description=${lit(screen.purpose)}`,
+    `      spec={SPEC}`,
+    `      rows={rows}`,
+    `      loading={loading}`,
+    `      error={error}`,
+    `      onRetry={() => setTick((t) => t + 1)}${rowHref}`,
+    `    />`,
+    `  );`,
+    `}`,
+    ``,
+  ]
+    .filter((line): line is string => line !== null)
+    .join("\n");
+}
+
+/* -------------------------------------------------------------------------- */
+/* detail                                                                     */
+/* -------------------------------------------------------------------------- */
+
+function renderDetail(
+  screen: IAutoViewProductPlan.IScreen,
+  endpoints: IAutoViewEndpoint[],
+  doc: OpenApi.IDocument,
+  allScreens: IAutoViewProductPlan.IScreen[],
+): string {
+  const op = primaryOp(screen, endpoints);
+  if (op === null) return renderLanding(screen, allScreens, endpoints, doc);
+
+  const typeName = op.responseBody?.typeName ?? null;
+  const fields = typeName ? extractFields(typeName, doc) : [];
+  const linkIndex = resourceLinkIndex(allScreens, endpoints);
+  const fieldsLit = `[\n${fields
+    .map((f) => `  ${lit(toColumnSpec(f, linkIndex))}`)
+    .join(",\n")}\n]`;
+
+  const props = buildProps(op, doc);
+  const call = buildCall(op, props);
+
+  // Edit-link action, when an edit screen exists for this entity.
+  const editScreen = allScreens.find(
+    (s) => s.uiPattern === "form" && s.path === `${screen.path}/edit`,
+  );
+  // The detail route is dynamic (`/orders/[ordersId]`). The edit link must
+  // substitute the id VALUE into the bracket segment, not leave a literal
+  // `[ordersId]` — Next.js rejects a `<Link href>` that still contains a bracket
+  // at runtime ("Dynamic href found in <Link>"), a defect tsc + next build
+  // cannot see.
+  const editHref = `${substituteRouteParams(screen.path, op)}/edit`;
+
+  // Secondary endpoints the detail composes (its update / delete / action
+  // operations) become real buttons: DELETE → a destructive button, POST → an
+  // action button labeled by the verb. PUT/PATCH updates are covered by the
+  // Edit link, so they are not duplicated here. This is what makes the detail
+  // page functional — you can act on the record, not just look at it.
+  const secondaryOps = screen.endpoints
+    .slice(1)
+    .map((a) => endpoints.find((e) => e.accessor.join(".") === a))
+    .filter((o): o is IAutoViewEndpoint => o !== undefined);
+  const actionOps = secondaryOps.filter((o) => {
+    const m = o.method.toUpperCase();
+    return m === "DELETE" || m === "POST";
+  });
+  const hasActions = actionOps.length > 0;
+
+  // Direct child collections (`/sales/[id]/questions`) — embedded inline below
+  // the record as preview tables, turning a flat detail into a master-detail
+  // view. Their list endpoints reuse this page's id params (a child collection
+  // adds no new bracket of its own).
+  const childCollectionScreens = allScreens.filter((s) => {
+    if (s.uiPattern !== "table" && s.uiPattern !== "catalog") return false;
+    if (!s.path.startsWith(`${screen.path}/`)) return false;
+    const rest = s.path.slice(screen.path.length + 1);
+    return rest.length > 0 && !rest.includes("/"); // direct child collection only
+  });
+  const childOps = childCollectionScreens
+    .map((c) => primaryOp(c, endpoints))
+    .filter((o): o is IAutoViewEndpoint => o !== null);
+
+  // Declare every path param any operation on this page needs (primary detail,
+  // each action, each embedded child list), sourced from useParams — the route
+  // may name a segment `[id]` while the SDK calls it `saleId`. The primary op's
+  // order matches the route; actions and child lists share its leading params.
+  const paramNames = Array.from(
+    new Set(
+      [op, ...actionOps, ...childOps].flatMap((o) =>
+        o.parameters.map((p) => p.name),
+      ),
+    ),
+  );
+  const needsParams = paramNames.length > 0;
+  // Source every param from the route segment at ITS OWN op's position, unioned
+  // across all ops. Different ops name the same id differently — the detail's
+  // `sales.at` calls it `id`, the child `sales.snapshots.index` calls it
+  // `saleId`, an action `categories.create` calls it `channelCode` — but they
+  // all address the same leading route segment (`[salesId]` / `[channelsId]`).
+  // Mapping each op's params positionally and merging declares every alias from
+  // the right segment, instead of leaving a child/action id sourced from a
+  // route param name that does not exist (→ empty string → failed fetch).
+  const allParamOps = [op, ...actionOps, ...childOps];
+  const mergedParamSource = new Map<string, string>();
+  for (const o of allParamOps) {
+    for (const [param, src] of paramSourceMap(o, screen.path)) {
+      if (!mergedParamSource.has(param)) mergedParamSource.set(param, src);
+    }
+  }
+  const paramDecls = declareParams(
+    paramNames,
+    mergedParamSource,
+    numericParams(allParamOps),
+  );
+
+  // Dedupe by visible label — actor-scoped duplicates (admin + seller `erase`)
+  // collapse to one route here, so both would render an identical "Delete"
+  // button. Keep the first; track labels so child links don't repeat them.
+  // List route this record belongs to (`/sales/[salesId]` → `/sales`) — where a
+  // successful delete navigates, since the record no longer exists.
+  const listPath = screen.path.replace(/\/\[[^\]]+\]$/, "") || "/";
+
+  const usedLabels = new Set<string>();
+  const actionButtons: string[] = [];
+  let hasDelete = false;
+  for (const o of actionOps) {
+    const isDelete = o.method.toUpperCase() === "DELETE";
+    // Label from the last STATIC path segment (`/orders/{id}/cancel` → "Cancel"),
+    // not the accessor's auto-generated tail (`postById`) which reads as noise.
+    const verb =
+      o.path
+        .split("/")
+        .filter((s) => s.length > 0 && !s.startsWith("{"))
+        .pop() ?? "Action";
+    const label = isDelete ? "Delete" : titleizeSegment(verb);
+    if (usedLabels.has(label)) continue;
+    usedLabels.add(label);
+    const acall = buildCall(o, buildProps(o, doc));
+    if (isDelete) {
+      // Confirmed delete → on success navigate to the list (record is gone).
+      hasDelete = true;
+      actionButtons.push(
+        `          <ConfirmButton label=${lit(label)} disabled={busy} onConfirm={() => del(() => ${acall})} />`,
+      );
+    } else {
+      // A mutating action re-fetches the record so the change is visible.
+      actionButtons.push(
+        `          <Button variant="outline" size="sm" disabled={busy} onClick={() => act(() => ${acall})}>${label}</Button>`,
+      );
+    }
+  }
+
+  // Inline child-collection embeds. Each direct child list is rendered as a
+  // compact preview table below the record (master-detail), not a button that
+  // jumps away. Skip a child whose label already appears as an action button (a
+  // POST `/sales/{id}/questions` action + the `/sales/[id]/questions` list both
+  // read "Questions"). The child list reuses this page's id params, substituted
+  // by name through `buildProps`.
+  const childEmbeds = childCollectionScreens
+    .map((c) => {
+      const cop = primaryOp(c, endpoints);
+      if (cop === null) return null;
+      const label = titleizeSegment(c.path.slice(screen.path.length + 1));
+      if (usedLabels.has(label)) return null;
+      usedLabels.add(label);
+      const { columns, accessExpr } = tableResponse(cop, doc);
+      const columnsLit = `[\n${orderColumns(columns)
+        .map((f) => `          ${lit(toColumnSpec(f, linkIndex))}`)
+        .join(",\n")}\n        ]`;
+      return {
+        title: label,
+        href: substituteRouteParams(c.path, op),
+        columnsLit,
+        call: buildCall(cop, buildProps(cop, doc)),
+        accessExpr,
+      };
+    })
+    .filter((x): x is NonNullable<typeof x> => x !== null);
+  const hasEmbeds = childEmbeds.length > 0;
+
+  const embedsJsx = childEmbeds
+    .map((e) =>
+      [
+        `        <EmbeddedCollection`,
+        `          title=${lit(e.title)}`,
+        `          href={${"`"}${e.href}${"`"}}`,
+        `          columns={${e.columnsLit}}`,
+        `          load={() =>`,
+        `            ${e.call}`,
+        `              .then((res) => (${e.accessExpr}) as readonly unknown[])`,
+        `          }`,
+        `        />`,
+      ].join("\n"),
+    )
+    .join("\n");
+
+  const actionInner = [
+    editScreen
+      ? `          <Button asChild variant="outline" size="sm">\n            <Link href={${"`"}${editHref}${"`"}}>Edit</Link>\n          </Button>`
+      : null,
+    ...actionButtons,
+    hasActions
+      ? `          {actionMsg ? <span className="self-center text-xs text-muted-foreground">{actionMsg}</span> : null}`
+      : null,
+  ]
+    .filter((l): l is string => l !== null)
+    .join("\n");
+  const needButton = editScreen !== undefined || hasActions;
+  const needLink = editScreen !== undefined;
+  const actions = needButton
+    ? `\n      actions={\n        <>\n${actionInner}\n        </>\n      }`
+    : "";
+
+  const effectDeps = needsParams ? `[tick, ${paramNames.join(", ")}]` : "[tick]";
+
+  const navNames = [
+    needsParams ? "useParams" : null,
+    hasDelete ? "useRouter" : null,
+  ].filter((s): s is string => s !== null);
+  const navImport =
+    navNames.length > 0
+      ? `import { ${navNames.join(", ")} } from "next/navigation";`
+      : null;
+
+  return [
+    `"use client";`,
+    ``,
+    `import * as React from "react";`,
+    navImport,
+    needLink ? `import Link from "next/link";` : null,
+    ``,
+    `import api from "@/src/lib/api";`,
+    `import { connection } from "@/src/lib/connection";`,
+    `import { ResourceDetail } from "@/components/auto/ResourceDetail";`,
+    hasEmbeds
+      ? `import { EmbeddedCollection } from "@/components/auto/EmbeddedCollection";`
+      : null,
+    needButton ? `import { Button } from "@/components/ui/button";` : null,
+    hasDelete
+      ? `import { ConfirmButton } from "@/components/auto/ConfirmButton";`
+      : null,
+    `import type { ColumnSpec } from "@/components/auto/types";`,
+    ``,
+    `const FIELDS: ColumnSpec[] = ${fieldsLit};`,
+    ``,
+    `export default function Page() {`,
+    needsParams ? `  const params = useParams();` : null,
+    hasDelete ? `  const router = useRouter();` : null,
+    needsParams ? paramDecls : null,
+    `  const [data, setData] = React.useState<unknown>(null);`,
+    `  const [loading, setLoading] = React.useState(true);`,
+    `  const [error, setError] = React.useState<string | null>(null);`,
+    `  const [tick, setTick] = React.useState(0);`,
+    hasActions ? `  const [busy, setBusy] = React.useState(false);` : null,
+    hasActions
+      ? `  const [actionMsg, setActionMsg] = React.useState<string | null>(null);`
+      : null,
+    hasActions ? `  const act = (fn: () => Promise<unknown>) => {` : null,
+    hasActions ? `    setBusy(true);` : null,
+    hasActions ? `    setActionMsg(null);` : null,
+    hasActions ? `    fn()` : null,
+    hasActions
+      ? `      .then(() => { setActionMsg("Done."); setTick((t) => t + 1); })`
+      : null,
+    hasActions
+      ? `      .catch((e) => setActionMsg(e instanceof Error ? e.message : String(e)))`
+      : null,
+    hasActions ? `      .finally(() => setBusy(false));` : null,
+    hasActions ? `  };` : null,
+    hasDelete ? `  const del = (fn: () => Promise<unknown>) => {` : null,
+    hasDelete ? `    setBusy(true);` : null,
+    hasDelete ? `    setActionMsg(null);` : null,
+    hasDelete ? `    fn()` : null,
+    hasDelete ? `      .then(() => router.push(${routeHrefFromParams(listPath)}))` : null,
+    hasDelete
+      ? `      .catch((e) => { setActionMsg(e instanceof Error ? e.message : String(e)); setBusy(false); });`
+      : null,
+    hasDelete ? `  };` : null,
+    ``,
+    `  React.useEffect(() => {`,
+    `    let alive = true;`,
+    `    setLoading(true);`,
+    `    setError(null);`,
+    `    ${call}`,
+    `      .then((res) => {`,
+    `        if (alive) setData(res);`,
+    `      })`,
+    `      .catch((e) => {`,
+    `        if (alive) setError(e instanceof Error ? e.message : String(e));`,
+    `      })`,
+    `      .finally(() => {`,
+    `        if (alive) setLoading(false);`,
+    `      });`,
+    `    return () => {`,
+    `      alive = false;`,
+    `    };`,
+    `  }, ${effectDeps});`,
+    ``,
+    `  return (`,
+    hasEmbeds ? `    <>` : null,
+    `    <ResourceDetail`,
+    `      title=${lit(screen.title)}`,
+    `      fields={FIELDS}`,
+    `      data={data}`,
+    `      loading={loading}`,
+    `      error={error}`,
+    `      onRetry={() => setTick((t) => t + 1)}${actions}`,
+    `    />`,
+    hasEmbeds ? `      <div className="px-5 pb-8 md:px-8">` : null,
+    hasEmbeds ? `        <div className="max-w-3xl space-y-5">` : null,
+    hasEmbeds ? embedsJsx : null,
+    hasEmbeds ? `        </div>` : null,
+    hasEmbeds ? `      </div>` : null,
+    hasEmbeds ? `    </>` : null,
+    `  );`,
+    `}`,
+    ``,
+  ]
+    .filter((line): line is string => line !== null)
+    .join("\n");
+}
+
+/* -------------------------------------------------------------------------- */
+/* form (create / edit)                                                       */
+/* -------------------------------------------------------------------------- */
+
+function renderForm(
+  screen: IAutoViewProductPlan.IScreen,
+  endpoints: IAutoViewEndpoint[],
+  doc: OpenApi.IDocument,
+): string {
+  const op = primaryOp(screen, endpoints);
+  if (op === null || op.requestBody === null) {
+    // No request body to drive a form — degrade to a detail-less notice.
+    return renderEmptyForm(screen);
+  }
+
+  const inputs = extractFields(op.requestBody.typeName, doc);
+  const fieldsLit = `[\n${inputs
+    .map((f) => `  ${lit(toFieldInput(f))}`)
+    .join(",\n")}\n]`;
+
+  const props = buildProps(op, doc, { bodyExpr: "values" });
+  const call = buildCall(op, props);
+
+  // Edit forms prefill from the current record: find the detail GET among the
+  // screen's secondary endpoints and fetch it on mount.
+  const isEdit = screen.path.endsWith("/edit");
+  const detailOp = isEdit
+    ? (screen.endpoints
+        .slice(1)
+        .map((a) => endpoints.find((e) => e.accessor.join(".") === a))
+        .find(
+          (e): e is IAutoViewEndpoint =>
+            e !== undefined &&
+            e.method.toLowerCase() === "get" &&
+            e.parameters.length > 0,
+        ) ?? null)
+    : null;
+
+  // Params for both the update op and the prefill detail op, sourced by name
+  // from the shared route segments (same merge as the detail page).
+  const paramOps = detailOp !== null ? [op, detailOp] : [op];
+  const paramNames = Array.from(
+    new Set(paramOps.flatMap((o) => o.parameters.map((p) => p.name))),
+  );
+  const needsParams = paramNames.length > 0;
+  const mergedSource = new Map<string, string>();
+  for (const o of paramOps)
+    for (const [pn, src] of paramSourceMap(o, screen.path))
+      if (!mergedSource.has(pn)) mergedSource.set(pn, src);
+  const paramDecls = declareParams(
+    paramNames,
+    mergedSource,
+    numericParams(paramOps),
+  );
+  const paramHook = needsParams
+    ? `  const params = useParams();\n${paramDecls}\n`
+    : "";
+
+  const detailCall =
+    detailOp !== null ? buildCall(detailOp, buildProps(detailOp, doc)) : null;
+
+  return [
+    `"use client";`,
+    ``,
+    `import * as React from "react";`,
+    needsParams ? `import { useParams } from "next/navigation";` : null,
+    ``,
+    `import api from "@/src/lib/api";`,
+    `import { connection } from "@/src/lib/connection";`,
+    `import { ResourceForm } from "@/components/auto/ResourceForm";`,
+    `import type { FieldInput } from "@/components/auto/types";`,
+    ``,
+    `const FIELDS: FieldInput[] = ${fieldsLit};`,
+    ``,
+    `export default function Page() {`,
+    paramHook ? paramHook : null,
+    `  const [submitting, setSubmitting] = React.useState(false);`,
+    `  const [error, setError] = React.useState<string | null>(null);`,
+    `  const [result, setResult] = React.useState<string | null>(null);`,
+    detailCall !== null
+      ? `  const [initial, setInitial] = React.useState<Record<string, unknown> | undefined>(undefined);`
+      : null,
+    detailCall !== null ? `` : null,
+    detailCall !== null ? `  React.useEffect(() => {` : null,
+    detailCall !== null ? `    let alive = true;` : null,
+    detailCall !== null ? `    ${detailCall}` : null,
+    detailCall !== null
+      ? // cast through `unknown`: the prefill source may type as `void` (a 204
+        // detail, e.g. GitHub's collaborator check) which does not overlap Record.
+        `      .then((res) => { if (alive) setInitial(res as unknown as Record<string, unknown>); })`
+      : null,
+    detailCall !== null ? `      .catch(() => undefined);` : null,
+    detailCall !== null ? `    return () => { alive = false; };` : null,
+    detailCall !== null
+      ? `  }, [${paramNames.join(", ")}]);`
+      : null,
+    ``,
+    `  const onSubmit = (values: Record<string, unknown>) => {`,
+    `    setSubmitting(true);`,
+    `    setError(null);`,
+    `    setResult(null);`,
+    `    ${call}`,
+    `      .then(() => {`,
+    `        setResult("Saved successfully.");`,
+    `      })`,
+    `      .catch((e) => {`,
+    `        setError(e instanceof Error ? e.message : String(e));`,
+    `      })`,
+    `      .finally(() => {`,
+    `        setSubmitting(false);`,
+    `      });`,
+    `  };`,
+    ``,
+    `  return (`,
+    `    <ResourceForm`,
+    `      title=${lit(screen.title)}`,
+    `      description=${lit(screen.purpose)}`,
+    `      fields={FIELDS}`,
+    `      submitting={submitting}`,
+    `      error={error}`,
+    `      result={result}`,
+    detailCall !== null ? `      initialValues={initial}` : null,
+    `      onSubmit={onSubmit}`,
+    `    />`,
+    `  );`,
+    `}`,
+    ``,
+  ]
+    .filter((line): line is string => line !== null)
+    .join("\n");
+}
+
+function renderEmptyForm(screen: IAutoViewProductPlan.IScreen): string {
+  return [
+    `"use client";`,
+    ``,
+    `import { ResourceForm } from "@/components/auto/ResourceForm";`,
+    ``,
+    `export default function Page() {`,
+    `  return (`,
+    `    <ResourceForm`,
+    `      title=${lit(screen.title)}`,
+    `      fields={[]}`,
+    `      submitting={false}`,
+    `      onSubmit={() => undefined}`,
+    `    />`,
+    `  );`,
+    `}`,
+    ``,
+  ].join("\n");
+}
+
+/* -------------------------------------------------------------------------- */
+/* landing                                                                    */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Resource hub-ness — how many DISTINCT child resources nest under a resource,
+ * i.e. how many other resources hang off its id (`/files/{file_id}/metadata`,
+ * `/files/{file_id}/versions`, … → `files` parents `metadata`, `versions`, …).
+ * A resource that parents several others is a genuine domain hub; one only ever
+ * read on its own (`/x/{id}`) parents nothing and scores 0. Deterministic from
+ * the path shape — the producer→consumer graph the IR already carries — used to
+ * float the few real hubs (`files`/`folders`/`users`) above the long tail on the
+ * landing page, instead of every path-param hit (which almost every resource has
+ * from its own detail route and so does not discriminate).
+ */
+function resourceHubness(
+  endpoints: IAutoViewEndpoint[],
+): Map<string, number> {
+  const children = new Map<string, Set<string>>();
+  for (const e of endpoints) {
+    const segs = e.path.split("/").filter((s) => s.length > 0);
+    for (let i = 1; i < segs.length; i++) {
+      if (!segs[i]!.startsWith("{")) continue;
+      const parent = segs[i - 1]!;
+      const child = segs[i + 1];
+      if (child === undefined || child.startsWith("{")) continue;
+      const set = children.get(parent) ?? new Set<string>();
+      set.add(child);
+      children.set(parent, set);
+    }
+  }
+  const score = new Map<string, number>();
+  for (const [res, set] of children) score.set(res, set.size);
+  return score;
+}
+
+/** How many hub resources get a live count card on the home dashboard. Past
+ *  this the cards become noise; the long tail stays in the link grid below. */
+const DASHBOARD_STAT_LIMIT = 8;
+
+function renderLanding(
+  screen: IAutoViewProductPlan.IScreen,
+  allScreens: IAutoViewProductPlan.IScreen[],
+  endpoints: IAutoViewEndpoint[],
+  doc: OpenApi.IDocument,
+): string {
+  const hubness = resourceHubness(endpoints);
+  const resourceOf = (path: string): string =>
+    path.replace(/^\//, "").split("/")[0] ?? "";
+  const weightOf = (path: string): number => hubness.get(resourceOf(path)) ?? 0;
+
+  // Links: every top-level browsable screen (chain depth 1, bracket-less). A
+  // nested resource or param-less sub-view is reached from its parent, never
+  // the home hub.
+  const isTopLevel = (s: IAutoViewProductPlan.IScreen): boolean =>
+    (s.depth === undefined || s.depth === 1) && !s.path.includes("[");
+  const links = allScreens
+    .filter(
+      (s) =>
+        isTopLevel(s) &&
+        (s.uiPattern === "table" ||
+          s.uiPattern === "catalog" ||
+          s.uiPattern === "detail"),
+    )
+    .map((s) => ({
+      href: s.path,
+      title: s.title,
+      weight: weightOf(s.path),
+    }));
+  const linksLit = `[\n${links.map((l) => `  ${lit(l)}`).join(",\n")}\n]`;
+
+  // Stats: the top hub resources whose list is fetchable standalone (no path
+  // params), surfaced as live count cards. The count prefers a known total
+  // field (pagination) and falls back to the fetched array length — both
+  // deterministic from the response shape already resolved by `tableResponse`.
+  const statScreens = allScreens
+    .filter((s) => isTopLevel(s) && s.uiPattern === "table")
+    .map((s) => ({ screen: s, op: primaryOp(s, endpoints) }))
+    .filter(
+      (x): x is { screen: IAutoViewProductPlan.IScreen; op: IAutoViewEndpoint } =>
+        x.op !== null && x.op.parameters.length === 0,
+    )
+    .sort((a, b) => weightOf(b.screen.path) - weightOf(a.screen.path))
+    .slice(0, DASHBOARD_STAT_LIMIT);
+
+  const statTitlesLit = `[\n${statScreens
+    .map((x) => `  ${lit({ href: x.screen.path, title: x.screen.title })}`)
+    .join(",\n")}\n]`;
+
+  const fetchers = statScreens.map((x) => {
+    const call = buildCall(x.op, buildProps(x.op, doc));
+    const { accessExpr } = tableResponse(x.op, doc);
+    const collection = responseCollection(x.op, doc);
+    const titleField =
+      collection !== null ? titleFieldOf(collection.columns)?.name : undefined;
+    const href = lit(x.screen.path);
+    // First couple of record titles as a "recent" preview, when the row type
+    // has a title-ish field; otherwise an empty preview.
+    const recentExpr =
+      titleField !== undefined
+        ? `rows.slice(0, 2).map((row) => { const v = (row as Record<string, unknown>)?.[${lit(titleField)}]; return typeof v === "string" || typeof v === "number" ? String(v) : null; }).filter((s): s is string => s !== null)`
+        : "[] as string[]";
+    return [
+      `      ${call}`,
+      `        .then((res) => {`,
+      `          const r = res as unknown as { pagination?: { records?: number; total?: number }; total?: number; count?: number };`,
+      `          const t = r?.pagination?.records ?? r?.pagination?.total ?? r?.total ?? r?.count;`,
+      `          const rows = (${accessExpr} as readonly unknown[]);`,
+      `          const n = typeof t === "number" ? t : rows.length;`,
+      `          const recent = ${recentExpr};`,
+      `          return [${href}, { count: n, recent }] as const;`,
+      `        })`,
+      `        .catch(() => [${href}, { count: null, recent: [] as string[] }] as const)`,
+    ].join("\n");
+  });
+
+  const hasStats = fetchers.length > 0;
+  const fetchBlock = hasStats
+    ? [
+        `  const [counts, setCounts] = React.useState<Record<string, { count: number | null; recent: string[] }>>({});`,
+        ``,
+        `  React.useEffect(() => {`,
+        `    let alive = true;`,
+        `    Promise.all([`,
+        fetchers.join(",\n"),
+        `    ]).then((entries) => {`,
+        `      if (!alive) return;`,
+        `      setCounts(Object.fromEntries(entries));`,
+        `    });`,
+        `    return () => {`,
+        `      alive = false;`,
+        `    };`,
+        `  }, []);`,
+        ``,
+        `  const stats: DashboardStat[] = STAT_TITLES.map((s) => ({`,
+        `    href: s.href,`,
+        `    title: s.title,`,
+        `    count: counts[s.href]?.count ?? null,`,
+        `    recent: counts[s.href]?.recent ?? [],`,
+        `  }));`,
+      ].join("\n")
+    : `  const stats: DashboardStat[] = [];`;
+
+  return [
+    `"use client";`,
+    ``,
+    `import * as React from "react";`,
+    ``,
+    hasStats ? `import api from "@/src/lib/api";` : null,
+    hasStats ? `import { connection } from "@/src/lib/connection";` : null,
+    `import { ResourceDashboard } from "@/components/auto/ResourceDashboard";`,
+    `import type { DashboardStat } from "@/components/auto/ResourceDashboard";`,
+    `import type { LandingLink } from "@/components/auto/ResourceLanding";`,
+    ``,
+    `const LINKS: LandingLink[] = ${linksLit};`,
+    hasStats
+      ? `\nconst STAT_TITLES: { href: string; title: string }[] = ${statTitlesLit};`
+      : null,
+    ``,
+    `export default function Page() {`,
+    fetchBlock,
+    ``,
+    `  return (`,
+    `    <ResourceDashboard`,
+    `      title=${lit(screen.title)}`,
+    `      subtitle=${lit(screen.purpose)}`,
+    `      stats={stats}`,
+    `      links={LINKS}`,
+    `    />`,
+    `  );`,
+    `}`,
+    ``,
+  ]
+    .filter((l): l is string => l !== null)
+    .join("\n");
+}