npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@adea-ai/ui

v0.158.0

Published

The Adea design system: Kobalte-backed Solid components, semantic OKLCH tokens, and the app-shell layout primitives shared by Adea and Cortana.

Readme

@adea-ai/ui

The shared Solid component library for Adea and Cortana. Applications retain their domain compositions, persistence, services, and native capabilities.

bun add @adea-ai/ui

Built on SolidJS, Tailwind v4, Kobalte and corvu. solid-js is a peer, and the four heavy optional peers (chart.js, embla-carousel, embla-carousel-solid, solid-chartjs) are marked optional so installing the library does not drag in a charting or carousel engine you never use.

Contents

Getting started

Import the stylesheet and wrap your app in the provider.

import { ThemeProvider } from '@adea-ai/ui/components/theme'
import '@adea-ai/ui/globals.css'

export function App() {
  return (
    <ThemeProvider>
      <YourApp />
    </ThemeProvider>
  )
}

ThemeProvider is what applies a theme, an accent and a typeface, and what persists the choice. Without it you get the two default variants and nothing else.

Tailwind ignores dependency directories by default. Register the component directories your application uses in its stylesheet, relative to that stylesheet:

@import 'tailwindcss';
@import '@adea-ai/ui/theme.css';
@import '@adea-ai/ui/base.css';
@import '@adea-ai/ui/appearance-font-settings.css'; /* optional: shared font roles and Appearance controls */
@source '../node_modules/@adea-ai/ui/src/components/ui/button';

globals.css combines Tailwind, base styles, and theme tokens. Fonts require a separate explicit @adea-ai/ui/fonts.css import. The packed-artifact gate expands all component and library export conditions and rejects leaked story/test files, including declaration output.

Entry points

Folder subpaths such as @adea-ai/ui/components/ui/button resolve the folder's public index under the types, Solid source, development, and compiled conditions. The package includes source for Solid compilation and Tailwind discovery, and compiled JavaScript plus declarations for other supported consumers. License and donor notices travel in dist/LICENSE and dist/NOTICE.

For shortcut labels in server-side or other non-UI code, import platformModifierKey from @adea-ai/ui/components/ui/kbd/platform-modifier. This entry does not load the keyboard components; the keyboard folder entry continues to export the same helper for component consumers.

Charts and carousels are exported only from their subpaths, so root imports work without their optional peers:

import { Button } from '@adea-ai/ui'
import { LineChart } from '@adea-ai/ui/components/ui/chart'
import { Carousel, CarouselSlide } from '@adea-ai/ui/components/ui/carousel'

Install chart.js and solid-chartjs for charts, or embla-carousel and embla-carousel-solid for carousels. Their helpers and types live on the same subpaths.

Split-layout tree imports

Scoped persistence decoders can import MAX_LAYOUT_LEAVES, MAX_LAYOUT_DEPTH, MIN_SPLIT_RATIO, MAX_SPLIT_RATIO, listLeaves, countLeaves, layoutDepth, and the opaque tree types from @adea-ai/ui/components/layout/split-layout/tree. This read-only entry has no UI runtime, renderer, or pane-editing dependencies. The existing /model entry re-exports the same functions and types for compatibility. Use /model for split, close, move, resize, and undo operations; use the component entry when rendering the layout.

Theming

The catalogue is 34 themes across two appearances, grouped into families. The provider takes an initial selection and every axis is a plain value:

<ThemeProvider
  initial={{
    appearance: 'system', // 'light' | 'dark' | 'system'
    lightThemeId: 'adea-light',
    darkThemeId: 'adea-dark',
    accent: 'theme', // or 'violet' | 'blue' | 'green' | 'amber' | 'cyan' | 'pink',
    //                    or a theme-carried accent such as 'ansi-blue'
    fonts: {
      ui: { family: 'system', size: 14 },
      content: { family: 'system', size: 14 },
      code: { family: 'system', size: 12 },
    },
  }}
>

| Axis | Values | How it is applied | | ---------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | Appearance | light, dark, system | a dark class plus color-scheme on <html> | | Theme | any of the 34 catalogue ids | the variant's tokens, written as custom properties on <html> | | Accent | theme (follow the variant), one of six presets, or an accent the theme pair carries (ansi-blue…) | a data-accent attribute on <html>, plus the resolved roles as custom properties | | Fonts | UI, content and code family ids from the shared catalogue; sizes from 10–32px | Stable data-*-font ids plus resolved --font-* family and pixel-size properties |

Older single-font font preferences remain readable and migrate their family to the UI axis; new preferences store fonts with one family and size per axis. Canonical size properties stay in pixels for native editor integrations; the shared text tokens use rem-relative ratios so browser root-text enlargement still scales UI, prose, keyboard keys and code.

Read and change the current selection with useTheme():

const { selection, resolvedAppearance, setSelection, themes, themeAccents } = useTheme()
setSelection({ accent: 'amber' })

themeAccents() lists the accents the selected light/dark theme pair carries itself (@adea-ai/themes' themeAccentPresets): the palette's own blue, magenta, cyan and green, offered only when both themes clear the catalogue's accent floors. Their ids are role-shaped, so ansi-blue follows a theme switch to the new theme's blue; a slot the new pair cannot offer falls back to the theme's own primary. The primary grid is the theme default plus five standard presets; Violet remains available under Additional colors, and theme accents have their own group.

Two components ship for the settings surface: AppearancePanel is the whole appearance view, and ThemeToggle is the light/dark switch on its own.

SettingsLayout composes a controlled vertical tab root, grouped SettingsNavigation, and a scrollable panel viewport. Supply the selected value, onChange, navigation groups, and matching TabsContent panels. The host owns URL or preference updates and panel content; below 48rem of viewport width the rail becomes a horizontal, scrollable strip of tabs above the panels (groups in order, Left/Right keys, aria-orientation="horizontal"), and navigationLayout="rail" | "strip" pins one shape at every width. The layout reports repeated activation through onReselect and reveals the selected row on either axis by default. Use SettingsNavigation directly when you already own the surrounding tabs composition; it follows the enclosing Tabs orientation. Shared tabs associate panels with custom trigger IDs in browser and server renders; an explicit panel aria-labelledby takes precedence. Independent tab roots keep their associations separate.

Controlled appearance mode

ThemeModeToggle provides the shared light/dark/system selector for hosts that own their preference provider and storage. Pass mode and onModeChange; the control owns roving keyboard focus, pressed state and explanatory tooltips. It does not require or mount the shared ThemeProvider. ThemeToggle retains its existing provider-bound API.

Controlled appearance editor

AppearanceEditor and AppearancePopover retain the accepted Zeron-derived System/Light/Dark miniature cards, independent light/dark theme rows, palette swatches, default/preset/custom accent choices and Theme default/Frosted/Opaque surface choices. The popup supports live host preview and Save/Cancel/Reset; Kobalte provides radio navigation, selection, dismissal and focus restoration. Since its menus prevent Tab, the theme row carries Tab and Shift+Tab through the enclosing dialog's focus order. DropdownMenuContent.portalMount keeps the theme menu within its enclosing modal's accessible subtree.

Supply canonical AdeaTheme previews and AdeaThemeRecord choices. themeRecords/themeRecordById export those records, and appearancePreviewThemes({ lightThemeId, darkThemeId, accent }) resolves a draft's ids and accent, a preset or a theme-carried accent, into the two preview themes, exactly as ThemeProvider would apply them; withAccent is the overlay on its own. builtinThemes is the shadcn projection a document is painted with, not an editor input. Pass themeAccentOptions, themeAccentsFor(lightThemeId, darkThemeId), to offer the accents the previewed pair carries after the presets; the editor itself loads no catalogue or normalization. Hosts own saved-ID recovery, validation, draft snapshots, System appearance resolution, native transparency, live application tokens, Save persistence and restoration on Cancel/dismissal. saving, saveDisabledReason, recoveryNotice, customAccentError, and surfaceCapability expose those outcomes; an unavailable import or Frosted capability stays visibly unavailable. App-specific persisted versions and the legacy translucent value need an app-owned adapter to the editor's theme surface selection. The library does not silently migrate stored preferences.

A host recomposes the editor through props, never by forking it. Every option keeps the default below, so an existing consumer renders as before:

| Prop | Default | What it changes | | -------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | fontSettingsPlacement | inline | end closes the option list with the typefaces, after Glass, Reduce transparency and Theme library. | | accentEntryStyle | swatches | labels renders every choice as a named chip. row draws the presets as circles in one equally spaced line (it holds at 320px, where the grid wraps) and turns Custom into a button that opens the native colour selector: only a chosen colour changes the draft. | | showThemeDefaultAccent | true | false drops the leading "Theme default" entry, for a host whose default accent already is a preset. | | showCustomAccentCaption | true | false drops the "Custom" caption over the swatches style's custom chip. No effect on labels or row. | | showModeIcons | false | A sun, moon or monitor glyph beside each mode card's label. | | triggerVariant (popover) | ghost | toolbar holds the pressed rung while the sheet is open and repeats the palette glyph in the tooltip, like the other toolbar actions. |

customAccentValue seeds the native selector (row) and the draft the swatches Custom chip commits; hand it your starting colour.

Avoiding the flash

A themed app has to know the appearance before the first paint, or it paints once in the wrong mode. themeScript emits the inline script that does it:

<head>
  <script innerHTML={themeScript('my-app-appearance')} />
</head>

Pass the same key to ThemeProvider as storageKey, and the two agree.

Fonts

Font preference roles and font assets are separate opt-ins. Import appearance-font-settings.css after the theme and base styles to enable the shared UI/content/code projections and utilities. globals.css does not import font assets; import fonts.css explicitly when those faces are wanted:

@import '@adea-ai/ui/theme.css';
@import '@adea-ai/ui/base.css';
@import '@adea-ai/ui/appearance-font-settings.css';
@import '@adea-ai/ui/fonts.css'; /* omit to bring your own */

appearance-font-settings.css defaults --font-ui, --font-content and --font-code to System and scales each text role. Import it after theme.css and base.css, then apply settings with the shared runtime or prepaint helper; the helper resolves catalogue ids to family tokens and writes canonical pixel sizes. This stylesheet does not load any font files. The font-ui-size, font-content-size and font-code-size entries in the token gallery are runtime-projected properties: applyAppearanceFontSettings and fontSettingsBootstrapScript write their pixel values from normalized font settings. They are not fixed declarations in the theme stylesheet. --font-sans and --font-mono remain compatibility aliases for UI and code. The shared projection and prepaint helpers are exported from @adea-ai/ui/lib/appearance-font-settings; hosts can normalize persisted ids, apply the shared data attributes, resolve family ids through the published --font-family-* tokens, and reuse the same bootstrap snippet without duplicating catalogue rules. For versioned host preferences, pass the expected version as the bootstrap helper's second argument. Only an exact version match is applied before paint; missing or unsupported records use the System defaults. Omitting the argument retains the unversioned helper behavior. Each UI, Content and Code chooser keeps the complete font catalogue, and Code uses the exact selected catalogue family. Choose a Mono option when you want a monospace face; System uses the platform's monospace counterpart for Code.

Forms and navigation

Use NativeSelect for a compact list of known choices that should keep native keyboard, form submission, option, and label behavior:

import { NativeSelect } from '@adea-ai/ui/components/ui/native-select'
import { Label } from '@adea-ai/ui/components/ui/label'

<Label for="relationship-kind">Relationship kind</Label>
<NativeSelect
  id="relationship-kind"
  name="relationshipKind"
  value={kind()}
  onChange={handleChange}
  options={[
    { value: 'all', label: 'All relationships' },
    { value: 'derived', label: 'Derived' },
  ]}
/>

NativeSelect renders a real <select> and passes native props and children through. Use value with onChange for a controlled selection, or defaultValue to initialize an uncontrolled one. Use Select for searchable, runtime, or longer lists that need a custom popover.

InputControl is the styled native input without suggestion-list behavior. Use Input when a form should offer native datalist suggestions; custom values remain valid and submit unchanged. The library owns the datalist and unique association; a suggestion does not restrict the submitted value. Native required, pattern, form, event, and ref props still apply to the input.

ModalDialog defaults to a compact surface for short tasks. Use size="settings" with SettingsPage for a wider, viewport-bounded settings surface; the shared layout keeps its panel content scrollable while the dialog title remains visible.

ThreadPanel.headerActions accepts shared controls for host actions such as marking a thread unread. Closing the thread remains a separate labelled, tooltip-backed control. Hosts retain read-marker and message authority.

AccountMenu owns the trigger tooltip, menu keyboard behavior, and session row. Pass size to match its host control size. Use an item's onSelect for an immediate action, or onSelectAfterClose to open a dialog after the menu has finished closing. The latter receives the connected trigger button for dialog focus restoration and is cancelled if the menu unmounts. Authentication, updates, navigation, and other effects remain host callbacks.

SidebarNavTitle accepts polymorphic as for a host's title heading. SidebarNavLabel keeps a row's complete accessible text while truncating its visible label, leaving room for adjacent controls. The navigation root clamps its preferred width to the containing lane at narrow widths and enlarged root text. SidebarNavRow moves adjacent actions onto a second line when the item's preferred label space and the controls cannot fit together. Row and section actions remain visible when any coarse pointer is available, including on hybrid devices; hover, keyboard focus, and an expanded menu continue to reveal them as well. Action hit-area size remains determined by the supplied shared control size. Use SidebarNavSection.headingAs (h1 through h6) for section headings. Sections may be uncontrolled with defaultOpen or controlled with open and onOpenChange. Put disclosure-button attributes and host-owned row interactions in triggerProps; its onClick and onKeyDown run before shared behavior, and preventDefault() cancels the corresponding toggle or Alt+Arrow reorder callback. triggerProps.onReorder receives up or down; the host remains responsible for updating its hierarchy and preserving stable row identity. Disclosure buttons stay inside their heading and trailing actions stay outside it, preserving hierarchy and independent keyboard actions.

Board checks the caller's legal-move predicate before settling a pointer drop. Ctrl/Cmd + arrow moves skip disabled columns without wrapping at the edges. After a controlled move settles, focus follows the moved card only when the source card owned focus; another focus or pointer action cancels restoration.

Square icon controls use the control-height tokens through the Tailwind --size mapping; --spacing-control-* remains the separate inline-padding ladder. Text controls, icon buttons and toggles share the same height in both densities. Dimensions remain rem-based and follow the consumer's root font size. The browser geometry lane checks the standard density rungs, heights and padding under both themes/densities; the 2xl touch target remains 48px under compact density.

On narrow screens, the shared TopBar keeps a usable middle Search target while side groups scroll horizontally when their actions do not fit. Keyboard focus reveals each action. Groups opt out of native window dragging. Use TopBarTitle align="center" to center text within its slot; the host controls slot placement. Use layout-only visibility classes when a title should yield space to essential controls.

Catalog browser

CatalogBrowser presents a host-owned searchable catalog with ordered category groups, discover/installed tabs, bounded group expansion, optional filters and supplemental tabs. Give entries the full set of detail records so opening an item remains stable when a query or tab filters the visible groups. The host owns catalog verification, filtering, installed state, permission decisions, errors, and actions. Selecting an item opens its host-rendered detail and returns focus to the originating result when Back is chosen. CatalogDetail provides the shared item summary/action frame and CatalogDetailSection gives host-specific permissions or metadata a shared section surface. Supply resultsRegionLabel and detailRegionLabel to name their keyboard-focusable, shared ScrollArea regions. The results area scrolls notices along with loading, empty, and error states even when those states contain no interactive control. Use CatalogDetail sectionsLayout="columns" for related detail fields in a single padded, outlined card. Its sections share dividers on wide screens and stack on narrow screens; hosts should pass CatalogDetailSection children directly and use no local padding or border overrides. The default keeps separate section cards.

import {
  CatalogBrowser,
  CatalogDetail,
  CatalogDetailSection,
  type CatalogBrowserEntry,
  type CatalogBrowserGroup,
} from '@adea-ai/ui/components/composites/catalog-browser'

const entries: readonly CatalogBrowserEntry<VerifiedPlugin>[] = /* all detail records */ []
const groups: readonly CatalogBrowserGroup<VerifiedPlugin>[] = /* visible filtered groups */ []

<CatalogBrowser
  open={open()}
  tabs={[
    { id: 'discover', label: 'Discover' },
    { id: 'installed', label: 'Installed' },
    { id: 'navigation', label: 'Navigation', kind: 'supplemental' },
  ]}
  tab={tab()}
  tabsLabel="Catalog views"
  onTabChange={setTab}
  query={query()}
  onQueryChange={setQuery}
  searchLabel="Search catalog"
  searchPlaceholder="Search applications"
  resultsRegionLabel="Catalog results"
  resultCount={visibleCount()}
  resultLabel={(count) => `${count} applications`}
  loadingLabel="Loading catalog"
  status={catalogStatus()}
  catalogError={catalogError()}
  emptyState={emptyState()}
  groups={groups}
  entries={entries}
  selectedId={selectedId()}
  onSelect={(plugin) => setSelectedId(plugin.id)}
  onBack={() => setSelectedId(null)}
  backLabel="Back to catalog"
  detailRegionLabel="Application details"
  installedLabel="Installed"
  publishedByLabel={(publisher) => `Published by ${publisher}`}
  showMoreLabel={(hidden) => `See ${hidden[0]?.name} and more`}
  showLessLabel="Show less"
  renderIcon={(plugin) => <PluginIcon plugin={plugin} />}
  renderDetail={(plugin) => (
    <CatalogDetail
      title={plugin.name}
      description={plugin.description}
      category={plugin.category}
      publisher={plugin.publisher}
      publishedByLabel={(publisher) => `Published by ${publisher}`}
      action={<InstallButton plugin={plugin} />}
    >
      <CatalogDetailSection title="Permissions">
        <PluginPermissions plugin={plugin} />
      </CatalogDetailSection>
    </CatalogDetail>
  )}
  renderSupplementalView={(id) => (id === 'navigation' ? <NavigationSettings /> : undefined)}
/>

The CatalogBrowser story demonstrates category expansion, search, separate installed content, a supplemental navigation surface, and host-provided details.

Catalog detail summaries place actions and feedback beneath identity on narrow screens, preserving readable title/description flow. Grouped field sections keep their content at the top while sharing the outline and dividers.

Composer

Chat composer

ChatComposer translates the pinned Kiro composer hierarchy: knowledge context, follow-ups and adjacent band, approval/notices, staged content, input/action rows and the context shelf. It composes the existing IME and busy-action units. Its optional controlled collapse contract unmounts input and shelf and replaces them with a labeled bar showing the waiting draft's first line. Collapse keeps the host draft and caret selection; controlRef exposes instance-scoped focus()/expandAndFocus() instead of a global shortcut or broadcast.

The host supplies value, onValueChange and onSubmit({text, action}); it owns attachments and runtime authority and clears its draft only after confirmation. The shared input guards pending delivery, reports failure, visibly blocks unsupported delivery and fences local feedback on resetKey. Enter follows the controlled busy mode, while Ctrl/Cmd+Enter requests the other supported busy action. sendableActions declares non-text payload eligibility per action: a reference-only draft can send or queue without becoming steerable. Explicit false also vetoes delivery when the draft contains text; alternate-action hints appear only when that action is eligible. Mode selection itself never fires. approvalFocus is host-derived presentation, not a permission decision. Agent and model controls remain distinct host contributions in context.

Sent-prompt history, manual resize, uploads, voice and stop/resume are not part of the shared composer; hosts build them.

sendableActions is the host's payload eligibility contract: explicit false refuses that action even with typed text, explicit true supports structured payloads without text, and omitted entries fall back to nonempty text. Selecting an unavailable action cannot override this contract through keyboard delivery.

Keyboard and IME

MessageComposer preserves native IME candidate commits and suppresses sending during composition, including the 50 ms commit window when browser flags have already cleared. A separate Enter sends after that window; Shift+Enter remains a soft break. A host or menu that already prevented the event keeps ownership. The selected KiroCrew textarea guard is translated to Solid ownership; it adds no document listener or application session state. Source and license details are retained in NOTICE.

The field contract addresses the textarea itself: inputRef receives its native HTMLTextAreaElement, inputId assigns its stable id, and inputLabel, inputDescription and inputDescribedBy provide its accessible name and help. The default inputSize="comfortable" uses the shared 4rem minimum and 12rem maximum; inputResize selects one of the Textarea's named resize behaviors. Textarea owns both its standalone and borderless variant="composer" appearances, so consumers do not need to style a nested control.

Busy send button

BusySendButton translates KiroCrew's split fire/mode-picker composition. Pass controlled mode, onModeChange and onFire. disabled prevents firing while leaving mode choice available before typing; selectionDisabled gates choosing. Inject unavailable reasons for unsupported or unauthorized modes: rows remain visible, and the selected action cannot fire. Supply alternateActionHint only when the host implements the described keyboard chord. The component adds no keyboard chord, preference storage, runtime command or queue. Persistence and same-session preference synchronization remain application-owned.

Kobalte owns the menu and focus lifecycle. Its Tab prevention lacks row cycling, so a menu-scoped donor translation cycles enabled rows without a document listener. Stories cover before-typing, working, unavailable and read-only states.

Paste tokens

@adea-ai/ui/components/conversation also exports the pure paste-token model: PasteBlock, isPasteBlock, countLines, shouldCollapse, nextSeq, formatToken, findTokenRanges, tokenRangeAt, pruneBlocks, expandAll, recollapsePastes, remapCarriedBlocks, stripTrailingBlankLines, and the threshold and marker constants. Hosts provide stable, bounded ASCII block IDs and own draft state, persistence, message reconciliation and editor behavior. The model does not read storage or the clipboard, upload files, edit a textarea, or provide undo/history, previews or chips. The opt-in editor below composes this pure model with a controlled textarea. Source attribution is in NOTICE.

Atomic paste editor

ChatComposer keeps its plain-text API and bundle closure. Consumers that need atomic paste editing import AtomicChatComposer from the direct @adea-ai/ui/components/conversation/atomic subpath. It accepts host-owned blocks, a synchronous createBlockId() and one onChange({ text, blocks }) callback. Paste, native typing and pruning report the complete draft together. Submit receives one snapshot containing text, the selected action and cloned referenced blocks before delivery starts. Both entries share a private composition shell; the UI owns no paste identity, history, storage, transport or undo state.

The editor collapses text-only pastes at the existing three-line or 200-character thresholds, supports raw Cmd/Ctrl+Shift+V for the next paste, preserves standalone and Markdown quote-prefix placement, and keeps token deletion, navigation, selection and dropped-text replacement atomic. Double-click or touch expands a token. Copy and cut expand fully selected tokens in order while partial selections remain native. An aria-hidden mirror highlights tokens behind the single labeled textarea. Hover and caret previews wait 300 ms, scan and show at most 1,200 characters across up to 12 lines, close when their text/block/scope becomes stale, and stay suppressed on touch devices. Keyboard users can open the token next to the caret or current selection with Alt+Down Arrow and dismiss it with Escape. The input announces that shortcut and the open preview through aria-describedby while keeping focus in the textarea. The preview uses the existing tooltip portal without intercepting textarea input.

Only ClipboardEvent.clipboardData text is read. Clipboard permissions, images and files, uploads, rich editing, persistence and sent-prompt history stay with the host. The AtomicPasteTokens story shows the controlled contract.

Transcript

Following new output

ConversationSurface follows streamed text, earlier-row growth, turn collapse and pane resizing using the KiroCrew plain-scroller decision contract. A deliberate upward scroll releases follow, including small moves near the bottom. Returning to the bottom or choosing Jump to latest re-arms it; the action does not estimate unread messages from pixel distance. Instant pins keep self-scroll attribution synchronized. Keyboard jumping returns focus to the transcript when its jump control disappears; automatic pins never move focus.

threshold controls jump-button visibility (80px by default), independently of follow intent. follow={false} is fully inert: positioning belongs to the host, with no observer or mount pin. Re-enabling it explicitly re-arms at the bottom unless the host supplies initialReadingPosition: { top, following }. That snapshot is consumed only on mount, identity reset or follow re-enable; ordinary snapshot prop changes never reposition the reader. A parked snapshot releases follow until an explicit jump or native return to the bottom. The onReadingPositionChange callback reports native offset and actual follow intent, including small upward moves inside the jump visibility threshold. An optional resetKey resets follow or consumes the current identity's snapshot. Canonical session identity, durable restoration and virtualized transcript windows remain application-owned. ref and onScroll still reach the inner scroller.

The SurfaceFollowing story shows streaming, collapse and pane resizing.

Transcript composition

TranscriptComposition assembles ordered host-classified rows, contiguous groups, turn presentation and accessible fold controls. Import it from the public component subpath:

import {
  TranscriptComposition,
  type TranscriptCompositionRendererProps,
  type TranscriptRow,
} from '@adea-ai/ui/components/conversation/transcript-composition'

type Message = { text: string }
const rows: readonly TranscriptRow<Message>[] = [
  { id: 'question-1', value: { text: 'Inspect the cursor.' }, opensTurn: 'reset' },
  {
    id: 'tool-1',
    value: { text: 'Read the cursor.' },
    fold: 'tool',
    call: { phase: 'request', id: 'call-1' },
  },
]

function HostMessage(props: TranscriptCompositionRendererProps<Message>) {
  return <article>{props.row.value.text}</article>
}

export function TranscriptPreview() {
  return <TranscriptComposition rows={rows} renderRow={HostMessage} />
}

Each row needs a stable unique id within its transcript. The host supplies the Solid row component and classifies turn boundaries, calls, conclusions, always-visible actions and redacted values. The renderer does not parse protocol payloads or decide permission, session, event, delivery or success state.

Settled tool folds start closed and unmount their hidden row payloads. Live rows stay open until the host marks them settled; an explicit row choice survives that running-state transition. foldMode="prose" folds host-marked eligible activity before a host-designated conclusion, leaving that conclusion visible. The foldState="collapsed" command keeps hidden content mounted. It folds eligible rows before a host-marked conclusion; without that boundary it leaves prose visible and can still collapse explicitly classified tool calls. Always-visible rows stay in place. disclosure plus onDisclosureChange lets an application restore explicit choices from its own durable store using transcriptDisclosureKey.

Split layout

The split-layout model (adapted from bb/Muxy; see NOTICE) is pure: createLayoutState, splitPane, movePane, closePane, undoClosePane, focusPane, swapPanes, resizeSplit, normalizeLayout and the reading-order helpers. Leaves extend {kind: 'leaf', id: string} with any host-owned payload. Closing the last leaf calls an injected placeholder factory; it never selects a harness, starts a terminal or deletes a project. The limits are eight leaves, depth eight and 10 to 90 percent split ratios. Construct or validate a tree before editing it; the shared constructor validates visual structure and identities, while applications still decode/scoped-persist preferences and retain unknown future versions for recovery.

splitPaneBalanced(state, targetLeafId, { placement, leaf, splitId }) is an opt-in automatic reflow for hosts that want a new pane beside the selected pane in reading order. It keeps one row for one or two panes, starts a second row at three, and balances the row lengths through the eight-pane limit (two rows of four at the cap). Leaves in each row receive equal widths and both rows receive equal height; adding a pane can therefore redistribute existing pane widths. Opaque leaf objects are retained. Existing split ID strings are recycled across the rebuilt branches; an ID can acquire a different axis or descendants, so hosts must resolve resize actions against the current tree rather than cache a branch. The new split ID names the nearest common branch of the selected and new panes. The new pane is focused, and the close-undo stack is cleared like other structural edits. The explicit-axis splitPane operation is unchanged for hosts that do not want an automatic reflow.

No persistent state, session services, native drag region or host framework is imported into this model.

Host pane presentation

Controlled split ratios survive host visibility changes and disposal. Corvu panel registration and unregistration callbacks with incomplete sizes, and callbacks from detached or hidden roots, do not become host resize requests. Real pointer and keyboard resizing still flows through the same constrained callback.

SplitLayout can keep its default pane header while allowing a host to supply inline visible content with renderPaneLabel, opt pane regions into keyboard Tab navigation with paneTabIndex={0}, and provide a domain-specific splitter name with labelForSeparator. Pane regions remain programmatically focusable by default (paneTabIndex={-1}), and separators keep their orientation-based names unless the host supplies a label.

renderPaneLabel receives a stable Accessor<L> once for each leaf owner. Read leaf() inside the returned JSX so Solid tracks payload changes while the same pane owner is retained during split and move operations. This visible header content does not define the region's accessible name or the close button's name: both continue to come from labelForLeaf, so hosts should provide an accessible domain label there as well.

Pointer moves use a bounded, window-framed native drag-image snapshot while the source dims and the handle changes from a grab to a grabbing cursor. The temporary preview is inert, has no duplicate IDs, and is removed when dragging ends. Reduced-motion preference disables the source opacity transition; keyboard moves remain host-owned through renderPaneActions.

The HostPresentation story shows a decorative icon and host title, keyboard pane stops, and a workspace-specific separator name. A narrow-width component fixture also checks that a long host title does not widen its pane header.

Scene controls

SceneControls composes movement, jump and optional zoom actions for a host scene. onMovementChange(direction, pressed) and onJumpChange(pressed) report held state from pointer or keyboard input; zoom callbacks fire once per activation. The shared controls capture pointers and release held actions on pointer end/cancel, lost capture, window blur and component cleanup. The host maps these typed callbacks to its own camera or movement system; the component does not synthesize keyboard events or access host globals. Each icon action uses the shared tooltip and a 2xl 48px target that stays that size under compact density. Rounded movement and zoom group surfaces use the shared scrim treatment, which follows the library's reduced-transparency and fallback policy.

import { SceneControls } from '@adea-ai/ui/components/composites/scene-controls'

;<SceneControls
  onMovementChange={(direction, pressed) => setMovement(direction, pressed)}
  onJumpChange={(pressed) => setJumping(pressed)}
  onZoomIn={zoomIn}
  onZoomOut={zoomOut}
/>

Labels default to English and can be supplied through labels for a host's locale. Hold actions have separate accessible names and explanatory tooltip strings so localization can describe the gesture without changing the action name. SceneControls owns control arrangement and interaction lifecycle; the host owns placement, persistence and scene behavior.

Package checks

Each check:packed-* script packs the real npm archive, installs it into a throwaway consumer (optional peers left out, lifecycle scripts off) and checks it under both the compiled and Solid source export conditions. Browser cases run headless in Chromium and WebKit, and most also server-render in Node. Every check confirms the packed LICENSE and NOTICE and enforces a size budget. Install the browsers once with bunx playwright install chromium webkit (add --with-deps on Linux if system libraries are missing).

| Script | What it covers | Budget (gzip JS / raw CSS) | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | check:packed-conversation | Conversation subpath: draft recovery, IME, follow, jump focus, busy actions, composer collapse, atomic paste tokens | 26 / 50 / 54 KiB (plain, busy, composed) / 42 KiB | | check:packed-transcript | Transcript composition: row identity, tool folds, keyboard disclosure, accessibility | set in the script | | check:packed-appearance | Appearance editor with real @adea-ai/themes records: keyboard, live preview, save, cancel and reset, narrow layouts | 64 KiB / 50 KiB | | check:packed-scene-controls | Scene controls and ActionButton: held-action release, labels, 48px targets at 320px and 200% text | 40 KiB / 32 KiB | | check:packed-layout | Split-layout model subpath in Node, with no runtime imports | 3 KiB | | check:packed-layout-renderer | Split layout, sidebar and top bar rendering | 32 KiB / 34 KiB | | check:packed-paste-model | Paste-token model subpath with a strict TypeScript consumer | 3 KiB | | check:packed-consumer | Root imports, lightweight controls, overlays and the shell | set in the script |

The atomic paste editor may add at most 6 KiB of gzip JS over the composed fixture. Tailwind discovery in these fixtures is explicit; they never rely on scanning node_modules. The checks prove the published component contracts; persistence, hydration and manual assistive-technology checks happen in the apps.

bun run test:components runs the component contracts against a real Vite/Solid/Tailwind build in Chromium and WebKit.

What one component costs

bun run --cwd packages/ui check:tree-shaking builds real bundles against the built package. Each row uses the public entry, and importing one component does not pull in the rest of the library. The script writes this table (-- --write) and CI fails when the committed figures drift from what it measures.

| Public import | Gzipped | What it brings | | --------------------------------------------------------------- | ---------- | ------------------------------------- | | @adea-ai/ui → Button | 22.4 kB | the floor: Solid, clsx, tw-merge | | @adea-ai/ui → Board | 22.8 kB | nothing | | @adea-ai/ui/components/composites/list-row → ListRowControl | 21.9 kB | nothing: the row without its tooltip | | @adea-ai/ui → DiffBlock | 23.2 kB | lucide icons | | @adea-ai/ui → CodeBlock | 48.7 kB | lucide icons, Kobalte tooltip on copy | | @adea-ai/ui → MessageRow | 27.8 kB | nothing | | @adea-ai/ui → CalendarSurface | 30.7 kB | corvu calendar | | @adea-ai/ui → ModalDialog | 51.2 kB | Kobalte dialog, the shared tooltip | | @adea-ai/ui/components/ui/carousel → Carousel | 34.9 kB | embla | | @adea-ai/ui/components/composites/list-row → ListRow | 42.4 kB | Kobalte tooltip | | @adea-ai/ui → NavigationMenu | 59.1 kB | Kobalte navigation menu | | @adea-ai/ui/components/ui/chart → LineChart | 89.9 kB | chart.js, the line controller only | | root plus chart and carousel entries | 470.3 kB | and Button is 4.8% of it |

The chart splits from itself, which is why chart.js was chosen: LineChart is 10.6 kB smaller than importing all seven chart types together (89.9 kB against 100.5 kB), because the controllers are imported per component while the shared scales and plugins are registered once. The gate fails if that stops being true.

Three budgets are enforced in CI: importing Button must stay under 40.0 kB and under 25.0% of the whole library, and no sampled component may exceed 180.0 kB.

Adding a component

shadcn add installs an item from the registry on GitLab Pages (or from ./packages/ui/public/r/<name>.json in a checkout):

bunx shadcn@latest add https://adea-ai.gitlab.io/design-system/ui/r/button.json

Reviewing it

Every component, every variant and the token galleries are in the workshop:

bun run storybook

The toolbar switches theme, accent, fonts and density live, which is the fastest way to see how a component behaves across the catalogue rather than in one theme.

Licence

Apache-2.0. Donor attributions are in NOTICE, which ships in the package.