@svgrid/enterprise 1.2.0 → 2.0.0

package/src/studio/samples/support.ts

@@ -0,0 +1,182 @@
+import type { EntitySchema } from '../../schema.js'
+import { screen, formScreen, boardScreen, detailScreen, project, dashScreen, statusPills, pad, ids, type SampleApp } from './shared.js'
+
+const customers: EntitySchema = {
+  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: EntitySchema = {
+  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: EntitySchema = {
+  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' } },
+    { field: 'satisfaction', type: 'number', label: 'CSAT', min: 1, max: 5, input: { editorType: 'rating', help: 'Customer rating on close' } },
+    { 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 },
+    { 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 },
+    { 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 },
+    { 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: SampleApp = {
+  id: 'support',
+  name: 'Support desk',
+  description: 'Tickets, customers and agents - 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: '#0ea5e9',
+  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: '#0ea5e9',
+      preset: 'atlassian',
+      footer: '',
+      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'] }),
+        // 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/src/studio/scaffold-app.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'vitest'
+import { compile } from 'svelte/compiler'
+import type { EntitySchema } from '../schema'
+import { MANAGED_START, MANAGED_END } from './scaffold'
+import { scaffoldApp } from './scaffold-app'
+
+const companies: EntitySchema = {
+  name: 'companies', label: 'Companies', idField: 'id',
+  fields: [
+    { field: 'id', type: 'number', primaryKey: true, readonly: true },
+    { field: 'name', type: 'text', required: true },
+  ],
+}
+const contacts: EntitySchema = {
+  name: 'contacts', label: 'Contacts', idField: 'id',
+  fields: [
+    { field: 'id', type: 'number', primaryKey: true, readonly: true },
+    { field: 'full_name', type: 'text', required: true },
+    // FK with a placeholder labelField - scaffoldApp should resolve it to 'name'.
+    { field: 'company_id', type: 'relation', relation: { entity: 'companies', foreignKey: 'company_id', labelField: 'xxx' } },
+  ],
+}
+
+describe('scaffoldApp', () => {
+  const { files } = scaffoldApp([companies, contacts], { appTitle: 'CRM' })
+  const byPath = Object.fromEntries(files.map((f) => [f.path, f]))
+
+  it('emits every entity screen plus a layout and home page', () => {
+    for (const p of [
+      'src/lib/companies.schema.ts', 'src/routes/companies/+page.svelte', 'src/routes/api/companies/+server.ts',
+      'src/lib/contacts.schema.ts', 'src/routes/contacts/+page.svelte', 'src/routes/api/contacts/+server.ts',
+      'src/routes/+layout.svelte', 'src/routes/+page.svelte',
+    ]) {
+      expect(byPath[p], p).toBeDefined()
+    }
+  })
+
+  it('the layout links every entity and renders the routed page', () => {
+    const layout = byPath['src/routes/+layout.svelte']!.contents
+    expect(layout).toContain('"href":"/companies"')
+    expect(layout).toContain('"href":"/contacts"')
+    expect(layout).toContain('{@render children?.()}')
+    expect(layout).toContain('CRM')
+  })
+
+  it('the sidebar is collapsible and starts collapsed on tablet / phone', () => {
+    const layout = byPath['src/routes/+layout.svelte']!.contents
+    // Off-canvas drawer driven by a collapse toggle + a <= 1024px media query.
+    expect(layout).toContain('matchMedia')
+    expect(layout).toContain('max-width: 1024px')
+    expect(layout).toContain('function toggleNav')
+    expect(layout).toContain('class:is-drawer={drawer}')
+    expect(layout).toContain('app-shell__burger')
+  })
+
+  it('the home page lists the entities', () => {
+    const home = byPath['src/routes/+page.svelte']!.contents
+    expect(home).toContain('"label":"Companies"')
+    expect(home).toContain('"label":"Contacts"')
+  })
+
+  it('resolves relation labelFields across the app (linkRelationLabels)', () => {
+    const schema = byPath['src/lib/contacts.schema.ts']!.contents
+    // The placeholder 'xxx' is replaced by the related companies schema's 'name'.
+    expect(schema).toContain('"labelField":"name"')
+    expect(schema).not.toContain('"labelField":"xxx"')
+  })
+
+  it('the contacts page wires a lookup to the companies route', () => {
+    const page = byPath['src/routes/contacts/+page.svelte']!.contents
+    expect(page).toContain('createRelationLookup')
+    expect(page).toContain('endpoint: "/api/companies"')
+  })
+
+  it('layout and home are valid Svelte (compile)', () => {
+    for (const p of ['src/routes/+layout.svelte', 'src/routes/+page.svelte']) {
+      expect(() => compile(byPath[p]!.contents, { filename: p, generate: 'client' }), p).not.toThrow()
+    }
+  })
+
+  it('wraps shell files in managed markers', () => {
+    for (const p of ['src/routes/+layout.svelte', 'src/routes/+page.svelte']) {
+      expect(byPath[p]!.contents).toContain(MANAGED_START)
+      expect(byPath[p]!.contents).toContain(MANAGED_END)
+    }
+  })
+
+  it('throws with no schemas', () => {
+    expect(() => scaffoldApp([])).toThrow(/no schemas/)
+  })
+})

package/src/studio/scaffold-app.ts

@@ -0,0 +1,161 @@
+/**
+ * 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">
+${managed(`  let { children } = $props()
+  const appTitle = ${JSON.stringify(appTitle)}
+  const nav = ${JSON.stringify(nav)}
+
+  // The sidebar collapses to an off-canvas drawer either on user request or on
+  // tablet / phone (<= 1024px), where it also starts collapsed. The desktop
+  // collapse choice persists across visits.
+  let navOpen = $state(false)
+  let collapsed = $state(false)
+  let narrow = $state(false)
+  const drawer = $derived(collapsed || narrow)
+  function toggleNav() { collapsed = !collapsed; try { localStorage.setItem('svapp:nav', collapsed ? 'c' : 'e') } catch (_) { /* storage blocked */ } }
+  $effect(() => {
+    const mq = window.matchMedia('(max-width: 1024px)')
+    const sync = () => (narrow = mq.matches)
+    sync()
+    try { const s = localStorage.getItem('svapp:nav'); if (s) collapsed = s === 'c' } catch (_) { /* storage blocked */ }
+    mq.addEventListener('change', sync)
+    return () => mq.removeEventListener('change', sync)
+  })`)}
+</script>
+
+<div class="app-shell" class:is-drawer={drawer} class:is-navopen={navOpen}>
+  <header class="app-shell__mobilebar">
+    <button type="button" class="app-shell__burger" aria-label="Toggle navigation" aria-expanded={navOpen} onclick={() => (navOpen = !navOpen)}>
+      <svg viewBox="0 0 24 24" width="22" height="22" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M3 6h18M3 12h18M3 18h18"/></svg>
+    </button>
+    <a class="app-shell__brand" href="/">{appTitle}</a>
+    {#if !narrow}<button type="button" class="app-shell__dock" aria-label="Dock sidebar" title="Dock sidebar" onclick={toggleNav}>
+      <svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M9 6l6 6-6 6"/></svg>
+    </button>{/if}
+  </header>
+  {#if navOpen}<button type="button" class="app-shell__backdrop" aria-label="Close navigation" onclick={() => (navOpen = false)}></button>{/if}
+  <aside class="app-shell__nav">
+    <div class="app-shell__navhead">
+      <a class="app-shell__brand" href="/">{appTitle}</a>
+      <button type="button" class="app-shell__collapse" aria-label="Collapse sidebar" title="Collapse sidebar" onclick={toggleNav}>
+        <svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M15 6l-6 6 6 6"/></svg>
+      </button>
+    </div>
+    <nav onclick={() => (navOpen = false)}>
+      {#each nav as item (item.href)}
+        <a class="app-shell__link" href={item.href}>{item.label}</a>
+      {/each}
+    </nav>
+  </aside>
+  <main class="app-shell__main">
+    {@render children?.()}
+  </main>
+</div>
+
+<style>
+  .app-shell { display: grid; grid-template-columns: 220px 1fr; min-height: 100vh; }
+  .app-shell__nav { display: flex; flex-direction: column; gap: 4px; padding: 16px 12px; border-right: 1px solid #e5e7eb; background: #f8fafc; }
+  .app-shell__navhead { display: flex; align-items: center; justify-content: space-between; gap: 8px; }
+  .app-shell__brand { font-weight: 700; font-size: 16px; padding: 6px 10px 12px; color: inherit; text-decoration: none; }
+  .app-shell__navhead .app-shell__brand { padding-bottom: 6px; }
+  .app-shell__collapse, .app-shell__dock, .app-shell__burger { display: inline-flex; align-items: center; justify-content: center; padding: 6px; border: 0; border-radius: 8px; background: transparent; color: #64748b; cursor: pointer; }
+  .app-shell__collapse:hover, .app-shell__dock:hover, .app-shell__burger:hover { background: #e2e8f0; color: #0f172a; }
+  .app-shell__link { padding: 8px 10px; border-radius: 6px; color: #334155; text-decoration: none; }
+  .app-shell__link:hover { background: #e2e8f0; }
+  .app-shell nav { display: flex; flex-direction: column; gap: 4px; }
+  .app-shell__main { padding: 20px 24px; min-width: 0; }
+  .app-shell__mobilebar { display: none; align-items: center; gap: 12px; padding: 10px 14px; border-bottom: 1px solid #e5e7eb; background: #f8fafc; position: sticky; top: 0; z-index: 50; }
+  .app-shell__mobilebar .app-shell__dock { margin-left: auto; }
+  .app-shell__backdrop { display: none; position: fixed; inset: 0; z-index: 55; border: 0; padding: 0; background: rgba(15, 23, 42, 0.42); cursor: pointer; }
+  /* Drawer mode: tablet / phone (<= 1024px) or a user-collapsed desktop sidebar.
+     The sidebar becomes a fixed off-canvas panel that slides in when opened. */
+  .app-shell.is-drawer { display: block; }
+  .app-shell.is-drawer .app-shell__mobilebar { display: flex; }
+  .app-shell.is-drawer .app-shell__backdrop { display: block; }
+  .app-shell.is-drawer .app-shell__nav {
+    position: fixed; top: 0; bottom: 0; left: 0; z-index: 60; width: 264px; max-width: 82vw;
+    transform: translateX(-100%); transition: transform 0.24s ease; box-shadow: 0 0 40px rgba(15, 23, 42, 0.28);
+  }
+  .app-shell.is-drawer.is-navopen .app-shell__nav { transform: translateX(0); }
+  .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">
+${managed(`  const appTitle = ${JSON.stringify(appTitle)}
+  const entities = ${JSON.stringify(nav)}`)}
+</script>
+
+<section class="home">
+  <h2 class="home__title">{appTitle}</h2>
+  <div class="home__grid">
+    {#each entities as item (item.href)}
+      <a class="home__card" href={item.href}>{item.label}</a>
+    {/each}
+  </div>
+</section>
+
+<style>
+  .home__title { margin: 0 0 16px; font-size: 20px; font-weight: 600; }
+  .home__grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(180px, 1fr)); gap: 12px; }
+  .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 }
+}

package/src/studio/scaffold.test.ts

@@ -0,0 +1,178 @@
+import { describe, expect, it } from 'vitest'
+import { compile } from 'svelte/compiler'
+import type { EntitySchema } from '../schema'
+import { MANAGED_END, MANAGED_START, mergeManaged, scaffold } from './scaffold'
+
+const schema: EntitySchema = {
+  name: 'customers',
+  label: 'Customer',
+  idField: 'id',
+  fields: [
+    { field: 'id', type: 'text', primaryKey: true, readonly: true },
+    { field: 'firstName', type: 'text', required: true },
+    { field: 'age', type: 'number' },
+    { field: 'tier', type: 'enum', options: [{ value: 'free', label: 'Free' }] },
+  ],
+}
+
+describe('scaffold', () => {
+  const { files } = scaffold(schema)
+  const byPath = Object.fromEntries(files.map((f) => [f.path, f]))
+
+  it('emits schema, server route, and page files at SvelteKit paths', () => {
+    expect(Object.keys(byPath).sort()).toEqual([
+      'src/lib/customers.schema.ts',
+      'src/routes/api/customers/+server.ts',
+      'src/routes/customers/+page.svelte',
+    ])
+  })
+
+  it('the schema file exports a typed EntitySchema literal and Row type', () => {
+    const c = byPath['src/lib/customers.schema.ts']!.contents
+    expect(c).toContain('export const customersSchema: EntitySchema<CustomersRow>')
+    expect(c).toContain('export type CustomersRow = {')
+    expect(c).toContain('age: number')
+    expect(c).toContain('firstName: string')
+    expect(c).toContain(`field: "tier", type: "enum"`)
+    expect(c).toContain(`options: [{"value":"free","label":"Free"}]`)
+  })
+
+  it('the server route wires createKitHandlers', () => {
+    const c = byPath['src/routes/api/customers/+server.ts']!.contents
+    expect(c).toContain('createKitHandlers({ schema: customersSchema, source })')
+    expect(c).toContain('export const { POST }')
+  })
+
+  it('the page wires the grid + edit panel over the transport', () => {
+    const c = byPath['src/routes/customers/+page.svelte']!.contents
+    expect(c).toContain("createKitDataSource<CustomersRow>({ endpoint: '/api/customers' })")
+    expect(c).toContain('schemaToColumns(customersSchema)')
+    expect(c).toContain('<SvGrid')
+    expect(c).toContain('<SvGridEditPanel')
+  })
+
+  it('the page is a full data screen: sort, filter, paging, delete, optimistic', () => {
+    const c = byPath['src/routes/customers/+page.svelte']!.contents
+    expect(c).toContain('sortable')
+    expect(c).toContain('externalSort')
+    expect(c).toContain('controller.setSort(s)')
+    expect(c).toContain('filterable')
+    expect(c).toContain('showGlobalFilter')
+    expect(c).toContain('controller.setFilter(') // server filtering
+    expect(c).toContain('fitColumns') // columns fill the width
+    expect(c).toContain('enableRowSummaries={false}') // no default summary
+    expect(c).toContain('externalPagination') // native server pagination footer
+    expect(c).toContain('onPaginationChange')
+    expect(c).toContain('controller.setPage(') // pagination
+    expect(c).toContain('removeSelected') // multi-select delete
+    expect(c).toContain('optimistic: true')
+    expect(c).toContain("getRowId: (r) => String(r.id)") // uses the primary key
+    expect(c).toContain('role="alert"') // error state
+    expect(c).toContain('emptyMessage=') // empty state
+  })
+
+  it('the generated page is syntactically valid Svelte (compiles)', () => {
+    // Compile with Svelte's own compiler - validates markup, runes, bindings,
+    // and snippets. (It does not resolve imports; that's the bundler's job.)
+    const page = byPath['src/routes/customers/+page.svelte']!.contents
+    expect(() => compile(page, { filename: '+page.svelte', generate: 'client' })).not.toThrow()
+  })
+
+  it('wraps every file body in managed markers', () => {
+    for (const f of files) {
+      expect(f.contents).toContain(MANAGED_START)
+      expect(f.contents).toContain(MANAGED_END)
+    }
+  })
+
+  it('emits a connected +server.ts for a database dialect', () => {
+    const pg = scaffold(schema, { dataSource: 'postgres' }).files.find(
+      (f) => f.path === 'src/routes/api/customers/+server.ts',
+    )!.contents
+    expect(pg).toContain("import pg from 'pg'")
+    expect(pg).toContain('new pg.Pool({ connectionString: process.env.DATABASE_URL })')
+    expect(pg).toContain('createSqlDataSource')
+    expect(pg).toContain("placeholders: '$'")
+    expect(pg).toContain('await pool.query(text, params)')
+
+    const sqlite = scaffold(schema, { dataSource: 'sqlite' }).files.find((f) =>
+      f.path.endsWith('+server.ts'),
+    )!.contents
+    expect(sqlite).toContain("import Database from 'better-sqlite3'")
+    expect(sqlite).toContain('db.prepare(text).all(...params)')
+
+    const mssql = scaffold(schema, { dataSource: 'mssql' }).files.find((f) =>
+      f.path.endsWith('+server.ts'),
+    )!.contents
+    expect(mssql).toContain("import mssql from 'mssql'")
+    expect(mssql).toContain("placeholders: '@'")
+
+    // supabase reuses the postgres driver
+    const supa = scaffold(schema, { dataSource: 'supabase' }).files.find((f) =>
+      f.path.endsWith('+server.ts'),
+    )!.contents
+    expect(supa).toContain("import pg from 'pg'")
+  })
+
+  it('honors route/apiRoute overrides', () => {
+    const { files: f2 } = scaffold(schema, { route: 'clients', apiRoute: '/data/clients' })
+    const paths = f2.map((x) => x.path)
+    expect(paths).toContain('src/routes/clients/+page.svelte')
+    expect(paths).toContain('src/routes/data/clients/+server.ts')
+  })
+
+  it('the base page (no relations) has no lookup wiring', () => {
+    const c = byPath['src/routes/customers/+page.svelte']!.contents
+    expect(c).not.toContain('createRelationLookup')
+    expect(c).not.toContain('lookups={lookups}')
+  })
+})
+
+describe('scaffold with relation fields', () => {
+  const relSchema: EntitySchema = {
+    name: 'contacts',
+    label: 'Contact',
+    idField: 'id',
+    fields: [
+      { field: 'id', type: 'number', primaryKey: true, readonly: true },
+      { field: 'name', type: 'text', required: true },
+      { field: 'companyId', type: 'relation', label: 'Company', relation: { entity: 'companies', foreignKey: 'companyId', labelField: 'name' } },
+    ],
+  }
+  const page = scaffold(relSchema).files.find((f) => f.path === 'src/routes/contacts/+page.svelte')!.contents
+
+  it('generates a lookup over the related API route and wires it into the edit panel', () => {
+    expect(page).toContain('createRelationLookup')
+    expect(page).toContain('createKitDataSource({ endpoint: "/api/companies" })')
+    expect(page).toContain('labelField: "name"')
+    expect(page).toContain('const lookups = { "companyId": companyIdLookup }')
+    expect(page).toContain('lookups={lookups}')
+  })
+
+  it('the page with lookups is valid Svelte (compiles)', () => {
+    expect(() => compile(page, { filename: '+page.svelte', generate: 'client' })).not.toThrow()
+  })
+})
+
+describe('mergeManaged', () => {
+  it('uses the generated file whole when there is no existing content', () => {
+    const gen = `head\n${MANAGED_START}\nX\n${MANAGED_END}\ntail`
+    expect(mergeManaged(null, gen)).toBe(gen)
+  })
+
+  it('replaces only the managed region, preserving user edits outside', () => {
+    const existing = `import x\n${MANAGED_START}\nOLD\n${MANAGED_END}\n// my custom helper\nconst keep = 1`
+    const generated = `import y\n${MANAGED_START}\nNEW\n${MANAGED_END}\nignored tail`
+    const merged = mergeManaged(existing, generated)
+    expect(merged).toContain('import x') // user's import kept
+    expect(merged).toContain('// my custom helper') // user's code kept
+    expect(merged).toContain('const keep = 1')
+    expect(merged).toContain('NEW') // managed region updated
+    expect(merged).not.toContain('OLD')
+    expect(merged).not.toContain('ignored tail')
+  })
+
+  it('falls back to generated when existing has no markers', () => {
+    expect(mergeManaged('no markers here', 'GEN')).toBe('GEN')
+  })
+})