@specverse/engines 4.1.30 → 4.2.0

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

@@ -0,0 +1,120 @@
+/**
+ * List-view body composer for ReactAppStarter
+ *
+ * Implements the `renderBody` contract of view-emitter.ts for list
+ * views. Uses the canonical Tailwind adapter from
+ * `@specverse/runtime/views/tailwind` to render the TABLE SHELL, then
+ * injects a JSX `.map()` expression into the tbody so the generated
+ * component renders rows from the `filtered` array defined by the
+ * skeleton.
+ *
+ * Why split it this way: the adapter produces static HTML (the same
+ * HTML app-demo uses). For Factory B we want React that maps over
+ * runtime data — so we take the adapter's shell and replace a sentinel
+ * inside the tbody with a `{filtered.map(...)}` expression. The shell
+ * stays canonical; only the row-iteration JSX is synthesized here.
+ *
+ * See README.md for the full architecture.
+ */
+
+import { createUniversalTailwindAdapter } from '@specverse/runtime/views/tailwind';
+import { inferFieldsFromSchema } from '@specverse/runtime/views/core';
+import { htmlToJsx } from './html-to-jsx.js';
+import type { EmitContext, ModelSpec } from './view-emitter.js';
+
+/**
+ * Sentinel token. Must be ASCII-safe (no curly braces) so it survives
+ * the html-to-jsx transform unchanged, and must be unique enough not
+ * to appear in real HTML output.
+ */
+const TBODY_SENTINEL = '__SPECVERSE_TBODY_ROWS__';
+
+/**
+ * Compose the list view's body as JSX-safe source. Returned string is
+ * meant to be dropped at `{{BODY}}` inside `skeletons/list.tsx.template`.
+ */
+export function composeListBody(context: EmitContext): string {
+  const columns = inferColumns(context);
+  const headers = columns.map(humanize);
+
+  const adapter = createUniversalTailwindAdapter({ darkMode: true });
+  const shellHtml = adapter.components.table.render({
+    properties: { columns: headers },
+    children: TBODY_SENTINEL,
+  });
+
+  // Transform the static HTML shell to JSX-safe source. The sentinel
+  // lands in a text position inside the <tbody> and survives the
+  // transform untouched.
+  const shellJsx = htmlToJsx(shellHtml);
+
+  // Build the row-iteration JSX that replaces the sentinel. The
+  // skeleton's useMemo produces `filtered: Model[]`, so the map
+  // expression binds over that. onSelect is a prop the skeleton
+  // declares. Delete action wires to the deleteItem mutation.
+  const rowMap = buildRowMap(columns);
+
+  if (!shellJsx.includes(TBODY_SENTINEL)) {
+    // Defensive: catches adapter output changes that no longer flow
+    // `children` into the tbody. Caught at composer time, not runtime.
+    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);
+}
+
+/**
+ * Select the non-metadata attributes of a model. Delegates to the
+ * canonical pattern library so the column set is identical to what
+ * the runtime React adapter picks for the same model — parity test P3
+ * relies on this being one-and-the-same function.
+ */
+function inferColumns(context: EmitContext): string[] {
+  return inferFieldsFromSchema(context.modelSchemas, context.model.name);
+}
+
+/**
+ * Convert a camelCase attribute name to Title-Case words for display
+ * as a column header. Matches the convention used by runtime's
+ * pattern adapter (see `humanize` in runtime react-pattern-adapter).
+ */
+function humanize(name: string): string {
+  return name
+    .replace(/([A-Z])/g, ' $1')
+    .replace(/^./, c => c.toUpperCase())
+    .trim();
+}
+
+/**
+ * Emit the `{filtered.map(...)}` JSX expression that renders each
+ * row. Keep the output readable so users inspecting the generated
+ * file can follow what's happening.
+ */
+function buildRowMap(columns: string[]): string {
+  // Type-cast to `any` to avoid TS generic syntax (`<string, unknown>`)
+  // inside JSX expressions, which the TSX parser can't always
+  // disambiguate from a JSX opening tag. `any` is the right choice for
+  // starter-kit output anyway — the user will often reshape the row
+  // type after editing.
+  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');
+
+  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');
+}

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

@@ -0,0 +1,80 @@
+/**
+ * Factory B top-level orchestrator
+ *
+ * Single entry point the realize engine calls. Returns a map of
+ * `relativePath → content` for every file the factory decides to
+ * write, after applying regeneration-safety triage. Realize handles
+ * the actual filesystem writes via its normal multi-file generator
+ * pipeline.
+ *
+ * Skipped (user-edited) files are NOT in the returned map — realize
+ * never sees them, so user edits are safe. The hash manifest is
+ * emitted as one of the returned files (`.specverse-gen/hashes.json`)
+ * so it rolls through the same write pipeline.
+ */
+
+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';
+import type { ExpandedSpec } from './views-generator.js';
+
+export interface OrchestratorContext {
+  /** Expanded spec (post-inference). */
+  spec: ExpandedSpec & { metadata?: { name?: string }; name?: string };
+  /** Resolved manifest configuration. */
+  manifest?: unknown;
+  /** Absolute path to the project root (the frontend directory for this factory). */
+  projectRoot: string;
+}
+
+/**
+ * The shape realize expects from a multi-file generator: a map of
+ * relative paths to their contents. Realize creates parent dirs and
+ * writes the files verbatim.
+ *
+ * Skipped (user-edited) files are intentionally absent — realize
+ * never sees them.
+ */
+export type OrchestratorOutput = Record<string, string>;
+
+/**
+ * Produce the complete file set for a Factory B run. Realize writes
+ * whatever comes back; the orchestrator is the sole source of truth
+ * for "what ends up on disk."
+ */
+export async function generate(context: OrchestratorContext): Promise<OrchestratorOutput> {
+  const { spec, projectRoot } = context;
+
+  // 1. Produce all file contents (pure composition — no I/O yet).
+  const proposed: Record<string, string> = {};
+
+  const viewFiles = await generateViews({ spec });
+  Object.assign(proposed, viewFiles);
+
+  proposed['src/App.tsx'] = await generateAppTsx({ spec });
+  proposed['package.json'] = await generatePackageJson({ spec });
+
+  // 2. Load prior hash manifest + triage. Read-only.
+  const prevManifest = loadHashManifest(projectRoot);
+  const result = reconcileWrites(projectRoot, proposed, prevManifest);
+
+  // 3. Log the summary for operator visibility.
+  console.log(summarize(result, projectRoot));
+
+  // 4. Emit the hash manifest as one of the written files so it flows
+  //    through realize's normal write pipeline.
+  const manifestPath = `${HASHES_DIR}/${HASHES_FILE}`;
+  const out: OrchestratorOutput = {
+    ...result.approvedWrites,
+    [manifestPath]: JSON.stringify(result.manifest, null, 2) + '\n',
+  };
+
+  return out;
+}

package/libs/instance-factories/applications/templates/react-starter/package-json-generator.ts

@@ -0,0 +1,57 @@
+/**
+ * package.json generator for ReactAppStarter
+ *
+ * Deliberately does NOT include @specverse/runtime. The promise of
+ * Factory B is that the generated project is standalone — everything
+ * needed to render is emitted as local source.
+ */
+
+export interface PackageJsonGeneratorContext {
+  spec: {
+    metadata?: { name?: string };
+    name?: string;
+  };
+  manifest?: unknown;
+}
+
+export async function generate(context: PackageJsonGeneratorContext): Promise<string> {
+  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: string): string {
+  return s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'specverse-starter-app';
+}

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

@@ -0,0 +1,157 @@
+/**
+ * Regeneration safety for ReactAppStarter
+ *
+ * When realize runs Factory B, generated files can end up in two states:
+ *
+ *  1. Pristine — the file on disk is byte-identical to what we last
+ *     wrote. Safe to overwrite with a new version.
+ *
+ *  2. User-edited — the user modified the file. We must NOT clobber
+ *     their work.
+ *
+ * The mechanism is an SHA-256 hash recorded per file in
+ * `.specverse-gen/hashes.json` at write time. At regeneration, we
+ * compare the on-disk hash against the recorded one. Mismatch → skip
+ * with a warning. Match → overwrite and update the hash.
+ *
+ * The factory orchestrator wraps realize's write calls through
+ * `reconcileWrites` below, which handles all three outcomes:
+ *  - brand-new file → write, record hash
+ *  - pristine existing → overwrite, update hash
+ *  - user-edited existing → skip, leave hash unchanged
+ */
+
+import { createHash } from 'crypto';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join, relative } from 'path';
+
+/** Relative path (from project root) → SHA-256 hex digest. */
+export type HashManifest = Record<string, string>;
+
+export const HASHES_DIR = '.specverse-gen';
+export const HASHES_FILE = 'hashes.json';
+
+export function sha256(s: string): string {
+  return createHash('sha256').update(s, 'utf8').digest('hex');
+}
+
+/**
+ * Load a `.specverse-gen/hashes.json` from the project root. Returns
+ * an empty manifest if the file is missing or malformed — the
+ * calling convention is that a missing manifest means "no record of
+ * prior generation, treat everything as new."
+ */
+export function loadHashManifest(projectRoot: string): HashManifest {
+  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: HashManifest = {};
+      for (const [k, v] of Object.entries(parsed)) {
+        if (typeof v === 'string') out[k] = v;
+      }
+      return out;
+    }
+  } catch {
+    // Malformed — treat as missing. Next generate pass will overwrite.
+  }
+  return {};
+}
+
+/** Write the manifest back to `.specverse-gen/hashes.json`. */
+export function saveHashManifest(projectRoot: string, manifest: HashManifest): void {
+  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');
+}
+
+export interface ReconcileResult {
+  /** Relative path → content for every file approved for writing. */
+  approvedWrites: Record<string, string>;
+  /** Files we skipped because the user edited them (or couldn't confirm origin). */
+  skipped: { path: string; reason: string }[];
+  /** The updated hash manifest reflecting all approved writes. */
+  manifest: HashManifest;
+}
+
+/**
+ * Pure-planning triage. For each proposed file, decides whether the
+ * write is safe:
+ *  - Path doesn't exist → APPROVE, record hash.
+ *  - Path exists + on-disk hash matches recorded hash → APPROVE
+ *    (pristine overwrite), update hash.
+ *  - Path exists + hash mismatch → SKIP (user-edited), preserve old
+ *    hash record.
+ *  - Path exists + no recorded hash → SKIP (cautious default).
+ *
+ * Reads the filesystem but doesn't write. Returns the approved writes
+ * as a map the caller can pass to the realize write pipeline.
+ */
+export function reconcileWrites(
+  projectRoot: string,
+  proposed: Record<string, string>,
+  prevManifest: HashManifest
+): ReconcileResult {
+  const manifest: HashManifest = { ...prevManifest };
+  const approvedWrites: Record<string, string> = {};
+  const skipped: { path: string; reason: string }[] = [];
+
+  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 — 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 };
+}
+
+/**
+ * Human-readable summary of a ReconcileResult. Used by the factory
+ * orchestrator to log after a run.
+ */
+export function summarize(result: ReconcileResult, projectRoot: string): string {
+  const lines: string[] = [];
+  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');
+}

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

@@ -0,0 +1,47 @@
+/**
+ * {{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';
+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();
+
+  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/libs/instance-factories/applications/templates/react-starter/skeletons/detail.tsx.template

@@ -0,0 +1,94 @@
+/**
+ * {{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';
+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();
+
+  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/libs/instance-factories/applications/templates/react-starter/skeletons/form.tsx.template

@@ -0,0 +1,114 @@
+/**
+ * {{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';
+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();
+
+  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>
+  );
+}