@specverse/engines 4.1.30 → 4.2.1

package/libs/instance-factories/applications/react-app-starter.yaml

@@ -0,0 +1,143 @@
+name: ReactAppStarter
+version: "1.0.0"
+category: view
+description: "Fully standalone React starter kit — pre-rendered view components the user can fork and extend. No @specverse/runtime dependency."
+
+metadata:
+  author: "SpecVerse Team"
+  license: "MIT"
+  tags: [react, vite, spa, frontend, starter, editable]
+  mode: starter
+
+compatibility:
+  specverse: ">=4.0.0"
+  node: ">=18.0.0"
+
+capabilities:
+  provides:
+    - "app.frontend"
+    - "ui.scaffolding"
+    - "ui.router"
+    - "ui.staticviews"
+    - "ui.staticforms"
+    - "ui.staticcomponents"
+  requires: []
+
+technology:
+  runtime: "browser"
+  language: "typescript"
+  framework: "react"
+  bundler: "vite"
+  version: "^18.2.0"
+
+dependencies:
+  # Runtime deps baked into the generated package.json.
+  # Deliberately no @specverse/runtime — the starter kit is
+  # standalone by design.
+  runtime:
+    - name: "react"
+      version: "^18.2.0"
+    - name: "react-dom"
+      version: "^18.2.0"
+    - name: "@tanstack/react-query"
+      version: "^5.0.0"
+
+  dev:
+    - name: "@types/react"
+      version: "^18.2.0"
+    - name: "@types/react-dom"
+      version: "^18.2.0"
+    - name: "typescript"
+      version: "^5.2.0"
+    - name: "vite"
+      version: "^6.0.0"
+    - name: "@vitejs/plugin-react"
+      version: "^4.2.0"
+    - name: "tailwindcss"
+      version: "^3.4.13"
+    - name: "postcss"
+      version: "^8.4.47"
+    - name: "autoprefixer"
+      version: "^10.4.20"
+
+codeTemplates:
+  # === Infrastructure reused from ReactAppRuntime ===
+  # Safe to share because these files don't embed any runtime-specific
+  # logic — just build config + entry points.
+  index-html:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/react/index-html-generator.ts"
+    outputPattern: "{frontendDir}/index.html"
+
+  main-tsx:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/react/main-tsx-generator.ts"
+    outputPattern: "{frontendDir}/src/main.tsx"
+
+  vite-config:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/react/vite-config-generator.ts"
+    outputPattern: "{frontendDir}/vite.config.ts"
+
+  tsconfig:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/react/tsconfig-generator.ts"
+    outputPattern: "{frontendDir}/tsconfig.json"
+
+  index-css:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/react/index-css-generator.ts"
+    outputPattern: "{frontendDir}/src/index.css"
+
+  gitignore:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/react/gitignore-generator.ts"
+    outputPattern: "{frontendDir}/.gitignore"
+
+  env-example:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/react/env-example-generator.ts"
+    outputPattern: "{frontendDir}/.env.example"
+
+  # API wiring — starter-specific. The starter's hooks inline their
+  # own fetch transport so there is NO apiClient.ts (the runtime
+  # apiClient imports runtime-only types that this factory doesn't
+  # emit). Users wanting a shared transport layer can add one by
+  # hand; the hooks file is intentionally small enough to edit.
+  use-api-hooks:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/react-starter/use-api-hooks-starter-generator.ts"
+    outputPattern: "{frontendDir}/src/hooks/useApi.ts"
+
+  api-types:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/react-starter/api-types-starter-generator.ts"
+    outputPattern: "{frontendDir}/src/types/api.ts"
+
+  # === Starter-specific: emitted view components + helpers + App + package.json ===
+  # The orchestrator returns a map of {relativePath: content} covering:
+  #   src/views/*.tsx         one per (model, view-type) pair
+  #   src/lib/entity-display.ts    FK→name helper (standalone source)
+  #   src/App.tsx             simple internal-routing shell
+  #   package.json            no @specverse/runtime dep
+  #   .specverse-gen/hashes.json  content hashes for regeneration safety
+  #
+  # Regeneration safety is internal to the orchestrator: user-edited
+  # files are omitted from the returned map (so realize never sees
+  # them), and the hash manifest's per-file entries are preserved for
+  # those skipped files so a later un-edit restores regenerability.
+  starter-output:
+    engine: typescript
+    generator: "libs/instance-factories/applications/templates/react-starter/orchestrator.ts"
+    outputPattern: "{frontendDir}/"
+
+configuration:
+  projectStructure: "monorepo"
+  frontendDir: "frontend"
+  backendDir: "backend"
+
+  vite:
+    port: 5173
+    host: "localhost"
+    proxy:
+      "/api": "http://localhost:3000"

package/libs/instance-factories/applications/templates/react/env-example-generator.ts

@@ -11,8 +11,30 @@ export default function generateEnvExample(context: TemplateContext): string {
   const pathConfig = getPathConfig(context);
   const defaultApiUrl = getApiBaseUrl(pathConfig);
 
-  return `# API Configuration
-# Base URL for backend API
+  return `# ─── Ports ────────────────────────────────────────────────────
+# Running more than one SpecVerse project at once? Each project reads
+# its own .env — copy this file to .env and bump the numbers so the
+# projects don't collide.
+#
+# Suggested ranges (shared across the ecosystem):
+#   3000-3049 : generated project backends (one per project)
+#   3050-3099 : app-demo per-spec runtime backends
+#   5173-5199 : vite frontends (one per project)
+#   9000+     : app-demo Server Manager
+
+# Backend (Fastify) port — read by \`npm run dev:backend\`.
+PORT=3000
+
+# Frontend (vite) port — read by \`npm run dev:frontend\`.
+VITE_PORT=5173
+
+# Frontend host — '0.0.0.0' if you want LAN access.
+VITE_HOST=localhost
+
+# ─── API wiring ────────────────────────────────────────────────
+# Base URL for backend API. Used by the generated apiClient AND by
+# vite's dev-server proxy (so /api and /ws requests from the browser
+# are forwarded to your backend). Keep this in sync with PORT.
 VITE_API_BASE_URL=${defaultApiUrl}
 
 # API Path Prefix

package/libs/instance-factories/applications/templates/react/vite-config-generator.ts

@@ -16,45 +16,66 @@ export default function generateViteConfig(context: TemplateContext): string {
   const apiBaseUrl = getApiBaseUrl(pathConfig);
   const apiProxy = configuration?.vite?.proxy?.['/api'] || apiBaseUrl;
 
-  return `import { defineConfig } from 'vite';
+  return `import { defineConfig, loadEnv } from 'vite';
 import react from '@vitejs/plugin-react';
 import path from 'path';
 
-// https://vitejs.dev/config/
-export default defineConfig({
-  plugins: [react()],
-  server: {
-    port: ${vitePort},
-    host: '${viteHost}',
-    proxy: {
-      '/api': {
-        target: '${apiProxy}',
-        changeOrigin: true,
-      },
-      // WebSocket proxy — the runtime's useEntitySync hook opens
-      // ws://<host>/ws to receive entity mutation events from the
-      // backend event bus. Without this proxy the socket tries to
-      // connect to the vite dev server on /ws and fails, forcing
-      // state-sync to fall back to React Query's refetchInterval
-      // polling (usable but slow).
-      '/ws': {
-        target: '${apiProxy.replace(/^http/, 'ws')}',
-        ws: true,
-        changeOrigin: true,
+/**
+ * Ports and proxy targets are env-overridable via this project's
+ * .env (and .env.local). Lets you run several SpecVerse projects
+ * side-by-side without port collisions:
+ *
+ *   # project-a/.env
+ *   PORT=3001
+ *   VITE_PORT=5174
+ *   VITE_API_BASE_URL=http://localhost:3001
+ *
+ *   # project-b/.env
+ *   PORT=3002
+ *   VITE_PORT=5175
+ *   VITE_API_BASE_URL=http://localhost:3002
+ */
+export default defineConfig(({ mode }) => {
+  const env = loadEnv(mode, process.cwd(), '');
+  const port = Number(env.VITE_PORT ?? ${vitePort});
+  const host = env.VITE_HOST ?? '${viteHost}';
+  const apiTarget = env.VITE_API_BASE_URL ?? '${apiProxy}';
+
+  return {
+    plugins: [react()],
+    server: {
+      port,
+      host,
+      proxy: {
+        '/api': {
+          target: apiTarget,
+          changeOrigin: true,
+        },
+        // WebSocket proxy — the runtime's useEntitySync hook opens
+        // ws://<host>/ws to receive entity mutation events from the
+        // backend event bus. Without this proxy the socket tries to
+        // connect to the vite dev server on /ws and fails, forcing
+        // state-sync to fall back to React Query's refetchInterval
+        // polling (usable but slow).
+        '/ws': {
+          target: apiTarget.replace(/^http/, 'ws'),
+          ws: true,
+          changeOrigin: true,
+        },
       },
     },
-  },
-  build: {
-    outDir: 'dist',
-    sourcemap: true,
-  },
-  resolve: {
-    alias: {
-      '@': path.resolve(__dirname, './src'),
+    build: {
+      outDir: 'dist',
+      sourcemap: true,
+    },
+    resolve: {
+      alias: {
+        '@': path.resolve(__dirname, './src'),
+      },
+      // Prevent React duplication when using local packages
+      dedupe: ['react', 'react-dom'],
     },
-    // Prevent React duplication when using local packages
-    dedupe: ['react', 'react-dom'],
-  },
+  };
 });
 `;
 }

package/libs/instance-factories/applications/templates/react-starter/README.md

@@ -0,0 +1,211 @@
+# ReactAppStarter — Emitter Architecture
+
+**Audience**: anyone touching the view emitter for Factory B (the "starter-kit" React factory).
+
+**Companion docs**:
+- `specverse-self/docs/guides/VIEW-RENDERING-ARCHITECTURE.md` (the "one pattern library, three consumers" design)
+- `specverse-self/docs/plans/2026-04-17-UNIFIED-VIEW-RENDERING.md` (the migration plan)
+
+---
+
+## The problem this solves
+
+Factory B emits a standalone React codebase. For every view in the inferred spec (dev defaults + user-defined views), it writes a `.tsx` file the user can read, fork, and edit. The generated code:
+
+- Has no `@specverse/runtime` dependency (fully standalone).
+- Is idiomatic React with typed props, hooks, event handlers — not a big static HTML blob.
+- Renders the **same** visual output as `@specverse/runtime` renders for the same spec (verified by Phase 3 parity test P3).
+
+The tension: "idiomatic React structure" wants hand-crafted JSX. "Same visual output as runtime" wants a single rendering authority. Strategy 3 resolves this by splitting *structure* (hand-written skeleton templates) from *interior* (canonical Tailwind adapter rendering).
+
+## The three pieces
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 1. view-emitter.ts  — orchestrator                          │
+│    Takes (viewSpec, modelSpec, expandedSpec) → .tsx string  │
+└──────────────┬───────────────────────────────┬──────────────┘
+               │                               │
+               ▼                               ▼
+┌──────────────────────────────┐  ┌─────────────────────────────────┐
+│ 2. skeletons/*.tsx.template  │  │ 3. html-to-jsx.ts  — transformer│
+│    One per view type:        │  │                                 │
+│      list.tsx.template       │  │    Converts Tailwind-HTML       │
+│      detail.tsx.template     │  │    strings from the runtime     │
+│      form.tsx.template       │  │    adapter into JSX-safe source │
+│      dashboard.tsx.template  │  │    (class→className, self-close,│
+│      + specialist types      │  │    brace escape, attribute map) │
+│                              │  │                                 │
+│    Each has a {{BODY}}       │  │    ~50-150 LoC, bounded scope   │
+│    placeholder the emitter   │  │                                 │
+│    fills with transformed    │  │                                 │
+│    JSX.                      │  │                                 │
+└──────────────────────────────┘  └─────────────────────────────────┘
+                                              ▲
+                                              │
+                                              │ renders body as HTML
+                                              │
+                        ┌─────────────────────┴──────────────────────┐
+                        │ @specverse/runtime/views/tailwind          │
+                        │  createUniversalTailwindAdapter()          │
+                        │  (the canonical build-time renderer —      │
+                        │   same code app-demo and Factory A         │
+                        │   transitively rely on at runtime)         │
+                        └────────────────────────────────────────────┘
+```
+
+## Data flow for ONE view
+
+Given an inferred `PostListView` in the expanded spec:
+
+1. **view-emitter.ts** receives `(view, model, expandedSpec)`.
+2. Picks the correct skeleton based on `view.type`: `skeletons/list.tsx.template`.
+3. Builds a render context for the pattern: `{ primaryModel: 'Post', modelSchemas: {...}, viewSpec: view, modelData: [] }` (empty data — structure only).
+4. Calls `createUniversalTailwindAdapter()` and renders the composite pattern's interior → HTML string.
+   Example output: `<table class="w-full ..."><thead><tr><th class="...">Title</th>...`.
+5. Passes that HTML through **html-to-jsx.ts** → JSX-safe source.
+   Example: `<table className="w-full ..."><thead><tr><th className="...">{/* data.map */}Title</th>...`.
+6. Substitutes `{{BODY}}` in the skeleton with the transformed JSX.
+7. Substitutes skeleton placeholders like `{{MODEL_NAME}}`, `{{PLURAL}}`, `{{PROPS_INTERFACE}}` with model-specific values.
+8. Returns the complete `.tsx` source string.
+
+The factory's realize pass calls this once per view, writes each to `frontend/src/views/{ViewName}.tsx`, updates `.specverse-gen/hashes.json`.
+
+## Why this split works
+
+- **Idiomatic outer structure** — skeletons are hand-written `.tsx.template` files, tweaked by the humans who maintain the factory. They define imports, props interfaces, hook placement, event wiring, loading states, empty states. Exactly what a human React author would write.
+- **Pattern-driven interior** — the actual markup (table header cells, row templates, form fields, badge styling) comes from the canonical Tailwind adapter. When runtime improves the pattern rendering, Factory B inherits the fix automatically — because the adapter is the single source.
+- **No full re-implementation** — we don't build a second renderer. The adapter already works for runtime; we reuse it at build time.
+
+## The html-to-jsx transformer — scope
+
+Input: HTML string with Tailwind classes. Single root element (always — the adapter always produces a containing element).
+
+Output: A JSX-safe source string that can be dropped between JSX tags.
+
+What it does:
+1. `class="..."` → `className="..."`
+2. Self-closing tags: `<img src="...">` → `<img src="..." />`
+3. Escape `{` and `}` in text content by wrapping in `{'{'}` / `{'}'}` when they appear outside attribute values.
+4. Convert `style="color: red"` to `style={{ color: 'red' }}`.
+5. Convert `for="..."` to `htmlFor="..."`.
+6. Strip any attributes that aren't valid in JSX.
+
+What it explicitly does NOT do:
+- Parse JavaScript inside the HTML (the adapter produces static HTML — no JS expressions).
+- Insert React hooks or event handlers — those live in the skeleton, not the interior.
+- Handle SVG / MathML nuances — only HTML+Tailwind.
+
+Test coverage target: feed the transformer 50 pre-captured HTML snippets from the canonical adapter output, assert the JSX output parses as valid TSX via `typescript.transpileModule`.
+
+## Skeleton template format
+
+A skeleton is a `.tsx.template` file — syntactically valid TypeScript with substitution markers. Example (sketch for `list.tsx.template`):
+
+```tsx
+/**
+ * {{MODEL_NAME}}ListView — generated by @specverse/realize (ReactAppStarter)
+ *
+ * Safe to edit. Edits are preserved across regeneration (content-hashed).
+ * Regenerate with `spv realize` or, if this file was edited, delete the
+ * file first to opt back into regeneration.
+ */
+import { useState, useMemo } from 'react';
+import { use{{PLURAL_MODEL}}Query, useDelete{{MODEL_NAME}}Mutation } from '../hooks/useApi';
+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();
+  const [searchTerm, setSearchTerm] = useState('');
+
+  const filtered = useMemo(
+    () => items.filter(item =>
+      Object.values(item).some(v => String(v).toLowerCase().includes(searchTerm.toLowerCase()))
+    ),
+    [items, searchTerm]
+  );
+
+  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>;
+
+  return (
+    <div className="p-6 space-y-4">
+      <div className="flex justify-between items-center">
+        <input
+          type="search"
+          placeholder="Search {{PLURAL_LOWER}}…"
+          value={searchTerm}
+          onChange={e => setSearchTerm(e.target.value)}
+          className="rounded border px-3 py-2 w-64"
+        />
+        <button
+          onClick={onCreate}
+          className="rounded bg-blue-600 px-4 py-2 text-white hover:bg-blue-700"
+        >
+          + New {{MODEL_NAME}}
+        </button>
+      </div>
+
+      {/* {{BODY}} — pattern-rendered table interior, JSX-transformed */}
+      {{BODY}}
+
+      {filtered.length === 0 && (
+        <div className="p-8 text-center text-gray-400">No {{PLURAL_LOWER}} yet.</div>
+      )}
+    </div>
+  );
+}
+```
+
+Substitution contract:
+- `{{MODEL_NAME}}` — PascalCase model name (e.g., `Post`).
+- `{{PLURAL_MODEL}}` — PascalCase plural (e.g., `Posts`).
+- `{{PLURAL_LOWER}}` — lowercase plural (e.g., `posts`).
+- `{{BODY}}` — exactly one substitution per skeleton, where the pattern-rendered interior goes.
+
+Substitution is plain string replacement — no template expression evaluation.
+
+## File placement
+
+```
+engines/libs/instance-factories/applications/templates/react-starter/
+├── README.md                        # this file
+├── view-emitter.ts                  # orchestrator (step 1)
+├── html-to-jsx.ts                   # transformer (step 3)
+├── skeletons/
+│   ├── list.tsx.template            # list view
+│   ├── detail.tsx.template          # detail view
+│   ├── form.tsx.template            # form view (Phase 2e)
+│   ├── dashboard.tsx.template       # dashboard (Phase 2e)
+│   └── specialist-*.tsx.template    # board/timeline/calendar (Phase 2e)
+└── __tests__/
+    ├── html-to-jsx.test.ts          # transformer unit tests
+    └── view-emitter.test.ts         # end-to-end: (spec, view) → valid TSX
+```
+
+## Build order (Phase 2a in the migration plan)
+
+1. Implement `html-to-jsx.ts` first (smallest, most testable, standalone).
+2. Write `list.tsx.template` (one view type; production-quality).
+3. Implement `view-emitter.ts` — orchestrator that wires html-to-jsx + canonical Tailwind adapter + skeleton.
+4. Integration test: take a reference spec with one model + its list view, emit, assert the `.tsx` source parses and its JSX matches the expected shape.
+5. Only after list works end-to-end: template out to detail + form + dashboard.
+
+## Open questions (inside Phase 2a)
+
+1. **Where do per-model hooks come from?** `use{{PLURAL_MODEL}}Query` and `useDelete{{MODEL_NAME}}Mutation` in the skeleton presume a generated hooks file (`src/hooks/useApi.ts`) that provides them. `ReactAppRuntime` already generates this file via `use-api-hooks-generator.ts` — Factory B should reuse that generator (shared between both factories as called out in the migration plan).
+2. **How does the skeleton address auto-generated fields (id, createdAt, etc.)?** The view should skip them in the table/form. `isAutoGeneratedField()` logic needs to be available in the generated output. Plan: emit a `src/lib/field-helpers.ts` alongside the views (inlined from the pattern library's logic, same way the runtime has it).
+3. **What happens when the view spec has `uiComponents` that the pattern library doesn't recognize?** Runtime gracefully falls back to a default table. Factory B should do the same — same fallback logic, same output.
+4. **Should the skeleton expose a slot for user-added React nodes (e.g. `<Children />` or a `prepend` prop)?** Useful for extensibility without forcing users to edit the generated file. Defer to v2 of the emitter — start with fixed skeletons.
+
+## Non-goals
+
+- No JSX AST parsing or manipulation. `html-to-jsx.ts` is a string transformer, not a compiler.
+- No server-side rendering of the React components. The emitter outputs source files; the user's Vite build bundles them.
+- No runtime customization of skeletons. A project that wants different skeletons forks the factory or the generated code.

package/libs/instance-factories/applications/templates/react-starter/__tests__/dashboard-body-composer.test.ts

@@ -0,0 +1,153 @@
+import { describe, it, expect } from 'vitest';
+import * as ts from 'typescript';
+import { composeDashboardBody } from '../dashboard-body-composer.js';
+import { emitView, type EmitContext, type ModelSpec } from '../view-emitter.js';
+
+function makeContext(overrides: Partial<EmitContext> = {}): EmitContext {
+  const post: ModelSpec = {
+    name: 'Post',
+    attributes: {
+      id: { type: 'UUID', required: true },
+      title: { type: 'String', required: true },
+      body: { type: 'Text', required: false },
+      status: { type: 'String', required: false, values: ['draft', 'live', 'archived'] },
+      createdAt: { type: 'DateTime', required: false },
+    },
+  };
+
+  return {
+    view: { type: 'dashboard', model: 'Post' },
+    viewName: 'PostDashboardView',
+    model: post,
+    modelSchemas: { Post: post },
+    renderBody: composeDashboardBody,
+    ...overrides,
+  };
+}
+
+function assertValidTsx(source: string, label: string): void {
+  const result = ts.transpileModule(source, {
+    compilerOptions: {
+      jsx: ts.JsxEmit.Preserve,
+      target: ts.ScriptTarget.ES2022,
+      module: ts.ModuleKind.ESNext,
+      moduleResolution: ts.ModuleResolutionKind.Bundler,
+      strict: false,
+    },
+    reportDiagnostics: true,
+  });
+  const errors = result.diagnostics?.filter(d => d.category === ts.DiagnosticCategory.Error) ?? [];
+  if (errors.length > 0) {
+    const message = errors
+      .map(d => ts.flattenDiagnosticMessageText(d.messageText, '\n'))
+      .join('\n');
+    throw new Error(`${label} failed to parse as TSX:\n${message}\n\n--- source ---\n${source}`);
+  }
+}
+
+describe('composeDashboardBody — metrics row', () => {
+  it('emits a total-count card', () => {
+    const body = composeDashboardBody(makeContext());
+    expect(body).toContain('Total posts');
+    expect(body).toContain('{items.length}');
+  });
+
+  it('emits a per-value breakdown card for each enum value when a small enum exists', () => {
+    const body = composeDashboardBody(makeContext());
+    // The `status` attribute has 3 values. Each gets a card.
+    expect(body).toContain('Status: Draft');
+    expect(body).toContain('Status: Live');
+    expect(body).toContain('Status: Archived');
+    // Filter expressions for counts
+    expect(body).toContain(`i.status === "draft"`);
+    expect(body).toContain(`i.status === "live"`);
+    expect(body).toContain(`i.status === "archived"`);
+  });
+
+  it('falls back to a placeholder card when no enum fields exist', () => {
+    const plain: ModelSpec = {
+      name: 'Plain',
+      attributes: {
+        id: { type: 'UUID' },
+        name: { type: 'String' },
+      },
+    };
+    const body = composeDashboardBody(makeContext({
+      model: plain,
+      view: { type: 'dashboard', model: 'Plain' },
+      viewName: 'PlainDashboardView',
+      modelSchemas: { Plain: plain },
+    }));
+    expect(body).toContain('Add a metric here');
+  });
+
+  it('skips large enums (> 6 values) to avoid card sprawl', () => {
+    const huge: ModelSpec = {
+      name: 'Huge',
+      attributes: {
+        id: { type: 'UUID' },
+        tier: {
+          type: 'String',
+          values: ['s', 'a', 'b', 'c', 'd', 'e', 'f'], // 7 → should be skipped
+        },
+      },
+    };
+    const body = composeDashboardBody(makeContext({
+      model: huge,
+      view: { type: 'dashboard', model: 'Huge' },
+      viewName: 'HugeDashboardView',
+      modelSchemas: { Huge: huge },
+    }));
+    expect(body).not.toContain('Tier: S');
+    expect(body).toContain('Add a metric here');  // placeholder kicked in
+  });
+});
+
+describe('composeDashboardBody — recent preview', () => {
+  it('emits a table with business-field columns (metadata excluded)', () => {
+    const body = composeDashboardBody(makeContext());
+    expect(body).toContain('Recent Posts');
+    expect(body).toContain('>Title<');
+    expect(body).toContain('>Body<');
+    expect(body).toContain('>Status<');
+    // metadata excluded
+    expect(body).not.toContain('>Id<');
+    expect(body).not.toContain('>Created At<');
+  });
+
+  it('maps over `preview` (from the skeleton), not `items`', () => {
+    const body = composeDashboardBody(makeContext());
+    expect(body).toContain('{preview.map((item, idx) =>');
+  });
+
+  it('handles empty-list state with a spanning row', () => {
+    const body = composeDashboardBody(makeContext());
+    expect(body).toContain('{preview.length === 0 && (');
+    expect(body).toContain('No records yet.');
+  });
+});
+
+describe('composeDashboardBody — TODO comments', () => {
+  it('flags the extension point for aggregation metrics', () => {
+    const body = composeDashboardBody(makeContext());
+    expect(body).toContain('TODO: add aggregation metrics');
+  });
+});
+
+describe('emitView wired to composeDashboardBody — end-to-end', () => {
+  it('produces a complete PostDashboardView.tsx that parses', () => {
+    const source = emitView(makeContext());
+    assertValidTsx(source, 'PostDashboardView');
+  });
+
+  it('wires the skeleton: component, hooks, preview memo, body', () => {
+    const source = emitView(makeContext());
+    expect(source).toContain('export function PostDashboardView');
+    expect(source).toContain('usePostsQuery');
+    expect(source).toContain('Post dashboard');
+    expect(source).toContain('items.slice(0, previewLimit)');
+    expect(source).toContain('Total posts');
+    expect(source).toContain('Recent Posts');
+    expect(source).not.toMatch(/\{\{[A-Z_]+\}\}/);
+  });
+});