@svgrid/enterprise 2.5.2 → 2.6.0

package/dist/studio/samples/support.js

@@ -0,0 +1,209 @@
+import { screen, formScreen, boardScreen, workspaceScreen, detailScreen, project, dashScreen, statusPills, pad, ids, whenIsAny } from './shared.js';
+// Outlook-style chrome: a solid blue command ribbon (the toolbar), a light "folder"
+// rail with compact rows, and an accented left bar on the active folder.
+const OUTLOOK_CSS = `.sv-app.theme-outlook .sv-app__toolbar { background: #0f6cbd; border-bottom: 0; }
+.sv-app.theme-outlook .sv-app__toolbar, .sv-app.theme-outlook .sv-app__search-ic, .sv-app.theme-outlook .sv-app__kbd { color: #fff; }
+.sv-app.theme-outlook .sv-app__search { background: rgba(255, 255, 255, 0.16); border-color: rgba(255, 255, 255, 0.28); }
+.sv-app.theme-outlook .sv-app__search-in { color: #fff; }
+.sv-app.theme-outlook .sv-app__search-in::placeholder { color: rgba(255, 255, 255, 0.75); }
+.sv-app.theme-outlook .sv-app__side { background: #faf9f8; padding: 12px 8px; }
+.sv-app.theme-outlook .sv-app__brandtext { color: #0f6cbd; font-weight: 700; }
+.sv-app.theme-outlook .sv-app__link { border-radius: 4px; padding: 6px 12px; font-size: 13.5px; }
+.sv-app.theme-outlook .sv-app__link.is-active { background: color-mix(in srgb, #0f6cbd 12%, #fff); color: #0f6cbd; box-shadow: inset 3px 0 0 #0f6cbd; }`;
+const customers = {
+    name: 'customers',
+    label: 'Customer',
+    idField: 'id',
+    fields: [
+        { field: 'id', type: 'text', primaryKey: true, readonly: true },
+        { field: 'name', type: 'text', required: true, minLength: 2 },
+        { field: 'email', type: 'text', format: 'email', required: true, input: { help: 'Primary contact address' } },
+        { field: 'phone', type: 'text', input: { editorType: 'phone', help: 'Support callback number' } },
+        { field: 'country', type: 'text', label: 'Country', input: { editorType: 'country', help: 'Billing country' } },
+        { field: 'accountNo', type: 'text', label: 'Account #', input: { editorType: 'mask', mask: '####-####', help: 'Internal billing account number' } },
+        { field: 'plan', type: 'enum', required: true, defaultValue: 'free', options: [
+                { value: 'free', label: 'Free', color: '#94a3b8' },
+                { value: 'pro', label: 'Pro', color: '#6366f1' },
+                { value: 'business', label: 'Business', color: '#f59e0b' },
+            ] },
+        { field: 'signupAt', type: 'datetime', label: 'Signed up', input: { editorType: 'datetime', help: 'When the account was created' } },
+        { field: 'health', type: 'number', label: 'Account health', min: 1, max: 5, defaultValue: 3, input: { editorType: 'rating', help: '1-5 relationship score' } },
+        { field: 'active', type: 'boolean', defaultValue: true },
+    ],
+};
+const agents = {
+    name: 'agents',
+    label: 'Agent',
+    idField: 'id',
+    fields: [
+        { field: 'id', type: 'text', primaryKey: true, readonly: true },
+        { field: 'name', type: 'text', required: true, minLength: 2 },
+        { field: 'email', type: 'text', format: 'email', required: true, input: { help: 'Work address' } },
+        { field: 'team', type: 'enum', required: true, defaultValue: 'technical', options: [
+                { value: 'billing', label: 'Billing', color: '#10b981' },
+                { value: 'technical', label: 'Technical', color: '#6366f1' },
+                { value: 'onboarding', label: 'Onboarding', color: '#f59e0b' },
+            ] },
+        { field: 'phone', type: 'text', input: { editorType: 'phone', help: 'Desk extension' } },
+        { field: 'skills', type: 'text', label: 'Skills', input: { editorType: 'chips', help: 'Tools and specialities' } },
+        { field: 'capacity', type: 'number', label: 'Capacity (%)', min: 0, max: 100, defaultValue: 80, input: { editorType: 'slider', help: 'Share of a full ticket load' } },
+        { field: 'csat', type: 'number', label: 'CSAT', min: 1, max: 5, defaultValue: 3, input: { editorType: 'rating', help: 'Rolling satisfaction score' } },
+        { field: 'calendarColor', type: 'text', label: 'Calendar color', defaultValue: '#6366f1', input: { editorType: 'color', help: 'Shown on the shift calendar' } },
+        { field: 'active', type: 'boolean', defaultValue: true },
+    ],
+};
+const tickets = {
+    name: 'tickets',
+    label: 'Ticket',
+    idField: 'id',
+    fields: [
+        { field: 'id', type: 'text', primaryKey: true, readonly: true },
+        { field: 'subject', type: 'text', required: true, minLength: 3 },
+        { field: 'customerId', type: 'relation', label: 'Customer', relation: { entity: 'customers', foreignKey: 'customerId', labelField: 'name' } },
+        { field: 'agentId', type: 'relation', label: 'Agent', relation: { entity: 'agents', foreignKey: 'agentId', labelField: 'name' } },
+        { field: 'priority', type: 'enum', required: true, defaultValue: 'normal', options: [
+                { value: 'low', label: 'Low', color: '#94a3b8' },
+                { value: 'normal', label: 'Normal', color: '#6366f1' },
+                { value: 'high', label: 'High', color: '#f59e0b' },
+                { value: 'urgent', label: 'Urgent', color: '#ef4444' },
+            ] },
+        { field: 'status', type: 'enum', required: true, defaultValue: 'open', options: [
+                { value: 'open', label: 'Open', color: '#6366f1' },
+                { value: 'pending', label: 'Pending', color: '#f59e0b' },
+                { value: 'resolved', label: 'Resolved', color: '#10b981' },
+                { value: 'closed', label: 'Closed', color: '#94a3b8' },
+            ] },
+        { field: 'channel', type: 'enum', options: [
+                { value: 'email', label: 'Email', color: '#6366f1' },
+                { value: 'chat', label: 'Chat', color: '#10b981' },
+                { value: 'phone', label: 'Phone', color: '#f59e0b' },
+            ] },
+        { field: 'tags', type: 'text', label: 'Tags', input: { editorType: 'chips', help: 'Topic labels for routing' } },
+        { field: 'createdAt', type: 'datetime', label: 'Created', input: { editorType: 'datetime', help: 'When the ticket was opened' } },
+        { field: 'firstResponseMins', type: 'number', label: 'First response (min)', min: 0, input: { help: 'Time to the first agent reply' } },
+        // The close notes appear the moment a ticket reaches a terminal status, and
+        // the ticket cannot be saved in that state without them.
+        { field: 'resolution', type: 'text', label: 'Resolution', hidden: { grid: true },
+            input: { editorType: 'textarea', span: 2, help: 'What fixed it - required to resolve or close' },
+            when: { visible: whenIsAny('status', ['resolved', 'closed']), required: whenIsAny('status', ['resolved', 'closed']) } },
+        { field: 'satisfaction', type: 'number', label: 'CSAT', min: 1, max: 5, input: { editorType: 'rating', help: 'Customer rating on close' },
+            // A rating only means something once the customer has had an outcome.
+            when: { visible: whenIsAny('status', ['resolved', 'closed']) } },
+        { field: 'estimateHrs', type: 'number', label: 'Estimate (hrs)', min: 0, defaultValue: 1, input: { help: 'Estimated effort to resolve' } },
+        { field: 'hourlyRate', type: 'number', label: 'Rate ($/hr)', min: 0, defaultValue: 90, input: { help: 'Billed support rate' } },
+        // Derived: estimated support cost for the ticket (display-only, never seeded).
+        { field: 'cost', type: 'number', label: 'Cost ($)', readonly: true, formula: 'estimateHrs * hourlyRate' },
+    ],
+};
+const seed = {
+    customers: [
+        { id: 'c1', name: 'Ada Lovelace', email: 'ada@analytic.io', phone: '+1 (415) 555-0101', country: 'United States', accountNo: '4021-7788', plan: 'business', signupAt: '2025-09-12T09:15:00Z', health: 5, active: true },
+        { id: 'c2', name: 'Alan Turing', email: 'alan@bletchley.uk', phone: '+44 20 7946 0102', country: 'United Kingdom', accountNo: '5590-2143', plan: 'pro', signupAt: '2025-11-03T14:20:00Z', health: 4, active: true },
+        { id: 'c3', name: 'Grace Hopper', email: 'grace@navy.mil', phone: '+1 (202) 555-0103', country: 'United States', accountNo: '7781-6620', plan: 'business', signupAt: '2026-01-21T10:05:00Z', health: 5, active: true },
+        { id: 'c4', name: 'Linus Torvalds', email: 'linus@kernel.org', phone: '+1 (503) 555-0104', country: 'United States', accountNo: '3312-9087', plan: 'pro', signupAt: '2026-03-08T08:45:00Z', health: 3, active: true },
+        { id: 'c5', name: 'Barbara Liskov', email: 'barbara@sub.dev', phone: '+1 (617) 555-0105', country: 'United States', accountNo: '9001-4455', plan: 'free', signupAt: '2026-05-30T16:30:00Z', health: 2, active: false },
+    ],
+    agents: [
+        { id: 'a1', name: 'Sam Rivera', email: 'sam@support.io', team: 'technical', phone: '+1 (415) 555-0201', skills: ['TypeScript', 'AWS', 'GraphQL'], capacity: 85, csat: 5, calendarColor: '#6366f1', active: true },
+        { id: 'a2', name: 'Jamie Chen', email: 'jamie@support.io', team: 'billing', phone: '+1 (312) 555-0202', skills: ['SQL', 'Leadership'], capacity: 70, csat: 4, calendarColor: '#10b981', active: true },
+        { id: 'a3', name: 'Priya Patel', email: 'priya@support.io', team: 'onboarding', phone: '+1 (206) 555-0203', skills: ['Product', 'UX', 'Figma'], capacity: 60, csat: 4, calendarColor: '#f59e0b', active: true },
+    ],
+    tickets: [
+        { id: 'tk1', subject: 'Cannot reset password', customerId: 'c1', agentId: 'a1', priority: 'high', status: 'open', channel: 'email', tags: ['auth', 'login'], createdAt: '2026-07-10T08:30:00Z', firstResponseMins: 12, satisfaction: 4, estimateHrs: 2, hourlyRate: 90 },
+        { id: 'tk2', subject: 'Invoice discrepancy', customerId: 'c2', agentId: 'a2', priority: 'normal', status: 'pending', channel: 'email', tags: ['billing'], createdAt: '2026-07-08T11:05:00Z', firstResponseMins: 45, satisfaction: 3, estimateHrs: 1, hourlyRate: 75 },
+        { id: 'tk3', subject: 'API returns 500', customerId: 'c3', agentId: 'a1', priority: 'urgent', status: 'open', channel: 'chat', tags: ['api', 'outage'], createdAt: '2026-07-12T15:40:00Z', firstResponseMins: 4, satisfaction: 5, estimateHrs: 4, hourlyRate: 120 },
+        { id: 'tk4', subject: 'How do I export data?', customerId: 'c4', agentId: 'a3', priority: 'low', status: 'resolved', channel: 'chat', tags: ['export'], createdAt: '2026-07-02T09:20:00Z', firstResponseMins: 20, satisfaction: 5, estimateHrs: 1, hourlyRate: 60, resolution: 'Walked the customer through Export > CSV in the toolbar.' },
+        { id: 'tk5', subject: 'Upgrade to Business', customerId: 'c5', agentId: 'a3', priority: 'normal', status: 'closed', channel: 'phone', tags: ['upgrade', 'billing'], createdAt: '2026-06-28T13:10:00Z', firstResponseMins: 8, satisfaction: 4, estimateHrs: 1, hourlyRate: 75, resolution: 'Upgraded the account to Business and prorated the invoice.' },
+        { id: 'tk6', subject: 'SSO configuration', customerId: 'c1', agentId: 'a1', priority: 'high', status: 'pending', channel: 'email', tags: ['sso', 'security'], createdAt: '2026-07-11T10:00:00Z', firstResponseMins: 60, satisfaction: 2, estimateHrs: 3, hourlyRate: 120 },
+        { id: 'tk7', subject: 'Double charge refund', customerId: 'c2', agentId: 'a2', priority: 'urgent', status: 'resolved', channel: 'phone', tags: ['refund', 'billing'], createdAt: '2026-07-05T16:25:00Z', firstResponseMins: 15, satisfaction: 4, estimateHrs: 2, hourlyRate: 90, resolution: 'Refunded the duplicate charge; payment retry guard added.' },
+        { id: 'tk8', subject: 'Feature request: dark mode', customerId: 'c3', agentId: 'a3', priority: 'low', status: 'open', channel: 'chat', tags: ['feature'], createdAt: '2026-07-13T12:50:00Z', firstResponseMins: 90, satisfaction: 3, estimateHrs: 5, hourlyRate: 100 },
+    ],
+};
+export const support = {
+    id: 'support',
+    name: 'Support desk',
+    description: 'Tickets, customers and agents - an Outlook-style help desk behind a sign-in, with triage + SLA dashboards (CSAT sparkline + gauge, pivot, tabbed breakdown), a team-capacity dashboard, status-pill grids, master/detail, and rich edit forms.',
+    emoji: '\u{1F3AF}',
+    accent: '#0f6cbd',
+    build: () => {
+        const customerRows = pad(customers, seed.customers, 16);
+        const agentRows = pad(agents, seed.agents, 6);
+        const ticketRows = pad(tickets, seed.tickets, 36, { customerId: ids(customerRows), agentId: ids(agentRows) });
+        return project({
+            title: 'Support Desk',
+            brand: 'Support Desk',
+            accent: '#0f6cbd',
+            preset: 'atlassian',
+            footer: '',
+            // Outlook-style mail/triage client: blue command ribbon + a light folder rail.
+            appClass: 'theme-outlook',
+            customCss: OUTLOOK_CSS,
+            // Sign-in with two roles: agents work tickets but cannot delete records.
+            auth: { enabled: true, protect: true },
+            access: {
+                enabled: true,
+                defaultRole: 'agent',
+                roles: [
+                    { role: 'admin', screens: '*', actions: '*' },
+                    { role: 'agent', screens: '*', actions: ['create', 'update'] },
+                ],
+            },
+            entities: [customers, agents, tickets],
+            seed: { customers: customerRows, agents: agentRows, tickets: ticketRows },
+            screens: [
+                // Triage dashboard: volume + CSAT KPIs (CSAT card trends over created date),
+                // a CSAT gauge, status/priority/channel breakdowns, a tabbed view, and a
+                // ticket grid with status AND priority pills.
+                dashScreen(tickets, { id: 'overview', title: 'Overview', order: 0 }, [
+                    { kpi: 'Open tickets', reduce: 'count', span: 1 },
+                    { kpi: 'Avg first response', measure: 'firstResponseMins', reduce: 'avg', span: 1 },
+                    { kpi: 'Avg CSAT', measure: 'satisfaction', reduce: 'avg', trendField: 'createdAt', trendReduce: 'avg', span: 1 },
+                    { gauge: 'Avg CSAT', measure: 'satisfaction', reduce: 'avg', min: 0, max: 5, span: 1 },
+                    { chart: 'status', reduce: 'count', type: 'bar', span: 2 },
+                    { chart: 'priority', reduce: 'count', type: 'pie', span: 1 },
+                    { chart: 'channel', reduce: 'count', type: 'bar', span: 2 },
+                    { tabs: [
+                            { label: 'By status', tiles: [{ chart: 'status', reduce: 'count', type: 'bar' }] },
+                            { label: 'By priority', tiles: [{ chart: 'priority', reduce: 'count', type: 'bar' }] },
+                            { label: 'By channel', tiles: [{ chart: 'channel', reduce: 'count', type: 'bar' }] },
+                        ], span: 3 },
+                    { grid: true, format: [...statusPills(tickets, 'status'), ...statusPills(tickets, 'priority')], summaries: true, span: 3 },
+                ]),
+                // SLA / quality: response + CSAT KPIs, a CSAT gauge, and a pivot of CSAT by
+                // priority (rows) x status (columns).
+                // Ticket board: tickets as cards in status columns (drag to change status).
+                boardScreen(tickets, { id: 'board', title: 'Board', order: 1 }, { groupBy: 'status', titleField: 'subject', subtitleField: 'priority', filter: ['priority', 'channel', 'agentId'] }),
+                // A docking console: filter | ticket queue | selected-ticket panel (drag / float / pin).
+                workspaceScreen(tickets, { id: 'console', title: 'Console', order: 2 }, { filter: ['priority', 'channel', 'agentId'], record: true, grid: { format: [...statusPills(tickets, 'status'), ...statusPills(tickets, 'priority')] } }),
+                // Customer 360: account header (plan pill + health tile) with a timeline of
+                // the customer's tickets (newest first, colored by status).
+                detailScreen(customers, { id: 'customer-360', title: 'Customer 360', order: 2 }, {
+                    titleField: 'name', subtitleField: 'email', statusField: 'plan', metricFields: ['health'],
+                    related: [{ entity: 'tickets', foreignKey: 'customerId', label: 'Tickets', titleField: 'subject', subtitleField: 'priority', dateField: 'createdAt', statusField: 'status' }],
+                }),
+                dashScreen(tickets, { id: 'performance', title: 'Performance', order: 3 }, [
+                    { kpi: 'Avg first response', measure: 'firstResponseMins', reduce: 'avg', span: 1 },
+                    { kpi: 'Avg CSAT', measure: 'satisfaction', reduce: 'avg', span: 1 },
+                    { kpi: 'Est. hours', measure: 'estimateHrs', reduce: 'sum', format: 'number', span: 1 },
+                    { gauge: 'Avg CSAT', measure: 'satisfaction', reduce: 'avg', min: 0, max: 5, span: 1 },
+                    { chart: 'channel', measure: 'firstResponseMins', reduce: 'avg', type: 'bar', span: 2 },
+                    { chart: 'priority', measure: 'satisfaction', reduce: 'avg', type: 'bar', span: 1 },
+                    { pivot: { rows: ['priority'], cols: ['status'], measure: 'satisfaction', aggregate: 'avg' }, span: 3 },
+                ]),
+                // Team load: capacity gauge + a per-agent capacity leaderboard.
+                dashScreen(agents, { id: 'team', title: 'Team', order: 4 }, [
+                    { kpi: 'Agents', reduce: 'count', span: 1 },
+                    { kpi: 'Avg capacity', measure: 'capacity', reduce: 'avg', format: 'percent', span: 1 },
+                    { kpi: 'Avg CSAT', measure: 'csat', reduce: 'avg', span: 1 },
+                    { gauge: 'Avg team capacity', measure: 'capacity', reduce: 'avg', min: 0, max: 100, unit: '%', span: 1 },
+                    { chart: 'name', measure: 'capacity', reduce: 'avg', type: 'bar', span: 2 },
+                    { chart: 'team', reduce: 'count', type: 'pie', span: 1 },
+                    { grid: true, format: statusPills(agents, 'team'), summaries: true, span: 3 },
+                ]),
+                formScreen(tickets, { id: 'tickets', title: 'Tickets', order: 5 }, undefined, { format: [...statusPills(tickets, 'status'), ...statusPills(tickets, 'priority')], summaries: true }),
+                screen(customers, 'master-detail', { id: 'customers', title: 'Customers', order: 6, child: tickets, foreignKey: 'customerId', linkScreen: 'customer-360' }),
+                formScreen(agents, { id: 'agents', title: 'Agents', order: 7 }),
+            ],
+        });
+    },
+};

package/dist/studio/scaffold-app.d.ts

@@ -0,0 +1,22 @@
+/**
+ * scaffoldApp - scaffold a whole data app, not a single page. Given several
+ * `EntitySchema`s (e.g. every table from `introspectDatabase` + `--all`), it
+ * emits each entity's screen (via `scaffold`) plus a shared **navigation
+ * layout** and a **home page** linking them. It also runs `linkRelationLabels`
+ * across the set, so foreign-key lookups resolve their display field from the
+ * actual related schema and every relation's `/api/<entity>` route exists.
+ *
+ * Pure string building, like `scaffold`. Each generated shell file wraps its
+ * body in `svgrid:managed` markers so re-running is safe.
+ */
+import { type EntitySchema } from '../schema.js';
+import { type GeneratedFile, type ScaffoldOptions } from './scaffold.js';
+export type ScaffoldAppOptions = {
+    /** Backend for every entity's API route (see `ScaffoldOptions.dataSource`). */
+    dataSource?: ScaffoldOptions['dataSource'];
+    /** App title shown in the nav + home. Default `'Data App'`. */
+    appTitle?: string;
+};
+export declare function scaffoldApp(schemas: EntitySchema[], options?: ScaffoldAppOptions): {
+    files: GeneratedFile[];
+};

package/{src/studio/scaffold-app.ts → dist/studio/scaffold-app.js}

@@ -1,34 +1,23 @@
-/**
- * scaffoldApp - scaffold a whole data app, not a single page. Given several
- * `EntitySchema`s (e.g. every table from `introspectDatabase` + `--all`), it
- * emits each entity's screen (via `scaffold`) plus a shared **navigation
- * layout** and a **home page** linking them. It also runs `linkRelationLabels`
- * across the set, so foreign-key lookups resolve their display field from the
- * actual related schema and every relation's `/api/<entity>` route exists.
- *
- * Pure string building, like `scaffold`. Each generated shell file wraps its
- * body in `svgrid:managed` markers so re-running is safe.
- */
-import { linkRelationLabels, titleCase, type EntitySchema } from '../schema.js'
-import { scaffold, MANAGED_START, MANAGED_END, type GeneratedFile, type ScaffoldOptions } from './scaffold.js'
-
-export type ScaffoldAppOptions = {
-  /** Backend for every entity's API route (see `ScaffoldOptions.dataSource`). */
-  dataSource?: ScaffoldOptions['dataSource']
-  /** App title shown in the nav + home. Default `'Data App'`. */
-  appTitle?: string
-}
-
-type NavItem = { href: string; label: string }
-
-const MANAGED_NOTE = '// Regenerated by SvGrid Studio. Edits inside these markers are overwritten.'
-const managed = (body: string) => `${MANAGED_START}\n${MANAGED_NOTE}\n${body}\n${MANAGED_END}`
-
-function layoutFile(nav: NavItem[], appTitle: string): GeneratedFile {
-  return {
-    path: 'src/routes/+layout.svelte',
-    description: 'App shell: a collapsible nav sidebar linking every entity screen (an off-canvas drawer on tablet/phone), with the routed page in the main area.',
-    contents: `<script lang="ts">
+/**
+ * scaffoldApp - scaffold a whole data app, not a single page. Given several
+ * `EntitySchema`s (e.g. every table from `introspectDatabase` + `--all`), it
+ * emits each entity's screen (via `scaffold`) plus a shared **navigation
+ * layout** and a **home page** linking them. It also runs `linkRelationLabels`
+ * across the set, so foreign-key lookups resolve their display field from the
+ * actual related schema and every relation's `/api/<entity>` route exists.
+ *
+ * Pure string building, like `scaffold`. Each generated shell file wraps its
+ * body in `svgrid:managed` markers so re-running is safe.
+ */
+import { linkRelationLabels, titleCase } from '../schema.js';
+import { scaffold, MANAGED_START, MANAGED_END } from './scaffold.js';
+const MANAGED_NOTE = '// Regenerated by SvGrid Studio. Edits inside these markers are overwritten.';
+const managed = (body) => `${MANAGED_START}\n${MANAGED_NOTE}\n${body}\n${MANAGED_END}`;
+function layoutFile(nav, appTitle) {
+    return {
+        path: 'src/routes/+layout.svelte',
+        description: 'App shell: a collapsible nav sidebar linking every entity screen (an off-canvas drawer on tablet/phone), with the routed page in the main area.',
+        contents: `<script lang="ts">
 ${managed(`  let { children } = $props()
   const appTitle = ${JSON.stringify(appTitle)}
   const nav = ${JSON.stringify(nav)}
@@ -108,15 +97,14 @@ ${managed(`  let { children } = $props()
   .app-shell.is-drawer .app-shell__navhead .app-shell__brand { display: none; } /* brand already in the top bar */
   .app-shell.is-drawer .app-shell__collapse { display: none; } /* dock lives in the top bar when drawered */
 </style>
-`,
-  }
-}
-
-function homeFile(nav: NavItem[], appTitle: string): GeneratedFile {
-  return {
-    path: 'src/routes/+page.svelte',
-    description: 'Home page: cards linking to each entity screen.',
-    contents: `<script lang="ts">
+`,
+    };
+}
+function homeFile(nav, appTitle) {
+    return {
+        path: 'src/routes/+page.svelte',
+        description: 'Home page: cards linking to each entity screen.',
+        contents: `<script lang="ts">
 ${managed(`  const appTitle = ${JSON.stringify(appTitle)}
   const entities = ${JSON.stringify(nav)}`)}
 </script>
@@ -136,26 +124,20 @@ ${managed(`  const appTitle = ${JSON.stringify(appTitle)}
   .home__card { display: block; padding: 18px 16px; border: 1px solid #e5e7eb; border-radius: 10px; color: inherit; text-decoration: none; font-weight: 600; }
   .home__card:hover { border-color: #94a3b8; background: #f8fafc; }
 </style>
-`,
-  }
-}
-
-export function scaffoldApp(
-  schemas: EntitySchema[],
-  options: ScaffoldAppOptions = {},
-): { files: GeneratedFile[] } {
-  if (schemas.length === 0) throw new Error('scaffoldApp: no schemas to scaffold')
-  const appTitle = options.appTitle ?? 'Data App'
-
-  // Resolve each relation's display field against the related schema in the set.
-  const linked = linkRelationLabels(schemas)
-
-  const files: GeneratedFile[] = []
-  for (const schema of linked) {
-    files.push(...scaffold(schema, { dataSource: options.dataSource }).files)
-  }
-
-  const nav: NavItem[] = linked.map((s) => ({ href: `/${s.name}`, label: s.label ?? titleCase(s.name) }))
-  files.push(layoutFile(nav, appTitle), homeFile(nav, appTitle))
-  return { files }
-}
+`,
+    };
+}
+export function scaffoldApp(schemas, options = {}) {
+    if (schemas.length === 0)
+        throw new Error('scaffoldApp: no schemas to scaffold');
+    const appTitle = options.appTitle ?? 'Data App';
+    // Resolve each relation's display field against the related schema in the set.
+    const linked = linkRelationLabels(schemas);
+    const files = [];
+    for (const schema of linked) {
+        files.push(...scaffold(schema, { dataSource: options.dataSource }).files);
+    }
+    const nav = linked.map((s) => ({ href: `/${s.name}`, label: s.label ?? titleCase(s.name) }));
+    files.push(layoutFile(nav, appTitle), homeFile(nav, appTitle));
+    return { files };
+}

package/dist/studio/scaffold.d.ts

@@ -0,0 +1,63 @@
+/**
+ * scaffold - turn an `EntitySchema` into runnable SvelteKit files. The shared
+ * code-emit core: both the AI generator (MCP `scaffold_entity` tool) and the
+ * visual designer's "Generate code" action call this one function, so there is
+ * a single source of truth for what generated code looks like.
+ *
+ * Every generated file wraps its body in `svgrid:managed` markers. A future
+ * regeneration replaces only the managed region, so edits a user makes outside
+ * the markers survive - idempotent generation, the thing that makes a
+ * generator trustworthy enough to keep using.
+ *
+ * Pure string building. No filesystem, no Svelte. The `validate` (Standard
+ * Schema) functions on a field cannot be serialized to a literal, so they are
+ * omitted from the emitted schema with a note to re-add them by hand.
+ */
+import { type EntitySchema } from '../schema.js';
+import type { SqlDialectName } from './introspect-db.js';
+export type GeneratedFile = {
+    path: string;
+    contents: string;
+    description: string;
+    /** A user-owned companion (e.g. a screen's `handlers.ts`): scaffolded once as a
+     *  starting stub, then never overwritten. In-place writers must skip it if it
+     *  already exists. See HANDLERS-DESIGN.md. */
+    userOwned?: boolean;
+};
+export type ScaffoldOptions = {
+    /** Route segment for the page, defaults to the schema name. e.g. `'customers'`. */
+    route?: string;
+    /** API route the page talks to, defaults to `/api/{route}`. */
+    apiRoute?: string;
+    /** `$lib` path for the generated schema module, defaults to `$lib/{route}.schema`. */
+    schemaImport?: string;
+    /**
+     * Backend the generated API route uses:
+     *   - `'memory'` (default): `createInMemoryDataSource` - runs immediately, no DB.
+     *   - `'sql'`: `createSqlDataSource` with an `execute(text, params)` stub you fill in.
+     *   - a dialect (`'postgres'` | `'supabase'` | `'mysql'` | `'mssql'` | `'sqlite'`):
+     *     a fully-connected route wired to that driver via `process.env.DATABASE_URL`.
+     */
+    dataSource?: 'memory' | 'sql' | SqlDialectName;
+};
+/**
+ * Whether an in-place writer must SKIP this file to preserve the developer's
+ * code: a user-owned companion (a screen's `handlers.ts`) that already exists on
+ * disk. Such files carry no `svgrid:managed` markers, so `mergeManaged` would
+ * overwrite them wholesale - the write-once contract lives here instead, shared
+ * by every writer (CLI regenerate + the designer's bundle write). See
+ * HANDLERS-DESIGN.md.
+ */
+export declare function skipUserOwned(file: Pick<GeneratedFile, 'userOwned'>, existsOnDisk: boolean): boolean;
+export declare const MANAGED_START = "// svgrid:managed:start";
+export declare const MANAGED_END = "// svgrid:managed:end";
+export declare function scaffold(schema: EntitySchema, options?: ScaffoldOptions): {
+    files: GeneratedFile[];
+};
+/**
+ * Merge freshly-scaffolded files into existing file contents, replacing only
+ * each file's `svgrid:managed` region and preserving everything a user wrote
+ * outside it. When there's no existing content (or no markers in it), the new
+ * file is used whole. This is what makes regeneration safe.
+ */
+export declare function mergeManaged(existing: string | null | undefined, generated: string): string;