@pilotiq/pilotiq 0.23.1 → 0.24.2

package/CLAUDE.md

@@ -1,265 +0,0 @@
-# CLAUDE.md — `@pilotiq/pilotiq`
-
-Deep notes for the **new** view-based admin panel package. The root `CLAUDE.md` covers monorepo-wide concerns (commands, playgrounds, cross-repo wiring); this file is loaded automatically when working inside `packages/pilotiq/`.
-
----
-
-## Architecture
-
-```
-Pilotiq.make() builder → pilotiq([panels]) provider → registerPilotiqRoutes() → @rudderjs/view
-                         pilotiq() Vite plugin → auto-generates pages/(pilotiq)/ stubs
-```
-
-**Setup (two lines):**
-1. `vite.config.ts` — `import { pilotiq } from '@pilotiq/pilotiq/vite'` → `plugins: [pilotiq(), ...]`
-2. `bootstrap/providers.ts` — `import { pilotiq } from '@pilotiq/pilotiq'` → `pilotiq([adminPanel])`
-
-**Extending the panel:** custom Field / Column / Entry / Widget primitives are documented end-to-end in `docs/guide/extending-pilotiq.md`. Field renderers register via `registerFieldRenderer` (`@pilotiq/pilotiq/react`); ComponentEntry components via `registerEntryComponents` (`@pilotiq/pilotiq/entries`); View components via `registerWidgetComponents` (`@pilotiq/pilotiq/widgets`); whole new widget element types via `registerWidgetRenderer` (`@pilotiq/pilotiq/react`); field label slot (inject UI next to any field label from a plugin) via `registerFieldLabelSlot` (`@pilotiq/pilotiq/react`). Columns are switch-dispatched in `SchemaRenderer` — no public registry; subclass an existing `columnType` and lean on `formatStateUsing` for per-row chrome.
-
----
-
-## Key Files
-
-Deep notes for many of these also live in `~/.claude/projects/-Users-sleman-Projects-pilotiq/memory/`.
-
-- `src/Pilotiq.ts` — Builder: `.path / .branding / .theme / .layout / .resources / .globals / .pages / .schema / .guard / .user(req=>userOrNull) / .use`. Exposes `pilotiq.resolveUser(req)` for routes.
-- `src/RelationManager.ts` — **Plan #11** abstract base for parent-scoped projections. Required `static relationship` (matches a key on the parent model's `static relations` map; doubles as URL segment). Optional `label / labelSingular / icon / recordTitleAttribute / relatedResource`. Static `form(form, ctx) / table(table, ctx) / detail(record, parent)` configurators (mirror Resource shape minus URL ownership — no `slug`, no `pages()`). `ctx: RelationManagerContext` carries `basePath / parentSlug / parentId / relationship / parentRecord / related? / mode` so user code can wire `Action.relationCreate / relationEdit / relationDelete(M, ctx)` (or the M2M sibling factories) from inside `static table()` without threading basePath / parentId by hand. **`mode: 'hasMany' | 'belongsToMany' | 'morphMany' | 'morphTo'`** is auto-derived from `parentModel.relations[rel].type` via `getRelationType` + `normalizeRelationMode` in `pageData.relationManagerData` (and at registration time in `routes.ts`). `belongsToMany` flips into pivot-mutation mode; `morphMany` / `morphOne` collapse into `'morphMany'` (parent-side polymorphic — auto-fills `<morphName>Id` + `<morphName>Type` on create + edit); `morphTo` is the child-side polymorphic (no auto-actions, no auto-discovery — set `static relatedResource` explicitly); everything else collapses to `'hasMany'`. Overrides may drop the trailing `ctx` parameter (TS allows narrower override signatures). Form lifecycle hooks (`mutateDataBefore*`, `before/after*`, `save / handleCreate / handleUpdate`) — same shape as `Resource.form()`. Seven `can*` async predicates — `canViewAny / canView / canCreate / canEdit / canDelete / canAttach / canDetach`, defaults all return `true`; the page-data builder defers to the related Resource's matching predicate when the manager hasn't overridden (reference-equality check on the prototype). **`canAttach / canDetach` are manager-only** — they don't fall through to the related Resource because attach/detach are pivot operations, not record operations. `safeManagerPolicy(M, method, Related, user, parent, child?)` — lives in RelationManager.ts so `Action.ts` can reuse it cycle-free; pageData re-exports for back-compat. Reserved relationship tokens (`edit / delete / restore / force-delete / _form / _action / _search / _uploads / _attach / _detach / _bulk-detach`) validated at panel boot. `src/schema/RelationTabs.ts` — schema element built by `buildRelationTabs(R, recordId, base, activeKey, user, parentRecord)`; auto-mounted on EditPage / ViewPage when `R.relations().length > 0` OR `R.getRecordPages()` is non-empty, plus on the three relation page roles for parent-context continuity. **Record sub-pages (2026-05-11):** `Resource.pages()` returns may include a `record: Record<string, typeof Page>` map for custom sub-pages mounted at `${resourceBase}/:id/${subPageSlug}`. Tabs surface in the strip between `__edit` and the manager tabs, in declaration order; gate on `await SubPage.canAccess(user, parentRecord)` (predicate widened with optional record arg — back-compat with existing `canAccess(user)` signatures). Boot validation rejects sub-page slugs that collide with reserved tokens, relation-manager `relationship` slugs, or fail the `[A-Za-z0-9_-]+` pattern. `PageMode` widened with `'record'`. Page data builder `resourceRecordPageData(pilotiq, slug, recordId, subPageSlug, req)` mirrors `resourceViewData`'s shape and runs `R.canAccess + R.canView + SubPage.canAccess` before resolving the sub-page's schema. The route + Vike dispatch share the relation-list URL slot (`${slug}/:id/${rel-or-subSlug}`); `dispatchPageData` tries the relation-manager lookup first, falls through to `resourceRecordPageData` when no manager matches. Plan + guide: `docs/plans/resource-record-sub-pages.md`, `docs/guide/record-sub-pages.md`. **Sub-nav follow-up (2026-05-03 cont'd):** the strip emits `[__view, __edit, …managers]` — both record-mode tabs are siblings rather than one-or-the-other. Each `__view` / `__edit` tab is gated on the corresponding page role being registered in `R.resolvePages()` (defaults ship both, but a `static pages()` override that drops one suppresses the matching tab so it can't 404). `activeKey` (`'__view'` / `'__edit'` / a manager's relationship key) selects the highlighted tab; `mode` parameter dropped — same fn produces every page's strip from a single shape. **Per-tab canX gating (2026-05-11):** the strip also evaluates the matching predicate per tab and drops entries the user can't reach — `__view` runs `R.canView(user, parentRecord)`, `__edit` runs `R.canEdit(user, parentRecord)`, each manager runs `safeManagerPolicy(M, 'canViewAny', Related, user, parentRecord)`. Predicates throwing fail closed (tab hidden); record-aware predicates skip when `parentRecord` is undefined (record-load failure surfaces a 404/403 on the route, so the strip stays consistent). After gating the strip may collapse to zero entries — `buildRelationTabs` then returns `undefined` (consistent with the no-managers branch). `buildNestedRelationTabs(R, M, base, step0, child1Id, activeKey, user, child1Record)` mirrors the same shape for the depth-2 strip; sibling nested manager tabs gate on `safeManagerPolicy(N, 'canViewAny', Related, user, child1Record)`; the back-link `__view` stays unconditional (user already passed `M.canViewAny` to reach the page). Routes still enforce in front of the data builder — this is presentation polish, not security.
-- `src/orm/modelDefaults.ts` — `ModelLike / ModelQuery` structural interfaces + `modelSave / modelLoadRecord / modelTableRecords` helpers. `defaultPages(R)` installs them as Form/Table sentinels when `R.model` is set. Pilotiq has zero runtime dep on `@rudderjs/orm`. Plan #11 additions: `ModelLike.relatedQuery?(parent, name)` optional override; default reads `parent.related(name)` (rudder ORM convention). `defaultRelatedQuery / resolveRelatedQuery / modelRelationTableRecords` helpers feed `Table.records()` for managers.
-- `src/Cluster.ts` — Filament-style structural cluster (Tier-3, 2026-05-05 cont'd¹⁴). `static label / slug / icon / navigationGroup / navigationSort / navigationLabel / navigationIcon / navigationBadge / navigationBadgeColor / navigationParentItem / canAccess(user) / landingPage`. Resources / Globals / Pages opt in via `static cluster = MyCluster`; URLs gain `${base}/${cluster.slug}/${child.slug}/...` prefix and the child nests under the cluster's nav entry. Boot validates dup slugs, reserved tokens (`_*`, `theme`, `api`), dangling references, top-level slug collisions, and landing-page sanity (must be in `pages()` AND back-reference the cluster). Cluster URL = first accessible child or `landingPage` URL when set. `Cluster.canAccess(user)` AND'd with child predicates — both must pass; failing cluster gate drops every child from nav AND 403s every cluster-prefixed route. Helpers `clusterPaths.ts` exports `resourceBasePath / globalBasePath / pageBasePath / clusterBasePath` used everywhere URLs are built (`routes.ts`, `pageData.ts`, `Resource.getGlobalSearchResultUrl`, `Action` factories via structural `ResourceLike.cluster`). Vite plugin emits `clusterSlugsByBasePath` map alongside `componentRegistry` in `_components.ts`; auto-gen route stubs detect cluster prefix via `clusterOffset(parts)` and shift their part-index reads accordingly so SPA nav works on both shapes. v1 limits: no nested clusters, no aggregated badges, no cluster-internal sidebar. Plan + guide: `docs/plans/clusters.md`, `docs/guide/clusters.md`.
-- `src/Resource.ts` — abstract class with **static** methods `label / labelSingular / slug / icon / model / form / table / detail / deleteRecord / pages / resolvePages / relations / getSlug`. Resources register as classes. `model?: ModelLike` opts into auto-wired CRUD. **Nav metadata (Plan #9):** `navigationGroup / navigationSort / navigationLabel / navigationIcon / navigationBadge / navigationBadgeColor / navigationParentItem` (parent ref by JS class name, not slug). Plus `recordTitleAttribute`. **Breadcrumb override (2026-05-06 cont'd⁴):** `breadcrumb?: string` static + `getBreadcrumb()` accessor — falls through to `label` when unset. Reads through every Phase C breadcrumb path (resource list/create/view/edit + the relation prefix used by depth-1 + depth-2 chains). Pair with a longer `label` when the sidebar / page-title plural reads better long ('Blog Posts') but the breadcrumb chain reads tighter short ('Posts'). **Authorization (Plan #10):** six async predicates default `true` — `canAccess / canViewAny / canView / canCreate / canEdit / canDelete`. Throwing → fail closed. Opaque user. **Global search (Plan #12):** `globalSearch` toggle (default `false` — opt-in), `globallySearchableAttributes()` defaults to `recordTitleAttribute` + every `Column.searchable()` from the configured table, `getGlobalSearchResultTitle / Subtitle / Url(record, base)` with sensible defaults (record[recordTitleAttribute] → name → title → id; URL = `${base}/${slug}/${id}`), `getGlobalSearchQuery(needle)` override returns a `ModelQuery` for joined / FTS / non-LIKE backends. **Plan #15 widgets:** `static headerSchema(ctx?) / footerSchema(ctx?)` return widget elements rendered above / below the resource list table; resource-scope widget endpoint `POST {base}/{slug}/_widget/:id` runs `canAccess + canViewAny` in front of widget visibility check. **Filter persistence (Tier-3, 2026-05-05 cont'd¹¹):** `persistFiltersInSession = false` opt-in flag — when true, the GET list handler stashes the URL filter slice (filters / `group` / `search` / `sort` / `perPage`; `page` + `tab` excluded) on `req.session` and 302-redirects bare visits back to the last-applied state. No-ops without `@rudderjs/session`. Helpers in `src/sessionFilters.ts`; guide `docs/guide/filter-persistence.md`. **Defer loading (Tier-3, 2026-05-05 cont'd¹²):** `deferLoading = false` opt-in flag — when true, the SSR pass on the list page calls `tagTableDeferred(elements, '${indexUrl}/_table')` BEFORE `loadTableRecords`, marking every Table on the page as deferred and stamping a `tableUrl`. `loadTableRecords` short-circuits the records handler when `Table.isDeferred()` returns true (URL chrome state — current sort / search / page — still mirrors). The renderer's `<TableRenderer>` shell handles the deferred branch: paints `<TableSkeleton>` on first frame, fetches `tableUrl + window.location.search` after mount with `Accept: application/json`, replaces the skeleton with the response's `tables[0]` meta. New route `GET {base}/{slug}/_table` (registered only when `R.deferLoading=true`) calls `resourceTableData()` which re-runs the same data builder WITHOUT the deferred flag — records load, per-row stamping runs, summaries compute, and `collectTableMetas(schemaData)` returns every `type:'table'` meta as a flat array. SPA nav re-runs SSR → re-paints skeleton → re-fetches; every nav pays one skeleton frame. Composes with `persistFiltersInSession` (bare-visit 302 redirect happens BEFORE the deferred-load decision). Guide `docs/guide/defer-loading.md`. **Soft deletes (Plan #13):** `softDeletes = false` opt-in flag + `deletedAtColumn = 'deletedAt'` column-name override. Two new async predicates: `canRestore(user, record)` (default `true`) and `canForceDelete(user, record)` (default delegates to `canDelete` via `this.canDelete(user, record)` for fail-closed inheritance). Both flags must opt in (rudder side `Model.softDeletes = true` AND pilotiq `Resource.softDeletes = true`); routes throw a clear boot error when only one side is set or when `model.restore / forceDelete` are missing. Wires up: `TrashedFilter` auto-injection on the list page; `Action.restore / forceDelete / bulkRestore / bulkForceDelete` factories; "moved to trash" framing on the standard delete success notification; auto-visibility on `Action.delete` (hides on already-trashed rows) / `Action.restore` + `forceDelete` (show only on trashed rows). Two new routes per soft-delete resource: `POST /:slug/:id/restore` and `POST /:slug/:id/force-delete` (both look up records via `query.withTrashed()` to bypass default scope).
-- `src/Global.ts` — singleton resource. Same shape as `Resource` minus list/create/delete. `navigationGroup` defaults to `'Settings'`. Authorization subset: `canAccess / canView / canEdit`.
-- `src/Page.ts` — page class: `static slug/label/icon`, `static schema(ctx)`, `static getResource()`, `static getMode() → 'list'|'create'|'edit'|'view'|'custom'`. Carries nav metadata. Single `canAccess(user)` gate.
-- `src/defaultPages.ts` — Four base classes `ListPage / CreatePage / EditPage / ViewPage`. Subclass via `static override getResource()`. Factories `defaultListPage(R) / defaultPages(R)`. **Filament-style explicit actions:** `getHeaderActions / getRowActions / getActions` return `[]` by default; users opt in via override or `Resource.table().headerActions(...) / .recordActions(...) / .bulkActions(...) / .actions(...)`. Slots accept `Array<Action | ActionGroup>`. Pre-built factories `Action.create / .edit / .view / .delete / .replicate(R, base, recordId?)` plus `Action.bulkReplicate(R, base, opts?)`. `Action.replicate` is handler-style — clones the source row via `R.model.create(...)` (strips PK + soft-delete column + `opts.excludeAttributes`, optional `opts.beforeReplicaSaved` mutator), redirects to the new record's edit page; visibility delegates to `R.canCreate`. `Action.bulkReplicate` iterates `ctx.records`, applies the same strip + mutate + create pipeline per row, skips rows that throw or fail per-row `canCreate`, notifies with the count. **`Action.relationReplicate(M, ctx, recordId?, opts?) / Action.relationBulkReplicate(M, ctx, opts?)` (2026-05-05)** — relation-manager siblings. Operate on `Related.model` instead of `R.model`; **force-pin** the parent attachment back onto the replica (hasMany → `[foreignKey]: ctx.parentId` from the parent's `static relations[name]` descriptor; morphMany → `<morphName>Id`/`<morphName>Type` via `computeMorphPayload(ctx.parentRecord)`) so a tampered source row can't slip a different parent in by riding its own FK column. Auto-hide on M2M (`belongsToMany / morphToMany / morphedByMany` — replicate doesn't fit pivot semantics) and on `morphTo` (no single owner to pin to). Visibility delegates to `safeManagerPolicy(M, 'canCreate', Related, user, parentRecord)`; bulk variant runs the same gate per-row inside the loop. **`opts.getCreatedNotificationTitle / opts.getRedirectUrl` (2026-05-05 cont'd):** all four replicate factories accept these overrides on `ReplicateOptions`. Single-row factories (`replicate / relationReplicate`) pass `{ replica, source }` to both callbacks; bulk factories (`bulkReplicate / relationBulkReplicate`) pass `{ count, records }` to the title callback (no redirect on bulk — they stay on the list / manager URL). Both callbacks may be sync or async; returning `undefined` falls back to the default copy / URL. Empty string is honored explicitly (not swallowed by `??`). **Plan #10 auto-visibility:** factories auto-attach a `.visible(...)` rule consulting matching policy. `CreatePage / EditPage` expose form lifecycle as optional static fields (`beforeCreate, afterUpdate, handleCreate/Update, mutateFormData*, mutateData*, getRedirectUrl, getCreatedNotificationTitle, getSavedNotificationTitle`); `installLifecycleHooks` wires them on. **List-page tabs:** `ListPage.getTabs() → ListTab[]` wraps in a `ListTabs` container. **Create & create another (2026-05-03):** `CreatePage.getFormActions(R)` ships TWO submits by default — primary `submit` ("Create ${labelSingular}") + secondary outlined `createAnother` ("Create & create another") posting `_continueCreate=1` via `Action.formField()`. The create POST handler routes the redirect back to `/create` (winning over `redirectAfterSave`) and emits `force: true` in the JSON response so the SPA's `FormRenderer` navigates even though the redirect URL matches the current page (the existing same-URL skip would otherwise preserve the just-submitted values on screen). Drop the second button by overriding `getFormActions(R)` to return only the primary submit. **Wizard mode (2026-05-04 cont'd, Filament `HasWizard` equivalent):** `CreatePage.getSteps(R) → Step[]` opt-in (default `[]`); when non-empty, `schema()` builds the form via `R.form()` (lifecycle preserved) then calls `form.schema([this.getWizard(Wizard.make().steps(steps), R)])` to swap the form's children with a Wizard wrapping the steps. Author the wizard's fields directly inside `Step.make(label).schema([…])` — `Resource.form().schema()` children are *replaced*. `getWizard(wizard, R)` chrome customizer for `.skippable() / .startOnStep(n) / .persist(false)` (default returns the wizard untouched). Per-step validation reuses Plan #8's `tagFormWizardUrls / formWizardData` pipeline unchanged (Wizard descendant gets detected, `wizardUrl` stamped, `findWizardStepFields` walks the new tree). EditPage wizard mode deferred.
-- `src/Tab.ts` + `src/elements/ListTabs.ts` — `ListTab.make(name).label().icon().badge(s|fn).badgeColor().default().modifyQuery(fn).modifyContext(fn)`. Distinct from the form-side `Tab` (under `Tabs.make()`).
-- `src/defaultGlobalPages.ts` — same factory pattern for `Global`; default returns `{ edit }`.
-- `src/Column.ts` — `Column.make(name).label().sortable().searchable()`. Cosmetic builders + built-in formatters (`.dateTime, .since, .money, .numeric, .limit, .words, .characters` (alias for `.limit`)). Server-side `.formatStateUsing((value, record) => string)` stashes per-row results on `row._formatted[name]`. **Footer summaries:** `.summarize([Sum/Average/Count/Range])` — `loadTableRecords` computes aggregates over the rendered rows and stamps `TableMeta.summaries[colName]` (`SummaryResult[]`); per-page only in v1. **Rich-display chrome (Filament-parity Tier-2, 2026-05-07 cont'd¹²):** `.listWithLineBreaks() / .bulleted() / .copyMessage(message?) / .markdown() / .html()` plus `sanitize / allowRaw` for the rich-text pair. `listWithLineBreaks` and `bulleted` apply only to array values (bulleted wins when both are set). `copyMessage` mounts a `CellCopyButton` after the cell value (the message doubles as the toast text; default `'Copied!'`). `markdown / html` are mutually exclusive and stamp `richText: 'markdown' | 'html'` onto the meta — `dispatchTable` server-renders matching cells through `marked` (markdown) or passthrough (html), runs the result through `sanitize-html` against `DEFAULT_SANITIZE_CONFIG` (or the user's widened config / `allowRaw`), and stamps `row._formatted[col.name]` + `row._richtextCells[col.name] = true` so the renderer mounts the existing prose-sm `dangerouslySetInnerHTML` path. `formatStateUsing` always wins over `markdown/html` (declared first by the user — assumed deliberate); the auto-richtext (Tiptap) walker filter excludes `isRichText()` columns so they don't double-render.
-- `src/summarizers/` — `Summarizer` base + `Sum / Average / Count / Range` subclasses. Each has `.label(text)` (rendered before the value) and `.format((n) => string)` for currency/locale formatting (Count ignores format). `compute(values)` filters out null/undefined/empty/NaN before aggregating — `Number(null)` returning 0 would otherwise pollute averages and ranges.
-- **`Column.toggleable(opts?)` (2026-05-10 cont'd⁸):** opt-in user-visibility chrome. Bare `toggleable()` lets the user hide the column from the toolbar's "Columns" dropdown; `toggleable({ initiallyHidden: true })` starts off-screen. State persists to `pilotiq.table.<currentPath>.columns.<col>` localStorage ('1' hidden / '0' visible / null falls back to `initiallyHidden`). Renderer adds a `<ColumnsToggleDropdown>` toolbar trigger next to FilterPopover / SortByPicker; uses `closeOnClick={false}` so users can toggle multiple columns without re-opening. `visibleColumns = columns.filter(c => !hiddenColumns.has(c.name))` replaces `columns` in the TableHead loop, body cells loop, per-group + footer summaries, and the empty-state colSpan. Hidden state is presentational only — data still loads server-side so sort/filter/group on a hidden column keeps working. Sparse meta — `toggleable` key absent unless the column opts in.
-- `src/columns/` — `TextColumn / BadgeColumn / IconColumn / BooleanColumn / ImageColumn / TextInputColumn / ToggleColumn / SelectColumn`. Each sets `columnType` via `setColumnType()`; renderer branches on it. `TextColumn.make(name)` is the explicit text-cell factory; `Column.make(name)` is an alias kept for back-compat — both produce identical wire shape (`columnType` defaults to `'text'`, omitted from meta). **Editable cell columns (2026-05-03):** `TextInputColumn / ToggleColumn / SelectColumn` flip `Column.isEditable() === true`; per-row `R.canEdit(user, row)` gate runs in `loadTableRecords` (via the new `LoadTableHooks.canEdit` callback threaded from `resourceIndexData`); successful gates stamp `_cellEditable[col]: true` + `_cellDisabled[col]: true` on the row, and `pageData.tagCellEditUrls(elements, indexUrl)` walks them after to add `_cellEditUrls[col]` (parallel to `tagFormStateUrls / tagTableReorderUrls`). PATCH route at `POST {base}/{slug}/:id/_cell/:column` body `{ value }`; coerce + validate + `R.model.update(id, { [col]: value })`. Boot guard requires `R.model.update` whenever an editable column is present. Renderer in `react/cells/EditableCell.tsx` (`CellTextInput / CellToggle / CellSelect` + `pickEditableCell()`) — debounced (500 ms default) for TextInput, immediate for Toggle / Select; optimistic local state + rollback on failure with error toast; `data-no-row-nav` so cell controls don't trigger row click; opt-in `.confirm(message)` gates the PATCH behind a Dialog. **`SelectColumn.options(record => …)` per-row resolver (2026-05-10 cont'd⁵):** function form receives the raw record and may return a Promise; runs in parallel with sibling resolvers inside the per-row `if (allowed)` block in `dispatchTable.ts` (gated behind canEdit so hidden cells don't pay the resolver cost). Stamps `row._cellSelectOptions[col.name]: ColumnSelectOption[]`; renderer's `<CellSelect>` reads `props.rowOptions` first, falls back to `col.selectOptions`. Resolver-only columns omit `selectOptions` from meta (per-row stamp wins); throwing resolver leaves the slot unset on that row only — others still stamp, and the cell falls back to whatever static `.options()` is set (or empty list) so one bad row doesn't break the whole table. Mixing static + resolver: re-calling `.options()` replaces the prior set in either direction.
-- `src/PilotiqRegistry.ts` — globalThis-backed singleton, `findByPath()` for route matching.
-- `src/sessionFilters.ts` — Tier-3 filter persistence helpers. `Resource.persistFiltersInSession = true` opts in; the GET list handler in `routes.ts` writes the active query slice (filters / `group` / `search` / `sort` / `perPage`; `page` + `tab` excluded) to `req.session` under `pilotiq:filters:<basePath>:<slug>` on every non-bare visit, and 302-redirects bare visits (zero query params) to the persisted slice. Duck-typed `req.session.get / put` (mirrors `notifications/flash.ts`) so it no-ops when `@rudderjs/session` isn't installed. Idempotent — short-circuits the `put()` when the slice deep-equals the stored value to avoid `Set-Cookie` churn on revisits. v1 = one slot per resource (all tabs share one filter slot); guide: `docs/guide/filter-persistence.md`.
-- `src/PilotiqServiceProvider.ts` — Provider + `pilotiq()` factory.
-- `src/search.ts` — Plan #12 `searchAllResources(pilotiq, query, user, opts?) → GlobalSearchResult[]`. Walks `cfg.resources` filtered by `globalSearch=true`, runs `canAccess + canViewAny` in parallel, builds a per-resource `ModelQuery` (override-or-default LIKE chain on `globallySearchableAttributes()`), `paginate(1, limitPerResource)`. Returns `[]` for queries shorter than 2 chars. Throws on a single resource silently drop its results; others still resolve. No new ORM contract — reuses the existing `paginate` from Plan #2/#6.
-- `src/pageData.ts` — Barrel module (~480 lines) + `dispatchPageData(pageContext)` Vike `+data` switchboard. Re-exports the per-page-role builders (`dashboardData`, `resourceIndexData`, `resourceCreateData`, `resourceEditData`, `resourceViewData`, `resourceRecordPageData`, `globalEditData`, `globalViewData`, `customPageData`, `formStateData`, `formWizardData`, `formCreateOptionData`, `mentionResolveData`, `widgetData`, `searchData`, `relationManagerData`, `panelInfo`, `applyRoleHooks`, `resolvePageHooks`) + the URL-tag helpers + the fill pipeline through the `./pageData.js` import path so external callers (`routes.ts`, tests, custom dispatchers) stay stable. **Plan #5 `formStateData(pilotiq, scope, body, req?)`** drives partial-resolve — runs `applyStateUpdate`, re-resolves form with bound read-only `$get` (resolve-time `$set` is a no-op closure; only `afterStateUpdated` writes survive), returns `{ ok, form: FormMeta, dirty }` or 404/422. **`tagFormStateUrls(elements, urlBuilder)`** stamps `Form.withStateUrl()` only on forms with at least one `live()` descendant. **Plan #8 `formWizardData(pilotiq, scope, body, req?)`** runs `validateSchema` over the requested step's children only — returns `{ ok }` (200) or `{ ok:false, status:422, errors }`. **`tagFormWizardUrls(elements, urlBuilder)`** stamps `Form.withWizardUrl()` only on forms with a `Wizard` descendant. **Navigation tree:** `panelInfo(pilotiq, req?)` is async — flattens resources/globals/pages, resolves `navigationParentItem` refs, sorts by `navigationSort`, parallel-resolves `navigationBadge()` via `Promise.all` (errors swallow). `buildNavigation` pre-evaluates `canAccess(user)` in parallel; failed items dropped. Both rudder GET handlers AND the auto-gen Vike `+data` hook call these so SSR + SPA-nav serve identical data; renderers read from `(ctx.data ?? ctx.viewProps)`. `resolveActiveTab(elements, query, currentPath)` stamps active tab + per-tab URL + parallel-resolved badge counts before `loadTableRecords`.
-- `src/pageData/` — Modular page-data subtree. Split out of `pageData.ts` in 6 phases (PR #34–#39, 4,948 → 481 lines):
-  - `breadcrumbs.ts` — 16 builder helpers (home / cluster / resource×4 / global / customPage / relation×4 + prefix / nestedRelation×4 + prefix) + `RelationChainStep` type.
-  - `helpers.ts` — `userCtx` / `uploadCtx` (`SchemaContext` builders), `callPageSchema`, 12 URL-tag helpers (`tagFormActions` / `tagFormStateUrls` / `tagTableReorderUrls` / `tagTableDeferred` / `tagCellEditUrls` / `tagFormWizardUrls` / `tagFieldAiUrls` / `tagSelectCreateOptionUrls` / `tagRichTextMentionUrls` / `tagWidgetUrls` / `tagActionDispatch`), the fill pipeline (`applyFillPipeline` + `applyRelationshipRepeaterFill` + `applyRelationshipBuilderFill` + `pickChildPrimaryKey` / `pickChildForeignKey` / `findRelationshipRepeaters` / `findRelationshipBuilders` / `parseBuilderDataPayload`), `resolveServerDataElements` + `collectServerDataElements` + `ServerDataMap`, and field-walker helpers (`walkSelectFields` / `isAsyncMentionField` / `formHasLiveField` / `formHasWizard`).
-  - `navigation.ts` — `panelInfo` (entry point for chrome envelopes), the meta interfaces (`UserMenuMeta` / `DatabaseNotificationsMeta` / `RightPanelMeta` / `RightSidebarMeta` / `NavItem` / `PanelInfoRoute`), `buildNavigation` + `nestAndSort` + `RawNavItem`, the render-hook resolvers (`resolveChromeHooks` / `applyRoleHooks` / `resolvePageHooks`), and the user-menu / sidebar / notification-meta builders.
-  - `resourcePages.ts` — `dashboardData`, `resourceIndexData`, `resourceTableData`, `collectTableMetas`, `resolveActiveTab` + `findListTabs` + `buildTabUrl`, `resourceCreateData`, `resourceEditData`, `resourceViewData`, `resourceRecordPageData`.
-  - `relationPages.ts` — Plan #11 relation manager builders. Types (`RelationManagerScope` / `RelationManagerResult` / `ResolvedChain`), lookup helpers (`findRelatedResource` / `findManager` / `childBelongsToParent` for IDOR), auto-wiring (`autoWireManagerTable` / `injectManagerTrashedFilter` / `autoWireManagerForm` / `safePolicy` / `safeManagerPolicy`), depth-1 builders (`relationManagerData` + `buildRelation*Data`), depth-2 chain resolution + builders (`resolveRelationChain` + `nestedRelationManagerData` + `nestedManagerCtx` + `nestedResponseEnvelope` + `buildNestedRelation*Data`).
-  - `relationTabs.ts` — `buildRelationTabs` (depth 1) + `buildNestedRelationTabs` (depth 2) + `deriveParentTitle` + `safeBool`. Lives in its own module because both `resourcePages.ts` (parent record view/edit strip) AND `relationPages.ts` (nested-tab strip on record manager pages) consume them — keeps the resource ↔ relation sibling import graph acyclic.
-  - `forms.ts` — Plan #5 `formStateData`, Plan #8 `formWizardData`, `formCreateOptionData` (SelectField inline-create), `mentionResolveData` (async-mention typeahead), plus per-builder helpers (`stepHookErrorMessage` / `findSelectFieldByName` / `isMentionResolverField` / `findRichTextFieldByName` / `stripRepeaterRowPrefix` / `stripBuilderRowPrefix`) and 9 wire-shape types.
-  - `misc.ts` — `globalEditData`, `globalViewData`, `customPageData`, `widgetData` (Plan #15 widget polling) + `findWidgetById`, `searchData` (Plan #12 global search), plus the `WidgetScope` / `WidgetRequest` / `WidgetSuccess` / `WidgetFailure` wire-shape types.
-- `src/routes.ts` — `registerPilotiqRoutes()` using `view()`. Each GET handler delegates to `pageData.ts`; POST handlers stay here. **Plan #10 wiring:** every handler runs `checkPolicy(() => R.canX(user, …))`; failure → `forbidden(res, json)` (403 JSON or HTML). Record-aware predicates load via `R.model.find(id)` when set. 403 ≠ 401 — `Pilotiq.guard()` is the 401 layer. Routes:
-  - `GET ${base}` → dashboard
-  - `GET ${base}/${slug}` → resource list
-  - `GET/POST ${base}/${slug}/create` → create
-  - `GET ${base}/${slug}/:id` → view
-  - `GET/POST ${base}/${slug}/:id/edit` → edit
-  - `POST ${base}/${slug}/:id/delete` → delete
-  - `POST ${base}/${slug}/_action/:actionName` → resource action dispatch
-  - `POST ${base}/${pageSlug}/_action/:actionName` → custom-page action dispatch
-  - `GET/POST ${base}/${slug}` (Global) → singleton edit
-  - `GET ${base}/${pageSlug}` → custom page
-  - **Plan #5 partial-resolve endpoints** — `POST {…}/_form/:formId/state` (resource-create / resource-edit / global-edit / custom-page). Body `{ changed, values }`; `handleFormState(req, res, pilotiq, scope, formId)` shared helper.
-  - **Plan #8 wizard step-validate endpoints** — `POST {…}/_form/:formId/wizard` (same four scopes). Body `{ step, values }`; `handleFormWizard` shared helper. 200 → advance; 422 → `{ errors }` for inline display; 404 → step out of range or no Wizard on form. Reuses the same policy prelude as the form-state endpoint.
-  - **Plan #11 relation manager routes** — six handlers per registered `(Resource, RelationManager)` pair. `GET ${base}/${slug}/:id/${rel}` (list), `GET/POST ${base}/${slug}/:id/${rel}/create` (create), `GET/POST ${base}/${slug}/:id/${rel}/:childId/edit` (edit), `POST ${base}/${slug}/:id/${rel}/:childId/delete` (delete). Two-layer auth (parent `canAccess + canEdit`, then manager-scope `canX` with fall-through to related Resource). IDOR check (`childBelongsToParent`) re-runs the relation query before edit/delete. `FormContext` stamped with `parent / parentId / parentRecord / relationship`. Reserved-token guard at panel boot.
-  - **Polymorphic follow-up — morph-column auto-injection (2026-05-03):** when `mode === 'morphMany'`, the `relation-create` and `relation-edit` POST handlers compose a `mutateDataBeforeCreate` / `mutateDataBeforeUpdate` on the manager form that runs AFTER any user-supplied hook and spreads `computeMorphPayload(parent, descriptor)` into the data — `<morphName>Id` ← `parent[primaryKey]`, `<morphName>Type` ← `parent.constructor.morphAlias ?? parent.constructor.name`. Framework wins last so a tampered POST body (`commentableId=v1&commentableType=Video`) cannot reassign a child to a different polymorphic parent. Helpers `getMorphRelationDescriptor` + `computeMorphPayload` in `orm/modelDefaults.ts`. `morphTo` recognized in the union but no auto-actions inject (target class is dynamic — set `static relatedResource`). Playground demo: `Comment.commentable: morphTo([Post, Video])` + `Post.comments / Video.comments: morphMany`; `PostsCommentsManager` and `VideosCommentsManager` share the same `CommentResource`. Plan: `docs/plans/relations-polymorphic.md`.
-  - **M2M follow-up — manager-scoped action + detach routes (2026-05-03):** two extra handlers per relation manager. `POST ${base}/${slug}/:id/${rel}/_action/:actionName` — manager-scoped action dispatch; loads parent, runs `canAccess + canEdit`, rebuilds the manager's table via `M.table(Table.make(), managerCtx)` (same context as the data builder so factories see the same shape), finds the named action via `resolveDispatchTarget`, and calls `dispatchAction` with `relation: { parent, parentId, relationship }` stamped onto `DispatchActionInput` so M2M handlers (`relationAttach / relationBulkDetach`) can call `parent.related(rel).attach / detach` without re-loading the parent. Records hydrate against the related Resource's model. `POST ${base}/${slug}/:id/${rel}/:childId/_detach` — direct row-detach for `Action.relationDetach`; M2M-only (404s with a clear message when `mode !== 'belongsToMany'`); IDOR check runs `where(pk, '=', childId).paginate(1, 1)` against the parent's relation accessor before calling `.detach([id])`. Both routes mounted unconditionally — handler-style actions are useful on hasMany too. The M2M action factories live alongside the relation factories: `Action.relationAttach(M, ctx)` (header, modal-form with a `SelectField` populated by `attachFactory.loadAttachableCandidates(parent, rel, relatedModel, recordTitleAttr, limit?)`); `Action.relationDetach(M, ctx)` (row, direct POST to `_detach`); `Action.relationBulkDetach(M, ctx)` (bulk handler that iterates `ctx.records`, applies `M.canDetach` per row, then calls `parent.related(rel).detach(ids)` once). All three auto-hide when `ctx.mode !== 'belongsToMany'`. The standard `relationCreate / relationEdit / relationDelete` factories also auto-hide under M2M (no per-pivot create/edit/delete surface). `attachFactory.ts` lives next to `importFactory.ts / exportFactory.ts` for the same cycle-cleanliness reasons. `ActionContext.relation = { parent, parentId, relationship }` and `DispatchActionInput.relation` carry the request-time parent record from the route into the handler. v1 limitations: no pivot-extras editing (ORM doesn't surface pivot reads), no reorderable pivots (no ORM `orderByPivot`), no polymorphic M2M, no `syncWithoutDetaching` / `toggle` factories. Plan: `docs/plans/relations-m2m.md`.
-  - **Plan #12 global search** — `GET ${base}/_search?q=…` returns `{ ok, results: GlobalSearchResult[] }`. Panel-level (one route per panel, not per-resource). Per-resource filtering happens inside `searchData`. No 403 on the route — empty results when nothing's accessible. Query length capped at 200 chars; min 2 to fetch; results capped at 25 total / 5 per resource by default.
-- `src/vite.ts` — `pilotiq()` Vite plugin: generates `(pilotiq)/` pages + `+Layout.tsx` + `+Head.tsx`. Reads `app/Pilotiq/AdminPanel.ts` (override via `pilotiq({ panels })`) using **jiti**. Emits `pages/(pilotiq)/_components.ts` — manifest with `componentRegistry: { ClassName: ClassRef }` so component-typed icons resolve at render. Re-runs in `configureServer` on panel changes. Panel files must be import-safe.
-- `src/icons/` — User-extensible icon registry. `registerIcons({ name: Component })` + `getIcon(name)`. Icon static fields accept string (registry key) or component (lucide / tabler / heroicons / phosphor). `panelInfo()`'s `serializeIcon(value, ownerClassName)` ships strings as-is and components as `{ class: ownerClassName }`. `useIconFor()` resolves at render. `@pilotiq/pilotiq/icons/lucide` exports a baseline. Component detection accepts `function` and `object` (forwardRef / memo).
-- `src/schema/` — Unified `Element` model:
-  - `Element.ts` — abstract base. Contract: `getType(), toMeta()`, optional `_children: Element[]`. **Plan #8 layout-level state:** `visible(rule) / hidden(rule)` accept `boolean | (ctx: LayoutContext) => bool | Promise<bool>` — resolver drops hidden non-Field/non-Action layouts. `columnSpan(n) / columnStart(n) / columnOrder(n)` emit under `meta._layout` and map to Tailwind `col-span-* / col-start-* / order-*` (1..12 clamp).
-  - **Display:** `Text, Heading, Alert, Divider, Image, Icon, Markdown, Html, UnorderedList`. **`UnorderedList` (2026-05-04 cont'd):** `UnorderedList.make(items?: string[]).items([…]).color(TextColor).size(TextSize).weight(TextWeight)` — bullet list display prime; reuses the `Text` class maps so styling matches neighbouring text in a detail view. **Text formatting (2026-05-03 cont'd):** `.color('default'|'muted'|'primary'|…) / .size('xs'|'sm'|'base'|'lg'|'xl') / .weight('normal'|'medium'|'semibold'|'bold') / .badge(v=true) / .badgeColor(BadgeColor)` — pill rendering reuses `BADGE_COLOR_CLASSES`; bare `Text.make()` keeps the prior `text-sm text-muted-foreground` defaults. **Image:** `Image.make(url).alt(t).width(n).height(n).size(n).rounded()|.circle()`. **Icon:** `Icon.make(registryName).size(px).color(IconColor).label(t)` — string-only (registry-resolved); for component-typed icons used by Resource/Page/Global statics see `IconValue`. **Markdown / Html (2026-05-03 cont'd):** read-only display primes (the `MarkdownField` / `RichTextField` editor counterparts). `Markdown.make(source).gfm(b=true).breaks(b=false).prose(b=true).size('sm'|'base'|'lg')` server-renders the source via `marked` so initial paint shows formatted HTML with no parser shipped to display-only pages. `Html.make(html).prose().size()` passes raw strings through (use for legacy CMS columns or already-rendered fragments). Both wrap in a `prose max-w-none` container with optional `prose-sm` / `prose-lg` modifier when `prose=true` (default). **Sanitized by default (2026-05-07 cont'd⁷)** via `sanitize-html` against `DEFAULT_SANITIZE_CONFIG` (`schema/sanitize.ts`); strips `<script>` / `<iframe>` / `javascript:` / inline event handlers / `style=`. Three escape hatches on both primes: `.allowRaw()` (sugar) / `.sanitize(false)` (explicit) / `.sanitize({ allowedTags, allowedAttributes, allowedSchemes })` widening config. The renderer collapses both to a single `case 'markdown' | 'html'` branch in `renderElement` since shapes are identical (server-converted html string + prose flag). **Head-safe (2026-05-07 cont'd⁸):** `MetaTag.make({ name | property | httpEquiv | charset, content? }) / LinkTag.make({ rel, href?, mimeType? }) / ScriptTag.make({ src? | body?, async?, defer?, dataAttributes? }) / StyleTag.make(css, { nonce? })` — value-Element tags emitted ONLY by `panels::head.* / panels::scripts / panels::styles` render-hook callbacks. Body-level Elements inside head slots get skipped with a console warning. `mimeType` on Link/Script renames the HTML `type=` attribute (which collides with the wire-shape discriminator); renderer maps back. Mounted via `<HeadHooks position="start"|"end">` from `@pilotiq/pilotiq/react` inside the auto-generated `+Head.tsx`. **Containers:** `Card, Section, Tabs/Tab, Grid, Group, Fieldset, Split, Wizard/Step` (Plan #8). **Section polish (Plan #8):** `icon(name) / badge(text) / aside(v=true) / compact(v=true) / persistCollapsed(key?)` (key auto-derived from page slug + title). `aside()` flips into right-rail when nested in `Split`. `persistCollapsed` writes `pilotiq.section.<key>` to localStorage on toggle. **`dense(v=true)` (2026-05-03)** — orthogonal to `compact()`: `compact` trims outer padding + heading size; `dense` trims the inner grid `gap` between children (gap-2 / 8px vs gap-4 / 16px). Compose both for a settings-page look. **`secondary(v=true) / afterHeader([Action…])` (2026-05-07 cont'd¹¹)** — Filament v5 chrome polish: `secondary` flips the surface to `bg-muted/40 border-muted` so the section recedes beneath a primary card; `afterHeader` mounts right-aligned `Action[]` buttons in the section header (resolved through the standard walker so `.visible() / .disabled()` rules evaluate the same way as anywhere else; v1 is `Action[]` only — Element-typed children would require a second resolver pass).
-  - `Wizard.ts` — `Wizard.make().steps([Step.make(label).icon(name).description(d).schema([…])]).skippable().startOnStep(n).persist(false)`. All steps' children resolve every cycle so cross-step `$get` works; client renderer hides inactive steps via `display:none` so controlled inputs survive transitions. Active step persists to `pilotiq.wizard.<formId>.step` localStorage key. Next button POSTs `{ step, values }` to `Form.wizardUrl` — 200 advances, 422 stamps inline errors, missing url advances immediately. **Wizard nav polish (2026-05-10):** `.persistStepInQueryString(key='step'|true|false)` mirrors the active step to the URL as `?<key>=N` (1-based) via `history.replaceState` (purely client-side state sync, no SSR re-fetch); URL wins over localStorage on initial mount so deep-linking works; multi-wizard pages need distinct keys to avoid collisions. `.submitAction(a => a.label('Create campaign')) / .nextAction(...) / .previousAction(...)` customize the chrome of the built-in nav buttons — the customizer receives a framework-built default `Action` (Submit / Next / Back) and returns a customized clone (or fresh `Action`); chrome (label/icon/color/size/outlined/iconOnly/tooltip/disabled rules) carries through to the rendered button while click behavior stays hardwired (advance / recede / submit-form). `submitAction` is the opt-in case: by default the wizard renders a hint pointing at the page-level Save; setting `submitAction` mounts a real `<button type="submit">` inside the wizard chrome on the final step (pair with `CreatePage.getFormActions(R) → []` to suppress the page-level Save when the wizard is the entire form). Resolved through `resolveSchema`'s `if (el instanceof Wizard)` branch so `.visible(false)` on a customizer cleanly drops the slot from meta (renderer falls back to default chrome).
-  - `Split.ts` — two-column layout. `.from('left' \| 'right').gap(n).schema([main, aside])`. Aside child detected via `Section.aside()` marker; falls back to second child. Renders `flex flex-col @md:flex-row` with `@container` query so nested Splits behave.
-  - `Fieldset.ts` — labeled border container. `.columns(1\|2\|3).schema([…])`. `<fieldset><legend>` semantics, lighter than Section.
-  - `Group.ts` — chrome-less container. Pass-through `<div>`. Useful for visibility gating without imposing border/heading.
-  - **Plan #15 widgets (2026-05-03):** `ServerDataElement` abstract base + `View / StatsOverview / Stat / TableWidget` (core) + `Chart` (in `@pilotiq/recharts`). `Stat.make(label).value().description().descriptionIcon(name, position?).icon().color().chart([sparkline]).url().openUrlInNewTab().extraAttributes()` — Stat is a fluent value object, NOT an Element (no place in tree; emitted by `StatsOverview.getStats`). `StatsOverview` extends ServerDataElement; subclass form `static columns / static async getStats(ctx)` or fluent `.columns(n).getStatsHandler(fn)`; resolved Stats serialized to `StatMeta[]` so renderer never touches the class. `View` extends ServerDataElement; `static componentName / static getData(ctx)` (or `.component(name).getDataHandler(fn)`); component lookup via `@pilotiq/pilotiq/widgets` runtime registry (`registerWidgetComponents({ Name: Component })`); core ships `react/widgets/ViewRenderer.tsx` that consumes `getWidgetComponent(meta.component)` and falls back to inline error panels for missing-component / missing-name / hook-error. `TableWidget` extends ServerDataElement; subclass form `static label / model / viewAllUrl / columns() / async query(q) / async records(ctx)`; fluent form `TableWidget.make(id).label().model(M).query(fn).records(fn).columns([…]).viewAllUrl(href)`; resolution falls through `instance.records → static records → instance model+query → static model+query → throws`; default query hook = `q => q.paginate(1, 5)`; per-row `formatStateUsing` runs in resolver and stamps `row._formatted[col]`; columns inline under `meta.columns` (NOT `meta.children`) so resolver doesn't double-walk; named distinct from `Table` (which drives Resource list pages). All four ship `lazy: true` default + `.poll(seconds)` setter + `serverData: true` sentinel + auto-stamped `id` (subclass class name fallback) — every widget element is one of: `case 'stats'/'tableWidget'/'view'` in `SchemaRenderer` OR dispatched through `getWidgetRenderer(type)` for adapter-package widgets.
-  - **`Pilotiq.dashboard(P)` sugar:** stores `cfg.dashboardPage`, auto-adds page to `cfg.pages` (no dupes), `dashboardData()` resolves P's schema instead of `cfg.schema`, `panelInfo()` collapses page nav URL to `${base}`, slug-route registration skips it. Convention: `static slug = ''` so the regular slug-route doesn't double-catch.
-  - **Resource header/footer schema:** `Resource.headerSchema(ctx?) / footerSchema(ctx?)` statics return `Element[]` (default `[]`). `ListPage.schema` is async; slots between `getHeader()` and `ListTabs+Table` (header) and after `Table` (footer). `resourceIndexData` calls `tagWidgetUrls + resolveServerDataElements` and stamps `_widgetData`. New `WidgetScope` variant `{ kind: 'resource'; slug }` + `POST {base}/{slug}/_widget/:id` route runs `R.canAccess + R.canViewAny` in front of widget visibility check.
-  - **`react/WidgetDataContext.tsx`:** `WidgetDataProvider` ferries `_widgetData` map into render tree. `useInitialWidgetData(id)` reads SSR slot; `useWidgetData(meta)` owns lifecycle — initial paint reads `_widgetData[id]`, lazy mount-fetch fires when `null + widgetUrl + !error`, polling setInterval pauses while tab hidden, latest-wins seq-tracking drops stale responses, error-sentinel `{ error: '…' }` round-trips through hooks failures. `tagWidgetUrls(elements, urlBuilder)` walker stamps `meta.widgetUrl` on every server-data element (panel-scope on dashboard, page-scope on custom pages, resource-scope on resource header/footer). Walker stops at `form/repeater/builder/table` containers — widgets-inside-arrays unsupported in v1.
-  - `resolveSchema()` — async recursive walker. `RenderContext { mode?, record?, basePath?, recordId?, values?, $get?, $set?, changed?, user? }`. **Plan #5:** when `values` is present, conditional callbacks and `SelectField.options(fn)` see `$get/$set`. **Plan #8:** layout elements (anything not Field/Action/ActionGroup) with a `visible(rule)` are evaluated against a `LayoutContext` (same shape as `ConditionContext`); throwing → fail-closed (hidden + warn). `Element.toMeta()` may return `Record | Promise<Record>`. After `toMeta()`, `meta._layout = { columnSpan?, columnStart?, columnOrder? }` is stamped when any positioning method was used.
-- `src/elements/` — first-class container Elements:
-  - `Form.ts` — `Form.make().schema([...])` + lifecycle setters (`validate, mutateData*, before*, save, handleCreate/Update, after*, redirectAfterSave, loadRecord, fillFromRecord, mutateFormData*, savedNotification, createdNotification, disableSavedNotification`). Render-time setters `withValues / withErrors / withStateUrl / withWizardUrl`. `toMeta()` emits `formId / method / action / values / errors / stateUrl / wizardUrl`. Auto-generated `formId`; multi-form pages discriminate via hidden `_formId` input.
-  - `Table.ts` — `Table.make().columns([...]).records(fn).defaultSort.paginate`. `records(ctx) → { rows, total }` or bare row array. Render setters `withRows / withSort / withSearch / withPage`. **Grouping (Tier-2 follow-up to Batch B, 2026-05-03):** `Table.defaultGroup(string | TableGroup)` widened — bare-column form still works (band rows by `column`), `TableGroup` form auto-registers in `groups([…])`. `Table.groups([TableGroup.make(col).label(text).collapsible().collapsed().getTitleFromRecordUsing(r=>str).getDescriptionFromRecordUsing(r=>str).date()])` — multi-option group selector. URL key `?group=col` selects the active option; `?group=` (empty) explicitly disables; absent falls back to `defaultGroup`. Reserved query keys: `search/sort/page/perPage/group`. `parseActiveGroup(query, table)` reconciles URL → active column. `dispatchTable.loadTableRecords` calls `withActiveGroup(col)` after reconciliation; `toMeta` then emits `defaultGroup` as the resolved active column (NOT the configured one). Per-row stamping: `_groupValue` (raw / `YYYY-MM-DD` for date), `_groupTitle?` (resolved title — user handler wins over `date()`'s default formatter), `_groupDescription?`. Throwing handlers fall silent. Renderer ships a `<TableGroupPicker>` Select dropdown above the table when 2+ groups (or 1 with rich metadata); collapsible heading rows show a chevron + per-group fold state persisted at `pilotiq.table.<currentPath>.groups.<column>.<value>`. **Per-group summarizers (2026-05-03 cont'd):** when an active group is set AND at least one column has `summarize([…])`, dispatcher also computes summaries within each group bucket and stamps `TableMeta.groupSummaries: Record<groupValue, Record<colName, SummaryResult[]>>`; renderer emits an inline summary row at the END of each group band, aligned to the global `<tfoot>` columns, suppressed when the group is collapsed. **Manual group ordering (2026-05-03 cont'd):** `TableGroup.orderUsing((a, b) => number)` overrides the default alphabetic comparator on group keys; sugar helper `orderByKeys([…])` exported alongside the class. `dispatchTable.sortRowsByGroupValue` accepts the comparator; empty-bucket-last + within-group stability stay structural (run before/after the user's comparator respectively). `scopeQueryByKey` (click-to-drill-in) still deferred — coupled enough to filter wiring to deserve its own pass. **`Table.queryStringIdentifier(id)` (Tier-3, 2026-05-05 cont'd¹³):** namespaces every URL key for one table under `${id}_<key>` so multiple tables on one page (custom-page case) don't fight over `?search=` / `?sort=` / etc. Server-side: `parseTableQuery / parseFilterValues / parseActiveGroup` accept an optional `prefix`; `loadTableRecords` reads each table's prefix from `Table.getQueryStringIdentifier()` and parses its slice independently. Renderer-side: `prefixK(prefix, key)` mirrors the join inline, threaded into `buildTableQuery`, the search input (`name="<id>_search"`), `FilterSelect / FilterMultiSelect / FilterDateRange / FilterForm / ActiveFiltersBar / FilterPopover / TableGroupPicker` (all accept `prefix`), the `urlGroup` reader, and a new `<SearchFormHiddenInputs prefix>` that mirrors current URL state into the native search form so a bare `<form method="get">` Enter-submit doesn't drop sort / filter selections (or other tables' params). `sessionFilters.ts` extends its excluded-page-key check to drop both bare `page` and any `<prefix>_page` so persistFiltersInSession composes; deferred `_table` JSON endpoint composes naturally (server reads each table's prefix). Empty / non-`[A-Za-z0-9_-]+` ids throw at config time. Guide: `docs/guide/query-string-identifier.md`. **`Table.filtersLayout(position)` (Filament v5 parity, 2026-05-06 cont'd⁸):** swaps the toolbar Filters popover for an inline strip in the matching slot. `'modal'` (default) preserves today's behaviour; `'above-content'` always-visible strip above the table; `'above-content-collapsible'` adds a toolbar toggle that flips a `pilotiq.table.<currentPath>.filters.open` localStorage slot (defaults open when the URL carries any filter value); `'below-content'` strip after pagination. Inline modes hide the active-filter pill row — every widget already shows its current value, and per-widget clear affordances stay. Sidebar positions (`BeforeContent` / `AfterContent`) reshape the page rather than the table chrome and are deferred until a consumer asks. Pure renderer change — no ORM contract changes, no URL-state changes.
-  - `TableGroup.ts` — value-object primitive owned by `Table.groups([…])`. Fluent setters: `label / collapsible / collapsed / getTitleFromRecordUsing / getDescriptionFromRecordUsing / date / orderUsing(comparator) / scopable(b=true) / scopeQueryByKey(fn) / getKeyFromRecordUsing(fn)`. Helpers `bucketDateValue(raw) → 'YYYY-MM-DD'`, `formatDateBucketTitle(raw) → 'May 4, 2026'`, and `orderByKeys([…]) → comparator` exported for downstream tests / custom formatters. **Click-to-drill (2026-05-11):** `.scopeQueryByKey((q, key) => q.where(col, '=', key))` opts heading text into a real `<a href>` that drills the table into one bucket — banding suppressed, "Drilled into <Label>: <Value>" chip mounts above the table with × to clear. `.scopeQueryByKey()` / `.getKeyFromRecordUsing()` both auto-arm `.scopable(true)`. URL state: dedicated `?<prefix>groupKey=<value>` (added to `RESERVED_QUERY_KEYS` so filter names can't collide); `?page` resets to 1 on drill-in; `<prefix>groupKey` excluded from `persistFiltersInSession` slice (drill-in is page-state, not filter-state). `dispatchTable.parseActiveGroupKey(query, table, activeCol, prefix?)` reconciles the URL value against the registered scopable group; threads through `ctx.groupScope: { group, key }` into the records handler so `modelTableRecords` + `modelRelationTableRecords` splice the scoper after filters/tab. Default scoper for `.date()` groups installs a whole-day range (`>=` `YYYY-MM-DD 00:00:00` + `<=` `YYYY-MM-DD 23:59:59`); plain groups default to exact-match. Per-group summaries suppressed in drilled-in render; global `tfoot` summary still computes over the visible bucket. Renderer's group heading becomes a `<GroupHeadingLink>` (SPA-nav via `useNavigate()`, cmd-click / right-click "open in new tab" works); collapsible chevron stays as a separate button so folding doesn't drill in. Plan + guide: `docs/plans/table-group-scope-query-by-key.md`, `docs/guide/grouping.md`.
-  - `dispatchForm.ts` — `dispatchFormSubmit(form, body, ctx)` runs full lifecycle. Form-level validator errors land under `_form` key. `findForms / selectForm` for multi-form. **Plan #5:** `applyStateUpdate(form, values, changed, ctx)` finds the changed field, coerces only that one, runs `afterStateUpdated`, returns `{ values, dirty }`. **Plan #8:** `findWizardStepFields(formChildren, stepIndex)` walks the form's tree, returns the children of the requested step (or `undefined` when no Wizard / step out of range).
-  - `dispatchTable.ts` — `parseTableQuery / loadTableRecords`. Walks tree, calls every `Table.records(ctx)` in parallel, mirrors state back.
-  - `dispatchAction.ts` — `findActions / parseActionBody / dispatchAction`. Routes auto-stamp `Action.dispatchUrl()`.
-- `src/fields/` — `Field` base + 20 subclasses (`TextField, EmailField, NumberField, SelectField, TextareaField, ToggleField, DateField, SlugField`, **Plan #6:** `HiddenField/Hidden, CheckboxField/Checkbox, RadioField/Radio, CheckboxListField/CheckboxList, SliderField/Slider, ColorPickerField/ColorPicker, DateTimePickerField/DateTimePicker, KeyValueField/KeyValue, FileUploadField/FileUpload`, **Plan #14:** `RepeaterField/Repeater`, **Tier-2 micro-plans (2026-05-04):** `ToggleButtonsField/ToggleButtons` — sugar over Radio with chip rendering; same `OptionsResolver` shape; no separate coerce branch (string passthrough). `TagsInputField/TagsInput` — free-text tag chips; `string[]` value; `.suggestions(string[]|resolver) / .separator(',') / .splitKeys(['Enter']) / .reorderable() / .maxTags(n)`; wire format = JSON-encoded array in a single hidden input; new `tagsInput` coerce branch parses back to `string[]`. **`reorderable()` (2026-05-03):** chips become draggable via native HTML5 drag-and-drop with a 2px vertical drop indicator and a grip-icon affordance; reuses `reorderRows` helper from `RepeaterInput`. Off by default — most tag sets are insertion-ordered or alphabetized. **`MarkdownField/Markdown` (2026-05-04 cont'd)** — plain-markdown editor; raw string value (same wire format as `TextareaField`, no new coerce branch); `.toolbarButtons([…]) / .disableToolbarButtons([…]) / .minHeight(css) / .maxHeight(css) / .fileAttachmentsDirectory(d) / .fileAttachmentsVisibility('public'\|'private')`. Default toolbar = 10 buttons (`bold/italic/strike/link/heading/bulletList/orderedList/blockquote/codeBlock/attachFiles`). Renderer ships a tab switcher (Write / Preview); preview HTML is rendered client-side via `marked` (`gfm: true, breaks: false`), no DOMPurify in v1 (admin-trusted authors). `attachFiles` reuses the existing `_uploads` route + `UploadAdapter`; the button is stripped server-side when no adapter is registered via the new `RenderContext.hasUploadAdapter` flag (see "RenderContext" note below). Paste-image splices `![alt](url)`; ⌘B/⌘I/⌘K shortcuts). Visibility flags + condition callbacks (`showWhen, hideWhen, disabledWhen`), validators via `.validate(v|v[])`. **Plan #5:** `Field.live(opts?: boolean | { onBlur?: boolean; debounce?: number })` marks re-resolve trigger; `Field.afterStateUpdated((value, ctx) => …)` server hook; `SelectField.options(fnOrArray)` async-aware; `FieldCondition` widened from `(record) => bool` to `(ctx: ConditionContext) => bool`. Conditions skip when both `record` and `values` are undefined. **`Field.afterStateUpdatedJs(body)` (2026-05-04 cont'd, Tier-2 follow-up):** client-only counterpart to `afterStateUpdated`. Body string compiled via `new Function` (CSP `unsafe-eval` required) with `$state / $get / $set` bound; cached by source-string identity in `react/fieldJsHandler.ts`; runs synchronously on every change (no `live()` required, no roundtrip). Compose with the server hook — JS runs first, server response (when `live()` is also set) overlays sibling values. Repeater/Builder rows: dotted-path `$get / $set` route through `readNestedValue / writeNestedValue` (snapshot-then-overlay so `$get(thisField)` matches `$state`). `tagFormStateUrls` stamps `stateUrl` for forms with EITHER `live()` OR `afterStateUpdatedJs` so the `FormStateProvider` mounts (the endpoint is unused for JS-only forms; client only POSTs on `live`). **Plan #6 cross-field plumbing on `Field`:** `prefix(string|{icon}) / suffix(...) / helperText(text) / inlineLabel(v=true) / default(value) / dehydrated(false) / formatStateUsing(fn)`. **`inlineLabel()` (2026-05-04 cont'd)** mirrors the `Entry.inlineLabel` shipped with Plan #16 — `FieldShell` swaps to a `flex items-baseline gap-3` row with a `min-w-32` label column (default label-above unchanged); helperText still renders under the value. Bare `inlineLabel(false)` clears. `dehydrated(false)` drops the field from the POST body before validation. `OptionsResolver` extracted to `fields/optionsResolver.ts` and shared by SelectField/Radio/CheckboxList. FileUpload reads `ctx.uploadUrl` (panel-level URL stamped by `pageData.uploadCtx`). New coerce branches: `checkbox` (toggle-like), `slider` (number-like), `dateTime`, `checkboxList` (string[]), `color`, `keyValue` (JSON-string → object), `fileUpload` (URL string or string[]). **Plan #14 `RepeaterField`:** array-of-subschema field; `.schema([...]) / .columns(n) / .defaultItems(n) / .min/maxItems / .reorderable() / .collapsible().collapsed() / .accordion() / .cloneable() / .itemLabel(row=>str) / .addActionLabel(text)`. **`accordion()` (2026-05-06):** one-row-open-at-a-time mode; auto-arms `collapsible()`. Renderer swaps the per-row `collapsed[id]` map for a single `accordionOpenId: string | null` slot; persisted under `pilotiq.repeater.<formId>.<name>.accordion`. Compose with `collapsed()` for "all start closed" (default opens first visible row). Available on Builder too — same shape, persisted under `pilotiq.builder.<formId>.<name>.accordion`. **`expandAction(b) / expandAllAction(b?) / collapseAllAction(b?)` (2026-05-08, audit gap #7):** widens `RowButtonKind` from 7 → 10 slots. `expandAction` is a sibling of `collapseAction` for the *collapsed* state only (open state still routes through `collapseAction`; bare `collapseAction` continues to cover both states for back-compat). `expandAllAction / collapseAllAction` are opt-in field-header bulk chips — calling enables (with or without a `RowButton` override), auto-arms `collapsible()`. Renderer mounts via shared `<BulkCollapseHeader>` above the rows in both Repeater and Builder; accordion mode preserves "only one open" by opening the first visible row on `expandAll` and clearing `accordionOpenId` on `collapseAll`. Per-row mode iterates every row id and writes the `pilotiq.repeater|builder.<formId>.<name>.<rowId>` storage slot so reload restores the bulk state. Table mode skips the chrome (collapsing is meaningless on `<tr>` rows). All three serialize through the existing `serializeRowButtons` helper — no new wire-shape branch. Server-resolved `meta.rows: { id, children, itemLabel? }[]` + `meta.template`. `coerceFormValues` runs a Repeater pass before generic field coercion (handles JSON + flat-key bodies, trims trailing untouched rows, recurses into nested Repeaters). `validateSchema` recurses; per-row errors keyed `items.<i>.<name>`; `min/maxItems` under bare key. `applyStateUpdate` resolves dotted paths; row-scoped `$get/$set` + `ctx.row` exposed to `afterStateUpdated`; cross-row reads via dotted paths. Inner `Section.visible(({ values }) => …)` sees row-scoped values. Walkers (`findForms / findActions / findTables / findFieldByName / validation walk / coerce walkFields`) STOP at Repeater boundary via structural `isRepeaterField` helper. Client renderer `react/fields/RepeaterInput.tsx` uses `FormIdContext` for localStorage keying; uncontrolled inputs with name-prefixing per row preserve typed values across reorder/clone/collapse. Reorder via native HTML5 drag-and-drop (grip handle + 2px drop indicator) plus Up/Down buttons as keyboard fallback — both routes through pure helper `reorderRows(rows, fromIdx, insertBeforeIdx)`. Inner-field live re-resolve roundtrip wired via container-level delegated `onChange / onBlur` in `RepeaterInput`: dotted-path `target.name` → `findFieldMeta(formMeta, name)` (now walks Repeater rows) → `formState.triggerLive(name, value)`. `FormStateProvider` snapshots the form's full DOM via `parseFormDataToNested(new FormData(formRef.current))` then writes the override through `writeNestedValue`, so the server sees fresh cross-row values + the just-typed leaf. `useFieldState` returns `controlled: false` for dotted names (preserves uncontrolled-input reorder behavior) but still proxies `triggerLive`. **Plan #14 v1.2 (2026-05-02):** React-controlled primitives that update via callbacks (Switch / Slider / Base UI Select / Checkbox / Radio / DateField / DateTime / Color / KeyValue / FileUpload / CheckboxList) call `fs.triggerLive(value)` explicitly in BOTH controlled and uncontrolled paths so their inner `live()` fires inside Repeater rows. Native inputs (text/number/email/textarea/range/date/checkbox/radio) still bubble through `RepeaterInput`'s container-level delegate as before. **Row-level visibility:** `Repeater.itemHidden(rule)` — boolean or `(LayoutContext) => bool | Promise<bool>`; truthy stamps `RepeaterRowMeta.hidden = true`. The renderer keeps hidden rows mounted via `display: none` (no chrome, no drag wiring) so inputs + `__id` round-trip through FormData on submit — visibility is purely UX, never a data filter. Move Up/Down skips hidden neighbours; throwing predicate fails-closed-as-VISIBLE (inverse of layout `visible()`'s posture — silent hiding of in-progress data is the worse failure mode). `itemHidden` re-evaluates on every server resolve (initial SSR, `live()` re-resolve, full submit re-render); the renderer-side `RepeaterInput` / `BuilderInput` sync `hidden / canDelete / canClone / canReorder` from fresh `meta.rows` by row id via `react/fields/syncRowGates.ts` so locally added rows + uncontrolled-input typed values survive the round-trip. Throwing predicate fails-closed-as-VISIBLE (inverse of layout `visible()`'s posture — silent hiding of in-progress data is the worse failure mode). **Plan #14 follow-up — `BuilderField/Builder` (2026-05-02):** heterogeneous-row sibling. `Block.make(name).label().icon().columns().schema([…]).maxItems(n)` defines block types; `Builder.make(name).blocks([…]).reorderable().cloneable().collapsible().blockNumbers().blockPickerColumns(n).addable(false).deletable(false).reorderableWithButtons().addActionAlignment('start'\|'center'\|'end').itemLabel((data, blockName)=>str).itemHidden(rule)`. Storage envelope: `[{ __id, type, data: {…block fields} }]`. Server-side: `resolveBuilderRows` resolves each row against the block matching `row.type`, ships `meta.rows: { id, type, children, itemLabel?, hidden?, unknownType? }[]` + `meta.blocks: { name, label, icon?, columns?, maxItems?, template }[]` (per-block resolved templates so the picker can mount fresh rows without a roundtrip). `coerceBuilderValue` folds JSON + flat-key bodies into the envelope shape; `validateBuilder` keys per-row errors as `name.<i>.data.<child>`, total-count + per-block-type maxItems land under bare key. `applyBuilderStateUpdate` handles dotted paths `name.<i>.data.<leaf>` (the literal `data` segment distinguishes from Repeater's `name.<i>.<leaf>`) — picks the block from `values[name][i].type`, resolves leaf from block schema, runs `afterStateUpdated` with row-scoped `$get/$set` + `ctx.row.blockType`. Walkers (`findForms / findActions / findTables / findFieldByName / coerce walkFields / validate walk`) stop at Builder via structural `isBuilderField` helper alongside `isRepeaterField`. Unknown block types in submitted data round-trip verbatim (renderer shows a placeholder, server passes data through) — config rollbacks never silently lose content. Client renderer `react/fields/BuilderInput.tsx` reuses `reorderRows` from `RepeaterInput`; the picker dropdown is a plain `useState`-driven menu (no Popover dep) that greys out per-block-type capped options; row header carries block icon (via `useIconFor` from `react/icon-context.tsx`) + optional 1-based numbering; localStorage keying namespaces under `pilotiq.builder.<formId>.<name>.<rowId>` (parallel to repeater). **`Repeater.relationship(name | { name, model?, foreignKey?, orderColumn? })` (2026-05-03):** stores rows in a real `HasMany` relation on the parent record instead of a JSON column. Field surface `.relationship(arg).orderColumn(col)`; mutually exclusive with `simple()` and `dehydrated(false)`. Wire shape `meta.relationship?: { name, orderColumn? }` (server-only `model` / `foreignKey` never serialize). Load: `pageData.applyRelationshipRepeaterFill(form, values, record, R.model)` reads rows from `parent.related(name)` via `resolveRelatedQuery`, stamps `__id = String(child.pk)`, strips PK + FK from each rendered row. Save: `dispatchFormSubmit` calls `extractRelationshipRepeaters` after `coerceFormValues + unwrapSimpleRepeaters` (deletes the field's value from `data` so the parent's `M.update / create` never sees it), then after `persist()` returns the parent record runs `persistRelationshipRows` — diff submitted rows against `parent.related(name)` rows: `__id` matching an existing PK → `M.update(__id, row)` (FK NOT overwritten, defends against tampered re-link), `__id` absent or non-matching → `M.create({ ...row, [foreignKey]: parentPk })`, existing PKs missing from submitted set → `M.delete(pk)`. `orderColumn` (when set) stamps the row's 0-based index on every create + update payload. Routes (`POST /:slug/create`, `POST /:slug/:id/edit`) thread `parentModel: R.model` onto the `FormContext`; the pipeline throws a clear error when missing. ORM contract additions: `getParentRelationDescriptor(parentModel, name)` reads `static relations[name]` from the parent (rudder convention `{ type, model: () => ChildModel, foreignKey }`), returns `undefined` when absent — caller throws with a config message pointing at the override paths. **M2M family shipped 2026-05-05 cont'd⁸** — `belongsToMany`, `morphToMany`, `morphedByMany` all dispatch through `parent[rel]().attach/detach/sync` (resolved via `resolveM2MAccessor` in `src/orm/m2mAccessor.ts`). Row-create → `M.create()` then `accessor.attach([newPk])`. Row-update → `M.update()` (pivot untouched). Row-remove → `accessor.detach([pk])` only — **no `M.delete`** (the related child may be linked to other parents; cascadeDelete deferred). `cfg.orderColumn` rejected with a clear error under M2M (ORM has no `orderByPivot`). New ORM helper `getM2MRelationDescriptor(parentModel, name)` recognizes the three M2M `type` strings; called FIRST in `resolveChildAndAttachment` (a belongsToMany entry has no `foreignKey` so it'd silently fall through to the hasMany branch otherwise). Plan: `docs/plans/repeater-relationship-m2m.md`. Remaining gaps: pivot-extras editing (ORM v1 doesn't surface pivot reads), `cascadeDelete: true` opt-in. No transaction wrapper around parent + child diff in v1 — partial failure leaves the parent saved. Plan + memory: `docs/plans/repeater-relationship.md`, `docs/guide/repeater.md` "Relationship-backed rows" section, `project_pilotiq_repeater_relationship.md`. **`Builder.relationship(name | { name, model?, foreignKey?, typeColumn?, dataColumn?, orderColumn? })` (2026-05-05 cont'd³):** heterogeneous-row sibling. Each row persists as a child record carrying a discriminator column (default `'type'`, holds the block name) + a JSON payload column (default `'data'`, holds the per-block inner-schema values verbatim) — column names overridable via `typeColumn` / `dataColumn`. Field surface `.relationship(arg).orderColumn(col)`; mutually exclusive with `dehydrated(false)`. Wire shape `meta.relationship?: { name, typeColumn?, dataColumn?, orderColumn? }` (server-only `model` / `foreignKey` never serialize). Load: `pageData.applyRelationshipBuilderFill(form, values, record, R.model)` runs after `applyRelationshipRepeaterFill` in `resourceEditData`; reads rows from `parent.related(name)`, stamps `{__id, type, data}` per row, JSON-parses string `data` columns, strips PK + FK + type/data from each rendered row payload. Save: `dispatchFormSubmit` runs `extractRelationshipBuilders` after the Repeater extract (deletes the field's value from `data`), then after `persist()` returns runs `persistRelationshipBuilderRows` — diff submitted rows: `__id` matching an existing PK → `M.update(__id, { [typeColumn]: row.type, [dataColumn]: row.data, [orderColumn]: idx })` (FK NOT overwritten); `__id` absent or non-matching → `M.create({ [typeColumn]: row.type, [dataColumn]: row.data, [foreignKey]: parentPk, [orderColumn]: idx })`; existing PKs missing from submitted set → `M.delete(pk)`. Type column rewrites on update — block type can switch between submits. Reuses Repeater's existing routes-side `parentModel: R.model` threading + `getParentRelationDescriptor` ORM helper. v1 = `hasMany` + `morphMany` / `morphOne` only; **M2M family deliberately deferred** (heterogeneous `{type, data}` envelope doesn't compose with pivot semantics — `resolveBuilderChildAndAttachment` raises a clear error pointing at `Repeater.relationship`). Per-block-type model dispatch (each block points at a different child model) is the prerequisite for ever supporting M2M on Builder; deferred until a consumer asks. Plan + guide: `docs/plans/builder-relationship.md`, `docs/guide/builder.md` "Relationship-backed rows" section, `project_pilotiq_builder_relationship.md`. **`Repeater.afterCreate(fn) / afterUpdate(fn) / afterDelete(fn)` (2026-05-10 cont'd⁷):** per-row hooks fired inside `persistRelationshipRows` after each child operation. Handler receives `(record, ctx: RepeaterRowContext)` with `ctx = { parent, parentId, field, index, mode }`; `mode` is the resolved `RepeaterRelationMode` (`'hasMany' | 'morphMany' | 'belongsToMany' | 'morphToMany' | 'morphedByMany'`) so handlers can branch on M2M-detach-vs-physical-delete in `afterDelete`. `index` is `-1` on `afterDelete` (deleted rows aren't in the submitted set). Each setter throws at config time when `relationship()` hasn't been called first (config-time guard mirrors `orderColumn() / pivotColumns()`). Errors propagate — a throwing handler stops the rest of the persist diff; v1 isn't transactional so earlier rows are already committed. `afterUpdate` payload falls back to `{ ...existingByPk, ...payload }` when `model.update` returns void (rudder ORM's update typing — kept for ORMs that don't echo the updated record).
-- `src/entries/` — **Plan #16 (2026-05-04 cont'd)** read-only label-value pairs for `Resource.detail()`. **`RepeatableEntry` (2026-05-06 cont'd⁶)** — array-of-subschema sibling of `RepeaterField`. `RepeatableEntry.make(name).schema([Entry…]).columns(n).grid(n).table([cols]).contained(false)`. Reads the array off `ctx.record[name]` and resolves the inner schema once per row with `record` scoped to the row's data — inner entries (`TextEntry / BadgeEntry / IconEntry / ImageEntry / KeyValueEntry / ColorEntry`) read state via the same `record[childName]` lookup they use anywhere else. Three layout modes (renderer dispatches `table > grid > stack`); v1 takes a fixed integer for `grid()` (responsive object form deferred until asked). Primitive array elements stash under a reserved `_value` key so a `TextEntry.make('_value')` can target them. Empty / non-array / null falls through to the inherited `default()` placeholder. Resolution lives in `resolveSchema.ts → resolveRepeatableRows` next to the Repeater/Builder branches. `Entry` abstract base extends `Element` with the chrome surface (`label / inlineLabel / default / helperText / tooltip / weight / color / size / lineClamp / wrap / copyable / formatStateUsing`) plus the `Column`-mirroring formatter chain (`since / dateTime / money / numeric / limit`). Subclasses set `getEntryType()` for the wire-side discriminator. Seven leaves: `TextEntry` (default), `BadgeEntry.colors({ value: BadgeColor })`, `IconEntry.options({ value: { icon, color, label } })`, `ImageEntry.dimensions(px) / .square() / .rounded() / .circle() / .width(px) / .height(px)`, **`KeyValueEntry.keyLabel(t).valueLabel(t)` (2026-05-04 cont'd)** — read-only sibling of `KeyValueField`; renderer normalizes object | JSON-string | other into a `Record<string, unknown>` (non-JSON strings + arrays fall through to fallback) and renders a two-column kv table; nested values JSON-stringify for compactness; copyable serializes objects via `JSON.stringify`, **`ColorEntry.dimensions(px) / .square / .rounded / .circle / .hideValue()` (2026-05-04 cont'd)** — sibling of `ColorPickerField`; renders the raw CSS color string as a chip + the value text beside (toggle with `hideValue()` for chip-only). State resolves from `ctx.record[name]` at meta-build time — `Entry.toMeta(ctx)` is gated through the `el instanceof Field || el instanceof Filter || el instanceof Entry` branch in `resolveSchema.ts`. **`Entry.state(path | fn)` (2026-05-04 cont'd⁵):** override the default lookup when the value lives at a nested path or needs to be derived. String form does dotted-path traversal (`'author.name'`, `'tags.0.label'`); numeric segments index into arrays; missing intermediates resolve to `undefined`. Function form runs the user accessor with the full record; throwing fails soft (value=undefined). The entry's `name` still drives the auto-derived label and the discriminator key — pair `.state(...)` with `.label(...)` when the path doesn't read well as a heading. Composes with `formatStateUsing` (state resolves the value, formatter formats it). **`ComponentEntry` (2026-05-04 cont'd⁶, escape-hatch leaf):** hands rendering off to a user-supplied React component registered via `registerEntryComponents({ Name: Component })` from the `@pilotiq/pilotiq/entries` subpath (parallel to `@pilotiq/pilotiq/widgets` for `View`). Subclass form sets `static componentName = '...'`; fluent form uses `.component('...')`. Component receives `{ value }` props (where `value` is the resolved state via `.state(...)` or `record[name]`). For multi-field needs, pack via `.state(r => ({ … }))`. `entryType: 'component'`; renderer dispatches inside `renderEntry` and paints inline error panels (`<EntryComponentError>`) for missing-name / missing-registration. Render-time errors propagate to React's nearest error boundary (no per-entry boundary in v1). The renderer wraps the user component in `<EntryShell>` for label / helperText / tooltip / copyable parity with the typed leaves. Subpath `@pilotiq/pilotiq/entries` lives next to `/widgets` + `/uploads` for the same client-safe-import reason. Demo: `playground/app/Pilotiq/Posts/{ReadingStats.tsx, PostResource.detail()}` + registration in `pages/+Layout.tsx`. `formatStateUsing` runs server-side and stamps `_formatted` (renderer prefers it over re-applying `format`); throwing handlers fail soft. Renderer `react/SchemaRenderer.tsx → renderEntry` dispatches on `meta.entryType` (`'text' | 'badge' | 'icon' | 'image' | 'keyValue' | 'color'`) and wraps every leaf in `<EntryShell>` (label-above by default, label-left when `inlineLabel()`; copyable trigger and `?` info-tooltip both live in the shell). Wire-side `EntryMeta.type === 'entry'` so walkers branch via `isEntry(el)` rather than `instanceof`. Layout-level `visible / hidden / columnSpan` inherited from `Element`. Plan: `docs/plans/infolist-entries.md`, guide `docs/guide/infolists.md`. Demos: `playground/app/Pilotiq/Posts/PostResource.detail()` (Text / Badge / Icon), `playground/app/Pilotiq/Articles/ArticleResource.detail()` (KeyValue / Color against the `metadata` JSON-blob and `accentColor` columns).
-- `src/filters/` — `Filter` base + `SelectFilter / MultiSelectFilter / BooleanFilter / TernaryFilter / DateRangeFilter / TrashedFilter / FormFilter / QueryBuilderFilter`. Lives as children of `Table` via `.filters([...])`. URL keys; reserved keys are `search/sort/page/perPage`. `Filter.query(fn)` overrides default where-clause. **Filter expansion (2026-05-03):** `TernaryFilter` is 3-state (yes/no/blank) for nullable booleans — `.trueLabel/.falseLabel/.blankLabel/.nullable(false)`; default `_queryFn` set in `make()` emits `where(true)/where(false)/whereNull(name)` (falls back to `where(name,null)` when `whereNull?` is missing on the query — added as optional to `ModelQuery` parallel to Plan #13's `withTrashed?`). `DateRangeFilter` is a single URL key with `from..to`-encoded value (`?createdAt=2026-01-01..2026-12-31`, either side may be empty); `.includesTime/.minDate/.maxDate`; default handler emits `where(>=,from)`/`where(<=,to)` skipping the empty side; `parseDateRangeValue` / `encodeDateRangeValue` exported. Both filters set `_queryFn` inside `make()` (TrashedFilter pattern, NOT BooleanFilter's kind-branch pattern), so the model adapter's existing `if (customQuery)` branch covers them with no kind-specific changes. Renderer: `'ternary'` reuses `FilterSelect` with server-supplied options; `'dateRange'` is a new `FilterDateRange` component (two date / datetime-local inputs + Clear `×`, SPA-nav, `?page` reset on change). **Batch C (2026-05-02):** `Filter.indicator(string | (value, filter) => string)` overrides the active-filter pill text; default is `"<label>: <displayValue>"` where `displayValue` comes from each subclass's `formatActiveValue(value)` hook (Select/Multi → option labels, Boolean → Yes/No, Ternary → configured trueLabel/falseLabel/blankLabel, DateRange → `from → to` / `≥ from` / `≤ to`). `toMeta()` emits `indicator?: string` only when the filter has an active value. New `MultiSelectFilter` is a sibling of SelectFilter — `.options([...])`, comma-separated URL value (`?status=draft,published`), `kind: 'multiSelect'`, default `_queryFn` set in `make()` emits `where(name, 'IN', values)` (skips when the parsed list is empty). Helpers `parseMultiSelectValue / encodeMultiSelectValue` exported alongside the class. Renderer: new `<ActiveFiltersBar>` pill row above the table (× clears the URL key + resets `?page`; "Clear all" appears with 2+ active pills); new `FilterMultiSelect` checkbox stack inside the popover for `kind === 'multiSelect'`. **FormFilter (2026-05-04):** arbitrary-schema multi-field filter — `FormFilter.make(name).form([fields…]).handle((q, values) => q).formIndicator((values, filter) => string)`. URL value is JSON-encoded under the single filter key (`?amount={"min":100,"max":500}`); `parseFormFilterValue / encodeFormFilterValue` helpers exported. `toMeta(ctx)` is async, calls `resolveSchema(form, ctx)` to resolve inner fields (so dependent-options resolvers see the user / values context just like a regular form), then walks the resolved tree and stamps each field's `defaultValue` from the parsed URL payload so existing filters round-trip into the popover. `Filter.toMeta` widened to `(ctx?: RenderContext): FilterMeta | Promise<FilterMeta>` and `protected buildBaseMeta()` extracted so sibling sync subclasses (Select/Boolean/Ternary/DateRange/MultiSelect/Trashed) keep `super.toMeta()`-equivalent shape without spreading a Promise union. `resolveSchema` now passes `ctx` to `Filter` instances (mirroring the Field branch) so `FormFilter`'s inner schema resolves with the surrounding render context. `Filter.toMeta` default queryFn for `FormFilter` is a no-op `(q) => q` so modelDefaults' `if (customQuery)` short-circuits cleanly when the user hasn't called `.handle()` (otherwise the default `where(name, jsonString)` clause would fire with a JSON blob). Renderer: `kind === 'form'` mounts a `<FilterForm>` inside the existing `FilterPopover` — `<form>` ref + `new FormData(form)` collector + `encodeFormFilterValue` + Apply / Clear submit buttons. Field renderers reuse `renderFormChild` so every existing field type works inside a filter form (the popover is a small surface, so plain fields read best). **QueryBuilderFilter (2026-05-05 cont'd²¹):** Filament-style composable advanced filter — `QueryBuilderFilter.make(name).label().constraints([Constraint…])`. Constraints are typed value-objects (NOT Elements) — `TextConstraint / NumberConstraint / DateConstraint / SelectConstraint / BooleanConstraint`. Each declares `getOperators()` (per-operator label + `valueKind`) and `apply(query, operator, value): ModelQuery` (translates a single rule to ORM `where` clauses). URL value JSON-encodes into a single key `?runtime={"operator":"and","rules":[…]}`; tree-walker `applyTreeToQuery` chains every rule via `.where()` (AND-root only — see below). Indicator pill formats as `"Label: N condition(s)"` by default; `.treeIndicator(fn)` for override; `.handle((q, tree, filter) => …)` for custom dispatch (cross-table joins). Renderer `<FilterQueryBuilder>` widens `FilterPopover` to `w-[36rem]` when present; mounts a row-stack of (constraint Select + operator Select + value input dispatched off `valueKind`); local-state until Apply (mirrors FilterForm). v1 = AND-only / no nested groups / no relation traversal. **OR + nested groups blocked on rudder ORM `whereGroup` support** — see `~/Projects/rudder/docs/plans/where-group.md`. `notContains` operator on `TextConstraint` deferred (Prisma adapter doesn't translate `NOT LIKE`). Helpers `parseQueryBuilderValue / encodeQueryBuilderValue / emptyQueryBuilderTree / applyTreeToQuery` exported alongside the filter. Plan + guide: `docs/guide/query-builder.md`.
-- `src/actions/` — `Action` primitive. Placement: `inline | bulk | row | header`. Four mutually-exclusive dispatch modes: `Action.href(url) / .method(m).action(url) / .handler(ctx=>…) / .submit()`. Submit can target outside form via `.form(formId)` (HTML `form=` attribute). Submit can also attach a `name`/`value` pair via `.formField(name, value='1')` so the clicked button's pair lands in the form body — `FormRenderer.onSubmit` threads `event.submitter` into `new FormData(form, submitter)` to preserve it. Confirm-gated submits intentionally don't honor `formField` (programmatic `requestSubmit()` has no submitter). Handler actions get `dispatchUrl` stamped at render time.
-
-  **Form-modal actions** (`Action.schema([Field, ...]).handler(...)` or `.modal*()` chrome) — trigger renders Dialog with schema as form. Submit fetches with `Accept: application/json`; server returns `{ ok, redirect, notifications }` (200) / `{ ok: false, errors }` (422) / `{ ok: false, error }` (500). **Form-method actions stay on 303-redirect form-post for back-compat** (Delete-row).
-
-  **Variants & cosmetics**: `.color('primary'|'destructive'|'success'|'warning'|'info'|'ghost') / .size / .tooltip / .outlined / .iconButton / .badge / .badgeColor`. `.destructive()` is sugar.
-
-  **Conditional visibility**: `.visible / .hidden / .disabled / .authorize` — rule is `boolean | (ctx) => boolean | Promise<boolean>` with `ActionVisibilityContext { record?, records?, user? }`. `Action.evaluate(ctx)` async; throws → `visible: false`. Non-row placements eval at schema-resolve. Row-placement actions defer to per-row eval in `loadTableRecords`, stamping `_visibleActions` / `_disabledActions`.
-
-- `src/actions/Action.ts` — `Action` class itself (~1,515 lines): types (`ActionContext / ActionResult / ActionHandler / ActionVisibilityContext / VisibilityRule / ResourceLike / ReplicateOptions` etc), instance fields + setters, modal chrome, link / form / submit mode wiring, `evaluate()` and `toMeta()`. Static factory methods stay on the class as thin delegators (`Action.create / .edit / .view / .delete / .replicate / .restore / .forceDelete / .markAsRead / .bulkDelete / .bulkRestore / .bulkForceDelete / .bulkReplicate / .relationCreate / .relationEdit / .relationDelete / .relationRestore / .relationForceDelete / .relationReplicate / .relationBulkReplicate / .relationAttach / .relationDetach / .relationBulkDetach`) — call sites stay stable; bodies live in the factory sub-modules. `Action.import / .export / .bulkExport` are the exceptions — their bodies stay in Action.ts since they already delegate their internals to the older `*Factory.ts` files via static + dynamic imports. Split via 4 phases (`docs/plans/action-split.md`, 2,159 → 1,515 lines).
-- `src/actions/factoryHelpers.ts` — Shared helpers consumed by every factory sub-module: `resourceBase(basePath, R)` (cluster-aware URL builder), `callPredicate(fn, user, record?)` (Plan #10 fail-open predicate caller), `isTrashed(record, R)` (soft-delete state probe), `isM2MMode(mode)` (true for `belongsToMany / morphToMany / morphedByMany`), `relationUrlPrefix(ctx)` (depth-1 + depth-2 relation URL prefix).
-- `src/actions/crudFactories.ts` — Single-row resource factories: `createAction / editAction / viewAction / deleteAction / replicateAction / restoreAction / forceDeleteAction / markAsReadAction`. Each builds an `Action` shaped by `ResourceLike`'s policy predicates + soft-delete flags.
-- `src/actions/bulkFactories.ts` — Bulk-placement factories: `bulkDeleteAction / bulkRestoreAction / bulkForceDeleteAction / bulkReplicateAction`. Handler-style — iterate `ctx.records`, run per-row policy, call matching model method, return notification with the count succeeded. Owns the phase-local `labelForCount(R, n)` helper for "1 post" / "5 posts" pluralization.
-- `src/actions/relationFactories.ts` — Relation hasMany / morph factories: `relationCreateAction / relationEditAction / relationDeleteAction / relationRestoreAction / relationForceDeleteAction` plus the replicate pair `relationReplicateAction / relationBulkReplicateAction`. Replicate helpers (`computeRelationPin / persistRelationReplica / runRelationReplicateRow`) are private to this file — they force-pin the parent attachment columns (`<foreignKey>` for hasMany; `<morphName>Id` + `<morphName>Type` for morphMany via `computeMorphPayload`) AFTER the strip + BEFORE `beforeReplicaSaved`, so a tampered source row can't slip a different parent in. All factories auto-hide under M2M (factories deferred to `m2mFactories.ts`) and under `morphTo` (child-side polymorphic — no single owner to pin to).
-- `src/actions/m2mFactories.ts` — Pivot factories: `relationAttachAction / relationDetachAction / relationBulkDetachAction`. All three auto-hide outside any M2M mode. `relationAttach` builds a modal-form `SelectField` picker via `attachFactory.buildAttachModalSchema` and POSTs the selected id to the manager's `_action/relationAttach` endpoint; `relationDetach` is a direct row-POST to `_detach/:childId`; `relationBulkDetach` runs the per-row `canDetach` gate inside the handler before calling `parent.related(rel).detach(ids)` once.
-- `src/actions/exportFactory.ts` — `Action.export / Action.bulkExport` internals (resolveExportColumns / collectExportRows / buildExportRow / encodeExport / defaultExportFilename). Lives in its own module so the Action ↔ Table cycle stays clean — `Action.export`'s handler dynamic-imports it at request time. Drives the table's existing `records()` handler in pages so filters / search / sort flow through unchanged. CSV body via `src/io/csv.ts` (RFC 4180 encoder + parser, in-memory only). Handler return shape extended with `{ download: { filename, contentType, body } }` on `ActionResult` + `DispatchActionSuccess`; route layer detects, sets `Content-Type` + `Content-Disposition: attachment` + `res.send(body)` (mutually exclusive with `redirect`); client `dispatchHandlerAction` content-sniffs `Content-Disposition` and triggers a synthetic `<a download>` blob download. Plan: `docs/plans/import-export-actions.md`.
-- `src/actions/importFactory.ts` — `Action.import` internals (parseImportText / runImport / buildImportSchema / buildImportNotification). Auto-builds the modal-form schema (FileUpload + a Mode select when `upsertBy` is set); handler reads `ctx.values.file`, fetches the URL the FileUpload stamped, parses CSV/JSON, walks rows through `R.model.create` (or `R.model.update` for matched upserts). Per-row `validate / beforeCreate / beforeUpdate` hooks; partial-failure-soft (rows that throw / fail validate accumulate in `summary.errors` and the import keeps going). Format auto-detected from filename when not set; `maxRows` cap (default 10_000). Visibility delegates to `R.canCreate`. No transaction wrapper in v1 (rudder ORM doesn't expose one to pilotiq yet).
-- `src/actions/attachFactory.ts` — `Action.relationAttach` modal-form internals: `buildAttachModalSchema({ Related, relationship, recordTitleAttr, labelSingular })` returns a `[SelectField]` populated by `loadAttachableCandidates(parent, rel, relatedModel, recordTitleAttr, limit?)` which fetches up to 50 candidate rows and filters out already-attached ids server-side. Mirrors the `importFactory.ts` / `exportFactory.ts` split — lives outside the Action class so M2M-specific imports (SelectField + ORM helpers) stay out of the main file.
-- `src/io/csv.ts` — `encodeCsv(rows, columns) / parseCsv(input)`. RFC 4180: CRLF emit, LF/CRLF accept, double-quote escaping for embedded quotes, BOM stripped on input. Every cell parsed as a string — type coercion is the importer's job. No third-party dep.
-- `src/actions/ActionGroup.ts` — `ActionGroup.make(name).label().icon().tooltip().actions([Action, ...])`. Renders as DropdownMenu. Same trigger styling + visibility rules as Action. Nested groups flatten. Bulk placement unsupported.
-- `src/schema/Heading.ts` — `Heading.actions([Action…])` — title left + actions right. Used by `CreatePage / EditPage` to put Save in header.
-- `src/validation/` — `Validator = (value, ctx?) => string | null | Promise<string | null>` + optional `serialized: SerializedRule` mirrored to `FieldMeta.rules`. Built-ins: `required, email, minLength, maxLength, min, max, pattern, unique` (async DB probe). `validateSchema(elements, values, record?) → Promise<{ name → string[] }>` — async-aware (awaits each field's validators in declaration order). `Field.required()` auto-contributes a check unless an explicit `required()` is present. `Field.runValidators` is `async` and returns `Promise<string[]>`. `unique({ model, column?, ignoreRecord=true, where?, caseInsensitive?, message? })` — uses `M.query().where(col, value).paginate(1, 2)` (no new ORM contract); `ignoreRecord` skips the row matching `ctx.record[primaryKey]` so edit-no-change saves don't conflict; `caseInsensitive` uses SQL `LIKE` with `%`/`_`/`\` escaped (SQLite/MySQL friendly, Postgres collation-dependent); thrown errors propagate (no silent fail-closed); inside a Repeater it probes the DB but does NOT see unsaved sibling rows. **`Field.distinct(opts?)` (2026-05-04 cont'd)** — cross-row uniqueness inside a Repeater / Builder. Stored on Field as `_distinct: DistinctOptions`; consumed by `validateRepeater` + `validateBuilder` (no-op outside an array-row context). Options: `caseInsensitive` (default false), `ignoreNulls` (default true — empty/null/'' rows are skipped), `message` (default `'Must be unique'`). First occurrence always passes; second + subsequent rows fail with the configured message under `<field>.<i>.<child>` (Repeater) or `<field>.<i>.data.<child>` (Builder). Builder comparison is per-block-type — `heading.text="X"` never conflicts with `paragraph.text="X"`. Pair with `unique({ model })` for in-form + cross-record uniqueness.
-- `src/notifications/` — `Notification.make(title).body().success/error/warning/info().icon().duration()`. Action handlers return `{ notify }`. `dispatchAction` normalizes to `NotificationMeta[]`. Form-post 303 path uses `@rudderjs/session` flash via duck-typed `req.session`; silently no-ops when absent. **Database-backed notifications (Filament v5 parity, 2026-05-06 cont'd¹²):** the same builder doubles as the entry-point for persistent notifications: `Notification.make(t).success().sendToDatabase(recipient)` writes a row on the `notification` table shipped by `@rudderjs/notification`. `Pilotiq.databaseNotifications(opts?)` opt-in toggle (default: off) mounts the bell-icon dropdown next to `<UserMenu>` + four endpoints: `GET ${base}/_notifications` (list + unreadCount), `POST ${base}/_notifications/:id/read` / `:id/unread` / `read-all`. Sugar setters `databaseNotificationsPolling(s|null)` / `databaseNotificationsPosition('topbar'|'sidebar')`. `panelInfo()` emits the `databaseNotifications` meta block (sparse — absent when not opted in OR no user resolves) carrying `position / polling / pageSize / badgeColor / trigger? / listUrl / readUrl / readAllUrl / unreadUrl`. Routes 401 when no user resolves, scope every read/write through `notifiable_id = String(user.id)`. Storage helper `notifications/database.ts` soft-imports `@rudderjs/orm` (variable-string dynamic import) so pilotiq stays zero-dep on orm — when no adapter is registered, list / count / mark functions return empty/zero/false; `persist()` throws (caller has explicitly asked to write). Wire shape `DatabaseNotificationMeta = { id, createdAt, readAt?, title, body?, type?, icon?, url? }`; reads JSON-decode the `data` column. Bell renderer `react/NotificationBell.tsx` is hand-built on `<DropdownMenu>` — fetch on mount + setInterval polling (paused while document hidden), latest-wins seq tracking on the list fetch, optimistic mark-read flips. **Broadcast (Phase 2, 2026-05-06 cont'd¹³):** `databaseNotificationsBroadcast(true | { wsUrl })` opt-in pushes new rows over WebSocket on `private-pilotiq-notifications.${user.id}` so the bell can refetch immediately instead of waiting for the next poll. `Notification.make(t).sendToDatabase(user, { broadcast: true })` chains the persist + push in one call; `Notification.make(t).broadcast(user)` pushes without persisting. `panelInfo()` ships `databaseNotifications.broadcast = { wsUrl, channel, event }` (sparse — absent when broadcast wasn't enabled or the user has no `id`). Routes registers a `private-pilotiq-notifications.*` auth callback at boot via `notifications/registerBroadcastAuth.ts`; the callback gates subscriptions on `pilotiq.resolveUser(req).id === channel.userId` so a tampered subscribe can't snoop another user's inbox. `@rudderjs/broadcast` is a runtime soft-import (variable-string dynamic import in both `notifications/broadcast.ts` and `registerBroadcastAuth.ts`); when not installed everything degrades to polling cleanly. Bell renderer subscribes via `RudderSocket` resolved from `window.__pilotiqRudderSocket` first, falling back to `@rudderjs/broadcast/client/RudderSocket.js`; failures (package missing / connect rejected / auth false) silently fall back to polling. Same-origin `wsUrl` (when meta.broadcast.wsUrl is empty) defaults to `${ws|wss}://${host}/ws`, matching the broadcast provider's default upgrade path. v1 limits: single notifiable type per panel (default `'users'`); no `Action.markAsRead()` factory inside notifications; no full-inbox modal page. Test seams: `_setTestAdapter(adp | null | undefined)` (orm), `_setTestBroadcast(mod | null | undefined)` (push), `_setTestBroadcastAuth(mod | null | undefined)` (auth registration). Tests in `notifications/database.test.ts`, `databaseNotifications.test.ts`, `broadcast.test.ts`, `registerBroadcastAuth.test.ts`. Plan + guide: `docs/guide/database-notifications.md` ("Broadcast (Phase 2)" section).
-- `src/theme/` — Theme engine: types, presets (default/nova/maia/lyra), base-colors, accent-colors, chart-palettes, radius, icon-map, `resolveTheme / generateThemeCSS`.
-- `src/react/AppShell.tsx` — Picks layout mode (sidebar / topbar). Wraps in `ToasterProvider` + `CommandPaletteProvider` (Plan #12 — palette open state lives here so the trigger pill in the layout header and the dialog share via context). `panel.navigation` from `panelInfo()`; `currentPath` from auto-gen `+Layout.tsx`.
-- `src/react/CommandPalette.tsx` — Plan #12 Cmd+K palette. Hand-rolled on Dialog primitive (no `cmdk` dep). Global Cmd/Ctrl+K listener; debounced fetch (150ms) to `${basePath}/_search` with in-flight seq cancellation (mirrors Plan #5 pattern). Empty input → flattens `panel.navigation` into a quick-nav list. Keyboard nav (↑/↓/Enter/Esc). Exports `useCommandPaletteOpener()` for triggers.
-- `src/react/SearchTrigger.tsx` — Plan #12 "Search… ⌘K" pill mounted inside SidebarLayout + TopbarLayout headers. macOS-aware shortcut hint. Renders nothing outside an AppShell (defensive — opener returns null without provider).
-- `src/react/Toaster.tsx` — `<ToasterProvider initialNotifications={...}>` + `useToast()`. Hand-built. Stack fixed bottom-right, auto-dismiss after 5s.
-- `src/react/ThemeProvider.tsx` — Light/dark/system context, localStorage, CSS var injection.
-- `src/react/ThemeToggle.tsx` — Sun/moon toggle.
-- `src/react/layouts/SidebarLayout.tsx` — shadcn Sidebar. `<SidebarGroup>` per nav group, `<SidebarMenuSub>` for children, `<SidebarMenuBadge>` for badges. Active = longest URL prefix.
-- `src/react/layouts/TopbarLayout.tsx` — horizontal nav variant. Group label → dropdown trigger.
-- `src/react/ThemeSettingsPage.tsx` — Theme editor: controls + live iframe preview.
-- `src/react/SchemaRenderer.tsx` — Thin top-level dispatcher (~550 lines) for resolved schema. Walks elements via `renderElement` and delegates each type to a sibling renderer under `src/react/schemaRenderer/`. Public surface: `<SchemaRenderer elements={...} widgetData={...} />` + the `FormFields` helper. Re-exports `dispatchHandlerAction` + `renderFormChild` for consumers (`RepeaterInput.tsx`, `SelectFieldInput.tsx`). Page-chrome renderers that don't fit a sub-namespace (`ListTabsRenderer`, `BreadcrumbsRenderer`, `RelationTabsRenderer`, `RelationTabIcon`) still live here.
-- `src/react/schemaRenderer/` — Modular renderer subtree. Split out of `SchemaRenderer.tsx` in 5 phases (PR #29–#33, 6,798 → 549 lines):
-  - `constants.ts` — `TEXT_*` / `COLUMN_*` / `BADGE_COLOR_CLASSES` lookup tables + `alertStyles`.
-  - `columnFormat.ts` — `applyColumnFormat` (dateTime / since / money / numeric / limit / words). Used by both table cells and entries.
-  - `helpers.tsx` — `resolveIcon`, `layoutClasses`, `renderChildren`, `withTooltip`, `IconCmp` type.
-  - `SimpleElements.tsx` — 13 stateless leaf + layout primitives (text/image/icon/markdown/html/heading/emptyState/divider/unorderedList/card/grid/group/split/fieldset). Exports `renderSimpleElement(el, index, deps)`; deps inject `renderElement` + `renderActionLike` for cases that recurse or mount action children.
-  - `AlertRenderer.tsx` — dismissible alert + localStorage persist.
-  - `SectionRenderer.tsx` — collapsible / persistable Section; takes `renderElement` prop for child recursion.
-  - `TabsRenderer.tsx` — pills + underline variants.
-  - `WizardRenderer.tsx` — multi-step form, URL/localStorage step persist, `WizardNavButton` chrome customizers.
-  - `EntryRenderer.tsx` — `renderEntry` (8 entry types: text/badge/icon/image/keyValue/color/code/component/repeatable) + `EntryShell` chrome + tooltip/copy helpers.
-  - `action/` — Phase 3 action layer:
-    - `renderAction.tsx` — main switch (submit / href / method / handler / disabled placeholder) + `renderActionLike` (action / actionGroup / slotComponent).
-    - `ActionModalDialog.tsx` / `ConfirmActionDialog.tsx` — modal + confirm dialogs.
-    - `MethodActionButton.tsx` / `HandlerActionButton.tsx` — POST-style and JSON-dispatch buttons.
-    - `ActionGroupTrigger.tsx` — dropdown trigger + pending-dialog state.
-    - `buttons.tsx` — `actionButtonClass` / `renderActionIcon` / `renderActionBadge` + `COLOR_VARIANTS` / `OUTLINED_VARIANTS` / `SIZE_CLASSES` / `ICON_SIZE_CLASSES` + `RenderActionOptions` interface.
-    - `helpers.ts` — `dispatchNotifications`, `dispatchMethodAction`, `dispatchHandlerAction`, attachment-download helpers + `Notify` / `Navigate` types.
-  - `form/` — Phase 4 form layer:
-    - `FormRenderer.tsx` — HTML form chrome + fetch+JSON submit + error stamping + `FormStateProvider` mount + `FormBody` / `renderFormChild` / `renderFieldWithValue`.
-    - `renderField.tsx` — 13-way field-type switch + `TextFieldShell` (handles password reveal / mask / datalist via `useTextInputControls`).
-  - `table/` — Phase 5 table layer:
-    - `TableRenderer.tsx` — deferred-load wrapper + `TableSkeleton`.
-    - `TableRendererBody.tsx` — the body itself. Column rendering / sort+pagination+search URL state / group banding+drill-in / per-row inline edit+delete / bulk-action toolbar / cards-layout dispatch / empty+loading states. Accepts a `TableBodyDeps` bag (`renderElement` + `renderActionLike` + `renderFormChild`).
-    - `CardsLayoutBody.tsx` — `contentLayout('cards')` body + responsive `CARDS_GRID_COLS_*` lookup tables + `pickCardCols` / `cardsPerRowClasses`.
-    - `filters.tsx` — every filter widget (`FilterSelect` / `FilterMultiSelect` / `FilterDateRange` / `FilterForm` / `FilterQueryBuilder` + query-builder sub-components) plus chrome (`FilterPopover` / `FilterStrip` / `FilterStripToggle` / `ActiveFiltersBar`) plus toolbar siblings (`TableGroupPicker` / `SortByPicker` / `ColumnsToggleDropdown` / `GroupHeaderText` / `renderFilterControl` / `resolveColumnUrl`).
-    - `formatCell.tsx` — `formatCell` (8 column-type dispatch) + `wrapCell` / `wrapCellList` + `CellCopyButton` + `rowId`.
-    - `url.tsx` — `TableUrlState` + `prefixK` / `buildTableQuery` / `nextSortDir` / `SearchFormHiddenInputs` / `getCurrentSearchParams`.
-    - `links.tsx` — `RecordCellLink` (cell-level SPA link wrapper) + `ActiveGroupKeyChip` + `GroupHeadingLink`.
-    - `renderRowActions.tsx` — per-row action strip; takes `renderActionLike` as a parameter so it stays free of the action import cycle.
-  - **Dependency injection convention.** Renderers that need to recurse take `renderElement` (and sometimes `renderActionLike` / `renderFormChild`) as props or function arguments. `SchemaRenderer.tsx` binds them via closure with thin wrappers (`renderActionLike`, `renderField`, `renderFormChild`, `FormRenderer`, `TableRenderer`) so the rest of the file passes the closure-bound versions into the switch.
-
-  **Row click navigation (table layer):** `Table.recordUrl(r => …)` stamps `_recordUrl`; each *data cell* wraps content in a real `<a href>` (`RecordCellLink`). Plain left-clicks SPA-nav via `useNavigate()`; modified clicks fall through. Action and bulk-select cells stay unwrapped. Per-column overrides: `Column.recordUrl(fn|false)`. `formatCell` switches on `col.columnType`, applies built-in `format` spec, reads `row._formatted[colName]` first. **Per-row classes:** `Table.recordClasses(r => '…')` stamps `_recordClasses` and the renderer concatenates onto the `<tr>` className (after striped + cursor-pointer). **Auto-refresh:** `Table.poll(seconds)` emits `pollInterval` on the meta; `TableRendererBody`'s `useEffect` runs `setInterval(navigate(pathname+search), n*1000)` and pauses while `document.visibilityState !== 'visible'`. **Group banding:** `Table.defaultGroup(col)` stable-sorts rows via `sortRowsByGroupValue` in `dispatchTable` (empty/null group values bubble to the bottom), stamps `_groupValue` per row; the renderer inserts a heading `<TableRow>` whenever the value changes between adjacent rows. **Footer summaries:** `Column.summarize([…])` makes `loadTableRecords` compute aggregates over the rendered rows; renderer mounts a `<TableFooter>` row aligned to the columns when `meta.summaries` is non-empty.
-
-  **All non-modal action triggers SPA-update:** `dispatchHandlerAction / dispatchMethodAction` fetch with `Accept: application/json`, drain notifications via `useToast()`, then `useNavigate()` to redirect. Handler actions WITH confirm/modal → `ActionModalDialog` (controlled or uncontrolled). Confirm-only modals reuse same dialog.
-
-  **Row-data convention** — server-side eval results land on each row under reserved keys: `_visibleActions, _disabledActions, _formatted, _recordUrl, _columnRecordUrls, _recordClasses, _groupValue`. `renderRowActions` filters `conditional: true` actions through `_visibleActions`.
-
-  **Form submit dispatch (Save).** `FormRenderer` intercepts onSubmit, fetches with `Accept: application/json`. `FormData` is built with the submit `event.submitter` so `Action.formField()` name/value pairs ride the body (e.g. `_continueCreate=1` for "Create & create another"). On success: drain notifications, then `useNavigate(redirect)` — but skips when `redirect === current URL` so scroll preservation kicks in, UNLESS the response carries `force: true` (used by "create another" so the same `/create` URL still remounts a fresh form). On 422: parses errors into client state. On 5xx: error toast. Native form-post 303 path preserved as fallback. All POST handlers honor `Accept: application/json`.
-
-  **Walkers use structural type checks, not `instanceof`.** `findForms / findActions` match on `el.getType() === 'form' | 'action'` — Vite SSR module-cache duplication breaks `instanceof`. See `feedback_vite_ssr_module_dup_instanceof.md`.
-
-  **Plan #5 reactive fields (client).** `react/FormStateContext.tsx` ships `FormStateProvider` + `useFieldState(name)` + `useFormState()`. `FormRenderer` is dual-path: with `stateUrl` set it wraps children in the provider (controlled inputs); without it, falls back to today's uncontrolled `defaultValue` path. Each field renderer (`TextLikeInput` for text/email/number/textarea/slug; specialized inputs for toggle/select/date) consults `useFieldState` first, falls back to `defaultValue` when outside the provider — so non-live forms cost nothing. `triggerLive(name)` reads each field's `live` config and POSTs `{ changed, values }` to `stateUrl` (immediate / debounced via `setTimeout` / on blur). In-flight race handling via `requestSeqRef + latestSeenRef` (refs, not state — StrictMode trap). 422 → inline errors; other failures → toast. **Live forms must pin `Form.make().formId('stable-id')`** — see `feedback_pilotiq_live_forms_pin_formid.md`. Public exports: `FormStateProvider`, `useFieldState`, `useFormState` from `@pilotiq/pilotiq/react`.
-- `src/react/ui/` — shadcn primitives (sidebar, button, sheet, separator, tooltip, skeleton, input, checkbox, calendar, dialog, dropdown-menu, popover, select, switch, table, tabs, textarea, **slider** added in Plan #6).
-- `src/react/fields/` — extracted per-fieldtype renderers (`FieldShell`, `TextLikeInput`, `SelectFieldInput`, `ToggleFieldInput`, `DateFieldInput`, `HiddenInput`, `CheckboxInput`, `RadioInput`, `ToggleButtonsInput`, `CheckboxListInput`, `SliderInput`, `ColorInput`, `DateTimeInput`, `KeyValueInput`, `TagsInput`, `FileUploadInput`, `MarkdownInput`). `FieldShell` wraps every input with the label / required asterisk / prefix / suffix / helperText chrome — consumed by `schemaRenderer/form/renderField.tsx`'s 13-way field-type switch.
-- `src/uploads/` — `UploadAdapter` interface + `localUpload({ root, urlPrefix })` adapter for FileUpload. Apps register via `Pilotiq.uploads({ adapter })`; route `POST {base}/_uploads` (multipart) hands the file off to the adapter and returns `{ ok, url }`. `_uploads` route validates `accept` + `maxSize` server-side from the field meta (re-checked even though the client also enforces, so a tampered client can't bypass). Adapter contract is storage-agnostic — disk / S3 / R2 / `@pilotiq/media` all implement the same shape. **`RenderContext.uploadUrl` vs `hasUploadAdapter` (2026-05-04 cont'd):** `uploadUrl` is *always* stamped by `pageData.uploadCtx` (so `FileUpload` can show a clear "no upload route configured" error when missed); the companion `hasUploadAdapter: true` is only set when `cfg.uploads` is present, and tells fields with *optional* upload affordances (e.g. `MarkdownField`'s `attachFiles` toolbar button) to hide themselves rather than render a broken control. `uploadCtx(ctx, cfg)` takes the full PilotiqConfig now (was: `basePath`).
-- `src/plugins/themeEditor.ts` — `themeEditor()` plugin.
-
----
-
-## Page generation (Vite plugin output)
-
-- `pages/(pilotiq)/+Head.tsx` — FOUC prevention script (reads localStorage, sets `.dark` before hydration) + Google Fonts preload
-- `pages/(pilotiq)/+Layout.tsx` — wraps pages in ThemeProvider + AppShell, injects theme CSS inline for SSR
-- `pages/(pilotiq)/+config.ts` — `passToClient: ['viewProps']`
-- `pages/(pilotiq)/dashboard/` — Dashboard (1-segment URL)
-- `pages/(pilotiq)/slug/` — **Single route** for 2-segment URLs (resource index, Global edit, custom page). Server sets `pageType: 'resource' | 'global' | 'page'` in viewProps; the renderer just renders `schemaData` uniformly via `<SchemaRenderer />`.
-- `pages/(pilotiq)/resource-create/` — 3-segment with `parts[2] === 'create'`
-- `pages/(pilotiq)/resource-view/` — 3-segment with `parts[2] !== 'create'` and `parts[1] !== 'theme'` (catches `${slug}/:id` for resource view AND `${global-slug}/view`)
-- `pages/(pilotiq)/resource-edit/` — 4-segment with `parts[3] === 'edit'`
-- `pages/(pilotiq)/relation-list/` — 4-segment relation list (`{slug}/:id/{rel}`); excludes `parts[3] === 'edit'` (resource-edit) and `parts[2] === 'create'` (resource-create)
-- `pages/(pilotiq)/relation-create/` — 5-segment with `parts[4] === 'create'`
-- `pages/(pilotiq)/relation-edit/` — 6-segment with `parts[5] === 'edit'`
-- `pages/(pilotiq)/theme/` — Theme editor page (only when `.use(themeEditor())`); slug route excludes `parts[1] === 'theme'`
-- Every `+Page.tsx` stub is just `<SchemaRenderer elements={vp.schemaData ?? []} />` — server resolves, client renders.
-- Route functions check `PilotiqRegistry` on server, tentatively match on client for SPA nav
-
----
-
-## Plugin system
-
-- `PilotiqPlugin` interface: `{ name, register(panel), registerRoutes?(router, pilotiq) }`
-- `.use(plugin)` on builder — calls `plugin.register(panel)` immediately
-- `.plugins([p1, p2, …])` array sugar — `.use()`s each in order
-- **`registerRoutes?(router, pilotiq)` (optional)** — called by `registerPilotiqRoutes(router, pilotiq)` AFTER the core routes register. Plugins that own HTTP routes (chat endpoints, presence, custom REST) implement this hook so the host stops needing a separate `aiPlugin.mount(router, pilotiq)` two-step. Order matches registration; pilotiq's underscore-prefixed sibling-route convention (`_search`, `_uploads`, `_widget`, `_notifications`) is the recommended URL shape.
-- `@pilotiq/pilotiq/plugins` export path for built-in plugins (`themeEditor()`)
-- Adapter packages ship matching plugin factories alongside their `register*()` exports: `tiptap()` (`@pilotiq/tiptap`), `codeEditor({ languages? })` (`@pilotiq/codemirror`), `recharts()` (`@pilotiq/recharts`). The plugin form is the recommended setup — registers run through the panel module so it's wired in one place. `register*()` exports remain for direct use from `pages/+Layout.tsx` if desired. Both forms are idempotent (`Map.set` under the hood).
-
-### Right sidebar (Phases A + B + C)
-
-- `Pilotiq.rightPanel({ id, label?, icon?, render, defaultWidth?, canAccess?, hidden?, sort? })` registers a single contribution; `Pilotiq.rightPanels([…])` is the bulk variant. Boot validates id shape `^[A-Za-z0-9_.-]+$`, dup ids, defaultWidth bounds, and that `render` is a component.
-- Server pipeline (Phase A): `panelInfo()` calls `buildRightSidebarMeta(cfg, user)` — runs `canAccess(user)` in parallel via `Promise.all`, drops `hidden:true`, sorts by `sort` ascending (registration order ties), serializes per-tab `RightPanelMeta { id, label, icon?, defaultWidth }`. Sparse: absent from `panelInfo()` when no contributions registered, every `canAccess` failed/threw, or every survivor was hidden.
-- Build-time wiring (Phase B): `_components.ts` Vite emitter walks `cfg.rightPanels` and stamps `rightPanelRegistry: { [id]: RenderComponent }` parallel to `componentRegistry`. `useRightPanelComponent(id)` resolves the body at mount time — render references never travel over the wire.
-- Chrome (Phase C): `RightSidebar.tsx` renders a fixed-position right rail on desktop with a 4 px left-edge resize handle, mobile Sheet fallback below `md`, tab strip auto-hidden when only one contribution is registered. `RightSidebarTrigger.tsx` mounts in the topbar between `<NotificationBell>` and `<UserMenu>` in both layouts; uses the contribution's icon when single, `PanelRightOpen/Close` lucide icons when multiple. Mod-Shift-\ (`code === 'Backslash'`) toggles open/close — owned by core, not pluggable.
-- Runtime state lives in `RightSidebarContext.tsx` — `useRightSidebar()` returns `{ open, setOpen, toggle, activeId, setActiveId, width, setWidth, contributions, bounds }`; `useRightSidebarOptional()` returns `null` outside the provider for chrome that wants to render conditionally. Persists three slots per `basePath`: `pilotiq.rightSidebar.<basePath>.{open,activeId,width}`. Width writes only on `pointerup` to avoid Storage churn.
-- Layout-flow shim: `AppShell` wraps the layout in a `<div>` with `paddingInlineEnd: width` when the panel is open on desktop (no padding on mobile or when closed). The wrapper element is stable across open/close so the Layout subtree never remounts. Real layout-column promotion deferred to v2.
-- Width bounds: `RIGHT_PANEL_MIN_WIDTH=240`, `RIGHT_PANEL_MAX_WIDTH=800`, `RIGHT_PANEL_DEFAULT_WIDTH=360`. Per-contribution `defaultWidth` clamps to the same range. `clampPanelWidth(value, opts?)` helper is exported from `@pilotiq/pilotiq/react` for tests + the Tiptap side-panel adopter (deferred).
-- Plugin authors expose factories: `panel.rightPanel(...)` from inside their `register(panel)` so consumers wire via `.plugins([…])`.
-- Plan: `docs/plans/right-sidebar.md`. Guide: `docs/guide/right-sidebar.md`.
-
-### Component slots
-
-- `Pilotiq.components({ nav, header, footer })` registers build-time chrome-slot overrides. Three slots ship: `nav` (replaces default nav tree — `<SidebarMenu>` body in `SidebarLayout`, `<nav>` cluster in `TopbarLayout`), `header` (replaces the whole `<header>` chrome bar in both layouts — in `TopbarLayout` this subsumes the nav region, so setting `header` makes `nav` irrelevant for that layout), `footer` (mounts a `<footer>` element below the main content area in both layouts — separate from the `panels::footer` render hook, which keeps firing INSIDE the content area). The shape is open-ended so additions don't break this surface. `.components()` is order-independent and merges across calls (later call wins per slot; unset keys preserved).
-- Build-time wiring mirrors `rightPanels` — the Vite plugin's `_components.ts` emitter walks `cfg.components` and stamps `componentSlotRegistry: { [slot]: Component }` parallel to `componentRegistry` + `rightPanelRegistry`. The component ref never travels over the wire; the auto-gen `+Layout.tsx` imports the registry and forwards it to `<AppShell componentSlotRegistry=…>`, which threads it through to the layout via `AppShellProps`.
-- Render-hooks vs slots: render-hooks (`panels::sidebar.nav.start` / `panels::sidebar.nav.end`) *splice* around the nav region — they still fire whether the nav is the framework default OR a custom slot component, so plugins that just want to inject a header banner above the nav don't fight with consumers that swap the whole nav. **`header` is the exception** — render hooks rooted INSIDE the default header (`panels::topbar.start`, `panels::topbar.end`, `panels::user-menu.before`, `panels::user-menu.after`) do NOT fire when the header is replaced, since the container they splice into is gone. Plugin authors who care about preserving those splices inside a custom header can mount `<RenderHookSlot name="…" hooks={panel.renderHooks} />` themselves from within the custom header.
-- Public surface: `NavComponentProps`, `HeaderComponentProps`, `FooterComponentProps`, `isNavItemActive` re-exported from `@pilotiq/pilotiq/react`. `NavItem` is also re-exported there for convenience (it already exists on the main barrel). Prop contracts: `nav` + `header` both receive `{ navigation: NavItem[]; basePath: string; currentPath?: string }` (header mirrors nav so a topbar-replacement header can render the nav inline without juggling a second slot); `footer` receives `{ basePath: string; currentPath?: string }` (minimal — footers rarely need the nav tree). For `header` replacements, the existing pilotiq chrome components (`SearchTrigger`, `ThemeToggle`, `NotificationBell`, `RightSidebarTrigger`, `UserMenu`) are exported from `@pilotiq/pilotiq/react` so consumers can drop them back in à la carte rather than reimplementing every control. Authoring example: a user-defined `MyCustomSidebar` lives in `app/Pilotiq/` next to the panel module, gets registered via `Pilotiq.make('Admin').components({ nav: MyCustomSidebar })`.
-- **Authoring `.tsx` inside the panel module dir:** the Vite plugin jiti-loads the panel module at boot so it can harvest `cfg.components` into `_components.ts`. Two gotchas surfaced when this happens: (1) jiti needs JSX support enabled to parse `.tsx` — the plugin passes `jsx: { runtime: 'automatic' }` to `createJiti`, matching the playground tsconfig's `"jsx": "react-jsx"` (no per-file React import needed); (2) jiti's resolver falls through `.js` → `.ts` but NOT `.js` → `.tsx`, so the import statement in the panel module must use the literal `.tsx` extension (e.g. `import { MyCustomSidebar } from './MyCustomSidebar.tsx'`). `allowImportingTsExtensions: true` in the playground tsconfig keeps TS happy with this. The non-panel-module sibling pattern (a `.tsx` registered via `registerWidgetComponents` / `registerEntryComponents` from `+Layout.tsx`) sidesteps both — it's read by Vite, not jiti — but that pattern doesn't apply to component slots because the slot needs a real component ref at panel-build time, not a registry name.
-
----
-
-## Theme system
-
-- `Pilotiq.theme({ preset, baseColor, accentColor, chartPalette, radius, fonts, iconLibrary, cssVariables })` configures theme
-- `resolveTheme()` layers: preset → base color → accent color → chart palette → raw CSS vars
-- `generateThemeCSS()` outputs `:root { ... } .dark { ... }` with `!important` for Tailwind override
-- ThemeProvider manages light/dark/system state, persists to `localStorage['pilotiq-theme']`
-- ThemeToggle renders in both SidebarLayout and TopbarLayout headers
-- FOUC prevention: inline `<script>` in +Head.tsx + inline `<style>` in +Layout.tsx
-- **Default preset: Pilotiq brand** — paper (white) page bg, cream (`oklch(0.979 0.008 78)`) sidebar, terracotta (`#d97757`) primary, ink (`#1a1a1a`) text, Satoshi font via Fontshare CDN. Matches the pilotiq.io marketing site tokens.
-- 4 presets (default, nova, maia, lyra), 7 base colors (`default` sentinel + 6 scales including `cream`), 17 accent colors (incl. `terracotta`), 6 chart palettes (incl. `terracotta`, `default` is a no-op sentinel), 5 radii
-- `resolveTheme()` fallbacks: body/heading font → `'Satoshi'`, radius → `'medium'` (10px)
-- All colors in OKLCH format for perceptual uniformity
-- `themeEditor` works without `.theme()` — the editor seeds an empty config so the built-in default preset + DB overrides still resolve; API routes mount on `hasThemeEditor()`, not on `getTheme()`
-
-**Fontshare for Satoshi:** the `+Head.tsx` font loader (and the theme editor preview iframe) detects `Satoshi` by name and loads it from `https://api.fontshare.com/v2/css?f[]=satoshi@300,500,700&display=swap`. Everything else falls back to Google Fonts. The loader reads from `resolved.fonts` (post-defaults) so Satoshi's stylesheet is always requested when it's the resolved heading or body font, even if the user only overrode the other side.
-
-**themeEditor() plugin:**
-- `import { themeEditor } from '@pilotiq/pilotiq/plugins'` → `.use(themeEditor())`
-- Adds "Theme" nav link in sidebar footer / topbar
-- ThemeSettingsPage: controls sidebar + live iframe preview (srcDoc, client-only via mounted guard)
-- API routes: GET/PUT/DELETE `{base}/api/_theme` persisted to `panelGlobal` table
-- `applyToParent()` updates `<style id="pilotiq-theme">` for instant visual feedback on save
-- Service provider loads saved overrides from DB on boot via `panel.setThemeOverrides()`
-- `getMergedTheme()` merges code defaults + DB overrides at runtime
-- Generated page passes `vike/client/router` `navigate` via `onNavigate` prop for server data re-fetch
-- `@pilotiq/pilotiq` must be in `optimizeDeps.exclude` in app's `vite.config.ts`
-
----
-
-## Pilotiq-specific pitfalls
-
-- **Vike ignores gitignored pages:** NEVER add `pages/` subdirectories to `.gitignore`. Vike respects `.gitignore` when scanning — gitignored page directories are invisible to routing, causing silent 404s.
-- **Route functions + SPA nav:** Route functions in `pages/(pilotiq)/` must tentatively match on the client (`import.meta.env.SSR` check only gates the registry lookup, not the entire match). Returning `false` on client breaks SPA navigation and causes full page reloads.
-- **Page stubs are auto-generated:** `pages/(pilotiq)/` is regenerated by the `pilotiq()` Vite plugin. Don't edit manually — changes are overwritten. To customize rendering, create `app/Views/` files with matching `export const route` (static routes beat route functions).
-- **Layout persistence:** AppShell lives in `+Layout.tsx`, NOT in individual `+Page.tsx`. Vike keeps layouts mounted across navigations — putting the shell in pages causes sidebar to remount/reset on every nav.
-- **Stale `dist/`:** edits to `packages/pilotiq/src/**` require a rebuild to show up in the playground — run `pnpm -F @pilotiq/pilotiq build`, or `cd packages/pilotiq && pnpm dev` for watch mode.
-- **playground needs Tailwind:** `@pilotiq/pilotiq` ships components with Tailwind class names in `className`. The playground's `src/index.css` must `@import "tailwindcss"` with `@source "../../packages/pilotiq/src"` so Tailwind scans pilotiq's components. Without this, the UI renders unstyled.
-- **`optimizeDeps.exclude`:** `@pilotiq/pilotiq` must be in `optimizeDeps.exclude` in the app's `vite.config.ts` to avoid `node:fs` client errors during dev.
-- **Panel module must be client-safe:** `app/Pilotiq/AdminPanel.ts` is re-imported on the client via the Vite plugin's `_components.ts` manifest; Node-only side-effects (e.g. `localUpload(...)`) must move to `bootstrap/providers.ts`. `@pilotiq/pilotiq/uploads` is a separate subpath for this reason.

package/dist/react/useCollabSeed.d.ts

@@ -1,23 +0,0 @@
-import type { CollabRoom } from './CollabRoomContext.js';
-/**
- * Run `seedFn` exactly once after the collab room's first sync.
- *
- * Mirrors `@rudderjs/sync/react`'s `useCollabSeed` shape — same purpose,
- * reimplemented here so pilotiq core stays free of any hard runtime dep
- * on Yjs. The `room` parameter is pilotiq's opaque `CollabRoom`, so the
- * seed callback receives `doc: unknown` and is responsible for its own
- * share-type lookup (`doc.getXmlFragment(key)` for Tiptap consumers,
- * `doc.getText(key)` for CodeMirror, etc.) and its own emptiness check.
- *
- * Returns `true` once the seed callback has run (or was skipped because
- * the room has no `.synced` Promise — i.e. a legacy non-framework
- * provider), so consumers can gate editor mount / placeholder swap.
- *
- * The hook wraps `seedFn` in `doc.transact(..., 'pilotiq-collab-seed')`
- * so downstream observers can filter the synthetic write. Two peers
- * mounting against a brand-new record may both see "empty" and both
- * seed — same race window as the legacy `onProviderSynced` path; the
- * fix is server-side seed handoff, deferred.
- */
-export declare function useCollabSeed(room: CollabRoom | null, key: string, seedFn: (doc: unknown) => void): boolean;
-//# sourceMappingURL=useCollabSeed.d.ts.map

package/dist/react/useCollabSeed.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"useCollabSeed.d.ts","sourceRoot":"","sources":["../../src/react/useCollabSeed.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAIxD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAK,UAAU,GAAG,IAAI,EAC1B,GAAG,EAAM,MAAM,EACf,MAAM,EAAG,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,GAC9B,OAAO,CAwDT"}