@svgrid/enterprise 2.5.2 → 2.6.0

package/dist/studio/project.js

@@ -0,0 +1,1798 @@
+import { collectColumnRefs } from '../expressions/parse.js';
+import { uiComponentSpec } from './ui-components.js';
+/** Block kinds allowed inside a Tabs / Accordion container: the controller-free,
+ *  `allRows`-driven display blocks (no grid / form / master-detail, which need the
+ *  screen controller). `component` covers any UI-kit component added by key. */
+export const TAB_CHILD_KINDS = ['chart', 'kpi', 'gauge', 'dashboard', 'pivot', 'tree', 'component'];
+/** Alias: the same set applies to Accordion sections. */
+export const CONTAINER_CHILD_KINDS = TAB_CHILD_KINDS;
+/** Display-block child kinds (no `component`) - what the container "add block" menu offers;
+ *  components are added separately, by registry key, via `addContainerComponent`. */
+export const CONTAINER_DISPLAY_KINDS = ['chart', 'kpi', 'gauge', 'dashboard', 'pivot', 'tree'];
+/** All blocks on a screen, flattened to include the children nested in Tabs
+ *  containers - used to detect kinds for imports / data loading. */
+export function flattenBlocks(blocks) {
+    const out = [];
+    for (const b of blocks) {
+        out.push(b);
+        if (b.config.kind === 'tabs')
+            for (const t of b.config.tabs)
+                out.push(...flattenBlocks(t.blocks));
+        if (b.config.kind === 'accordion')
+            for (const s of b.config.sections)
+                out.push(...flattenBlocks(s.blocks));
+    }
+    return out;
+}
+/** Sanitize a user-typed class list to a safe value (letters/digits/_/- and spaces) so
+ *  it can never break out of a `class="..."` attribute. Shared by block/screen/app. */
+export function sanitizeClassName(raw) {
+    return (raw ?? '').replace(/[^a-zA-Z0-9 _-]/g, '').trim().replace(/\s+/g, ' ').slice(0, 120);
+}
+/** The sanitized extra class(es) for a block's wrapper. */
+export function blockClassName(block) {
+    return sanitizeClassName(block.className);
+}
+/** The number of columns (1-12) a block occupies in the 12-col layout. */
+export const blockColumns = (b) => 
+// Default to full width when a block sets neither colSpan nor span (Copilot /
+// hand-authored configs may omit both) - never emit `span NaN` into the HTML.
+Math.max(1, Math.min(12, Math.round(b.colSpan ?? (b.span != null ? b.span * 4 : 12))));
+/** Restrict a user-typed color to a safe subset so it can't break out of an inline
+ *  `style="..."` attribute (hex, rgb()/hsl(), named colors, css vars). */
+const safeColor = (c) => c.replace(/[^#a-zA-Z0-9(),.%\s_-]/g, '').slice(0, 64);
+/** The CSS declarations for a block's style overrides, for its wrapper element - shared
+ *  by codegen and the designer so the preview matches the generated app. Empty when no
+ *  overrides. Numeric fields are safe; the background color is sanitized. */
+export function blockStyleCss(style) {
+    if (!style)
+        return '';
+    const d = [];
+    if (style.border === true)
+        d.push('border: 1px solid var(--sg-border, #e6e8ec)');
+    else if (style.border === false)
+        d.push('border: none');
+    if (style.shadow === true)
+        d.push('box-shadow: 0 1px 2px rgba(15, 23, 42, 0.06)');
+    else if (style.shadow === false)
+        d.push('box-shadow: none');
+    if (typeof style.padding === 'number')
+        d.push(`padding: ${style.padding}px`);
+    if (typeof style.margin === 'number')
+        d.push(`margin: ${style.margin}px`);
+    if (style.background)
+        d.push(`background: ${safeColor(style.background)}`);
+    if (typeof style.radius === 'number')
+        d.push(`border-radius: ${style.radius}px`);
+    return d.join('; ');
+}
+/** Merge a partial style patch over a block's style, dropping keys set to undefined;
+ *  returns undefined when nothing is left (keeps the model + serialized config clean). */
+export function mergeBlockStyle(base, patch) {
+    const merged = { ...base, ...patch };
+    for (const k of Object.keys(merged))
+        if (merged[k] === undefined)
+            delete merged[k];
+    return Object.keys(merged).length ? merged : undefined;
+}
+/** The always-present page lifecycle handlers the Code view edits. Kept as named
+ *  constants so codegen, the designer, and the manifest agree on the slot names.
+ *  `onLoad` runs on mount (with the page context); `onDestroy` runs on unmount
+ *  (cleanup: timers, subscriptions, aborts). */
+export const ON_LOAD = 'onLoad';
+export const ON_DESTROY = 'onDestroy';
+/** Every lifecycle slot the Code view can edit, in display order. */
+export const HANDLER_SLOTS = [ON_LOAD, ON_DESTROY];
+/** The handler-steps key for a component block's click event. */
+export const clickSlot = (blockId) => `click:${blockId}`;
+/** The handler-steps key for a grid block's row-select (row click) event. The
+ *  compiled steps get the clicked `row` in scope (use row-field values). */
+export const rowSelectSlot = (blockId) => `rowSelect:${blockId}`;
+/** The handler-steps key for a component block's change (value change) event. */
+export const changeSlot = (blockId) => `change:${blockId}`;
+/** Generic event slot - `click`/`change` produce the same keys as clickSlot/changeSlot,
+ *  so existing projects keep their wiring; any other declared component event
+ *  (focus, select, toggle, ...) gets its own `<event>:<blockId>` slot. */
+export const eventSlot = (event, blockId) => `${event}:${blockId}`;
+/** The handler-steps key for the screen's form-submit (record saved) event. The
+ *  compiled steps get the submitted `row` (values) in scope. */
+export const FORM_SUBMIT = 'formSubmit';
+/** The Grid's real event surface (mirrors SvGrid's `on*` callbacks). Studio wires
+ *  every one into `ctx.grid` so page code can subscribe with `ctx.grid.onCellClick =
+ *  (e) => {}`. `params` is the handler's parameter list, with `Row` as the row-type
+ *  placeholder (substituted per screen). `builtin` marks events a Studio feature may
+ *  already use (sort/filter/paginate/edit/row-click) - codegen COMPOSES the user's
+ *  handler onto the built-in rather than emitting a duplicate prop. Signatures are
+ *  transcribed from packages/grid/src/SvGrid.types.ts. */
+export const GRID_EVENTS = [
+    { key: 'rowClick', method: 'onRowClick', prop: 'onRowClick', builtin: true, desc: 'A data row is single-clicked.', params: 'e: { rowIndex: number; columnId: string; row: Row }' },
+    { key: 'rowDoubleClick', method: 'onRowDoubleClick', prop: 'onRowDoubleClick', builtin: true, desc: 'A data row is double-clicked.', params: 'e: { rowIndex: number; columnId: string; row: Row }' },
+    { key: 'cellClick', method: 'onCellClick', prop: 'onCellClick', builtin: false, desc: 'A data cell is single-clicked.', params: 'e: { rowIndex: number; colIndex: number; columnId: string; value: unknown; row: Row }' },
+    { key: 'cellDoubleClick', method: 'onCellDoubleClick', prop: 'onCellDoubleClick', builtin: false, desc: 'A data cell is double-clicked.', params: 'e: { rowIndex: number; colIndex: number; columnId: string; value: unknown; row: Row }' },
+    { key: 'rowSelectionChange', method: 'onRowSelectionChange', prop: 'onRowSelectionChange', builtin: false, desc: 'The row selection changes.', params: 'selection: Record<string, boolean>, rows: Row[]' },
+    { key: 'cellSelectionChange', method: 'onCellSelectionChange', prop: 'onCellSelectionChange', builtin: false, desc: 'The cell-selection rectangle changes.', params: 'ranges: Array<[number, number, number, number]>' },
+    { key: 'activeCellChange', method: 'onActiveCellChange', prop: 'onActiveCellChange', builtin: false, desc: 'The active cell changes.', params: 'cell: { rowIndex: number; colIndex: number; columnId: string }' },
+    { key: 'cellValueChange', method: 'onCellValueChange', prop: 'onCellValueChange', builtin: true, desc: 'An inline cell edit is committed.', params: 'e: { rowIndex: number; columnId: string; oldValue: unknown; newValue: unknown; row: Row }' },
+    { key: 'sortingChange', method: 'onSortingChange', prop: 'onSortingChange', builtin: true, desc: 'The sort clauses change.', params: 'sorting: Array<{ id: string; desc: boolean }>' },
+    { key: 'filtersChange', method: 'onFiltersChange', prop: 'onFiltersChange', builtin: true, desc: 'Any in-grid filter changes.', params: 'filters: { global: string; columns: Array<{ id: string; operator: string; value: string; valueTo?: string; selectedValues?: string[] }> }' },
+    { key: 'paginationChange', method: 'onPaginationChange', prop: 'onPaginationChange', builtin: true, desc: 'The page or page size changes.', params: 'pagination: { pageIndex: number; pageSize: number }' },
+    { key: 'columnOrderChange', method: 'onColumnOrderChange', prop: 'onColumnOrderChange', builtin: false, desc: 'The column order changes.', params: 'order: ReadonlyArray<string>' },
+    { key: 'scrollBottomReached', method: 'onScrollBottomReached', prop: 'onScrollBottomReached', builtin: false, desc: 'The body scrolls near the bottom (lazy-load hook).', params: 'e: { scrollTop: number; scrollHeight: number; clientHeight: number }' },
+    { key: 'noteChange', method: 'onNoteChange', prop: 'onNoteChange', builtin: false, desc: 'A cell note/comment is saved or removed (needs editable comments).', params: 'e: { rowId: string; columnId: string; note: string }' },
+    { key: 'rowDragEnd', method: 'onRowDragEnd', prop: 'onRowDragEnd', builtin: false, desc: 'A managed row drag settles (needs row dragging enabled).', params: 'e: { row: Row; toIndex: number; sameGrid: boolean; fromGridId: number; toGridId: number }' },
+    // Data-layer events - fired by the screen's data controller after a write settles
+    // (form save, inline edit, delete action, or ctx.data.create/update/delete), not by
+    // the grid markup. Only fire on entity screens (which have a data source).
+    { key: 'rowAdded', method: 'onRowAdded', prop: '', builtin: false, dataEvent: true, desc: 'A row was created (form / ctx.data.create).', params: 'row: Row' },
+    { key: 'rowUpdated', method: 'onRowUpdated', prop: '', builtin: false, dataEvent: true, desc: 'A row was updated (form / inline edit / ctx.data.update).', params: 'row: Row' },
+    { key: 'rowDeleted', method: 'onRowDeleted', prop: '', builtin: false, dataEvent: true, desc: 'A row was deleted (delete action / ctx.data.delete).', params: 'id: string' },
+];
+const identSafe = (s) => (s || '').replace(/[^a-zA-Z0-9_$]/g, '_').replace(/^([0-9])/, '_$1') || 'v';
+/** The `$state(...)` initializer for a variable's declared type. */
+export function stateInitExpr(v) {
+    const raw = (v.initial ?? '').trim();
+    switch (v.type) {
+        case 'number': return raw === '' || Number.isNaN(Number(raw)) ? '0' : raw;
+        case 'boolean': return raw === 'true' ? 'true' : 'false';
+        case 'json': return raw || 'null';
+        case 'string': return q(v.initial ?? '');
+    }
+}
+/** The TS type annotation for a variable. */
+export function stateTsType(v) {
+    return v.type === 'number' ? 'number' : v.type === 'boolean' ? 'boolean' : v.type === 'json' ? 'unknown' : 'string';
+}
+export function compileValue(v, rowExpr = 'row') {
+    switch (v.kind) {
+        case 'state': return `ctx.state.${identSafe(v.name)}`;
+        case 'param': return `ctx.params[${q(v.name)}]`;
+        case 'field': return `${rowExpr}?.[${q(v.name)}]`;
+        case 'literal': return litValue(v.value);
+    }
+}
+export function compileCondition(c, rowExpr = 'row') {
+    const L = compileValue(c.left, rowExpr);
+    const R = c.right ? compileValue(c.right, rowExpr) : "''";
+    switch (c.op) {
+        case 'eq': return `${L} === ${R}`;
+        case 'neq': return `${L} !== ${R}`;
+        case 'gt': return `Number(${L}) > Number(${R})`;
+        case 'lt': return `Number(${L}) < Number(${R})`;
+        case 'gte': return `Number(${L}) >= Number(${R})`;
+        case 'lte': return `Number(${L}) <= Number(${R})`;
+        case 'contains': return `String(${L}).includes(String(${R}))`;
+        case 'truthy': return `Boolean(${L})`;
+        case 'falsy': return `!(${L})`;
+    }
+}
+const compileFields = (fs) => `{ ${fs.map((f) => `${identSafe(f.field)}: ${compileValue(f.value)}`).join(', ')} }`;
+const q = (s) => `'${String(s).replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+/** Emit a value literal: true/false/number bare, else a quoted string. */
+const litValue = (v) => {
+    const t = v.trim();
+    if (t === 'true' || t === 'false')
+        return t;
+    if (t !== '' && !Number.isNaN(Number(t)))
+        return t;
+    return q(v);
+};
+/** Compile one step to a `ctx` statement (a single line, no trailing newline). */
+export function compileStep(step) {
+    switch (step.type) {
+        case 'navigate': return `ctx.goto(${q(step.to)})`;
+        case 'gridExport': {
+            const fmt = step.format ?? 'csv';
+            const fn = fmt === 'tsv' ? 'exportTsv' : fmt === 'json' ? 'exportJson' : 'exportCsv';
+            const mime = fmt === 'json' ? 'application/json' : fmt === 'tsv' ? 'text/tab-separated-values' : 'text/csv';
+            // A scoped block so the locals don't collide when there are two export steps.
+            return [
+                '{',
+                `  const data = await ctx.grid.${fn}()`,
+                "  const link = document.createElement('a')",
+                `  link.href = URL.createObjectURL(new Blob([data], { type: ${q(mime)} }))`,
+                `  link.download = ${q('export.' + fmt)}`,
+                '  link.click()',
+                '  URL.revokeObjectURL(link.href)',
+                '}',
+            ].join('\n');
+        }
+        case 'gridCopy': return `ctx.grid.copyToClipboard()`;
+        case 'gridClear': return step.what === 'sort' ? `ctx.grid.clearSort()` : step.what === 'selection' ? `ctx.grid.clearRowSelection()` : `ctx.grid.clearAllFilters()`;
+        case 'gridSort': return `ctx.grid.setSort(${q(step.field)}, ${q(step.dir ?? 'asc')})`;
+        case 'gridFilter': return `ctx.grid.setFilter(${q(step.field)}, { operator: 'contains', value: ${q(step.value)} })`;
+        case 'reloadData': return `await ctx.data.reload()`;
+        case 'setProp': return `ctx.${step.target}.${step.prop} = ${litValue(step.value)}`;
+        case 'setText': return `ctx.${step.target}.text = ${litValue(step.value)}`;
+        case 'alert': return `alert(${q(step.message)})`;
+        case 'apiAction': return `await fetch(${q('/api/actions/' + step.actionId)}, { method: 'POST' })`;
+        case 'setVar': return `ctx.state.${identSafe(step.name)} = ${compileValue(step.value)}`;
+        case 'createRecord': return `await ctx.data.create(${compileFields(step.values)})`;
+        case 'updateRecord': return `await ctx.data.update(${compileValue(step.id)}, ${compileFields(step.values)})`;
+        case 'deleteRecord': return `await ctx.data.delete(${compileValue(step.id)})`;
+        case 'branch': {
+            const body = indentLines(compileHandlerSteps(step.then));
+            const elseB = step.else?.length ? ` else {\n${indentLines(compileHandlerSteps(step.else))}\n}` : '';
+            return `if (${compileCondition(step.condition)}) {\n${body}\n}${elseB}`;
+        }
+        case 'code': return step.code;
+    }
+}
+/** Indent every line by 2 spaces (nested branch bodies). */
+const indentLines = (s) => s.split('\n').map((l) => (l ? '  ' + l : l)).join('\n');
+/** Compile a list of steps to a handler body (indented lines). */
+export function compileHandlerSteps(steps) {
+    return steps.map((s) => compileStep(s)).join('\n');
+}
+/** All trigger events, in display order; before-hooks transform/validate, after-hooks are side effects. */
+export const TRIGGER_EVENTS = ['beforeCreate', 'afterCreate', 'beforeUpdate', 'afterUpdate', 'beforeDelete', 'afterDelete'];
+/** Compile one trigger step against the payload variable `rowExpr` (default `v`). */
+export function compileTriggerStep(step, rowExpr = 'v') {
+    switch (step.type) {
+        case 'setField': return `${rowExpr}[${q(step.field)}] = ${compileValue(step.value, rowExpr)}`;
+        case 'requireField': return `if (${rowExpr}[${q(step.field)}] == null || ${rowExpr}[${q(step.field)}] === '') throw new Error(${q(step.message || step.field + ' is required')})`;
+        case 'reject': return `if (${compileCondition(step.condition, rowExpr)}) throw new Error(${q(step.message)})`;
+        case 'branch': {
+            const body = indentLines(compileTriggerSteps(step.then, rowExpr));
+            const elseB = step.else?.length ? ` else {\n${indentLines(compileTriggerSteps(step.else, rowExpr))}\n}` : '';
+            return `if (${compileCondition(step.condition, rowExpr)}) {\n${body}\n}${elseB}`;
+        }
+        case 'code': return step.code;
+    }
+}
+export function compileTriggerSteps(steps, rowExpr = 'v') {
+    return steps.map((s) => compileTriggerStep(s, rowExpr)).join('\n');
+}
+/** Layouts that arrange blocks as dockable / split panes (both back onto a
+ *  serialized `DockManagerState`; `split` renders it locked = resize-only). */
+export const PANE_LAYOUTS = ['split', 'dock'];
+export function isPaneLayout(layout) { return PANE_LAYOUTS.includes(layout); }
+export const CANVAS_COLS = 12;
+/** Height of one canvas row in px (grid-auto-rows), shared by designer + codegen. */
+export const CANVAS_ROW_PX = 40;
+/** Gap between canvas cells in px. */
+export const CANVAS_GAP_PX = 8;
+/** `maxWidth: 0` (or absent) means full-bleed. */
+export const GRID_OPT_DEFAULTS = { colGap: 16, rowGap: 16, maxWidth: 0, align: 'start', mobileBreakpoint: 720 };
+export const STACK_OPT_DEFAULTS = { gap: 16, maxWidth: 0, align: 'left', dividers: false, minHeight: 160 };
+export const SPLIT_OPT_DEFAULTS = { orientation: 'auto', minPaneSize: 80, persist: true };
+export const DOCK_OPT_DEFAULTS = { allowPopout: false, hideSingleTab: false, headerPosition: 'top', persist: true };
+export const CANVAS_OPT_DEFAULTS = { cols: CANVAS_COLS, rowHeight: CANVAS_ROW_PX, gap: CANVAS_GAP_PX, showGrid: false };
+export const gridOpts = (s) => ({ ...GRID_OPT_DEFAULTS, ...s.layoutOpts?.grid });
+export const stackOpts = (s) => ({ ...STACK_OPT_DEFAULTS, ...s.layoutOpts?.stack });
+export const splitOpts = (s) => ({ ...SPLIT_OPT_DEFAULTS, ...s.layoutOpts?.split });
+export const dockOpts = (s) => ({ ...DOCK_OPT_DEFAULTS, ...s.layoutOpts?.dock });
+export const canvasOpts = (s) => ({ ...CANVAS_OPT_DEFAULTS, ...s.layoutOpts?.canvas });
+/** Patch one mode's settings (merged over any existing values). */
+export function setLayoutOpts(project, screenId, mode, patch) {
+    return mapScreen(project, screenId, (s) => ({ ...s, layoutOpts: { ...s.layoutOpts, [mode]: { ...s.layoutOpts?.[mode], ...patch } } }));
+}
+export const CRUD_ACTIONS = ['create', 'update', 'delete'];
+/** Does a role's rules permit opening a screen? */
+export const roleCanScreen = (r, screenId) => r.screens === '*' || r.screens.includes(screenId);
+/** Does a role's rules permit a write action? */
+export const roleCanAction = (r, action) => r.actions === '*' || r.actions.includes(action);
+/** The render mode for a screen. `'ssr'` emits idiomatic SvelteKit (`+page.server.ts`
+ *  with a `load` + form `actions`, SSR + progressive enhancement); `'spa'` (the
+ *  default) emits the client data-source-controller page. Opt-in for now. */
+export function screenRenderMode(_project, screen) {
+    return screen.renderMode === 'ssr' ? 'ssr' : 'spa';
+}
+/** Block kinds a read-only SSR screen can host: pure renders over server-loaded
+ *  rows. Board/calendar/scheduler (client interaction runtimes), components
+ *  (client bindings), grids-with-extras, and containers stay SPA. */
+const SSR_READ_KINDS = new Set(['chart', 'pivot', 'dashboard', 'kpi', 'gauge', 'tree', 'detail', 'master-detail']);
+/** How a screen would emit under SSR: 'grid' (single grid -> load + form actions,
+ *  URL-driven sort/filter/page), 'read' (data-viz/detail blocks -> load only), or
+ *  null when it must stay SPA. */
+export function ssrScreenShape(project, screen) {
+    if (!screen.entity || screen.code)
+        return null;
+    const source = project.dataSources?.[screen.entity];
+    const kind = source?.kind ?? project.dataSource;
+    // memory runs the source in-process; sql reuses the connected /api route via
+    // event.fetch; rest calls the remote API straight from the server, which needs
+    // an absolute URL to resolve there. (supabase and pglite stay SPA: pglite only
+    // exists in the browser, and a Supabase read carries the signed-in user's token,
+    // which a server-side call with the anon key would silently drop.)
+    if (kind === 'rest') {
+        if (!(source?.kind === 'rest' && /^https?:\/\//i.test(source.baseUrl ?? '')))
+            return null;
+    }
+    else if (kind !== 'memory' && kind !== 'sql') {
+        return null;
+    }
+    const blocks = screen.blocks ?? [];
+    // A grid, optionally preceded by a facet panel. The panel is the reason this
+    // allowance exists: every list screen the generator produces is [filter, grid],
+    // so without it the shipped app shape could never render on the server. Facets
+    // map cleanly onto the URL params `planFromSearchParams` already reads.
+    const grids = blocks.filter((b) => b.config.kind === 'grid');
+    if (grids.length === 1 && blocks.every((b) => b.config.kind === 'grid' || b.config.kind === 'filter')) {
+        const g = grids[0].config;
+        if (g.treeData || g.scheduler)
+            return null;
+        return 'grid';
+    }
+    if (blocks.length >= 1 && blocks.every((b) => SSR_READ_KINDS.has(b.config.kind)))
+        return 'read';
+    return null;
+}
+/** Whether a screen can be emitted as SSR-native (any supported shape). */
+export function ssrEligible(project, screen) {
+    return ssrScreenShape(project, screen) !== null;
+}
+/** Set a screen's render mode ('spa' clears back to the default). */
+export function setScreenRenderMode(project, screenId, mode) {
+    return {
+        ...project,
+        screens: project.screens.map((s) => (s.id === screenId ? { ...s, renderMode: mode === 'ssr' ? 'ssr' : undefined } : s)),
+    };
+}
+/** True when the screen should actually emit as SSR (mode is 'ssr' AND eligible). */
+export function isSsrScreen(project, screen) {
+    return screenRenderMode(project, screen) === 'ssr' && ssrEligible(project, screen);
+}
+/**
+ * Turn server rendering on for every screen that can support it, for entities
+ * backed by a real database. Applied when a project is first generated, so a new
+ * app reads as idiomatic SvelteKit (a `load` and form `actions`) rather than a
+ * client SPA. Screens that already state a mode are left alone, so this never
+ * overrides a choice somebody made.
+ *
+ * Deliberately limited to sources that hold one copy of the data. In-memory and
+ * PGlite sources are module singletons, so an SSR screen would read and write the
+ * *server's* copy of the rows while the app's remaining SPA screens read the
+ * browser's - create a row on one and the other never sees it. SQL and REST have
+ * no such split: every path goes to the same database or the same remote API.
+ */
+const SSR_DEFAULT_KINDS = new Set(['sql', 'rest']);
+export function withSsrDefaults(project) {
+    return {
+        ...project,
+        screens: project.screens.map((screen) => {
+            if (screen.renderMode || !screen.entity)
+                return screen;
+            const kind = project.dataSources?.[screen.entity]?.kind ?? project.dataSource;
+            if (!SSR_DEFAULT_KINDS.has(kind))
+                return screen;
+            return ssrEligible(project, screen) ? { ...screen, renderMode: 'ssr' } : screen;
+        }),
+    };
+}
+/** The triggers configured for an entity (or an empty object). */
+export function triggersOf(project, entity) {
+    return project.triggers?.[entity] ?? {};
+}
+/** Set (or clear, with `null`) an entity's steps for one trigger event. */
+export function setTrigger(project, entity, event, steps) {
+    const cur = project.triggers?.[entity] ?? {};
+    const nextEnt = { ...cur };
+    if (steps && steps.length)
+        nextEnt[event] = steps;
+    else
+        delete nextEnt[event];
+    const triggers = { ...project.triggers };
+    if (Object.keys(nextEnt).length)
+        triggers[entity] = nextEnt;
+    else
+        delete triggers[entity];
+    return { ...project, triggers: Object.keys(triggers).length ? triggers : undefined };
+}
+/** Turn multi-tenancy on/off and configure the scoping column. */
+export function setTenancy(project, tenancy) {
+    if (!tenancy || !tenancy.enabled) {
+        const { tenancy: _drop, ...rest } = project;
+        return rest;
+    }
+    return { ...project, tenancy };
+}
+/** The tenant column name, defaulted. */
+export const tenantField = (project) => project.tenancy?.field || 'tenantId';
+/** True when `entity` is scoped to a tenant (i.e. tenancy is on and it is not
+ *  listed as shared). Shared entities stay global reference data. */
+export function isTenantScoped(project, entity) {
+    if (project.tenancy?.enabled !== true)
+        return false;
+    return !(project.tenancy.sharedEntities ?? []).includes(entity);
+}
+/** Add or replace a scheduled job (matched by `id`). Pass `null` to remove one. */
+export function setJob(project, id, job) {
+    const rest = (project.jobs ?? []).filter((j) => j.id !== id);
+    const next = job ? [...rest, { ...job, id }] : rest;
+    return { ...project, jobs: next.length ? next : undefined };
+}
+/** The designer's block palette, in menu order. (Editing is a Grid property, so
+ *  there's no standalone form block.) */
+export const blockPalette = [
+    { kind: 'grid', label: 'Grid' },
+    { kind: 'chart', label: 'Chart', needs: 'measure' },
+    { kind: 'pivot', label: 'Pivot', needs: 'measure' },
+    { kind: 'dashboard', label: 'Dashboard' },
+    { kind: 'kpi', label: 'KPI tile', needs: 'measure' },
+    { kind: 'gauge', label: 'Gauge', needs: 'measure' },
+    { kind: 'tree', label: 'Tree' },
+    { kind: 'tabs', label: 'Tabs' },
+    { kind: 'accordion', label: 'Accordion' },
+    { kind: 'master-detail', label: 'Master / detail', needs: 'child' },
+    { kind: 'board', label: 'Board' },
+    { kind: 'calendar', label: 'Calendar' },
+    { kind: 'detail', label: 'Detail page' },
+    { kind: 'filter', label: 'Filter panel' },
+    { kind: 'record', label: 'Record panel' },
+    { kind: 'lookup', label: 'Lookup' },
+];
+// --- helpers ---------------------------------------------------------------
+/** A free `${prefix}${n}` id not already in `taken`. */
+function uid(prefix, taken) {
+    let n = 1;
+    while (taken.has(`${prefix}${n}`))
+        n++;
+    return `${prefix}${n}`;
+}
+export function entityOf(project, name) {
+    if (name == null)
+        return undefined;
+    return project.entities.find((e) => e.name === name);
+}
+const gridHidden = (f) => f.hidden === true || (typeof f.hidden === 'object' && f.hidden.grid === true);
+function pickDimension(entity) {
+    const nonKey = entity.fields.filter((f) => !f.primaryKey);
+    // Prefer a low-cardinality dimension: enum, then boolean, then text.
+    return (nonKey.find((f) => f.type === 'enum')?.field ??
+        nonKey.find((f) => f.type === 'boolean')?.field ??
+        nonKey.find((f) => f.type === 'text')?.field ??
+        nonKey[0]?.field ??
+        entity.fields[0]?.field ??
+        '');
+}
+function pickMeasure(entity) {
+    return entity.fields.find((f) => f.type === 'number' && !f.primaryKey)?.field;
+}
+/** Sensible grid columns for an entity: every non-grid-hidden field, shown. */
+export function gridColumns(entity) {
+    const pk = entity.idField ?? entity.fields.find((f) => f.primaryKey)?.field;
+    return entity.fields
+        .filter((f) => !gridHidden(f))
+        // Hide the raw primary-key column by default (a "co1 / dl2" id column reads
+        // as unfinished); everything else is visible. Users can re-enable it.
+        .map((f) => ({ field: f.field, show: f.field !== pk, header: f.label }));
+}
+/** A default config for a freshly-added block of `kind`, sized for the entity. */
+export function defaultBlockConfig(kind, entity) {
+    switch (kind) {
+        case 'grid':
+            return { kind, columns: gridColumns(entity), pageSize: 10, selectable: true, sortable: true, filterable: false, editing: 'form', formPresentation: 'modal', density: 'normal', striped: false, cellSelection: false, rowSummaries: false, paginated: true, paginationPosition: 'bottom', pageSizeOptions: [10, 25, 50, 100] };
+        case 'form':
+            return { kind, presentation: 'modal' };
+        case 'chart': {
+            const measure = pickMeasure(entity);
+            return { kind, dimension: pickDimension(entity), measure, reduce: measure ? 'sum' : 'count', type: 'bar' };
+        }
+        case 'kpi': {
+            const measure = pickMeasure(entity);
+            return { kind, label: measure ? `Total ${measure}` : `Total ${entity.label ?? entity.name}`, measure, reduce: measure ? 'sum' : 'count' };
+        }
+        case 'gauge': {
+            const measure = pickMeasure(entity);
+            return { kind, label: measure ? `Avg ${measure}` : `${entity.label ?? entity.name} count`, measure, reduce: measure ? 'avg' : 'count', min: 0, max: 100 };
+        }
+        case 'tree': {
+            const label = entity.fields.find((f) => !f.primaryKey && f.type === 'text')?.field ?? entity.fields.find((f) => !f.primaryKey)?.field ?? entity.fields[0]?.field ?? '';
+            // A self-referential FK (relation back to this entity) is the natural parent link; else guess by name.
+            const parent = entity.fields.find((f) => f.type === 'relation' && f.relation?.entity === entity.name)?.field
+                ?? entity.fields.find((f) => /parent/i.test(f.field))?.field ?? '';
+            return { kind, labelField: label, parentField: parent };
+        }
+        case 'tabs':
+            return { kind, tabs: [{ label: 'Overview', blocks: [] }, { label: 'Details', blocks: [] }] };
+        case 'accordion':
+            return { kind, sections: [{ label: 'Section 1', blocks: [] }, { label: 'Section 2', blocks: [] }], multiple: false };
+        case 'dashboard':
+            return { kind };
+        case 'master-detail':
+            return { kind, childEntity: '', foreignKey: '' };
+        case 'lookup':
+            return { kind, field: entity.fields.find((f) => f.type === 'relation')?.field ?? entity.fields[0]?.field ?? '' };
+        case 'pivot': {
+            const measure = pickMeasure(entity);
+            const dim = pickDimension(entity);
+            return { kind, rows: dim ? [dim] : [], cols: [], measure, aggregate: measure ? 'sum' : 'count' };
+        }
+        case 'filter':
+            return { kind, fields: pickFacetFields(entity) };
+        case 'record':
+            return { kind, editable: false };
+        case 'board': {
+            const enumField = entity.fields.find((f) => f.type === 'enum' && !f.primaryKey)?.field ?? '';
+            const titleF = entity.fields.find((f) => f.type === 'text' && !f.primaryKey)?.field ?? entity.fields.find((f) => !f.primaryKey)?.field ?? '';
+            const badge = pickMeasure(entity);
+            return { kind, groupBy: enumField, titleField: titleF, ...(badge ? { badgeField: badge } : {}) };
+        }
+        case 'calendar': {
+            const dateF = entity.fields.find((f) => (f.type === 'datetime' || f.type === 'date' || f.type === 'dateString') && !f.primaryKey)?.field ?? '';
+            const titleF = entity.fields.find((f) => f.type === 'text' && !f.primaryKey)?.field ?? entity.fields.find((f) => !f.primaryKey)?.field ?? '';
+            const colorF = entity.fields.find((f) => f.type === 'enum' && !f.primaryKey)?.field;
+            return { kind, dateField: dateF, titleField: titleF, ...(colorF ? { colorField: colorF } : {}) };
+        }
+        case 'detail': {
+            const nonKey = entity.fields.filter((f) => !f.primaryKey);
+            const titleF = nonKey.find((f) => f.type === 'text')?.field ?? nonKey[0]?.field ?? entity.fields[0]?.field ?? '';
+            const statusF = nonKey.find((f) => f.type === 'enum')?.field;
+            const subF = nonKey.find((f) => (f.type === 'text' || f.type === 'relation') && f.field !== titleF)?.field;
+            const metrics = nonKey.filter((f) => f.type === 'number').slice(0, 3).map((f) => f.field);
+            return { kind, titleField: titleF, ...(subF ? { subtitleField: subF } : {}), ...(statusF ? { statusField: statusF } : {}), ...(metrics.length ? { metricFields: metrics } : {}) };
+        }
+        case 'component':
+            // Entity-agnostic - built directly by `addComponentBlock`, never through here.
+            return { kind, component: '', props: {} };
+    }
+}
+/** Low-cardinality, filter-friendly fields (enum, boolean, then text), non-key.
+ *  Used to seed the faceted Filter panel. Caps at 4 so the panel stays compact. */
+export function pickFacetFields(entity) {
+    return entity.fields
+        .filter((f) => !f.primaryKey && (f.type === 'enum' || f.type === 'boolean' || f.type === 'text'))
+        .sort((a, b) => facetRank(a.type) - facetRank(b.type))
+        .slice(0, 4)
+        .map((f) => f.field);
+}
+const facetRank = (t) => (t === 'enum' ? 0 : t === 'boolean' ? 1 : 2);
+const DEFAULT_SPAN = {
+    grid: 3, form: 1, chart: 2, dashboard: 3, kpi: 1, gauge: 1, tree: 2, tabs: 3, accordion: 3, 'master-detail': 3, lookup: 1, pivot: 3, filter: 1, record: 1, board: 3, calendar: 3, detail: 3, component: 1,
+};
+function makeBlock(kind, entity, taken) {
+    return { id: uid(`${kind}-`, taken), span: DEFAULT_SPAN[kind], config: defaultBlockConfig(kind, entity) };
+}
+// --- Tabs container ops (pure; the designer builds a new config + updateBlock) ---
+/** Append a tab to a Tabs container. */
+export function addTab(cfg, label) {
+    return { ...cfg, tabs: [...cfg.tabs, { label: label ?? `Tab ${cfg.tabs.length + 1}`, blocks: [] }] };
+}
+/** Remove a tab by index (keeps at least one). */
+export function removeTab(cfg, index) {
+    if (cfg.tabs.length <= 1)
+        return cfg;
+    return { ...cfg, tabs: cfg.tabs.filter((_, i) => i !== index) };
+}
+/** Rename a tab by index. */
+export function renameTab(cfg, index, label) {
+    return { ...cfg, tabs: cfg.tabs.map((t, i) => (i === index ? { ...t, label } : t)) };
+}
+/** Add a child block (default config for `kind`) to a tab. Only `TAB_CHILD_KINDS` are allowed. */
+export function addTabBlock(cfg, index, kind, entity) {
+    if (!TAB_CHILD_KINDS.includes(kind))
+        return cfg;
+    const taken = new Set();
+    cfg.tabs.forEach((t) => flattenBlocks(t.blocks).forEach((b) => taken.add(b.id)));
+    const block = { id: uid(`${kind}-`, taken), span: DEFAULT_SPAN[kind], config: defaultBlockConfig(kind, entity) };
+    return { ...cfg, tabs: cfg.tabs.map((t, i) => (i === index ? { ...t, blocks: [...t.blocks, block] } : t)) };
+}
+/** Remove a child block from a tab by id. */
+export function removeTabBlock(cfg, index, blockId) {
+    return { ...cfg, tabs: cfg.tabs.map((t, i) => (i === index ? { ...t, blocks: t.blocks.filter((b) => b.id !== blockId) } : t)) };
+}
+/** Build a UI-kit component child block for a container section (Tabs / Accordion),
+ *  seeded with the registry's default props + content. Returns null for an unknown
+ *  component key. Entity-agnostic - components need no entity. */
+function makeComponentChild(componentKey, taken) {
+    const spec = uiComponentSpec(componentKey);
+    if (!spec)
+        return null;
+    const props = {};
+    for (const p of spec.props)
+        if (p.default != null)
+            props[p.key] = p.default;
+    if (spec.hasContent)
+        props._content = spec.contentDefault ?? spec.label;
+    const set = new Set(taken);
+    return { id: uid('component-', set), span: DEFAULT_SPAN.component, config: { kind: 'component', component: componentKey, props } };
+}
+/** Add a specific UI-kit component (by registry key) to a tab. */
+export function addTabComponent(cfg, index, componentKey) {
+    const taken = new Set();
+    cfg.tabs.forEach((t) => flattenBlocks(t.blocks).forEach((b) => taken.add(b.id)));
+    const block = makeComponentChild(componentKey, taken);
+    if (!block)
+        return cfg;
+    return { ...cfg, tabs: cfg.tabs.map((t, i) => (i === index ? { ...t, blocks: [...t.blocks, block] } : t)) };
+}
+// --- Accordion container (mirrors the Tabs helpers) ------------------------
+/** Append a section (collapsible panel) to an accordion. */
+export function addAccordionSection(cfg, label) {
+    return { ...cfg, sections: [...cfg.sections, { label: label ?? `Section ${cfg.sections.length + 1}`, blocks: [] }] };
+}
+/** Remove a section by index (keeps at least one). */
+export function removeAccordionSection(cfg, index) {
+    if (cfg.sections.length <= 1)
+        return cfg;
+    return { ...cfg, sections: cfg.sections.filter((_, i) => i !== index) };
+}
+/** Rename a section by index. */
+export function renameAccordionSection(cfg, index, label) {
+    return { ...cfg, sections: cfg.sections.map((s, i) => (i === index ? { ...s, label } : s)) };
+}
+/** Toggle single- vs multiple-open behaviour. */
+export function setAccordionMultiple(cfg, multiple) {
+    return { ...cfg, multiple };
+}
+/** Add a display-block child (default config for `kind`) to a section. Only CONTAINER_CHILD_KINDS. */
+export function addAccordionBlock(cfg, index, kind, entity) {
+    if (!CONTAINER_CHILD_KINDS.includes(kind))
+        return cfg;
+    const taken = new Set();
+    cfg.sections.forEach((s) => flattenBlocks(s.blocks).forEach((b) => taken.add(b.id)));
+    const block = { id: uid(`${kind}-`, taken), span: DEFAULT_SPAN[kind], config: defaultBlockConfig(kind, entity) };
+    return { ...cfg, sections: cfg.sections.map((s, i) => (i === index ? { ...s, blocks: [...s.blocks, block] } : s)) };
+}
+/** Add a specific UI-kit component (by registry key) to a section. */
+export function addAccordionComponent(cfg, index, componentKey) {
+    const taken = new Set();
+    cfg.sections.forEach((s) => flattenBlocks(s.blocks).forEach((b) => taken.add(b.id)));
+    const block = makeComponentChild(componentKey, taken);
+    if (!block)
+        return cfg;
+    return { ...cfg, sections: cfg.sections.map((s, i) => (i === index ? { ...s, blocks: [...s.blocks, block] } : s)) };
+}
+/** Remove a child block from a section by id. */
+export function removeAccordionBlock(cfg, index, blockId) {
+    return { ...cfg, sections: cfg.sections.map((s, i) => (i === index ? { ...s, blocks: s.blocks.filter((b) => b.id !== blockId) } : s)) };
+}
+/** A default screen for an entity: a grid (editing via a popup form by default). */
+export function defaultScreenFor(entity) {
+    const grid = makeBlock('grid', entity, new Set());
+    return { id: entity.name, entity: entity.name, title: entity.label ?? entity.name, route: entity.name, blocks: [grid] };
+}
+/** A new project from a set of entities: one default screen each, in-memory. */
+export function createProject(entities, opts = {}) {
+    return {
+        title: opts.title ?? 'My Studio App',
+        entities: [...entities],
+        screens: entities.map(defaultScreenFor),
+        dataSource: opts.dataSource ?? 'memory',
+    };
+}
+// --- immutable ops ---------------------------------------------------------
+function mapScreen(project, screenId, fn) {
+    return { ...project, screens: project.screens.map((s) => (s.id === screenId ? fn(s) : s)) };
+}
+export function addBlock(project, screenId, kind) {
+    return mapScreen(project, screenId, (s) => {
+        const entity = entityOf(project, s.entity);
+        if (!entity)
+            return s;
+        const taken = new Set(s.blocks.map((b) => b.id));
+        return { ...s, blocks: [...s.blocks, makeBlock(kind, entity, taken)] };
+    });
+}
+/** Insert a new block at `index` (drag-drop from the palette). Clamps to range. */
+export function addBlockAt(project, screenId, kind, index) {
+    return mapScreen(project, screenId, (s) => {
+        const entity = entityOf(project, s.entity);
+        if (!entity)
+            return s;
+        const taken = new Set(s.blocks.map((b) => b.id));
+        const block = makeBlock(kind, entity, taken);
+        const blocks = [...s.blocks];
+        blocks.splice(Math.max(0, Math.min(index, blocks.length)), 0, block);
+        return { ...s, blocks };
+    });
+}
+/** Add a UI-kit component block (see `ui-components.ts`'s `UI_COMPONENT_REGISTRY`)
+ *  to a screen. Unlike `addBlock`/`addBlockAt`, this needs no entity - it works on
+ *  any screen, including a freestanding one, or mixed onto an entity-bound one. */
+export function addComponentBlock(project, screenId, componentKey, defaultProps = {}, index) {
+    return mapScreen(project, screenId, (s) => {
+        const taken = new Set(flattenBlocks(s.blocks).map((b) => b.id));
+        const name = uniqueComponentName(componentKey, s);
+        const block = { id: uid('component-', taken), span: DEFAULT_SPAN.component, config: { kind: 'component', component: componentKey, props: { ...defaultProps }, name } };
+        const blocks = [...s.blocks];
+        blocks.splice(index != null ? Math.max(0, Math.min(index, blocks.length)) : blocks.length, 0, block);
+        return { ...s, blocks };
+    });
+}
+/** A valid, unique JS identifier for a component handle on a screen, e.g. `button1`.
+ *  Handles are the named objects code reaches (btn.setLabel(...), btn.onclick = ...). */
+export function componentHandleName(cfg) {
+    const raw = (cfg.name ?? cfg.component).trim();
+    const id = raw.replace(/[^A-Za-z0-9_$]/g, '_').replace(/^([0-9])/, '_$1');
+    return id || 'el';
+}
+function uniqueComponentName(componentKey, screen) {
+    const taken = new Set(flattenBlocks(screen.blocks)
+        .filter((b) => b.config.kind === 'component')
+        .map((b) => componentHandleName(b.config)));
+    let n = 1;
+    while (taken.has(`${componentKey}${n}`))
+        n++;
+    return `${componentKey}${n}`;
+}
+/** Rename a component's handle (the variable code uses to reach it). */
+export function setComponentName(project, screenId, blockId, name) {
+    return mapScreen(project, screenId, (s) => ({
+        ...s,
+        blocks: mapBlockTree(s.blocks, blockId, (b) => (b.config.kind === 'component' ? { ...b, config: { ...b.config, name: name.trim() || undefined } } : b)),
+    }));
+}
+/** True when a component has at least one data-bound prop. */
+export function componentHasBindings(cfg) {
+    return !!cfg.bindings && Object.keys(cfg.bindings).length > 0;
+}
+/** Bind (or, with `binding: null`, unbind) one component prop to the screen's data. */
+export function setComponentBinding(project, screenId, blockId, propKey, binding) {
+    return mapScreen(project, screenId, (s) => ({
+        ...s,
+        blocks: mapBlockTree(s.blocks, blockId, (b) => {
+            if (b.config.kind !== 'component')
+                return b;
+            const bindings = { ...(b.config.bindings ?? {}) };
+            if (binding)
+                bindings[propKey] = binding;
+            else
+                delete bindings[propKey];
+            return { ...b, config: { ...b.config, bindings: Object.keys(bindings).length ? bindings : undefined } };
+        }),
+    }));
+}
+/** Apply `fn` to the block with `id` anywhere in the tree (top level or nested in a Tabs / Accordion container). */
+function mapBlockTree(blocks, id, fn) {
+    return blocks.map((b) => {
+        if (b.id === id)
+            return fn(b);
+        if (b.config.kind === 'tabs') {
+            return { ...b, config: { ...b.config, tabs: b.config.tabs.map((t) => ({ ...t, blocks: mapBlockTree(t.blocks, id, fn) })) } };
+        }
+        if (b.config.kind === 'accordion') {
+            return { ...b, config: { ...b.config, sections: b.config.sections.map((s) => ({ ...s, blocks: mapBlockTree(s.blocks, id, fn) })) } };
+        }
+        return b;
+    });
+}
+/** Remove the block with `id` anywhere in the tree (top level or nested in a Tabs / Accordion container). */
+function removeBlockTree(blocks, id) {
+    return blocks
+        .filter((b) => b.id !== id)
+        .map((b) => b.config.kind === 'tabs' ? { ...b, config: { ...b.config, tabs: b.config.tabs.map((t) => ({ ...t, blocks: removeBlockTree(t.blocks, id) })) } }
+        : b.config.kind === 'accordion' ? { ...b, config: { ...b.config, sections: b.config.sections.map((s) => ({ ...s, blocks: removeBlockTree(s.blocks, id) })) } }
+            : b);
+}
+export function removeBlock(project, screenId, blockId) {
+    return mapScreen(project, screenId, (s) => ({ ...s, blocks: removeBlockTree(s.blocks, blockId) }));
+}
+/** Clone a block (config + width/height) with a fresh id, inserted right after it. */
+export function duplicateBlock(project, screenId, blockId) {
+    return mapScreen(project, screenId, (s) => {
+        const idx = s.blocks.findIndex((b) => b.id === blockId);
+        if (idx < 0)
+            return s;
+        const src = s.blocks[idx];
+        // JSON clone (not structuredClone): the config is always JSON-safe, and this
+        // also unwraps any Svelte reactive $state proxy, which structuredClone rejects.
+        const clone = { ...src, id: uid(`${src.config.kind}-`, new Set(s.blocks.map((b) => b.id))), config: JSON.parse(JSON.stringify(src.config)) };
+        return { ...s, blocks: [...s.blocks.slice(0, idx + 1), clone, ...s.blocks.slice(idx + 1)] };
+    });
+}
+/** Move a block one slot up (`-1`) or down (`+1`). No-op at the ends. */
+export function moveBlock(project, screenId, blockId, dir) {
+    return mapScreen(project, screenId, (s) => {
+        const i = s.blocks.findIndex((b) => b.id === blockId);
+        const j = i + dir;
+        if (i < 0 || j < 0 || j >= s.blocks.length)
+            return s;
+        const blocks = [...s.blocks];
+        [blocks[i], blocks[j]] = [blocks[j], blocks[i]];
+        return { ...s, blocks };
+    });
+}
+/** Reorder a block to an explicit index (drag-drop). Clamps to range. */
+export function reorderBlock(project, screenId, blockId, toIndex) {
+    return mapScreen(project, screenId, (s) => {
+        const from = s.blocks.findIndex((b) => b.id === blockId);
+        if (from < 0)
+            return s;
+        const blocks = [...s.blocks];
+        const [moved] = blocks.splice(from, 1);
+        blocks.splice(Math.max(0, Math.min(toIndex, blocks.length)), 0, moved);
+        return { ...s, blocks };
+    });
+}
+/** Patch a block's config (merged), span/height, and/or appearance `style` (merged;
+ *  keys set to undefined are cleared). */
+export function updateBlock(project, screenId, blockId, patch) {
+    return mapScreen(project, screenId, (s) => ({
+        ...s,
+        blocks: mapBlockTree(s.blocks, blockId, (b) => ({
+            ...b,
+            span: patch.span ?? b.span,
+            colSpan: patch.colSpan ?? b.colSpan,
+            height: patch.height ?? b.height,
+            style: patch.style ? mergeBlockStyle(b.style, patch.style) : b.style,
+            className: patch.className !== undefined ? (patch.className.trim() || undefined) : b.className,
+            config: patch.config ? { ...b.config, ...patch.config } : b.config,
+        })),
+    }));
+}
+/** Replace an entity's schema (e.g. after field edits), keeping its screens. */
+export function updateEntity(project, name, schema) {
+    const entities = project.entities.map((e) => (e.name === name ? schema : e));
+    if (name === schema.name)
+        return { ...project, entities };
+    // Renamed: retarget its screens AND any master-detail block pointing at it.
+    const screens = project.screens.map((s) => {
+        const blocks = s.blocks.map((b) => b.config.kind === 'master-detail' && b.config.childEntity === name
+            ? { ...b, config: { ...b.config, childEntity: schema.name } }
+            : b);
+        return { ...s, entity: s.entity === name ? schema.name : s.entity, blocks };
+    });
+    return { ...project, entities, screens };
+}
+/** Add an entity + its default screen. */
+export function addEntity(project, schema) {
+    if (entityOf(project, schema.name))
+        return project;
+    return { ...project, entities: [...project.entities, schema], screens: [...project.screens, defaultScreenFor(schema)] };
+}
+/** Remove an entity and every screen bound to it. */
+export function removeEntity(project, name) {
+    return {
+        ...project,
+        entities: project.entities.filter((e) => e.name !== name),
+        screens: project.screens.filter((s) => s.entity !== name),
+    };
+}
+/** Append a screen, making its id AND route unique against the existing set. */
+function appendScreen(project, base, keyBase) {
+    const ids = new Set(project.screens.map((s) => s.id));
+    const routes = new Set(project.screens.map((s) => s.route));
+    const id = ids.has(base.id) ? uid(`${keyBase}-`, ids) : base.id;
+    const route = routes.has(base.route) ? uid(`${base.route}-`, routes) : base.route;
+    return { ...project, screens: [...project.screens, { ...base, id, route }] };
+}
+export function addScreen(project, entity) {
+    const schema = entityOf(project, entity);
+    if (!schema)
+        return project;
+    return appendScreen(project, defaultScreenFor(schema), entity);
+}
+export function removeScreen(project, screenId) {
+    return { ...project, screens: project.screens.filter((s) => s.id !== screenId) };
+}
+export function updateScreen(project, screenId, 
+// `renderMode` is patchable here so SSR output is reachable without the
+// designer - the CLI and the MCP tools drive the model through this function.
+patch) {
+    return mapScreen(project, screenId, (s) => ({ ...s, ...patch }));
+}
+// ---- Screen layout: 12-column grid (default) or a docking workspace ----------
+/** The screen's layout engine. Defaults to `'grid'` (the 12-column responsive grid). */
+export function screenLayoutOf(screen) {
+    return screen.layout ?? 'grid';
+}
+/** A short title for a block's dock pane. */
+function dockPaneTitle(block) {
+    const c = block.config;
+    const byKind = {
+        grid: 'Grid', form: 'Form', chart: 'Chart', dashboard: 'Dashboard', tree: 'Tree', pivot: 'Pivot',
+        filter: 'Filters', record: 'Record', detail: 'Detail', board: 'Board', calendar: 'Calendar',
+        'master-detail': 'Master / detail', lookup: 'Lookup', tabs: 'Tabs', accordion: 'Accordion',
+        kpi: 'KPI', gauge: 'Gauge', component: 'Component',
+    };
+    return c.label || c.title || c.name || c.component || byKind[c.kind] || 'Panel';
+}
+/** Every pane id present anywhere in a dock workspace (main tree + floating + auto-hidden). */
+export function dockPaneIds(state) {
+    const ids = new Set();
+    const walk = (n) => { if (n.type === 'tabs')
+        for (const p of n.panes)
+            ids.add(p.id);
+    else
+        for (const c of n.children)
+            walk(c); };
+    if (state.main)
+        walk(state.main);
+    for (const w of state.floating)
+        for (const p of w.leaf.panes)
+            ids.add(p.id);
+    for (const e of state.autoHide)
+        for (const p of e.leaf.panes)
+            ids.add(p.id);
+    return ids;
+}
+/**
+ * Smart auto-layout: seed a docking workspace from a screen's blocks by role -
+ * filters dock left, record / detail panels dock right, KPIs / gauges strip across
+ * the top, and the main content (grid / board / calendar / chart / ...) fills the
+ * centre. Pane ids equal block ids. Runtime float / pin / pop-out is layered on later.
+ */
+export function buildDockLayout(screen) {
+    const taken = new Set(screen.blocks.map((b) => b.id));
+    const genId = (p) => { const id = uid(p, taken); taken.add(id); return id; };
+    const paneFor = (b) => ({ id: b.id, title: dockPaneTitle(b), closable: true });
+    const roleOf = (b) => {
+        switch (b.config.kind) {
+            case 'filter': return 'left';
+            case 'record':
+            case 'detail': return 'right';
+            case 'kpi':
+            case 'gauge': return 'top';
+            default: return 'center';
+        }
+    };
+    const groupOf = (direction, children, sizes) => ({ type: 'group', id: genId('dg-'), direction, children, sizes });
+    const norm = (ws) => { const s = ws.reduce((a, b) => a + b, 0) || 1; return ws.map((w) => w / s); };
+    // Each block gets its OWN leaf, so split view can size every block independently
+    // (grouping them into one tabs leaf would trap them as tabs - unresizable when
+    // the manager is locked). Multiple blocks in a bucket stack along the given axis.
+    const oneLeaf = (b) => ({ type: 'tabs', id: genId('dt-'), panes: [paneFor(b)], active: 0 });
+    const stackOf = (bs, direction) => bs.length === 1 ? oneLeaf(bs[0]) : groupOf(direction, bs.map(oneLeaf), norm(bs.map(() => 1)));
+    // A forced split orientation (split-view setting) ignores roles and lays ALL
+    // blocks out as equal panes in one row / column.
+    const forced = splitOpts(screen).orientation;
+    if (forced !== 'auto' && screen.blocks.length) {
+        return { main: stackOf(screen.blocks, forced), floating: [], autoHide: [] };
+    }
+    const buckets = { left: [], center: [], right: [], top: [] };
+    for (const b of screen.blocks)
+        buckets[roleOf(b)].push(b);
+    const rowChildren = [];
+    const rowWeights = [];
+    if (buckets.left.length) {
+        rowChildren.push(stackOf(buckets.left, 'column'));
+        rowWeights.push(1);
+    }
+    if (buckets.center.length) {
+        rowChildren.push(stackOf(buckets.center, 'column'));
+        rowWeights.push(3);
+    }
+    if (buckets.right.length) {
+        rowChildren.push(stackOf(buckets.right, 'column'));
+        rowWeights.push(1);
+    }
+    const row = rowChildren.length === 0 ? null : rowChildren.length === 1 ? rowChildren[0] : groupOf('row', rowChildren, norm(rowWeights));
+    let main;
+    if (buckets.top.length && row)
+        main = groupOf('column', [stackOf(buckets.top, 'row'), row], [0.28, 0.72]);
+    else if (buckets.top.length)
+        main = stackOf(buckets.top, 'row');
+    else if (row)
+        main = row;
+    else
+        main = { type: 'tabs', id: genId('dt-'), panes: [], active: 0 };
+    return { main, floating: [], autoHide: [] };
+}
+/** Every group / tabs node id in a workspace (to keep freshly generated ids unique). */
+function collectDockNodeIds(state) {
+    const ids = [];
+    const walk = (n) => { ids.push(n.id); if (n.type === 'group')
+        for (const c of n.children)
+            walk(c); };
+    if (state.main)
+        walk(state.main);
+    for (const w of state.floating) {
+        ids.push(w.id);
+        walk(w.leaf);
+    }
+    for (const e of state.autoHide) {
+        ids.push(e.id);
+        walk(e.leaf);
+    }
+    return ids;
+}
+/** Append a pane to the main area's first tabs leaf (creating one if the area is empty). */
+function addDockPaneToMain(state, p, genId) {
+    const main = state.main;
+    if (!main)
+        return { ...state, main: { type: 'tabs', id: genId(), panes: [p], active: 0 } };
+    let added = false;
+    const add = (n) => {
+        if (added)
+            return n;
+        if (n.type === 'tabs') {
+            added = true;
+            return { ...n, panes: [...n.panes, p], active: n.panes.length };
+        }
+        return { ...n, children: n.children.map(add) };
+    };
+    const nextMain = add(main);
+    if (added)
+        return { ...state, main: nextMain };
+    // No tabs leaf anywhere: put main + a new tabs side by side.
+    return { ...state, main: { type: 'group', id: genId(), direction: 'row', children: [main, { type: 'tabs', id: genId(), panes: [p], active: 0 }], sizes: [0.7, 0.3] } };
+}
+/** Remove a pane anywhere in a workspace; collapse emptied tabs + single-child groups. */
+function stripDockPane(state, paneId) {
+    const strip = (n) => {
+        if (n.type === 'tabs') {
+            const panes = n.panes.filter((p) => p.id !== paneId);
+            return panes.length ? { ...n, panes, active: Math.min(n.active, panes.length - 1) } : null;
+        }
+        const children = n.children.map(strip).filter((c) => c !== null);
+        if (children.length === 0)
+            return null;
+        if (children.length === 1)
+            return children[0];
+        return { ...n, children, sizes: children.map(() => 1 / children.length) };
+    };
+    const main = state.main ? strip(state.main) : null;
+    const floating = state.floating.map((w) => ({ ...w, leaf: { ...w.leaf, panes: w.leaf.panes.filter((p) => p.id !== paneId) } })).filter((w) => w.leaf.panes.length > 0);
+    const autoHide = state.autoHide.map((e) => ({ ...e, leaf: { ...e.leaf, panes: e.leaf.panes.filter((p) => p.id !== paneId) } })).filter((e) => e.leaf.panes.length > 0);
+    return { ...state, main, floating, autoHide };
+}
+/** Incrementally reconcile a dock workspace to the screen's blocks - add a pane for each new
+ *  block, strip panes for removed blocks - WITHOUT rebuilding, so the user's arrangement
+ *  (splits / floats / pins) is preserved. Seeds a fresh workspace if none exists. */
+export function syncDockPanes(screen) {
+    if (!isPaneLayout(screenLayoutOf(screen)))
+        return screen;
+    if (!screen.dock)
+        return { ...screen, dock: buildDockLayout(screen) };
+    const blockIds = new Set(screen.blocks.map((b) => b.id));
+    const present = dockPaneIds(screen.dock);
+    const missing = screen.blocks.filter((b) => !present.has(b.id));
+    const extra = [...present].filter((id) => !blockIds.has(id));
+    if (missing.length === 0 && extra.length === 0)
+        return screen;
+    let dock = screen.dock;
+    for (const id of extra)
+        dock = stripDockPane(dock, id);
+    const taken = new Set([...blockIds, ...collectDockNodeIds(dock)]);
+    const genId = () => { const id = uid('dt-', taken); taken.add(id); return id; };
+    for (const b of missing)
+        dock = addDockPaneToMain(dock, { id: b.id, title: dockPaneTitle(b), closable: true }, genId);
+    return { ...screen, dock };
+}
+/** Rebuild the dock workspace if its panes no longer match the screen's blocks (a safety
+ *  net after block add / delete while the visual editor hasn't reconciled incrementally). */
+export function reconcileDock(screen) {
+    if (!isPaneLayout(screenLayoutOf(screen)))
+        return screen;
+    const blockIds = new Set(screen.blocks.map((b) => b.id));
+    const paneIds = screen.dock ? dockPaneIds(screen.dock) : new Set();
+    const same = !!screen.dock && blockIds.size === paneIds.size && [...blockIds].every((id) => paneIds.has(id));
+    return same ? screen : { ...screen, dock: buildDockLayout(screen) };
+}
+/** Switch a screen between the 12-column grid and a docking workspace. Switching to
+ *  `'dock'` seeds a workspace (smart auto-layout) if none exists yet. */
+export function setScreenLayout(project, screenId, layout) {
+    // Both pane layouts (split / dock) back onto a DockManagerState; canvas seeds
+    // explicit cell coordinates. Switching split<->dock preserves the existing
+    // arrangement, but coming FROM a non-pane layout (grid / stack / canvas) seeds a
+    // fresh one - so a stale arrangement never carries over into a new workspace.
+    return mapScreen(project, screenId, (s) => {
+        if (isPaneLayout(layout)) {
+            const dock = isPaneLayout(screenLayoutOf(s)) && s.dock ? s.dock : buildDockLayout(s);
+            return { ...s, layout, dock };
+        }
+        if (layout === 'canvas')
+            return { ...s, layout, canvas: s.canvas ?? buildCanvasLayout(s) };
+        return { ...s, layout };
+    });
+}
+// --- free-form canvas geometry ----------------------------------------------
+const clampInt = (n, lo, hi) => Math.max(lo, Math.min(hi, Math.round(n)));
+/** A sensible default row height (in canvas rows) for a block kind - tall for
+ *  data views, short for a single stat. */
+function defaultCanvasRows(block) {
+    const kind = block.config.kind;
+    if (kind === 'kpi' || kind === 'gauge')
+        return 3;
+    if (kind === 'filter')
+        return 4;
+    if (kind === 'chart' || kind === 'record' || kind === 'detail')
+        return 6;
+    return 8; // grid / board / pivot / tree / dashboard / master-detail / form / etc.
+}
+/** Seed canvas rects for every block: flow them two-up (half-width each) down the
+ *  page, so switching to canvas gives a reasonable starting arrangement. */
+export function buildCanvasLayout(screen) {
+    const cols = canvasOpts(screen).cols;
+    const out = {};
+    let row = 0;
+    let col = 0;
+    let rowMax = 0;
+    for (const b of screen.blocks) {
+        const colSpan = Math.max(1, Math.round(cols / 2));
+        const rowSpan = defaultCanvasRows(b);
+        if (col + colSpan > cols) {
+            col = 0;
+            row += rowMax;
+            rowMax = 0;
+        }
+        out[b.id] = { col, row, colSpan, rowSpan };
+        col += colSpan;
+        rowMax = Math.max(rowMax, rowSpan);
+    }
+    return out;
+}
+/** The stored rect for a block, or a computed default (so a block added after the
+ *  layout was seeded still lands somewhere sane). */
+export function canvasRectOf(screen, blockId) {
+    const stored = screen.canvas?.[blockId];
+    const cols = canvasOpts(screen).cols;
+    if (stored) {
+        // Clamp a stored rect to the current column count (it may have been placed
+        // when the canvas had more columns).
+        const colSpan = Math.max(1, Math.min(stored.colSpan, cols));
+        return { ...stored, colSpan, col: Math.max(0, Math.min(stored.col, cols - colSpan)) };
+    }
+    return buildCanvasLayout(screen)[blockId] ?? { col: 0, row: 0, colSpan: Math.max(1, Math.round(cols / 2)), rowSpan: 8 };
+}
+/** Move / resize a block on the canvas. Values are clamped to the screen's column
+ *  count (col in-grid, colSpan 1..cols; row >= 0, rowSpan >= 1). */
+export function setCanvasRect(project, screenId, blockId, rect) {
+    return mapScreen(project, screenId, (s) => {
+        const cols = canvasOpts(s).cols;
+        const cur = canvasRectOf(s, blockId);
+        const colSpan = clampInt(rect.colSpan ?? cur.colSpan, 1, cols);
+        const col = clampInt(rect.col ?? cur.col, 0, cols - colSpan);
+        const rowSpan = Math.max(1, clampInt(rect.rowSpan ?? cur.rowSpan, 1, 999));
+        const row = Math.max(0, clampInt(rect.row ?? cur.row, 0, 999));
+        return { ...s, canvas: { ...s.canvas, [blockId]: { col, row, colSpan, rowSpan } } };
+    });
+}
+const GRID_PRESET_LABELS = {
+    full: 'Full width',
+    'two-col': 'Two columns',
+    'three-col': 'Three columns',
+    sidebar: 'Sidebar + main',
+    'kpi-row': 'KPI row + full',
+};
+export function gridPresetLabel(preset) { return GRID_PRESET_LABELS[preset]; }
+export const GRID_PRESETS = ['full', 'two-col', 'three-col', 'sidebar', 'kpi-row'];
+/** Small, wide KPI-like blocks that a "KPI row" preset lays out as a strip. */
+const KPI_ROW_KINDS = ['kpi', 'gauge'];
+/** Apply a grid preset: rewrite the top-level blocks' `colSpan` to the pattern.
+ *  Only touches the current screen's own blocks (nested container children keep
+ *  their spans). A no-op for a screen with no blocks. */
+export function applyGridPreset(project, screenId, preset) {
+    return mapScreen(project, screenId, (s) => {
+        if (s.blocks.length === 0)
+            return s;
+        const span = (i, b) => {
+            switch (preset) {
+                case 'full': return 12;
+                case 'two-col': return 6;
+                case 'three-col': return 4;
+                // Narrow first block (filters / nav) beside a wide content column.
+                case 'sidebar': return i === 0 ? 4 : 8;
+                // KPI-ish blocks form a 4-across strip; everything else spans full.
+                case 'kpi-row': return KPI_ROW_KINDS.includes(b.config.kind) ? 3 : 12;
+            }
+        };
+        return { ...s, blocks: s.blocks.map((b, i) => ({ ...b, colSpan: span(i, b) })) };
+    });
+}
+/** Persist a new dock workspace (user rearranged panes in the designer). */
+export function setScreenDock(project, screenId, dock) {
+    return mapScreen(project, screenId, (s) => ({ ...s, dock }));
+}
+// --- screen state variables --------------------------------------------------
+/** Add a state variable (unique name; `state_N` if the name is taken / empty). */
+export function addStateVar(project, screenId, v = {}) {
+    return mapScreen(project, screenId, (s) => {
+        const taken = new Set((s.state ?? []).map((x) => x.name));
+        let name = identSafe(v.name || 'value');
+        if (taken.has(name)) {
+            let i = 2;
+            while (taken.has(`${name}${i}`))
+                i++;
+            name = `${name}${i}`;
+        }
+        const next = { name, type: v.type ?? 'string', initial: v.initial };
+        return { ...s, state: [...(s.state ?? []), next] };
+    });
+}
+/** Patch a state variable by (old) name. Renames keep the identifier valid + unique. */
+export function updateStateVar(project, screenId, name, patch) {
+    return mapScreen(project, screenId, (s) => {
+        const cur = s.state ?? [];
+        const taken = new Set(cur.filter((x) => x.name !== name).map((x) => x.name));
+        return {
+            ...s,
+            state: cur.map((x) => {
+                if (x.name !== name)
+                    return x;
+                let nm = patch.name !== undefined ? identSafe(patch.name) : x.name;
+                if (nm !== x.name && taken.has(nm)) {
+                    let i = 2;
+                    while (taken.has(`${nm}${i}`))
+                        i++;
+                    nm = `${nm}${i}`;
+                }
+                return { ...x, ...patch, name: nm };
+            }),
+        };
+    });
+}
+/** Remove a state variable by name. */
+export function removeStateVar(project, screenId, name) {
+    return mapScreen(project, screenId, (s) => ({ ...s, state: (s.state ?? []).filter((x) => x.name !== name) }));
+}
+/** Rebuild the pane arrangement from scratch (smart auto-layout, honoring the
+ *  current split orientation). Used when a setting invalidates the layout - e.g.
+ *  the user flips split orientation - or as a "reset arrangement" action. */
+export function reseedScreenDock(project, screenId) {
+    return mapScreen(project, screenId, (s) => ({ ...s, dock: buildDockLayout(s) }));
+}
+/** The current title (tab text) of a block's dock pane, if the screen is docked. */
+export function dockPaneTitleOf(screen, paneId) {
+    if (!screen.dock)
+        return undefined;
+    let found;
+    const walk = (n) => { if (n.type === 'tabs') {
+        const p = n.panes.find((x) => x.id === paneId);
+        if (p)
+            found = p.title;
+    }
+    else
+        for (const c of n.children)
+            walk(c); };
+    if (screen.dock.main)
+        walk(screen.dock.main);
+    for (const w of screen.dock.floating) {
+        const p = w.leaf.panes.find((x) => x.id === paneId);
+        if (p)
+            found = p.title;
+    }
+    for (const e of screen.dock.autoHide) {
+        const p = e.leaf.panes.find((x) => x.id === paneId);
+        if (p)
+            found = p.title;
+    }
+    return found;
+}
+/** Rename a block's dock pane (the tab text) anywhere in the workspace. */
+export function setDockPaneTitle(project, screenId, paneId, title) {
+    return mapScreen(project, screenId, (s) => {
+        if (!s.dock)
+            return s;
+        const relabelPanes = (panes) => panes.map((p) => (p.id === paneId ? { ...p, title } : p));
+        const relabel = (n) => (n.type === 'tabs' ? { ...n, panes: relabelPanes(n.panes) } : { ...n, children: n.children.map(relabel) });
+        const main = s.dock.main ? relabel(s.dock.main) : null;
+        const floating = s.dock.floating.map((w) => ({ ...w, leaf: { ...w.leaf, panes: relabelPanes(w.leaf.panes) } }));
+        const autoHide = s.dock.autoHide.map((e) => ({ ...e, leaf: { ...e.leaf, panes: relabelPanes(e.leaf.panes) } }));
+        return { ...s, dock: { ...s.dock, main, floating, autoHide } };
+    });
+}
+/** A freestanding screen: no bound entity, so no blocks/data binding - just a
+ *  title and (once actions are added) a toolbar. For a blank page the developer
+ *  builds on, or one that's purely a home for custom actions ("Run report"). */
+export function addFreestandingScreen(project, opts) {
+    const id = 'screen';
+    const route = opts.route ?? id;
+    return appendScreen(project, { id, title: opts.title, route, blocks: [] }, 'screen');
+}
+/** Every custom action id already used project-wide (screen toolbars + row
+ *  actions) - action ids become `/api/actions/<id>` routes, so they must be
+ *  unique across the whole project, not just within one screen. */
+function takenActionIds(project) {
+    const taken = new Set();
+    for (const s of project.screens) {
+        for (const a of s.actions ?? [])
+            taken.add(a.id);
+        for (const b of flattenBlocks(s.blocks)) {
+            if (b.config.kind !== 'grid')
+                continue;
+            for (const a of b.config.rowActions ?? [])
+                if (a.kind === 'custom' && a.id)
+                    taken.add(a.id);
+        }
+    }
+    return taken;
+}
+/** Add a toolbar-level custom action to a screen (works on a freestanding screen
+ *  too). Generates a stable id from `taken` project-wide ids; the generated app
+ *  gets a wired-up button + a stub `/api/actions/<id>` route to fill in. */
+export function addScreenAction(project, screenId, action) {
+    const id = uid('action-', takenActionIds(project));
+    return mapScreen(project, screenId, (s) => ({ ...s, actions: [...(s.actions ?? []), { id, ...action }] }));
+}
+export function removeScreenAction(project, screenId, actionId) {
+    return mapScreen(project, screenId, (s) => ({ ...s, actions: (s.actions ?? []).filter((a) => a.id !== actionId) }));
+}
+/** Opt a screen into a user-owned `handlers.ts` companion (design + your own code).
+ *  The generator scaffolds the stub once and never rewrites it. */
+export function enableScreenCode(project, screenId) {
+    return mapScreen(project, screenId, (s) => ({ ...s, code: true }));
+}
+/** Drop the code companion binding (leaves any file the user already wrote on disk;
+ *  the generator simply stops emitting/importing it). */
+export function disableScreenCode(project, screenId) {
+    return mapScreen(project, screenId, (s) => ({ ...s, code: false, renderGrid: undefined }));
+}
+/** Toggle whether the page renders a Grid fed by `ctx.setRows` from `onLoad`.
+ *  Implies `code: true` (a Grid needs the handler to fill it). */
+export function setScreenRenderGrid(project, screenId, on) {
+    return mapScreen(project, screenId, (s) => ({ ...s, code: on ? true : s.code, renderGrid: on || undefined }));
+}
+/** Set the body of one event handler (e.g. `load`) - the code inside the generated
+ *  function. This is what the designer's Code view edits per slot (the "single
+ *  onLoad block"). Empty clears it back to the stub default. Implies `code: true`. */
+export function setHandlerBody(project, screenId, handler, body) {
+    return mapScreen(project, screenId, (s) => {
+        const bodies = { ...(s.handlerBodies ?? {}) };
+        if (body.trim())
+            bodies[handler] = body;
+        else
+            delete bodies[handler];
+        return { ...s, code: true, handlerBodies: Object.keys(bodies).length ? bodies : undefined };
+    });
+}
+/** Set the full source the designer writes into the screen's `handlers.ts` companion.
+ *  An advanced escape hatch that overrides the structured per-event bodies: when
+ *  present it is emitted verbatim. Empty string clears it. Implies `code: true`. */
+export function setScreenHandlersSource(project, screenId, source) {
+    const trimmed = source.trim();
+    return mapScreen(project, screenId, (s) => ({ ...s, code: true, handlersSource: trimmed || undefined }));
+}
+// --- visual methods (the Methods panel) ------------------------------------
+/** Replace the steps of one method slot (`onLoad`, `onDestroy`, or `click:<blockId>`).
+ *  An empty list clears the slot. Implies `code: true`. */
+export function setHandlerSteps(project, screenId, slot, steps) {
+    return mapScreen(project, screenId, (s) => {
+        const all = { ...(s.handlerSteps ?? {}) };
+        if (steps.length)
+            all[slot] = steps;
+        else
+            delete all[slot];
+        return { ...s, code: true, handlerSteps: Object.keys(all).length ? all : undefined };
+    });
+}
+/** Append a step to a method slot. */
+export function addHandlerStep(project, screenId, slot, step) {
+    const s = project.screens.find((x) => x.id === screenId);
+    return setHandlerSteps(project, screenId, slot, [...(s?.handlerSteps?.[slot] ?? []), step]);
+}
+/** Replace / remove a step at `index` (null removes it). */
+export function updateHandlerStep(project, screenId, slot, index, step) {
+    const s = project.screens.find((x) => x.id === screenId);
+    const steps = [...(s?.handlerSteps?.[slot] ?? [])];
+    if (index < 0 || index >= steps.length)
+        return project;
+    if (step === null)
+        steps.splice(index, 1);
+    else
+        steps[index] = step;
+    return setHandlerSteps(project, screenId, slot, steps);
+}
+/** Move a step within its slot (dir -1 up, +1 down). */
+export function moveHandlerStep(project, screenId, slot, index, dir) {
+    const s = project.screens.find((x) => x.id === screenId);
+    const steps = [...(s?.handlerSteps?.[slot] ?? [])];
+    const j = index + dir;
+    if (index < 0 || index >= steps.length || j < 0 || j >= steps.length)
+        return project;
+    [steps[index], steps[j]] = [steps[j], steps[index]];
+    return setHandlerSteps(project, screenId, slot, steps);
+}
+/** Drop the visual steps for a slot into the raw code editor (compile once), so a
+ *  user can hand-edit from there. Moves `handlerSteps[slot]` -> `handlerBodies[slot]`. */
+export function stepsToCode(project, screenId, slot) {
+    const s = project.screens.find((x) => x.id === screenId);
+    const steps = s?.handlerSteps?.[slot];
+    if (!steps?.length)
+        return project;
+    const withBody = setHandlerBody(project, screenId, slot, compileHandlerSteps(steps));
+    return setHandlerSteps(withBody, screenId, slot, []);
+}
+/** Deep-clone `block` with fresh ids (recursing into Tabs children). */
+function freshBlockIds(blocks, taken) {
+    return blocks.map((b) => {
+        const config = JSON.parse(JSON.stringify(b.config));
+        const id = uid(`${config.kind}-`, taken);
+        taken.add(id);
+        if (config.kind === 'tabs')
+            config.tabs = config.tabs.map((t) => ({ ...t, blocks: freshBlockIds(t.blocks, taken) }));
+        if (config.kind === 'accordion')
+            config.sections = config.sections.map((s) => ({ ...s, blocks: freshBlockIds(s.blocks, taken) }));
+        return { ...b, id, config };
+    });
+}
+/** Insert a block (deep-cloned, fresh id) into a screen - the paste target. Appends by default. */
+export function insertBlock(project, screenId, block, index) {
+    return mapScreen(project, screenId, (s) => {
+        const taken = new Set(flattenBlocks(s.blocks).map((b) => b.id));
+        const [clone] = freshBlockIds([block], taken);
+        const blocks = [...s.blocks];
+        blocks.splice(index ?? blocks.length, 0, clone);
+        return { ...s, blocks };
+    });
+}
+/** Duplicate a whole screen (fresh id / route / title + fresh block ids), inserted after it. */
+export function duplicateScreen(project, screenId) {
+    const idx = project.screens.findIndex((s) => s.id === screenId);
+    if (idx < 0)
+        return project;
+    const src = project.screens[idx];
+    const ids = new Set(project.screens.map((s) => s.id));
+    const routes = new Set(project.screens.map((s) => s.route));
+    const id = uid(`${src.entity}-`, ids);
+    const route = uid(`${src.route}-`, routes);
+    // Seed the taken-ids set with the source's block ids so the clone's ids don't collide.
+    const clone = { ...src, id, route, title: `${src.title} copy`, blocks: freshBlockIds(src.blocks, new Set(flattenBlocks(src.blocks).map((b) => b.id))) };
+    const screens = [...project.screens];
+    screens.splice(idx + 1, 0, clone);
+    return { ...project, screens };
+}
+/** Move a screen to an explicit index (drag-reorder the tab strip). Clamps to range. */
+export function reorderScreen(project, screenId, toIndex) {
+    const from = project.screens.findIndex((s) => s.id === screenId);
+    if (from < 0)
+        return project;
+    const screens = [...project.screens];
+    const [moved] = screens.splice(from, 1);
+    screens.splice(Math.max(0, Math.min(toIndex, screens.length)), 0, moved);
+    return { ...project, screens };
+}
+export function setDataSource(project, dataSource) {
+    return { ...project, dataSource };
+}
+/** Set the deploy target (SvelteKit adapter + provider config the bundle emits). */
+export function setDeployTarget(project, deploy) {
+    if (deploy === 'auto') {
+        const { deploy: _drop, ...rest } = project;
+        return rest;
+    }
+    return { ...project, deploy };
+}
+/** Enable / disable the authentication starter (login + session + hooks). */
+export function setAuth(project, patch) {
+    if (!patch.enabled) {
+        const { auth: _drop, ...rest } = project;
+        return rest;
+    }
+    const prev = project.auth;
+    const oauth = patch.oauth ?? prev?.oauth;
+    const provider = patch.provider ?? prev?.provider;
+    return {
+        ...project,
+        auth: {
+            enabled: true,
+            ...(provider && provider !== 'builtin' ? { provider } : {}),
+            protect: patch.protect ?? prev?.protect ?? true,
+            register: patch.register ?? prev?.register ?? false,
+            userAdmin: patch.userAdmin ?? prev?.userAdmin ?? false,
+            ...(oauth && oauth.length ? { oauth } : {}),
+            ...((patch.twoFactor ?? prev?.twoFactor) ? { twoFactor: true } : {}),
+            ...((patch.email ?? prev?.email) ? { email: true } : {}),
+        },
+    };
+}
+/** Enable / disable the typed Drizzle data layer (schema + repos + migrations). */
+export function setDataLayer(project, enabled) {
+    if (!enabled) {
+        const { dataLayer: _drop, ...rest } = project;
+        return rest;
+    }
+    return { ...project, dataLayer: 'drizzle' };
+}
+export function seedUsers(project) {
+    const roles = project.access?.enabled ? project.access.roles.map((r) => r.role) : [];
+    if (!roles.length)
+        return [{ email: 'admin@example.com', name: 'Admin', password: 'admin1234', role: 'admin' }];
+    return roles.map((role) => ({
+        email: `${role.replace(/[^a-z0-9]+/gi, '')}@example.com`.toLowerCase(),
+        name: role.charAt(0).toUpperCase() + role.slice(1),
+        role,
+        password: `${role.replace(/[^a-z0-9]+/gi, '').toLowerCase()}1234`,
+    }));
+}
+/** A skeleton binding for a kind, seeded with the entity's name as its table/path. */
+export function defaultEntitySource(kind, entityName) {
+    switch (kind) {
+        case 'rest': return { kind: 'rest', baseUrl: '', path: entityName, method: 'GET', params: [] };
+        case 'sql': return { kind: 'sql', table: entityName };
+        case 'supabase': return { kind: 'supabase', table: entityName };
+        case 'pglite': return { kind: 'pglite', table: entityName };
+        default: return { kind: 'memory' };
+    }
+}
+/** Bind one entity to a data source (REST / SQL / Supabase / in-memory). */
+export function setEntityDataSource(project, entityName, source) {
+    return { ...project, dataSources: { ...project.dataSources, [entityName]: source } };
+}
+/** The resolved source for an entity: its explicit per-entity binding, else a skeleton
+ *  for the project's default source kind (so the rail "Default source" actually applies
+ *  to unbound entities, and this agrees with `ssrScreenShape`'s fallback). */
+export function entityDataSource(project, entityName) {
+    return project.dataSources?.[entityName] ?? defaultEntitySource(project.dataSource ?? 'memory', entityName);
+}
+export function setTheme(project, theme) {
+    return { ...project, theme: { ...project.theme, ...theme } };
+}
+/** Apply a Studio theme preset: sets the preset id and clears any manual accent
+ *  override so the preset's own accent takes effect (the user can re-tune it
+ *  afterwards with the color picker). Pass `accent` to pin one explicitly. */
+export function setThemePreset(project, preset, accent) {
+    const theme = { ...project.theme, preset };
+    if (accent)
+        theme.accent = accent;
+    else
+        delete theme.accent;
+    return { ...project, theme };
+}
+/** Configure the generated app shell (layout style, brand, footer, nav position). */
+export function setShell(project, shell) {
+    return { ...project, theme: { ...project.theme, shell: { ...project.theme?.shell, ...shell } } };
+}
+/** Build a screen for an entity from a template (a preset arrangement of blocks). */
+export function screenFromTemplate(entity, template, opts = {}) {
+    const taken = new Set();
+    const make = (kind, span, config) => {
+        const b = makeBlock(kind, entity, taken);
+        taken.add(b.id);
+        if (span)
+            b.span = span;
+        if (config)
+            b.config = config;
+        return b;
+    };
+    const measure = pickMeasure(entity);
+    const label = entity.label ?? entity.name;
+    let blocks;
+    if (template === 'empty') {
+        blocks = [];
+    }
+    else if (template === 'dashboard') {
+        const kpis = [make('kpi', 1, { kind: 'kpi', label: `Total ${label}`, reduce: 'count' })];
+        if (measure)
+            kpis.push(make('kpi', 1, { kind: 'kpi', label: `Total ${measure}`, measure, reduce: 'sum' }));
+        blocks = [...kpis, make('chart', 2), make('grid', 3)];
+    }
+    else if (template === 'master-detail') {
+        const md = make('master-detail', 3, {
+            kind: 'master-detail',
+            childEntity: opts.child?.name ?? '',
+            foreignKey: opts.foreignKey ?? opts.child?.fields.find((f) => f.type === 'relation' && f.relation?.entity === entity.name)?.field ?? '',
+        });
+        blocks = [make('grid', 3), md];
+    }
+    else {
+        blocks = [make('grid', 3)]; // crud (the grid edits via a popup form)
+    }
+    return { id: entity.name, entity: entity.name, title: label, route: entity.name, blocks };
+}
+/** Add a screen built from a template. `child` (for master-detail) is an entity name. */
+export function addScreenFromTemplate(project, entityName, template, opts = {}) {
+    const entity = entityOf(project, entityName);
+    if (!entity)
+        return project;
+    const base = screenFromTemplate(entity, template, {
+        child: opts.child ? entityOf(project, opts.child) : undefined,
+        foreignKey: opts.foreignKey,
+    });
+    return appendScreen(project, base, entityName);
+}
+// --- persistence: round-trippable studio.config -----------------------------
+/** `name`, or the first free `${name}_${n}` if taken. Records the result. */
+function makeUnique(name, taken) {
+    if (!taken.has(name)) {
+        taken.add(name);
+        return name;
+    }
+    let i = 2;
+    while (taken.has(`${name}_${i}`))
+        i++;
+    const u = `${name}_${i}`;
+    taken.add(u);
+    return u;
+}
+/**
+ * Enforce the structural invariants the designer + codegen rely on: unique
+ * entity names, unique field names within an entity, unique screen ids + routes,
+ * and unique block ids within a screen. In-app ops already keep these, but a
+ * hand-edited / externally-produced `studio.config.json` may not - and a
+ * duplicate key would crash a keyed `{#each}` list at render time. Idempotent:
+ * a project that already satisfies the invariants is returned value-equal.
+ */
+export function sanitizeProject(project) {
+    const entityNames = new Set();
+    const entities = [];
+    for (const e of project.entities) {
+        if (entityNames.has(e.name))
+            continue; // drop a duplicate-named entity; screens still resolve to the survivor
+        entityNames.add(e.name);
+        const fieldNames = new Set();
+        entities.push({ ...e, fields: e.fields.map((f) => ({ ...f, field: makeUnique(f.field, fieldNames) })) });
+    }
+    const ids = new Set();
+    const routes = new Set();
+    const screens = project.screens.map((s) => {
+        const blockIds = new Set();
+        return {
+            ...s,
+            id: makeUnique(s.id, ids),
+            route: makeUnique(s.route, routes),
+            blocks: s.blocks.map((b) => ({ ...b, id: makeUnique(b.id, blockIds) })),
+        };
+    });
+    const result = { ...project, entities, screens };
+    // Drop per-entity source bindings for entities that no longer exist.
+    if (project.dataSources) {
+        const pruned = Object.fromEntries(Object.entries(project.dataSources).filter(([n]) => entityNames.has(n)));
+        if (Object.keys(pruned).length)
+            result.dataSources = pruned;
+        else
+            delete result.dataSources;
+    }
+    return result;
+}
+/** Serialize a project to a `studio.config.json` string (the persisted design). */
+export function serializeProject(project) {
+    return JSON.stringify(project, null, 2);
+}
+/**
+ * Parse a `studio.config.json` string back into a `StudioProject`, validating
+ * the shape. Note: only the data model round-trips - any runtime functions on an
+ * entity (`computed` / `validate` / `hooks`) are not part of the config.
+ */
+export function parseProject(json) {
+    let raw;
+    try {
+        raw = JSON.parse(json);
+    }
+    catch {
+        throw new Error('parseProject: not valid JSON');
+    }
+    if (!raw || typeof raw !== 'object')
+        throw new Error('parseProject: expected a project object');
+    const p = raw;
+    // An empty `entities` array is a valid work-in-progress (a "start from zero"
+    // project). Codegen is gated separately by validateProject / isProjectValid.
+    if (!Array.isArray(p.entities))
+        throw new Error('parseProject: missing "entities"');
+    if (!Array.isArray(p.screens))
+        throw new Error('parseProject: missing "screens"');
+    return sanitizeProject({
+        title: typeof p.title === 'string' ? p.title : 'My Studio App',
+        entities: p.entities,
+        screens: p.screens,
+        dataSource: (p.dataSource ?? 'memory'),
+        ...(p.dataSources && typeof p.dataSources === 'object' ? { dataSources: p.dataSources } : {}),
+        ...(p.supabase && typeof p.supabase === 'object' ? { supabase: p.supabase } : {}),
+        ...(p.theme && typeof p.theme === 'object' ? { theme: p.theme } : {}),
+        ...(p.access && typeof p.access === 'object' ? { access: p.access } : {}),
+        ...(p.auth && typeof p.auth === 'object' && p.auth.enabled ? { auth: p.auth } : {}),
+        ...(p.dataLayer === 'drizzle' ? { dataLayer: 'drizzle' } : {}),
+        ...(typeof p.audit === 'boolean' ? { audit: p.audit } : {}),
+        ...(p.i18n && typeof p.i18n === 'object' ? { i18n: p.i18n } : {}),
+        ...(typeof p.deploy === 'string' && p.deploy !== 'auto' ? { deploy: p.deploy } : {}),
+        ...(p.triggers && typeof p.triggers === 'object' ? { triggers: p.triggers } : {}),
+    });
+}
+/** Validate a project. Errors block codegen; warnings are advisory. */
+export function validateProject(project) {
+    const issues = [];
+    if (project.entities.length === 0)
+        issues.push({ level: 'error', message: 'Add at least one entity.' });
+    if (project.screens.length === 0)
+        issues.push({ level: 'warning', message: 'No screens yet.' });
+    // Form conditions read other fields by name. A name that resolves to nothing
+    // compares against undefined, so the field it guards would sit hidden or
+    // locked forever with no clue why - worth catching before it ships.
+    for (const entity of project.entities) {
+        const names = new Set(entity.fields.map((f) => f.field));
+        for (const field of entity.fields) {
+            if (!field.when)
+                continue;
+            for (const [flag, expr] of Object.entries(field.when)) {
+                if (!expr)
+                    continue;
+                for (const ref of collectColumnRefs(expr)) {
+                    if (!names.has(ref)) {
+                        issues.push({
+                            level: 'error',
+                            message: `"${entity.name}.${field.field}" has a ${flag} condition on "${ref}", which is not a field on ${entity.name}.`,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    const routes = new Set();
+    for (const s of project.screens) {
+        // `entity` is optional (a freestanding screen has none, by design) - only a
+        // *dangling* reference (set but unresolvable) is an error.
+        if (s.entity !== undefined && !entityOf(project, s.entity)) {
+            issues.push({ level: 'error', message: `Screen "${s.title}" points at a missing entity "${s.entity}".`, screen: s.id });
+        }
+        if (routes.has(s.route))
+            issues.push({ level: 'error', message: `Duplicate route "/${s.route}".`, screen: s.id });
+        routes.add(s.route);
+        if (s.entity !== undefined && s.blocks.length === 0) {
+            issues.push({ level: 'warning', message: `Screen "${s.title}" has no blocks.`, screen: s.id });
+        }
+        else if (s.entity === undefined && !s.actions?.length && s.blocks.length === 0) {
+            issues.push({ level: 'warning', message: `Screen "${s.title}" is empty - add an action or some content.`, screen: s.id });
+        }
+        for (const b of flattenBlocks(s.blocks)) {
+            const at = (message, level = 'warning') => ({ level, message, screen: s.id, block: b.id });
+            const c = b.config;
+            if (c.kind === 'master-detail') {
+                if (!c.childEntity || !c.foreignKey)
+                    issues.push(at('Master/detail needs a child entity + foreign key.'));
+                else if (!entityOf(project, c.childEntity))
+                    issues.push(at(`Master/detail points at a missing child entity "${c.childEntity}".`));
+            }
+            else if (c.kind === 'tree') {
+                if (!c.labelField || !c.parentField)
+                    issues.push(at('Tree needs a label field and a self-referential parent field.'));
+            }
+            else if (c.kind === 'lookup') {
+                if (!c.field)
+                    issues.push(at('Lookup needs a relation field.'));
+            }
+            else if (c.kind === 'filter') {
+                if (!c.fields.length)
+                    issues.push(at('Filter panel has no facets - pick fields to filter on.'));
+            }
+            else if (c.kind === 'chart') {
+                if (!c.dimension)
+                    issues.push(at('Chart has no group-by dimension.'));
+            }
+            else if (c.kind === 'pivot') {
+                if (!c.rows.length && !c.cols.length)
+                    issues.push(at('Pivot has no row or column dimensions.'));
+            }
+            else if (c.kind === 'tabs') {
+                if (c.tabs.every((t) => t.blocks.length === 0))
+                    issues.push(at('Tabs container has no blocks in any tab.'));
+            }
+            else if (c.kind === 'accordion') {
+                if (c.sections.every((s) => s.blocks.length === 0))
+                    issues.push(at('Accordion container has no blocks in any section.'));
+            }
+            else if (c.kind === 'component') {
+                if (!c.component)
+                    issues.push(at('Component block has no component selected.'));
+            }
+        }
+    }
+    // Project-level deployment footguns (all advisory - the app still generates).
+    const sources = Object.values(project.dataSources ?? {});
+    const sqlSources = sources.filter((s) => s.kind === 'sql');
+    if (sqlSources.length > 0 && project.dataLayer !== 'drizzle') {
+        issues.push({
+            level: 'warning',
+            message: 'SQL entities have no migrations - their tables must already exist in the database. ' +
+                'Enable the Drizzle data layer for typed migrations, or run the generated db/schema.sql against your database first.',
+        });
+    }
+    if (project.deploy === 'cloudflare' && sqlSources.some((s) => s.dialect === 'postgres' || s.dialect === 'supabase')) {
+        issues.push({
+            level: 'warning',
+            message: 'Cloudflare Workers cannot run the socket "pg" Postgres driver. Swap the generated route to an HTTP driver ' +
+                '(e.g. Neon serverless) or choose another deploy target.',
+        });
+    }
+    for (const [name, src] of Object.entries(project.dataSources ?? {})) {
+        if (src.kind === 'supabase' && !(src.url ?? project.supabase?.url) && !(src.key ?? project.supabase?.key)) {
+            issues.push({
+                level: 'warning',
+                message: `Supabase entity "${name}" has no URL/key - set the shared project connection (or this entity's own), or the generated app just reads PUBLIC_SUPABASE_URL / PUBLIC_SUPABASE_ANON_KEY from .env.`,
+            });
+        }
+    }
+    // Supabase Auth needs a Supabase client to authenticate against: either the shared
+    // project connection or at least one Supabase-bound entity (both emit connections.ts).
+    if (project.auth?.enabled && project.auth.provider === 'supabase') {
+        const hasSupabase = !!project.supabase?.url || sources.some((s) => s.kind === 'supabase');
+        if (!hasSupabase) {
+            issues.push({
+                level: 'warning',
+                message: 'Supabase Auth needs a Supabase connection. Set the shared project URL / anon key (in a data-source builder), or bind an entity to Supabase.',
+            });
+        }
+        // Supabase Auth is a client-side gate; it does not populate the server-side role
+        // the RBAC route guard reads. Server enforcement must come from RLS instead.
+        if (project.access?.enabled) {
+            issues.push({
+                level: 'warning',
+                message: 'Supabase Auth signs in on the client, so it does not populate the server-side role that RBAC route guards check. Enforce per-user access with Row Level Security policies on your Supabase tables.',
+            });
+        }
+    }
+    return issues;
+}
+export function isProjectValid(project) {
+    return !validateProject(project).some((i) => i.level === 'error');
+}