@svgrid/enterprise 2.0.4 → 2.2.1

package/src/studio/emit-project.test.ts

@@ -1,8 +1,34 @@
 import { describe, expect, it } from 'vitest'
 import { compile } from 'svelte/compiler'
 import type { EntitySchema } from '../schema'
-import { addBlock, addTabBlock, createProject, parseProject, setDeployTarget, setEntityDataSource, setShell, setTheme, setThemePreset, updateBlock, updateScreen, type GridConfig, type MasterDetailConfig, type TabsConfig, type StudioProject } from './project'
-import { emitStudioProject, emitStudioAppBundle, studioDeployInfo } from './emit-project'
+import { addBlock, addComponentBlock, addFreestandingScreen, addScreenAction, addTabBlock, addAccordionBlock, addAccordionComponent, createProject, enableScreenCode, flattenBlocks, parseProject, serializeProject, addStateVar, setScreenLayout, setLayoutOpts, setScreenDock, setDockPaneTitle, dockPaneTitleOf, syncDockPanes, dockPaneIds, removeBlock, setAuth, setComponentBinding, setDataLayer, setDeployTarget, setEntityDataSource, setTrigger, setHandlerBody, setHandlerSteps, stepsToCode, clickSlot, setScreenHandlersSource, setScreenRenderGrid, setShell, setTheme, setThemePreset, updateBlock, updateScreen, type GridConfig, type MasterDetailConfig, type TabsConfig, type AccordionConfig, type StudioProject } from './project'
+import ts from 'typescript'
+import { emitStudioProject, emitStudioAppBundle, studioDeployInfo, ctxCompletions, ctxAmbientDts } from './emit-project'
+import { UI_COMPONENT_REGISTRY } from './ui-components'
+
+/** Type-check a handler BODY against a generated ambient ctx `.d.ts` using the real
+ *  TypeScript compiler - the same surface the in-editor language service uses.
+ *  Returns main.ts diagnostics (empty = clean). Mirrors the editor's function wrap. */
+function typeCheckBody(dts: string, body: string): string[] {
+  const PRE = 'async function __run(ctx: PageContext): Promise<void> {\n'
+  const files: Record<string, string> = { 'env.d.ts': dts, 'main.ts': `${PRE}${body}\n}\n` }
+  const options: ts.CompilerOptions = {
+    target: ts.ScriptTarget.ES2021, lib: ['lib.es2021.d.ts', 'lib.dom.d.ts'],
+    module: ts.ModuleKind.ESNext, strict: false, noEmit: true, skipLibCheck: true, types: [],
+  }
+  const host = ts.createCompilerHost(options, true)
+  const origGet = host.getSourceFile.bind(host)
+  const origRead = host.readFile.bind(host)
+  const origExists = host.fileExists.bind(host)
+  host.getSourceFile = (name, langOrOpts, onErr, shouldCreate) =>
+    files[name] != null ? ts.createSourceFile(name, files[name], langOrOpts, true) : origGet(name, langOrOpts, onErr, shouldCreate)
+  host.readFile = (name) => files[name] ?? origRead(name)
+  host.fileExists = (name) => files[name] != null || origExists(name)
+  const program = ts.createProgram(['env.d.ts', 'main.ts'], options, host)
+  const main = program.getSourceFile('main.ts')
+  return [...program.getSemanticDiagnostics(main), ...program.getSyntacticDiagnostics(main)]
+    .map((d) => ts.flattenDiagnosticMessageText(d.messageText, '\n'))
+}
 
 const customers: EntitySchema = {
   name: 'customers', label: 'Customer', idField: 'id',
@@ -134,6 +160,25 @@ describe('emitStudioProject (per-block screens)', () => {
     expect(() => compile(page, { filename: 'customers/+page.svelte', generate: 'client' })).not.toThrow()
   })
 
+  it('Accordion block: nests display blocks + components into SvAccordion sections', () => {
+    let p = createProject([customers])
+    const sid = p.screens[0]!.id
+    p = addBlock(p, sid, 'accordion')
+    const ab = p.screens.find((s) => s.id === sid)!.blocks.find((b) => b.config.kind === 'accordion')!
+    let cfg = addAccordionBlock(ab.config as AccordionConfig, 0, 'chart', customers)   // display child
+    cfg = addAccordionComponent(cfg, 1, 'badge')                                       // component child
+    p = updateBlock(p, sid, ab.id, { config: cfg })
+    const page = emitStudioProject(p).find((f) => f.path === 'src/routes/customers/+page.svelte')!.contents
+    expect(page).toMatch(/import \{[^}]*SvAccordion[^}]*\} from '@svgrid\/grid'/)
+    expect(page).toMatch(/import \{[^}]*SvBadge[^}]*\} from '@svgrid\/grid'/)  // nested component imported
+    expect(page).toContain('{#snippet panel(item)}')
+    expect(page).toContain('expandMode="single"')
+    expect(page).toContain('<SvSchemaChart')                        // display child renders
+    expect(page).toContain('<SvBadge')                              // component child renders
+    expect(page).toMatch(/let accOpen_\w+ = \$state<string\[\]>\(\['/)  // expanded-ids state var
+    expect(() => compile(page, { filename: 'customers/+page.svelte', generate: 'client' })).not.toThrow()
+  })
+
   it('a chart-only screen has no controller/edit modal', () => {
     let p = createProject([customers])
     const sid = p.screens[0]!.id
@@ -282,7 +327,10 @@ describe('emitStudioProject (per-block screens)', () => {
 
   it('RBAC: emits access.ts, gates the UI, guards the server route + nav, and compiles', () => {
     let p = createProject([customers, orders])
-    p = setEntityDataSource(p, 'orders', { kind: 'sql', table: 'orders', dialect: 'postgres' }) // gets a +server.ts
+    // Both entities get a +server.ts, so we can prove each route's authorize call
+    // is bound to ITS OWN entity's screen id, not a shared/blanket value.
+    p = setEntityDataSource(p, 'customers', { kind: 'sql', table: 'customers', dialect: 'postgres' })
+    p = setEntityDataSource(p, 'orders', { kind: 'sql', table: 'orders', dialect: 'postgres' })
     p = { ...p, access: { enabled: true, defaultRole: 'viewer', roles: [
       { role: 'admin', screens: '*', actions: '*' },
       { role: 'viewer', screens: ['customers'], actions: [] },
@@ -294,14 +342,23 @@ describe('emitStudioProject (per-block screens)', () => {
     expect(access).toContain('export const currentRole = writable<AppRole>("viewer")')
     expect(access).toContain('export function authorizeAction')
     expect(access).toContain('export function getServerRole')
+    // Reads are gated by screen access now (server-enforced), not blanket-allowed:
+    // an entity with no bound screen (e.g. a lookup-only relation target) stays
+    // open since there's nothing to gate it by.
+    expect(access).toContain("if (action !== 'read') return can(role, action)")
+    expect(access).toContain('if (screenIds.length === 0) return true')
+    expect(access).toContain('return screenIds.some((id) => canScreen(role, id))')
 
     const page = files.find((f) => f.path === 'src/routes/customers/+page.svelte')!.contents
     expect(page).toContain("import { currentRole, can } from '$lib/access'")
     expect(page).toContain("{#if can($currentRole, 'create')}") // New button gated
     expect(page).toContain("if (can($currentRole, 'update'))")   // edit gated
 
-    const route = files.find((f) => f.path === 'src/routes/api/orders/+server.ts')!.contents
-    expect(route).toContain('authorize: ({ action, event }) => authorizeAction(getServerRole(event), action)')
+    // Each entity's route carries its OWN screen id(s) - not a shared/static value.
+    const customersRoute = files.find((f) => f.path === 'src/routes/api/customers/+server.ts')!.contents
+    expect(customersRoute).toContain('authorize: ({ action, event }) => authorizeAction(getServerRole(event), action, ["customers"])')
+    const ordersRoute = files.find((f) => f.path === 'src/routes/api/orders/+server.ts')!.contents
+    expect(ordersRoute).toContain('authorize: ({ action, event }) => authorizeAction(getServerRole(event), action, ["orders"])')
 
     const layout = files.find((f) => f.path === 'src/routes/+layout.svelte')!.contents
     expect(layout).toContain('canScreen($currentRole, item.id)') // nav hides forbidden screens
@@ -319,6 +376,265 @@ describe('emitStudioProject (per-block screens)', () => {
     expect(page).not.toContain('$currentRole')
   })
 
+  it('Auth: scaffolds session + hooks + login + seed users, closes the RBAC loop, and compiles', () => {
+    let p = createProject([customers])
+    p = { ...p, access: { enabled: true, defaultRole: 'viewer', roles: [
+      { role: 'admin', screens: '*', actions: '*' },
+      { role: 'viewer', screens: ['customers'], actions: [] },
+    ] } }
+    p = setAuth(p, { enabled: true })
+    const files = emitStudioProject(p)
+    const get = (path: string) => files.find((f) => f.path === path)?.contents
+
+    // The whole starter is emitted.
+    for (const path of ['src/lib/server/auth.ts', 'src/lib/server/users.ts', 'src/hooks.server.ts', 'src/auth.d.ts', 'src/routes/+layout.server.ts', 'src/routes/login/+page.svelte', 'src/routes/login/+page.server.ts', 'src/routes/logout/+page.server.ts']) {
+      expect(files.find((f) => f.path === path), path).toBeTruthy()
+    }
+    // SESSION_SECRET merges into the single shared .env.example (bundle level).
+    const envEx = emitStudioAppBundle(p).filter((f) => f.path === '.env.example')
+    expect(envEx).toHaveLength(1)
+    expect(envEx[0]!.contents).toContain('SESSION_SECRET')
+    // hooks resolves the session into event.locals.role - the value getServerRole reads.
+    expect(get('src/hooks.server.ts')).toContain('event.locals.role = user?.role')
+    // Dependency-free crypto (no external auth lib).
+    expect(get('src/lib/server/auth.ts')).toContain('crypto.subtle')
+    expect(get('src/lib/server/auth.ts')).toContain('export async function signSession')
+    // One demo user per RBAC role.
+    expect(get('src/lib/server/users.ts')).toContain('admin@example.com')
+    expect(get('src/lib/server/users.ts')).toContain('viewer@example.com')
+    // Protect-by-default guards the app in the root server load.
+    expect(get('src/routes/+layout.server.ts')).toContain("throw redirect(302, '/login?redirectTo='")
+    // Login form action signs + sets the session cookie.
+    expect(get('src/routes/login/+page.server.ts')).toContain('cookies.set(SESSION_COOKIE')
+    // The shell wires the session in: login bypass, real user, sign-out, role seed.
+    const layout = get('src/routes/+layout.svelte')!
+    expect(layout).toContain('["/login"].includes($page.url.pathname)') // login renders bare (no shell)
+    expect(layout).toContain('action="/logout"')
+    expect(layout).toContain('currentRole.set(data.role')
+    expect(layout).toContain('data?.user?.email')
+
+    for (const f of files.filter((f) => f.path.endsWith('.svelte'))) {
+      expect(() => compile(f.contents, { filename: f.path, generate: 'client' }), f.path).not.toThrow()
+    }
+  })
+
+  // A SQL entity with a NUMBER primary key + a db-column alias, to exercise the
+  // serial / autoincrement + dbColumn mapping paths.
+  const products: EntitySchema = {
+    name: 'products', label: 'Product', idField: 'id',
+    fields: [
+      { field: 'id', type: 'number', primaryKey: true },
+      { field: 'title', type: 'text' },
+      { field: 'price', type: 'number' },
+      { field: 'inStock', type: 'boolean', dbColumn: 'in_stock' },
+    ],
+  }
+
+  it('Data layer: Drizzle schema + typed repos + migrations config for SQL entities', () => {
+    let p = createProject([products])
+    p = setEntityDataSource(p, 'products', { kind: 'sql', table: 'products_tbl', dialect: 'postgres' })
+    p = setDataLayer(p, true)
+    const files = emitStudioProject(p)
+    const get = (path: string) => files.find((f) => f.path === path)?.contents
+
+    for (const path of ['src/lib/server/db/schema.ts', 'src/lib/server/db/index.ts', 'src/lib/server/db/products.ts', 'drizzle.config.ts']) {
+      expect(files.find((f) => f.path === path), path).toBeTruthy()
+    }
+    const schema = get('src/lib/server/db/schema.ts')!
+    expect(schema).toContain("from 'drizzle-orm/pg-core'")
+    expect(schema).toContain('pgTable("products_tbl"')                  // real DB table name
+    expect(schema).toContain('"id": serial("id").primaryKey()')         // number PK -> serial
+    expect(schema).toContain('"inStock": boolean("in_stock")')          // dbColumn alias
+    expect(schema).toContain('typeof products.$inferSelect')
+    // A typed repo with returning-based CRUD, id typed from the PK.
+    const repo = get('src/lib/server/db/products.ts')!
+    expect(repo).toContain('export const productsRepo')
+    expect(repo).toContain('.returning()).at(0)!')
+    expect(repo).toContain('get: async (id: number)')
+    // drizzle-kit migration config + client.
+    expect(get('drizzle.config.ts')).toContain("dialect: 'postgresql'")
+    expect(get('src/lib/server/db/index.ts')).toContain('drizzle-orm/node-postgres')
+  })
+
+  it('Data layer: package.json wires drizzle deps + migration scripts; SQLite maps a number id to autoincrement', () => {
+    let p = createProject([products])
+    p = setEntityDataSource(p, 'products', { kind: 'sql', table: 'products', dialect: 'sqlite' })
+    p = setDataLayer(p, true)
+    const files = emitStudioAppBundle(p)
+    const pkg = JSON.parse(files.find((f) => f.path === 'package.json')!.contents)
+    expect(pkg.dependencies['drizzle-orm']).toBeTruthy()
+    expect(pkg.devDependencies['drizzle-kit']).toBeTruthy()
+    expect(pkg.scripts['db:generate']).toBe('drizzle-kit generate')
+    expect(pkg.scripts['db:migrate']).toBe('drizzle-kit migrate')
+    const schema = files.find((f) => f.path === 'src/lib/server/db/schema.ts')!.contents
+    expect(schema).toContain("from 'drizzle-orm/sqlite-core'")
+    expect(schema).toContain('integer("id").primaryKey({ autoIncrement: true })')
+  })
+
+  it('no data layer without the toggle, without a SQL entity, or on an unsupported dialect', () => {
+    // Off by default.
+    let sqlOnly = setEntityDataSource(createProject([customers]), 'customers', { kind: 'sql', table: 'customers', dialect: 'postgres' })
+    expect(emitStudioProject(sqlOnly).find((f) => f.path === 'src/lib/server/db/schema.ts')).toBeUndefined()
+    // Toggle on but no SQL entity (memory source) -> nothing.
+    expect(emitStudioProject(setDataLayer(createProject([customers]), true)).find((f) => f.path.startsWith('src/lib/server/db/'))).toBeUndefined()
+    // Toggle on + MSSQL (Drizzle has no SQL Server driver) -> raw route only, no Drizzle layer.
+    const mssql = setDataLayer(setEntityDataSource(createProject([customers]), 'customers', { kind: 'sql', table: 'customers', dialect: 'mssql' }), true)
+    expect(emitStudioProject(mssql).find((f) => f.path === 'src/lib/server/db/schema.ts')).toBeUndefined()
+  })
+
+  it('Data layer: MySQL emits a re-select repo (no RETURNING) + int autoincrement PK', () => {
+    let p = createProject([products])
+    p = setEntityDataSource(p, 'products', { kind: 'sql', table: 'products', dialect: 'mysql' })
+    p = setDataLayer(p, true)
+    const files = emitStudioProject(p)
+    const schema = files.find((f) => f.path === 'src/lib/server/db/schema.ts')!.contents
+    expect(schema).toContain("from 'drizzle-orm/mysql-core'")
+    expect(schema).toContain('int("id").autoincrement().primaryKey()')
+    const repo = files.find((f) => f.path === 'src/lib/server/db/products.ts')!.contents
+    expect(repo).toContain('async function getById')           // re-select helper
+    expect(repo).toContain('.insertId')                        // uses the insert id
+    expect(repo).not.toContain('.returning()')                 // MySQL has none
+  })
+
+  it('DB-backed auth: auth + data layer moves the user store into an auth_users table (hashed)', () => {
+    let p = createProject([products])
+    p = setEntityDataSource(p, 'products', { kind: 'sql', table: 'products', dialect: 'postgres' })
+    p = setDataLayer(p, true)
+    p = setAuth(p, { enabled: true })
+    const files = emitStudioProject(p)
+    // The auth_users table lives in the same Drizzle schema (one migration covers it).
+    expect(files.find((f) => f.path === 'src/lib/server/db/schema.ts')!.contents).toContain('authUsers = pgTable("auth_users"')
+    // users.ts queries the DB + seeds once; login verifies the PBKDF2 hash.
+    const users = files.find((f) => f.path === 'src/lib/server/users.ts')!.contents
+    expect(users).toContain("from './db/schema'")
+    expect(users).toContain('function ensureSeeded')
+    expect(users).toContain('passwordHash: await hashPassword(u.password)')
+    const login = files.find((f) => f.path === 'src/routes/login/+page.server.ts')!.contents
+    expect(login).toContain('const user = await findUser(email)')
+    expect(login).toContain('await verifyPassword(password, user.passwordHash)')
+    // Without the data layer, auth stays on the in-code demo store.
+    const inCode = emitStudioProject(setAuth(createProject([products]), { enabled: true }))
+    expect(inCode.find((f) => f.path === 'src/lib/server/users.ts')!.contents).toContain('export const USERS')
+  })
+
+  it('Auth depth: register + password reset + change-password + admin user management (DB-backed)', () => {
+    let p = createProject([products])
+    p = { ...p, access: { enabled: true, defaultRole: 'viewer', roles: [
+      { role: 'admin', screens: '*', actions: '*' },
+      { role: 'viewer', screens: ['products'], actions: [] },
+    ] } }
+    p = setEntityDataSource(p, 'products', { kind: 'sql', table: 'products', dialect: 'postgres' })
+    p = setDataLayer(p, true)
+    p = setAuth(p, { enabled: true, register: true, userAdmin: true })
+    const files = emitStudioProject(p)
+    const get = (path: string) => files.find((f) => f.path === path)?.contents
+
+    // Change-password (any signed-in user), self-service sign-up + recovery, admin screen.
+    for (const path of ['src/routes/account/+page.server.ts', 'src/routes/register/+page.server.ts', 'src/routes/forgot-password/+page.server.ts', 'src/routes/reset-password/+page.server.ts', 'src/routes/users/+page.server.ts', 'src/routes/users/+page.svelte']) {
+      expect(files.find((f) => f.path === path), path).toBeTruthy()
+    }
+    // Registration assigns the (least-privileged) default role.
+    expect(get('src/routes/register/+page.server.ts')).toContain('role: "viewer"')
+    // Password recovery uses signed reset tokens + an email stub (no extra table).
+    expect(get('src/lib/server/auth.ts')).toContain('export async function signReset')
+    expect(get('src/lib/server/auth.ts')).toContain('export async function sendResetEmail')
+    // User admin is role-gated server-side (only a full-access role can manage users).
+    expect(get('src/routes/users/+page.server.ts')).toContain("canScreen(getServerRole(event), '__users__')")
+    // The DB store gained full CRUD.
+    const users = get('src/lib/server/users.ts')!
+    for (const fn of ['createUser', 'updatePassword', 'setUserRole', 'deleteUser', 'listUsers']) expect(users).toContain(`export async function ${fn}`)
+    // Nav gains the admin Users screen (canScreen-gated); the auth pages render bare.
+    const layout = get('src/routes/+layout.svelte')!
+    expect(layout).toContain('"/users"')
+    expect(layout).toContain('"/register"') // bare-render set includes the sign-up flow
+    expect(get('src/routes/+layout.server.ts')).toContain('const PUBLIC = new Set(["/login","/register","/forgot-password","/reset-password"])')
+    expect(get('src/routes/login/+page.svelte')).toContain('href="/register"')
+
+    for (const f of files.filter((f) => f.path.endsWith('.svelte'))) {
+      expect(() => compile(f.contents, { filename: f.path, generate: 'client' }), f.path).not.toThrow()
+    }
+  })
+
+  it('Auth extras: OAuth (github/google/oidc) + email 2FA + real email, all DB-backed', () => {
+    let p = createProject([products])
+    p = { ...p, access: { enabled: true, defaultRole: 'viewer', roles: [{ role: 'admin', screens: '*', actions: '*' }, { role: 'viewer', screens: ['products'], actions: [] }] } }
+    p = setEntityDataSource(p, 'products', { kind: 'sql', table: 'products', dialect: 'postgres' })
+    p = setDataLayer(p, true)
+    p = setAuth(p, { enabled: true, oauth: ['github', 'google', 'oidc'], twoFactor: true })
+    const files = emitStudioProject(p)
+    const bundle = emitStudioAppBundle(p)
+    const get = (path: string) => files.find((f) => f.path === path)?.contents
+
+    // OAuth: shared provider module + a [provider] start + callback endpoint.
+    for (const path of ['src/lib/server/oauth.ts', 'src/routes/auth/[provider]/+server.ts', 'src/routes/auth/[provider]/callback/+server.ts']) {
+      expect(files.find((f) => f.path === path), path).toBeTruthy()
+    }
+    expect(get('src/lib/server/oauth.ts')).toContain('export async function pkceChallenge') // PKCE
+    expect(get('src/lib/server/oauth.ts')).toContain('.well-known/openid-configuration') // OIDC discovery (Azure AD)
+    expect(get('src/routes/auth/[provider]/+server.ts')).toContain('code_challenge_method')
+    expect(get('src/routes/auth/[provider]/+server.ts')).toContain('new Set<Provider>(["github", "google", "oidc"])')
+    expect(get('src/routes/login/+page.svelte')).toContain('/auth/github')
+
+    // Email 2FA: schema column, challenge helpers, login branch, verify route, account toggle.
+    expect(get('src/lib/server/db/schema.ts')).toContain('"twoFactor": boolean("two_factor").notNull().default(false)')
+    expect(get('src/lib/server/auth.ts')).toContain('export async function signChallenge')
+    expect(get('src/routes/login/+page.server.ts')).toContain('if (user.twoFactor)')
+    expect(files.find((f) => f.path === 'src/routes/login/verify/+page.server.ts')).toBeTruthy()
+    expect(get('src/lib/server/users.ts')).toContain('export async function setTwoFactor')
+
+    // Real email layer (2FA implies it) + nodemailer wired only as an optional SMTP dep.
+    expect(get('src/lib/server/email.ts')).toContain('api.resend.com')
+    expect(get('src/lib/server/email.ts')).toContain("await import('nodemailer')")
+    const pkg = JSON.parse(bundle.find((f) => f.path === 'package.json')!.contents)
+    expect(pkg.dependencies.nodemailer).toBeTruthy()
+    expect(pkg.devDependencies['@types/nodemailer']).toBeTruthy()
+    // .env.example documents the OAuth + email vars.
+    const env = bundle.find((f) => f.path === '.env.example')!.contents
+    expect(env).toContain('GITHUB_CLIENT_ID')
+    expect(env).toContain('OIDC_ISSUER')
+    expect(env).toMatch(/RESEND_API_KEY|SMTP_HOST/)
+
+    for (const f of files.filter((f) => f.path.endsWith('.svelte'))) {
+      expect(() => compile(f.contents, { filename: f.path, generate: 'client' }), f.path).not.toThrow()
+    }
+  })
+
+  it('Auth extras: OAuth / 2FA are inert without the DB-backed store', () => {
+    const p = setAuth(createProject([products]), { enabled: true, oauth: ['github'], twoFactor: true })
+    const files = emitStudioProject(p) // memory source -> no data layer
+    expect(files.find((f) => f.path === 'src/lib/server/oauth.ts')).toBeUndefined()
+    expect(files.find((f) => f.path === 'src/lib/server/email.ts')).toBeUndefined()
+    expect(files.find((f) => f.path === 'src/routes/login/verify/+page.server.ts')).toBeUndefined()
+    // Falls back to the in-code demo store + plain login.
+    expect(files.find((f) => f.path === 'src/routes/login/+page.server.ts')!.contents).not.toContain('user.twoFactor')
+  })
+
+  it('Auth depth: register/userAdmin are inert without the DB-backed store or RBAC', () => {
+    // register requested but no data layer -> no register routes (needs persistence).
+    const noDb = emitStudioProject(setAuth(createProject([products]), { enabled: true, register: true, userAdmin: true }))
+    expect(noDb.find((f) => f.path === 'src/routes/register/+page.server.ts')).toBeUndefined()
+    expect(noDb.find((f) => f.path === 'src/routes/users/+page.server.ts')).toBeUndefined()
+    // DB-backed but RBAC off -> register yes, userAdmin no (needs a role to gate on).
+    let p = setEntityDataSource(createProject([products]), 'products', { kind: 'sql', table: 'products', dialect: 'postgres' })
+    p = setAuth(setDataLayer(p, true), { enabled: true, register: true, userAdmin: true })
+    const files = emitStudioProject(p)
+    expect(files.find((f) => f.path === 'src/routes/register/+page.server.ts')).toBeTruthy()
+    expect(files.find((f) => f.path === 'src/routes/users/+page.server.ts')).toBeUndefined()
+  })
+
+  it('no auth files unless auth.enabled; protect:false drops the route guard', () => {
+    // Off by default.
+    expect(emitStudioProject(createProject([customers])).find((f) => f.path === 'src/hooks.server.ts')).toBeUndefined()
+    // protect:false still scaffolds login but does not force a redirect.
+    const p = setAuth(createProject([customers]), { enabled: true, protect: false })
+    const layoutServer = emitStudioProject(p).find((f) => f.path === 'src/routes/+layout.server.ts')!.contents
+    expect(layoutServer).not.toContain('throw redirect')
+    // Single admin seed user when RBAC is off.
+    const users = emitStudioProject(p).find((f) => f.path === 'src/lib/server/users.ts')!.contents
+    expect(users).toContain('admin@example.com')
+    expect(users).not.toContain('viewer@example.com')
+  })
+
   it('Audit: emits the store + route + viewer, wires connected routes, and compiles', () => {
     let p = createProject([customers, orders])
     p = setEntityDataSource(p, 'orders', { kind: 'sql', table: 'orders', dialect: 'postgres' })
@@ -457,6 +773,44 @@ describe('emitStudioProject (per-block screens)', () => {
     expect(parseProject(JSON.stringify(p)).deploy).toBeUndefined()
   })
 
+  it('Deploy pipeline: CI workflow always, a push-to-deploy workflow + DEPLOY.md + deploy script per target', () => {
+    const bundle = emitStudioAppBundle(setDeployTarget(createProject([customers]), 'vercel'))
+    const get = (p: string) => bundle.find((f) => f.path === p)?.contents
+    // Universal CI (robust without a committed lockfile).
+    const ci = get('.github/workflows/ci.yml')!
+    expect(ci).toContain('npm install')
+    expect(ci).not.toContain('npm ci')       // no lockfile is shipped
+    expect(ci).not.toContain('cache: npm')
+    expect(ci).toContain('npm run build')
+    // Push-to-deploy workflow, gated on the secret so an unconfigured repo stays green.
+    const deploy = get('.github/workflows/deploy.yml')!
+    expect(deploy).toContain("if: ${{ secrets.VERCEL_TOKEN != '' }}")
+    expect(deploy).toContain('vercel deploy --prebuilt --prod')
+    // Runbook + npm deploy script.
+    expect(get('DEPLOY.md')).toContain('VERCEL_TOKEN')
+    expect(JSON.parse(get('package.json')!).scripts.deploy).toBe('vercel deploy --prod')
+    // Designer panel exposes the required secrets.
+    expect(studioDeployInfo(setDeployTarget(createProject([customers]), 'vercel')).secrets).toEqual(['VERCEL_TOKEN', 'VERCEL_ORG_ID', 'VERCEL_PROJECT_ID'])
+  })
+
+  it('Deploy pipeline: node target ships a Dockerfile + .dockerignore and no deploy workflow', () => {
+    const bundle = emitStudioAppBundle(setDeployTarget(createProject([customers], { title: 'My App' }), 'node'))
+    expect(bundle.find((f) => f.path === 'Dockerfile')!.contents).toContain('CMD ["node", "build"]')
+    expect(bundle.find((f) => f.path === '.dockerignore')).toBeTruthy()
+    expect(bundle.find((f) => f.path === '.github/workflows/deploy.yml')).toBeUndefined() // self-hosted: no push-deploy
+    expect(bundle.find((f) => f.path === '.github/workflows/ci.yml')).toBeTruthy()        // ...but still CI
+    expect(bundle.find((f) => f.path === 'DEPLOY.md')!.contents).toContain('docker build')
+  })
+
+  it('Deploy pipeline: a single .env.example merges DATABASE_URL + SESSION_SECRET (no duplicate)', () => {
+    let p = setEntityDataSource(createProject([customers]), 'customers', { kind: 'sql', table: 'customers', dialect: 'postgres' })
+    p = setAuth(p, { enabled: true })
+    const envs = emitStudioAppBundle(p).filter((f) => f.path === '.env.example')
+    expect(envs).toHaveLength(1)
+    expect(envs[0]!.contents).toContain('DATABASE_URL')
+    expect(envs[0]!.contents).toContain('SESSION_SECRET')
+  })
+
   it('Round-trip: the exported bundle ships studio.config.json that re-parses into the designer', () => {
     const p = setShell(createProject([customers, orders]), { brand: 'Acme', logo: 'data:image/png;base64,AA' })
     const bundle = emitStudioAppBundle(p)
@@ -590,6 +944,220 @@ describe('emitStudioProject (per-block screens)', () => {
   })
 })
 
+describe('Custom actions', () => {
+  it('a toolbar action on an entity-bound screen emits a wired handler + button + stub route, and compiles', () => {
+    let p = createProject([customers])
+    const sid = p.screens[0]!.id
+    p = addScreenAction(p, sid, { label: 'Sync now', icon: '\u{1F504}', confirm: 'Sync now?' })
+    const actionId = p.screens[0]!.actions![0]!.id
+    const files = emitStudioProject(p)
+
+    const page = files.find((f) => f.path === 'src/routes/customers/+page.svelte')!.contents
+    expect(page).toContain(`let actionBusy_${actionId.replace(/-/g, '_')} = $state(false)`)
+    expect(page).toContain(`fetch('/api/actions/${actionId}'`)
+    expect(page).toContain('Sync now')
+    expect(page).toContain(`confirm('Sync now?')`)
+
+    const route = files.find((f) => f.path === `src/routes/api/actions/${actionId}/+server.ts`)!.contents
+    expect(route).toContain('export async function POST')
+    expect(route).toContain('TODO: your business logic here')
+
+    for (const f of files.filter((f) => f.path.endsWith('.svelte'))) {
+      expect(() => compile(f.contents, { filename: f.path, generate: 'client' }), f.path).not.toThrow()
+    }
+  })
+
+  it('a row-level custom action renders per row, wired to the same stub route, and compiles', () => {
+    let p = createProject([customers])
+    const sid = p.screens[0]!.id
+    const gridId = p.screens[0]!.blocks.find((b) => b.config.kind === 'grid')!.id
+    p = addScreenAction(p, sid, { label: 'Resend invoice' })
+    const actionId = p.screens[0]!.actions![0]!.id
+    p = updateScreen(p, sid, { actions: [] }) // the action now lives only on the row, not the toolbar
+    p = updateBlock(p, sid, gridId, { config: {
+      rowActions: [{ kind: 'custom', id: actionId, label: 'Resend invoice' }],
+    } as Partial<GridConfig> })
+    const files = emitStudioProject(p)
+
+    const page = files.find((f) => f.path === 'src/routes/customers/+page.svelte')!.contents
+    expect(page).toContain("id: '__actions'") // synthetic action column
+    expect(page).toContain(`runAction_${actionId.replace(/-/g, '_')}({ id: `)
+    expect(page).toContain('Resend invoice')
+
+    expect(files.find((f) => f.path === `src/routes/api/actions/${actionId}/+server.ts`)).toBeTruthy()
+
+    for (const f of files.filter((f) => f.path.endsWith('.svelte'))) {
+      expect(() => compile(f.contents, { filename: f.path, generate: 'client' }), f.path).not.toThrow()
+    }
+  })
+
+  it('a freestanding screen (no entity) renders a toolbar action and no grid/data plumbing, and compiles', () => {
+    let p = addFreestandingScreen(createProject([customers]), { title: 'Reports', route: 'reports' })
+    const sid = p.screens.find((s) => s.title === 'Reports')!.id
+    p = addScreenAction(p, sid, { label: 'Run report' })
+    const actionId = p.screens.find((s) => s.id === sid)!.actions![0]!.id
+    const files = emitStudioProject(p)
+
+    const page = files.find((f) => f.path === 'src/routes/reports/+page.svelte')!.contents
+    expect(page).toContain('Run report')
+    expect(page).toContain(`fetch('/api/actions/${actionId}'`)
+    expect(page).not.toContain('createServerDataSource')
+    expect(page).not.toContain('<SvGrid')
+
+    for (const f of files.filter((f) => f.path.endsWith('.svelte'))) {
+      expect(() => compile(f.contents, { filename: f.path, generate: 'client' }), f.path).not.toThrow()
+    }
+  })
+
+  it('RBAC-gated action: the toolbar button and the stub route both check canScreen', () => {
+    let p = addFreestandingScreen(createProject([customers]), { title: 'Reports', route: 'reports' })
+    const sid = p.screens.find((s) => s.title === 'Reports')!.id
+    p = addScreenAction(p, sid, { label: 'Run report' })
+    const actionId = p.screens.find((s) => s.id === sid)!.actions![0]!.id
+    p = { ...p, access: { enabled: true, defaultRole: 'viewer', roles: [
+      { role: 'admin', screens: '*', actions: '*' },
+      { role: 'viewer', screens: [], actions: [] },
+    ] } }
+    const files = emitStudioProject(p)
+
+    const page = files.find((f) => f.path === 'src/routes/reports/+page.svelte')!.contents
+    expect(page).toContain(`{#if canScreen($currentRole, '${sid}')}`)
+
+    const route = files.find((f) => f.path === `src/routes/api/actions/${actionId}/+server.ts`)!.contents
+    expect(route).toContain("import { getServerRole, canScreen } from '$lib/access'")
+    expect(route).toContain(`if (!canScreen(getServerRole(event), '${sid}'))`)
+    expect(route).toContain('status: 403')
+
+    for (const f of files.filter((f) => f.path.endsWith('.svelte'))) {
+      expect(() => compile(f.contents, { filename: f.path, generate: 'client' }), f.path).not.toThrow()
+    }
+  })
+})
+
+describe('Component blocks', () => {
+  it('a component block mixed onto an entity-bound screen emits the import + literal markup, and compiles', () => {
+    let p = createProject([customers])
+    const sid = p.screens[0]!.id
+    p = addComponentBlock(p, sid, 'button', { variant: 'primary', block: true }, 0)
+    const files = emitStudioProject(p)
+
+    const page = files.find((f) => f.path === 'src/routes/customers/+page.svelte')!.contents
+    const importLine = page.split('\n').find((l) => l.includes("from '@svgrid/grid'"))!
+    expect(importLine).toContain('SvButton') // merged into the screen's one @svgrid/grid import
+    expect(page).toContain("<SvButton variant={'primary'} size={'md'} block>{'Click me'}</SvButton>")
+
+    for (const f of files.filter((f) => f.path.endsWith('.svelte'))) {
+      expect(() => compile(f.contents, { filename: f.path, generate: 'client' }), f.path).not.toThrow()
+    }
+  })
+
+  it('a freestanding screen with component blocks emits deduped imports + markup for each, and compiles', () => {
+    let p = addFreestandingScreen(createProject([customers]), { title: 'Reports', route: 'reports' })
+    const sid = p.screens.find((s) => s.title === 'Reports')!.id
+    p = addComponentBlock(p, sid, 'button', { variant: 'secondary' })
+    p = addComponentBlock(p, sid, 'badge', { variant: 'success' })
+    const files = emitStudioProject(p)
+
+    const page = files.find((f) => f.path === 'src/routes/reports/+page.svelte')!.contents
+    expect(page).toContain("import { SvBadge, SvButton } from '@svgrid/grid'") // sorted, deduped
+    expect(page).toContain("<SvButton variant={'secondary'} size={'md'}>{'Click me'}</SvButton>")
+    expect(page).toContain("<SvBadge variant={'success'} size={'md'} pill>{'Badge'}</SvBadge>")
+    expect(page).not.toContain('Add your own content here')
+
+    for (const f of files.filter((f) => f.path.endsWith('.svelte'))) {
+      expect(() => compile(f.contents, { filename: f.path, generate: 'client' }), f.path).not.toThrow()
+    }
+  })
+
+  it('an empty freestanding screen (no blocks) still emits the placeholder comment', () => {
+    const p = addFreestandingScreen(createProject([customers]), { title: 'Reports', route: 'reports' })
+    const page = emitStudioProject(p).find((f) => f.path === 'src/routes/reports/+page.svelte')!.contents
+    expect(page).toContain('Add your own content here')
+  })
+
+  it('a component with a free-typed label containing quotes/braces cannot break out of the markup, and compiles', () => {
+    let p = createProject([customers])
+    const sid = p.screens[0]!.id
+    p = addComponentBlock(p, sid, 'button', { _content: `it's a "test" {value}` }, 0)
+    const files = emitStudioProject(p)
+    const page = files.find((f) => f.path === 'src/routes/customers/+page.svelte')!.contents
+    expect(() => compile(page, { filename: 'page.svelte', generate: 'client' })).not.toThrow()
+  })
+
+  it('component props bound to data emit reactive expressions over allRows (aggregate / field / expr), get no code handle, and compile', () => {
+    let p = createProject([customers])
+    const sid = p.screens[0]!.id
+    const flat = () => flattenBlocks(p.screens.find((s) => s.id === sid)!.blocks).filter((b) => b.config.kind === 'component')
+
+    p = addComponentBlock(p, sid, 'stat', { label: 'Total spend' })
+    const stat = flat()[0]!
+    p = setComponentBinding(p, sid, stat.id, 'value', { kind: 'aggregate', field: 'spend', reduce: 'sum' })
+
+    p = addComponentBlock(p, sid, 'badge', { _content: 'tier' })
+    const badge = flat()[1]!
+    p = setComponentBinding(p, sid, badge.id, '_content', { kind: 'field', field: 'tier' })
+
+    p = addComponentBlock(p, sid, 'progress', { value: 0, max: 100 })
+    const prog = flat()[2]!
+    p = setComponentBinding(p, sid, prog.id, 'value', { kind: 'expr', code: 'rows.filter((r) => r.spend > 100).length' })
+
+    const files = emitStudioProject(p)
+    const page = files.find((f) => f.path === 'src/routes/customers/+page.svelte')!.contents
+
+    // aggregate -> reduceValue over allRows; imported once.
+    expect(page).toContain("value={(reduceValue(allRows, { measure: 'spend', reduce: 'sum' })).toLocaleString()}")
+    expect(page).toMatch(/import \{[^}]*reduceValue[^}]*\} from '@svgrid\/enterprise'/)
+    // field -> first row's value.
+    expect(page).toContain("{String(allRows[0]?.['tier'] ?? '')}")
+    // expr -> the user code wrapped with rows = allRows.
+    expect(page).toContain('value={((rows) => (rows.filter((r) => r.spend > 100).length))(allRows)}')
+    // the screen loads every row for the bindings.
+    expect(page).toContain('async function loadAll()')
+    // bound components are static reactive markup, not code handles.
+    expect(page).not.toContain('= handle(')
+
+    for (const f of files.filter((f) => f.path.endsWith('.svelte'))) {
+      expect(() => compile(f.contents, { filename: f.path, generate: 'client' }), f.path).not.toThrow()
+    }
+  })
+
+  it('every registry component codegens to a page that compiles, from the full UI kit', () => {
+    let p = addFreestandingScreen(createProject([customers]), { title: 'Sink', route: 'sink' })
+    const sid = p.screens.find((s) => s.title === 'Sink')!.id
+    for (const spec of UI_COMPONENT_REGISTRY) p = addComponentBlock(p, sid, spec.key)
+    const files = emitStudioProject(p)
+    const page = files.find((f) => f.path === 'src/routes/sink/+page.svelte')!.contents
+    // The kit spans well beyond the original eight (inputs, nav, display, ...).
+    expect(UI_COMPONENT_REGISTRY.length).toBeGreaterThanOrEqual(24)
+    // Every importName is present in the single @svgrid/grid import.
+    for (const spec of UI_COMPONENT_REGISTRY) expect(page).toContain(spec.importName)
+    for (const f of files.filter((f) => f.path.endsWith('.svelte'))) {
+      expect(() => compile(f.contents, { filename: f.path, generate: 'client' }), f.path).not.toThrow()
+    }
+  })
+
+  it('array/object "fixed" props (Timeline items, Sparkline data) emit verbatim, not stringified', () => {
+    let p = addFreestandingScreen(createProject([customers]), { title: 'Viz', route: 'viz' })
+    const sid = p.screens.find((s) => s.title === 'Viz')!.id
+    p = addComponentBlock(p, sid, 'timeline')
+    p = addComponentBlock(p, sid, 'sparkline', { type: 'line' })
+    const page = emitStudioProject(p).find((f) => f.path === 'src/routes/viz/+page.svelte')!.contents
+    expect(page).toContain("items={[{ title: 'Order placed'")   // real array expression
+    expect(page).toContain('data={[4, 8, 5, 9')                 // real number array
+    expect(page).not.toContain("items={'[")                      // never quoted as a string
+  })
+
+  it('an unrecognized component key emits a harmless placeholder comment instead of throwing', () => {
+    let p = addFreestandingScreen(createProject([customers]), { title: 'Reports', route: 'reports' })
+    const sid = p.screens.find((s) => s.title === 'Reports')!.id
+    p = addComponentBlock(p, sid, 'not-a-real-component', {})
+    const files = emitStudioProject(p)
+    const page = files.find((f) => f.path === 'src/routes/reports/+page.svelte')!.contents
+    expect(page).toContain('unknown component "not-a-real-component"')
+    expect(() => compile(page, { filename: 'page.svelte', generate: 'client' })).not.toThrow()
+  })
+})
+
 describe('data-source codegen', () => {
   const byPathOf = (files: ReturnType<typeof emitStudioProject>, path: string) => files.find((f) => f.path === path)
 
@@ -745,6 +1313,22 @@ describe('grid editing (a Grid property) -> codegen', () => {
     expect(page).toContain('controller.setFilter')
   })
 
+  it('filterUi picks the filter surfaces (row / menu / global); default is the global search', () => {
+    // Default (no filterUi) -> global search only.
+    const dflt = pageFor(withGrid({ filterable: true }))
+    expect(dflt).toContain('showGlobalFilter')
+    expect(dflt).not.toContain('showFilterRow')
+    expect(dflt).not.toContain('showFilterMenu')
+    // Explicit row + menu (no global).
+    const rm = pageFor(withGrid({ filterable: true, filterUi: { row: true, menu: true } }))
+    expect(rm).toContain('showFilterRow')
+    expect(rm).toContain('showFilterMenu')
+    expect(rm).not.toContain('showGlobalFilter')
+    // Column filters still flow to the server controller.
+    expect(rm).toContain('externalFilter')
+    expect(rm).toContain('onFiltersChange')
+  })
+
   it('form presentation is honored', () => {
     expect(pageFor(withGrid({ formPresentation: 'drawer' }))).toContain('presentation="drawer"')
   })
@@ -761,10 +1345,10 @@ describe('grid editing (a Grid property) -> codegen', () => {
     expect(page).toContain('rowHeight={28}')
   })
 
-  it('normal density + defaults emit no rowHeight and totals off', () => {
+  it('normal density emits the standard 30px row height (consistent with master-detail) + totals off', () => {
     const page = pageFor(createProject([customers]))
     expect(page).toContain('enableRowSummaries={false}')
-    expect(page).not.toContain('rowHeight=')
+    expect(page).toContain('rowHeight={30}')
   })
 
   it('per-column header / width / align overrides flow into the columns', () => {
@@ -810,6 +1394,443 @@ describe('grid editing (a Grid property) -> codegen', () => {
     expect(page).toContain("initialColumnPinning={{ left: ['name'] }}")
     expect(page).toContain('columnVirtualization={false}')
   })
+
+  it('row grouping switches the grid to full-client mode + seeds setGroupBy + rolls up column aggregates', () => {
+    let p = createProject([customers])
+    const sid = p.screens[0]!.id
+    const gid = p.screens[0]!.blocks[0]!.id
+    const cfg = p.screens[0]!.blocks[0]!.config as GridConfig
+    const columns = cfg.columns.map((c) => (c.field === 'mrr' ? { ...c, aggregate: 'sum' as const } : c))
+    p = updateBlock(p, sid, gid, { config: { grouping: ['tier'], columns } as Partial<import('./project').BlockConfig> })
+    const page = pageFor(p)
+    // Full-client data + grouping controls + seeded grouping.
+    expect(page).toContain('data={allRows}')
+    expect(page).toContain('loading={!allRowsReady}')
+    expect(page).toContain('groupable')
+    expect(page).toContain("a.setGroupBy(['tier'])")
+    // Per-column aggregate flows into the column override.
+    expect(page).toContain("'mrr': { aggregate: 'sum' }")
+    // Client-side sort/paginate, NOT the server controller wiring.
+    expect(page).not.toContain('externalSort')
+    expect(page).not.toContain('externalPagination')
+    expect(page).not.toContain('onSortingChange')
+    // Loads the whole dataset.
+    expect(page).toContain('async function loadAll()')
+    for (const f of emitStudioProject(p).filter((f) => f.path.endsWith('.svelte'))) {
+      expect(() => compile(f.contents, { filename: f.path, generate: 'client' }), f.path).not.toThrow()
+    }
+  })
+
+  it('per-column value formats compile to the grid format (CellFormatConfig)', () => {
+    let p = createProject([customers])
+    const sid = p.screens[0]!.id
+    const gid = p.screens[0]!.blocks[0]!.id
+    const cfg = p.screens[0]!.blocks[0]!.config as GridConfig
+    const columns = cfg.columns.map((c) =>
+      c.field === 'mrr' ? { ...c, format: { type: 'currency', currency: 'EUR' } as const } : c,
+    )
+    p = updateBlock(p, sid, gid, { config: { columns } as Partial<import('./project').BlockConfig> })
+    const page = pageFor(p)
+    expect(page).toContain("'mrr': { format: { type: 'currency', currency: 'EUR' } }")
+    for (const f of emitStudioProject(p).filter((f) => f.path.endsWith('.svelte'))) {
+      expect(() => compile(f.contents, { filename: f.path, generate: 'client' }), f.path).not.toThrow()
+    }
+  })
+
+  it('percent + number formats emit decimals via Intl options', () => {
+    let p = createProject([customers])
+    const sid = p.screens[0]!.id
+    const gid = p.screens[0]!.blocks[0]!.id
+    const cfg = p.screens[0]!.blocks[0]!.config as GridConfig
+    const columns = cfg.columns.map((c) =>
+      c.field === 'mrr' ? { ...c, format: { type: 'percent', decimals: 1, valueIsPercentPoints: true } as const } : c,
+    )
+    p = updateBlock(p, sid, gid, { config: { columns } as Partial<import('./project').BlockConfig> })
+    expect(pageFor(p)).toContain("format: { type: 'percent', valueIsPercentPoints: true, options: { minimumFractionDigits: 1, maximumFractionDigits: 1 } }")
+  })
+
+  it('rich cell renderers emit per-column cell snippets + imports (badge / progress / link) and compile', () => {
+    let p = createProject([customers])
+    const sid = p.screens[0]!.id
+    const gid = p.screens[0]!.blocks[0]!.id
+    const cfg = p.screens[0]!.blocks[0]!.config as GridConfig
+    const columns = cfg.columns.map((c) =>
+      c.field === 'tier' ? { ...c, cellType: { kind: 'badge' } as const }
+      : c.field === 'mrr' ? { ...c, cellType: { kind: 'progress', max: 500 } as const }
+      : c.field === 'name' ? { ...c, cellType: { kind: 'link', as: 'email' } as const }
+      : c,
+    )
+    p = updateBlock(p, sid, gid, { config: { columns } as Partial<import('./project').BlockConfig> })
+    const page = pageFor(p)
+    // Imports pulled in for the renderers.
+    expect(page).toMatch(/import \{[^}]*renderSnippet[^}]*\} from '@svgrid\/grid'/)
+    expect(page).toMatch(/import \{[^}]*SvBadge[^}]*\} from '@svgrid\/grid'/)
+    expect(page).toMatch(/import \{[^}]*SvProgress[^}]*\} from '@svgrid\/grid'/)
+    // Cell refs + snippets.
+    expect(page).toContain('cell: (ctx: CellContext<Customers>) => renderSnippet(cellRender_')
+    expect(page).toContain('<SvBadge variant={stBadgeVariant(value)}')
+    expect(page).toContain('max={500}')
+    expect(page).toContain("href={'mailto:' + String(value ?? '')}")
+    // The shared badge-intent helper is emitted once.
+    expect(page.match(/function stBadgeVariant\(/g)?.length).toBe(1)
+    for (const f of emitStudioProject(p).filter((f) => f.path.endsWith('.svelte'))) {
+      expect(() => compile(f.contents, { filename: f.path, generate: 'client' }), f.path).not.toThrow()
+    }
+  })
+
+  it('an export toolbar captures the grid api + wires CSV / JSON / copy buttons, and compiles', () => {
+    let p = createProject([customers])
+    const sid = p.screens[0]!.id
+    const gid = p.screens[0]!.blocks[0]!.id
+    p = updateBlock(p, sid, gid, { config: { export: { csv: true, json: true, copy: true } } as Partial<import('./project').BlockConfig> })
+    const page = pageFor(p)
+    expect(page).toMatch(/import \{[^}]*type SvGridApi[^}]*\} from '@svgrid\/grid'/)
+    expect(page).toContain('let gridApi_' + gid.replace(/-/g, '_') + ' = $state<SvGridApi<any, any> | null>(null)')
+    expect(page).toContain('<div class="st-grid-toolbar">')
+    expect(page).toContain('.exportCsv({ filename: \'customers\' })')
+    expect(page).toContain('.exportJson({ filename: \'customers\' })')
+    expect(page).toContain('.copyToClipboard()')
+    for (const f of emitStudioProject(p).filter((f) => f.path.endsWith('.svelte'))) {
+      expect(() => compile(f.contents, { filename: f.path, generate: 'client' }), f.path).not.toThrow()
+    }
+  })
+
+  it('no export config emits no toolbar', () => {
+    expect(pageFor(createProject([customers]))).not.toContain('st-grid-toolbar')
+  })
+
+  it('tree data renders a client hierarchy: visible-row walk + tree cell on the label column, no flat sort/paginate', () => {
+    let p = createProject([customers])
+    const sid = p.screens[0]!.id
+    const gid = p.screens[0]!.blocks[0]!.id
+    p = updateBlock(p, sid, gid, { config: { treeData: { parentField: 'tier', labelField: 'name' } } as Partial<import('./project').BlockConfig> })
+    const page = pageFor(p)
+    // Full-client tree state + derivation.
+    expect(page).toContain('let treeExpanded_' + gid.replace(/-/g, '_'))
+    expect(page).toContain('function treeBuild_' + gid.replace(/-/g, '_'))
+    expect(page).toContain('data={tree_' + gid.replace(/-/g, '_') + '.visible}')
+    expect(page).toContain('loading={!allRowsReady}')
+    // Tree cell on the label column; other columns untouched.
+    expect(page).toContain('renderSnippet(treeCell_' + gid.replace(/-/g, '_'))
+    expect(page).toContain('{#snippet treeCell_' + gid.replace(/-/g, '_'))
+    expect(page).toContain('async function loadAll()')
+    // No flat sort / paginate / grouping that would break the hierarchy.
+    expect(page).not.toContain('externalSort')
+    expect(page).not.toContain('showPagination')
+    expect(page).not.toContain('groupable')
+    for (const f of emitStudioProject(p).filter((f) => f.path.endsWith('.svelte'))) {
+      expect(() => compile(f.contents, { filename: f.path, generate: 'client' }), f.path).not.toThrow()
+    }
+  })
+
+  it('scheduler view renders the grid as a calendar: enableSchedulerView + scheduler prop + write-back, and compiles', () => {
+    let p = createProject([customers])
+    const sid = p.screens[0]!.id
+    const gid = p.screens[0]!.blocks[0]!.id
+    p = updateBlock(p, sid, gid, { config: { scheduler: { startField: 'mrr', titleField: 'name', colorField: 'tier', initialView: 'week', editable: true, drawer: true } } as Partial<import('./project').BlockConfig> })
+    const page = pageFor(p)
+    // Renderer registered once + imported.
+    expect(page).toMatch(/import \{[^}]*enableSchedulerView[^}]*\} from '@svgrid\/enterprise'/)
+    expect(page).toContain('enableSchedulerView()')
+    // Full-client scheduler grid with the mapped config.
+    expect(page).toContain('data={allRows}')
+    expect(page).toContain("scheduler={{ startField: 'mrr'")
+    expect(page).toContain("titleField: 'name'")
+    expect(page).toContain("initialView: 'week'")
+    expect(page).toContain('editable: true')
+    // Optimistic write-back through the controller.
+    expect(page).toContain('onEventMove:')
+    expect(page).toContain('onEventCommit:')
+    expect(page).toContain('controller.updateRow(')
+    expect(page).toContain('async function loadAll()')
+    for (const f of emitStudioProject(p).filter((f) => f.path.endsWith('.svelte'))) {
+      expect(() => compile(f.contents, { filename: f.path, generate: 'client' }), f.path).not.toThrow()
+    }
+  })
+
+  it('an ungrouped grid stays server-driven (no groupable, keeps the controller view)', () => {
+    const page = pageFor(createProject([customers]))
+    expect(page).not.toContain('groupable')
+    expect(page).not.toContain('setGroupBy')
+    expect(page).toContain('data={view.rows}')
+    expect(page).toContain('externalSort')
+  })
+})
+
+describe('dock layout (screen.layout = dock)', () => {
+  it('a dock screen renders SvDockManager with a pane per block + persistence + mobile stack, and compiles', () => {
+    let p = createProject([customers])
+    const sid = p.screens[0]!.id
+    p = addBlock(p, sid, 'filter')
+    p = addBlock(p, sid, 'kpi')
+    p = setScreenLayout(p, sid, 'dock')
+    const files = emitStudioProject(p)
+    const page = files.find((f) => f.path === 'src/routes/customers/+page.svelte')!.contents
+    // Imports + workspace state + persistence.
+    expect(page).toMatch(/import \{[^}]*SvDockManager[^}]*\} from '@svgrid\/grid'/)
+    expect(page).toContain('let dockWorkspace = $state<DockManagerState>(')
+    expect(page).toContain("localStorage.getItem('dock:customers')")
+    expect(page).toContain('let dockNarrow = $state(false)')
+    // The manager + a pane per block, wired to persist on change.
+    expect(page).toContain('<SvDockManager bind:workspace={dockWorkspace} onChange={(w) => saveDock(w)}>')
+    expect(page).toContain('{#snippet pane(p)}')
+    for (const b of p.screens[0]!.blocks) expect(page).toContain(`{#if p.id === '${b.id}'}`)
+    // Mobile fallback stacks the plain grid body.
+    expect(page).toContain('{#if dockNarrow}')
+    for (const f of files.filter((f) => f.path.endsWith('.svelte'))) {
+      expect(() => compile(f.contents, { filename: f.path, generate: 'client' }), f.path).not.toThrow()
+    }
+  })
+
+  it('a canvas-layout screen places blocks on a 12-col grid by cell coords and compiles', () => {
+    let p = createProject([customers])
+    const sid = p.screens[0]!.id
+    p = addBlock(p, sid, 'kpi')
+    p = setScreenLayout(p, sid, 'canvas')
+    const files = emitStudioProject(p)
+    const page = files.find((f) => f.path === 'src/routes/customers/+page.svelte')!.contents
+    expect(page).toContain('<div class="st-canvas">')
+    expect(page).toContain('<div class="st-canvas__cell" style="grid-column:')
+    expect(page).toMatch(/grid-column: \d+ \/ span \d+; grid-row: \d+ \/ span \d+;/)
+    expect(page).not.toContain('SvDockManager')
+    const css = emitStudioAppBundle(p).find((f) => f.path === 'src/app.css')!.contents
+    expect(css).toContain('.st-canvas { display: grid; grid-template-columns: repeat(12, 1fr);')
+    for (const f of files.filter((f) => f.path.endsWith('.svelte'))) {
+      expect(() => compile(f.contents, { filename: f.path, generate: 'client' }), f.path).not.toThrow()
+    }
+  })
+
+  it('layout settings flow into codegen (dock props, persist off, canvas cols, grid gap)', () => {
+    // Dock with pop-out + bottom tabs + no persistence.
+    let d = createProject([customers])
+    const dsid = d.screens[0]!.id
+    d = addBlock(d, dsid, 'kpi')
+    d = setScreenLayout(d, dsid, 'dock')
+    d = setLayoutOpts(d, dsid, 'dock', { allowPopout: true, headerPosition: 'bottom', persist: false })
+    const dpage = emitStudioProject(d).find((f) => f.path.endsWith('/+page.svelte'))!.contents
+    expect(dpage).toContain('allowPopout')
+    expect(dpage).toContain('headerPosition="bottom"')
+    expect(dpage).not.toContain('onChange={(w) => saveDock(w)}') // persistence off
+    expect(dpage).not.toContain('function saveDock')
+
+    // Canvas with 24 columns + custom row height.
+    let c = createProject([customers])
+    const csid = c.screens[0]!.id
+    c = setScreenLayout(c, csid, 'canvas')
+    c = setLayoutOpts(c, csid, 'canvas', { cols: 24, rowHeight: 32 })
+    const cpage = emitStudioProject(c).find((f) => f.path.endsWith('/+page.svelte'))!.contents
+    expect(cpage).toContain('grid-template-columns: repeat(24, 1fr); grid-auto-rows: 32px;')
+
+    // Grid gap setting scoped into the page style.
+    let g = createProject([customers])
+    const gsid = g.screens[0]!.id
+    g = setLayoutOpts(g, gsid, 'grid', { colGap: 24, rowGap: 8 })
+    const gpage = emitStudioProject(g).find((f) => f.path.endsWith('/+page.svelte'))!.contents
+    expect(gpage).toContain('.st-screen { grid-template-columns: repeat(12, 1fr); gap: 8px 24px;')
+
+    for (const files of [emitStudioProject(d), emitStudioProject(c), emitStudioProject(g)]) {
+      for (const f of files.filter((f) => f.path.endsWith('.svelte'))) {
+        expect(() => compile(f.contents, { filename: f.path, generate: 'client' }), f.path).not.toThrow()
+      }
+    }
+  })
+
+  it('state variables + logic-core steps emit reactive state, ctx.state, and compiled code', () => {
+    let p = createProject([customers])
+    const sid = p.screens[0]!.id
+    p = addStateVar(p, sid, { name: 'query', type: 'string', initial: 'hi' })
+    p = addStateVar(p, sid, { name: 'count', type: 'number', initial: '0' })
+    // A click handler that sets a var, then branches on it.
+    p = addComponentBlock(p, sid, 'button', {})
+    const btn = flattenBlocks(p.screens[0]!.blocks).find((b) => b.config.kind === 'component')!
+    p = setHandlerSteps(p, sid, `click:${btn.id}`, [
+      { type: 'setVar', name: 'count', value: { kind: 'literal', value: '3' } },
+      { type: 'branch', condition: { left: { kind: 'state', name: 'count' }, op: 'gt', right: { kind: 'literal', value: '2' } }, then: [{ type: 'alert', message: 'big' }] },
+    ])
+    const files = emitStudioProject(p)
+    const page = files.find((f) => f.path.endsWith('/+page.svelte'))!.contents
+    expect(page).toContain("let query = $state<string>('hi')")
+    expect(page).toContain('let count = $state<number>(0)')
+    expect(page).toContain('state: { get query() { return query }, set query(x) { query = x }, get count() { return count }, set count(x) { count = x } }')
+    // The compiled step code lives in the handlers.ts companion (onLoad wires the onclick).
+    const handlers = files.find((f) => f.path.endsWith('/handlers.ts'))!.contents
+    expect(handlers).toContain('ctx.state.count = 3')
+    expect(handlers).toContain('if (Number(ctx.state.count) > Number(2)) {')
+    const pctx = files.find((f) => f.path.endsWith('/page-context.ts'))!.contents
+    expect(pctx).toContain('state: { query: string; count: number }')
+    for (const f of files.filter((f) => f.path.endsWith('.svelte'))) {
+      expect(() => compile(f.contents, { filename: f.path, generate: 'client' }), f.path).not.toThrow()
+    }
+  })
+
+  it('grid row-select event slot wires onRowClick to compiled steps (cross-block state)', () => {
+    let p = createProject([customers])
+    const sid = p.screens[0]!.id
+    p = addStateVar(p, sid, { name: 'selName', type: 'string' })
+    const gridBlock = flattenBlocks(p.screens[0]!.blocks).find((b) => b.config.kind === 'grid')!
+    // On row select: copy the clicked row's name into state (drives sibling blocks).
+    p = setHandlerSteps(p, sid, `rowSelect:${gridBlock.id}`, [
+      { type: 'setVar', name: 'selName', value: { kind: 'field', name: 'name' } },
+    ])
+    const files = emitStudioProject(p)
+    const page = files.find((f) => f.path.endsWith('/+page.svelte'))!.contents
+    expect(page).toContain('onRowClick={async (e) => {')
+    expect(page).toContain('const row = e.row')
+    expect(page).toContain("ctx.state.selName = row?.['name']")
+    for (const f of files.filter((f) => f.path.endsWith('.svelte'))) {
+      expect(() => compile(f.contents, { filename: f.path, generate: 'client' }), f.path).not.toThrow()
+    }
+  })
+
+  it('component on-change event slot wires ctx.<name>.onchange + the wrapper fires change', () => {
+    let p = createProject([customers])
+    const sid = p.screens[0]!.id
+    p = addStateVar(p, sid, { name: 'touched', type: 'boolean' })
+    p = addComponentBlock(p, sid, 'button', {})
+    const cmp = flattenBlocks(p.screens[0]!.blocks).find((b) => b.config.kind === 'component')!
+    p = setHandlerSteps(p, sid, `change:${cmp.id}`, [{ type: 'setVar', name: 'touched', value: { kind: 'literal', value: 'true' } }])
+    const files = emitStudioProject(p)
+    const page = files.find((f) => f.path.endsWith('/+page.svelte'))!.contents
+    const handlers = files.find((f) => f.path.endsWith('/handlers.ts'))!.contents
+    expect(page).toContain(".fire('change', e)")
+    expect(handlers).toMatch(/ctx\.\w+\.onchange = async \(\) => \{/)
+    expect(handlers).toContain('ctx.state.touched = true')
+    for (const f of files.filter((f) => f.path.endsWith('.svelte'))) {
+      expect(() => compile(f.contents, { filename: f.path, generate: 'client' }), f.path).not.toThrow()
+    }
+  })
+
+  it('on-record-saved (formSubmit) steps run inside save() with the submitted row + ctx', () => {
+    let p = createProject([customers])
+    const sid = p.screens[0]!.id
+    // Default CRUD screen edits via a popup form (editing = 'form').
+    p = setHandlerSteps(p, sid, 'formSubmit', [
+      { type: 'navigate', to: '/customers' },
+    ])
+    const page = emitStudioProject(p).find((f) => f.path.endsWith('/+page.svelte'))!.contents
+    expect(page).toContain('async function save({ mode, id, values }')
+    expect(page).toContain('const row = values')
+    expect(page).toContain('const ctx = { grid: gridApi!,')
+    expect(page).toContain("ctx.goto('/customers')")
+    for (const f of emitStudioProject(p).filter((f) => f.path.endsWith('.svelte'))) {
+      expect(() => compile(f.contents, { filename: f.path, generate: 'client' }), f.path).not.toThrow()
+    }
+  })
+
+  it('entity triggers compile into the SQL route as createKitHandlers hooks (server-enforced)', () => {
+    let p = setEntityDataSource(createProject([customers]), 'customers', { kind: 'sql', table: 'customers', dialect: 'postgres' })
+    p = setTrigger(p, 'customers', 'beforeCreate', [
+      { type: 'requireField', field: 'name', message: 'Name required' },
+      { type: 'setField', field: 'tier', value: { kind: 'literal', value: 'free' } },
+    ])
+    p = setTrigger(p, 'customers', 'afterUpdate', [{ type: 'code', code: 'console.log("updated", row)' }])
+    const route = emitStudioProject(p).find((f) => f.path === 'src/routes/api/customers/+server.ts')!.contents
+    expect(route).toContain('hooks: {')
+    expect(route).toContain('beforeCreate: async ({ values }) => {')
+    expect(route).toContain('const v = values as Record<string, unknown>')
+    expect(route).toContain("if (v['name'] == null || v['name'] === '') throw new Error('Name required')")
+    expect(route).toContain("v['tier'] = 'free'")
+    expect(route).toContain('afterUpdate: async ({ row }) => {')
+    // The route uses createKitHandlers - hooks are a valid option on it.
+    expect(route).toContain('createKitHandlers({')
+  })
+
+  it('a grid-layout screen (default) emits no dock manager', () => {
+    const page = emitStudioProject(createProject([customers])).find((f) => f.path === 'src/routes/customers/+page.svelte')!.contents
+    expect(page).not.toContain('SvDockManager')
+    expect(page).toContain('<div class="st-screen">')
+  })
+
+  it('a split-layout screen renders a LOCKED SvDockManager (resize-only) and compiles', () => {
+    let p = createProject([customers])
+    const sid = p.screens[0]!.id
+    p = addBlock(p, sid, 'filter')
+    p = addBlock(p, sid, 'kpi')
+    p = setScreenLayout(p, sid, 'split')
+    const files = emitStudioProject(p)
+    const page = files.find((f) => f.path === 'src/routes/customers/+page.svelte')!.contents
+    // Same SvDockManager plumbing as dock, but locked.
+    expect(page).toMatch(/import \{[^}]*SvDockManager[^}]*\} from '@svgrid\/grid'/)
+    expect(page).toContain('<SvDockManager bind:workspace={dockWorkspace} onChange={(w) => saveDock(w)} locked>')
+    expect(page).toContain('{#snippet pane(p)}')
+    for (const b of p.screens[0]!.blocks) expect(page).toContain(`{#if p.id === '${b.id}'}`)
+    for (const f of files.filter((f) => f.path.endsWith('.svelte'))) {
+      expect(() => compile(f.contents, { filename: f.path, generate: 'client' }), f.path).not.toThrow()
+    }
+  })
+
+  it('a stack-layout screen wraps blocks in a single-column flow (.st-stack) and compiles', () => {
+    let p = createProject([customers])
+    const sid = p.screens[0]!.id
+    p = addBlock(p, sid, 'kpi')
+    p = setScreenLayout(p, sid, 'stack')
+    const files = emitStudioProject(p)
+    const page = files.find((f) => f.path === 'src/routes/customers/+page.svelte')!.contents
+    expect(page).toContain('<div class="st-stack">')
+    expect(page).not.toContain('<div class="st-screen">')
+    expect(page).not.toContain('SvDockManager')
+    // Default stack min-height flows into the page-scoped style so blocks aren't tiny.
+    expect(page).toContain('.st-stack > * { min-height: 160px; }')
+    const css = emitStudioAppBundle(p).find((f) => f.path === 'src/app.css')!.contents
+    expect(css).toContain('.st-stack { display: flex; flex-direction: column;')
+    for (const f of files.filter((f) => f.path.endsWith('.svelte'))) {
+      expect(() => compile(f.contents, { filename: f.path, generate: 'client' }), f.path).not.toThrow()
+    }
+  })
+
+  it('syncDockPanes adds a pane for a new block + strips a removed one, preserving arrangement', () => {
+    let p = createProject([customers])
+    const sid = p.screens[0]!.id
+    p = setScreenLayout(p, sid, 'dock')
+    const before = p.screens[0]!.dock!
+    const beforeIds = [...dockPaneIds(before)]
+    // Add a block: sync appends its pane, keeps the existing ones + the main node id (arrangement).
+    p = addBlock(p, sid, 'chart')
+    p = { ...p, screens: p.screens.map((s) => (s.id === sid ? syncDockPanes(s) : s)) }
+    const afterAdd = p.screens[0]!.dock!
+    const addIds = dockPaneIds(afterAdd)
+    for (const id of beforeIds) expect(addIds.has(id)).toBe(true) // existing panes preserved
+    const chartId = p.screens[0]!.blocks.find((b) => b.config.kind === 'chart')!.id
+    expect(addIds.has(chartId)).toBe(true) // new pane added
+    expect(afterAdd.main?.id).toBe(before.main?.id) // main node reused (arrangement not rebuilt)
+    // Remove the chart: its pane is stripped, the rest stay.
+    p = removeBlock(p, sid, chartId)
+    p = { ...p, screens: p.screens.map((s) => (s.id === sid ? syncDockPanes(s) : s)) }
+    const afterRemove = dockPaneIds(p.screens[0]!.dock!)
+    expect(afterRemove.has(chartId)).toBe(false)
+    for (const id of beforeIds) expect(afterRemove.has(id)).toBe(true)
+  })
+
+  it('setDockPaneTitle renames a pane (tab text) + dockPaneTitleOf reads it back', () => {
+    let p = createProject([customers])
+    const sid = p.screens[0]!.id
+    p = setScreenLayout(p, sid, 'dock')
+    const gridBlock = p.screens[0]!.blocks[0]!
+    expect(dockPaneTitleOf(p.screens[0]!, gridBlock.id)).toBe('Grid') // auto title
+    p = setDockPaneTitle(p, sid, gridBlock.id, 'Customers table')
+    expect(dockPaneTitleOf(p.screens[0]!, gridBlock.id)).toBe('Customers table')
+    // Custom title survives an incremental pane sync (add a block).
+    p = addBlock(p, sid, 'chart')
+    p = { ...p, screens: p.screens.map((s) => (s.id === sid ? syncDockPanes(s) : s)) }
+    expect(dockPaneTitleOf(p.screens[0]!, gridBlock.id)).toBe('Customers table')
+  })
+
+  it('setScreenLayout(dock) seeds a workspace by role + survives serialize/parse', () => {
+    let p = createProject([customers])
+    const sid = p.screens[0]!.id
+    p = addBlock(p, sid, 'filter')
+    p = setScreenLayout(p, sid, 'dock')
+    const scr = p.screens[0]!
+    expect(scr.layout).toBe('dock')
+    expect(scr.dock).toBeTruthy()
+    // Pane ids equal block ids.
+    const paneIds = dockPaneIds(scr.dock!)
+    for (const b of scr.blocks) expect(paneIds.has(b.id)).toBe(true)
+    // Round-trips through the project (de)serializer.
+    const round = parseProject(serializeProject(p))
+    expect(round.screens[0]!.layout).toBe('dock')
+    expect(round.screens[0]!.dock).toEqual(scr.dock)
+  })
 })
 
 describe('emitStudioAppBundle (full runnable app)', () => {
@@ -834,6 +1855,17 @@ describe('emitStudioAppBundle (full runnable app)', () => {
     expect(pkg.devDependencies['vite']).toBeTruthy()
   })
 
+  it('pins Vite 7 (not 8) so the app boots in StackBlitz WebContainer', () => {
+    const bundle = emitStudioAppBundle(createProject([customers]))
+    const pkg = JSON.parse(bundle.find((f) => f.path === 'package.json')!.contents)
+    // Vite 8's Rolldown bundler crashes in the WebContainer; pin the Rollup-based stack.
+    expect(pkg.devDependencies['vite']).toBe('^7.0.0')
+    expect(pkg.devDependencies['@sveltejs/vite-plugin-svelte']).toBe('^6.0.0')
+    expect(pkg.devDependencies['vitest']).toMatch(/^\^4\./) // vitest 4 supports vite 7
+    // engine-strict must not hard-fail install in a sandbox whose Node may differ.
+    expect(bundle.find((f) => f.path === '.npmrc')!.contents).toContain('engine-strict=false')
+  })
+
   it('ships a per-entity smoke test + vitest wiring', () => {
     const bundle = emitStudioAppBundle(createProject([customers, orders], { title: 'My Sales App' }))
     const pkg = JSON.parse(bundle.find((f) => f.path === 'package.json')!.contents)
@@ -883,6 +1915,21 @@ describe('pages (nav) + shell codegen', () => {
     expect(layout).toContain('(c) Acme')
   })
 
+  it('emits a bottom-nav shell (fixed bar, no sidebar drawer state, footer text dropped) that compiles', () => {
+    const p = setShell(createProject([customers, orders]), { style: 'bottom-nav', brand: 'Acme', footer: '(c) Acme' })
+    const layout = layoutOf(p)
+    expect(layout).toContain('sv-app--bottom')
+    expect(layout).toContain('sv-app__bar--bottom')
+    expect(layout).toContain('Acme')
+    // The bottom bar occupies that visual role; footer text is intentionally not rendered
+    // in the markup (the `const footer = ...` script declaration is unconditional and stays,
+    // but nothing in the bottom-nav body dereferences it).
+    expect(layout).not.toContain('<footer class="sv-app__footbar">')
+    // top-nav/sidebar-only collapse state must not leak into the bottom-nav shell.
+    expect(layout).not.toContain('let collapsed = $state')
+    expect(() => compile(layout, { filename: '+layout.svelte', generate: 'client' })).not.toThrow()
+  })
+
   it('defaults to sidebar; an empty footer omits the footer element', () => {
     const p = setShell(createProject([customers]), { footer: '' })
     const layout = layoutOf(p)
@@ -912,12 +1959,399 @@ describe('pages (nav) + shell codegen', () => {
     expect(layout).not.toContain('--sg-accent: #0969da')
   })
 
-  it('custom CSS is appended to the generated app.css', () => {
+  it('custom CSS goes to its own src/custom.css, imported after app.css by the layout', () => {
     const p = setTheme(createProject([customers]), { customCss: '.st__title { letter-spacing: -0.03em; }' })
-    const appcss = emitStudioAppBundle(p).find((f) => f.path === 'src/app.css')!.contents
-    expect(appcss).toContain('Custom CSS (from the designer)')
-    expect(appcss).toContain('.st__title { letter-spacing: -0.03em; }')
-    // No custom block when unset.
-    expect(emitStudioAppBundle(createProject([customers])).find((f) => f.path === 'src/app.css')!.contents).not.toContain('Custom CSS (from the designer)')
+    const files = emitStudioAppBundle(p)
+    const customCss = files.find((f) => f.path === 'src/custom.css')!
+    expect(customCss.contents).toContain('.st__title { letter-spacing: -0.03em; }')
+    // app.css no longer carries the user's CSS.
+    expect(files.find((f) => f.path === 'src/app.css')!.contents).not.toContain('.st__title { letter-spacing: -0.03em; }')
+    // The layout imports both, custom.css after app.css so it overrides.
+    const layout = files.find((f) => f.path === 'src/routes/+layout.svelte')!.contents
+    expect(layout.indexOf("import '../custom.css'")).toBeGreaterThan(layout.indexOf("import '../app.css'"))
+    // custom.css is always emitted (even empty) so the import never dangles.
+    expect(emitStudioAppBundle(createProject([customers])).find((f) => f.path === 'src/custom.css')).toBeTruthy()
+  })
+
+  it('no "Home" nav link; / redirects to the first screen', () => {
+    const files = emitStudioProject(createProject([customers, orders]))
+    const layout = files.find((f) => f.path === 'src/routes/+layout.svelte')!.contents
+    // The auto "Home" link is gone (it duplicated the first screen's landing).
+    expect(layout).not.toContain('>Home<')
+    expect(layout).not.toContain("label: 'Home'")
+    // `/` is a redirect to the first navigable screen, not a distinct page.
+    const home = files.find((f) => f.path === 'src/routes/+page.svelte')!.contents
+    expect(home).toContain('const home = "/customers"')
+    expect(home).toContain('goto(home, { replaceState: true })')
+  })
+
+  it('ships a light/dark switcher: both token sets scoped by [data-theme] + a toggle', () => {
+    const p = setThemePreset(createProject([customers]), 'tailwind')
+    const layout = layoutOf(p)
+    // Both palettes emitted, keyed off <html data-theme>.
+    expect(layout).toContain(':root[data-theme="light"]')
+    expect(layout).toContain(':root[data-theme="dark"]')
+    expect(layout).toContain('--sg-bg: #ffffff')   // Tailwind light bg
+    expect(layout).toContain('--sg-bg: #0f172a')   // Tailwind dark bg
+    // The toggle + its runtime are wired in and persist the choice.
+    expect(layout).toContain('function toggleTheme()')
+    expect(layout).toContain("document.documentElement.dataset.theme")
+    expect(layout).toContain("localStorage.setItem('svapp:theme'")
+    expect(layout).toContain('sv-app__theme')
+    expect(() => compile(layout, { filename: '+layout.svelte', generate: 'client' })).not.toThrow()
+  })
+})
+
+describe('code companion (design + your own code)', () => {
+  // A blank page with code enabled + a Grid fed by onLoad.
+  const build = () => {
+    let p = addFreestandingScreen(createProject([customers]), { title: 'Report', route: 'report' })
+    const sid = p.screens.find((s) => s.route === 'report')!.id
+    p = setScreenRenderGrid(p, sid, true) // implies code enabled
+    return { p, sid }
+  }
+
+  it('emits a user-owned handlers.ts (onLoad) + a regenerated page-context.ts', () => {
+    const { p } = build()
+    const files = emitStudioProject(p)
+    const companion = files.find((f) => f.path === 'src/routes/report/handlers.ts')
+    expect(companion, 'companion emitted').toBeTruthy()
+    expect(companion!.userOwned).toBe(true)
+    expect(companion!.contents).toContain('export async function onLoad(ctx: PageContext): Promise<void>')
+    expect(companion!.contents).toContain("import type { PageContext } from './page-context'")
+    expect(companion!.contents).toContain('never overwrites')
+    // The context type + shared handle runtime are generated (not user-owned).
+    const ctx = files.find((f) => f.path === 'src/routes/report/page-context.ts')!
+    expect(ctx.userOwned).toBeFalsy()
+    expect(ctx.contents).toContain('export type PageContext')
+    expect(files.find((f) => f.path === 'src/lib/handles.svelte.ts')).toBeTruthy()
+  })
+
+  it('onLoad exists even with no Grid (a general mount hook, not grid-gated)', () => {
+    let p = addFreestandingScreen(createProject([customers]), { title: 'Plain', route: 'plain' })
+    const sid = p.screens.find((s) => s.route === 'plain')!.id
+    p = enableScreenCode(p, sid) // code on, but renderGrid off
+    const page = emitStudioProject(p).find((f) => f.path === 'src/routes/plain/+page.svelte')!
+    expect(emitStudioProject(p).find((f) => f.path === 'src/routes/plain/handlers.ts')!.contents).toContain('export async function onLoad(ctx: PageContext)')
+    expect(page.contents).not.toContain('<SvGrid')
+    expect(page.contents).toContain('handlers.onLoad(') // still wired on mount
+  })
+
+  it('the page runs onLoad in onMount, renders the Grid, and compiles', () => {
+    const { p } = build()
+    const page = emitStudioProject(p).find((f) => f.path === 'src/routes/report/+page.svelte')!
+    expect(page.contents).toContain("import * as handlers from './handlers'")
+    // onLoad runs on mount and onDestroy on unmount, both with the full ctx (grid +
+    // the settable data battery, since this freestanding page owns its rows).
+    expect(page.contents).toContain('const ctx = { grid: gridApi!, data: { get rows() { return rows }, setRows: (r) => (rows = r) }')
+    expect(page.contents).toContain('as PageContext')
+    expect(page.contents).toContain('handlers.onLoad(ctx)')
+    expect(page.contents).toContain('return () => handlers.onDestroy(ctx)')
+    expect(page.contents).toContain('<SvGrid data={rows} columns={columns} features={features}')
+    expect(() => compile(page.contents, { filename: page.path, generate: 'client' })).not.toThrow()
+  })
+
+  it('the Grid is exposed as its real SvGridApi (ctx.grid), typed to the row in page-context', () => {
+    const { p } = build()
+    const files = emitStudioProject(p)
+    const page = files.find((f) => f.path === 'src/routes/report/+page.svelte')!
+    const ctx = files.find((f) => f.path === 'src/routes/report/page-context.ts')!
+    expect(page.contents).toContain('let gridApi = $state<SvGridApi<any, any> | null>(null)')
+    expect(page.contents).toContain('onApiReady={(a) => (gridApi = a)}')
+    expect(page.contents).toMatch(/import type \{[^}]*\bSvGridApi\b/)
+    // Freestanding data-grid rows are RowData; the grid api is typed to it.
+    expect(ctx.contents).toContain('grid: SvGridApi<any, RowData>')
+    expect(ctx.contents).toContain("import type { RowData } from '@svgrid/grid'")
+    expect(ctx.contents).toMatch(/import type \{[^}]*\bSvGridApi\b/)
+  })
+
+  it('a dropped component becomes a named, typed handle in code + markup', () => {
+    const { p: base, sid } = build()
+    const p = addComponentBlock(base, sid, 'button', { variant: 'primary' })
+    const files = emitStudioProject(p)
+    const page = files.find((f) => f.path === 'src/routes/report/+page.svelte')!
+    const ctx = files.find((f) => f.path === 'src/routes/report/page-context.ts')!
+    const companion = files.find((f) => f.path === 'src/routes/report/handlers.ts')!
+    // Named handle (button1) created + wired into the component markup.
+    expect(page.contents).toContain('const button1 = handle(')
+    expect(page.contents).toContain('<SvButton {...button1.props}>{button1.text}</SvButton>')
+    expect(page.contents).toContain("import { handle } from '$lib/handles.svelte'")
+    expect(page.contents).toContain('button1.fire(\'click\', e)')
+    expect(page.contents).toContain('const ctx = { grid: gridApi!, button1, data:')
+    expect(page.contents).toContain('handlers.onLoad(ctx)')
+    // Typed handle: ButtonHandle intersects Handle with the button's real setters.
+    expect(ctx.contents).toContain('button1: ButtonHandle')
+    expect(ctx.contents).toContain('type ButtonHandle = Handle & {')
+    expect(ctx.contents).toContain("setVariant(value: \"primary\" | \"secondary\" | \"outline\" | \"ghost\" | \"danger\"): void")
+    // Each prop is ALSO a read/write property (button1.variant = 'danger'), not just a setter.
+    expect(ctx.contents).toContain("variant: \"primary\" | \"secondary\" | \"outline\" | \"ghost\" | \"danger\"")
+    expect(ctx.contents).toContain('disabled: boolean')
+    expect(ctx.contents).toContain('text: string')
+    expect(companion.contents).toContain('ctx.button1')
+    expect(companion.contents).not.toContain('getElementById')
+    expect(() => compile(page.contents, { filename: page.path, generate: 'client' })).not.toThrow()
+  })
+
+  it('Methods panel: visual action steps compile to the ctx handler body + component onclick', () => {
+    const { p: base, sid } = build()
+    const withGrid = setScreenRenderGrid(base, sid, true) // gives ctx.grid
+    let p = addComponentBlock(withGrid, sid, 'button', { _content: 'Export' })
+    const btn = p.screens.find((s) => s.id === sid)!.blocks.find((b) => b.config.kind === 'component')!
+    // onLoad steps + the button's on-click steps.
+    p = setHandlerSteps(p, sid, 'onLoad', [
+      { type: 'gridSort', field: 'name', dir: 'desc' },
+      { type: 'setText', target: 'button1', value: 'Download' },
+    ])
+    p = setHandlerSteps(p, sid, clickSlot(btn.id), [
+      { type: 'gridExport', format: 'csv' },
+      { type: 'navigate', to: '/other' },
+      { type: 'alert', message: 'Done' },
+    ])
+    const files = emitStudioProject(p)
+    const handlers = files.find((f) => f.path === 'src/routes/report/handlers.ts')!.contents
+    // onLoad compiled from steps.
+    expect(handlers).toContain("ctx.grid.setSort('name', 'desc')")
+    expect(handlers).toContain("ctx.button1.text = 'Download'")
+    // The button's click steps become an onclick assignment inside onLoad.
+    expect(handlers).toContain('ctx.button1.onclick = async () => {')
+    expect(handlers).toContain('await ctx.grid.exportCsv()')
+    expect(handlers).toContain("ctx.goto('/other')")
+    expect(handlers).toContain("alert('Done')")
+    // The page runs it + compiles.
+    const page = files.find((f) => f.path === 'src/routes/report/+page.svelte')!
+    expect(page.contents).toContain('handlers.onLoad(ctx)')
+    for (const f of files.filter((f) => f.path.endsWith('.svelte'))) {
+      expect(() => compile(f.contents, { filename: f.path, generate: 'client' }), f.path).not.toThrow()
+    }
+  })
+
+  it('Methods: stepsToCode drops the visual steps into the raw code editor (take over)', () => {
+    const { p: base, sid } = build()
+    let p = setHandlerSteps(base, sid, 'onLoad', [{ type: 'alert', message: 'hi' }, { type: 'navigate', to: '/x' }])
+    p = stepsToCode(p, sid, 'onLoad')
+    const screen = p.screens.find((s) => s.id === sid)!
+    expect(screen.handlerSteps?.onLoad).toBeUndefined()        // steps cleared
+    expect(screen.handlerBodies?.onLoad).toBe("alert('hi')\nctx.goto('/x')") // compiled to raw body
+  })
+
+  it('Methods: a hand-written onLoad body MERGES with component on-click wiring (neither replaces the other)', () => {
+    const { p: base, sid } = build()
+    const withGrid = setScreenRenderGrid(base, sid, true)
+    let p = addComponentBlock(withGrid, sid, 'button', { _content: 'Go' })
+    const btn = p.screens.find((s) => s.id === sid)!.blocks.find((b) => b.config.kind === 'component')!
+    // Hand-written onLoad code AND a button with on-click steps.
+    p = setHandlerBody(p, sid, 'onLoad', "console.log('mounted')")
+    p = setHandlerSteps(p, sid, clickSlot(btn.id), [{ type: 'navigate', to: '/next' }])
+    const handlers = emitStudioProject(p).find((f) => f.path === 'src/routes/report/handlers.ts')!.contents
+    expect(handlers).toContain("console.log('mounted')")          // the hand-written body survives
+    expect(handlers).toContain('ctx.button1.onclick = async () => {') // + the onclick wiring is added
+    expect(handlers).toContain("ctx.goto('/next')")
+  })
+
+  it('handlersSource from the designer is emitted verbatim (advanced override)', () => {
+    const { p: base, sid } = build()
+    const src = "export async function onLoad() {\n  await fetch('/api/report')\n}"
+    const p = setScreenHandlersSource(base, sid, src)
+    const companion = emitStudioProject(p).find((f) => f.path === 'src/routes/report/handlers.ts')!
+    expect(companion.userOwned).toBe(true)
+    expect(companion.contents).toContain("await fetch('/api/report')")
+    expect(companion.contents).not.toContain('export async function onLoad(ctx') // structured shell replaced
+  })
+
+  it('no companion and no wiring when the screen has no code', () => {
+    const p = addFreestandingScreen(createProject([customers]), { title: 'Bare', route: 'bare' })
+    const files = emitStudioProject(p)
+    expect(files.find((f) => f.path === 'src/routes/bare/handlers.ts')).toBeUndefined()
+    expect(files.find((f) => f.path === 'src/routes/bare/+page.svelte')!.contents).not.toContain("from './handlers'")
+  })
+
+  it('entity screens wire onLoad/onDestroy + expose their grid as ctx.grid (reload, not setRows)', () => {
+    let p = createProject([customers, orders])
+    const sid = p.screens.find((s) => s.entity === 'customers')!.id
+    p = setHandlerBody(p, sid, 'onLoad', 'ctx.grid.autosizeAllColumns()')
+    const route = p.screens.find((s) => s.id === sid)!.route
+    const files = emitStudioProject(p)
+    const page = files.find((f) => f.path === `src/routes/${route}/+page.svelte`)!
+    const ctx = files.find((f) => f.path === `src/routes/${route}/page-context.ts`)!
+    expect(page.contents).toContain("import * as handlers from './handlers'")
+    expect(page.contents).toContain('let gridApi = $state<SvGridApi<any, any> | null>(null)')
+    expect(page.contents).toContain('onApiReady={(a) => (gridApi = a)}')
+    // Full ctx on mount + cleanup on unmount; the grid exposes reload(), not setRows.
+    expect(page.contents).toContain('const ctx = { grid: gridApi!, data: { get rows() { return view.rows }, reload: () => controller.refresh(), create: (v) => controller.createRow(v), update: (id, v) => controller.updateRow(id, v), delete: (id) => controller.deleteRow(id) }, goto, params: Object.fromEntries($page.url.searchParams) } as unknown as PageContext')
+    expect(page.contents).toContain('handlers.onLoad(ctx)')
+    expect(page.contents).toContain('return () => handlers.onDestroy(ctx)')
+    // The grid api is typed to the entity's row (Customers), not any.
+    expect(ctx.contents).toContain('grid: SvGridApi<any, Customers>')
+    expect(ctx.contents).toContain("import type { Customers } from '$lib/schemas'")
+    expect(ctx.contents).not.toContain('setRows: (rows') // the entity grid is controller-fed, no setRows member
+    expect(() => compile(page.contents, { filename: page.path, generate: 'client' })).not.toThrow()
+  })
+
+  it('data-viz blocks become setData handles; entity components + batteries are in ctx', () => {
+    let p = createProject([customers, orders])
+    const sid = p.screens.find((s) => s.entity === 'customers')!.id
+    // A chart + a KPI + a button on the customers screen, with code enabled.
+    p = addBlock(p, sid, 'chart')
+    p = addBlock(p, sid, 'kpi')
+    p = addComponentBlock(p, sid, 'button', { variant: 'primary' })
+    p = enableScreenCode(p, sid)
+    const route = p.screens.find((s) => s.id === sid)!.route
+    const files = emitStudioProject(p)
+    const page = files.find((f) => f.path === `src/routes/${route}/+page.svelte`)!
+    const ctx = files.find((f) => f.path === `src/routes/${route}/page-context.ts`)!
+    // Per-block DataHandles declared and fed to the chart/kpi markup.
+    expect(page.contents).toContain('const chart1 = dataHandle<Customers>(() => allRows)')
+    expect(page.contents).toContain('const kpi1 = dataHandle<Customers>(() => allRows)')
+    expect(page.contents).toContain('rows={chart1.rows}')
+    expect(page.contents).toContain("import { handle, dataHandle } from '$lib/handles.svelte'")
+    // ctx carries the data handles + the entity component handle + batteries.
+    expect(ctx.contents).toContain('chart1: DataHandle<Customers>')
+    expect(ctx.contents).toContain('kpi1: DataHandle<Customers>')
+    expect(ctx.contents).toContain('button1: ButtonHandle')
+    expect(ctx.contents).toContain('goto: (path: string) => void')
+    expect(ctx.contents).toContain('params: Record<string, string>')
+    expect(() => compile(page.contents, { filename: page.path, generate: 'client' })).not.toThrow()
+  })
+
+  it('emits the shared DataHandle runtime, and its private-$state pattern is valid Svelte', () => {
+    let p = createProject([customers])
+    const sid = p.screens.find((s) => s.entity === 'customers')!.id
+    p = addBlock(p, sid, 'chart') // needs a DataHandle
+    p = addComponentBlock(p, sid, 'button', {}) // needs a ComponentHandle
+    p = enableScreenCode(p, sid)
+    const mod = emitStudioProject(p).find((f) => f.path === 'src/lib/handles.svelte.ts')!
+    expect(mod.contents).toContain('export class DataHandle')
+    expect(mod.contents).toContain('setData(rows: T[]): void')
+    // The generated .svelte.ts is stripped of types + compiled by the bundler's
+    // svelte plugin; here we prove the reactive private-field pattern it relies on
+    // (a `#field = $state()` read through a getter) is valid Svelte 5 via the
+    // component compiler (which strips TS in `<script lang="ts">`).
+    const probe = `<script lang="ts">
+  class DataHandle<T> {
+    #override = $state<T[] | null>(null)
+    #fallback: () => T[]
+    constructor(fallback: () => T[]) { this.#fallback = fallback }
+    get rows(): T[] { return this.#override ?? this.#fallback() }
+    setData(rows: T[]): void { this.#override = rows }
+    clear(): void { this.#override = null }
+  }
+  let all = $state<number[]>([1, 2])
+  const h = new DataHandle<number>(() => all)
+</script>
+<p>{h.rows.length}</p>`
+    expect(() => compile(probe, { filename: 'probe.svelte', generate: 'client' })).not.toThrow()
+  })
+
+  it('ctxCompletions exposes the FULL grid api + every handle member + batteries', () => {
+    let p = createProject([customers])
+    const sid = p.screens.find((s) => s.entity === 'customers')!.id
+    p = addBlock(p, sid, 'chart')
+    p = addComponentBlock(p, sid, 'button', {})
+    p = enableScreenCode(p, sid)
+    const screen = p.screens.find((s) => s.id === sid)!
+    const comp = ctxCompletions(screen)
+    // The whole grid surface, not a handful.
+    expect(comp).toContain('ctx.grid.exportCsv()')
+    expect(comp).toContain('ctx.grid.autosizeAllColumns()')
+    expect(comp).toContain('ctx.grid.applyTransaction()')
+    expect(comp.filter((c) => c.startsWith('ctx.grid.')).length).toBeGreaterThan(40)
+    // Data handle + typed component setters + batteries.
+    expect(comp).toContain('ctx.chart1.setData()')
+    expect(comp).toContain('ctx.chart1.rows')
+    expect(comp).toContain('ctx.button1.setVariant()')
+    expect(comp).toContain('ctx.button1.onclick')
+    expect(comp).toContain('ctx.data.reload()')
+    expect(comp).toContain('ctx.goto()')
+    expect(comp).toContain('ctx.params')
+  })
+
+  it('per-block style overrides are emitted as inline CSS on the block wrapper', () => {
+    let p = createProject([customers])
+    const sid = p.screens[0]!.id
+    // Give the grid block a border-off + padding + margin override.
+    const bid = p.screens[0]!.blocks[0]!.id
+    p = updateBlock(p, sid, bid, { style: { border: false, padding: 24, margin: 8, radius: 10, background: '#fafafa' } })
+    const page = emitStudioProject(p).find((f) => f.path === 'src/routes/customers/+page.svelte')!
+    expect(page.contents).toContain('border: none')
+    expect(page.contents).toContain('padding: 24px')
+    expect(page.contents).toContain('margin: 8px')
+    expect(page.contents).toContain('border-radius: 10px')
+    expect(page.contents).toContain('background: #fafafa')
+    expect(() => compile(page.contents, { filename: page.path, generate: 'client' })).not.toThrow()
+  })
+
+  it('per-block className is emitted on the wrapper (merged with base classes) + sanitized', () => {
+    let p = createProject([customers])
+    const sid = p.screens[0]!.id
+    p = addBlock(p, sid, 'kpi')
+    const gridId = p.screens[0]!.blocks.find((b) => b.config.kind === 'grid')!.id
+    const kpiId = p.screens[0]!.blocks.find((b) => b.config.kind === 'kpi')!.id
+    p = updateBlock(p, sid, gridId, { className: 'my-grid highlight' })
+    p = updateBlock(p, sid, kpiId, { className: 'evil"onload=x' }) // sanitized
+    const page = emitStudioProject(p).find((f) => f.path === 'src/routes/customers/+page.svelte')!
+    expect(page.contents).toContain('class="my-grid highlight"')
+    // kpi keeps its base class, appends the (sanitized) user class - no attribute break-out.
+    expect(page.contents).toContain('class="kpi evilonloadx"')
+    expect(page.contents).not.toContain('onload=x')
+    expect(() => compile(page.contents, { filename: page.path, generate: 'client' })).not.toThrow()
+  })
+
+  it('per-screen className lands on .st-screen; app className lands on the shell root', () => {
+    let p = createProject([customers])
+    const sid = p.screens[0]!.id
+    p = updateScreen(p, sid, { className: 'crm-screen' })
+    p = setTheme(p, { appClass: 'brand-app' })
+    const files = emitStudioProject(p)
+    const page = files.find((f) => f.path === 'src/routes/customers/+page.svelte')!
+    expect(page.contents).toContain('<div class="st-screen crm-screen">')
+    const layout = files.find((f) => f.path === 'src/routes/+layout.svelte')!
+    expect(layout.contents).toMatch(/class="sv-app sv-app--\w+ brand-app"/)
+    expect(() => compile(page.contents, { filename: page.path, generate: 'client' })).not.toThrow()
+    expect(() => compile(layout.contents, { filename: layout.path, generate: 'client' })).not.toThrow()
+  })
+
+  it('ctxAmbientDts type-checks real ctx usage and catches grid/data typos (editor TS surface)', () => {
+    let p = createProject([customers])
+    const sid = p.screens.find((s) => s.entity === 'customers')!.id
+    p = addBlock(p, sid, 'chart')
+    p = addComponentBlock(p, sid, 'button', {})
+    p = enableScreenCode(p, sid)
+    const screen = p.screens.find((s) => s.id === sid)!
+    const dts = ctxAmbientDts(screen, customers)
+    // Valid, real code compiles clean: awaited grid export, feed a chart from the
+    // dataset, type a component setter, navigate, read a param.
+    expect(typeCheckBody(dts, [
+      'const csv = await ctx.grid.exportCsv()',
+      'console.log(csv.length)',
+      'ctx.chart1.setData(ctx.data.rows)',
+      "ctx.button1.setVariant('danger')",
+      "ctx.button1.variant = 'ghost'",        // prop assignment, not just the setter
+      'ctx.button1.disabled = true',
+      "ctx.button1.text = 'Save'",
+      "ctx.goto('/orders')",
+      'const id = ctx.params.id',
+      'ctx.grid.setSort("mrr", "desc")',
+    ].join('\n'))).toEqual([])
+    // Assigning the wrong type to a typed prop is caught.
+    expect(typeCheckBody(dts, "ctx.button1.variant = 'nope'").length).toBeGreaterThan(0)
+    expect(typeCheckBody(dts, 'ctx.button1.disabled = 5').length).toBeGreaterThan(0)
+    // A misspelled grid method is a hard error (SvGridApi is precisely typed).
+    const gridTypo = typeCheckBody(dts, 'ctx.grid.exprtCsv()')
+    expect(gridTypo.length).toBeGreaterThan(0)
+    expect(gridTypo.join(' ')).toMatch(/exprtCsv/)
+    // Feeding a chart the wrong element type is caught (DataHandle<Customers>).
+    expect(typeCheckBody(dts, 'ctx.chart1.setData([1, 2, 3])').length).toBeGreaterThan(0)
+    // An unknown ctx member is caught.
+    expect(typeCheckBody(dts, 'ctx.notAThing()').length).toBeGreaterThan(0)
+  })
+
+  it('onDestroy is a first-class slot in handlers.ts + page-context manifest', () => {
+    let p = createProject([customers])
+    const sid = p.screens.find((s) => s.entity === 'customers')!.id
+    p = setHandlerBody(p, sid, 'onDestroy', 'clearInterval(timer)')
+    const route = p.screens.find((s) => s.id === sid)!.route
+    const companion = emitStudioProject(p).find((f) => f.path === `src/routes/${route}/handlers.ts`)!
+    expect(companion.contents).toContain('export function onDestroy(ctx: PageContext): void')
+    expect(companion.contents).toContain('clearInterval(timer)')
   })
 })