@specverse/engines 4.2.0 → 4.2.2

package/dist/libs/instance-factories/applications/templates/react-starter/detail-body-composer.js

@@ -1,8 +1,10 @@
 import { METADATA_FIELDS } from "@specverse/runtime/views/core";
+import { extractBelongsToTargets } from "./belongs-to.js";
 const METADATA_FIELD_NAMES = new Set(METADATA_FIELDS);
 function composeDetailBody(context) {
-  const { business, metadata } = partitionFields(context.model);
-  const belongsTo = extractBelongsTo(context.model);
+  const belongsTo = extractBelongsToTargets(context.model);
+  const fkExcludes = new Set(belongsTo.map((r) => `${r.name}Id`));
+  const { business, metadata } = partitionFields(context.model, fkExcludes);
   const lines = [];
   lines.push('<div className="rounded-lg border border-gray-200 bg-white p-6 dark:border-gray-700 dark:bg-gray-900">');
   if (business.length > 0) {
@@ -11,17 +13,14 @@ function composeDetailBody(context) {
       lines.push(...renderField(field, { muted: false }));
     }
     lines.push("  </dl>");
-  } else {
+  } else if (belongsTo.length === 0) {
     lines.push('  <p className="text-sm text-gray-400">No business fields defined for this model.</p>');
   }
   if (belongsTo.length > 0) {
     lines.push("");
-    lines.push("  {/* TODO: resolve FK ids \u2192 related entity display names.");
-    lines.push("      See @specverse/runtime/views/core/entity-display for the");
-    lines.push("      canonical resolver, or load the related record in a hook. */}");
     lines.push('  <dl className="mt-6 grid grid-cols-1 gap-4 sm:grid-cols-2 border-t border-gray-200 dark:border-gray-700 pt-4">');
     for (const rel of belongsTo) {
-      lines.push(...renderField({ name: `${rel}Id`, label: humanize(rel) }, { muted: false }));
+      lines.push(...renderRelationshipField(rel));
     }
     lines.push("  </dl>");
   }
@@ -36,11 +35,12 @@ function composeDetailBody(context) {
   lines.push("</div>");
   return lines.join("\n");
 }
-function partitionFields(model) {
+function partitionFields(model, exclude = /* @__PURE__ */ new Set()) {
   const attrs = Object.keys(model.attributes ?? {});
   const business = [];
   const metadata = [];
   for (const name of attrs) {
+    if (exclude.has(name)) continue;
     const field = { name, label: humanize(name) };
     if (METADATA_FIELD_NAMES.has(name)) {
       metadata.push(field);
@@ -50,14 +50,16 @@ function partitionFields(model) {
   }
   return { business, metadata };
 }
-function extractBelongsTo(model) {
-  const rels = model.relationships ?? {};
-  const out = [];
-  for (const [name, def] of Object.entries(rels)) {
-    const d = def;
-    if (d?.type === "belongsTo") out.push(name);
-  }
-  return out;
+function renderRelationshipField(rel) {
+  const label = humanize(rel.name);
+  const fkName = `${rel.name}Id`;
+  const optionsVar = `${rel.name}Options`;
+  return [
+    "    <div>",
+    `      <dt className="text-sm font-medium text-gray-500 dark:text-gray-400">${label}</dt>`,
+    `      <dd className="mt-1 text-sm text-gray-900 dark:text-gray-100 break-words">{resolveEntityDisplayName((item as any).${fkName}, ${optionsVar})}</dd>`,
+    "    </div>"
+  ];
 }
 function renderField(field, opts) {
   const label = field.label ?? humanize(field.name);

package/dist/libs/instance-factories/applications/templates/react-starter/form-body-composer.js

@@ -1,8 +1,9 @@
 import { METADATA_FIELDS } from "@specverse/runtime/views/core";
+import { extractBelongsToTargets } from "./belongs-to.js";
 const AUTO_GENERATED_FIELD_NAMES = new Set(METADATA_FIELDS);
 function composeFormBody(context) {
-  const belongsTo = extractBelongsTo(context.model);
-  const shadowedFKs = new Set(belongsTo.map((rel) => `${rel}Id`));
+  const belongsTo = extractBelongsToTargets(context.model);
+  const shadowedFKs = new Set(belongsTo.map((rel) => `${rel.name}Id`));
   const fields = selectFormFields(context.model, shadowedFKs);
   const lines = [];
   lines.push('<div className="space-y-4">');
@@ -14,25 +15,37 @@ function composeFormBody(context) {
   for (const field of fields) {
     lines.push(...renderInput(field));
   }
-  if (belongsTo.length > 0) {
-    lines.push("");
-    lines.push("  {/* TODO: swap these text inputs for <select>s that load the related");
-    lines.push("      entities. See useEntitiesQuery(TargetModel) in the runtime hooks. */}");
-    for (const rel of belongsTo) {
-      lines.push(...renderInput({
-        name: `${rel}Id`,
-        label: humanize(rel),
-        type: "String",
-        required: true
-      }));
-    }
+  for (const rel of belongsTo) {
+    lines.push(...renderRelationshipSelect(rel));
   }
   lines.push("</div>");
   return lines.join("\n");
 }
+function renderRelationshipSelect(rel) {
+  const fkName = `${rel.name}Id`;
+  const varName = `${rel.name}Options`;
+  const label = humanize(rel.name);
+  return [
+    "  <div>",
+    `    <label className="${LABEL_CLS}" htmlFor="${fkName}">${label} *</label>`,
+    `    <select`,
+    `      id="${fkName}"`,
+    `      className="${INPUT_CLS}"`,
+    `      value={String((formData as any).${fkName} ?? '')}`,
+    `      onChange={e => handleChange('${fkName}', e.target.value)} required`,
+    `    >`,
+    `      <option value="">\u2014 choose \u2014</option>`,
+    `      {${varName}.map((opt: any) => (`,
+    `        <option key={opt.id} value={opt.id}>{getEntityDisplayName(opt)}</option>`,
+    `      ))}`,
+    `    </select>`,
+    "  </div>"
+  ];
+}
 function selectFormFields(model, skip = /* @__PURE__ */ new Set()) {
   const out = [];
   const attrs = model.attributes ?? {};
+  const lifecycleStates = extractLifecycleStates(model);
   for (const [name, rawDef] of Object.entries(attrs)) {
     if (AUTO_GENERATED_FIELD_NAMES.has(name)) continue;
     if (skip.has(name)) continue;
@@ -40,7 +53,9 @@ function selectFormFields(model, skip = /* @__PURE__ */ new Set()) {
     if (def?.auto) continue;
     const type = def?.type ?? parseTypeFromConvention(def) ?? "String";
     const required = def?.required === true || hasConventionFlag(def, "required");
-    const values = def?.values;
+    const declaredValues = def?.values;
+    const lifecycleValues = lifecycleStates.get(name);
+    const values = declaredValues ?? lifecycleValues;
     const maxLength = def?.maxLength ?? def?.max;
     const isLongString = typeof maxLength === "number" && maxLength > 100;
     out.push({
@@ -54,6 +69,26 @@ function selectFormFields(model, skip = /* @__PURE__ */ new Set()) {
   }
   return out;
 }
+function extractLifecycleStates(model) {
+  const out = /* @__PURE__ */ new Map();
+  const lifecycles = model.lifecycles ?? {};
+  for (const [name, rawDef] of Object.entries(lifecycles)) {
+    if (!rawDef || typeof rawDef !== "object") continue;
+    const def = rawDef;
+    if (Array.isArray(def.states) && def.states.length > 0) {
+      const names = def.states.map((s) => typeof s === "string" ? s : s?.name ?? s?.id ?? "").filter(Boolean);
+      if (names.length > 0) {
+        out.set(name, names);
+        continue;
+      }
+    }
+    if (typeof def.flow === "string") {
+      const states = def.flow.split(/\s*(?:->|,)\s*/).map((s) => s.trim()).filter(Boolean);
+      if (states.length > 0) out.set(name, states);
+    }
+  }
+  return out;
+}
 function parseTypeFromConvention(def) {
   if (typeof def === "string") {
     const first = def.trim().split(/\s+/)[0];
@@ -70,14 +105,6 @@ function hasConventionFlag(def, flag) {
 function normalizeType(type) {
   return type.replace(/[^A-Za-z].*$/, "");
 }
-function extractBelongsTo(model) {
-  const rels = model.relationships ?? {};
-  const out = [];
-  for (const [name, def] of Object.entries(rels)) {
-    if (def?.type === "belongsTo") out.push(name);
-  }
-  return out;
-}
 const INPUT_CLS = "w-full rounded border border-gray-300 px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-blue-500 dark:border-gray-600 dark:bg-gray-800 dark:text-gray-100";
 const LABEL_CLS = "block text-sm font-medium text-gray-700 dark:text-gray-300 mb-1";
 function renderInput(field) {

package/dist/libs/instance-factories/applications/templates/react-starter/helpers-emitter.js

@@ -28,14 +28,20 @@ export function getEntityDisplayName(entity: Record<string, unknown> | null | un
 /**
  * Map an entity id to the display name of the record with that id in
  * a provided list. Handy for resolving belongsTo FK columns in
- * list / detail views.
+ * list / detail / dashboard views.
+ *
+ * Typed as \`readonly unknown[]\` so callers can pass arrays of
+ * specific model types (e.g. \`User[]\`) without needing to cast; the
+ * runtime check on \`.id\` narrows safely.
  */
 export function resolveEntityDisplayName(
   id: unknown,
-  records: ReadonlyArray<Record<string, unknown>>
+  records: readonly unknown[]
 ): string {
   if (id == null) return '';
-  const match = records.find(r => r.id === id);
+  const match = records.find((r): r is Record<string, unknown> =>
+    typeof r === 'object' && r !== null && (r as { id?: unknown }).id === id
+  );
   return match ? getEntityDisplayName(match) : String(id);
 }
 `;

package/dist/libs/instance-factories/applications/templates/react-starter/list-body-composer.js

@@ -1,17 +1,25 @@
 import { createUniversalTailwindAdapter } from "@specverse/runtime/views/tailwind";
 import { inferFieldsFromSchema } from "@specverse/runtime/views/core";
 import { htmlToJsx } from "./html-to-jsx.js";
+import { buildFKMap } from "./belongs-to.js";
 const TBODY_SENTINEL = "__SPECVERSE_TBODY_ROWS__";
 function composeListBody(context) {
-  const columns = inferColumns(context);
-  const headers = columns.map(humanize);
+  const fkMap = buildFKMap(context.model);
+  const inferred = inferColumns(context);
+  const inferredSet = new Set(inferred);
+  const extraFKs = [...fkMap.keys()].filter((k) => !inferredSet.has(k));
+  const columns = [...inferred, ...extraFKs];
+  const headers = columns.map((col) => {
+    const fk = fkMap.get(col);
+    return humanize(fk ? fk.name : col);
+  });
   const adapter = createUniversalTailwindAdapter({ darkMode: true });
   const shellHtml = adapter.components.table.render({
     properties: { columns: headers },
     children: TBODY_SENTINEL
   });
   const shellJsx = htmlToJsx(shellHtml);
-  const rowMap = buildRowMap(columns);
+  const rowMap = buildRowMap(columns, fkMap);
   if (!shellJsx.includes(TBODY_SENTINEL)) {
     throw new Error(
       "composeListBody: tbody sentinel not present in adapter output. The canonical Tailwind adapter may have changed its table rendering."
@@ -25,10 +33,12 @@ function inferColumns(context) {
 function humanize(name) {
   return name.replace(/([A-Z])/g, " $1").replace(/^./, (c) => c.toUpperCase()).trim();
 }
-function buildRowMap(columns) {
-  const cells = columns.map(
-    (col) => `            <td className="px-6 py-4 text-sm text-gray-700 dark:text-gray-300">{String((item as any).${col} ?? '')}</td>`
-  ).join("\n");
+function buildRowMap(columns, fkMap) {
+  const cells = columns.map((col) => {
+    const fk = fkMap.get(col);
+    const expr = fk ? `{resolveEntityDisplayName((item as any).${col}, ${fk.name}Options)}` : `{String((item as any).${col} ?? '')}`;
+    return `            <td className="px-6 py-4 text-sm text-gray-700 dark:text-gray-300">${expr}</td>`;
+  }).join("\n");
   return [
     "{filtered.map((item, idx) => (",
     "  <tr",

package/dist/libs/instance-factories/applications/templates/react-starter/orchestrator.js

@@ -1,3 +1,5 @@
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { join, dirname } from "path";
 import { generate as generateViews } from "./views-generator.js";
 import { generate as generateAppTsx } from "./app-tsx-generator.js";
 import { generate as generatePackageJson } from "./package-json-generator.js";
@@ -9,7 +11,9 @@ import {
   HASHES_FILE
 } from "./regen-safety.js";
 async function generate(context) {
-  const { spec, projectRoot } = context;
+  const { spec, outputDir } = context;
+  const frontendDir = context.frontendDir || "frontend";
+  const projectRoot = frontendDir === "." ? outputDir : join(outputDir, frontendDir);
   const proposed = {};
   const viewFiles = await generateViews({ spec });
   Object.assign(proposed, viewFiles);
@@ -18,13 +22,20 @@ async function generate(context) {
   const prevManifest = loadHashManifest(projectRoot);
   const result = reconcileWrites(projectRoot, proposed, prevManifest);
   console.log(summarize(result, projectRoot));
-  const manifestPath = `${HASHES_DIR}/${HASHES_FILE}`;
-  const out = {
+  const toWrite = {
     ...result.approvedWrites,
-    [manifestPath]: JSON.stringify(result.manifest, null, 2) + "\n"
+    [`${HASHES_DIR}/${HASHES_FILE}`]: JSON.stringify(result.manifest, null, 2) + "\n"
   };
-  return out;
+  for (const [rel, content] of Object.entries(toWrite)) {
+    const abs = join(projectRoot, rel);
+    const dir = dirname(abs);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(abs, content, "utf-8");
+  }
+  return "";
 }
+var stdin_default = generate;
 export {
+  stdin_default as default,
   generate
 };

package/dist/libs/instance-factories/applications/templates/react-starter/skeletons/dashboard.tsx.template

@@ -0,0 +1,49 @@
+/**
+ * {{MODEL_NAME}}DashboardView — generated by @specverse/realize (ReactAppStarter)
+ *
+ * Safe to edit. Edits are preserved across regeneration via content
+ * hashing (see .specverse-gen/hashes.json). To accept an upstream
+ * regeneration of this file, delete it first, then run `spv realize`.
+ *
+ * A minimal dashboard: summary counts derived from the list query,
+ * plus a compact preview of recent records. Charts and aggregation
+ * metrics are deferred — add them as the backend grows suitable
+ * endpoints.
+ */
+import { useMemo } from 'react';
+import { use{{PLURAL_MODEL}}Query } from '../hooks/useApi';
+{{RELATED_IMPORTS}}
+import type { {{MODEL_NAME}} } from '../types/api';
+
+interface {{MODEL_NAME}}DashboardViewProps {
+  /** Number of recent records to preview. Default 5. */
+  previewLimit?: number;
+  onSelect?: (item: {{MODEL_NAME}}) => void;
+}
+
+export function {{MODEL_NAME}}DashboardView({
+  previewLimit = 5,
+  onSelect,
+}: {{MODEL_NAME}}DashboardViewProps) {
+  const { data: items = [], isLoading, error } = use{{PLURAL_MODEL}}Query();
+{{RELATED_HOOKS}}
+
+  const preview = useMemo(
+    () => items.slice(0, previewLimit),
+    [items, previewLimit]
+  );
+
+  if (isLoading) return <div className="p-4 text-gray-500">Loading dashboard…</div>;
+  if (error) return <div className="p-4 text-red-600">Error loading {{PLURAL_LOWER}}: {String(error)}</div>;
+
+  return (
+    <div className="p-6 space-y-6">
+      <h2 className="text-xl font-semibold text-gray-900 dark:text-gray-100">
+        {{MODEL_NAME}} dashboard
+      </h2>
+
+      {/* Pattern-rendered dashboard body (metrics + preview). Edit freely. */}
+      {{BODY}}
+    </div>
+  );
+}

package/dist/libs/instance-factories/applications/templates/react-starter/skeletons/detail.tsx.template

@@ -0,0 +1,96 @@
+/**
+ * {{MODEL_NAME}}DetailView — generated by @specverse/realize (ReactAppStarter)
+ *
+ * Safe to edit. Edits are preserved across regeneration via content
+ * hashing (see .specverse-gen/hashes.json). To accept an upstream
+ * regeneration of this file, delete it first, then run `spv realize`.
+ */
+import { use{{PLURAL_MODEL}}Query, useDelete{{MODEL_NAME}}Mutation } from '../hooks/useApi';
+{{RELATED_IMPORTS}}
+import type { {{MODEL_NAME}} } from '../types/api';
+
+interface {{MODEL_NAME}}DetailViewProps {
+  entityId: string | number;
+  onEdit?: (item: {{MODEL_NAME}}) => void;
+  onBack?: () => void;
+  /** Called after the delete mutation succeeds. */
+  onDeleted?: () => void;
+}
+
+export function {{MODEL_NAME}}DetailView({
+  entityId,
+  onEdit,
+  onBack,
+  onDeleted,
+}: {{MODEL_NAME}}DetailViewProps) {
+  const { data: items = [], isLoading, error } = use{{PLURAL_MODEL}}Query();
+  const deleteItem = useDelete{{MODEL_NAME}}Mutation();
+{{RELATED_HOOKS}}
+
+  const item = items.find(
+    (x: {{MODEL_NAME}}) => (x as any).id === entityId
+  );
+
+  if (isLoading) return <div className="p-4 text-gray-500">Loading…</div>;
+  if (error) return <div className="p-4 text-red-600">Error loading {{PLURAL_LOWER}}: {String(error)}</div>;
+  if (!item) return <div className="p-4 text-gray-400">No {{SINGULAR_LOWER}} matching id {String(entityId)}.</div>;
+
+  const handleDelete = async () => {
+    if (!confirm('Delete this {{SINGULAR_LOWER}}?')) return;
+    try {
+      await deleteItem.mutateAsync((item as any).id);
+      onDeleted?.();
+    } catch {
+      // deleteItem.error is surfaced below
+    }
+  };
+
+  return (
+    <div className="p-6 space-y-4">
+      <div className="flex items-center justify-between">
+        <div className="flex items-center gap-3">
+          {onBack && (
+            <button
+              type="button"
+              onClick={onBack}
+              className="text-sm text-gray-500 hover:text-gray-700"
+            >
+              ← Back
+            </button>
+          )}
+          <h2 className="text-xl font-semibold text-gray-900 dark:text-gray-100">
+            {{MODEL_NAME}} detail
+          </h2>
+        </div>
+        <div className="flex gap-2">
+          {onEdit && (
+            <button
+              type="button"
+              onClick={() => onEdit(item)}
+              className="rounded bg-blue-600 px-4 py-2 text-sm font-medium text-white hover:bg-blue-700"
+            >
+              Edit
+            </button>
+          )}
+          <button
+            type="button"
+            onClick={handleDelete}
+            disabled={deleteItem.isPending}
+            className="rounded bg-red-600 px-4 py-2 text-sm font-medium text-white hover:bg-red-700 disabled:opacity-60"
+          >
+            {deleteItem.isPending ? 'Deleting…' : 'Delete'}
+          </button>
+        </div>
+      </div>
+
+      {/* Pattern-rendered detail body (fields). Edit freely. */}
+      {{BODY}}
+
+      {deleteItem.isError && (
+        <div className="p-2 text-sm text-red-600">
+          Delete failed: {String(deleteItem.error)}
+        </div>
+      )}
+    </div>
+  );
+}

package/dist/libs/instance-factories/applications/templates/react-starter/skeletons/form.tsx.template

@@ -0,0 +1,116 @@
+/**
+ * {{MODEL_NAME}}FormView — generated by @specverse/realize (ReactAppStarter)
+ *
+ * Safe to edit. Edits are preserved across regeneration via content
+ * hashing (see .specverse-gen/hashes.json). To accept an upstream
+ * regeneration of this file, delete it first, then run `spv realize`.
+ *
+ * Controlled form. One field per non-auto-generated attribute.
+ * Mode: 'create' (default) or 'update' — passed as a prop.
+ */
+import { useEffect, useState } from 'react';
+import {
+  use{{PLURAL_MODEL}}Query,
+  useCreate{{MODEL_NAME}}Mutation,
+  useUpdate{{MODEL_NAME}}Mutation,
+} from '../hooks/useApi';
+{{RELATED_IMPORTS}}
+import type { {{MODEL_NAME}} } from '../types/api';
+
+type FormMode = 'create' | 'update';
+
+interface {{MODEL_NAME}}FormViewProps {
+  mode?: FormMode;
+  /** Required in update mode. */
+  entityId?: string | number;
+  onSuccess?: (item: {{MODEL_NAME}}) => void;
+  onCancel?: () => void;
+}
+
+export function {{MODEL_NAME}}FormView({
+  mode = 'create',
+  entityId,
+  onSuccess,
+  onCancel,
+}: {{MODEL_NAME}}FormViewProps) {
+  const { data: items = [] } = use{{PLURAL_MODEL}}Query();
+  const createItem = useCreate{{MODEL_NAME}}Mutation();
+  const updateItem = useUpdate{{MODEL_NAME}}Mutation();
+{{RELATED_HOOKS}}
+
+  const existing =
+    mode === 'update'
+      ? items.find((x: {{MODEL_NAME}}) => (x as any).id === entityId)
+      : undefined;
+
+  const [formData, setFormData] = useState<Partial<{{MODEL_NAME}}>>(existing ?? {});
+
+  // When the fetched list lands after initial render (update mode),
+  // hydrate the form with the loaded entity's data.
+  useEffect(() => {
+    if (existing) setFormData(existing);
+  }, [existing]);
+
+  const handleChange = (field: string, value: unknown) => {
+    setFormData(prev => ({ ...prev, [field]: value }) as Partial<{{MODEL_NAME}}>);
+  };
+
+  const handleSubmit = async (event: React.FormEvent) => {
+    event.preventDefault();
+    try {
+      const result =
+        mode === 'create'
+          ? await createItem.mutateAsync(formData as {{MODEL_NAME}})
+          : await updateItem.mutateAsync({
+              id: entityId as any,
+              data: formData as Partial<{{MODEL_NAME}}>,
+            });
+      onSuccess?.(result as {{MODEL_NAME}});
+    } catch {
+      // Mutation errors are surfaced below via createItem / updateItem.
+    }
+  };
+
+  const mutation = mode === 'create' ? createItem : updateItem;
+  const submitLabel =
+    mode === 'create'
+      ? mutation.isPending ? 'Creating…' : 'Create {{MODEL_NAME}}'
+      : mutation.isPending ? 'Updating…' : 'Update {{MODEL_NAME}}';
+
+  return (
+    <form onSubmit={handleSubmit} className="p-6 space-y-6">
+      <h2 className="text-xl font-semibold text-gray-900 dark:text-gray-100">
+        {mode === 'create' ? 'New {{MODEL_NAME}}' : 'Edit {{MODEL_NAME}}'}
+      </h2>
+
+      {/* Pattern-rendered form fields. Edit freely. */}
+      {{BODY}}
+
+      <div className="flex gap-2 border-t border-gray-200 dark:border-gray-700 pt-4">
+        <button
+          type="submit"
+          disabled={mutation.isPending}
+          className="rounded bg-blue-600 px-4 py-2 text-sm font-medium text-white hover:bg-blue-700 disabled:opacity-60"
+        >
+          {submitLabel}
+        </button>
+        {onCancel && (
+          <button
+            type="button"
+            onClick={onCancel}
+            className="rounded border border-gray-300 px-4 py-2 text-sm font-medium text-gray-700 hover:bg-gray-50 dark:border-gray-600 dark:text-gray-200 dark:hover:bg-gray-800"
+          >
+            Cancel
+          </button>
+        )}
+      </div>
+
+      {mutation.isError && (
+        <div className="rounded border border-red-200 bg-red-50 p-3 text-sm text-red-700 dark:border-red-800 dark:bg-red-950 dark:text-red-300">
+          {mode === 'create' ? 'Create failed: ' : 'Update failed: '}
+          {String(mutation.error)}
+        </div>
+      )}
+    </form>
+  );
+}

package/dist/libs/instance-factories/applications/templates/react-starter/skeletons/list.tsx.template

@@ -0,0 +1,74 @@
+/**
+ * {{MODEL_NAME}}ListView — generated by @specverse/realize (ReactAppStarter)
+ *
+ * Safe to edit. Edits are preserved across regeneration via content
+ * hashing (see .specverse-gen/hashes.json). To accept an upstream
+ * regeneration of this file, delete it first, then run `spv realize`.
+ */
+import { useState, useMemo } from 'react';
+import { use{{PLURAL_MODEL}}Query, useDelete{{MODEL_NAME}}Mutation } from '../hooks/useApi';
+{{RELATED_IMPORTS}}
+import type { {{MODEL_NAME}} } from '../types/api';
+
+interface {{MODEL_NAME}}ListViewProps {
+  onSelect?: (item: {{MODEL_NAME}}) => void;
+  onCreate?: () => void;
+}
+
+export function {{MODEL_NAME}}ListView({ onSelect, onCreate }: {{MODEL_NAME}}ListViewProps) {
+  const { data: items = [], isLoading, error } = use{{PLURAL_MODEL}}Query();
+  const deleteItem = useDelete{{MODEL_NAME}}Mutation();
+{{RELATED_HOOKS}}
+  const [searchTerm, setSearchTerm] = useState('');
+
+  const filtered = useMemo(
+    () =>
+      items.filter((item: {{MODEL_NAME}}) =>
+        // Cast to `any` inside JSX context — `Record<string, unknown>`
+        // looks like a JSX opening tag to the TSX parser when this
+        // expression ends up inside JSX. `any` is safe here: we only
+        // read values for substring-matching against the search term.
+        Object.values(item as any).some(v =>
+          String(v ?? '').toLowerCase().includes(searchTerm.toLowerCase())
+        )
+      ),
+    [items, searchTerm]
+  );
+
+  if (isLoading) return <div className="p-4 text-gray-500">Loading {{PLURAL_LOWER}}…</div>;
+  if (error) return <div className="p-4 text-red-600">Error loading {{PLURAL_LOWER}}: {String(error)}</div>;
+
+  return (
+    <div className="p-6 space-y-4">
+      <div className="flex items-center justify-between">
+        <input
+          type="search"
+          placeholder="Search {{PLURAL_LOWER}}…"
+          value={searchTerm}
+          onChange={e => setSearchTerm(e.target.value)}
+          className="w-64 rounded border border-gray-300 px-3 py-2 text-sm"
+        />
+        <button
+          type="button"
+          onClick={onCreate}
+          className="rounded bg-blue-600 px-4 py-2 text-sm font-medium text-white hover:bg-blue-700"
+        >
+          + New {{MODEL_NAME}}
+        </button>
+      </div>
+
+      {/* Pattern-rendered list body (table + rows). Edit freely. */}
+      {{BODY}}
+
+      {filtered.length === 0 && (
+        <div className="p-8 text-center text-gray-400">No {{PLURAL_LOWER}} yet.</div>
+      )}
+
+      {deleteItem.isError && (
+        <div className="p-2 text-sm text-red-600">
+          Delete failed: {String(deleteItem.error)}
+        </div>
+      )}
+    </div>
+  );
+}