@specverse/engines 4.1.22 → 4.1.24

package/dist/inference/ui-contracts/rules/nav-has-model-entries.js

@@ -0,0 +1,29 @@
+/**
+ * Rule: nav-has-model-entries
+ *
+ * For every model declared in the spec, assert that the runtime UI
+ * exposes a visible reference to the model (nav entry, sidebar link,
+ * dashboard card — any of them count). v1 uses a loose "text appears
+ * on the page" assertion; a stricter ARIA-role variant can come
+ * later once the runtime standardizes its nav component's semantics.
+ *
+ * One TestCase per model.
+ *
+ * This is the most important rule: if the runtime can't even show
+ * the model name after initial render, everything else downstream is
+ * certainly broken. It's also the cheapest — one navigation, one
+ * text query per model.
+ */
+export const RULE_ID = 'nav-has-model-entries';
+export const navHasModelEntries = (spec) => {
+    return spec.models.map(model => ({
+        ruleId: RULE_ID,
+        specElement: model.name,
+        name: `[${RULE_ID}] ${model.name} is visible in the nav`,
+        steps: [
+            { action: 'bootRuntime' },
+            { action: 'expectNavHasModel', modelName: model.name },
+        ],
+    }));
+};
+//# sourceMappingURL=nav-has-model-entries.js.map

package/dist/inference/ui-contracts/rules/nav-has-model-entries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nav-has-model-entries.js","sourceRoot":"","sources":["../../../../src/inference/ui-contracts/rules/nav-has-model-entries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,MAAM,CAAC,MAAM,OAAO,GAAG,uBAAuB,CAAC;AAE/C,MAAM,CAAC,MAAM,kBAAkB,GAAmB,CAAC,IAAoB,EAAc,EAAE;IACrF,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC/B,MAAM,EAAE,OAAO;QACf,WAAW,EAAE,KAAK,CAAC,IAAI;QACvB,IAAI,EAAE,IAAI,OAAO,KAAK,KAAK,CAAC,IAAI,wBAAwB;QACxD,KAAK,EAAE;YACL,EAAE,MAAM,EAAE,aAAa,EAAE;YACzB,EAAE,MAAM,EAAE,mBAAmB,EAAE,SAAS,EAAE,KAAK,CAAC,IAAI,EAAE;SACvD;KACF,CAAC,CAAC,CAAC;AACN,CAAC,CAAC"}

package/dist/inference/ui-contracts/test-case-types.d.ts

@@ -0,0 +1,135 @@
+/**
+ * TestCase — declarative description of a UI contract test.
+ *
+ * Rules (pure functions) produce TestCase[]. The translator renders
+ * each TestCase into a Playwright `.spec.ts` file that imports helpers
+ * from `@specverse/runtime/test-harness`. Neither rules nor test cases
+ * know anything about React Query, cache invalidation, or any
+ * implementation detail — they speak only spec language.
+ *
+ * v1 steps cover navigation + assertion. Later phases add create /
+ * delete / evolve / expect-absent for state-sync rules.
+ */
+export type TestStep = {
+    action: 'bootRuntime';
+} | {
+    action: 'expectNavHasModel';
+    modelName: string;
+} | {
+    action: 'navigateToModel';
+    modelName: string;
+} | {
+    action: 'navigateToModelForm';
+    modelName: string;
+} | {
+    action: 'navigateToModelDetail';
+    modelName: string;
+} | {
+    action: 'expectViewRenders';
+} | {
+    action: 'expectListColumn';
+    modelName: string;
+    attributeName: string;
+} | {
+    action: 'expectFormInput';
+    modelName: string;
+    attributeName: string;
+    required?: boolean;
+} | {
+    action: 'expectLifecycleState';
+    modelName: string;
+    stateName: string;
+} | {
+    action: 'expectRelationshipSection';
+    modelName: string;
+    relationshipName: string;
+} | {
+    action: 'expectActionButton';
+    modelName: string;
+    actionLabel: string;
+} | {
+    action: 'createEntity';
+    modelName: string;
+    data: Record<string, unknown>;
+    bindAs?: string;
+    uniqueField?: string;
+} | {
+    action: 'deleteEntity';
+    modelName: string;
+    idExpr: string;
+} | {
+    action: 'evolveEntity';
+    modelName: string;
+    idExpr: string;
+    targetState: string;
+} | {
+    action: 'expectEntityInList';
+    modelName: string;
+    displayValue?: string;
+    displayExpr?: string;
+} | {
+    action: 'expectEntityAbsent';
+    modelName: string;
+    displayValue?: string;
+    displayExpr?: string;
+};
+export interface TestCase {
+    /** The rule that produced this test case. Used in test names for attribution. */
+    ruleId: string;
+    /** The spec element the case applies to (e.g. 'Poll', 'PollController.delete'). */
+    specElement: string;
+    /** Full test name — shown by Playwright reporter. */
+    name: string;
+    /** Ordered sequence of actions/assertions. */
+    steps: TestStep[];
+}
+/**
+ * A rule is a pure function from a normalized spec to a list of test
+ * cases. Rules never touch the filesystem, the network, or any mutable
+ * state — they just describe what should be tested.
+ */
+export type UiContractRule = (spec: NormalizedSpec) => TestCase[];
+/**
+ * Minimal normalized spec shape the rules operate on. The realize
+ * pipeline converts raw spec output into this shape before running
+ * rules. Kept deliberately small — rules grow their own helpers as
+ * they need richer data.
+ */
+export interface NormalizedSpec {
+    models: ModelInfo[];
+    controllers?: ControllerInfo[];
+    services?: ServiceInfo[];
+    views?: ViewInfo[];
+}
+export interface ModelInfo {
+    name: string;
+    attributes?: AttributeInfo[];
+    lifecycles?: Record<string, unknown>;
+    relationships?: RelationshipInfo[];
+}
+export interface AttributeInfo {
+    name: string;
+    type?: string;
+    required?: boolean;
+    category?: 'business' | 'metadata' | 'relationship';
+}
+export interface RelationshipInfo {
+    name: string;
+    type: string;
+    target?: string;
+}
+export interface ControllerInfo {
+    name: string;
+    model?: string;
+    cured?: Record<string, unknown>;
+}
+export interface ServiceInfo {
+    name: string;
+    operations?: Record<string, unknown>;
+}
+export interface ViewInfo {
+    name: string;
+    type: string;
+    model?: string;
+}
+//# sourceMappingURL=test-case-types.d.ts.map

package/dist/inference/ui-contracts/test-case-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-case-types.d.ts","sourceRoot":"","sources":["../../../src/inference/ui-contracts/test-case-types.ts"],"names":[],"mappings":"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"}

package/dist/inference/ui-contracts/test-case-types.js

@@ -0,0 +1,14 @@
+/**
+ * TestCase — declarative description of a UI contract test.
+ *
+ * Rules (pure functions) produce TestCase[]. The translator renders
+ * each TestCase into a Playwright `.spec.ts` file that imports helpers
+ * from `@specverse/runtime/test-harness`. Neither rules nor test cases
+ * know anything about React Query, cache invalidation, or any
+ * implementation detail — they speak only spec language.
+ *
+ * v1 steps cover navigation + assertion. Later phases add create /
+ * delete / evolve / expect-absent for state-sync rules.
+ */
+export {};
+//# sourceMappingURL=test-case-types.js.map

package/dist/inference/ui-contracts/test-case-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-case-types.js","sourceRoot":"","sources":["../../../src/inference/ui-contracts/test-case-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/inference/ui-contracts/translator.d.ts

@@ -0,0 +1,17 @@
+/**
+ * TestCase → Playwright .spec.ts translator.
+ *
+ * Renders a list of TestCase objects into a single Playwright spec
+ * file. The output file imports from `@specverse/runtime/test-harness`
+ * and nothing else from the runtime — all logic lives in the harness
+ * helpers. The translator is intentionally dumb: each step maps to a
+ * helper call, nothing more.
+ */
+import type { TestCase } from './test-case-types.js';
+/**
+ * Render a full `.spec.ts` file for one or more test cases sharing
+ * the same rule. One file per rule keeps failures easy to attribute
+ * and lets `npx playwright test` filter by rule ID via file glob.
+ */
+export declare function renderSpecFile(ruleId: string, testCases: TestCase[]): string;
+//# sourceMappingURL=translator.d.ts.map

package/dist/inference/ui-contracts/translator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translator.d.ts","sourceRoot":"","sources":["../../../src/inference/ui-contracts/translator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAY,MAAM,sBAAsB,CAAC;AAuG/D;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,MAAM,CA6B5E"}

package/dist/inference/ui-contracts/translator.js

@@ -0,0 +1,142 @@
+/**
+ * TestCase → Playwright .spec.ts translator.
+ *
+ * Renders a list of TestCase objects into a single Playwright spec
+ * file. The output file imports from `@specverse/runtime/test-harness`
+ * and nothing else from the runtime — all logic lives in the harness
+ * helpers. The translator is intentionally dumb: each step maps to a
+ * helper call, nothing more.
+ */
+/**
+ * Render a single step as a line of test body code.
+ */
+function renderStep(step) {
+    switch (step.action) {
+        case 'bootRuntime':
+            // Assign `page` once per test body. Multiple bootRuntime steps
+            // inside one test aren't supported and would shadow the binding.
+            return `  const { page } = await bootRuntime(browser);`;
+        case 'expectNavHasModel':
+            return `  await expectNavHasModel(page, ${JSON.stringify(step.modelName)});`;
+        case 'navigateToModel':
+            return `  await navigateToModel(page, ${JSON.stringify(step.modelName)});`;
+        case 'navigateToModelForm':
+            return `  await navigateToModelForm(page, ${JSON.stringify(step.modelName)});`;
+        case 'navigateToModelDetail':
+            return `  await navigateToModelDetail(page, ${JSON.stringify(step.modelName)});`;
+        case 'expectViewRenders':
+            return `  await expectViewRenders(page);`;
+        case 'expectListColumn':
+            return `  await expectListColumn(page, ${JSON.stringify(step.modelName)}, ${JSON.stringify(step.attributeName)});`;
+        case 'expectFormInput': {
+            const opts = step.required ? `, { required: true }` : ``;
+            return `  await expectFormInput(page, ${JSON.stringify(step.modelName)}, ${JSON.stringify(step.attributeName)}${opts});`;
+        }
+        case 'expectLifecycleState':
+            return `  await expectLifecycleState(page, ${JSON.stringify(step.modelName)}, ${JSON.stringify(step.stateName)});`;
+        case 'expectRelationshipSection':
+            return `  await expectRelationshipSection(page, ${JSON.stringify(step.modelName)}, ${JSON.stringify(step.relationshipName)});`;
+        case 'expectActionButton':
+            return `  await expectActionButton(page, ${JSON.stringify(step.modelName)}, ${JSON.stringify(step.actionLabel)});`;
+        case 'createEntity': {
+            const varName = step.bindAs || 'created';
+            const dataLit = JSON.stringify(step.data);
+            const optsLit = step.uniqueField
+                ? `, { uniqueField: ${JSON.stringify(step.uniqueField)} }`
+                : '';
+            return `  const ${varName} = await createEntity(page, ${JSON.stringify(step.modelName)}, ${dataLit}${optsLit});`;
+        }
+        case 'deleteEntity':
+            return `  await deleteEntity(page, ${JSON.stringify(step.modelName)}, ${step.idExpr});`;
+        case 'evolveEntity':
+            return `  await evolveEntity(page, ${JSON.stringify(step.modelName)}, ${step.idExpr}, ${JSON.stringify(step.targetState)});`;
+        case 'expectEntityInList': {
+            const display = step.displayExpr ?? JSON.stringify(step.displayValue ?? '');
+            return `  await expectEntityInList(page, ${JSON.stringify(step.modelName)}, ${display});`;
+        }
+        case 'expectEntityAbsent': {
+            const display = step.displayExpr ?? JSON.stringify(step.displayValue ?? '');
+            return `  await expectEntityAbsent(page, ${JSON.stringify(step.modelName)}, ${display});`;
+        }
+        default: {
+            const _exhaustive = step;
+            throw new Error(`translator: unknown step action: ${JSON.stringify(_exhaustive)}`);
+        }
+    }
+}
+/**
+ * Collect the set of harness helpers a test case depends on so the
+ * import list only contains what's actually used.
+ */
+function helpersFor(step) {
+    switch (step.action) {
+        case 'bootRuntime':
+            return ['bootRuntime'];
+        case 'expectNavHasModel':
+            return ['expectNavHasModel'];
+        case 'navigateToModel':
+            return ['navigateToModel'];
+        case 'navigateToModelForm':
+            return ['navigateToModelForm'];
+        case 'navigateToModelDetail':
+            return ['navigateToModelDetail'];
+        case 'expectViewRenders':
+            return ['expectViewRenders'];
+        case 'expectListColumn':
+            return ['expectListColumn'];
+        case 'expectFormInput':
+            return ['expectFormInput'];
+        case 'expectLifecycleState':
+            return ['expectLifecycleState'];
+        case 'expectRelationshipSection':
+            return ['expectRelationshipSection'];
+        case 'expectActionButton':
+            return ['expectActionButton'];
+        case 'createEntity':
+            return ['createEntity'];
+        case 'deleteEntity':
+            return ['deleteEntity'];
+        case 'evolveEntity':
+            return ['evolveEntity'];
+        case 'expectEntityInList':
+            return ['expectEntityInList'];
+        case 'expectEntityAbsent':
+            return ['expectEntityAbsent'];
+        default:
+            return [];
+    }
+}
+/**
+ * Render a full `.spec.ts` file for one or more test cases sharing
+ * the same rule. One file per rule keeps failures easy to attribute
+ * and lets `npx playwright test` filter by rule ID via file glob.
+ */
+export function renderSpecFile(ruleId, testCases) {
+    const helpers = new Set();
+    for (const tc of testCases) {
+        for (const step of tc.steps) {
+            for (const h of helpersFor(step))
+                helpers.add(h);
+        }
+    }
+    const importList = [...helpers].sort().join(', ');
+    const header = `/**
+ * Auto-generated UI contract test file.
+ * Rule: ${ruleId}
+ * DO NOT EDIT — regenerated every \`spv realize\` run. Hand edits are
+ * lost on the next regenerate. Change the rule or the spec instead.
+ */
+
+import { test } from '@playwright/test';
+import { ${importList} } from '@specverse/runtime/test-harness';
+`;
+    const body = testCases.map(tc => {
+        const stepLines = tc.steps.map(renderStep).join('\n');
+        return `
+test(${JSON.stringify(tc.name)}, async ({ browser }) => {
+${stepLines}
+});`;
+    }).join('\n');
+    return header + body + '\n';
+}
+//# sourceMappingURL=translator.js.map

package/dist/inference/ui-contracts/translator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"translator.js","sourceRoot":"","sources":["../../../src/inference/ui-contracts/translator.ts"],"names":[],"mappings":"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"}

package/dist/libs/instance-factories/applications/templates/react/api-client-generator.js

@@ -43,9 +43,12 @@ export const WS_URL = apiUrl
   : \`\${window.location.protocol === 'https:' ? 'wss:' : 'ws:'}/\${window.location.host}/ws\`;
 
 /**
- * Generic API request helper
+ * Generic API request helper \u2014 exported so view components can
+ * use it as a drop-in replacement for raw fetch calls. Always
+ * routes through this module so the conformance check
+ * \`no-raw-fetch-in-views\` stays green.
  */
-async function apiRequest<T = any>(
+export async function apiRequest<T = any>(
   method: string,
   path: string,
   body: any = null

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

@@ -21,6 +21,17 @@ export default defineConfig({
         target: '${apiProxy}',
         changeOrigin: true,
       },
+      // WebSocket proxy \u2014 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,
+      },
     },
   },
   build: {

package/dist/libs/instance-factories/scaffolding/templates/generic/package-json-generator.js

@@ -29,6 +29,13 @@ function generatePackageJson(context) {
       "test": "npm test --workspaces",
       "test:backend": `npm test --workspace=${backendDir}`,
       "test:frontend": `npm test --workspace=${frontendDir}`,
+      // UI contract tests — auto-generated from spec inference rules.
+      // Assumes backend + frontend are already running (see docs/proposals/UI-CONTRACT-INFERENCE.md).
+      "test:contract": "playwright test --config=playwright.contract.config.ts",
+      // Implementation conformance — static grep-level checks that
+      // verify the runtime implementation has no escape hatches
+      // violating the design contract. Fast (millis), no browser.
+      "test:conformance": "node scripts/test-conformance.mjs",
       // Database management (backend)
       "db:setup": `npm run db:setup --workspace=${backendDir}`,
       "db:generate": `npm run db:generate --workspace=${backendDir}`,
@@ -39,6 +46,9 @@ function generatePackageJson(context) {
       "lint": "npm run lint --workspaces",
       "lint:fix": "npm run lint:fix --workspaces"
     };
+    pkg.devDependencies = {
+      "@playwright/test": "^1.40.0"
+    };
   } else {
     pkg.scripts = {
       ...aggregated.scripts,

package/dist/libs/instance-factories/views/templates/react/components-generator.js

@@ -135,13 +135,14 @@ function pluralize(s) {
 function generateListView(name, model, lower, plural, api, classified, belongsTo, lifecycle, view) {
   const displayCols = classified.business.slice(0, 5);
   const statusField = lifecycle?.statusField || classified.lifecycle[0]?.name;
+  const apiPath = api.replace(/^\/api/, "");
   const relFetches = belongsTo.map((r) => {
     const tLower = r.target.charAt(0).toLowerCase() + r.target.slice(1);
     return `  const [${tLower}Map, set${r.target}Map] = useState<Record<string, any>>({});`;
   }).join("\n");
   const relEffects = belongsTo.map((r) => {
     const tLower = r.target.charAt(0).toLowerCase() + r.target.slice(1);
-    return `    fetch('/api/${tLower}s').then(r => r.json()).then(data => {
+    return `    apiRequest('GET', '/${tLower}s').then(data => {
       if (Array.isArray(data)) {
         const m: Record<string, any> = {};
         data.forEach(e => { m[e.id] = e; });
@@ -156,6 +157,7 @@ function generateListView(name, model, lower, plural, api, classified, belongsTo
   });
   return `import { useState, useEffect } from 'react';
 import { Link } from 'react-router-dom';
+import { apiRequest } from '../lib/apiClient';
 import { getEntityDisplayName } from '../lib/field-helpers';
 import { formatValue, formatDate, StatusBadge } from '../lib/view-helpers';
 
@@ -165,7 +167,7 @@ function ${name}() {
 ${relFetches}
 
   useEffect(() => {
-    fetch('${api}').then(r => r.json()).then(data => {
+    apiRequest('GET', '${apiPath}').then(data => {
       setItems(Array.isArray(data) ? data : []);
       setLoading(false);
     }).catch(() => setLoading(false));
@@ -228,6 +230,7 @@ export default ${name};
 }
 function generateDetailView(name, model, lower, plural, api, classified, belongsTo, hasMany, lifecycle, view) {
   const statusField = lifecycle?.statusField || classified.lifecycle[0]?.name;
+  const apiPath = api.replace(/^\/api/, "");
   const relFetches = belongsTo.map((r) => {
     const tLower = r.target.charAt(0).toLowerCase() + r.target.slice(1);
     return `  const [${tLower}Ref, set${r.target}Ref] = useState<any>(null);`;
@@ -235,7 +238,7 @@ function generateDetailView(name, model, lower, plural, api, classified, belongs
   const relEffects = belongsTo.map((r) => {
     const tLower = r.target.charAt(0).toLowerCase() + r.target.slice(1);
     const fk = `${r.name}_id`;
-    return `      if (data.${fk}) fetch(\`/api/${tLower}s/\${data.${fk}}\`).then(r => r.json()).then(d => set${r.target}Ref(d)).catch(() => {});`;
+    return `      if (data.${fk}) apiRequest('GET', \`/${tLower}s/\${data.${fk}}\`).then(d => set${r.target}Ref(d)).catch(() => {});`;
   }).join("\n");
   const hasManyFetches = hasMany.map((r) => {
     const tLower = r.target.charAt(0).toLowerCase() + r.target.slice(1);
@@ -243,10 +246,11 @@ function generateDetailView(name, model, lower, plural, api, classified, belongs
   }).join("\n");
   const hasManyEffects = hasMany.map((r) => {
     const tLower = r.target.charAt(0).toLowerCase() + r.target.slice(1);
-    return `      fetch(\`/api/${tLower}s?${lower}Id=\${data.id}\`).then(r => r.json()).then(d => set${capitalize(r.name)}Items(Array.isArray(d) ? d : [])).catch(() => {});`;
+    return `      apiRequest('GET', \`/${tLower}s?${lower}Id=\${data.id}\`).then(d => set${capitalize(r.name)}Items(Array.isArray(d) ? d : [])).catch(() => {});`;
   }).join("\n");
   return `import { useState, useEffect } from 'react';
 import { Link, useSearchParams, useNavigate } from 'react-router-dom';
+import { apiRequest } from '../lib/apiClient';
 import { getEntityDisplayName } from '../lib/field-helpers';
 import { formatValue, formatDate, StatusBadge } from '../lib/view-helpers';
 
@@ -261,7 +265,7 @@ ${hasManyFetches}
 
   useEffect(() => {
     if (!id) { setLoading(false); return; }
-    fetch(\`${api}/\${id}\`).then(r => r.ok ? r.json() : null).then(data => {
+    apiRequest('GET', \`${apiPath}/\${id}\`).then(data => {
       setItem(data);
       setLoading(false);
       if (data) {
@@ -276,7 +280,7 @@ ${hasManyEffects}
 
   const handleDelete = async () => {
     if (!confirm('Delete this ${lower}?')) return;
-    await fetch(\`${api}/\${id}\`, { method: 'DELETE' });
+    await apiRequest('DELETE', \`${apiPath}/\${id}\`);
     navigate('/${lower}list');
   };
 
@@ -358,12 +362,13 @@ export default ${name};
 function generateFormView(name, model, lower, plural, api, classified, belongsTo, lifecycle, view) {
   const editableFields = [...classified.business, ...classified.lifecycle];
   const statusField = lifecycle?.statusField;
+  const apiPath = api.replace(/^\/api/, "");
   const relStates = belongsTo.map((r) => {
     return `  const [${r.target.charAt(0).toLowerCase() + r.target.slice(1)}Options, set${r.target}Options] = useState<any[]>([]);`;
   }).join("\n");
   const relEffects = belongsTo.map((r) => {
     const tLower = r.target.charAt(0).toLowerCase() + r.target.slice(1);
-    return `    fetch('/api/${tLower}s').then(r => r.json()).then(d => set${r.target}Options(Array.isArray(d) ? d : [])).catch(() => {});`;
+    return `    apiRequest('GET', '/${tLower}s').then(d => set${r.target}Options(Array.isArray(d) ? d : [])).catch(() => {});`;
   }).join("\n");
   function inputForField(attr) {
     const { name: n, type, required, values } = attr;
@@ -390,6 +395,7 @@ ${lifecycle.states.map((s) => `          <option value="${s}">${s.replace(/[_-]/
   }
   return `import { useState, useEffect } from 'react';
 import { useSearchParams, useNavigate } from 'react-router-dom';
+import { apiRequest } from '../lib/apiClient';
 import { getEntityDisplayName } from '../lib/field-helpers';
 
 function ${name}() {
@@ -403,7 +409,7 @@ ${relStates}
 
   useEffect(() => {
     if (editId) {
-      fetch(\`${api}/\${editId}\`).then(r => r.json()).then(data => setForm(data || {})).catch(() => {});
+      apiRequest('GET', \`${apiPath}/\${editId}\`).then(data => setForm(data || {})).catch(() => {});
     }
 ${relEffects}
   }, [editId]);
@@ -418,17 +424,12 @@ ${relEffects}
     setSaving(true);
     setError('');
     try {
-      const method = editId ? 'PUT' : 'POST';
-      const url = editId ? \`${api}/\${editId}\` : '${api}';
-      const res = await fetch(url, {
-        method,
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(form),
-      });
-      if (!res.ok) {
-        const err = await res.json().catch(() => ({}));
-        throw new Error(err.message || 'Save failed');
+      if (editId) {
+        await apiRequest('PUT', \`${apiPath}/\${editId}\`, form);
+      } else {
+        await apiRequest('POST', '${apiPath}', form);
       }
+      // apiRequest throws on non-2xx so reaching here means success.
       navigate('/${lower}list');
     } catch (err: any) {
       setError(err.message);
@@ -490,7 +491,9 @@ export default ${name};
 function generateDashboardView(name, model, lower, plural, api, classified, view, modelDef) {
   const numericAttrs = classified.business.filter((a) => ["integer", "number", "money", "decimal", "float"].includes(a.type.toLowerCase()));
   const metricNames = numericAttrs.map((a) => a.name).slice(0, 4);
+  const apiPath = api.replace(/^\/api/, "");
   return `import { useState, useEffect } from 'react';
+import { apiRequest } from '../lib/apiClient';
 import { getEntityDisplayName } from '../lib/field-helpers';
 import { formatDate, StatusBadge } from '../lib/view-helpers';
 
@@ -499,7 +502,7 @@ function ${name}() {
   const [loading, setLoading] = useState(true);
 
   useEffect(() => {
-    fetch('${api}').then(r => r.json()).then(data => {
+    apiRequest('GET', '${apiPath}').then(data => {
       setItems(Array.isArray(data) ? data : []);
       setLoading(false);
     }).catch(() => setLoading(false));
@@ -552,8 +555,10 @@ export default ${name};
 function generateBoardView(name, model, lower, plural, api, lifecycle, view) {
   const states = lifecycle?.states || ["todo", "in_progress", "done"];
   const statusField = lifecycle?.statusField || "status";
+  const apiPath = api.replace(/^\/api/, "");
   return `import { useState, useEffect } from 'react';
 import { Link } from 'react-router-dom';
+import { apiRequest } from '../lib/apiClient';
 import { getEntityDisplayName } from '../lib/field-helpers';
 import { statusColor } from '../lib/view-helpers';
 
@@ -562,7 +567,7 @@ function ${name}() {
   const [loading, setLoading] = useState(true);
 
   useEffect(() => {
-    fetch('${api}').then(r => r.json()).then(data => {
+    apiRequest('GET', '${apiPath}').then(data => {
       setItems(Array.isArray(data) ? data : []);
       setLoading(false);
     }).catch(() => setLoading(false));
@@ -614,8 +619,10 @@ export default ${name};
 `;
 }
 function generateTimelineView(name, model, lower, plural, api, view) {
+  const apiPath = api.replace(/^\/api/, "");
   return `import { useState, useEffect } from 'react';
 import { Link } from 'react-router-dom';
+import { apiRequest } from '../lib/apiClient';
 import { getEntityDisplayName } from '../lib/field-helpers';
 import { formatDate, StatusBadge } from '../lib/view-helpers';
 
@@ -624,7 +631,7 @@ function ${name}() {
   const [loading, setLoading] = useState(true);
 
   useEffect(() => {
-    fetch('${api}').then(r => r.json()).then(data => {
+    apiRequest('GET', '${apiPath}').then(data => {
       const sorted = (Array.isArray(data) ? data : []).sort((a, b) =>
         new Date(b.createdAt || 0).getTime() - new Date(a.createdAt || 0).getTime()
       );
@@ -669,7 +676,9 @@ function generateCalendarView(name, model, lower, plural, api, view, modelDef) {
   const dateField = attrs.find(
     (a) => ["startdate", "duedate", "scheduledat", "eventdate", "date"].includes(a.name.toLowerCase())
   )?.name || "createdAt";
+  const apiPath = api.replace(/^\/api/, "");
   return `import { useState, useEffect } from 'react';
+import { apiRequest } from '../lib/apiClient';
 import { getEntityDisplayName } from '../lib/field-helpers';
 
 function ${name}() {
@@ -678,7 +687,7 @@ function ${name}() {
   const [currentMonth, setCurrentMonth] = useState(new Date());
 
   useEffect(() => {
-    fetch('${api}').then(r => r.json()).then(data => {
+    apiRequest('GET', '${apiPath}').then(data => {
       setItems(Array.isArray(data) ? data : []);
       setLoading(false);
     }).catch(() => setLoading(false));
@@ -737,14 +746,16 @@ export default ${name};
 function generateAnalyticsView(name, model, lower, plural, api, classified, lifecycle, view, modelDef) {
   const numericAttrs = classified.business.filter((a) => ["integer", "number", "money", "decimal", "float"].includes(a.type.toLowerCase()));
   const statusField = lifecycle?.statusField || "status";
+  const apiPath = api.replace(/^\/api/, "");
   return `import { useState, useEffect } from 'react';
+import { apiRequest } from '../lib/apiClient';
 
 function ${name}() {
   const [items, setItems] = useState<any[]>([]);
   const [loading, setLoading] = useState(true);
 
   useEffect(() => {
-    fetch('${api}').then(r => r.json()).then(data => {
+    apiRequest('GET', '${apiPath}').then(data => {
       setItems(Array.isArray(data) ? data : []);
       setLoading(false);
     }).catch(() => setLoading(false));