@fungi.computer/caps 0.7.1 → 0.9.0

package/README.md

@@ -812,6 +812,64 @@ closes the disclosure and returns focus to the launcher. Reduced motion settles
 immediately. Available-app and primary-action buttons do not claim toggle state.
 `alwaysExpanded` keeps the disclosure open for dock layouts.
 
+### First-run kit
+
+Compose these for an App's first ten seconds; Caps owns the presentation and
+your App owns the words.
+
+- `EmptyState` takes `primaryAction` (`label`, `onSelect`, `pending`,
+  `disabled`, `disabledReason`): at most one primary per state. Put secondary
+  buttons in `actions`. `suggestions` chips accept `pending` and `disabled`.
+  `visual="blobs"` is the living idle Loader and is what a `panel` shows when
+  you pass no visual; `speech` keeps the mascot.
+- `ResultState` is the failure card: `tone` (`failed`, `done`, `neutral`), up to
+  three numbered `steps`, `visual` art, and `headingLevel`.
+- `LoadingState` takes `size`, `variant`, `detail`, and `slowAfterMs`
+  (default 8000) with `onRetry`; after that it adds "Still working…" and a
+  Retry. Formations by moment: `line` opening a window, `wander` connecting,
+  `square` installing, `bloom` a run in progress. `Loader pace="idle"` slows a
+  formation for decorative art. Reduced motion shows the static silhouette.
+- `Keycap touch="hide"` drops a keyboard legend on touch-first devices;
+  `KeycapButton` hides its `shortcut` legend that way.
+
+- `SetupNotice` (`blocks/setup-notice`) names a missing setup with its one fix:
+  `need` (title), `cause` (one sentence), required `fix`, optional `secondary`
+  and `available` (what still works), and `variant` `panel` (an EmptyState
+  panel), `banner` or `inline` (a warning Alert). While `fix.pending` the button
+  shows the Loader and reads "Waiting for {waitingFor}…". Render it only while
+  the setup is missing; the host unmounts it when the fact turns ready. One
+  notice per window, and the notice is the call to action.
+- `FailureLine` (`components/failure-line`) is the item failure: an error dot,
+  one plain line, labelled `Retry` / `Dismiss`, and "Failed {n} times" once when
+  `count` is above 1. `density` is `row` or `tile`. Never use the `bang` glyph.
+
+Which key and which status light:
+
+| Need                                                                | Use                     |
+| ------------------------------------------------------------------- | ----------------------- |
+| An action button in an App, game dock or toy panel                  | `KeycapButton`          |
+| A keyboard legend beside copy or inside a key                       | `Keycap` (native `kbd`) |
+| State of an App row, chip or toolbar                                | `Status` (gooey bead)   |
+| An editorial or field-guide progress mark (ring, arc, check, cross) | `StatusMark`            |
+
+`bang` is for unread beads only. Never put it in a button or chip; use a dot.
+
+### Toaster CSS placement
+
+`Toaster` wraps Sonner, which injects its own unlayered stylesheet at runtime.
+Anything inside a cascade layer loses to it, so the toast rules (Stipe token
+variables, font, close button, icons) live unlayered near the top of
+`src/styles.css`, with raised specificity. Keep new toast rules there, not in
+`first-run.css` or a layer.
+
+### Hairlines
+
+`--stipe-hairline` (about 22%) outlines controls: Keycap, Button and chips keep
+it, and the plastic look stays. `--stipe-hairline-quiet` (about 10%, an additive
+Stipe token) draws separators inside a surface: table row lines, list and panel
+dividers, prose rules. Use fewer frames, not lighter ones: never put a framed
+box inside a framed box, and never change a control outline to the quiet token.
+
 ### Status beads and dashboard controls
 
 `Status` is a gooey SVG bead. Set `glyph` (`dot`, `pill` or `bang`), `tone`, and

package/dist/blocks/app-bar.d.ts

@@ -15,8 +15,10 @@ export type AppBarProps = {
     /** Portal container for the App dial; defaults to the document body. */
     container?: HTMLElement | null;
     windows: readonly AppBarItem[];
-    /** Team Apps available to launch from the speed dial. */
+    /** Apps available to launch from the speed dial. */
     launchers: readonly AppBarItem[];
+    /** The Apps section heading and its launcher name; the host owns the wording. */
+    appsLabel?: string;
     /** Recent Sessions supplied by the shell's session owner. */
     sessions?: readonly AppBarItem[];
     /** Keep long launcher names readable instead of truncating them. */
@@ -40,4 +42,4 @@ export type AppBarProps = {
     };
 };
 /** An anchored launcher between persistent running apps and a spring-out app tray. */
-export declare function AppBar({ container, windows, launchers, sessions, launcherLabels, alwaysExpanded, isOpen, onOpenChange, emptyLabel, launcher, primaryAction, }: AppBarProps): import("react/jsx-runtime").JSX.Element;
+export declare function AppBar({ container, windows, launchers, sessions, appsLabel, launcherLabels, alwaysExpanded, isOpen, onOpenChange, emptyLabel, launcher, primaryAction, }: AppBarProps): import("react/jsx-runtime").JSX.Element;

package/dist/blocks/app-bar.js

@@ -42,7 +42,7 @@ function AppBarItemView({ item, available, expanded, onSelect, onClose, session
                 }, children: [_jsx("span", { ref: icon, className: "caps-app-bar-icon", "aria-hidden": "true", children: item.icon ?? _jsx(PanelsTopLeft, {}) }), available ? (_jsx("span", { className: "caps-app-bar-item-label", children: item.label })) : null] }), item.onClose ? (_jsx("button", { type: "button", className: "caps-app-bar-close", "aria-label": `Close ${item.label}`, tabIndex: tabIndex, onClick: onClose, children: _jsx(X, { "aria-hidden": "true" }) })) : null] }));
 }
 /** An anchored launcher between persistent running apps and a spring-out app tray. */
-export function AppBar({ container, windows, launchers, sessions = [], launcherLabels = "truncate", alwaysExpanded = false, isOpen, onOpenChange, emptyLabel, launcher, primaryAction, }) {
+export function AppBar({ container, windows, launchers, sessions = [], appsLabel = "Apps", launcherLabels = "truncate", alwaysExpanded = false, isOpen, onOpenChange, emptyLabel, launcher, primaryAction, }) {
     const popoverRoot = useOverlayRoot("popover");
     const portalContainer = container ?? popoverRoot;
     const [internalOpen, setInternalOpen] = useState(false);
@@ -232,9 +232,9 @@ export function AppBar({ container, windows, launchers, sessions = [], launcherL
         else
             setOpen(next);
     };
-    return (_jsx(BasePopover.Root, { open: expanded, onOpenChange: changeOpen, modal: false, children: _jsxs("nav", { ref: root, style: appBarStyle, className: "caps-app-bar", "aria-label": "Team Apps and Sessions launcher", "data-open": expanded ? "true" : "false", children: [_jsx("div", { ref: runningRef, className: "caps-app-bar-region caps-app-bar-items", role: "group", "aria-label": "Running apps", "aria-hidden": "false", children: windows.map((item) => renderItem(item, false)) }), _jsx("div", { className: "caps-app-bar-launcher", children: _jsx("button", { ref: launcherRef, type: "button", className: "caps-app-bar-launcher-button", "aria-label": launcher.label, title: launcher.label, "aria-expanded": expanded, "aria-controls": primaryAction ? actionId : availableId, onClick: () => {
+    return (_jsx(BasePopover.Root, { open: expanded, onOpenChange: changeOpen, modal: false, children: _jsxs("nav", { ref: root, style: appBarStyle, className: "caps-app-bar", "aria-label": `${appsLabel} and Sessions launcher`, "data-open": expanded ? "true" : "false", children: [_jsx("div", { ref: runningRef, className: "caps-app-bar-region caps-app-bar-items", role: "group", "aria-label": "Running apps", "aria-hidden": "false", children: windows.map((item) => renderItem(item, false)) }), _jsx("div", { className: "caps-app-bar-launcher", children: _jsx("button", { ref: launcherRef, type: "button", className: "caps-app-bar-launcher-button", "aria-label": launcher.label, title: launcher.label, "aria-expanded": expanded, "aria-controls": primaryAction ? actionId : availableId, onClick: () => {
                             setOpen(!open);
-                        }, children: _jsx("span", { className: "caps-app-bar-mascot", "aria-hidden": "true", children: launcher.icon ?? _jsx(PanelsTopLeft, {}) }) }) }), portalContainer ? (_jsx(BasePopover.Portal, { container: portalContainer, keepMounted: true, children: _jsx(BasePopover.Positioner, { anchor: root, side: "bottom", align: "start", sideOffset: 4, collisionPadding: 8, collisionBoundary: portalContainer === document.body ? undefined : portalContainer, className: "caps-app-bar-positioner", children: _jsxs(BasePopover.Popup, { initialFocus: false, finalFocus: false, style: appBarStyle, ref: availableRef, id: availableId, className: "caps-app-bar-region caps-app-bar-launchers", role: "group", "aria-label": "Speed dial", "aria-hidden": !expanded, children: [launchers.length > 0 ? (_jsxs("div", { className: "caps-app-bar-section", role: "group", "aria-label": "Team Apps", children: [_jsx("span", { className: "caps-app-bar-section-label", children: "Team Apps" }), _jsx("div", { className: "caps-app-bar-app-list", children: launchers.map((item) => renderItem(item, true)) })] })) : null, sessions.length > 0 ? (_jsxs("div", { className: "caps-app-bar-section caps-app-bar-sessions", role: "group", "aria-label": "Recent Sessions", children: [_jsx("span", { className: "caps-app-bar-section-label", children: "Recent Sessions" }), _jsx("div", { className: "caps-app-bar-session-list", children: sessions.map((item) => renderItem(item, true, true)) })] })) : null, launchers.length === 0 &&
+                        }, children: _jsx("span", { className: "caps-app-bar-mascot", "aria-hidden": "true", children: launcher.icon ?? _jsx(PanelsTopLeft, {}) }) }) }), portalContainer ? (_jsx(BasePopover.Portal, { container: portalContainer, keepMounted: true, children: _jsx(BasePopover.Positioner, { anchor: root, side: "bottom", align: "start", sideOffset: 4, collisionPadding: 8, collisionBoundary: portalContainer === document.body ? undefined : portalContainer, className: "caps-app-bar-positioner", children: _jsxs(BasePopover.Popup, { initialFocus: false, finalFocus: false, style: appBarStyle, ref: availableRef, id: availableId, className: "caps-app-bar-region caps-app-bar-launchers", role: "group", "aria-label": "Speed dial", "aria-hidden": !expanded, children: [launchers.length > 0 ? (_jsxs("div", { className: "caps-app-bar-section", role: "group", "aria-label": appsLabel, children: [_jsx("span", { className: "caps-app-bar-section-label", children: appsLabel }), _jsx("div", { className: "caps-app-bar-app-list", children: launchers.map((item) => renderItem(item, true)) })] })) : null, sessions.length > 0 ? (_jsxs("div", { className: "caps-app-bar-section caps-app-bar-sessions", role: "group", "aria-label": "Recent Sessions", children: [_jsx("span", { className: "caps-app-bar-section-label", children: "Recent Sessions" }), _jsx("div", { className: "caps-app-bar-session-list", children: sessions.map((item) => renderItem(item, true, true)) })] })) : null, launchers.length === 0 &&
                                     sessions.length === 0 &&
                                     emptyLabel ? (_jsx("span", { className: "caps-app-bar-empty", role: "status", children: emptyLabel })) : null] }) }) })) : null, primaryAction && portalContainer ? (_jsx(BasePopover.Root, { open: open, onOpenChange: changeOpen, modal: false, children: _jsx(BasePopover.Portal, { container: portalContainer, keepMounted: true, children: _jsx(BasePopover.Positioner, { anchor: launcherRef, side: "bottom", align: "end", sideOffset: 8, collisionPadding: 8, collisionBoundary: portalContainer === document.body
                                 ? undefined

package/dist/blocks/empty-state.d.ts

@@ -22,10 +22,28 @@ export type EmptyStateSuggestion = Readonly<{
     label: string;
     /** Called when the chip is chosen. */
     onSelect: () => void;
+    /** Running what this chip starts; shows a loader in the chip. */
+    pending?: boolean;
+    disabled?: boolean;
+}>;
+/** The one main step a first-run state invites; at most one per state. */
+export type EmptyStatePrimaryAction = Readonly<{
+    /** A verb plus an object, such as "New repository". */
+    label: string;
+    /** Called when the action is chosen. */
+    onSelect: () => void;
+    /** Running the action; shows a loader in the button and blocks a repeat. */
+    pending?: boolean;
+    disabled?: boolean;
+    /** Why the action is unavailable; shown under the button when disabled. */
+    disabledReason?: string;
 }>;
 /** Props accepted by EmptyState. */
 export type EmptyStateProps = Omit<HTMLAttributes<HTMLElement>, "title"> & {
+    /** Secondary actions only; the main step goes in `primaryAction`. */
     actions?: ReactNode;
+    /** The one main step, rendered as a primary Button before the chips. */
+    primaryAction?: EmptyStatePrimaryAction;
     description: ReactNode;
     /** Chips that offer a starting point, such as a prompt to try. */
     suggestions?: readonly EmptyStateSuggestion[];
@@ -34,15 +52,21 @@ export type EmptyStateProps = Omit<HTMLAttributes<HTMLElement>, "title"> & {
     title: ReactNode;
     /** Heading level for the title; use one below the heading it sits under. */
     headingLevel?: EmptyStateHeadingLevel;
-    /** Static art. */
-    visual?: ReactNode;
+    /**
+     * Static art. `"blobs"` is the living idle Loader; a `panel` with no visual
+     * shows it too.
+     */
+    visual?: Exclude<ReactNode, string> | "blobs";
     /** Render a visual from the current speaking and thinking state. */
     renderVisual?: (state: EmptyStateVisualState) => ReactNode;
     variant?: EmptyStateVariant;
 };
 /** Product-neutral absence presentation; hosts supply copy, art, and actions. */
 export declare const EmptyState: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLElement>, "title"> & {
+    /** Secondary actions only; the main step goes in `primaryAction`. */
     actions?: ReactNode;
+    /** The one main step, rendered as a primary Button before the chips. */
+    primaryAction?: EmptyStatePrimaryAction;
     description: ReactNode;
     /** Chips that offer a starting point, such as a prompt to try. */
     suggestions?: readonly EmptyStateSuggestion[];
@@ -51,8 +75,11 @@ export declare const EmptyState: import("react").ForwardRefExoticComponent<Omit<
     title: ReactNode;
     /** Heading level for the title; use one below the heading it sits under. */
     headingLevel?: EmptyStateHeadingLevel;
-    /** Static art. */
-    visual?: ReactNode;
+    /**
+     * Static art. `"blobs"` is the living idle Loader; a `panel` with no visual
+     * shows it too.
+     */
+    visual?: Exclude<ReactNode, string> | "blobs";
     /** Render a visual from the current speaking and thinking state. */
     renderVisual?: (state: EmptyStateVisualState) => ReactNode;
     variant?: EmptyStateVariant;

package/dist/blocks/empty-state.js

@@ -1,6 +1,7 @@
-import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { forwardRef, useEffect, useId, useState, useRef, } from "react";
 import { Button } from "../components/button.js";
+import { Loader } from "../components/loader.js";
 import { useMotion, motionTime } from "../lib/motion.js";
 import { cn } from "../lib/cn.js";
 const headingTags = { 2: "h2", 3: "h3", 4: "h4" };
@@ -22,14 +23,23 @@ function useSpeaking(enabled, timing) {
     }, [active, duration]);
     return speaking;
 }
+const blobs = (_jsx(Loader, { decorative: true, pace: "idle", size: "md", tone: "primary", variant: "wander" }));
 /** Product-neutral absence presentation; hosts supply copy, art, and actions. */
-export const EmptyState = forwardRef(function EmptyState({ actions, className, description, headingLevel = 2, suggestions, thinking = false, title, visual, renderVisual, variant = "plain", ...props }, ref) {
+export const EmptyState = forwardRef(function EmptyState({ actions, className, description, headingLevel = 2, primaryAction, suggestions, thinking = false, title, visual, renderVisual, variant = "plain", ...props }, ref) {
     const titleId = useId();
     const heading = useRef(null);
     const timing = useMotion(heading);
     const speaking = useSpeaking(variant === "speech", timing) && !thinking;
     const Heading = headingTags[headingLevel];
-    const art = renderVisual ? renderVisual({ speaking, thinking }) : visual;
-    const copy = (_jsxs(_Fragment, { children: [_jsx(Heading, { ref: heading, className: "empty-state-title", id: props["aria-labelledby"] ? undefined : titleId, children: title }), _jsx("p", { children: description }), suggestions && suggestions.length > 0 ? (_jsx("ul", { "aria-label": "Try one of these", className: "empty-state-suggestions", children: suggestions.map((suggestion) => (_jsx("li", { children: _jsx(Button, { size: "sm", variant: "outline", onClick: suggestion.onSelect, children: suggestion.label }) }, suggestion.label))) })) : null, actions ? _jsx("div", { className: "empty-state-actions", children: actions }) : null] }));
+    const chosen = visual ?? (variant === "panel" ? "blobs" : undefined);
+    const art = renderVisual
+        ? renderVisual({ speaking, thinking })
+        : chosen === "blobs"
+            ? blobs
+            : chosen;
+    const disabledReasonId = `${titleId}-reason`;
+    const copy = (_jsxs(_Fragment, { children: [_jsx(Heading, { ref: heading, className: "empty-state-title", id: props["aria-labelledby"] ? undefined : titleId, children: title }), _jsx("p", { children: description }), primaryAction ? (_jsxs("div", { className: "empty-state-primary", children: [_jsx(Button, { "aria-describedby": primaryAction.disabled && primaryAction.disabledReason
+                            ? disabledReasonId
+                            : undefined, disabled: primaryAction.disabled, loading: primaryAction.pending === true, onClick: primaryAction.onSelect, variant: "primary", children: primaryAction.label }), primaryAction.disabled && primaryAction.disabledReason ? (_jsx("span", { className: "empty-state-reason", id: disabledReasonId, children: primaryAction.disabledReason })) : null] })) : null, suggestions && suggestions.length > 0 ? (_jsx("ul", { "aria-label": "Try one of these", className: "empty-state-suggestions", children: suggestions.map((suggestion, index) => (_jsx("li", { children: _jsx(Button, { disabled: suggestion.disabled, loading: suggestion.pending === true, size: "sm", variant: "outline", onClick: suggestion.onSelect, children: suggestion.label }) }, `${String(index)}:${suggestion.label}`))) })) : null, actions ? _jsx("div", { className: "empty-state-actions", children: actions }) : null] }));
     return (_jsxs("section", { ...props, "aria-labelledby": props["aria-labelledby"] ?? titleId, className: cn("empty-state", variant !== "plain" && `empty-state-${variant}`, className), ref: ref, children: [art ? (_jsx("div", { "aria-hidden": "true", className: "empty-state-visual", children: art })) : null, variant === "speech" ? (_jsx("div", { className: "empty-state-bubble", children: copy })) : (copy)] }));
 });

package/dist/blocks/loading-state.d.ts

@@ -1,5 +1,46 @@
 import { type HTMLAttributes, type ReactNode } from "react";
+import { type LoaderVariant } from "../components/loader.js";
+/** How long a wait runs before LoadingState admits it is slow. */
+export declare const LOADING_SLOW_AFTER_MS = 8000;
+/** Props accepted by LoadingState. */
+export type LoadingStateProps = HTMLAttributes<HTMLDivElement> & {
+    message: ReactNode;
+    /** `false` drops the frame (border, plate, padding) for a window-opening state that fills its pane. */
+    framed?: boolean;
+    /** An App icon shown above the loader, for an App opening state. */
+    icon?: ReactNode;
+    /** A second, quieter line under the message. */
+    detail?: ReactNode;
+    /** Blob size; `md` is the default for a window or pane. */
+    size?: "sm" | "md" | "lg";
+    /** Which formation moves; pick one per moment (see the Caps README). */
+    variant?: LoaderVariant;
+    /**
+     * Milliseconds before the wait is called slow: "Still working…" is added
+     * and `onRetry`, if given, offers a Retry. Infinity never says so.
+     */
+    slowAfterMs?: number;
+    /** Called when Retry is chosen; Retry only appears once the wait is slow. */
+    onRetry?: () => void;
+};
 /** A bounded, labelled loading region; the caller owns the message. */
 export declare const LoadingState: import("react").ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & {
     message: ReactNode;
+    /** `false` drops the frame (border, plate, padding) for a window-opening state that fills its pane. */
+    framed?: boolean;
+    /** An App icon shown above the loader, for an App opening state. */
+    icon?: ReactNode;
+    /** A second, quieter line under the message. */
+    detail?: ReactNode;
+    /** Blob size; `md` is the default for a window or pane. */
+    size?: "sm" | "md" | "lg";
+    /** Which formation moves; pick one per moment (see the Caps README). */
+    variant?: LoaderVariant;
+    /**
+     * Milliseconds before the wait is called slow: "Still working…" is added
+     * and `onRetry`, if given, offers a Retry. Infinity never says so.
+     */
+    slowAfterMs?: number;
+    /** Called when Retry is chosen; Retry only appears once the wait is slow. */
+    onRetry?: () => void;
 } & import("react").RefAttributes<HTMLDivElement>>;

package/dist/blocks/loading-state.js

@@ -1,8 +1,23 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { forwardRef } from "react";
+import { forwardRef, useEffect, useState, } from "react";
+import { Button } from "../components/button.js";
 import { Loader } from "../components/loader.js";
 import { cn } from "../lib/cn.js";
+/** How long a wait runs before LoadingState admits it is slow. */
+export const LOADING_SLOW_AFTER_MS = 8000;
 /** A bounded, labelled loading region; the caller owns the message. */
-export const LoadingState = forwardRef(function LoadingState({ className, message, ...props }, ref) {
-    return (_jsxs("div", { ...props, className: cn("caps-loading-state", className), ref: ref, role: "status", children: [_jsx(Loader, { decorative: true, size: "sm" }), _jsx("span", { children: message })] }));
+export const LoadingState = forwardRef(function LoadingState({ className, detail, framed = true, icon, message, onRetry, size = "md", slowAfterMs = LOADING_SLOW_AFTER_MS, variant = "line", ...props }, ref) {
+    const [slow, setSlow] = useState(false);
+    useEffect(() => {
+        setSlow(false);
+        if (!Number.isFinite(slowAfterMs))
+            return undefined;
+        const timer = globalThis.setTimeout(() => {
+            setSlow(true);
+        }, slowAfterMs);
+        return () => {
+            globalThis.clearTimeout(timer);
+        };
+    }, [slowAfterMs, message]);
+    return (_jsxs("div", { ...props, className: cn("caps-loading-state", className), "data-framed": framed ? undefined : "false", "data-icon": icon ? "" : undefined, "data-size": size, "data-slow": slow || undefined, ref: ref, role: "status", children: [icon ? (_jsx("span", { "aria-hidden": "true", className: "caps-loading-state-icon", children: icon })) : null, _jsx(Loader, { decorative: true, size: size, variant: variant }), _jsxs("span", { className: "caps-loading-state-copy", children: [_jsx("span", { children: message }), detail ? (_jsx("span", { className: "caps-loading-state-detail", children: detail })) : null, slow ? (_jsx("span", { className: "caps-loading-state-detail", children: "Still working\u2026" })) : null] }), slow && onRetry ? (_jsx(Button, { className: "caps-loading-state-retry", size: "sm", variant: "outline", onClick: onRetry, children: "Retry" })) : null] }));
 });

package/dist/blocks/permission-grid.js

@@ -10,5 +10,5 @@ function index(position) {
 /** Product-neutral, dense capability sheet: one row per capability. */
 export function PermissionGrid({ caption, summary, rows, headings = DEFAULT_HEADINGS, className, }) {
     const hasControls = rows.some((row) => row.control !== undefined);
-    return (_jsxs("figure", { className: `caps-permission-grid ${className ?? ""}`, children: [_jsxs("figcaption", { className: "caps-permission-grid-caption", children: [_jsx("span", { className: "caps-permission-grid-title", children: caption }), summary === undefined ? null : (_jsx("span", { className: "caps-permission-grid-summary", children: summary }))] }), _jsxs("table", { children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", className: "caps-permission-grid-index", children: "#" }), _jsx("th", { scope: "col", children: headings.capability }), _jsx("th", { scope: "col", children: headings.state }), _jsx("th", { scope: "col", children: headings.scope }), hasControls ? (_jsx("th", { scope: "col", children: headings.control ?? _jsx("span", { className: "sr-only", children: "Change" }) })) : null] }) }), _jsx("tbody", { children: rows.map((row, position) => (_jsxs("tr", { "data-state": row.state, children: [_jsxs("td", { className: "caps-permission-grid-index", children: [_jsx("span", { children: index(position) }), row.group === undefined ? null : (_jsx("span", { className: "caps-permission-grid-group", children: row.group }))] }), _jsx("th", { scope: "row", children: _jsxs("span", { className: "caps-permission-grid-capability", children: [_jsx("span", { className: "caps-permission-grid-mark", "aria-hidden": "true", children: row.mark }), _jsx("span", { children: row.label })] }) }), _jsx("td", { children: _jsx("span", { className: "caps-permission-grid-state", "data-state": row.state, children: row.stateLabel }) }), _jsx("td", { className: "caps-permission-grid-scope", children: row.scope }), hasControls ? _jsx("td", { children: row.control ?? null }) : null] }, row.id))) })] })] }));
+    return (_jsxs("figure", { className: `caps-permission-grid ${className ?? ""}`, children: [_jsxs("figcaption", { className: "caps-permission-grid-caption", children: [_jsx("span", { className: "caps-permission-grid-title", children: caption }), summary === undefined ? null : (_jsx("span", { className: "caps-permission-grid-summary", children: summary }))] }), _jsxs("table", { children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", className: "caps-permission-grid-index", children: "#" }), _jsx("th", { scope: "col", children: headings.capability }), _jsx("th", { scope: "col", className: "caps-permission-grid-col-state", children: headings.state }), _jsx("th", { scope: "col", className: "caps-permission-grid-col-scope", children: headings.scope }), hasControls ? (_jsx("th", { scope: "col", className: "caps-permission-grid-col-control", children: headings.control ?? _jsx("span", { className: "sr-only", children: "Change" }) })) : null] }) }), _jsx("tbody", { children: rows.map((row, position) => (_jsxs("tr", { "data-state": row.state, children: [_jsxs("td", { className: "caps-permission-grid-index", children: [_jsx("span", { children: index(position) }), row.group === undefined ? null : (_jsx("span", { className: "caps-permission-grid-group", title: row.group, children: row.group }))] }), _jsx("th", { scope: "row", children: _jsxs("span", { className: "caps-permission-grid-capability", children: [_jsx("span", { className: "caps-permission-grid-mark", "aria-hidden": "true", children: row.mark }), _jsx("span", { children: row.label })] }) }), _jsx("td", { children: _jsx("span", { className: "caps-permission-grid-state", "data-state": row.state, children: row.stateLabel }) }), _jsx("td", { className: "caps-permission-grid-scope", children: row.scope }), hasControls ? _jsx("td", { children: row.control ?? null }) : null] }, row.id))) })] })] }));
 }

package/dist/blocks/result-state.d.ts

@@ -1,15 +1,33 @@
 import { type HTMLAttributes, type ReactNode } from "react";
+/** The document heading level of a ResultState title. */
+export type ResultStateHeadingLevel = 2 | 3 | 4;
+/** What happened: `failed` is the failure card, `done` a finished result. */
+export type ResultStateTone = "failed" | "done" | "neutral";
 /** Props accepted by ResultState. */
 export type ResultStateProps = Omit<HTMLAttributes<HTMLElement>, "title"> & {
+    /** One primary action, then secondary ones. */
     actions?: ReactNode;
     description: ReactNode;
+    headingLevel?: ResultStateHeadingLevel;
     icon?: ReactNode;
+    /** Up to three numbered next steps; extra steps are not shown. */
+    steps?: readonly ReactNode[];
     title: ReactNode;
+    tone?: ResultStateTone;
+    /** Larger decorative art above the title, such as an illustration. */
+    visual?: ReactNode;
 };
 /** A labelled result presentation; hosts own its meaning and next actions. */
 export declare const ResultState: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLElement>, "title"> & {
+    /** One primary action, then secondary ones. */
     actions?: ReactNode;
     description: ReactNode;
+    headingLevel?: ResultStateHeadingLevel;
     icon?: ReactNode;
+    /** Up to three numbered next steps; extra steps are not shown. */
+    steps?: readonly ReactNode[];
     title: ReactNode;
+    tone?: ResultStateTone;
+    /** Larger decorative art above the title, such as an illustration. */
+    visual?: ReactNode;
 } & import("react").RefAttributes<HTMLElement>>;

package/dist/blocks/result-state.js

@@ -1,8 +1,13 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { forwardRef, useId } from "react";
+import { Status } from "../components/status.js";
 import { cn } from "../lib/cn.js";
+const headingTags = { 2: "h2", 3: "h3", 4: "h4" };
+const MAX_STEPS = 3;
 /** A labelled result presentation; hosts own its meaning and next actions. */
-export const ResultState = forwardRef(function ResultState({ actions, className, description, icon, title, ...props }, ref) {
+export const ResultState = forwardRef(function ResultState({ actions, className, description, headingLevel = 2, icon, steps, title, tone = "neutral", visual, ...props }, ref) {
     const titleId = useId();
-    return (_jsxs("section", { ...props, "aria-labelledby": props["aria-labelledby"] ?? titleId, className: cn("result-state", className), ref: ref, children: [icon ? _jsx("div", { "aria-hidden": "true", children: icon }) : null, _jsx("h2", { id: props["aria-labelledby"] ? undefined : titleId, children: title }), _jsx("p", { children: description }), actions ? _jsx("div", { className: "result-state-actions", children: actions }) : null] }));
+    const Heading = headingTags[headingLevel];
+    const shown = steps?.slice(0, MAX_STEPS) ?? [];
+    return (_jsxs("section", { ...props, "aria-labelledby": props["aria-labelledby"] ?? titleId, className: cn("result-state", className), "data-tone": tone === "neutral" ? undefined : tone, ref: ref, children: [visual ? (_jsx("div", { "aria-hidden": "true", className: "result-state-visual", children: visual })) : null, icon ? _jsx("div", { "aria-hidden": "true", children: icon }) : null, _jsxs(Heading, { id: props["aria-labelledby"] ? undefined : titleId, children: [tone === "neutral" ? null : (_jsx(Status, { glyph: "dot", tone: tone === "failed" ? "error" : "success" })), _jsx("span", { children: title })] }), _jsx("p", { children: description }), shown.length > 0 ? (_jsx("ol", { className: "result-state-steps", children: shown.map((step, index) => (_jsx("li", { children: step }, index))) })) : null, actions ? _jsx("div", { className: "result-state-actions", children: actions }) : null] }));
 });

package/dist/blocks/setup-notice.d.ts

@@ -0,0 +1,32 @@
+import type { HTMLAttributes, ReactNode } from "react";
+/** A step the person takes to finish setup. */
+export type SetupNoticeAction = Readonly<{
+    label: string;
+    /** Called when the step is chosen. */
+    onSelect: () => void;
+}>;
+/** The required fix; `pending` means it opened Settings and is waiting. */
+export type SetupNoticeFix = SetupNoticeAction & Readonly<{
+    pending?: boolean;
+}>;
+/** Props accepted by SetupNotice. */
+export type SetupNoticeProps = Omit<HTMLAttributes<HTMLElement>, "title" | "children"> & {
+    /** The title, such as "Connect a model to start chatting". */
+    need: ReactNode;
+    /** One sentence naming the real cause. */
+    cause: ReactNode;
+    /** The one primary fix; never a dead CTA. */
+    fix: SetupNoticeFix;
+    secondary?: SetupNoticeAction;
+    /** What still works meanwhile, such as "Uploads work now". */
+    available?: ReactNode;
+    /** Names what is awaited while pending, after "Waiting for". */
+    waitingFor?: string;
+    /** `panel` replaces an empty state; `banner` and `inline` sit above or in content. */
+    variant: "panel" | "inline" | "banner";
+};
+/**
+ * Missing setup, named with its fix. Render it only while the setup fact is
+ * missing; when the fact turns ready the host unmounts it (and may toast).
+ */
+export declare function SetupNotice({ available, cause, className, fix, need, secondary, variant, waitingFor, ...props }: SetupNoticeProps): import("react/jsx-runtime").JSX.Element;

package/dist/blocks/setup-notice.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Alert } from "../components/alert.js";
+import { Button } from "../components/button.js";
+import { Status } from "../components/status.js";
+import { cn } from "../lib/cn.js";
+import { EmptyState } from "./empty-state.js";
+/**
+ * Missing setup, named with its fix. Render it only while the setup fact is
+ * missing; when the fact turns ready the host unmounts it (and may toast).
+ */
+export function SetupNotice({ available, cause, className, fix, need, secondary, variant, waitingFor = "setup", ...props }) {
+    const pending = fix.pending === true;
+    const label = pending ? `Waiting for ${waitingFor}…` : fix.label;
+    const detail = available ? (_jsxs(_Fragment, { children: [cause, " ", _jsx("span", { className: "caps-setup-notice-available", children: available })] })) : (cause);
+    if (variant === "panel") {
+        return (_jsx(EmptyState, { ...props, actions: secondary ? (_jsx(Button, { size: "sm", variant: "ghost", onClick: secondary.onSelect, children: secondary.label })) : undefined, className: cn("caps-setup-notice", className), "data-variant": "panel", description: detail, primaryAction: {
+                label,
+                onSelect: fix.onSelect,
+                pending,
+            }, title: need, variant: "panel", visual: _jsx(Status, { className: "caps-setup-notice-dot", glyph: "dot", tone: "warning" }) }));
+    }
+    return (_jsx("div", { className: "caps-setup-notice-frame", children: _jsx(Alert, { ...props, action: _jsxs("span", { className: "caps-setup-notice-actions", children: [secondary ? (_jsx(Button, { size: "sm", variant: "ghost", onClick: secondary.onSelect, children: secondary.label })) : null, _jsx(Button, { loading: pending, size: "sm", variant: "outline", onClick: fix.onSelect, children: label })] }), className: cn("caps-setup-notice", className), "data-variant": variant, description: detail, role: "status", title: _jsxs("span", { className: "caps-setup-notice-title", children: [_jsx(Status, { glyph: "dot", tone: "warning" }), need] }), tone: "warning" }) }));
+}

package/dist/components/button.js

@@ -41,7 +41,7 @@ export const Button = forwardRef(function Button({ asChild = false, children, cl
     if (asChild) {
         return (_jsx(Slot, { ...props, "aria-busy": loading ? true : props["aria-busy"], "aria-disabled": disabled === true || loading ? true : undefined, className: classes, ref: node, children: children }));
     }
-    return (_jsx("button", { ...props, "aria-busy": loading ? true : props["aria-busy"], className: classes, disabled: disabled === true || loading, ref: node, type: props.type ?? "button", children: result === undefined && resultLabel === undefined ? (_jsxs(_Fragment, { children: [loading ? (_jsx(Loader, { className: "size-3", decorative: true, size: "sm" })) : null, children] })) : (_jsx(ResultFaces, { label: resultLabel, loading: loading, onResultEnd: onResultEnd, result: result, settled: mountedResult, children: children })) }));
+    return (_jsx("button", { ...props, "aria-busy": loading ? true : props["aria-busy"], className: classes, disabled: disabled === true || loading, ref: node, type: props.type ?? "button", children: result === undefined && resultLabel === undefined ? (_jsxs(_Fragment, { children: [loading ? (_jsx(Loader, { decorative: true, size: "sm", tone: "current", variant: "wander" })) : null, children] })) : (_jsx(ResultFaces, { label: resultLabel, loading: loading, onResultEnd: onResultEnd, result: result, settled: mountedResult, children: children })) }));
 });
 /**
  * When a button's label changes (loading, a result, new text) its width eases
@@ -247,5 +247,5 @@ function ResultFaces({ children, label, loading, onResultEnd, result, settled, }
                 animation.cancel();
         };
     }, [showing, reduced]);
-    return (_jsxs("span", { ref: faces, className: "caps-button-faces", "data-showing": showing ? "result" : "label", children: [_jsxs("span", { className: "caps-button-face", "data-face": "label", "aria-hidden": showing ? true : undefined, children: [loading || showing ? (_jsx(Loader, { className: "size-3", decorative: true, size: "sm" })) : null, children] }), resultMounted ? (_jsxs("span", { className: "caps-button-face", "data-face": "result", "aria-hidden": showing ? undefined : true, children: [_jsx("svg", { className: "caps-button-check", viewBox: "0 0 24 24", "aria-hidden": "true", focusable: "false", children: _jsx("path", { d: "M4.5 12.5 9.5 17.5 19.5 6.5", pathLength: 1 }) }), label === undefined ? children : label] })) : null] }));
+    return (_jsxs("span", { ref: faces, className: "caps-button-faces", "data-showing": showing ? "result" : "label", children: [_jsxs("span", { className: "caps-button-face", "data-face": "label", "aria-hidden": showing ? true : undefined, children: [loading || showing ? (_jsx(Loader, { decorative: true, size: "sm", tone: "current", variant: "wander" })) : null, children] }), resultMounted ? (_jsxs("span", { className: "caps-button-face", "data-face": "result", "aria-hidden": showing ? undefined : true, children: [_jsx("svg", { className: "caps-button-check", viewBox: "0 0 24 24", "aria-hidden": "true", focusable: "false", children: _jsx("path", { d: "M4.5 12.5 9.5 17.5 19.5 6.5", pathLength: 1 }) }), label === undefined ? children : label] })) : null] }));
 }

package/dist/components/confirm-action.d.ts

@@ -1,3 +1,4 @@
+import { type ButtonSize, type ButtonVariant } from "./button.js";
 /** A deliberate hold, or an exact phrase before a destructive action. */
 export type ConfirmActionProps = {
     /** The action's trigger label and dialog title. */
@@ -8,6 +9,10 @@ export type ConfirmActionProps = {
     onConfirm: () => Promise<void>;
     /** Caller-owned, safe-to-display failure copy; rejection details are never displayed. */
     error?: string;
+    /** The trigger key's look; destructive by default, quiet where a toolbar needs it. */
+    variant?: ButtonVariant;
+    /** The trigger key's size. */
+    size?: ButtonSize;
 } & ({
     mode: "hold";
     phrase?: never;
@@ -20,4 +25,4 @@ export type ConfirmActionProps = {
  * confirmations available for retry. Type mode closes on success and restores
  * focus through Dialog. A pending action cannot be dismissed or cancelled.
  */
-export declare function ConfirmAction({ label, confirmLabel, onConfirm, error, mode, phrase, }: ConfirmActionProps): import("react/jsx-runtime").JSX.Element;
+export declare function ConfirmAction({ label, confirmLabel, onConfirm, error, variant, size, mode, phrase, }: ConfirmActionProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/confirm-action.js

@@ -10,7 +10,7 @@ import { Input } from "./input.js";
  * confirmations available for retry. Type mode closes on success and restores
  * focus through Dialog. A pending action cannot be dismissed or cancelled.
  */
-export function ConfirmAction({ label, confirmLabel, onConfirm, error, mode, phrase, }) {
+export function ConfirmAction({ label, confirmLabel, onConfirm, error, variant = "destructive", size, mode, phrase, }) {
     const [open, setOpen] = useState(false);
     const [typed, setTyped] = useState("");
     const [state, setState] = useState("idle");
@@ -45,7 +45,7 @@ export function ConfirmAction({ label, confirmLabel, onConfirm, error, mode, phr
         }
     }
     if (mode === "hold") {
-        return (_jsxs("div", { className: "grid gap-sm", children: [_jsx(HoldButton, { variant: "destructive", loading: busy, result: result, holdHint: confirmLabel, onConfirm: () => void confirm(), children: label }), _jsx(FieldError, { children: message })] }));
+        return (_jsxs("div", { className: "grid gap-sm", children: [_jsx(HoldButton, { variant: variant, ...(size === undefined ? {} : { size }), loading: busy, result: result, holdHint: confirmLabel, onConfirm: () => void confirm(), children: label }), _jsx(FieldError, { children: message })] }));
     }
     return (_jsxs(Dialog, { open: open, onOpenChange: (next, details) => {
             if (pending.current) {
@@ -55,7 +55,7 @@ export function ConfirmAction({ label, confirmLabel, onConfirm, error, mode, phr
             setOpen(next);
             setTyped("");
             setState("idle");
-        }, children: [_jsx(DialogTrigger, { render: _jsx(Button, { variant: "destructive" }), children: label }), _jsx(DialogContent, { initialFocus: input, children: _jsxs(Form, { busy: busy, onSubmit: (event) => {
+        }, children: [_jsx(DialogTrigger, { render: _jsx(Button, { variant: variant, ...(size === undefined ? {} : { size }) }), children: label }), _jsx(DialogContent, { initialFocus: input, children: _jsxs(Form, { busy: busy, onSubmit: (event) => {
                         event.preventDefault();
                         void confirm();
                     }, children: [_jsxs(DialogHeader, { children: [_jsx(DialogTitle, { children: label }), _jsx(DialogDescription, { children: "Type the phrase exactly to confirm." })] }), _jsx(Field, { label: `Type ${phrase} to confirm`, children: _jsx(Input, { ref: input, autoComplete: "off", autoCapitalize: "none", spellCheck: false, value: typed, onChange: (event) => {

package/dist/components/dialog.js

@@ -43,7 +43,7 @@ export const DialogPopup = forwardRef(function DialogPopup({ className, finalFoc
     const dialog = useDialogContext();
     return (_jsx(BaseDialog.Popup, { ...props, "data-size": size, className: (state) => cn("caps-dialog-popup overflow-y-auto overscroll-contain rounded-box bg-base-100 p-lg text-base-content shadow-xl", size === "fill"
             ? "fixed inset-0 h-full w-full max-w-none"
-            : "max-h-screen w-11/12 max-w-(--container-lg)", resolveClassName(className, state)), finalFocus: dialog.interactionOwner === "host" ? false : (finalFocus ?? true), ref: ref }));
+            : "caps-dialog-popup-default", resolveClassName(className, state)), finalFocus: dialog.interactionOwner === "host" ? false : (finalFocus ?? true), ref: ref }));
 });
 /**
  * The default portal, backdrop and popup composition for a Dialog.

package/dist/components/failure-line.d.ts

@@ -0,0 +1,46 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+/** Props accepted by FailureLine. */
+export type FailureLineProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    /** One plain line naming the real cause; never a raw code. */
+    message: ReactNode;
+    /** Called when Retry is chosen; without it no Retry button shows. */
+    onRetry?: () => void;
+    /** Called when Dismiss is chosen; without it no Dismiss button shows. */
+    onDismiss?: () => void;
+    retryLabel?: string;
+    dismissLabel?: string;
+    /** A more specific accessible name for Retry, such as "Retry prompt". */
+    retryAriaLabel?: string;
+    /** A more specific accessible name for Dismiss. */
+    dismissAriaLabel?: string;
+    /** How many times it failed; above 1 the line adds a "Failed" line with the count once. */
+    count?: number;
+    /** `row` sits in a list or under a control; `tile` fills a media tile. */
+    density?: "row" | "tile";
+    /** `status` is polite; use `alert` only for a single, urgent failure. */
+    role?: "status" | "alert";
+};
+/**
+ * One item failure: an error dot, one line, and labelled Retry and Dismiss.
+ * It never uses the bang glyph; the dot is the whole signal.
+ */
+export declare const FailureLine: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    /** One plain line naming the real cause; never a raw code. */
+    message: ReactNode;
+    /** Called when Retry is chosen; without it no Retry button shows. */
+    onRetry?: () => void;
+    /** Called when Dismiss is chosen; without it no Dismiss button shows. */
+    onDismiss?: () => void;
+    retryLabel?: string;
+    dismissLabel?: string;
+    /** A more specific accessible name for Retry, such as "Retry prompt". */
+    retryAriaLabel?: string;
+    /** A more specific accessible name for Dismiss. */
+    dismissAriaLabel?: string;
+    /** How many times it failed; above 1 the line adds a "Failed" line with the count once. */
+    count?: number;
+    /** `row` sits in a list or under a control; `tile` fills a media tile. */
+    density?: "row" | "tile";
+    /** `status` is polite; use `alert` only for a single, urgent failure. */
+    role?: "status" | "alert";
+} & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/failure-line.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef } from "react";
+import { Button } from "./button.js";
+import { Status } from "./status.js";
+import { cn } from "../lib/cn.js";
+/**
+ * One item failure: an error dot, one line, and labelled Retry and Dismiss.
+ * It never uses the bang glyph; the dot is the whole signal.
+ */
+export const FailureLine = forwardRef(function FailureLine({ className, count, density = "row", dismissAriaLabel, dismissLabel = "Dismiss", message, onDismiss, onRetry, retryAriaLabel, retryLabel = "Retry", role = "status", ...props }, ref) {
+    return (_jsxs("div", { ...props, className: cn("caps-failure-line", className), "data-density": density, ref: ref, role: role, children: [_jsx(Status, { glyph: "dot", tone: "error" }), _jsxs("span", { className: "caps-failure-line-copy", children: [_jsx("span", { children: message }), count !== undefined && count > 1 ? (_jsxs("span", { className: "caps-failure-line-count", children: ["Failed ", count, " times"] })) : null] }), onRetry || onDismiss ? (_jsxs("span", { className: "caps-failure-line-actions", children: [onRetry ? (_jsx(Button, { "aria-label": retryAriaLabel, size: "sm", variant: "outline", onClick: onRetry, children: retryLabel })) : null, onDismiss ? (_jsx(Button, { "aria-label": dismissAriaLabel, size: "sm", variant: "ghost", onClick: onDismiss, children: dismissLabel })) : null] })) : null] }));
+});

package/dist/components/keycap.d.ts

@@ -4,14 +4,22 @@ import { type ButtonHTMLAttributes, type HTMLAttributes, type ReactNode } from "
  * hovered or focused; the rest follow the theme.
  */
 export type KeycapTone = "neutral" | "primary" | "accent" | "inverse" | "destructive";
-/** Keycap sizes: a legend chip, a dock key and a big face key. */
-export type KeycapSize = "sm" | "md" | "lg";
+/**
+ * Keycap sizes: `hint` is a muted inline shortcut caption (caption height, no
+ * plastic), then a legend chip, a dock key and a big face key.
+ */
+export type KeycapSize = "hint" | "sm" | "md" | "lg";
 /** Props accepted by Keycap. */
 export type KeycapProps = HTMLAttributes<HTMLElement> & {
     tone?: KeycapTone;
     size?: KeycapSize;
     /** Show the key held down. Presentation only; the host owns input. */
     pressed?: boolean;
+    /**
+     * `hide` drops a keyboard legend on touch-first devices (`pointer: coarse`),
+     * where no one presses it.
+     */
+    touch?: "hide";
 };
 /**
  * One molded key legend, rendered as native `<kbd>`: the key a player presses.
@@ -22,6 +30,11 @@ export declare const Keycap: import("react").ForwardRefExoticComponent<HTMLAttri
     size?: KeycapSize;
     /** Show the key held down. Presentation only; the host owns input. */
     pressed?: boolean;
+    /**
+     * `hide` drops a keyboard legend on touch-first devices (`pointer: coarse`),
+     * where no one presses it.
+     */
+    touch?: "hide";
 } & import("react").RefAttributes<HTMLElement>>;
 /** Props accepted by KeycapButton. */
 export type KeycapButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children"> & {