@specverse/engines 4.1.30 → 4.2.1

package/dist/libs/instance-factories/applications/templates/react-starter/html-to-jsx.js

@@ -0,0 +1,192 @@
+const VOID_ELEMENTS = /* @__PURE__ */ new Set([
+  "area",
+  "base",
+  "br",
+  "col",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "link",
+  "meta",
+  "source",
+  "track",
+  "wbr"
+]);
+const ATTRIBUTE_RENAMES = {
+  class: "className",
+  for: "htmlFor",
+  tabindex: "tabIndex",
+  readonly: "readOnly",
+  maxlength: "maxLength",
+  minlength: "minLength",
+  colspan: "colSpan",
+  rowspan: "rowSpan",
+  autofocus: "autoFocus",
+  autocomplete: "autoComplete",
+  cellpadding: "cellPadding",
+  cellspacing: "cellSpacing",
+  enctype: "encType",
+  usemap: "useMap",
+  accesskey: "accessKey",
+  contenteditable: "contentEditable",
+  spellcheck: "spellCheck",
+  crossorigin: "crossOrigin",
+  srcset: "srcSet",
+  srcdoc: "srcDoc"
+};
+function htmlToJsx(html) {
+  if (!html) return "";
+  const tokens = tokenize(html);
+  return tokens.map(transformToken).join("");
+}
+function tokenize(input) {
+  const tokens = [];
+  let i = 0;
+  const n = input.length;
+  while (i < n) {
+    const ch = input[i];
+    if (ch === "<") {
+      const tagStart = i;
+      i++;
+      let quote = null;
+      while (i < n) {
+        const c = input[i];
+        if (quote) {
+          if (c === quote) quote = null;
+          i++;
+          continue;
+        }
+        if (c === '"' || c === "'") {
+          quote = c;
+          i++;
+          continue;
+        }
+        if (c === ">") {
+          i++;
+          break;
+        }
+        i++;
+      }
+      const raw = input.slice(tagStart, i);
+      const isClosing = raw.startsWith("</");
+      const isSelfClosed = raw.endsWith("/>");
+      const tagName = parseTagName(raw);
+      tokens.push({ kind: "tag", raw, tagName, isClosing, isSelfClosed });
+    } else {
+      const textStart = i;
+      while (i < n && input[i] !== "<") i++;
+      tokens.push({ kind: "text", value: input.slice(textStart, i) });
+    }
+  }
+  return tokens;
+}
+function parseTagName(tagRaw) {
+  const m = tagRaw.match(/^<\/?([a-zA-Z][a-zA-Z0-9-]*)/);
+  return m ? m[1].toLowerCase() : "";
+}
+function transformToken(token) {
+  if (token.kind === "text") {
+    return token.value;
+  }
+  return transformTag(token.raw, token.tagName, token.isClosing, token.isSelfClosed);
+}
+function transformTag(raw, tagName, isClosing, isSelfClosed) {
+  if (isClosing) {
+    return raw;
+  }
+  const inner = isSelfClosed ? raw.slice(1, -2).trimEnd() : raw.slice(1, -1);
+  const nameMatch = inner.match(/^([a-zA-Z][a-zA-Z0-9-]*)(.*)$/s);
+  if (!nameMatch) return raw;
+  const elementName = nameMatch[1];
+  const attrsSection = nameMatch[2];
+  const attrs = parseAttributes(attrsSection);
+  const renamedAttrs = attrs.map(renameAttribute);
+  const rebuiltAttrs = serializeAttributes(renamedAttrs);
+  const shouldSelfClose = VOID_ELEMENTS.has(tagName) && !isSelfClosed;
+  if (shouldSelfClose || isSelfClosed) {
+    return `<${elementName}${rebuiltAttrs} />`;
+  }
+  return `<${elementName}${rebuiltAttrs}>`;
+}
+function parseAttributes(section) {
+  const attrs = [];
+  let i = 0;
+  const n = section.length;
+  while (i < n) {
+    while (i < n && /\s/.test(section[i])) i++;
+    if (i >= n) break;
+    const nameStart = i;
+    while (i < n && /[a-zA-Z0-9:_-]/.test(section[i])) i++;
+    if (i === nameStart) {
+      i++;
+      continue;
+    }
+    const name = section.slice(nameStart, i);
+    let j = i;
+    while (j < n && /\s/.test(section[j])) j++;
+    if (j >= n || section[j] !== "=") {
+      attrs.push({ name });
+      continue;
+    }
+    i = j + 1;
+    while (i < n && /\s/.test(section[i])) i++;
+    if (i >= n) {
+      attrs.push({ name });
+      break;
+    }
+    const vc = section[i];
+    if (vc === '"' || vc === "'") {
+      const quote = vc;
+      i++;
+      const valStart = i;
+      while (i < n && section[i] !== quote) i++;
+      const value = section.slice(valStart, i);
+      if (i < n) i++;
+      attrs.push({ name, value, quote });
+    } else {
+      const valStart = i;
+      while (i < n && !/[\s/>]/.test(section[i])) i++;
+      const value = section.slice(valStart, i);
+      attrs.push({ name, value });
+    }
+  }
+  return attrs;
+}
+function renameAttribute(attr) {
+  const lower = attr.name.toLowerCase();
+  const newName = ATTRIBUTE_RENAMES[lower] ?? attr.name;
+  if (lower === "style" && attr.value !== void 0) {
+    return { name: newName, value: cssStringToJsxObject(attr.value), quote: void 0 };
+  }
+  return { ...attr, name: newName };
+}
+function serializeAttributes(attrs) {
+  if (attrs.length === 0) return "";
+  const parts = attrs.map((attr) => {
+    if (attr.value === void 0) return ` ${attr.name}`;
+    if (attr.value.startsWith("{{") && attr.value.endsWith("}}")) {
+      return ` ${attr.name}=${attr.value}`;
+    }
+    const q = attr.quote ?? '"';
+    return ` ${attr.name}=${q}${attr.value}${q}`;
+  });
+  return parts.join("");
+}
+function cssStringToJsxObject(css) {
+  const declarations = css.split(";").map((d) => d.trim()).filter((d) => d.length > 0);
+  if (declarations.length === 0) return "{{}}";
+  const entries = declarations.map((decl) => {
+    const colonIdx = decl.indexOf(":");
+    if (colonIdx === -1) return null;
+    const prop = decl.slice(0, colonIdx).trim();
+    const value = decl.slice(colonIdx + 1).trim();
+    const camelProp = prop.replace(/-([a-z])/g, (_m, c) => c.toUpperCase());
+    const escapedValue = value.replace(/'/g, "\\'");
+    return `${camelProp}: '${escapedValue}'`;
+  }).filter((e) => e !== null);
+  return `{{ ${entries.join(", ")} }}`;
+}
+export {
+  htmlToJsx
+};

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

@@ -0,0 +1,56 @@
+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 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, 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."
+    );
+  }
+  return shellJsx.replace(TBODY_SENTINEL, rowMap);
+}
+function inferColumns(context) {
+  return inferFieldsFromSchema(context.modelSchemas, context.model.name);
+}
+function humanize(name) {
+  return name.replace(/([A-Z])/g, " $1").replace(/^./, (c) => c.toUpperCase()).trim();
+}
+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",
+    "    key={idx}",
+    "    onClick={() => onSelect?.(item)}",
+    '    className="hover:bg-gray-50 dark:hover:bg-gray-800 cursor-pointer"',
+    "  >",
+    cells,
+    "  </tr>",
+    "))}"
+  ].join("\n");
+}
+export {
+  composeListBody
+};

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

@@ -0,0 +1,41 @@
+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";
+import {
+  loadHashManifest,
+  reconcileWrites,
+  summarize,
+  HASHES_DIR,
+  HASHES_FILE
+} from "./regen-safety.js";
+async function generate(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);
+  proposed["src/App.tsx"] = await generateAppTsx({ spec });
+  proposed["package.json"] = await generatePackageJson({ spec });
+  const prevManifest = loadHashManifest(projectRoot);
+  const result = reconcileWrites(projectRoot, proposed, prevManifest);
+  console.log(summarize(result, projectRoot));
+  const toWrite = {
+    ...result.approvedWrites,
+    [`${HASHES_DIR}/${HASHES_FILE}`]: JSON.stringify(result.manifest, null, 2) + "\n"
+  };
+  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/package-json-generator.js

@@ -0,0 +1,38 @@
+async function generate(context) {
+  const appName = context.spec?.metadata?.name ?? context.spec?.name ?? "specverse-starter-app";
+  const packageName = slugify(appName);
+  const pkg = {
+    name: packageName,
+    private: true,
+    version: "0.1.0",
+    type: "module",
+    scripts: {
+      dev: "vite",
+      build: "tsc && vite build",
+      preview: "vite preview",
+      typecheck: "tsc --noEmit"
+    },
+    dependencies: {
+      react: "^18.2.0",
+      "react-dom": "^18.2.0",
+      "@tanstack/react-query": "^5.0.0"
+    },
+    devDependencies: {
+      "@types/react": "^18.2.0",
+      "@types/react-dom": "^18.2.0",
+      "@vitejs/plugin-react": "^4.2.0",
+      autoprefixer: "^10.4.20",
+      postcss: "^8.4.47",
+      tailwindcss: "^3.4.13",
+      typescript: "^5.2.0",
+      vite: "^6.0.0"
+    }
+  };
+  return JSON.stringify(pkg, null, 2) + "\n";
+}
+function slugify(s) {
+  return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "specverse-starter-app";
+}
+export {
+  generate
+};

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

@@ -0,0 +1,89 @@
+import { createHash } from "crypto";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { join, relative } from "path";
+const HASHES_DIR = ".specverse-gen";
+const HASHES_FILE = "hashes.json";
+function sha256(s) {
+  return createHash("sha256").update(s, "utf8").digest("hex");
+}
+function loadHashManifest(projectRoot) {
+  const path = join(projectRoot, HASHES_DIR, HASHES_FILE);
+  if (!existsSync(path)) return {};
+  try {
+    const raw = readFileSync(path, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      const out = {};
+      for (const [k, v] of Object.entries(parsed)) {
+        if (typeof v === "string") out[k] = v;
+      }
+      return out;
+    }
+  } catch {
+  }
+  return {};
+}
+function saveHashManifest(projectRoot, manifest) {
+  const dir = join(projectRoot, HASHES_DIR);
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, HASHES_FILE);
+  writeFileSync(path, JSON.stringify(manifest, null, 2) + "\n", "utf8");
+}
+function reconcileWrites(projectRoot, proposed, prevManifest) {
+  const manifest = { ...prevManifest };
+  const approvedWrites = {};
+  const skipped = [];
+  for (const [relPath, content] of Object.entries(proposed)) {
+    const abs = join(projectRoot, relPath);
+    const newHash = sha256(content);
+    if (!existsSync(abs)) {
+      approvedWrites[relPath] = content;
+      manifest[relPath] = newHash;
+      continue;
+    }
+    const currentContent = readFileSync(abs, "utf8");
+    const currentHash = sha256(currentContent);
+    const recordedHash = prevManifest[relPath];
+    if (recordedHash == null) {
+      skipped.push({
+        path: relPath,
+        reason: "no prior hash recorded \u2014 cannot confirm this file was generated by us"
+      });
+      continue;
+    }
+    if (currentHash === recordedHash) {
+      approvedWrites[relPath] = content;
+      manifest[relPath] = newHash;
+      continue;
+    }
+    skipped.push({
+      path: relPath,
+      reason: "file has been edited since last generation"
+    });
+  }
+  return { approvedWrites, skipped, manifest };
+}
+function summarize(result, projectRoot) {
+  const lines = [];
+  const writeCount = Object.keys(result.approvedWrites).length;
+  lines.push(`[ReactAppStarter] Approved ${writeCount} file(s) for writing.`);
+  if (result.skipped.length > 0) {
+    lines.push(`[ReactAppStarter] Skipped ${result.skipped.length} user-edited file(s):`);
+    for (const { path, reason } of result.skipped) {
+      lines.push(`  - ${path} (${reason})`);
+    }
+    lines.push(
+      `To accept upstream regeneration for a skipped file, delete it (\`rm ${relative(process.cwd(), projectRoot)}/PATH\`) and re-run \`spv realize\`.`
+    );
+  }
+  return lines.join("\n");
+}
+export {
+  HASHES_DIR,
+  HASHES_FILE,
+  loadHashManifest,
+  reconcileWrites,
+  saveHashManifest,
+  sha256,
+  summarize
+};

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>
+  );
+}