@calliopelabs/ui 0.7.0 → 0.12.0

package/README.md

@@ -8,7 +8,7 @@ It is built Storybook first: every component and every screen pattern is built a
 
 - React 19 and TypeScript, shipped as per-file ESM with types. No Next-only APIs: the app hands the package its link component.
 - Tailwind CSS 4: the theme tokens as CSS, plus a preset.
-- Radix underneath the overlays and menus; lucide icons.
+- Radix underneath the overlays and menus; @xyflow/react underneath the workflow canvas; lucide icons.
 
 ## Install
 
@@ -240,6 +240,23 @@ export function Shell({ children, can, projects, me }: ShellProps) {
 }
 ```
 
+To fold a rail before first paint, describe it once and hand the same object to the script, the hook and the sidebar. The script stamps `data-rail-<name>` on `<html>` from the saved choice, and until React hydrates the sidebar paints from it, so a person who folded the rail never sees it open first:
+
+```tsx
+// lib/rails.ts (no "use client": the root layout imports it too)
+import type { RailBoot } from "@calliopelabs/ui";
+export const MAIN_RAIL: RailBoot = { key: "astrolift.shell.main", name: "main" };
+
+// app/layout.tsx
+<AppearanceScript product={astrolift} rails={[MAIN_RAIL]} />
+
+// the shell
+const [sidebarCollapsed, setSidebarCollapsed] = useRailState(MAIN_RAIL);
+<Sidebar railName={MAIN_RAIL.name} collapsed={sidebarCollapsed} ... />
+```
+
+A nav row takes a `badge` (`{ value, label, tone? }`: the value shows, the label is what a screen reader hears) and a `trailing` node, shown expanded and, as a mark on the area's icon, collapsed.
+
 `[` folds the sidebar and `]` the right rail. Below `md` both rails open as drawers from a top bar. Zentinelle docks its assistant in the same slot: a `RailPanel` with `collapsedMode="hidden"`, `width` from `useRailWidth(key, 400, { min: 320, max: 560 })` with `onWidthChange`, and `expanded` with `onExpandedChange` for the full-width view. Keep the conversation in state above the shell: on narrow screens a rail renders in its drawer as well as its hidden desktop place.
 
 A page is a `PageFrame`: breadcrumbs from the navigation model (`areaSwitcher`), the title row with its status, context and one primary action, at most one row of tabs, then the body.
@@ -263,7 +280,102 @@ A page is a `PageFrame`: breadcrumbs from the navigation model (`areaSwitcher`),
 </PageFrame>
 ```
 
-The package fetches nothing. `DataTable` reads a `TableController`: rows, state, paging, search and sort, all done by the server. An app implements it over its own data layer; Astrolift's `useCursorTable` already returns one.
+The package fetches nothing. `DataTable` reads a `TableController`: rows, state, paging, search and sort, all done by the server. An app implements it over its own data layer; Astrolift's `useCursorTable` already returns one. A list that is wholly in memory uses `useLocalTable(rows, { sortBy, searchText, filter })`, which searches, sorts and pages the whole set.
+
+## Workflows
+
+`WorkflowQuestionCard` shows a host-owned runtime question, including several
+fields, optional choices and Unicode answers. Bind `question.id`, its opaque
+`revision`, `answers` and delivery `state` to the same request. `onSubmit` reports
+answer intent only; the host must authorize delivery and set `submitting` before
+starting its request. Use `accepted` when the service accepted the answer and
+`acknowledged` only with correlated worker evidence. For uncertain delivery,
+`onRefresh` reads the original request without submitting it again. A changed
+question identity or revision requires a fresh host-owned answer draft.
+
+The card handles loading, empty, read-only, expired and unavailable states. Its
+copy is overridable through the `workflowQuestion` message group. It never starts
+work, grants permission, fetches data or infers acknowledgment from a click.
+
+The workflow surfaces are module-neutral: software, content, media, legal, document review, process, paperwork and automations are labels and versions the host supplies, and nothing in the model assumes tickets, repositories or code. They are host-driven: data in, callbacks out. The package never fetches, saves, authorizes or runs anything.
+
+- **Gallery.** `WorkflowGallery` is a full page of `WorkflowCard`s with search, a module filter, scope and status filters, grid and list views, and create and import when the host passes their handlers. Its filters are controlled (`filters`, `onFiltersChange`): a host that searches on its server passes them to its query; one that holds every definition uses `filterWorkflows(workflows, filters)`. Empty and no-matches are different states.
+- **Availability is explicit.** A `WorkflowSummary` carries `availability` (`available`, `unsupported` or `missing-capabilities` with the names). Only an available workflow the person may start (`permissions.start` not false) shows an enabled start; otherwise the card says why. A fixture or a story never establishes that a module runs.
+- **Runs and review.** `RunTimeline` shows stages with status, timing, attempts, gates and their inputs and outputs; process and automation runs review through it. `ArtifactList` and `ArtifactCard` show typed artifacts with a preview slot. `ReviewPanel` holds the verdict, anchored comments and approve or reject through `ConfirmDialog`, a rejection always with a reason. `GateBadge` reads a gate in one pill.
+- **Module viewers** plug into `ArtifactCard`'s preview and hand `ReviewPanel` an anchor for the next comment: `MediaReview` (video, audio and images, with timecoded and region comments; `formatTimecode` labels them), `DocumentReview` (paged redlines, clause anchors, annotations and sign-off, for legal and document review) and `FormReview` (extracted fields with confidence beside the source page, accept or correct per field).
+- **Editor.** `WorkflowWorkspace` is the whole editor on one page: `WorkflowPalette`, `WorkflowCanvas` and a side panel with `WorkflowInspector`, `WorkflowProblems` and `WorkflowJsonView`, around a working copy the host holds. Each piece also works alone.
+
+```tsx
+const [filters, setFilters] = useState(DEFAULT_WORKFLOW_FILTERS);
+
+<WorkflowGallery
+  workflows={filterWorkflows(definitions, filters)}
+  modules={installedModules}
+  filters={filters}
+  onFiltersChange={setFilters}
+  onCreate={canCreate ? openEditor : undefined}
+  onImport={canImport ? openImport : undefined}
+  actionsFor={(w) => ({
+    href: `/workflows/${w.id}`,
+    onEdit: () => edit(w.id),
+    onStart: () => start(w.id),
+    onExport: () => exportPackage(w.id),
+    permissions: { start: can("start", w), edit: can("edit", w) },
+  })}
+/>;
+```
+
+Their copy is in the `workflow`, `run`, `review`, `media`, `document`, `form`, `editor` and `workspace` message groups.
+
+### The definition and the registry
+
+A `WorkflowDefinition` is named flows of nodes and edges: step, sub-flow, gate, condition, go-to, fan-out, join, variants, evaluator, classifier and check. Edges are `next` (from an exit), `loop` (back to an earlier node, with a limit and an exit condition) and `data` (a typed output to a typed input). Positions live in the document.
+
+Nothing about a module is built in. The host hands the editor a `WorkflowRegistry`: the installed modules with their step presets and typed ports (`extends` lets a contract go where a document is wanted), the run facts, condition operators and gate kinds its runtime knows, the capabilities present, the node kinds it runs, and the roles, members, models, harnesses and efforts its pickers offer.
+
+```ts
+const registry: WorkflowRegistry = {
+  modules: installedModules.map((m) => ({ ...m, presets: m.stepPresets, types: m.dataTypes })),
+  facts: runtime.facts, // { id, label, type, node? }
+  operators: runtime.operators, // { id, label, types, unary? }
+  gateKinds: runtime.gateKinds, // { id, label, fields: ["approvers", "timeout"] }
+  capabilities: factory.capabilities,
+  nodeKinds: { variants: { status: "unsupported", reason: "Variants are not run yet." } },
+  roles,
+  members,
+  models,
+  harnesses,
+  efforts,
+};
+```
+
+- `canConnect(flow, connection, registry)` decides every edge: one per exit (a fan-out excepted), never a cycle, loops only back, data only forward to an input of a type it fits. The canvas lands only what it accepts.
+- `checkDefinition(definition, registry)` returns problems at three levels: `blocking` (holds a publish), `warning`, and `not-run` (this destination does not run the node: module, capability or kind missing). Each points at a flow, node or edge, as a code the `editor` messages name. `nodeAvailability` and `definitionAvailability` return the gallery's `WorkflowAvailability`.
+- Portability: `readWorkflowDefinition` keeps only the fields the format knows. `exportWorkflowPackage` writes a versioned `WorkflowPackage` with what it needs and no credentials, grants or named members; `readWorkflowPackage` reads one back, and `previewWorkflowImport(pkg, registry, replacing?)` says what importing it here would do: module and capability gaps, unknown vocabulary, nodes that would be disabled, gates needing approvers, problems, and the diff.
+
+### The workspace
+
+```tsx
+<WorkflowWorkspace
+  definition={draft}
+  onChange={setDraft}
+  registry={registry}
+  saved={savedRevision} // { id, label, at, by, definition }
+  published={publishedRevision}
+  onSave={(definition, base) => api.saveDraft(id, definition, base?.id)}
+  onPublish={(definition) => api.publish(id, definition)}
+  onSaveAs={(definition, name) => api.create(name, definition)}
+  onExport={(definition) => download(exportWorkflowPackage(definition, registry))}
+  onImport={pickPackageFile} // then pass importPreview, onImportConfirm, onImportCancel
+  readOnly={!can("edit")}
+/>
+```
+
+It marks unsaved edits and a draft that differs from live (`documentStatus`). A newer saved revision is taken when there is nothing to lose; when it moves under unsaved edits, it stops and asks: compare, use theirs, or keep mine. Publishing shows the draft against live (`WorkflowDiff`) and is held while anything blocks. A rejected promise's message is shown and the edits stay. Persistence and authority stay with the host: it never saves, publishes or runs anything itself. Below a 64rem container the palette and the side panel open as drawers.
+
+The canvas pans, zooms and fits without going below `READABLE_ZOOM`; loop bodies and fan-out branches fold, and a sub-flow shows in place. Every drag has a keyboard equivalent: Tab to a node or edge, Enter to select, arrows to move, Delete to remove, and Add and Connect in its toolbar.
+
+`@xyflow/react` comes with the package; its structural CSS is in the preset.
 
 ## Appearance
 
@@ -273,6 +385,157 @@ The person sets four axes, per product: the **ground** (black, charcoal, graphit
 - An org policy that arrives after sign-in goes in through `useAppearance().setPolicy`. An app that keeps the preference on its server passes `onChange` and hands the server's copy back through `applyServerAppearance`.
 - Status colours never move: lime ok, amber warn, red error, green info, whatever the accent or ground. Tests hold the generated CSS to that, and check WCAG contrast for every ground with every accent.
 
+### Runtime brand
+
+A product that runs per customer (one deployment, one brand) takes the brand at runtime, as plain JSON from its server, instead of a second `defineProduct`. The product stays a client-module constant; the brand travels beside it.
+
+```tsx
+// app/layout.tsx (Server Component)
+import { AppearanceScript, htmlAttributes, resolveRuntimeBrand } from "@calliopelabs/ui";
+
+const { brand, warnings } = resolveRuntimeBrand(await loadBrand(), studio);
+// log `warnings`: anything dropped or replaced, and why
+
+<html lang="en" {...htmlAttributes(studio, brand)} suppressHydrationWarning>
+  <head>
+    <AppearanceScript product={studio} brand={brand} nonce={nonce} />
+  </head>
+  <body>
+    {/* a "use client" wrapper: <AppearanceProvider product={studio} brand={brand}> */}
+    <Providers brand={brand}>{children}</Providers>
+  </body>
+</html>;
+```
+
+- `RuntimeBrand` carries `name`, `shortName`, `logo` (`https://` or `data:image` URLs), `accent` (`{ dark, light }`, inks optional), `lockAccent`, `sidebar` (a colour for the dark brand-sidebar grounds, or `{ dark, light }` to brand light grounds too), `sidebarMarker`, `grounds` and `defaultGround`.
+- `resolveRuntimeBrand` never throws. Colours must be lowercase `#rrggbb`; anything else is dropped with a warning, so nothing but a colour reaches the `<style>`. An accent under 3:1 on an offered ground falls back to the product's accent for that mode; inks under 4.5:1 become black or white; the sidebar text is picked to read 4.5:1; a marker under 3:1 is drawn in the sidebar text colour. Grounds outside the product are dropped.
+- The brand's accent is offered under the reserved key `brand`, first and as the default. `lockAccent: true` makes it the only accent and turns off custom colours.
+- `defaultGround` as one ground pins it whatever the system says; as `{ dark, light }` it follows the system.
+- `withBrand(product, brand)` is the product as the deployment shows it, and is what `AppearanceProvider` puts in context. `brandStyles(brand)` is the CSS `AppearanceScript` adds; `brandStyleVars(brand, mode)` is the same tokens as an inline style map, for a preview frame that carries its own `data-mode` and `data-ground`.
+- `BrandMark` draws the brand's logo: `logo.mark` in its tile, and `logo.onDark` or `logo.onLight` in place of the name, chosen by how light the sidebar is in each mode (both are in the markup; CSS shows the right one before paint). Collapsed with no mark, it shows `shortName`.
+- Without a brand, nothing changes: the same markup, the same boot script.
+
+## Server-rendered apps
+
+Apps that render HTML on the server (Django or Jinja, FastAPI with HTMX, Go templates, Rails with Hotwire, Laravel with Livewire, Phoenix LiveView) cannot take React components. They take the CSS layer instead: the same tokens and the same appearance boot script, as plain files, with no Tailwind and no build step.
+
+| File                                  | What it is                                                                                              |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `@calliopelabs/ui/css/tokens.css`     | Every token for every product, ground, accent, density and corners, driven by attributes on `<html>`    |
+| `@calliopelabs/ui/css/components.css` | Class-based components on those tokens (below)                                                          |
+| `@calliopelabs/ui/css/calliope.css`   | `tokens.css` and `components.css` in one file                                                           |
+| `@calliopelabs/ui/css/appearance.js`  | The boot script `AppearanceScript` renders, for the built-in products, plus `window.CalliopeAppearance` |
+
+Both are generated from `src/theme/tokens.ts` and `src/appearance/boot.ts`, and a test holds them to the preset's values and to `AppearanceScript`'s behaviour, so they cannot drift from the React side.
+
+### Getting the files
+
+From npm, copy them into the app's static files (or serve them from `node_modules` with the app's asset pipeline):
+
+```sh
+npm i @calliopelabs/ui
+cp node_modules/@calliopelabs/ui/dist/css/{calliope.css,appearance.js} static/calliope/
+```
+
+From a CDN, once the version is published to npm, pinned to that version:
+
+```
+https://cdn.jsdelivr.net/npm/@calliopelabs/ui@<version>/dist/css/calliope.css
+https://cdn.jsdelivr.net/npm/@calliopelabs/ui@<version>/dist/css/appearance.js
+```
+
+### The `<head>`
+
+The boot script goes first in `<head>`, as a plain script (no `async`, no `defer`) with the product on it, so the person's ground, accent, density and corners are on `<html>` before anything paints. A Django or Jinja base template:
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <script src="{% static 'calliope/appearance.js' %}" data-product="astrolift"></script>
+    <link rel="stylesheet" href="{% static 'calliope/calliope.css' %}" />
+    <link rel="stylesheet" href="{% static 'app.css' %}" />
+  </head>
+  <body>
+    {% block content %}{% endblock %}
+  </body>
+</html>
+```
+
+`data-product` is one of `astrolift`, `zentinelle`, `workbench`, `chat-studio`, `loadr` or `cykick`. The script reads the same `localStorage` entry as the React app (`<product>.appearance`), so a person's choice carries between a product's React and server-rendered pages on one origin. Under a strict CSP, serve the file from your origin (it is a file, so no nonce is needed) or inline its contents with the page's nonce.
+
+HTMX swaps and Hotwire or LiveView navigations replace `<body>`, not `<html>`, so the stamp survives them. A full page load runs the script again.
+
+### The attributes
+
+The stylesheet reads attributes, on `<html>` or on any element below it:
+
+| Attribute      | Values                                                                              |
+| -------------- | ----------------------------------------------------------------------------------- |
+| `data-product` | the product: its sidebar colour and its own accent                                  |
+| `data-mode`    | `dark` or `light`; must match the ground                                            |
+| `data-ground`  | `black`, `charcoal`, `graphite`, `emerald`, `navy` (dark); `paper`, `mist` (light)  |
+| `data-accent`  | `green`, `copper`, `ice`, `periwinkle`, `amber`, or the product's own (`teal`, ...) |
+| `data-density` | `compact` or `cards`                                                                |
+| `data-corners` | `0`, `2`, `4` or `10` (the boot script sets `--radius` inline instead)              |
+
+A server that keeps the preference itself can render the attributes into the template and skip the script:
+
+```html
+<html
+  lang="en"
+  data-product="astrolift"
+  data-mode="light"
+  data-ground="paper"
+  data-accent="copper"
+  data-density="compact"
+  data-corners="2"
+></html>
+```
+
+The app's own CSS uses the variables: `var(--background)`, `var(--foreground)`, `var(--card)`, `var(--border)`, `var(--primary)`, `var(--primary-foreground)`, `var(--muted-foreground)`, `var(--sidebar)`, the status set (`--success`, `--success-fg`, `--success-bg`, `--success-border`, and the same for `warning`, `info` and `danger`), `var(--radius)` and the density variables (`--row-pad-y`, `--panel-pad`, `--stack-gap`, ...). The fonts are the app's to load, as above.
+
+### Components
+
+`components.css` styles the common primitives by class, with the same tokens as the React components, so every ground, accent, density and corners setting reaches them. It sits in the `calliope` cascade layer, so the app's own CSS wins without a fight. The catalog's **CSS layer/Components** section shows each one with its markup.
+
+| Component        | Markup                                                                                                                                                                             |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Button           | `<button class="cui-btn">`; `cui-btn--outline`, `--secondary`, `--ghost`, `--danger`, `--link`; sizes `--sm`, `--lg`, `--icon` (with an `aria-label`)                              |
+| Field            | `<div class="cui-field">` with `cui-label`, the control, and `cui-hint` or `cui-error` (`aria-describedby`, `aria-invalid="true"`)                                                 |
+| Input, textarea  | `<input class="cui-input">`, `<textarea class="cui-textarea">`                                                                                                                     |
+| Select           | `<select class="cui-select">`                                                                                                                                                      |
+| Checkbox, switch | `<label class="cui-check"><input type="checkbox" class="cui-checkbox"> ...</label>`; a switch is `<input type="checkbox" role="switch" class="cui-switch">`                        |
+| Card, panel      | `cui-card` (padded); `cui-panel` with `cui-panel__header`, `cui-panel__title`, `cui-panel__body` (`--flush` for a table)                                                           |
+| Status, badge    | `<span class="cui-status cui-status--ok">` (`ok`, `warn`, `error`, `info`; none is muted; `cui-status--pulse` for in flight); `cui-badge` for neutral tags                         |
+| Table            | `<div class="cui-table-wrap" role="region" aria-label="..." tabindex="0"><table class="cui-table">`; `cui-num` on numeric cells                                                    |
+| Alert            | `<div class="cui-alert cui-alert--warn" role="status">` with `cui-alert__title` and `cui-alert__body`; `role="alert"` for errors                                                   |
+| Dialog           | `<dialog class="cui-dialog">` with `cui-dialog__header`, `__title`, `__description`, `__body`, and `<form method="dialog" class="cui-dialog__footer">`                             |
+| Page header      | `<header class="cui-page-header">` with `cui-page-header__row`, `__heading` (an `hgroup`), `__title` (the `h1`), `__actions`, `__description`                                      |
+| App shell        | `<div class="cui-shell">` with `<aside class="cui-sidebar">` (`cui-sidebar__brand`, a `nav` of `cui-nav` and `cui-nav__link`, `aria-current="page"`) and `<main class="cui-main">` |
+| Helpers          | `cui-stack`, `cui-row`, `cui-eyebrow`, `cui-muted`, `cui-mono`                                                                                                                     |
+
+A dialog opens without script through an invoker button, `<button commandfor="delete-app" command="show-modal">`, or with `document.getElementById("delete-app").showModal()` where invoker commands are not yet supported. The footer form closes it and reports which button through `dialog.returnValue`. With HTMX, a server can return the dialog and open it in `hx-on::after-swap`.
+
+### Changing the appearance
+
+`appearance.js` leaves a small API on `window.CalliopeAppearance`:
+
+```js
+CalliopeAppearance.set({ ground: "paper" }); // stores the choice and repaints; other axes keep theirs
+CalliopeAppearance.set({ accent: "#d94f8a" }); // a custom accent, kept only where it stands 3:1 off the ground
+CalliopeAppearance.set({ density: "cards", corners: 4 });
+CalliopeAppearance.get(); // { ground, mode, accent, density, corners }, as painted now
+CalliopeAppearance.reset(); // forget the choice; the product's defaults (and the system's light or dark) apply
+CalliopeAppearance.config; // the product's grounds, accents and corners, to build a picker from
+document.addEventListener("calliope:appearance", (event) => console.log(event.detail));
+```
+
+`set` keeps only values the product offers, like the React picker, and resolves through the same boot script, so a page painted by the server and one changed in the browser agree. A settings form posted to the server can call `set` from its response (an HTMX `hx-on::after-request`, for example) or render the attributes on the next page.
+
+A product that is not built in sets its sidebar with `[data-product="myapp"] { --brand-sidebar: #0b0b19; }` in its own CSS, picks a family accent, and boots with `CalliopeAppearance.boot(config)`, where `config` is the JSON `bootConfig(defineProduct(...))` returns (or one of `CalliopeAppearance.products`, edited).
+
 ## Copy and languages
 
 Every string the package renders is English by default and overridable, one group at a time:
@@ -292,7 +555,7 @@ Node 24 (`.nvmrc`).
 | `npm run storybook`                                         | The catalog, on port 6006                                                        |
 | `npm test`                                                  | Every test, including one that renders every story and runs the a11y addon on it |
 | `npm run lint`, `npm run typecheck`, `npm run format:check` | The gates CI runs                                                                |
-| `npm run theme`                                             | Regenerates `src/styles/theme.css` after a change to `src/theme/tokens.ts`       |
+| `npm run theme`                                             | Regenerates `src/styles/theme.css` and the CSS layer after a token change        |
 | `npm run build`, `npm run pack:check`                       | Builds `dist/` and checks the package a consumer receives                        |
 | `npm run build-storybook`                                   | The static catalog                                                               |
 

package/dist/appearance/AppearancePicker.js

@@ -13,7 +13,9 @@ import { CORNERS } from "./product.js";
 /** The sidebar a ground paints for this product, for the theme previews. */
 function sidebarFor(product, ground) {
     const sidebar = SURFACES[ground].sidebar;
-    return sidebar === "brand" ? product.sidebar : sidebar;
+    if (sidebar === "brand")
+        return product.sidebar;
+    return modeFor(ground) === "light" && product.sidebarLight ? product.sidebarLight : sidebar;
 }
 function accentOn(accent, ground) {
     if (!accent)
@@ -44,7 +46,7 @@ export function AppearancePicker({ className }) {
     const id = React.useId();
     const accents = product.accents;
     const activeTheme = product.themes.find((th) => th.ground === appearance.ground && th.accent === appearance.accent);
-    return (_jsxs("div", { "data-slot": "appearance-picker", className: cn("flex min-w-0 flex-col gap-6", className), children: [locked && (_jsxs("p", { className: "flex items-center gap-2 rounded-lg border border-info-border bg-info-bg px-3 py-2 text-sm text-info-fg", children: [_jsx(LockIcon, { className: "size-4 shrink-0", "aria-hidden": true }), t.locked] })), product.themes.length > 0 && (_jsx(Group, { legend: t.themes, children: _jsx("div", { className: "grid grid-cols-[repeat(auto-fill,minmax(9rem,1fr))] gap-2", children: product.themes.map((theme) => (_jsxs(Choice, { name: `${id}-theme`, checked: activeTheme?.id === theme.id, disabled: locked, onSelect: () => setAppearance({ ground: theme.ground, accent: theme.accent }), className: "flex-col items-stretch gap-2 p-2", children: [_jsx(ThemePreview, { product: product, ground: theme.ground, accent: accents.find((a) => a.key === theme.accent) }), _jsxs("span", { children: [_jsx("span", { className: "block text-sm font-semibold", children: t.themeName(theme) }), _jsx("span", { className: "block text-xs text-muted-foreground", children: t.themeHint(theme) })] })] }, theme.id))) }) })), _jsxs(Group, { legend: t.accent, children: [_jsx("div", { className: "flex flex-wrap gap-2", children: accents.map((accent) => (_jsxs(Choice, { name: `${id}-accent`, checked: appearance.accent === accent.key, disabled: locked, onSelect: () => setAppearance({ accent: accent.key }), children: [_jsx("span", { "aria-hidden": true, className: "size-3.5 rounded-full", style: { background: accentOn(accent, appearance.ground) } }), t.accentLabel(accent.key, accent.label)] }, accent.key))) }), _jsx(CustomAccentField, { id: `${id}-custom`, value: isCustomAccent(appearance.accent) ? appearance.accent : null, ground: appearance.ground, disabled: locked, onChange: (accent) => setAppearance({ accent }) })] }), _jsx(Group, { legend: t.ground, children: _jsx("div", { className: "flex flex-wrap gap-2", children: product.grounds.map((ground) => (_jsxs(Choice, { name: `${id}-ground`, checked: appearance.ground === ground, disabled: locked, onSelect: () => setAppearance({ ground }), children: [_jsx("span", { "aria-hidden": true, className: "size-3.5 rounded-full border", style: { background: SURFACES[ground].background } }), t.groundLabel(ground, GROUNDS[ground].label), _jsx("span", { className: "text-xs text-muted-foreground", children: t.mode(GROUNDS[ground].mode) })] }, ground))) }) }), _jsx(Group, { legend: t.density, children: _jsx("div", { className: "grid gap-2 sm:grid-cols-2", children: DENSITY_KEYS.map((density) => (_jsxs(Choice, { name: `${id}-density`, checked: appearance.density === density, disabled: locked, onSelect: () => setAppearance({ density }), className: "flex-col items-start gap-0.5 px-3 py-2", children: [_jsx("span", { className: "text-sm font-semibold", children: t.densityLabel(density) }), _jsx("span", { className: "text-xs text-muted-foreground", children: t.densityHint(density) })] }, density))) }) }), _jsx(Group, { legend: t.corners, children: _jsx("div", { className: "flex flex-wrap gap-2", children: CORNERS.map((corners) => (_jsxs(Choice, { name: `${id}-corners`, checked: appearance.corners === corners, disabled: locked, onSelect: () => setAppearance({ corners }), children: [_jsx("span", { "aria-hidden": true, className: "size-3.5 border-t-2 border-l-2 border-current", style: { borderTopLeftRadius: corners } }), t.cornersLabel(corners)] }, corners))) }) }), !locked && (_jsx("div", { children: _jsx(Button, { variant: "outline", size: "sm", onClick: reset, children: t.reset }) }))] }));
+    return (_jsxs("div", { "data-slot": "appearance-picker", className: cn("flex min-w-0 flex-col gap-6", className), children: [locked && (_jsxs("p", { className: "flex items-center gap-2 rounded-lg border border-info-border bg-info-bg px-3 py-2 text-sm text-info-fg", children: [_jsx(LockIcon, { className: "size-4 shrink-0", "aria-hidden": true }), t.locked] })), product.themes.length > 0 && (_jsx(Group, { legend: t.themes, children: _jsx("div", { className: "grid grid-cols-[repeat(auto-fill,minmax(9rem,1fr))] gap-2", children: product.themes.map((theme) => (_jsxs(Choice, { name: `${id}-theme`, checked: activeTheme?.id === theme.id, disabled: locked, onSelect: () => setAppearance({ ground: theme.ground, accent: theme.accent }), className: "flex-col items-stretch gap-2 p-2", children: [_jsx(ThemePreview, { product: product, ground: theme.ground, accent: accents.find((a) => a.key === theme.accent) }), _jsxs("span", { children: [_jsx("span", { className: "block text-sm font-semibold", children: t.themeName(theme) }), _jsx("span", { className: "block text-xs text-muted-foreground", children: t.themeHint(theme) })] })] }, theme.id))) }) })), _jsxs(Group, { legend: t.accent, children: [_jsx("div", { className: "flex flex-wrap gap-2", children: accents.map((accent) => (_jsxs(Choice, { name: `${id}-accent`, checked: appearance.accent === accent.key, disabled: locked, onSelect: () => setAppearance({ accent: accent.key }), children: [_jsx("span", { "aria-hidden": true, className: "size-3.5 rounded-full", style: { background: accentOn(accent, appearance.ground) } }), t.accentLabel(accent.key, accent.label)] }, accent.key))) }), !product.accentLocked && (_jsx(CustomAccentField, { id: `${id}-custom`, value: isCustomAccent(appearance.accent) ? appearance.accent : null, ground: appearance.ground, disabled: locked, onChange: (accent) => setAppearance({ accent }) }))] }), _jsx(Group, { legend: t.ground, children: _jsx("div", { className: "flex flex-wrap gap-2", children: product.grounds.map((ground) => (_jsxs(Choice, { name: `${id}-ground`, checked: appearance.ground === ground, disabled: locked, onSelect: () => setAppearance({ ground }), children: [_jsx("span", { "aria-hidden": true, className: "size-3.5 rounded-full border", style: { background: SURFACES[ground].background } }), t.groundLabel(ground, GROUNDS[ground].label), _jsx("span", { className: "text-xs text-muted-foreground", children: t.mode(GROUNDS[ground].mode) })] }, ground))) }) }), _jsx(Group, { legend: t.density, children: _jsx("div", { className: "grid gap-2 sm:grid-cols-2", children: DENSITY_KEYS.map((density) => (_jsxs(Choice, { name: `${id}-density`, checked: appearance.density === density, disabled: locked, onSelect: () => setAppearance({ density }), className: "flex-col items-start gap-0.5 px-3 py-2", children: [_jsx("span", { className: "text-sm font-semibold", children: t.densityLabel(density) }), _jsx("span", { className: "text-xs text-muted-foreground", children: t.densityHint(density) })] }, density))) }) }), _jsx(Group, { legend: t.corners, children: _jsx("div", { className: "flex flex-wrap gap-2", children: CORNERS.map((corners) => (_jsxs(Choice, { name: `${id}-corners`, checked: appearance.corners === corners, disabled: locked, onSelect: () => setAppearance({ corners }), children: [_jsx("span", { "aria-hidden": true, className: "size-3.5 border-t-2 border-l-2 border-current", style: { borderTopLeftRadius: corners } }), t.cornersLabel(corners)] }, corners))) }) }), !locked && (_jsx("div", { children: _jsx(Button, { variant: "outline", size: "sm", onClick: reset, children: t.reset }) }))] }));
 }
 /**
  * Any colour as the accent (Astrolift palette option A). It applies only once

package/dist/appearance/AppearanceProvider.d.ts

@@ -2,6 +2,7 @@ import * as React from "react";
 import type { Density, Mode } from "../theme/tokens.js";
 import { type Appearance, type OrgAppearancePolicy } from "./appearance.js";
 import type { Product } from "./product.js";
+import { type RuntimeBrand } from "./runtime-brand.js";
 export interface AppearanceContextValue {
     product: Product;
     /** What applies now: the org lock, the person's choice, the org default or the product default. */
@@ -21,6 +22,12 @@ export interface AppearanceContextValue {
 }
 export interface AppearanceProviderProps {
     product: Product;
+    /**
+     * This deployment's brand, the same value AppearanceScript got. Plain
+     * JSON, so a Server Component can hand it down; compared by value, so a
+     * fresh object with the same content does not re-apply.
+     */
+    brand?: RuntimeBrand | null;
     /** The org policy, when the caller already has it; `setPolicy` supplies it later otherwise. */
     policy?: OrgAppearancePolicy | null;
     /** Called with the person's new preference (null on reset), for an app that keeps it on its server. */
@@ -42,9 +49,10 @@ export interface AppearanceProviderProps {
  *
  * The product config carries component references (navigation icons), so
  * create this provider in a client module rather than passing the product
- * across from a Server Component.
+ * across from a Server Component. A runtime `brand` is plain data and may
+ * come from one; the context's `product` is the branded one (`withBrand`).
  */
-export declare function AppearanceProvider({ product, policy, onChange, value: controlled, children, }: AppearanceProviderProps): React.JSX.Element;
+export declare function AppearanceProvider({ product: baseProduct, brand, policy, onChange, value: controlled, children, }: AppearanceProviderProps): React.JSX.Element;
 /** The appearance context. Throws outside an AppearanceProvider. */
 export declare function useAppearance(): AppearanceContextValue;
 /** The product in context, or null outside an AppearanceProvider. */

package/dist/appearance/AppearanceProvider.js

@@ -3,6 +3,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import * as React from "react";
 import { subscribeLocal } from "../lib/local-store.js";
 import { appearanceFromServer, applyAppearance, clearAppearance, normalizePartial, parseStoredAppearance, readAppearance, readStoredAppearance, resolveAppearance, writeAppearance, } from "./appearance.js";
+import { withBrand } from "./runtime-brand.js";
 const AppearanceContext = React.createContext(null);
 const LIGHT_QUERY = "(prefers-color-scheme: light)";
 function subscribeScheme(onChange) {
@@ -27,9 +28,12 @@ const noSubscription = () => () => { };
  *
  * The product config carries component references (navigation icons), so
  * create this provider in a client module rather than passing the product
- * across from a Server Component.
+ * across from a Server Component. A runtime `brand` is plain data and may
+ * come from one; the context's `product` is the branded one (`withBrand`).
  */
-export function AppearanceProvider({ product, policy = null, onChange, value: controlled, children, }) {
+export function AppearanceProvider({ product: baseProduct, brand, policy = null, onChange, value: controlled, children, }) {
+    const brandKey = brand ? JSON.stringify(brand) : null;
+    const product = React.useMemo(() => withBrand(baseProduct, brandKey ? JSON.parse(brandKey) : null), [baseProduct, brandKey]);
     const isControlled = controlled !== undefined;
     const raw = React.useSyncExternalStore(subscribeLocal, () => readStoredAppearance(product), () => null);
     const scheme = React.useSyncExternalStore(subscribeScheme, systemMode, () => "dark");

package/dist/appearance/AppearanceScript.d.ts

@@ -1,16 +1,27 @@
+import { type RailBoot } from "../shell/rail-boot.js";
 import type { Product } from "./product.js";
+import { type RuntimeBrand } from "./runtime-brand.js";
 export interface AppearanceScriptProps {
     product: Product;
+    /** This deployment's brand, resolved on the server; pass the same value to AppearanceProvider. */
+    brand?: RuntimeBrand | null;
     /** The page's CSP nonce, when inline style and script need one. */
     nonce?: string;
+    /**
+     * Rails to fold before paint: each one's saved state is stamped on <html>
+     * as `data-rail-<name>`, and a Sidebar with the same `railName` paints
+     * from it until hydration. Pass the same objects to `useRailState`.
+     */
+    rails?: readonly RailBoot[];
 }
 /**
  * Render in <head>, before anything paints: the product's brand tokens (its
- * sidebar and its own accent) and the script that stamps the person's ground,
- * accent, density and corners on <html> from localStorage. Without it the page
- * paints the defaults and swaps once React hydrates, which reads as a flash.
+ * sidebar and its own accent), a runtime brand's tokens when there is one,
+ * and the script that stamps the person's ground, accent, density and corners
+ * on <html> from localStorage. Without it the page paints the defaults and
+ * swaps once React hydrates, which reads as a flash.
  *
  * Not a client component: it renders the same markup on the server and needs
  * no hooks, so a Next root layout can render it directly.
  */
-export declare function AppearanceScript({ product, nonce }: AppearanceScriptProps): import("react").JSX.Element;
+export declare function AppearanceScript({ product, brand, nonce, rails }: AppearanceScriptProps): import("react").JSX.Element;

package/dist/appearance/AppearanceScript.js

@@ -1,14 +1,20 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { railStyles } from "../shell/rail-boot.js";
 import { appearanceScript, productStyles } from "./boot.js";
+import { brandStyles, resolveRuntimeBrand, withBrand } from "./runtime-brand.js";
 /**
  * Render in <head>, before anything paints: the product's brand tokens (its
- * sidebar and its own accent) and the script that stamps the person's ground,
- * accent, density and corners on <html> from localStorage. Without it the page
- * paints the defaults and swaps once React hydrates, which reads as a flash.
+ * sidebar and its own accent), a runtime brand's tokens when there is one,
+ * and the script that stamps the person's ground, accent, density and corners
+ * on <html> from localStorage. Without it the page paints the defaults and
+ * swaps once React hydrates, which reads as a flash.
  *
  * Not a client component: it renders the same markup on the server and needs
  * no hooks, so a Next root layout can render it directly.
  */
-export function AppearanceScript({ product, nonce }) {
-    return (_jsxs(_Fragment, { children: [_jsx("style", { nonce: nonce, "data-calliope-ui": "product", dangerouslySetInnerHTML: { __html: productStyles(product) } }), _jsx("script", { nonce: nonce, "data-calliope-ui": "appearance", dangerouslySetInnerHTML: { __html: appearanceScript(product) } })] }));
+export function AppearanceScript({ product, brand, nonce, rails = [] }) {
+    const effective = withBrand(product, brand);
+    const brandCss = brand ? brandStyles(resolveRuntimeBrand(brand, product).brand) : "";
+    const railCss = railStyles(rails);
+    return (_jsxs(_Fragment, { children: [_jsx("style", { nonce: nonce, "data-calliope-ui": "product", dangerouslySetInnerHTML: { __html: productStyles(effective) } }), brandCss && (_jsx("style", { nonce: nonce, "data-calliope-ui": "brand", dangerouslySetInnerHTML: { __html: brandCss } })), railCss && (_jsx("style", { nonce: nonce, "data-calliope-ui": "rails", dangerouslySetInnerHTML: { __html: railCss } })), _jsx("script", { nonce: nonce, "data-calliope-ui": "appearance", dangerouslySetInnerHTML: { __html: appearanceScript(effective, rails) } })] }));
 }

package/dist/appearance/appearance.js

@@ -51,7 +51,7 @@ export function normalizePartial(raw, product) {
     const out = {};
     if (isGround(product, v.ground))
         out.ground = v.ground;
-    if (isProductAccent(product, v.accent) || isCustomAccent(v.accent))
+    if (isProductAccent(product, v.accent) || (isCustomAccent(v.accent) && !product.accentLocked))
         out.accent = v.accent;
     if (v.density === "compact" || v.density === "cards")
         out.density = v.density;

package/dist/appearance/boot.d.ts

@@ -1,3 +1,4 @@
+import { type RailBoot } from "../shell/rail-boot.js";
 import { type Mode } from "../theme/tokens.js";
 import { type Product } from "./product.js";
 /** What the boot script needs to know about a product: plain data, serialised into the page. */
@@ -20,11 +21,21 @@ export interface BootConfig {
     };
 }
 export declare function bootConfig(product: Product): BootConfig;
+/**
+ * The boot script, as source text: plain ES5 in a string, so no bundler,
+ * transpiler or coverage tool can rewrite it into something that needs a
+ * helper from outside. It is `normalize` + `resolveAppearance` (with no org
+ * policy, which cannot be known before paint) + `applyAppearance`, written a
+ * second time; boot.test.ts runs it against those over a matrix of stored
+ * preferences and system modes, so the two cannot drift apart.
+ */
+export declare const BOOT_SOURCE = "function (c) {\n  var d = document.documentElement, p = {};\n  try {\n    var raw = window.localStorage.getItem(c.key);\n    var parsed = raw ? JSON.parse(raw) : null;\n    if (parsed && typeof parsed === \"object\") p = parsed;\n  } catch (e) {}\n  var light = false;\n  try {\n    light = window.matchMedia(\"(prefers-color-scheme: light)\").matches;\n  } catch (e) {}\n  var has = function (o, k) {\n    return typeof k === \"string\" && Object.prototype.hasOwnProperty.call(o, k);\n  };\n  var lum = function (h) {\n    var n = parseInt(h.slice(1), 16), rgb = [(n >> 16) & 255, (n >> 8) & 255, n & 255];\n    var w = [0.2126, 0.7152, 0.0722], s = 0;\n    for (var i = 0; i < 3; i++) {\n      var v = rgb[i] / 255;\n      s += w[i] * (v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4));\n    }\n    return s;\n  };\n  var ratio = function (x, y) {\n    var a = lum(x), b = lum(y);\n    return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);\n  };\n  var ground = has(c.grounds, p.ground) ? p.ground : light ? c.defaults.light : c.defaults.dark;\n  var accent = p.accent;\n  var custom = typeof accent === \"string\" && /^#[0-9a-f]{6}$/.test(accent) &&\n    ratio(accent, c.grounds[ground].background) >= c.minContrast;\n  d.dataset.product = c.product;\n  d.dataset.ground = ground;\n  d.dataset.mode = c.grounds[ground].mode;\n  if (custom) {\n    d.dataset.accent = \"custom\";\n    d.style.setProperty(\"--brand-primary\", accent);\n    d.style.setProperty(\"--brand-on-primary\",\n      ratio(accent, \"#000000\") >= ratio(accent, \"#ffffff\") ? \"#000000\" : \"#ffffff\");\n  } else {\n    d.dataset.accent = c.accents.indexOf(accent) > -1 ? accent : c.defaults.accent;\n  }\n  d.dataset.density = p.density === \"compact\" || p.density === \"cards\" ? p.density : c.defaults.density;\n  d.style.setProperty(\"--radius\",\n    (c.corners.indexOf(p.corners) > -1 ? p.corners : c.defaults.corners) + \"px\");\n}";
 /**
  * The inline script that stamps a product's appearance on <html> before
  * first paint. Render it in <head> (AppearanceScript does), or write it into
- * an HTML template yourself.
+ * an HTML template yourself. `rails` also stamps each rail's fold
+ * (`data-rail-<name>`) from the entry `useRailState` keeps.
  */
-export declare function appearanceScript(product: Product): string;
+export declare function appearanceScript(product: Product, rails?: readonly RailBoot[]): string;
 /** The product's brand tokens as a CSS string: its sidebar surface and its own accent. */
 export declare function productStyles(product: Product): string;

package/dist/appearance/boot.js

@@ -1,3 +1,4 @@
+import { checkRails } from "../shell/rail-boot.js";
 import { renderProductCss } from "../theme/css.js";
 import { MIN_NON_TEXT_CONTRAST } from "../theme/contrast.js";
 import { GROUNDS, SURFACES } from "../theme/tokens.js";
@@ -9,7 +10,10 @@ export function bootConfig(product) {
         grounds: Object.fromEntries(product.grounds.map((g) => [g, { mode: GROUNDS[g].mode, background: SURFACES[g].background }])),
         accents: product.accents.map((a) => a.key),
         corners: [...CORNERS],
-        minContrast: MIN_NON_TEXT_CONTRAST,
+        // A locked accent takes no custom colour. No pair of colours reaches
+        // 22:1 (the most is 21), so the script refuses every custom accent
+        // without a second code path.
+        minContrast: product.accentLocked ? 22 : MIN_NON_TEXT_CONTRAST,
         defaults: {
             dark: product.defaults.ground.dark,
             light: product.defaults.ground.light,
@@ -27,7 +31,7 @@ export function bootConfig(product) {
  * second time; boot.test.ts runs it against those over a matrix of stored
  * preferences and system modes, so the two cannot drift apart.
  */
-const BOOT_SOURCE = `function (c) {
+export const BOOT_SOURCE = `function (c) {
   var d = document.documentElement, p = {};
   try {
     var raw = window.localStorage.getItem(c.key);
@@ -73,6 +77,28 @@ const BOOT_SOURCE = `function (c) {
   d.style.setProperty("--radius",
     (c.corners.indexOf(p.corners) > -1 ? p.corners : c.defaults.corners) + "px");
 }`;
+/**
+ * The rails' half of the boot script: each rail's fold from the entry
+ * `useRailState` keeps, stamped as `data-rail-<name>`. The default is
+ * `narrowerThan(collapsedBelow)`, written out; rail-boot.test.tsx holds the
+ * two to the same answer.
+ */
+const RAIL_SOURCE = `function (rails) {
+  var d = document.documentElement;
+  for (var i = 0; i < rails.length; i++) {
+    var r = rails[i], saved = null, folded = false;
+    try {
+      saved = window.localStorage.getItem(r.key);
+    } catch (e) {}
+    if (saved === "1") folded = true;
+    else if (saved !== "0" && r.collapsedBelow) {
+      try {
+        folded = window.matchMedia("(max-width: " + (r.collapsedBelow - 0.02) + "px)").matches;
+      } catch (e) {}
+    }
+    d.setAttribute("data-rail-" + r.name, folded ? "collapsed" : "expanded");
+  }
+}`;
 /** JSON that is safe inside an inline <script>. */
 function scriptJson(value) {
     return JSON.stringify(value).replace(/</g, "\\u003c");
@@ -80,10 +106,14 @@ function scriptJson(value) {
 /**
  * The inline script that stamps a product's appearance on <html> before
  * first paint. Render it in <head> (AppearanceScript does), or write it into
- * an HTML template yourself.
+ * an HTML template yourself. `rails` also stamps each rail's fold
+ * (`data-rail-<name>`) from the entry `useRailState` keeps.
  */
-export function appearanceScript(product) {
-    return `try{(${BOOT_SOURCE})(${scriptJson(bootConfig(product))})}catch(e){}`;
+export function appearanceScript(product, rails = []) {
+    const appearance = `try{(${BOOT_SOURCE})(${scriptJson(bootConfig(product))})}catch(e){}`;
+    if (rails.length === 0)
+        return appearance;
+    return `${appearance}try{(${RAIL_SOURCE})(${scriptJson(checkRails(rails))})}catch(e){}`;
 }
 /** The product's brand tokens as a CSS string: its sidebar surface and its own accent. */
 export function productStyles(product) {

package/dist/appearance/product.d.ts

@@ -70,6 +70,7 @@ export interface Product {
     /** The product's own accent when it has one; null when it uses a family accent. */
     brandAccent: BrandAccent | null;
     defaults: {
+        /** The ground until someone chooses, per system mode; both the same when a brand pins one. */
         ground: Record<Mode, Ground>;
         accent: string;
         density: Density;
@@ -79,6 +80,18 @@ export interface Product {
     nav: NavModel;
     /** localStorage key of the personal appearance preference. */
     storageKey: string;
+    /** Set by `withBrand`: the name for tight spots (a collapsed rail, a phone bar). */
+    shortName?: string;
+    /** Set by `withBrand`: the deployment's logo, as validated URLs. */
+    logo?: {
+        mark?: string;
+        onDark?: string;
+        onLight?: string;
+    };
+    /** Set by `withBrand`: the brand sidebar on light grounds, when the brand opts in. */
+    sidebarLight?: string;
+    /** Set by `withBrand`: the brand accent is the only accent, and no custom colour is accepted. */
+    accentLocked?: boolean;
 }
 /**
  * Validate a product config and fill in its defaults. Throws on anything

package/dist/appearance/product.js

@@ -51,8 +51,8 @@ export function defineProduct(config) {
         brandAccent = config.accent;
         if (!SLUG.test(brandAccent.key))
             fail(id, "brand accent key must be a lowercase slug");
-        if (brandAccent.key in ACCENTS || brandAccent.key === "custom") {
-            fail(id, `brand accent key ${brandAccent.key} is taken by the family`);
+        if (brandAccent.key in ACCENTS || brandAccent.key === "custom" || brandAccent.key === "brand") {
+            fail(id, `brand accent key ${brandAccent.key} is taken by the family or reserved`);
         }
         for (const field of ["dark", "onDark", "light", "onLight"]) {
             if (!HEX.test(brandAccent[field]))