@crewlethq/ui 0.55.0 → 0.56.0

package/README.md

@@ -42,17 +42,18 @@ import { Button } from '@crewlethq/ui/Button';  // 8 KB of CSS, not 182 KB
 | ---- | ---------- |
 | Actions | `Button` and `ButtonLink` (variants `primary`, `secondary`, `outline`, `ghost`, `accent`, `danger`; sizes `small`, `medium`, `large`; shapes `square`, `pill`), `IconButton`, `Menu`, `Link`, `Copyable`, `CopyButton`, `DownloadButton`, `Kbd` |
 | Content and text | `Text` (the eight registers and `inherit`), `Prose`, `Statement`, `Document`, `DocumentTitle` and `DocumentTitleField`, the Markdown grammar (`parseMarkdown`, `parseMarkdownSpans`, `markdownInline`, `safeHref` and the line readers, with no React in it), `Highlight`, `InlineCode`, `List` and `ListItem`, `DescriptionList`, `Timeline`, `RelativeTime`, `Note`, `Divider` |
-| Forms | `Input`, `Textarea`, `Label`, `FormField`, `FormRow`, `Checkbox`, `CheckboxGroup`, `ConfirmField`, `Select`, `Tag`, `TagsInput`, `DateTimePicker`, `TimeWindowPicker`, `ImageUpload`, `CharacterPicker`, `HuePicker`, `AvatarPicker`, `FactList`, `ChoiceList`, `Composer`, `MarkdownEditor`, `RichEditor` (with `preloadRichEditor`, and the round trip `roundTripMarkdown` and `canonicalMarkdown` from `@crewlethq/ui/RichEditorMarkdown`) |
-| Data display | `DataTable`, `CopyableCell`, `Table`, the read-only table cells (`TableKeyCell`, `TableNumberCell`, `TableDateCell`, `TableEntityCell`, `TableStatusCell`, `TableTagsCell`, `TableTextCell`), `StatCard`, `Meter`, `SegmentedMeter`, `Stepper`, `PricingCard`, `Avatar`, `AvatarStack`, `EntityChip`, `CodeBlock`, `QrCode`, `ObjectHeader`, `FactLine`, `SetByLine`, `Skeleton`, `Eyebrow`, `StatGroup`, `PinTile`, `IconTile`, `SettingsTable` (with `SettingsTable.Row`), `CatalogTile` |
+| Forms | `Input`, `Textarea`, `Label`, `FormField`, `FormRow`, `Checkbox`, `CheckboxGroup`, `ConfirmField`, `Select`, `Tag`, `TagsInput`, `DateTimePicker`, `TimeWindowPicker`, `TimeRangePicker`, `ImageUpload`, `CharacterPicker`, `HuePicker`, `AvatarPicker`, `FactList`, `ChoiceList`, `Composer`, `MarkdownEditor`, `RichEditor` (with `preloadRichEditor`, and the round trip `roundTripMarkdown` and `canonicalMarkdown` from `@crewlethq/ui/RichEditorMarkdown`) |
+| Data display | `DataGrid` (with `useDataGridDriving`, `useAnyDataGridDriving` and `countDataGridRows`), `DataTable`, `CopyableCell`, `Table`, the read-only table cells (`TableKeyCell`, `TableNumberCell`, `TableDateCell`, `TableEntityCell`, `TableStatusCell`, `TableTagsCell`, `TableTextCell`), `StatCard`, `Meter`, `SegmentedMeter`, `Stepper`, `PricingCard`, `Avatar`, `AvatarStack`, `EntityChip`, `CodeBlock`, `QrCode`, `ObjectHeader`, `FactLine`, `SetByLine`, `Skeleton`, `Eyebrow`, `StatGroup`, `PinTile`, `IconTile`, `SettingsTable` (with `SettingsTable.Row`), `CatalogTile` |
 | List screens | `DataView`, and its parts on their own: `DataViewToolbar`, `FilterAxisBar`, `FilterAxisChip`, plus the filter model (`filterDefsFromColumns`, `applyColumnFilters`, `filterPredicate`, `blankFilterValue`) |
 | Feedback and overlays | `Callout`, `ConflictNote`, `EditingStatus`, `Toaster`, `Modal` (with `variant="sheet"`), `ConfirmModal`, `CommandPalette`, `Tooltip`, `Popover`, `Announcer` |
 | Documents and review | `DiffView` and `DiffSummary` with the line diff they draw (`diffLines`, `diffStat`, `collapseDiff`, `firstChangedLines`, `splitLines`, `MAX_DIFF_LINES`, with no React in it), `DiffList`, `VersionCompare`, `CommentThread` |
+| Conversations and the assistant | `ChatThread` (with `ChatThreadHandle`), `MessageBubble`, `RunChip`, `StepList` and `StepStateMark`, `ProposalCard`, `ChangeList` (with `shortenUnchanged`), `StatusCard`, `ReceiptStrip`, `RefusalStrip`, `ResultTableCard`, `OpenInAppCard`, `EntityList`, `RefusalCard`, `SuggestionRow` and `SuggestionList`, `SendButton` |
 | Charts | `Legend`, `BarList`, `StackedBar`, `StackedColumns`, `ActivityStrip`, `TimeSeries`, `Sparkline`, the reading layer they share (`ChartTooltip`, `useChartHover`), and the ramp (`DATA_COLORS`, `DATA_COLOR_OTHER`, `dataColor`) |
-| Marks | `Count`, `StatusDot`, `EmptyValue`, `VisuallyHidden` |
+| Marks | `Count`, `StatusDot`, `Spinner`, `EmptyValue`, `VisuallyHidden` |
 | Hooks and seams | `useModalLayer`, `usePopupLayer`, `LayerHost`, `useListbox`, `useOptionKeys`, `useHighlightRest` and `HIGHLIGHT_REST_MS`, `useClipboard`, `useDownload`, `downloadText`, `downloadBlob`, `safeFilename`, `toCsv`, `elementToPng` and `ElementToPngError`, `useOutcome`, `useAnnouncer`, `useNow`, `formatRelative`, `HeadingLevelProvider`, `cx`, the node hues (`NODE_HUES`, `NODE_HUE_NAMES`, `isNodeHue`) |
 | Layout | `Container`, `Section`, `Card`, `TileGrid`, `ListDetail`, `AsideLayout`, `Tabs`, `Accordion`, `Disclosure`, `Outline` (with `useActiveHeading` and `scrollToHeading`), `TreeGrid` |
 | Arranging a page | `ArrangeBoard`, `ArrangeGrid`, `ArrangeFrame` (with `useGridResize`), `ArrangeGroup`, `ArrangeList`, and the reorder hooks under them (`useReorder`, `useReorderLists`, `moveKey`) |
-| Application shell | `AppShell` with `AppShell.Rail`, `SectionFrame` (with `SectionFrame.Nav` and `SectionFrame.Body`), `LockedLabel`, `AppShell.Topbar`, `AppShell.AccountRow` and `useAppShell`, `AuthLayout`, `SidebarNav` and `NavItem`, `DirectoryList`, `BrandLockup`, `SearchTrigger`, `PageHeader`, `Toolbar`, `Stack`, `Inline`, `Spacer`, `AutoGrid`, `ErrorBoundary`, `useShortcut`, `useFullscreen`, `useIdle`, `useMediaMatch` |
+| Application shell | `AppShell` with `AppShell.Rail`, the `aside` track and the `peek` slot (`useAppShellAside`, `useAppShellPeek`), `AppShell.ResizeHandle` (also `ResizeHandle`) and `useStoredWidth`, `SidePanel` and `SidePanelFrame`, `PeekRail` and `PeekHost` (with `PeekNeighbours`, `usePeekNeighbours`, `usePeekStep`, `peekClickHandler`, `peekRowActivation`), `SectionFrame` (with `SectionFrame.Nav` and `SectionFrame.Body`), `LockedLabel`, `AppShell.Topbar`, `AppShell.AccountRow` and `useAppShell`, `AuthLayout`, `SidebarNav` and `NavItem`, `DirectoryList`, `BrandLockup`, `SearchTrigger`, `PageHeader`, `Toolbar`, `Stack`, `Inline`, `Spacer`, `AutoGrid`, `ErrorBoundary`, `useShortcut`, `useFullscreen`, `useIdle`, `useMediaMatch` |
 | Preferences | `ThemeToggle`, `ThemeSwitcher`, `DensitySwitcher`, `ThemeGallery`, `ThemeSwatch`, `useThemePreference`, `useDensityPreference`, `useSystemTheme`, `resolveTheme`, `applyStoredPreferences`, and the framework-free `applyTheme`, `applyPalette`, `applyDensity` with `THEME_PREFERENCES`, `DENSITY_PREFERENCES` and their guards |
 | Artifacts | `SandboxedFrame` (with `SandboxedFramePlaceholder` and `SandboxedFrameNotice`), `LinkInterstitial` and `openExternal`, `VersionTimeline`, `ShareDialog` with the role ladder (`ARTIFACT_ROLES`, `SHAREABLE_ROLES`, `roleAtLeast`), `PrincipalPicker`, `Principal` and `PrincipalAvatar`, `ArtifactCard`, `ArtifactKindGlyph` and `ArtifactPreviewGlyph` (the preview a card draws with no cover, for a cover with nothing to draw), `ArtifactBar` and `ArtifactVersionChip` (an open artifact's one slim bar), `ArtifactPanel` and `ArtifactWorkspace` (the panels it opens beside or over the artifact), `CanvasBoard` (a design's artboards and notes on a `Canvas`, with the visibility budget `liveBoards`), `CanvasToolbar` (a canvas's tool palette, with `toolForKey`), `LayersList` (the list of a canvas's items beside it, marked by the canvas's selection), `CanvasSchematic` (a design's cover, drawn from its boards' frames), `AccessDeniedCard`, `ArtifactIcon` (with `artifactIconGlyph` and `ARTIFACT_ICON_WORDS`), the native gallery covers (`DocCover`, `SheetCover`, `DashboardCover`), `MergeConflicts`, the dashboard pieces (`WidgetFrame`, `DatasetSource` and `DatasetSourceList`), and `FrameProtocol` (the wire between a host page and an embedded artifact, with no React in it), `ArtifactNameCell` and `ArtifactAccessLabel` (with `ArtifactAccessGlyph`) for a list of artifacts |
 | Sheets | `SheetGrid`, the cells on their own (`CheckboxCell`, `TextCell`, `LongTextCell`, `NumberCell`, `SelectCell`, `MultiSelectCell`, `PersonCell`, `StatusCell`, `DateCell`, `UrlCell`, `RatingCell`, and `SheetCell` for any type), `ChangeMark`, and `SheetModel` (every rule a sheet is drawn from, with no React in it: values, parsing, the keyboard model, TSV, the pending edits of D23) |
@@ -204,6 +205,88 @@ places:
 - A surface that pans or zooms dispatches `LAYER_REPOSITION_EVENT` on its host
   when the content beneath it moves, and every panel anchored inside follows.
 
+## Changes in 0.56.0
+
+### The frame and its panels
+
+**`AppShell` takes an `aside`**: a panel the frame keeps beside every screen, such as an assistant, as a third track of the shell's grid that mirrors the rail. The host decides its shape (`asideShape`) from its own arithmetic, never a media query. A `column` is a complementary region named by `asideLabel`, a second sheet on the frame to the right of the page's: opening it pushes the page narrower, and the bar, the sticky heads, the one scroller and the measured gutter are the page's own and only narrower. An `overlay` covers the page's end edge behind a veil, and a `sheet` is the whole window on a phone. Both are modal dialogs on the shared layer stack: Tab stays in them, Escape and a press on the veil call `onAsideClose`, and focus goes back to what opened them. The panel is one element in every shape, so a window resized across the threshold does not remount it. `asideWidth` (420 by default) sizes the track, and `asideReserve` caps it so the page keeps its floor. `asideResize` (`min`, `max`, `defaultValue`, `onChange`, `onCommit`, `label`) puts a grip in the seam between the two sheets while the aside is a column. The panel arrives with a short entrance, never an exit, and none under reduced motion.
+
+**`AppShell` takes a `peek`**: a detail panel beside the scroller, inside the sheet and under the bar, as a `column` or a `drawer` (`peekShape`, the host's decision). The scroller now stands in a body row (`crewlet-app-shell__body`) that is always rendered, so opening an aside or a peek never remounts `main` or its scroll position. A stylesheet that selected `main` as a direct child of `.crewlet-app-shell__sheet` should select it as a descendant.
+
+**`AppShell.ResizeHandle` is new** (also exported as `ResizeHandle`): the WAI-ARIA window splitter, a focusable `separator` with `aria-orientation="vertical"`, `aria-valuenow`, `aria-valuemin`, `aria-valuemax` and a value text. It moves by pointer drag (measured from where the drag started, with the pointer captured), by ArrowLeft and ArrowRight (16px, 64px with Shift, `RESIZE_HANDLE_STEP` and `RESIZE_HANDLE_LARGE_STEP`), to its bounds by Home and End, and back to `defaultValue` by Enter or a double press. `onValueChange` reports every step and `onValueCommit` the end of each gesture. It is drawn as nothing at rest and a soft accent wash under the pointer, the keyboard and a drag, with a 24px target whatever its drawn width. **`useStoredWidth({ key, min, max, storage })`** keeps the width a reader dragged per browser: `width` is null until they choose one, `setWidth` draws, `commitWidth` draws and keeps, and a stored value is read back only when it is a finite number inside the bounds. Storage that throws leaves the width working for the session.
+
+**`SidePanel` and `SidePanelFrame` are new.** `SidePanel` is the panel beside what the reader works on: a head at the page bar's height (`title`, `icon`, `actions`, Close), a scrolling body and a `footer`. It is a complementary region named by its heading (`hideTitle` keeps the name and hides the words), never a dialog except as a sheet. It takes focus to its heading on open without drawing a ring there, or to a field (`initialFocus`, or `'none'`), hands focus back on close, and closes on Escape from anywhere inside unless something inside answered first. `SidePanelFrame` lays it beside the content as a `column` (capped by `reserve`, with a grip on the panel's edge when `resizable`), over the content's end as a `drawer`, or over all of it as a `sheet` (a modal dialog), as the host decides; with no `shape` it measures itself. In the shell's aside a `SidePanel` fills the track and leaves the landmark, the width and the grip to the shell. **`ArtifactPanel` and `ArtifactWorkspace` are now presets of the two**, with the same props, drawing, class names, container names and `--crewlet-artifact-panel-inset`. The panel's root is a `div` with the complementary role, where it was an `aside`.
+
+**`SidePanel` takes `flush`**: the body draws no inset, for content that owns its own edges, such as a `ChatThread`, which scrolls and insets itself, so the inset is drawn once and the thread's scrollbar stands on the panel's edge. `--crewlet-side-panel-inset` reads 0 inside a flush body, so a sticky foot that offsets itself by the inset still sits on the edge. A host that set the variable to 0 for the same result can pass `flush` instead.
+
+**`ArtifactBar` takes `end`**: a control the host ends every page head with, such as an assistant's Ask button, placed after More as `start` is placed before everything, so an open artifact's own bar keeps it where every other page's bar does. It stands a step further from the bar's own tools than they stand from each other, never wraps, keeps its size while the title gives way, and is never folded into More at any width; a control that should draw smaller on a phone does so itself.
+
+**`PeekRail` and `PeekHost` are new, moved from the engine dashboard.** `PeekRail` is the rail a list opens on one object: a bar with Previous and Next (`onStep`), Open (`openHref`) and Close, and a scrolling body that is a size container. As a column it is capped by `reserve` so the list keeps its floor, with a grip the keyboard moves; as a drawer it stands behind a veil a press on which closes it. In the shell's peek slot its shape is the shell's. `PeekHost` wires the generic half: the order a list publishes (`PeekNeighbours`, `usePeekNeighbours(tokens, query)`, `usePeekOrder`), the step through it (`usePeekStep(current, move)`), a body keyed on its object, a kind with no body closing the rail, an `openHref` that carries the list's query only for an object in the list, and an optional error `boundary`. The address, the keys and the bodies stay the host's. `peekClickHandler` and `peekRowActivation` hold the one rule for which presses on a row peek in place and which open elsewhere (`isPlainPress`).
+
+**`useDataGridDriving(drivable)` decides which grid takes the row keys**, moved from the engine dashboard's grid wrapper: with several grids on one screen, the one the reader last pointed at (`claim`, passed as the grid's `onPointerDown`), and with no gesture yet the first mounted grid with rows. `useAnyDataGridDriving` tells a screen with keys of its own to stand aside, and `countDataGridRows` counts rows through bands.
+
+**`TimeRangePicker` is new, moved from the engine dashboard**: the windows a screen offers as one row of radio segments, in the order given (`options`, `value`, `onChange`), and a window of the reader's own behind Custom (`custom`). It sits beside `TimeWindowPicker` rather than replacing it: this one is inline and never interprets a window, so a custom window comes back as the two typed strings for the screen to read on its own clock. The dialog is prefilled with the window on screen and takes two moments (`mode: 'instants'`) or two whole days (`mode: 'days'`). Each way the fields can be wrong is its own sentence (`timeRangeProblem`), a screen's own `validate` runs after them, Apply is the form's submit button, and a dismissed dialog leaves the reader on Custom as the group's one tab stop.
+
+### The assistant's pieces
+
+The parts the engine dashboard's assistant drawer is built from, each generic enough for any conversation, approval or result surface. Every one ships with a story for each state, holds still under reduced motion, and reads the same in the light, dark and named palettes.
+
+**`Spinner` is new**: the package's one ring, a 2px ring in the current ink with its right quarter open, `inline-block` so it is a box inside a line of text, sized by the text (`em`) or on the glyph scale (`xs`, `sm`, `md`: 12, 14 and 16px). Under reduced motion it stops and stays open, because a closed ring reads as an empty status circle. A pending `Button` now draws it in its leading icon's place (`crewlet-btn__spinner` stays on the element), so a button, a request's state column and a status tag share one mark.
+
+**`IconButton` takes `variant="primary"`**, the accent square, for the one icon-only control that is the decision on its surface. **The current place keeps its ink on every variant**: `IconButtonLink current` was declared above the variants and tied with them, so a ghost square's secondary ink won; it now follows them.
+
+**`Composer` sends on Enter, carries attachments and says why it is disabled.** `submitOn="enter"` sends on Enter and writes a line on Shift+Enter, never on an Enter that ends an input method's composition (`mod-enter`, Command or Control with Enter, stays the default). `trailing` puts a control on the field's row, its corner nested in the box's, and the field then starts at one line and grows to six; a placeholder never wraps it taller. `attachments` is a group of tags above the field inside the edge, named by `attachmentsLabel` and read before the field. `disabledReason` fades the whole composer once (the field and its button inside keep full opacity), shows the reason as the placeholder, describes the field with it and keeps the draft. The edge is now `--color-border-field`, the 3:1 field edge, where it was the 1.46:1 `--color-border-strong`, stepping up to `--color-border-control` under the pointer.
+
+**`SendButton` is new**: a chat composer's send, which becomes Stop while a request runs (`mode`, `onPress`), on one element so focus stays on it. Send is the primary `IconButton` with the arrow, Stop the secondary one with a filled square (`square` is now in the icons' `FILLABLE`). A `disabledReason` holds Send soft disabled; Stop is always available. `labels` words both.
+
+**`StepList` and `StepStateMark` are new, beside `Stepper`**: the steps of a request, each with its own state (`running`, `done`, `failed`, `refused`, `stopped`, `waiting`; `STEP_STATES`) said in words after its label (`STEP_STATE_LABELS`) and drawn by `StepStateMark` in one 16px column on the label's first line, with a mono `duration` and `detail` on the inset ground. A string detail breaks only at a space or after `/`, `?` or `&`, never inside a name such as `sign-in` (`stepDetailPieces`).
+
+**`RunChip` is new**: a request's state as the disclosure of its steps, eight states (`thinking`, `working`, `done`, `waiting`, `applying`, `stopped`, `failed`, `refused`; `RUN_STATES`) on the disclosure trigger with `StepStateMark` as its mark, the chevron hanging into the gutter, the title in the warning ink while it waits and the danger ink when it failed, and a `meta` behind a visible " · " that is hidden from assistive technology (a comma is said instead). Uncontrolled, it is open while the request works and closes itself when it settles. With nothing to open (`expandable`, or no children) it is words with the chevron's slot kept, so its mark does not move when the first step arrives. **`DisclosureAnatomy` takes `icon` and `expandable`** for it.
+
+**`ChatThread` is new**: a conversation as it grows. A focusable `role="log"` with `aria-live="off"` (the host announces a completed answer once, through its `Announcer`) and `aria-busy` while a request runs. It follows the end while the reader is within 48px of it (`CHAT_THREAD_FOLLOW_WITHIN`), anchored in code with the browser's scroll anchoring off, stays put once they scroll up, and shows Jump to latest with a count of what arrived. Its handle (`ChatThreadHandle`) offers `scrollToLatest` and `reveal(element)`, which brings a card that needs a decision into view whole, or with its head at the top when it does not fit.
+
+**`MessageBubble` is new**: one message on its writer's side, the reader's own at the end on the raised ground with a tail corner, anybody else's at the start inside a hairline, at most 85% of the thread and wrapping anywhere. An article named for who said it ("You said" by default), with an `attachment` slot for what it carried (the page a question was sent with, as a read-only `Tag`) and a `footer`.
+
+**`StatusCard` is new**: a record with a state on the default `Card`, a sentence-case title, the state as a `Tag` at the end of the head, and a section named by both. What happened goes in `strip`, and the foot follows one rule (`actionsAlign`): a decision ends the row (its buttons share it as blocks on a card under 360px), utilities start it with a ghost button pulled onto the text edge. `settled` steps the body back to the secondary ink. No tone rail.
+
+**`ReceiptStrip` and `RefusalStrip` are new**: what happened at a card's foot, on the card's hairline, a tone's soft tint under its ink and a 16px mark, a polite status or, for `danger`, an alert. `RefusalStrip` is the one drawing of a refusal, `inline` under the control that caused it or at a card's `foot`, with Try again (`onRetry`, `retrying`) and Dismiss (`onDismiss`) only where offered, and always in the caller's own sentence. The engine dashboard's write buttons can draw their refusal with it.
+
+**`DiffList` takes `layout`**: `stacked` stands each path over its value and wraps both, so a value is read rather than cut by the 200px path track, and `auto` does so under 480px of the list's own width. `columns` stays the default.
+
+**`ChangeList` is new**: a change as before and after pairs (decision D10) on `PropertyList`'s grid in `DiffList`'s tones. `fact`, `changed` (the old value struck through, an arrow and the new value on the added tint, wrapping as a unit), `added` (with a "New" tag for a field new to an existing record), `removed` and `text` rows, the last a word diff whose long unchanged runs are shortened at word boundaries (`shortenUnchanged`, `CHANGE_LIST_COLLAPSE_OVER`) with "Show the whole change" opening a stacking `DiffList`. A pair is said "Changed from X to Y", and added and removed values and words say so. `settled` keeps every pair in the secondary ink.
+
+**`ProposalCard` is new**: a change from proposal to outcome. The title is the action, the subtitle its scope, and the Tag its state (`pending`, `stepup`, `applying`, `applied`, `declined`, `expired`, `stale`, `failed`; `PROPOSAL_STATES`), worded for where it lands (`scope`: Applying and Applied on a page, Saving and Saved on the server). The `ChangeList` heading follows `kind` and the state ("What will change", "What will be created", "What changed", "What was created", "What was proposed"). The foot is Decline and the primary named for its effect, or a strip saying what happened, with Prepare it again (`onPrepareAgain`) and Try again (`onRetry`) where offered. Nothing takes focus when it arrives; while the approved change is carried out the primary keeps its label with the spinner, soft disabled, and Decline is held with its reason. A refusal is the engine's sentence (`failure`) followed by "Nothing changed.". Every word is in `labels` (`PROPOSAL_CARD_LABELS`).
+
+**`ProposalCard` takes `failureHint` and `approveBlocked`.** `failureHint` is what the person can do next about a failure, drawn on its own quieter line in the failure strip after the engine's sentence and "Nothing changed.", and only with `failure`. `approveBlocked` holds the primary soft disabled with a reason while the card is `pending` or `stepup` (a page action whose screen refuses the prepared change): it keeps its focus, says it is unavailable, is described by the reason, which the foot also shows above the decision, and never calls `onApprove`. Decline stays available, and the prop is ignored once the card is applying or settled.
+
+**`Table` takes `footer`, `align` and `framed`**: a total row whose first cell heads the row, a column of figures standing at the end with tabular figures, and `framed={false}` for a table that fills a card, with no edge of its own and its outer cells on the card's inset.
+
+**`DownloadButton` takes `file`**, an async source beside `text` for an export the server builds: the label stays with the spinner while it waits, a second press fetches nothing more, and a rejected fetch reads as a failed download. `useDownload` gains `downloadFile`. `DownloadButtonProps` is now a union of `DownloadButtonBaseProps` and `DownloadButtonSource`; an `interface` that extended it extends `DownloadButtonBaseProps` and adds its own source.
+
+**`ResultTableCard` is new**: a result as a flush `Table` in a `StatusCard`, its title (also the table's hidden caption) over its `window`, end-aligned figures and a `total` row, and a foot of utilities: `downloads` fetched on their press and the host's `link` at the far end. Over `maxRows` (20) rows it shows the first `collapsedRows` (10) and "Show all 48".
+
+**`IconTile` takes `tone="neutral"`**, the raised ground in the secondary ink, for a place or a record rather than a kind.
+
+**`OpenInAppCard` is new**: a place an answer points to, opened only by the person's press, its glyph on a neutral tile with its name and last two crumbs, Open in new tab (drawn only for an address `safeHref` trusts, without opener or referrer) and Open here (`onOpenHere`); once `opened`, a success Tag and a strip.
+
+**`EntityList`, `RefusalCard`, `SuggestionRow` and `SuggestionList` are new.** `EntityList` names people, seats or records as divided rows with one fact and the host's own link, bare or as a card under a `title`. `RefusalCard` says a request the person's access does not allow: Not permitted as a neutral Tag with the lock, the product's sentence, always "Nothing changed.", and utilities only. `SuggestionRow` is a suggested question or request in the list row's grammar, with an optional `detail`, `count` and `chevron`; a `fills` row says ", fills the message box" to assistive technology. `SuggestionList` puts each row in its own list item, plain or `divided` in a card.
+
+**`ToastProvider` and `Toaster` take `inset`** (`ToasterInset`, `{ inline?, block? }` in pixels): room the stack keeps clear on its own side and edge, added to the window inset it already keeps. A host sets `inline` to the width a panel beside the page occupies, so a toast stands beside the panel rather than over its composer, and `block` to the height of a phone sheet's foot, so it stands above it. It may change while toasts are up and they move with it; anything but a finite number of zero or more reads as zero. It is drawn through `--crewlet-toaster-inset-inline` and `--crewlet-toaster-inset-block` on the stack (`toasterInsetStyle` builds them), which a host may also set itself. With no inset the stack stands exactly where it did.
+
+**`ArtifactNameCell` takes words for some kinds only**: `ArtifactNameCellLabels.kinds` is now `Partial<Record<ArtifactKind, string>>`, merged over the kit's own words, so an application that words only the kinds it knows (one built before `brand`) compiles, and a kind it does not word reads in the kit's own word.
+
+**The shared clock reads the time now after sitting idle.** `useNow` and `currentNow` (and so `RelativeTime` and `EditingStatus`'s "Saved 2m ago") read an instant the interval moves only while a reader is subscribed, so a reader mounted after a quiet spell rendered the time the last reader left, until the first tick: a save two minutes old read "1m ago". While the clock is idle, a reading more than a second old is now replaced before it is used.
+
+**`@crewlethq/icons` adds `square-pen`, `square` and `circle-stop`** (`SquarePenGlyph`, `SquareGlyph`, which may be drawn filled, and `CircleStopGlyph`), vendored from the pinned `lucide-static`. Lucide publishes `history` as a retired alias of `rotate-ccw-clock`, which the package already carries, so a conversations list takes `RotateCcwClockGlyph`.
+
+**`ProductMark` takes `product="assistant"`**: Orbit, the crewmate octagon opened into four chamfered blades turning around one core, on the family's tile and lower facet. No eyes and no visor, because the assistant acts as the signed-in person and is drawn as a capability rather than a crew member. Its blades and core are separate detail paths, so a working state can turn the blades and hold the core still.
+
+**`@crewlethq/icons/product-mark` is new**: `ProductMark` and `PRODUCTS` on an entry of their own, whose import graph never reaches the root's illustrations, vendor marks or their stylesheets, so an Ask button in a first paint carries the marks alone. The root exports the same functions.
+
+## Changes in 0.55.0
+
+**`ProductMark` names its products `worklet` and `doclet`** (`@crewlethq/icons`). Worklet (projects and tasks) and Doclet (spaces and pages) are the two services' names, so the product values are `'worklet'`, `'doclet'` and `'chat'`. What to change: replace `product="works"` with `product="worklet"` and `product="knowledge"` with `product="doclet"`; the `crewlet-product-mark--*` modifier classes and the `svg/product/*.svg` files follow the values.
+
 ## Changes in 0.54.0
 
 The setup wizard's review step and footer, laid out for a decision.

package/dist/Accordion/index.js

@@ -1,5 +1,5 @@
-export { Accordion, AccordionItem } from '../chunk-ZNOXQACX.js';
-import '../chunk-FZVJDJFN.js';
+export { Accordion, AccordionItem } from '../chunk-T4D7RZNI.js';
+import '../chunk-TFGCNBWP.js';
 import '../chunk-BHHIIK3M.js';
 import '../chunk-PQADV6P6.js';
 import '../chunk-BZFWDIV6.js';

package/dist/AgentHandoffPanel/index.js

@@ -1,19 +1,24 @@
-export { AGENT_HANDOFF_LABELS, AgentHandoffPanel } from '../chunk-G22NPQG4.js';
+export { AGENT_HANDOFF_LABELS, AgentHandoffPanel } from '../chunk-GCASX3FD.js';
 import '../chunk-AUQPBL4O.js';
 import '../chunk-JQ7IFSF6.js';
-import '../chunk-OGXHZHRX.js';
-import '../chunk-4E5MWUUJ.js';
-import '../chunk-NBDN5JZV.js';
+import '../chunk-JLRXCKTS.js';
+import '../chunk-GG4QZWMQ.js';
+import '../chunk-HGYHWWA5.js';
+import '../chunk-XODESBSR.js';
 import '../chunk-SMBKXWML.js';
-import '../chunk-XANKR3EP.js';
+import '../chunk-FXQLNETQ.js';
 import '../chunk-XCUUI7E7.js';
-import '../chunk-FZVJDJFN.js';
+import '../chunk-TFGCNBWP.js';
 import '../chunk-BHHIIK3M.js';
 import '../chunk-PQADV6P6.js';
-import '../chunk-OG6CL3EB.js';
+import '../chunk-RSAQOKH3.js';
+import '../chunk-PIYJNCN7.js';
+import '../chunk-HD4QJ2SI.js';
+import '../chunk-EA23JG6R.js';
+import '../chunk-OMV5W53A.js';
+import '../chunk-2YTOOH3A.js';
 import '../chunk-H5XTJ7GJ.js';
-import '../chunk-LACA4JGC.js';
+import '../chunk-2BQYODY3.js';
 import '../chunk-NUZHC6MM.js';
-import '../chunk-RSAQOKH3.js';
 import '../chunk-BZFWDIV6.js';
 import '../chunk-ODEQTPFM.js';

package/dist/AppShell/AppShell.d.ts

@@ -36,9 +36,47 @@
  * layout it belongs to ends. Hidden rather than merely moved off screen, too,
  * because a rail translated out of view keeps every link in the tab order and
  * a keyboard reader walks through a dozen stops nobody can see.
+ *
+ * THE ASIDE MIRRORS THE RAIL. A panel the whole frame keeps open beside every
+ * screen (the assistant) is a third track of the shell's grid, a second sheet
+ * on the frame to the right of the page's, so opening it PUSHES the page
+ * narrower rather than covering it. Nothing about the page changes but its
+ * width: the bar, the sticky headers, the one scroller and the measured
+ * gutter are all the sheet's, and the sheet keeps them. Where the window
+ * cannot hold the page and the panel side by side the panel is an overlay
+ * over the page's end, and on a phone it is the whole window; both are
+ * modal surfaces on the shared layer stack. WHICH SHAPE is the host's
+ * decision (`asideShape`), never a media query's: the width that leaves the
+ * page its floor depends on what else the frame holds and on the density,
+ * which only the application knows.
+ *
+ * AND THE PEEK IS A COLUMN OF THE SHEET. A detail panel opened from a list
+ * (`peek`) stands beside the scroller inside the sheet, under the bar, so the
+ * section the reader is on still reads across the top. It is a column where
+ * the host says there is room and a drawer over the page where there is not.
  */
 import { type AriaAttributes, type HTMLAttributes, type MouseEventHandler, type ReactNode, type Ref } from 'react';
 import type { Tone } from '../utils/tone.js';
+import { type AppShellAsideShape, type AppShellPeekShape } from './regions.js';
+export { useAppShellAside, useAppShellPeek } from './regions.js';
+export type { AppShellAsideShape, AppShellPeekShape, AppShellRegionValue } from './regions.js';
+/** The aside's resting width, in px, where the host names none. */
+export declare const APP_SHELL_ASIDE_WIDTH = 420;
+/** How the reader resizes the aside while it is a column. */
+export interface AppShellAsideResize {
+    /** The narrowest the aside may be, in px. */
+    min: number;
+    /** The widest, in px, already capped by the host so the page keeps its floor. */
+    max: number;
+    /** The resting width a reset returns to. */
+    defaultValue?: number | undefined;
+    /** Every change while it happens. */
+    onChange: (width: number) => void;
+    /** Where a gesture ends: the moment to keep the width. */
+    onCommit?: ((width: number) => void) | undefined;
+    /** Names the grip: "Resize the assistant panel". */
+    label: string;
+}
 /** What the shell tells the components inside it. */
 interface AppShellContextValue {
     /** Whether the layout is below the shell breakpoint. */
@@ -97,9 +135,43 @@ export interface AppShellProps extends Omit<HTMLAttributes<HTMLDivElement>, 'tit
     toggleLabel?: string | undefined;
     /** The link that precedes everything, for a keyboard reader. */
     skipLabel?: string | undefined;
+    /**
+     * A panel the frame keeps beside every screen: the assistant. Nothing (or
+     * null) means no aside and no track. Normally a `SidePanel`, which leaves
+     * the landmark, the width and the grip to the shell here.
+     */
+    aside?: ReactNode;
+    /** The aside's width while it is a column or an overlay, in px. */
+    asideWidth?: number | undefined;
+    /**
+     * The page's floor beside an aside column, in px: the column's track is
+     * capped at what leaves the sheet this wide, so a width dragged on a wide
+     * window never takes a narrower window's page away.
+     */
+    asideReserve?: number | undefined;
+    /** Names the complementary region and, as an overlay or a sheet, the dialog. */
+    asideLabel?: string | undefined;
+    /** Which shape the aside takes; the host decides it. */
+    asideShape?: AppShellAsideShape | undefined;
+    /** Closes the aside: Escape and a press on the veil, as an overlay or a sheet. */
+    onAsideClose?: (() => void) | undefined;
+    /** Gives the aside a grip in the seam beside it while it is a column. */
+    asideResize?: AppShellAsideResize | undefined;
+    /**
+     * A detail panel beside the scroller, inside the sheet and under the bar:
+     * a peek opened from a list. Normally a `PeekRail`.
+     */
+    peek?: ReactNode;
+    /**
+     * Whether the peek is a column of the sheet or a drawer over the page; the
+     * host decides it. The peek sizes itself (`PeekRail` takes its width and
+     * the page's floor), because a column of the sheet is the peek's own box
+     * rather than a track of the frame.
+     */
+    peekShape?: AppShellPeekShape | undefined;
     children?: ReactNode;
 }
-export declare function AppShell({ sidebar, topbar, banner, footer, mainId, mainRef, fill, navigationKey, toggleLabel, skipLabel, className, style, children, ...rest }: AppShellProps): import("react").JSX.Element;
+export declare function AppShell({ sidebar, topbar, banner, footer, mainId, mainRef, fill, navigationKey, toggleLabel, skipLabel, aside, asideWidth, asideReserve, asideLabel, asideShape, onAsideClose, asideResize, peek, peekShape, className, style, children, ...rest }: AppShellProps): import("react").JSX.Element;
 export declare namespace AppShell {
     var Rail: typeof AppShellRail;
     var RailRow: import("react").ForwardRefExoticComponent<AppShellRailRowProps & import("react").RefAttributes<HTMLElement>>;
@@ -107,6 +179,7 @@ export declare namespace AppShell {
     var Topbar: typeof AppShellTopbar;
     var Toggle: typeof AppShellToggle;
     var AccountRow: typeof import("./AccountRow.js").AccountRow;
+    var ResizeHandle: typeof import("./ResizeHandle.js").ResizeHandle;
 }
 export interface AppShellRailProps {
     /**

package/dist/AppShell/ResizeHandle.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The grip that sizes a panel standing beside the page: the assistant in the
+ * shell's aside, a peek beside a list, a side panel beside an artifact.
+ *
+ * A SEPARATOR WITH A VALUE. It is `role="separator"` with
+ * `aria-orientation="vertical"` and the panel's width as `aria-valuenow`
+ * between `aria-valuemin` and `aria-valuemax`, which is the WAI-ARIA window
+ * splitter: a screen reader hears what it sizes and where it stands, and the
+ * keyboard moves it. The grip it replaces was mouse only, which left a reader
+ * without a pointer with whatever width somebody else had dragged.
+ *
+ * THE KEYS. Left and Right move the edge by `step` (16px), with Shift by
+ * `largeStep` (64px); Home and End take the panel to its narrowest and its
+ * widest; Enter or a double press puts it back at `defaultValue`. The edge
+ * moves the way the arrow points, so on a panel's left edge ArrowLeft widens
+ * it and on a right edge it narrows it.
+ *
+ * THE POINTER. A drag is measured from where it started, not from the
+ * window's edge: a panel inside an inset sheet stands a hairline and an inset
+ * in from the window, and a width read as `innerWidth - clientX` runs ahead
+ * of the hand by exactly that much. The pointer is captured, so a drag that
+ * leaves the grip, or the window, keeps sizing until it is released.
+ *
+ * TWO CALLBACKS, because the two moments are different: `onValueChange` for
+ * every step of a drag, to draw it, and `onValueCommit` once, where the
+ * gesture ends, to keep it. A preference written on every pointer move is a
+ * storage write per frame.
+ *
+ * Drawn as nothing at rest, a soft accent wash under the pointer, under
+ * focus and while dragging, and a 24px target whatever its drawn width.
+ */
+/** The step an arrow key moves the edge by, in px. */
+export declare const RESIZE_HANDLE_STEP = 16;
+/** The step Shift with an arrow key moves it by, in px. */
+export declare const RESIZE_HANDLE_LARGE_STEP = 64;
+export interface ResizeHandleProps {
+    /** The size the handle controls, in px. */
+    value: number;
+    /** The narrowest the panel may be, in px. */
+    min: number;
+    /**
+     * The widest, in px. A host that caps the panel so the page beside it
+     * keeps its floor passes the cap here, so End and a drag both stop where
+     * the panel is actually drawn.
+     */
+    max: number;
+    /** Every change, while it happens: a drag's move, a key's step. */
+    onValueChange: (value: number) => void;
+    /** Where a gesture ends (a released drag, a key, a reset): the moment to persist. */
+    onValueCommit?: ((value: number) => void) | undefined;
+    /** The resting size Enter and a double press return to. Without one neither does anything. */
+    defaultValue?: number | undefined;
+    /** Names the separator: "Resize the assistant panel". */
+    label: string;
+    /**
+     * Which edge of the sized panel the handle stands on. On the `left` edge
+     * (a panel at the window's right) moving the edge left widens the panel;
+     * on the `right` edge (a panel at the left) moving it right does. The
+     * shell is drawn left to right throughout, so the edge is physical.
+     */
+    edge?: 'left' | 'right' | undefined;
+    /** The element the handle sizes, by id. */
+    controls?: string | undefined;
+    /** What the value is read as: "420 pixels". */
+    valueText?: ((value: number) => string) | undefined;
+    /** The step an arrow key moves the edge by. */
+    step?: number | undefined;
+    /** The step Shift with an arrow key moves it by. */
+    largeStep?: number | undefined;
+    className?: string | undefined;
+}
+/** A width held inside its bounds, in whole pixels. */
+export declare function clampSize(value: number, min: number, max: number): number;
+export declare function ResizeHandle({ value, min, max, onValueChange, onValueCommit, defaultValue, label, edge, controls, valueText, step, largeStep, className, }: ResizeHandleProps): import("react").JSX.Element;

package/dist/AppShell/index.d.ts

@@ -1,6 +1,11 @@
 import '../HitArea/HitArea.css';
 import './AppShell.css';
-export { AppShell, AppShellRail, AppShellRailRow, AppShellRailStatus, AppShellToggle, AppShellTopbar, useAppShell } from './AppShell.js';
+import './ResizeHandle.css';
+export { APP_SHELL_ASIDE_WIDTH, AppShell, AppShellRail, AppShellRailRow, AppShellRailStatus, AppShellToggle, AppShellTopbar, useAppShell, useAppShellAside, useAppShellPeek, } from './AppShell.js';
+export { RESIZE_HANDLE_LARGE_STEP, RESIZE_HANDLE_STEP, ResizeHandle, clampSize } from './ResizeHandle.js';
+export type { ResizeHandleProps } from './ResizeHandle.js';
+export { readStoredWidth, useStoredWidth } from './storedWidth.js';
+export type { StoredWidth, StoredWidthOptions, WidthStorage } from './storedWidth.js';
 export { AccountRow } from './AccountRow.js';
 export type { AccountRowMenu, AccountRowProps } from './AccountRow.js';
-export type { ActionRailRowProps, ActionRailStatusProps, AppShellContextValue, AppShellProps, AppShellRailProps, AppShellRailRowProps, AppShellRailStatusProps, AppShellToggleProps, AppShellTopbarProps, RailRowCount, StaticRailRowProps, StaticRailStatusProps, } from './AppShell.js';
+export type { ActionRailRowProps, ActionRailStatusProps, AppShellAsideResize, AppShellAsideShape, AppShellContextValue, AppShellPeekShape, AppShellProps, AppShellRailProps, AppShellRailRowProps, AppShellRailStatusProps, AppShellRegionValue, AppShellToggleProps, AppShellTopbarProps, RailRowCount, StaticRailRowProps, StaticRailStatusProps, } from './AppShell.js';

package/dist/AppShell/index.js

@@ -1,11 +1,13 @@
-export { AccountRow, AppShell, AppShellRail, AppShellRailRow, AppShellRailStatus, AppShellToggle, AppShellTopbar, useAppShell } from '../chunk-34ANLQW2.js';
+export { APP_SHELL_ASIDE_WIDTH, AccountRow, AppShell, AppShellRail, AppShellRailRow, AppShellRailStatus, AppShellToggle, AppShellTopbar, readStoredWidth, useAppShell, useStoredWidth } from '../chunk-UVYGMCJ4.js';
 import '../chunk-RTPQDNW3.js';
-import '../chunk-TMM32U7D.js';
+import '../chunk-TKS7FTTO.js';
+export { RESIZE_HANDLE_LARGE_STEP, RESIZE_HANDLE_STEP, ResizeHandle, clampSize, useAppShellAside, useAppShellPeek } from '../chunk-PIYJNCN7.js';
+import '../chunk-HD4QJ2SI.js';
+import '../chunk-EA23JG6R.js';
 import '../chunk-OMV5W53A.js';
 import '../chunk-2YTOOH3A.js';
-import '../chunk-OG6CL3EB.js';
 import '../chunk-H5XTJ7GJ.js';
-import '../chunk-LACA4JGC.js';
+import '../chunk-2BQYODY3.js';
 import '../chunk-NUZHC6MM.js';
 import '../chunk-BZFWDIV6.js';
 import '../chunk-ODEQTPFM.js';

package/dist/AppShell/regions.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Where a component stands in the shell: the aside, or the peek slot.
+ *
+ * Its own module, so a panel that asks (`SidePanel`, `PeekRail`) carries the
+ * question and not the whole shell.
+ */
+/**
+ * The shape the aside takes, decided by the host from its own arithmetic.
+ *
+ * - `column`: a track of the frame's grid beside the sheet, a complementary
+ *   region; the page reflows narrower and stays reachable with Tab.
+ * - `overlay`: over the page's end edge, behind a veil, a modal dialog: Tab
+ *   stays in it, Escape and a press on the veil close it, focus returns.
+ * - `sheet`: the whole window, for a phone; modal in the same way.
+ */
+export type AppShellAsideShape = 'column' | 'overlay' | 'sheet';
+/** The shape a peek takes beside the scroller: a column of the sheet, or a drawer over the page. */
+export type AppShellPeekShape = 'column' | 'drawer';
+/** What a component inside the aside or the peek is told about where it stands. */
+export interface AppShellRegionValue<Shape extends string> {
+    shape: Shape;
+}
+export declare const AsideContext: import("react").Context<AppShellRegionValue<AppShellAsideShape> | null>;
+export declare const PeekContext: import("react").Context<AppShellRegionValue<AppShellPeekShape> | null>;
+/**
+ * The aside this component stands in, or null outside one.
+ *
+ * Null rather than a throw, unlike `useAppShell`: a side panel is drawn in
+ * the shell's aside and in a frame of its own, and it asks which so it can
+ * leave the landmark, the width and the grip to the shell when it is here.
+ */
+export declare function useAppShellAside(): AppShellRegionValue<AppShellAsideShape> | null;
+/** The peek slot this component stands in, or null outside one. */
+export declare function useAppShellPeek(): AppShellRegionValue<AppShellPeekShape> | null;

package/dist/AppShell/storedWidth.d.ts

@@ -0,0 +1,47 @@
+/**
+ * A width the reader dragged a panel to, kept per browser.
+ *
+ * NULL WHERE THEY NEVER DRAGGED ONE, rather than a default: the resting width
+ * is the host's (a canvas may rest a panel narrower than a list does), and a
+ * preference that answered with a default when nothing was stored would read
+ * as a reader who chose it.
+ *
+ * WHAT IS STORED IS A NUMBER AND NOTHING ELSE. A stored value is read back
+ * only when it is a finite number inside the bounds, so a value another
+ * build wrote, a hand-edited one, or one outside today's bounds is ignored
+ * rather than trusted. Storage that cannot be read or written (a private
+ * window, a blocked origin, a full quota) leaves the width working for the
+ * session: a preference is a convenience, never a reason to draw no panel.
+ *
+ * The key is the caller's, so an application keeps every storage key it
+ * writes in one registry of its own.
+ */
+/** The part of `Storage` the hook reads and writes. */
+export interface WidthStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+export interface StoredWidthOptions {
+    /** The storage key, from the application's own registry. */
+    key: string;
+    /** The narrowest width that is kept, in px. */
+    min: number;
+    /** The widest, in px. */
+    max: number;
+    /**
+     * Where the width is kept. The browser's `localStorage` when left out;
+     * `null` keeps it for the session only.
+     */
+    storage?: WidthStorage | null | undefined;
+}
+export interface StoredWidth {
+    /** The width the reader chose, or null where they never chose one. */
+    width: number | null;
+    /** Draw a width without keeping it: a drag's every move. */
+    setWidth: (px: number) => void;
+    /** Draw a width and keep it: where a drag or a key press ends. */
+    commitWidth: (px: number) => void;
+}
+/** The stored width, when it is one this panel can take; null otherwise. */
+export declare function readStoredWidth(storage: WidthStorage | null, key: string, min: number, max: number): number | null;
+export declare function useStoredWidth({ key, min, max, storage }: StoredWidthOptions): StoredWidth;