@svgrid/enterprise 2.5.2 → 2.6.0

package/dist/studio/project.d.ts

@@ -0,0 +1,1327 @@
+/**
+ * Studio project model - the declarative spine the visual designer edits and the
+ * codegen emits. A project is a multi-entity app: `entities` (the data model) +
+ * `screens` (one per entity by default), where a screen is an ordered list of
+ * data-bound `blocks` (grid, form, chart, dashboard, KPI, master-detail, lookup).
+ *
+ * Pure + node-safe (lives in the `./studio` subtree - `.js` imports, no Svelte,
+ * no `sources/`), mirroring the immutable-ops style of `schema-designer.ts`:
+ * every mutation returns a NEW project so Svelte reactivity + undo stay simple.
+ * Block-config unions are defined here (not imported from `sources/`) to keep the
+ * module resolvable under node16.
+ */
+import type { EntitySchema, FormSection } from '../schema.js';
+import type { ChartType, DockManagerState } from '@svgrid/grid';
+export type Reduce = 'sum' | 'avg' | 'count' | 'min' | 'max';
+export type DataSourceKind = 'memory' | 'sql' | 'supabase' | 'rest' | 'pglite';
+export type Presentation = 'modal' | 'drawer' | 'inline';
+export type RestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export type ParamLocation = 'path' | 'query' | 'header';
+export type ParamType = 'string' | 'number' | 'boolean';
+/** One request parameter in the REST builder (path `{id}`, query, or header). */
+export type RequestParam = {
+    name: string;
+    location: ParamLocation;
+    type: ParamType;
+    value?: string;
+};
+export type SqlDialectKind = 'postgres' | 'mysql' | 'sqlite' | 'mssql' | 'supabase' | 'turso';
+/** In-memory (seeded) source. `seed` carries curated rows (e.g. a sample app);
+ *  when absent the codegen + preview synthesize realistic rows. */
+export type MemorySource = {
+    kind: 'memory';
+    seed?: Record<string, unknown>[];
+};
+/** Wire-format preset that teaches the REST source how a backend pages / sorts /
+ *  wraps its rows, so the generated grid does REAL server-side paging + sort (not a
+ *  single fetched page). Maps to the `offsetLimit` / `dummyjson` / `jsonServer`
+ *  adapters in `@svgrid/enterprise`. Absent = the legacy manual `rowsPath`/`totalPath`
+ *  (parse only; no server paging). */
+export type RestAdapterConfig = {
+    kind: 'dummyjson';
+    rowsKey?: string;
+} | {
+    kind: 'jsonServer';
+} | {
+    kind: 'offsetLimit';
+    offsetParam?: string;
+    limitParam?: string;
+    sortByParam?: string;
+    orderParam?: string;
+    searchParam?: string;
+    rowsKey?: string;
+    totalKey?: string;
+};
+export type RestSource = {
+    kind: 'rest';
+    /** Origin + version prefix, e.g. `https://api.example.com/v1`. */
+    baseUrl: string;
+    /** Collection path, e.g. `customers` or `albums/{id}/tracks`. */
+    path: string;
+    method: RestMethod;
+    params: RequestParam[];
+    idField?: string;
+    /** Wire-format preset for real server paging/sort (offsetLimit / dummyjson /
+     *  jsonServer). When set, it supersedes `rowsPath`/`totalPath`. */
+    adapter?: RestAdapterConfig;
+    /** Dotted path in the response body holding the rows, e.g. `data.items`. */
+    rowsPath?: string;
+    /** Dotted path holding the total row count, e.g. `data.total`. */
+    totalPath?: string;
+};
+export type SqlSource = {
+    kind: 'sql';
+    table: string;
+    dialect?: SqlDialectKind; /** DB schema / search path (Postgres/MSSQL); default `public`. Qualifies the table. */
+    schema?: string;
+};
+export type SupabaseSource = {
+    kind: 'supabase';
+    table: string;
+    url?: string;
+    key?: string;
+    realtime?: boolean;
+};
+/** Embedded Postgres (PGlite) - a real, persistent database with ZERO backend
+ *  setup. Runs in the browser, persisting to IndexedDB. Swap for a `sql` source
+ *  pointed at hosted Postgres to go to production (same schema + SQL). */
+export type PgliteSource = {
+    kind: 'pglite';
+    table: string;
+    seed?: Record<string, unknown>[];
+};
+/** Where one entity's rows come from. */
+export type EntityDataSource = MemorySource | RestSource | SqlSource | SupabaseSource | PgliteSource;
+/** The kinds of block a screen can hold: data-bound (entity-derived) or the
+ *  entity-agnostic `'component'` (a UI-kit component from `UI_COMPONENT_REGISTRY`,
+ *  usable on any screen, including a freestanding one with no entity). */
+export type BlockKind = 'grid' | 'form' | 'chart' | 'dashboard' | 'kpi' | 'gauge' | 'tree' | 'tabs' | 'accordion' | 'master-detail' | 'lookup' | 'pivot' | 'filter' | 'record' | 'board' | 'calendar' | 'detail' | 'component';
+export type GridAlign = 'left' | 'center' | 'right';
+/** No-code per-column value formatting. Compiles to the grid's `format` (CellFormatConfig):
+ *  a raw `1234.5` becomes `$1,234.50` / `42%` / `Jun 27, 2026` without a code renderer. */
+export type ColumnFormat = {
+    type: 'number';
+    decimals?: number;
+} | {
+    type: 'currency';
+    currency?: string;
+} | {
+    type: 'percent';
+    decimals?: number; /** cell values are 0-100 (42 -> 42%) not 0-1. */
+    valueIsPercentPoints?: boolean;
+} | {
+    type: 'date';
+    pattern?: string;
+} | {
+    type: 'datetime';
+    pattern?: string;
+};
+/** No-code rich cell renderer for a column. Unlike `ColumnFormat` (value formatting),
+ *  these render a component/link: an auto-colored status pill, a progress bar, or a
+ *  clickable link. Compiles to a `cell` snippet on the column. Mutually exclusive with
+ *  `format` (a cell is either formatted text or a rich renderer). */
+export type ColumnCellType = {
+    kind: 'badge';
+} | {
+    kind: 'progress';
+    max?: number;
+} | {
+    kind: 'link';
+    as?: 'url' | 'email' | 'tel';
+};
+export type GridColumnConfig = {
+    field: string;
+    show: boolean;
+    header?: string;
+    width?: number;
+    align?: GridAlign;
+    pin?: 'left' | 'right'; /** Aggregate this column into the group summary row when the grid is grouped. */
+    aggregate?: Reduce; /** No-code display formatting (currency / percent / date / ...). */
+    format?: ColumnFormat; /** No-code rich cell renderer (badge / progress / link). */
+    cellType?: ColumnCellType;
+};
+/** How a grid edits its rows: read-only, inline (Excel-style cells), or a popup form. */
+export type GridEditing = 'none' | 'inline' | 'form';
+/** Row height preset. */
+export type GridDensity = 'compact' | 'normal' | 'comfortable';
+/** Where the pagination footer sits. */
+export type PagerPosition = 'top' | 'bottom' | 'both';
+export type GridConfig = {
+    kind: 'grid';
+    columns: GridColumnConfig[];
+    pageSize: number;
+    selectable: boolean;
+    sortable: boolean;
+    filterable: boolean;
+    /** Which filtering surfaces show when `filterable` is on. Undefined = the global search
+     *  box only (back-compat). Combine a global search, a per-column filter row, and/or the
+     *  column header filter menu. */
+    filterUi?: GridFilterUi;
+    editing: GridEditing;
+    /** Presentation of the edit form when `editing === 'form'`. */
+    formPresentation: Presentation;
+    /** Form layout depth (all optional; default = the auto 2-column form of all fields). */
+    formColumns?: 1 | 2 | 3;
+    /** Restrict + order the form's fields (field names). */
+    formFields?: string[];
+    /** Group fields into titled fieldsets. Overrides the entity's own
+     *  `EntitySchema.form.sections` for this grid's form. */
+    formSections?: FormSection[];
+    /** Dialog title override + width for the modal/drawer form. */
+    formTitle?: string;
+    formSize?: 'sm' | 'md' | 'lg';
+    density: GridDensity;
+    striped: boolean;
+    /** Excel-style cell/range selection. */
+    cellSelection: boolean;
+    /** Show a totals/summary footer row. */
+    rowSummaries: boolean;
+    /** Paginate (false shows all rows, no pager). */
+    paginated: boolean;
+    /** Where the pager sits when paginated. */
+    paginationPosition: PagerPosition;
+    /** Page-size choices in the pager's selector. */
+    pageSizeOptions: number[];
+    /** Drill-through: clicking a row navigates to `screen`, filtered by the clicked
+     *  row's `sourceField` value on the target's `targetField`. */
+    rowLink?: RowLink;
+    /** Per-row action buttons (edit / delete / navigate) shown in an actions column. */
+    rowActions?: RowAction[];
+    /** No-code conditional formatting: color / bold a cell by its value. Compiled to
+     *  the grid's `conditionalFormats` rule engine. */
+    formatRules?: FormatRule[];
+    /** No-code row grouping: fields to group rows by (outermost first). When set, the
+     *  grid loads the full dataset and groups/sorts/paginates client-side (so groups
+     *  span every row, not just a server page) and shows the grouping controls. Per-column
+     *  `aggregate` values roll up into each group's summary row. */
+    grouping?: string[];
+    /** No-code export toolbar: a button bar above the grid wired to the grid's own
+     *  export API (CSV / JSON / copy-to-clipboard - no extra dependencies). */
+    export?: GridExportConfig;
+    /** No-code tree data: render the grid's own rows as an expand/collapse hierarchy
+     *  built from a self-referential parent field. Mutually exclusive with `grouping`. */
+    treeData?: TreeDataConfig;
+    /** Render the grid's rows as a calendar / scheduler (a view of the grid, like the
+     *  Kanban board). Mutually exclusive with grouping / tree. Uses the enterprise
+     *  scheduler renderer (`enableSchedulerView`). */
+    scheduler?: SchedulerViewConfig;
+    /** Raw SvGrid prop overrides from the block's "All properties" panel - every grid
+     *  prop the curated controls don't manage. Passed straight through to `<SvGrid>`
+     *  (deduped against the curated props at codegen time). */
+    props?: Record<string, unknown>;
+};
+/** Which calendar view the scheduler opens on / offers. */
+export type SchedulerViewMode = 'month' | 'week' | 'day' | 'agenda' | 'timelineDay' | 'timelineWeek' | 'timelineMonth' | 'timelineYear';
+/** No-code scheduler-view config: map the entity's fields onto calendar events. Only
+ *  `startField` is required; the rest are optional refinements. Compiles to SvGrid's
+ *  `scheduler` prop + write-back handlers. */
+export type SchedulerViewConfig = {
+    /** Field holding the event start (Date / epoch / ISO string). Required. */
+    startField: string;
+    /** Field holding the event end. Omit to use a default duration from the start. */
+    endField?: string;
+    /** Field for the event title. Defaults to the first column. */
+    titleField?: string;
+    /** Field holding a per-event accent color. */
+    colorField?: string;
+    /** Field that groups events into per-resource columns (people / rooms / machines). */
+    resourceField?: string;
+    /** Field holding a recurrence rule (one event per matching day). */
+    recurrenceField?: string;
+    /** Boolean field marking an all-day event. */
+    allDayField?: string;
+    /** The view shown first. Default 'month'. */
+    initialView?: SchedulerViewMode;
+    /** Enable drag-to-move + edge-resize (writes back through the data source). */
+    editable?: boolean;
+    /** Show the built-in event detail drawer. */
+    drawer?: boolean;
+};
+/** Tree-data grid config: `parentField` is a self-referential FK (a row whose parent is
+ *  empty / not in the set is a root); `labelField` is the column that shows the indented,
+ *  expandable tree cell. */
+export type TreeDataConfig = {
+    parentField: string;
+    labelField: string;
+};
+/** Which export affordances the grid toolbar shows. All go through the grid's built-in
+ *  export API (dependency-free). Empty / all-false = no toolbar. */
+/** Export buttons on a grid's toolbar.
+ *
+ *  `csv` / `json` / `copy` use the free grid API. `xlsx` / `pdf` / `print` go
+ *  through `@svgrid/enterprise` (real OOXML, pdfmake, paginated print) and pull
+ *  in their optional peer deps - jszip for xlsx, pdfmake for pdf - which the
+ *  generated package.json declares only when the button is switched on. */
+export type GridExportConfig = {
+    csv?: boolean;
+    json?: boolean;
+    copy?: boolean;
+    xlsx?: boolean;
+    pdf?: boolean;
+    print?: boolean;
+};
+/** Which filtering surfaces the grid shows (when `filterable`). `global` = the search-all
+ *  box, `row` = a filter input under each header, `menu` = the column header filter menu. */
+export type GridFilterUi = {
+    global?: boolean;
+    row?: boolean;
+    menu?: boolean;
+};
+/** A conditional-formatting comparison. */
+export type FormatOp = 'eq' | 'ne' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'empty' | 'notEmpty';
+/** One no-code format rule: style a `field`'s cell when the comparison holds. */
+export type FormatRule = {
+    field: string;
+    op: FormatOp;
+    value?: string | number;
+    color?: string;
+    background?: string;
+    bold?: boolean;
+};
+/** A row-click drill-through to another screen. */
+export type RowLink = {
+    screen: string;
+    sourceField?: string;
+    targetField: string;
+};
+/** One per-row action button. */
+export type RowActionKind = 'edit' | 'delete' | 'navigate' | 'custom';
+export type RowAction = {
+    kind: RowActionKind;
+    label?: string;
+    /** navigate: target screen id. */
+    screen?: string;
+    /** navigate: field on this row whose value is passed (defaults to the id). */
+    sourceField?: string;
+    /** navigate: field on the target entity to filter by. */
+    targetField?: string;
+    /** custom: stable id - becomes the generated `/api/actions/<id>` route + handler
+     *  name. Required when `kind` is `'custom'`. */
+    id?: string;
+    /** custom: icon glyph (rendered next to the label). */
+    icon?: string;
+    /** custom: confirm before running, e.g. "Approve this order?". */
+    confirm?: string;
+};
+/** A custom action: a button wired to a generated stub API route + client
+ *  handler - the plumbing (fetch, loading state, error handling, RBAC gate) is
+ *  generated; the developer fills in the actual logic in the stub route.
+ *  Screen-level actions render in the screen's toolbar and work on ANY screen,
+ *  including one with no bound entity. Row-level actions (via `RowAction`'s
+ *  `'custom'` kind) render per-row in a grid, alongside edit/delete/navigate. */
+export type ActionConfig = {
+    id: string;
+    label: string;
+    icon?: string;
+    confirm?: string;
+};
+/** Legacy standalone edit-form block. Editing is now a Grid property; kept so old
+ *  `studio.config.json` files still parse. Not offered in the palette. */
+export type FormConfig = {
+    kind: 'form';
+    presentation: Presentation;
+};
+/** A chart, optionally drilling into `drillScreen` (filtered by the clicked category). */
+export type ChartConfig = {
+    kind: 'chart';
+    dimension: string;
+    measure?: string;
+    reduce: Reduce;
+    type: ChartType;
+    drillScreen?: string;
+    dataLabels?: boolean;
+    color?: string;
+};
+/** Number format for a KPI value. `auto` keeps the legacy behavior ($ when the
+ *  measure's label carries `$`, else grouped number). */
+export type KpiFormat = 'auto' | 'number' | 'currency' | 'percent' | 'compact';
+export type KpiConfig = {
+    kind: 'kpi';
+    label: string;
+    measure?: string;
+    reduce: Reduce;
+    /** Value formatting. Defaults to `auto`. */
+    format?: KpiFormat;
+    /** Field to bucket the measure by for an inline sparkline (e.g. a date or stage). */
+    trendField?: string;
+    /** Aggregate per sparkline bucket. Defaults to `reduce`. */
+    trendReduce?: Reduce;
+    /** Target value: shows a "% of target" delta chip. */
+    target?: number;
+};
+/** A radial gauge (SvGauge) of one aggregated measure within [min, max]. Like a
+ *  KPI but rendered as an arc - good for utilization, progress, scores. */
+export type GaugeConfig = {
+    kind: 'gauge';
+    label: string;
+    measure?: string;
+    reduce: Reduce;
+    min: number;
+    max: number;
+    unit?: string;
+};
+/** A hierarchical tree (SvTree) built from the entity's own rows: `labelField` is
+ *  the node text, `parentField` is a self-referential FK (a row whose parent is
+ *  empty / unknown is a root). Good for categories, folders, org charts. */
+export type TreeConfig = {
+    kind: 'tree';
+    labelField: string;
+    parentField: string;
+};
+/** One tab of a Tabs container: a label + its own ordered child blocks. */
+export type StudioTab = {
+    label: string;
+    blocks: Block[];
+};
+/** A tabbed container (SvTabs) grouping display blocks into tabs. Children are the
+ *  controller-free, `allRows`-driven blocks (see `TAB_CHILD_KINDS`). */
+export type TabsConfig = {
+    kind: 'tabs';
+    tabs: StudioTab[];
+};
+/** One section of an Accordion container: a label + its own ordered child blocks. */
+export type AccordionSection = {
+    label: string;
+    blocks: Block[];
+};
+/** An accordion container (SvAccordion): collapsible sections, each hosting its own
+ *  child blocks (same container-child set as Tabs). `multiple` lets several sections
+ *  stay open at once (default: single-open). */
+export type AccordionConfig = {
+    kind: 'accordion';
+    sections: AccordionSection[];
+    multiple?: boolean;
+};
+export type DashboardConfig = {
+    kind: 'dashboard';
+};
+export type MasterDetailConfig = {
+    kind: 'master-detail';
+    childEntity: string;
+    foreignKey: string;
+    linkScreen?: string;
+};
+export type LookupConfig = {
+    kind: 'lookup';
+    field: string;
+};
+/** A pivot table (SvPivotDesigner): row/column dimensions + one aggregated measure.
+ *  `aggregate` reuses the Reduce set (all valid pivot aggregators). */
+export type PivotConfig = {
+    kind: 'pivot';
+    rows: string[];
+    cols: string[];
+    measure?: string;
+    aggregate: Reduce;
+};
+/** A faceted filter panel that drives the screen's grid. `fields` are the columns
+ *  exposed as facets (enum/boolean -> select, text -> contains search). */
+export type FilterPanelConfig = {
+    kind: 'filter';
+    fields: string[];
+    title?: string;
+};
+/** A record detail panel: shows the row selected in the screen's grid via
+ *  SvGridEditPanel. `fields` optionally narrows which fields show (empty = all). */
+export type RecordConfig = {
+    kind: 'record';
+    fields?: string[];
+    editable: boolean;
+    presentation?: Presentation;
+};
+/** A Kanban board (SvBoard): columns are an `enum` field's options (`groupBy`),
+ *  rows become draggable cards titled by `titleField`. Dragging a card changes its
+ *  `groupBy` value. Optional `badgeField` (a chip) + `subtitleField` (secondary line). */
+export type BoardConfig = {
+    kind: 'board';
+    groupBy: string;
+    titleField: string;
+    badgeField?: string;
+    subtitleField?: string;
+    openScreen?: string;
+};
+/** A month event-calendar (SvSchedule): each row with a `dateField` value is an
+ *  event on that day, labelled by `titleField` and (optionally) tinted by an enum
+ *  `colorField`. Good for appointments / events / bookings / shifts. */
+export type CalendarConfig = {
+    kind: 'calendar';
+    dateField: string;
+    titleField: string;
+    colorField?: string;
+    openScreen?: string;
+};
+/** A related child collection shown as a tab on a record detail page. */
+export type DetailRelated = {
+    entity: string;
+    foreignKey: string;
+    label?: string;
+    titleField?: string;
+    subtitleField?: string;
+    dateField?: string;
+    statusField?: string;
+    parentField?: string;
+};
+/** A full record "detail page" (SvRecordDetail): a header (title + subtitle +
+ *  colored `statusField` pill + `metricFields` tiles), a tabbed Overview of
+ *  `sections` (field groups), and one tab per `related` child collection (a
+ *  timeline of the children pointing back at the record). The universal signature
+ *  view for relation-heavy entities where a board / calendar does not fit. */
+export type DetailConfig = {
+    kind: 'detail';
+    titleField: string;
+    subtitleField?: string;
+    statusField?: string;
+    metricFields?: string[];
+    sections?: {
+        label: string;
+        fields: string[];
+    }[];
+    related?: DetailRelated[];
+};
+/** A UI-kit component (from `UI_COMPONENT_REGISTRY`, keyed by `component`) dropped
+ *  onto a screen. Entity-agnostic - works on a freestanding page or mixed onto an
+ *  entity-bound screen alike. `props` holds its configured "chrome" values, keyed
+ *  by the registry entry's prop `key`; a component with `hasContent` also stores
+ *  its literal text content under the reserved `_content` key. */
+/** A data binding for one component prop (or `_content`): its value is computed
+ *  from the screen's rows instead of a static literal. `aggregate` reduces a field
+ *  over all rows (a KPI-style number), `field` reads the first row's field, `expr`
+ *  is a raw JS expression over `rows`. Needs an entity screen (rows to bind to). */
+export type ComponentBinding = {
+    kind: 'aggregate';
+    field?: string;
+    reduce: Reduce;
+} | {
+    kind: 'field';
+    field: string;
+} | {
+    kind: 'expr';
+    code: string;
+};
+export type ComponentConfig = {
+    kind: 'component';
+    component: string;
+    props: Record<string, unknown>;
+    name?: string;
+    bindings?: Record<string, ComponentBinding>;
+};
+export type BlockConfig = GridConfig | FormConfig | ChartConfig | KpiConfig | GaugeConfig | TreeConfig | TabsConfig | AccordionConfig | DashboardConfig | MasterDetailConfig | LookupConfig | PivotConfig | FilterPanelConfig | RecordConfig | BoardConfig | CalendarConfig | DetailConfig | ComponentConfig;
+/** 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 declare const TAB_CHILD_KINDS: ReadonlyArray<BlockKind>;
+/** Alias: the same set applies to Accordion sections. */
+export declare const CONTAINER_CHILD_KINDS: readonly BlockKind[];
+/** Display-block child kinds (no `component`) - what the container "add block" menu offers;
+ *  components are added separately, by registry key, via `addContainerComponent`. */
+export declare const CONTAINER_DISPLAY_KINDS: ReadonlyArray<BlockKind>;
+/** All blocks on a screen, flattened to include the children nested in Tabs
+ *  containers - used to detect kinds for imports / data loading. */
+export declare function flattenBlocks(blocks: ReadonlyArray<Block>): Block[];
+/** User style overrides for a block's wrapper element (the card around the block).
+ *  Each field is an OVERRIDE - `undefined` keeps the block kind's default look. Applied
+ *  identically in the designer preview and the generated app (see `blockStyleCss`). */
+export type BlockStyle = {
+    /** Force a border on (true) or off (false); undefined = the kind's default. */
+    border?: boolean;
+    /** Force a drop shadow on (true) or off (false); undefined = default. */
+    shadow?: boolean;
+    /** Inner padding, px. */
+    padding?: number;
+    /** Outer margin, px. */
+    margin?: number;
+    /** Background color (any CSS color). */
+    background?: string;
+    /** Corner radius, px. */
+    radius?: number;
+};
+export type Block = {
+    id: string;
+    /** Coarse width in a 3-col grid (legacy + quick buttons). `colSpan` overrides it. */
+    span: 1 | 2 | 3;
+    /** Fine width in a 12-col grid (1-12), set by the horizontal drag / slider.
+     *  Falls back to `span * 4` (so 1/2/3 -> 4/8/12) when unset. */
+    colSpan?: number;
+    /** Canvas/preview region height in px. Undefined = the kind's natural default.
+     *  Applies to height-driven blocks (grid, chart, master-detail). */
+    height?: number;
+    /** Per-block appearance overrides (border / shadow / padding / margin / bg / radius). */
+    style?: BlockStyle;
+    /** Extra CSS class(es) put on the block's wrapper, so custom.css can target it. */
+    className?: string;
+    config: BlockConfig;
+};
+/** 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 declare function sanitizeClassName(raw: string | undefined): string;
+/** The sanitized extra class(es) for a block's wrapper. */
+export declare function blockClassName(block: Pick<Block, 'className'>): string;
+/** The number of columns (1-12) a block occupies in the 12-col layout. */
+export declare const blockColumns: (b: Pick<Block, "span" | "colSpan">) => number;
+/** 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 declare function blockStyleCss(style: BlockStyle | undefined): string;
+/** 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 declare function mergeBlockStyle(base: BlockStyle | undefined, patch: Partial<BlockStyle>): BlockStyle | undefined;
+/** Navigation placement for a screen (Manage Pages: show/hide + label + order). */
+export type ScreenNav = {
+    show?: boolean;
+    label?: string;
+    order?: number;
+};
+/** 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 declare const ON_LOAD = "onLoad";
+export declare const ON_DESTROY = "onDestroy";
+/** Every lifecycle slot the Code view can edit, in display order. */
+export declare const HANDLER_SLOTS: ReadonlyArray<string>;
+/** The handler-steps key for a component block's click event. */
+export declare const clickSlot: (blockId: string) => string;
+/** 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 declare const rowSelectSlot: (blockId: string) => string;
+/** The handler-steps key for a component block's change (value change) event. */
+export declare const changeSlot: (blockId: string) => string;
+/** 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 declare const eventSlot: (event: string, blockId: string) => string;
+/** The handler-steps key for the screen's form-submit (record saved) event. The
+ *  compiled steps get the submitted `row` (values) in scope. */
+export declare const FORM_SUBMIT = "formSubmit";
+/** One event on the Grid, exposed to code-behind as `ctx.grid.<method> = (e) => {}`.
+ *  `prop` is the SvGrid callback it wires to (empty for `dataEvent`s, which fire from
+ *  Studio's data controller on create/update/delete rather than from the grid markup). */
+export type GridEventDef = {
+    key: string;
+    method: string;
+    prop: string;
+    params: string;
+    builtin: boolean;
+    desc: string;
+    dataEvent?: boolean;
+};
+/** 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 declare const GRID_EVENTS: readonly GridEventDef[];
+/** A screen-scoped reactive variable (`ctx.state.<name>`). Emitted as `$state`. */
+export type StateVarType = 'string' | 'number' | 'boolean' | 'json';
+export type StateVar = {
+    name: string;
+    type: StateVarType;
+    initial?: string;
+};
+/** The `$state(...)` initializer for a variable's declared type. */
+export declare function stateInitExpr(v: StateVar): string;
+/** The TS type annotation for a variable. */
+export declare function stateTsType(v: StateVar): string;
+/** A value expression usable in steps / conditions: a literal, a state var, a URL
+ *  param, or the current row (for row-scoped handlers). Compiles to a `ctx` expr. */
+export type LogicValue = {
+    kind: 'literal';
+    value: string;
+} | {
+    kind: 'state';
+    name: string;
+} | {
+    kind: 'param';
+    name: string;
+} | {
+    kind: 'field';
+    name: string;
+};
+export declare function compileValue(v: LogicValue, rowExpr?: string): string;
+export type LogicOp = 'eq' | 'neq' | 'gt' | 'lt' | 'gte' | 'lte' | 'contains' | 'truthy' | 'falsy';
+export type Condition = {
+    left: LogicValue;
+    op: LogicOp;
+    right?: LogicValue;
+};
+export declare function compileCondition(c: Condition, rowExpr?: string): string;
+/** A field assignment used by create / update record steps. */
+export type FieldValue = {
+    field: string;
+    value: LogicValue;
+};
+/** One step in a visual "method" (the Methods panel, Radzen-style). Each compiles
+ *  to a line of typed `ctx` code-behind - so the visual builder and the code editor
+ *  produce identical output. `code` is the raw-TS escape hatch. */
+export type ActionStep = {
+    type: 'navigate';
+    to: string;
+} | {
+    type: 'gridExport';
+    format?: 'csv' | 'tsv' | 'json';
+} | {
+    type: 'gridCopy';
+} | {
+    type: 'gridClear';
+    what: 'filters' | 'sort' | 'selection';
+} | {
+    type: 'gridSort';
+    field: string;
+    dir?: 'asc' | 'desc';
+} | {
+    type: 'gridFilter';
+    field: string;
+    value: string;
+} | {
+    type: 'reloadData';
+} | {
+    type: 'setProp';
+    target: string;
+    prop: string;
+    value: string;
+} | {
+    type: 'setText';
+    target: string;
+    value: string;
+} | {
+    type: 'alert';
+    message: string;
+} | {
+    type: 'apiAction';
+    actionId: string;
+} | {
+    type: 'setVar';
+    name: string;
+    value: LogicValue;
+} | {
+    type: 'createRecord';
+    values: FieldValue[];
+} | {
+    type: 'updateRecord';
+    id: LogicValue;
+    values: FieldValue[];
+} | {
+    type: 'deleteRecord';
+    id: LogicValue;
+} | {
+    type: 'branch';
+    condition: Condition;
+    then: ActionStep[];
+    else?: ActionStep[];
+} | {
+    type: 'code';
+    code: string;
+};
+export type ActionStepType = ActionStep['type'];
+/** Compile one step to a `ctx` statement (a single line, no trailing newline). */
+export declare function compileStep(step: ActionStep): string;
+/** Compile a list of steps to a handler body (indented lines). */
+export declare function compileHandlerSteps(steps: ReadonlyArray<ActionStep>): string;
+/** One step in an entity trigger (a server-side rule). */
+export type TriggerStep = {
+    type: 'setField';
+    field: string;
+    value: LogicValue;
+} | {
+    type: 'requireField';
+    field: string;
+    message?: string;
+} | {
+    type: 'reject';
+    condition: Condition;
+    message: string;
+} | {
+    type: 'branch';
+    condition: Condition;
+    then: TriggerStep[];
+    else?: TriggerStep[];
+} | {
+    type: 'code';
+    code: string;
+};
+export type TriggerEvent = 'beforeCreate' | 'afterCreate' | 'beforeUpdate' | 'afterUpdate' | 'beforeDelete' | 'afterDelete';
+/** All trigger events, in display order; before-hooks transform/validate, after-hooks are side effects. */
+export declare const TRIGGER_EVENTS: ReadonlyArray<TriggerEvent>;
+export type EntityTriggers = Partial<Record<TriggerEvent, TriggerStep[]>>;
+/** Compile one trigger step against the payload variable `rowExpr` (default `v`). */
+export declare function compileTriggerStep(step: TriggerStep, rowExpr?: string): string;
+export declare function compileTriggerSteps(steps: ReadonlyArray<TriggerStep>, rowExpr?: string): string;
+/** `entity` is optional: a screen with none is a freestanding page (no data
+ *  binding, no blocks - every `BlockKind` is entity-bound) - just a title, an
+ *  empty content area, and optionally a toolbar of custom `actions`. Wire up a
+ *  "Run report" / "Sync now" button on a blank page without a table behind it.
+ *
+ *  `code` opts the screen into a create-once `handlers.ts` companion (user-owned,
+ *  never regenerated) whose `onLoad(ctx)` runs on mount; `renderGrid` adds a Grid
+ *  fed via `ctx.setRows`. `handlerBodies` holds each handler's body (keyed by name). */
+/** How a screen arranges its blocks: the default 12-column responsive grid, or a
+ *  docking workspace (SvDockManager - drag-to-dock splits/tabs + floating / pinned panes,
+ *  serialized as `dock`). */
+export type ScreenLayout = 'grid' | 'stack' | 'split' | 'dock' | 'canvas';
+/** Layouts that arrange blocks as dockable / split panes (both back onto a
+ *  serialized `DockManagerState`; `split` renders it locked = resize-only). */
+export declare const PANE_LAYOUTS: ReadonlyArray<ScreenLayout>;
+export declare function isPaneLayout(layout: ScreenLayout): boolean;
+/** Free-form canvas: a block is placed on a 12-column grid by explicit cell
+ *  coordinates (col/row) + spans, instead of flowing. `row`/`rowSpan` count
+ *  fixed-height rows (see CANVAS_ROW_PX). All values are grid cells, 0-indexed. */
+export type CanvasRect = {
+    col: number;
+    row: number;
+    colSpan: number;
+    rowSpan: number;
+};
+export declare const CANVAS_COLS = 12;
+/** Height of one canvas row in px (grid-auto-rows), shared by designer + codegen. */
+export declare const CANVAS_ROW_PX = 40;
+/** Gap between canvas cells in px. */
+export declare const CANVAS_GAP_PX = 8;
+export type GridLayoutOpts = {
+    colGap?: number;
+    rowGap?: number;
+    maxWidth?: number;
+    align?: 'start' | 'stretch';
+    mobileBreakpoint?: number;
+};
+export type StackLayoutOpts = {
+    gap?: number;
+    maxWidth?: number;
+    align?: 'left' | 'center';
+    dividers?: boolean;
+    minHeight?: number;
+};
+export type SplitLayoutOpts = {
+    orientation?: 'auto' | 'row' | 'column';
+    minPaneSize?: number;
+    persist?: boolean;
+};
+export type DockLayoutOpts = {
+    allowPopout?: boolean;
+    hideSingleTab?: boolean;
+    headerPosition?: 'top' | 'bottom' | 'left' | 'right';
+    persist?: boolean;
+};
+export type CanvasLayoutOpts = {
+    cols?: number;
+    rowHeight?: number;
+    gap?: number;
+    showGrid?: boolean;
+};
+export type LayoutOpts = {
+    grid?: GridLayoutOpts;
+    stack?: StackLayoutOpts;
+    split?: SplitLayoutOpts;
+    dock?: DockLayoutOpts;
+    canvas?: CanvasLayoutOpts;
+};
+/** `maxWidth: 0` (or absent) means full-bleed. */
+export declare const GRID_OPT_DEFAULTS: Required<GridLayoutOpts>;
+export declare const STACK_OPT_DEFAULTS: Required<StackLayoutOpts>;
+export declare const SPLIT_OPT_DEFAULTS: Required<SplitLayoutOpts>;
+export declare const DOCK_OPT_DEFAULTS: Required<DockLayoutOpts>;
+export declare const CANVAS_OPT_DEFAULTS: Required<CanvasLayoutOpts>;
+export declare const gridOpts: (s: Screen) => Required<GridLayoutOpts>;
+export declare const stackOpts: (s: Screen) => Required<StackLayoutOpts>;
+export declare const splitOpts: (s: Screen) => Required<SplitLayoutOpts>;
+export declare const dockOpts: (s: Screen) => Required<DockLayoutOpts>;
+export declare const canvasOpts: (s: Screen) => Required<CanvasLayoutOpts>;
+/** Patch one mode's settings (merged over any existing values). */
+export declare function setLayoutOpts<K extends keyof LayoutOpts>(project: StudioProject, screenId: string, mode: K, patch: Partial<NonNullable<LayoutOpts[K]>>): StudioProject;
+export type Screen = {
+    id: string;
+    entity?: string;
+    title: string;
+    route: string;
+    blocks: Block[];
+    nav?: ScreenNav;
+    actions?: ActionConfig[];
+    code?: boolean;
+    renderGrid?: boolean;
+    handlerBodies?: Record<string, string>;
+    handlerSteps?: Record<string, ActionStep[]>;
+    handlersSource?: string;
+    className?: string;
+    layout?: ScreenLayout;
+    dock?: DockManagerState;
+    canvas?: Record<string, CanvasRect>;
+    layoutOpts?: LayoutOpts;
+    state?: StateVar[];
+    renderMode?: 'ssr' | 'spa';
+};
+/** The generated app's shell (master layout): sidebar, top-nav, or bottom-nav; brand, footer. */
+export type ShellStyle = 'sidebar' | 'top-nav' | 'bottom-nav';
+export type ShellConfig = {
+    style?: ShellStyle;
+    brand?: string;
+    footer?: string;
+    navPosition?: 'left' | 'right';
+    logo?: string;
+    toolbar?: boolean;
+};
+export type ProjectTheme = {
+    accent?: string;
+    preset?: string;
+    mode?: 'light' | 'dark';
+    shell?: ShellConfig;
+    customCss?: string;
+    appClass?: string;
+};
+/** A mutating CRUD action, gated by RBAC (reads are implied by screen access). */
+export type CrudAction = 'create' | 'update' | 'delete';
+export declare const CRUD_ACTIONS: readonly CrudAction[];
+/** Access rules for one role. */
+export type RoleAccess = {
+    role: string;
+    /** Screen ids the role can open. `'*'` = every screen. */
+    screens: '*' | string[];
+    /** Write actions the role may perform. `'*'` = all; read is implied by screen access. */
+    actions: '*' | CrudAction[];
+};
+/** Role-based access control for the app. When `enabled`, the generator emits a
+ *  `src/lib/access.ts` and gates nav / actions in the UI AND the server route. */
+export type AccessControl = {
+    enabled: boolean;
+    roles: RoleAccess[];
+    /** Fallback role when the app can't resolve one from the session. Default-denies. */
+    defaultRole?: string;
+};
+/** Authentication starter. When `enabled`, the generator scaffolds a real sign-in:
+ *  a session cookie + `hooks.server.ts` that populates `event.locals.role`/`user`
+ *  (closing the loop the RBAC layer expects), a `/login` page, sign-out, and demo
+ *  seed users (one per RBAC role, or a single admin). Dependency-free: Web Crypto +
+ *  stateless signed cookies. `protect` gates the whole app behind login (default). */
+/** Social / enterprise sign-in providers. `oidc` is a generic OpenID Connect issuer
+ *  (covers Azure AD / Entra ID, Okta, Auth0, Keycloak, ... via discovery). */
+export type OAuthProvider = 'github' | 'google' | 'oidc';
+export type AuthConfig = {
+    enabled: boolean;
+    /** Which sign-in system to scaffold. `'builtin'` (default) is the dependency-free
+     *  cookie-session starter below (own user store, server route guards, RBAC).
+     *  `'supabase'` delegates to Supabase Auth: a client-side `SvAuthGate` over the
+     *  shared Supabase client, pairing with the database's Row Level Security. The
+     *  builtin-only sub-options (register / userAdmin / oauth / twoFactor / email) do
+     *  not apply to the Supabase provider. */
+    provider?: 'builtin' | 'supabase';
+    /** Redirect unauthenticated visitors to /login for every route. Default true. */
+    protect?: boolean;
+    /** Self-service sign-up + password recovery (/register, /forgot-password,
+     *  /reset-password). Needs the DB-backed user store (turn on the data layer). */
+    register?: boolean;
+    /** An admin user-management screen (/users: list, invite, change role, remove).
+     *  Needs the DB-backed store + RBAC (only a full-access role can open it). */
+    userAdmin?: boolean;
+    /** OAuth / OpenID Connect sign-in buttons. Needs the DB-backed store. */
+    oauth?: OAuthProvider[];
+    /** Email one-time-code two-factor auth. Needs the DB-backed store + real email. */
+    twoFactor?: boolean;
+    /** Real email delivery (Resend HTTP API or SMTP via nodemailer); dev console otherwise.
+     *  Implied when `twoFactor` is on. */
+    email?: boolean;
+};
+/** Does a role's rules permit opening a screen? */
+export declare const roleCanScreen: (r: RoleAccess, screenId: string) => boolean;
+/** Does a role's rules permit a write action? */
+export declare const roleCanAction: (r: RoleAccess, action: CrudAction) => boolean;
+export type StudioProject = {
+    title: string;
+    entities: EntitySchema[];
+    screens: Screen[];
+    /** Default source kind for new entities; per-entity overrides live in `dataSources`. */
+    dataSource: DataSourceKind;
+    /** Per-entity data-source binding, keyed by entity name. */
+    dataSources?: Record<string, EntityDataSource>;
+    /** Project-level Supabase connection (URL + anon key), shared by every
+     *  Supabase-bound entity so it's set once. A per-entity `SupabaseSource.url`/`key`
+     *  still overrides for that entity. Read by the wizard + the `.env` paste hint. */
+    supabase?: {
+        url?: string;
+        key?: string;
+    };
+    theme?: ProjectTheme;
+    /** Role-based access control (optional; off unless `access.enabled`). */
+    access?: AccessControl;
+    /** Authentication starter (optional; off unless `auth.enabled`). Provides the
+     *  session/login that populates the role RBAC consumes. */
+    auth?: AuthConfig;
+    /** Typed data layer: when `'drizzle'` and there's a SQL-bound entity, emit a
+     *  Drizzle schema + typed repositories + drizzle-kit migrations. */
+    dataLayer?: 'drizzle';
+    /** Emit an audit trail: connected routes log create/update/delete + an /audit viewer. */
+    audit?: boolean;
+    /** Localization: when enabled, emit a message catalog + locale switcher and route
+     *  nav / titles / column headers through `t()`. */
+    i18n?: I18nConfig;
+    /** Deploy target: picks the SvelteKit adapter + provider config the bundle emits.
+     *  Defaults to `auto` (@sveltejs/adapter-auto, which detects Vercel/Netlify/Cloudflare). */
+    deploy?: DeployTarget;
+    /** Server-side business-rule triggers, keyed by entity name. Enforced on the
+     *  SQL route (compiled into createKitHandlers `hooks`). */
+    triggers?: Record<string, EntityTriggers>;
+    /** Scheduled background jobs: a guarded `/api/cron` endpoint plus the schedule
+     *  config for the deploy target. Empty / omitted emits nothing. */
+    jobs?: ScheduledJob[];
+    /** Multi-tenancy: scope every row to the signed-in user's tenant. */
+    tenancy?: TenancyConfig;
+};
+/**
+ * Multi-tenancy for the generated app: one database, one deployment, rows
+ * partitioned by a tenant column.
+ *
+ * Enforced on the SERVER, in the API route's `scope` option - reads are
+ * filtered, creates are stamped, and updates/deletes re-read the target under
+ * the scope first. A client that skips the UI still cannot reach another
+ * tenant's rows.
+ *
+ * Requires the [auth starter](./auth.md) (the tenant comes from the session)
+ * and the typed data layer (the column has to exist in the schema). Without
+ * both it degrades to off rather than emitting a half-enforced scope.
+ */
+export type TenancyConfig = {
+    enabled: boolean;
+    /** Column holding the tenant key on every scoped entity. Default `tenantId`. */
+    field?: string;
+    /** Entities to leave GLOBAL (shared across tenants) - reference/lookup tables
+     *  like currencies or countries that every tenant reads. */
+    sharedEntities?: string[];
+};
+/** What a scheduled job does when it fires.
+ *  - `email`: send a summary of an entity (row count + the newest rows).
+ *  - `code`: run a body you write, with `db` / `sendEmail` in scope. */
+export type ScheduledJobKind = 'email' | 'code';
+/**
+ * One scheduled background job.
+ *
+ * Jobs run on the SERVER via a generated `/api/cron` route, not in a browser
+ * tab - unlike the client-side `createScheduler` in `@svgrid/enterprise`, which
+ * only fires while the app is open. The route is secret-guarded and invoked by
+ * the platform's scheduler (Vercel Cron, a GitHub Actions schedule, or your own
+ * crontab hitting the URL).
+ */
+export type ScheduledJob = {
+    /** Stable id - the `?job=` selector and the handler name. */
+    id: string;
+    /** Human label used in comments + the DEPLOY.md table. */
+    name: string;
+    /** Standard 5-field cron expression, interpreted in UTC. */
+    cron: string;
+    /** Off by default is surprising for something you explicitly added, so a job
+     *  runs unless `enabled` is explicitly false. */
+    enabled?: boolean;
+    kind: ScheduledJobKind;
+    /** `email`: the entity to summarize. */
+    entity?: string;
+    /** `email`: recipient address. */
+    to?: string;
+    /** `email`: subject line. Defaults to the job name. */
+    subject?: string;
+    /** `code`: the handler body (TypeScript). */
+    code?: string;
+};
+/** 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 declare function screenRenderMode(_project: StudioProject, screen: Screen): 'ssr' | 'spa';
+/** 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 declare function ssrScreenShape(project: StudioProject, screen: Screen): 'grid' | 'read' | null;
+/** Whether a screen can be emitted as SSR-native (any supported shape). */
+export declare function ssrEligible(project: StudioProject, screen: Screen): boolean;
+/** Set a screen's render mode ('spa' clears back to the default). */
+export declare function setScreenRenderMode(project: StudioProject, screenId: string, mode: 'ssr' | 'spa'): StudioProject;
+/** True when the screen should actually emit as SSR (mode is 'ssr' AND eligible). */
+export declare function isSsrScreen(project: StudioProject, screen: Screen): boolean;
+export declare function withSsrDefaults(project: StudioProject): StudioProject;
+/** The triggers configured for an entity (or an empty object). */
+export declare function triggersOf(project: StudioProject, entity: string): EntityTriggers;
+/** Set (or clear, with `null`) an entity's steps for one trigger event. */
+export declare function setTrigger(project: StudioProject, entity: string, event: TriggerEvent, steps: TriggerStep[] | null): StudioProject;
+/** Turn multi-tenancy on/off and configure the scoping column. */
+export declare function setTenancy(project: StudioProject, tenancy: TenancyConfig | null): StudioProject;
+/** The tenant column name, defaulted. */
+export declare const tenantField: (project: StudioProject) => string;
+/** 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 declare function isTenantScoped(project: StudioProject, entity: string): boolean;
+/** Add or replace a scheduled job (matched by `id`). Pass `null` to remove one. */
+export declare function setJob(project: StudioProject, id: string, job: Omit<ScheduledJob, 'id'> | null): StudioProject;
+/** Where the generated app deploys. Drives the emitted SvelteKit adapter + config. */
+export type DeployTarget = 'auto' | 'vercel' | 'netlify' | 'cloudflare' | 'node';
+/** Localization config: the locales the app ships and which is the default. */
+export type I18nConfig = {
+    enabled: boolean;
+    locales: string[];
+    defaultLocale?: string;
+};
+export type ProjectIssueLevel = 'error' | 'warning';
+export type ProjectIssue = {
+    level: ProjectIssueLevel;
+    message: string;
+    screen?: string;
+    block?: string;
+};
+/** One palette entry: a draggable block kind + what it needs to be useful. */
+export type PaletteItem = {
+    kind: BlockKind;
+    label: string;
+    needs?: 'measure' | 'child';
+};
+/** The designer's block palette, in menu order. (Editing is a Grid property, so
+ *  there's no standalone form block.) */
+export declare const blockPalette: ReadonlyArray<PaletteItem>;
+export declare function entityOf(project: StudioProject, name: string | undefined): EntitySchema | undefined;
+/** Sensible grid columns for an entity: every non-grid-hidden field, shown. */
+export declare function gridColumns(entity: EntitySchema): GridColumnConfig[];
+/** A default config for a freshly-added block of `kind`, sized for the entity. */
+export declare function defaultBlockConfig(kind: BlockKind, entity: EntitySchema): BlockConfig;
+/** 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 declare function pickFacetFields(entity: EntitySchema): string[];
+/** Append a tab to a Tabs container. */
+export declare function addTab(cfg: TabsConfig, label?: string): TabsConfig;
+/** Remove a tab by index (keeps at least one). */
+export declare function removeTab(cfg: TabsConfig, index: number): TabsConfig;
+/** Rename a tab by index. */
+export declare function renameTab(cfg: TabsConfig, index: number, label: string): TabsConfig;
+/** Add a child block (default config for `kind`) to a tab. Only `TAB_CHILD_KINDS` are allowed. */
+export declare function addTabBlock(cfg: TabsConfig, index: number, kind: BlockKind, entity: EntitySchema): TabsConfig;
+/** Remove a child block from a tab by id. */
+export declare function removeTabBlock(cfg: TabsConfig, index: number, blockId: string): TabsConfig;
+/** Add a specific UI-kit component (by registry key) to a tab. */
+export declare function addTabComponent(cfg: TabsConfig, index: number, componentKey: string): TabsConfig;
+/** Append a section (collapsible panel) to an accordion. */
+export declare function addAccordionSection(cfg: AccordionConfig, label?: string): AccordionConfig;
+/** Remove a section by index (keeps at least one). */
+export declare function removeAccordionSection(cfg: AccordionConfig, index: number): AccordionConfig;
+/** Rename a section by index. */
+export declare function renameAccordionSection(cfg: AccordionConfig, index: number, label: string): AccordionConfig;
+/** Toggle single- vs multiple-open behaviour. */
+export declare function setAccordionMultiple(cfg: AccordionConfig, multiple: boolean): AccordionConfig;
+/** Add a display-block child (default config for `kind`) to a section. Only CONTAINER_CHILD_KINDS. */
+export declare function addAccordionBlock(cfg: AccordionConfig, index: number, kind: BlockKind, entity: EntitySchema): AccordionConfig;
+/** Add a specific UI-kit component (by registry key) to a section. */
+export declare function addAccordionComponent(cfg: AccordionConfig, index: number, componentKey: string): AccordionConfig;
+/** Remove a child block from a section by id. */
+export declare function removeAccordionBlock(cfg: AccordionConfig, index: number, blockId: string): AccordionConfig;
+/** A default screen for an entity: a grid (editing via a popup form by default). */
+export declare function defaultScreenFor(entity: EntitySchema): Screen;
+/** A new project from a set of entities: one default screen each, in-memory. */
+export declare function createProject(entities: EntitySchema[], opts?: {
+    title?: string;
+    dataSource?: DataSourceKind;
+}): StudioProject;
+export declare function addBlock(project: StudioProject, screenId: string, kind: BlockKind): StudioProject;
+/** Insert a new block at `index` (drag-drop from the palette). Clamps to range. */
+export declare function addBlockAt(project: StudioProject, screenId: string, kind: BlockKind, index: number): StudioProject;
+/** 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 declare function addComponentBlock(project: StudioProject, screenId: string, componentKey: string, defaultProps?: Record<string, unknown>, index?: number): StudioProject;
+/** 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 declare function componentHandleName(cfg: ComponentConfig): string;
+/** Rename a component's handle (the variable code uses to reach it). */
+export declare function setComponentName(project: StudioProject, screenId: string, blockId: string, name: string): StudioProject;
+/** True when a component has at least one data-bound prop. */
+export declare function componentHasBindings(cfg: ComponentConfig): boolean;
+/** Bind (or, with `binding: null`, unbind) one component prop to the screen's data. */
+export declare function setComponentBinding(project: StudioProject, screenId: string, blockId: string, propKey: string, binding: ComponentBinding | null): StudioProject;
+export declare function removeBlock(project: StudioProject, screenId: string, blockId: string): StudioProject;
+/** Clone a block (config + width/height) with a fresh id, inserted right after it. */
+export declare function duplicateBlock(project: StudioProject, screenId: string, blockId: string): StudioProject;
+/** Move a block one slot up (`-1`) or down (`+1`). No-op at the ends. */
+export declare function moveBlock(project: StudioProject, screenId: string, blockId: string, dir: -1 | 1): StudioProject;
+/** Reorder a block to an explicit index (drag-drop). Clamps to range. */
+export declare function reorderBlock(project: StudioProject, screenId: string, blockId: string, toIndex: number): StudioProject;
+/** Patch a block's config (merged), span/height, and/or appearance `style` (merged;
+ *  keys set to undefined are cleared). */
+export declare function updateBlock(project: StudioProject, screenId: string, blockId: string, patch: {
+    span?: 1 | 2 | 3;
+    colSpan?: number;
+    height?: number;
+    config?: Partial<BlockConfig>;
+    style?: Partial<BlockStyle>;
+    className?: string;
+}): StudioProject;
+/** Replace an entity's schema (e.g. after field edits), keeping its screens. */
+export declare function updateEntity(project: StudioProject, name: string, schema: EntitySchema): StudioProject;
+/** Add an entity + its default screen. */
+export declare function addEntity(project: StudioProject, schema: EntitySchema): StudioProject;
+/** Remove an entity and every screen bound to it. */
+export declare function removeEntity(project: StudioProject, name: string): StudioProject;
+export declare function addScreen(project: StudioProject, entity: string): StudioProject;
+export declare function removeScreen(project: StudioProject, screenId: string): StudioProject;
+export declare function updateScreen(project: StudioProject, screenId: string, patch: Partial<Pick<Screen, 'title' | 'route' | 'entity' | 'nav' | 'actions' | 'className' | 'renderMode'>>): StudioProject;
+/** The screen's layout engine. Defaults to `'grid'` (the 12-column responsive grid). */
+export declare function screenLayoutOf(screen: Screen): ScreenLayout;
+/** Every pane id present anywhere in a dock workspace (main tree + floating + auto-hidden). */
+export declare function dockPaneIds(state: DockManagerState): Set<string>;
+/**
+ * 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 declare function buildDockLayout(screen: Screen): DockManagerState;
+/** 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 declare function syncDockPanes(screen: Screen): Screen;
+/** 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 declare function reconcileDock(screen: Screen): 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 declare function setScreenLayout(project: StudioProject, screenId: string, layout: ScreenLayout): StudioProject;
+/** 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 declare function buildCanvasLayout(screen: Screen): Record<string, CanvasRect>;
+/** The stored rect for a block, or a computed default (so a block added after the
+ *  layout was seeded still lands somewhere sane). */
+export declare function canvasRectOf(screen: Screen, blockId: string): CanvasRect;
+/** 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 declare function setCanvasRect(project: StudioProject, screenId: string, blockId: string, rect: Partial<CanvasRect>): StudioProject;
+/** Named starting arrangements for the 12-column grid - a one-click way to set
+ *  every block's column span to a common pattern instead of picking each by hand. */
+export type GridPreset = 'full' | 'two-col' | 'three-col' | 'sidebar' | 'kpi-row';
+export declare function gridPresetLabel(preset: GridPreset): string;
+export declare const GRID_PRESETS: ReadonlyArray<GridPreset>;
+/** 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 declare function applyGridPreset(project: StudioProject, screenId: string, preset: GridPreset): StudioProject;
+/** Persist a new dock workspace (user rearranged panes in the designer). */
+export declare function setScreenDock(project: StudioProject, screenId: string, dock: DockManagerState): StudioProject;
+/** Add a state variable (unique name; `state_N` if the name is taken / empty). */
+export declare function addStateVar(project: StudioProject, screenId: string, v?: Partial<StateVar>): StudioProject;
+/** Patch a state variable by (old) name. Renames keep the identifier valid + unique. */
+export declare function updateStateVar(project: StudioProject, screenId: string, name: string, patch: Partial<StateVar>): StudioProject;
+/** Remove a state variable by name. */
+export declare function removeStateVar(project: StudioProject, screenId: string, name: string): StudioProject;
+/** 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 declare function reseedScreenDock(project: StudioProject, screenId: string): StudioProject;
+/** The current title (tab text) of a block's dock pane, if the screen is docked. */
+export declare function dockPaneTitleOf(screen: Screen, paneId: string): string | undefined;
+/** Rename a block's dock pane (the tab text) anywhere in the workspace. */
+export declare function setDockPaneTitle(project: StudioProject, screenId: string, paneId: string, title: string): StudioProject;
+/** 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 declare function addFreestandingScreen(project: StudioProject, opts: {
+    title: string;
+    route?: string;
+}): StudioProject;
+/** 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 declare function addScreenAction(project: StudioProject, screenId: string, action: {
+    label: string;
+    icon?: string;
+    confirm?: string;
+}): StudioProject;
+export declare function removeScreenAction(project: StudioProject, screenId: string, actionId: string): StudioProject;
+/** 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 declare function enableScreenCode(project: StudioProject, screenId: string): StudioProject;
+/** Drop the code companion binding (leaves any file the user already wrote on disk;
+ *  the generator simply stops emitting/importing it). */
+export declare function disableScreenCode(project: StudioProject, screenId: string): StudioProject;
+/** 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 declare function setScreenRenderGrid(project: StudioProject, screenId: string, on: boolean): StudioProject;
+/** 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 declare function setHandlerBody(project: StudioProject, screenId: string, handler: string, body: string): StudioProject;
+/** 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 declare function setScreenHandlersSource(project: StudioProject, screenId: string, source: string): StudioProject;
+/** Replace the steps of one method slot (`onLoad`, `onDestroy`, or `click:<blockId>`).
+ *  An empty list clears the slot. Implies `code: true`. */
+export declare function setHandlerSteps(project: StudioProject, screenId: string, slot: string, steps: ActionStep[]): StudioProject;
+/** Append a step to a method slot. */
+export declare function addHandlerStep(project: StudioProject, screenId: string, slot: string, step: ActionStep): StudioProject;
+/** Replace / remove a step at `index` (null removes it). */
+export declare function updateHandlerStep(project: StudioProject, screenId: string, slot: string, index: number, step: ActionStep | null): StudioProject;
+/** Move a step within its slot (dir -1 up, +1 down). */
+export declare function moveHandlerStep(project: StudioProject, screenId: string, slot: string, index: number, dir: -1 | 1): StudioProject;
+/** 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 declare function stepsToCode(project: StudioProject, screenId: string, slot: string): StudioProject;
+/** Insert a block (deep-cloned, fresh id) into a screen - the paste target. Appends by default. */
+export declare function insertBlock(project: StudioProject, screenId: string, block: Block, index?: number): StudioProject;
+/** Duplicate a whole screen (fresh id / route / title + fresh block ids), inserted after it. */
+export declare function duplicateScreen(project: StudioProject, screenId: string): StudioProject;
+/** Move a screen to an explicit index (drag-reorder the tab strip). Clamps to range. */
+export declare function reorderScreen(project: StudioProject, screenId: string, toIndex: number): StudioProject;
+export declare function setDataSource(project: StudioProject, dataSource: DataSourceKind): StudioProject;
+/** Set the deploy target (SvelteKit adapter + provider config the bundle emits). */
+export declare function setDeployTarget(project: StudioProject, deploy: DeployTarget): StudioProject;
+/** Enable / disable the authentication starter (login + session + hooks). */
+export declare function setAuth(project: StudioProject, patch: Partial<AuthConfig> & {
+    enabled: boolean;
+}): StudioProject;
+/** Enable / disable the typed Drizzle data layer (schema + repos + migrations). */
+export declare function setDataLayer(project: StudioProject, enabled: boolean): StudioProject;
+/** A demo user seed for the auth starter: one user per RBAC role (so you can sign in
+ *  and see each role's access), or a single admin when RBAC is off. Passwords are
+ *  demo seeds (like sample rows) - the generated code flags them for replacement. */
+export type SeedUser = {
+    email: string;
+    name: string;
+    role: string;
+    password: string;
+};
+export declare function seedUsers(project: StudioProject): SeedUser[];
+/** A skeleton binding for a kind, seeded with the entity's name as its table/path. */
+export declare function defaultEntitySource(kind: DataSourceKind, entityName: string): EntityDataSource;
+/** Bind one entity to a data source (REST / SQL / Supabase / in-memory). */
+export declare function setEntityDataSource(project: StudioProject, entityName: string, source: EntityDataSource): StudioProject;
+/** 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 declare function entityDataSource(project: StudioProject, entityName: string): EntityDataSource;
+export declare function setTheme(project: StudioProject, theme: ProjectTheme): StudioProject;
+/** 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 declare function setThemePreset(project: StudioProject, preset: string, accent?: string): StudioProject;
+/** Configure the generated app shell (layout style, brand, footer, nav position). */
+export declare function setShell(project: StudioProject, shell: ShellConfig): StudioProject;
+export type ScreenTemplate = 'crud' | 'dashboard' | 'master-detail' | 'empty';
+/** Build a screen for an entity from a template (a preset arrangement of blocks). */
+export declare function screenFromTemplate(entity: EntitySchema, template: ScreenTemplate, opts?: {
+    child?: EntitySchema;
+    foreignKey?: string;
+}): Screen;
+/** Add a screen built from a template. `child` (for master-detail) is an entity name. */
+export declare function addScreenFromTemplate(project: StudioProject, entityName: string, template: ScreenTemplate, opts?: {
+    child?: string;
+    foreignKey?: string;
+}): StudioProject;
+/**
+ * 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 declare function sanitizeProject(project: StudioProject): StudioProject;
+/** Serialize a project to a `studio.config.json` string (the persisted design). */
+export declare function serializeProject(project: StudioProject): string;
+/**
+ * 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 declare function parseProject(json: string): StudioProject;
+/** Validate a project. Errors block codegen; warnings are advisory. */
+export declare function validateProject(project: StudioProject): ProjectIssue[];
+export declare function isProjectValid(project: StudioProject): boolean;