@sableui/react 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,104 @@
 # What's new
 
+## 0.17.0
+
+Knowing where you are: a rail that follows a long read, and an approval
+that shows an agent's call the way agent products do.
+
+- **New: `SectionRail`.** A slim vertical rail of dots beside a long read —
+  a case study, an essay, a long landing page — one per section. A bar marks
+  the section being read and glides to the next as the page scrolls; hovering
+  or focusing a dot names it in one tooltip that travels between dots
+  (`TooltipGroup`). Picking a dot jumps there with the page's own
+  `scroll-behavior` (instant under reduced motion), and the bar goes straight
+  to the pick rather than stepping through every section in between. Pass
+  `root` when the content scrolls inside an element: only that element moves,
+  never the page around it. Links are real `#id` anchors, so it works without
+  script. Promoted from carldecaire.com's case-study rail.
+- **New: `useActiveSection(ids, { offset, root })`.** The scroll spy behind it,
+  exported for a contents list you draw yourself. The current section is the
+  last whose top has crossed the reading line; at the end of the scroll the
+  last one in view wins, so a short closing section is still reachable.
+- **`ApprovalBlock` asks the way agent products do.** It wraps the call's own
+  `ToolCall` — tool name and exact input, open on arrival — that turns to
+  Allowed or Denied once answered, and offers Deny / Always allow / Allow once.
+  The details table and the "for the rest of this chat" checkbox are gone;
+  `onApprove({ remember })` is unchanged, with `remember` now true for Always
+  allow. The example is an agent asking to run a command.
+
+## 0.16.0
+
+Five pieces of the calm, product-chrome look that AI and B2B tools share:
+tick-bar budgets, pastel art, filled fields, an inset frame and a dither
+texture. Each is told through the theme, so every preset can wear it.
+
+- **New: segmented meters.** `<Meter segments={40} />` draws the bar as a row
+  of ticks — a spend limit, credits left, a lead score, months of data — read
+  at a glance. Any reading above `min` shows at least one tick, and when the
+  value changes the fill runs through the ticks from the edge it is leaving.
+  Size the count to the track (about one tick per 8px) so a tick stays taller
+  than it is wide. `shape="ring"` ignores it.
+- **New: `GradientArt intensity="soft"`.** The same art as a pastel of itself:
+  lifted and quieted, bright in dark mode too. It is a stage for floating
+  chips, logo tiles and card header bands, not a surface for text.
+- **New: the field tokens, `field` and `field-border`.** Every text field —
+  Input, Textarea, Select, Combobox, SearchInput, NumberField, OTPField,
+  DatePicker, InputGroup, ChatComposer and CommandMenuTrigger — now paints
+  this pair, outlined on the card by default exactly as before. A theme fills
+  them all at once with `--theme-field: var(--muted)` and
+  `--theme-field-border: transparent`. Canvas has a matching **Fields**
+  control (Preset / Outline / Filled), and presets may set both hooks.
+  A hand-built field wearing `border-field-border` is caught by
+  `lookalike-control` like one wearing `border-input`.
+- **New: `AppShell frame="inset"`.** From `lg`, the rail and a small gap sit on
+  one ground and main becomes a rounded, bordered panel that scrolls inside
+  itself while the rail stays put. The Sidebar in the slot drops its border
+  and fills the row, and its footer rule spans the content column rather than
+  running out into the gap; below `lg` nothing changes. The ground is a new derived
+  token, `shell-ground` — one step off the rail, so the panel reads as lifted
+  even in themes whose rail is the page colour; tune it with
+  `--theme-shell-ground`. Inset moves the desktop scroll from `window` to
+  `#main-content`, so scroll listeners (restoration, scroll-to-top, scrollspy)
+  must target `main`.
+- **New utility: `texture-dither`.** A faint field of tiny squares that
+  dissolves, painted in `border-strong` so it follows every theme — decoration
+  for behind an empty state or a page header. `--dither-fade`,
+  `--dither-size` and `--dither-color` tune it.
+- **Status and tone colours at graphic strength.** Meters, segmented bars,
+  status dots, chart series and the soft tints behind badges, banners and
+  notes were painted with the label fills — dark enough to carry white text,
+  so in light mode they read brown, forest green and plum. They now read new
+  `-mark` tokens (`success-mark`, `tone-warning-mark`, `destructive-mark`,
+  `tone-info-mark`, `tone-1/2/3-mark`): the same hue lifted and saturated,
+  held to a 2:1 visibility floor on the page instead of a text ratio. Every
+  bundled theme tunes its own in both modes, and keeps its character —
+  Ember's olive, Poppy's pastels and Atelier's grey tone stay theirs; a
+  preset sets `--theme-*-mark` or gets one derived from its fill. Labels are
+  unchanged: solid badges, banners and buttons keep their fills, and text
+  keeps `-text`. `markFor` (from `@sableui/react/presets`) derives a mark the
+  same way, and Canvas moves the marks with any tone it generates.
+- **Canvas: a brand colour no longer flattens the tones.** Info is treated
+  as the status it is: it leans toward the brand within the blues instead of
+  being repainted (Brand only made it the brand, so a green brand's info read
+  as success; the schemes spun it anywhere). A status also keeps 25° off the
+  brand's own hue when its band allows, so a green brand gets a teal success
+  rather than a second copy of itself. And Brand only is a family you can tell
+  apart — a deep brand, a lighter neighbour and a muted sibling — instead of
+  one hue in four near-identical depths.
+- **Table:** `numeric` on TableHead and TableCell is now documented.
+- **New: search matches light up.** Combobox and CommandMenu paint the typed
+  text in each row's label, on a tint of the theme's `highlight`. It uses the CSS
+  Custom Highlight API, so rows get no `<mark>` wrappers and their accessible
+  names stay whole; browsers without it simply show no paint. Combobox lights
+  only what was typed, not a label a pick filled in. `highlightMatches={false}`
+  turns it off on either.
+- **New hook: `useMatchHighlight(query, { selector })`.** The same paint for a
+  results list you filter yourself, such as a SearchInput over a table: it
+  returns a callback ref for the results container.
+- **Textarea:** text you are editing no longer rewraps above the caret when
+  the field sits inside a `text-pretty` or `text-balance` block
+  (`text-wrap-style: stable`). ChatComposer gets the same fix.
+
 ## 0.15.0
 
 Motion with some life in it: small things that turn on now land like events,

package/bin/sable-lint.mjs

@@ -44,7 +44,11 @@ if (!existsSync(registryPath)) {
 }
 const REGISTRY = JSON.parse(readFileSync(registryPath, "utf8"))
 
-const semanticTokens = new Set((REGISTRY.tokens?.semantic ?? []).map((t) => t.name))
+// Derived colours (`tone-warning-mark`, `field`, `shell-ground`…) are real tokens
+// too: every theme gets them, so a utility naming one is not a typo.
+const semanticTokens = new Set(
+	[...(REGISTRY.tokens?.semantic ?? []), ...(REGISTRY.tokens?.derived ?? [])].map((t) => (typeof t === "string" ? t : t.name)),
+)
 // Motion token NAMES are reassembled from the registry's durations/easings lists.
 // A test in the package asserts this reconstruction equals _contract.ts exactly,
 // so the consumer linter can never validate against a drifted vocabulary.

package/dist/{_contract-CkqXDVww.d.ts → _contract-CDa9-NdB.d.ts}

@@ -147,6 +147,52 @@ declare const ART_TOKENS: readonly ["art-1", "art-2", "art-3", "art-4", "art-5",
  *   2 doubles it, for a theme that wants every colour to read as its own.
  */
 declare const PALETTE_TOKENS: readonly ["palette-harmony"];
+/**
+ * The text field's surface — derived like the edges, with a `--theme-*` hook.
+ *
+ * - `field` is the fill of every text-entry field (Input, Textarea, Select,
+ *   Combobox, SearchInput, InputGroup, ChatComposer…). It defaults to `card`.
+ * - `field-border` is that field's outline. It defaults to `input`.
+ *
+ * Together they are the one choice a theme makes about how a field reads:
+ * outlined on the card (the default), or filled — `--theme-field: var(--muted)`
+ * with `--theme-field-border: transparent` — the borderless grey well some
+ * product UIs use for every input. Every field wears the pair through
+ * lib/field-shell, so the choice reaches them all at once instead of being
+ * restyled per control.
+ */
+declare const FIELD_TOKENS: readonly ["field", "field-border"];
+/**
+ * The ground of an inset app frame — derived, with a `--theme-*` hook.
+ *
+ * `<AppShell frame="inset">` lifts main into a rounded panel and paints the
+ * rail and the gap around it as one surface. That surface cannot simply be
+ * `sidebar`: most themes paint the rail the page's own colour, so the panel
+ * sat on a ground of the same colour and only its hairline told them apart.
+ * `shell-ground` is one small step off the rail toward its ink, so the panel
+ * reads as lifted in every theme, and a theme sets `--theme-shell-ground` for
+ * a stronger or tinted ground.
+ */
+declare const APP_SHELL_TOKENS: readonly ["shell-ground"];
+/**
+ * Status and tone colours at GRAPHIC strength — derived, with `--theme-*` hooks.
+ *
+ * Each status colour already comes in two: the fill, which carries a label
+ * (dark enough for white ink at 4.5:1 in light mode), and `-text`, the colour
+ * as ink on a surface. Neither is right for a mark that carries no text — a
+ * meter's fill, a segmented bar, a status dot, a chart series, the soft tint
+ * behind a badge. Those were painted with the label fill, so in light mode
+ * every one of them was a deep brown, forest green or plum: muddy, and 5–9:1
+ * against the page when a graphic needs far less.
+ *
+ * A mark is the same hue lifted and saturated. It is held to a VISIBILITY floor
+ * of 2:1 against `background` and `card` (NON_TEXT_HARD_FLOOR, the `graphic`
+ * tier in contrast.ts), not to a text ratio: every mark that uses it sits
+ * beside text that states the same thing (a meter's reading, a dot's label).
+ * A graphic that is the ONLY carrier of its meaning still owes WCAG 1.4.11's
+ * 3:1 — use the fill, or add the text.
+ */
+declare const MARK_TOKENS: readonly ["destructive-mark", "success-mark", "tone-warning-mark", "tone-info-mark", "tone-1-mark", "tone-2-mark", "tone-3-mark"];
 /**
  * UI type tiers (mode-independent) — the chrome typography register.
  *
@@ -193,4 +239,4 @@ interface ThemeManifest {
     };
 }
 
-export { ART_TOKENS as A, DENSITY_TOKENS as D, MOTION_TOKENS as M, PALETTE_TOKENS as P, RADIUS_TOKENS as R, SEMANTIC_TOKENS as S, type ThemeManifest as T, WORKSPACE_SURFACE_TOKENS as W, type ThemeMode as a, type DensityToken as b, type MotionToken as c, RHYTHM_TOKENS as d, type RadiusToken as e, type RhythmToken as f, type SemanticToken as g, TYPE_OVERLINE_TOKENS as h, TYPE_REFINEMENT_TOKENS as i, TYPE_SCALE_TOKENS as j, TYPE_UI_TOKENS as k, type TypeOverlineToken as l, type TypeRefinementToken as m, type TypeScaleToken as n, type TypeUiToken as o, type WorkspaceSurfaceToken as p };
+export { APP_SHELL_TOKENS as A, DENSITY_TOKENS as D, FIELD_TOKENS as F, MARK_TOKENS as M, PALETTE_TOKENS as P, RADIUS_TOKENS as R, SEMANTIC_TOKENS as S, type ThemeManifest as T, WORKSPACE_SURFACE_TOKENS as W, type ThemeMode as a, ART_TOKENS as b, type DensityToken as c, MOTION_TOKENS as d, type MotionToken as e, RHYTHM_TOKENS as f, type RadiusToken as g, type RhythmToken as h, type SemanticToken as i, TYPE_OVERLINE_TOKENS as j, TYPE_REFINEMENT_TOKENS as k, TYPE_SCALE_TOKENS as l, TYPE_UI_TOKENS as m, type TypeOverlineToken as n, type TypeRefinementToken as o, type TypeScaleToken as p, type TypeUiToken as q, type WorkspaceSurfaceToken as r };

package/dist/blocks/approval-block.js

@@ -1,59 +1,48 @@
 // src/blocks/approval-block.tsx
-import { useEffect, useId, useRef, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import { Button } from "../components/button/index.js";
 import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from "../components/card/index.js";
-import { Checkbox } from "../components/checkbox/index.js";
-import { Code } from "../components/code/index.js";
 import { InlineStatus } from "../components/inline-status/index.js";
-import { Label } from "../components/label/index.js";
+import { ToolCall } from "../components/tool-call/index.js";
 import { cn } from "../lib/cn.js";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 var request = {
-  tool: "send_email",
-  title: "Send the invoice to Ada?",
-  description: "The agent wants to email invoice INV-1042. An email can't be unsent.",
-  details: [
-    { label: "To", value: "ada@example.com" },
-    { label: "Subject", value: "INV-1042 for October" },
-    { label: "Attached", value: "INV-1042.pdf" }
-  ],
-  allowed: "Allowed. Sending the email.",
-  denied: "Denied. The agent won't send it."
+  title: "Run this command?",
+  description: "The agent wants to migrate the production database in acme/api. It changes live data.",
+  tool: "run_command",
+  action: "Run a command",
+  // A command reads as the command; a structured call would pass its arguments object.
+  input: "pnpm db:migrate --env production",
+  allowed: "Allowed. Running the migration.",
+  denied: "Denied. The agent won't run it."
 };
 function ApprovalBlock({ className, framed = true, onApprove, onDeny }) {
   const [decision, setDecision] = useState(null);
-  const [remember, setRemember] = useState(false);
-  const id = useId();
   const outcome = useRef(null);
   useEffect(() => {
     if (decision) outcome.current?.focus();
   }, [decision]);
+  const approve = (remember) => {
+    setDecision("allowed");
+    onApprove?.({ remember });
+  };
   return /* @__PURE__ */ jsxs(Card, { variant: framed ? "default" : "flat", className: cn("w-full max-w-md", className), children: [
     /* @__PURE__ */ jsxs(CardHeader, { children: [
       /* @__PURE__ */ jsx(CardTitle, { children: request.title }),
       /* @__PURE__ */ jsx(CardDescription, { children: request.description })
     ] }),
-    /* @__PURE__ */ jsxs(CardContent, { className: "flex flex-col gap-4", children: [
-      /* @__PURE__ */ jsxs("dl", { className: "grid grid-cols-[auto_minmax(0,1fr)] gap-x-4 gap-y-1.5 text-body-sm", children: [
-        request.details.map((d) => /* @__PURE__ */ jsxs("div", { className: "contents", children: [
-          /* @__PURE__ */ jsx("dt", { className: "text-muted-foreground", children: d.label }),
-          /* @__PURE__ */ jsx("dd", { className: "truncate text-foreground", children: d.value })
-        ] }, d.label)),
-        /* @__PURE__ */ jsxs("div", { className: "contents", children: [
-          /* @__PURE__ */ jsx("dt", { className: "text-muted-foreground", children: "Tool" }),
-          /* @__PURE__ */ jsx("dd", { className: "min-w-0", children: /* @__PURE__ */ jsx(Code, { children: request.tool }) })
-        ] })
-      ] }),
-      decision ? null : /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-2", children: [
-        /* @__PURE__ */ jsx(Checkbox, { id: `${id}-remember`, checked: remember, onCheckedChange: (v) => setRemember(v) }),
-        /* @__PURE__ */ jsxs(Label, { htmlFor: `${id}-remember`, className: "text-body-sm", children: [
-          "Allow ",
-          /* @__PURE__ */ jsx(Code, { children: request.tool }),
-          " for the rest of this chat"
-        ] })
-      ] })
-    ] }),
-    /* @__PURE__ */ jsx(CardFooter, { actions: true, className: "justify-end", children: decision ? /* @__PURE__ */ jsx(
+    /* @__PURE__ */ jsx(CardContent, { children: /* @__PURE__ */ jsx(
+      ToolCall,
+      {
+        name: request.tool,
+        title: request.action,
+        status: decision === "allowed" ? "complete" : decision === "denied" ? "denied" : "awaiting",
+        statusLabel: decision === "allowed" ? "Allowed" : void 0,
+        input: request.input,
+        defaultOpen: true
+      }
+    ) }),
+    /* @__PURE__ */ jsx(CardFooter, { actions: true, children: decision ? /* @__PURE__ */ jsx(
       InlineStatus,
       {
         ref: outcome,
@@ -67,7 +56,8 @@ function ApprovalBlock({ className, framed = true, onApprove, onDeny }) {
       /* @__PURE__ */ jsx(
         Button,
         {
-          variant: "outline",
+          variant: "ghost",
+          className: "me-auto",
           onClick: () => {
             setDecision("denied");
             onDeny?.();
@@ -75,16 +65,8 @@ function ApprovalBlock({ className, framed = true, onApprove, onDeny }) {
           children: "Deny"
         }
       ),
-      /* @__PURE__ */ jsx(
-        Button,
-        {
-          onClick: () => {
-            setDecision("allowed");
-            onApprove?.({ remember });
-          },
-          children: "Allow"
-        }
-      )
+      /* @__PURE__ */ jsx(Button, { variant: "outline", onClick: () => approve(true), children: "Always allow" }),
+      /* @__PURE__ */ jsx(Button, { onClick: () => approve(false), children: "Allow once" })
     ] }) })
   ] });
 }

package/dist/blocks/approval-block.meta.js

@@ -4,18 +4,17 @@ var approvalBlockMeta = {
   family: "AI & agents",
   kind: "card",
   width: { min: "18rem", max: "28rem" },
-  summary: `An agent asking permission for one tool call: the question, what will happen and what can't be undone, the call's details, an "allow for the rest of this chat" Checkbox, and Deny / Allow.`,
-  intent: 'Reach for this in a chat or agent run when a tool call waits on the person \u2014 sending, paying, deleting, publishing. The call itself, before and after the decision, is a ToolCall with status="awaiting", then "complete" or "denied". A destructive action outside an agent is DestructiveActionModal.',
+  summary: "An agent asking permission for one tool call: the question, what is at stake, the call itself as a ToolCall with its exact input, and Deny / Always allow / Allow once.",
+  intent: `Reach for this in a chat or agent run when a tool call waits on the person \u2014 running a command, sending, paying, deleting, publishing. It wraps the call's own ToolCall, which shows status="awaiting" until the person answers and then "complete" or "denied". A destructive action outside an agent is DestructiveActionModal.`,
   notes: [
-    `The title is the question in plain words ("Send the invoice to Ada?"), not the tool's name; the tool's name is one row of the details, for the person who wants to know exactly what runs.`,
-    "The description says what can't be undone. That sentence is what the person is deciding on.",
-    "Deny comes first and Allow is the primary on the end, the same order as every Sable confirmation. Neither is focused on arrival: an approval that a stray Enter can grant is not an approval.",
-    "After a decision the buttons give way to one InlineStatus line saying what happened, so the thread keeps a record of the answer."
+    'The title is the question in plain words ("Run this command?"); the description says what is at stake. That sentence is what the person is deciding on.',
+    "The call is shown as the agent made it \u2014 tool name and raw input, open on arrival \u2014 because the exact arguments are what a careful person checks. Do not paraphrase them into a form.",
+    "Three answers, as agent products settle on: Deny on the start edge, then Always allow and Allow once, the primary on the end. Neither is focused on arrival: an approval that a stray Enter can grant is not an approval.",
+    "After a decision the buttons give way to one InlineStatus line saying what happened, and the ToolCall shows the outcome, so the thread keeps a record of the answer."
   ],
   a11y: [
     "Focus moves to the outcome line when the buttons leave, instead of dropping to the page; the line is a role=status region, so the decision is announced.",
-    "The details are a dl, so each value is read with its label.",
-    "The remember Checkbox has its own Label, so the tool name inside it is part of its accessible name."
+    "The ToolCall announces its own status change, and its input is a labelled code view."
   ]
 };
 export {

package/dist/blocks/index.d.ts

@@ -17,7 +17,7 @@ interface ApprovalBlockProps {
     className?: string;
     /** false drops the card's surface and border — for a chat column that already frames it. */
     framed?: boolean;
-    /** The person allowed the call. `remember` is the "for the rest of this chat" choice. */
+    /** The person allowed the call. `remember` is true for "Always allow". */
     onApprove?: (options: {
         remember: boolean;
     }) => void;

package/dist/blocks/wallet-block.js

@@ -11,6 +11,7 @@ var activity = [
   { title: "Refund", detail: "Order 1042 \xB7 Yesterday", amount: "-24.00", tone: "2" },
   { title: "Payout", detail: "To checking \xB7 Mon", amount: "-850.00", tone: "3" }
 ];
+var TONE_MARK = { "1": "bg-tone-1-mark", "2": "bg-tone-2-mark", "3": "bg-tone-3-mark" };
 function WalletBlock({ className, framed = true, onSend, onReceive }) {
   return /* @__PURE__ */ jsxs(Card, { variant: framed ? "default" : "flat", className: cn("w-full max-w-xs", className), children: [
     /* @__PURE__ */ jsxs(CardHeader, { children: [
@@ -30,8 +31,7 @@ function WalletBlock({ className, framed = true, onSend, onReceive }) {
             "span",
             {
               "aria-hidden": true,
-              className: "block size-8 rounded-full",
-              style: { background: `oklch(from var(--tone-${item.tone}) clamp(0.5, calc(l + 0.16), 0.9) max(calc(c * 1.25), 0.1) h)` }
+              className: cn("block size-8 rounded-full", TONE_MARK[item.tone])
             }
           ),
           title: item.title,

package/dist/components/app-shell/app-shell-frame.js

@@ -0,0 +1,16 @@
+"use client";
+
+// src/components/app-shell/app-shell-frame.tsx
+import { createContext, useContext } from "react";
+import { jsx } from "react/jsx-runtime";
+var AppShellFrameContext = createContext(null);
+function AppShellFrameProvider({ frame, children }) {
+  return /* @__PURE__ */ jsx(AppShellFrameContext.Provider, { value: frame, children });
+}
+function useAppShellFrame() {
+  return useContext(AppShellFrameContext);
+}
+export {
+  AppShellFrameProvider,
+  useAppShellFrame
+};

package/dist/components/app-shell/app-shell-main.js

@@ -0,0 +1,12 @@
+"use client";
+
+// src/components/app-shell/app-shell-main.tsx
+import { useScrollActivity } from "../../lib/use-scroll-activity.js";
+import { jsx } from "react/jsx-runtime";
+function AppShellMain({ scrolls, ...props }) {
+  const trackScroll = useScrollActivity();
+  return /* @__PURE__ */ jsx("main", { ref: scrolls ? trackScroll : void 0, ...props });
+}
+export {
+  AppShellMain
+};

package/dist/components/app-shell/app-shell.js

@@ -1,6 +1,8 @@
 // src/components/app-shell/app-shell.tsx
 import { cn } from "../../lib/cn.js";
 import { AppShellDock } from "./app-shell-dock.js";
+import { AppShellFrameProvider } from "./app-shell-frame.js";
+import { AppShellMain } from "./app-shell-main.js";
 import { SkipLink } from "./skip-link.js";
 import { jsx, jsxs } from "react/jsx-runtime";
 function AppShell({
@@ -10,18 +12,27 @@ function AppShell({
   bottomNav,
   dock,
   overlays,
+  frame = "flush",
   className,
   children,
   ...rest
 }) {
+  const inset = frame === "inset";
   return /* @__PURE__ */ jsxs(
     "div",
     {
+      "data-frame": inset ? "inset" : void 0,
       className: cn(
         // `overflow-x-clip` (not `-hidden`) contains horizontal bleed WITHOUT
         // establishing a scroll container — `-hidden` forces `overflow-y: auto`,
         // which breaks `position: sticky` on a descendant Sidebar.
         "flex min-h-screen flex-col overflow-x-clip bg-background text-foreground",
+        // Inset, from lg: the shell IS the viewport and never scrolls — main
+        // does. The ground is the rail's surface, so the rail and the gap
+        // around the panel read as one plane. A page-surface rail (Sidebar
+        // surface="page") is page-coloured, so the ground follows it and the
+        // panel's border carries the lift.
+        inset && "lg:h-dvh lg:min-h-0 lg:bg-shell-ground lg:[&:has(>[data-app-shell-body]>[data-surface=page])]:bg-background",
         className
       ),
       ...rest,
@@ -29,16 +40,29 @@ function AppShell({
         /* @__PURE__ */ jsx(SkipLink, {}),
         banners ? /* @__PURE__ */ jsx("div", { className: "relative z-(--z-nav)", children: banners }) : null,
         header,
-        /* @__PURE__ */ jsxs("div", { className: "flex min-h-0 flex-1", children: [
-          sidebar,
+        /* @__PURE__ */ jsxs("div", { "data-app-shell-body": inset ? "" : void 0, className: "flex min-h-0 flex-1", children: [
+          inset ? /* @__PURE__ */ jsx(AppShellFrameProvider, { frame: "inset", children: sidebar }) : sidebar,
           /* @__PURE__ */ jsx(
-            "main",
+            AppShellMain,
             {
               id: "main-content",
+              scrolls: inset,
+              tabIndex: inset ? -1 : void 0,
               style: { containerType: "inline-size" },
               className: cn(
                 "min-w-0 flex-1",
-                bottomNav && "pb-[calc(var(--nav-height)+env(safe-area-inset-bottom,0px))] lg:pb-0"
+                bottomNav && "pb-[calc(var(--nav-height)+env(safe-area-inset-bottom,0px))] lg:pb-0",
+                // The inset panel. A spacing-step gap on the open sides (the rail
+                // is the leading one). Banners and the dock are in flow in the
+                // shell's column, so the bottom gap already sits above a dock.
+                // Sticky children stick to the panel's top, and the overflow
+                // clips them to its rounded corners. A resting surface: a hairline
+                // edge and the subtlest raise, never a floating shadow.
+                inset && cn(
+                  "outline-none lg:m-2 lg:overflow-y-auto lg:overscroll-contain scrollbar-quiet",
+                  "lg:rounded-lg lg:border lg:border-border lg:bg-background lg:shadow-sm",
+                  sidebar && "lg:ms-0"
+                )
               ),
               children
             }

package/dist/components/app-shell/app-shell.meta.js

@@ -15,7 +15,12 @@ var appShellMeta = {
     "dock",
     "player bar",
     "now playing",
-    "persistent"
+    "persistent",
+    "inset",
+    "inset frame",
+    "floating panel",
+    "rounded content",
+    "scroll container"
   ],
   usage: {
     description: "Use AppShell as the outer product frame for authenticated or app-like experiences. It coordinates responsive chrome slots and guarantees a skip link plus main landmark; put route content inside the children and let AppHeader, Sidebar, BottomNav, and Banner own their own semantics.",
@@ -36,10 +41,23 @@ var appShellMeta = {
         guidance: "do",
         description: "Wrap EVERY return of a route in its own Page or Region \u2014 including early returns for loading, empty and error states. AppShell's <main> deliberately carries no padding (it is a frame, and padding belongs to the region that chose the width), so a route that returns a bare spinner or error renders flush against the chrome. This is the most common conversion bug: the happy path gets a Page, the three early returns do not."
       },
+      {
+        guidance: "do",
+        description: `Use frame="inset" for dense, multi-pane product apps \u2014 a CRM, an issue tracker, an AI workspace \u2014 where framing the content as one raised panel on the rail's ground helps it read as the workspace and the rail as chrome. Keep the Sidebar on surface="rail" so its tint is the ground. Inset moves the page scroll from the window to <main id="main-content"> on desktop: point scroll listeners, scroll restoration and scroll-to-top at that element, not window.`
+      },
       {
         guidance: "dont",
         description: "Nest AppShell inside route cards or panels. It is page chrome, not local content."
       },
+      {
+        guidance: "dont",
+        description: "Wrap a route in its own h-full overflow-y-auto box inside an inset shell. main is already the page's scroll container; a second one traps the scrollbar inside a smaller box and breaks sticky headers and the skip link's scroll target. Scroll a genuinely separate pane (a list beside a detail view) with Scroller.",
+        instead: ["Scroller"]
+      },
+      {
+        guidance: "dont",
+        description: 'Combine frame="inset" with a full-width header bar above the rail. The inset ground is the rail running the full height of the window; a bar across the top cuts it off. Use the flush frame with Sidebar surface="page" for that layout.'
+      },
       {
         guidance: "dont",
         description: "Put desktop-only navigation in the mobile header slot or mobile-only controls in the sidebar slot."
@@ -64,7 +82,7 @@ var appShellMeta = {
       {
         name: "Main",
         required: true,
-        description: "The route content landmark with id main-content."
+        description: 'The route content landmark with id main-content. With frame="inset", from lg it is a rounded, bordered panel that scrolls inside itself.'
       },
       {
         name: "Bottom nav",
@@ -113,6 +131,12 @@ var appShellMeta = {
       name: "overlays",
       type: "ReactNode",
       description: "Floating overlays \u2014 a message launcher, FAB, or modal mount points."
+    },
+    {
+      name: "frame",
+      type: '"flush" | "inset"',
+      default: '"flush"',
+      description: `How the desktop frame (lg and up) holds the content; below lg both are the same mobile layout with page scroll. "flush": main sits on the page beside the rail and the document scrolls. "inset": the shell fills the viewport and paints the shell-ground token (one step off the rail's surface, tunable with --theme-shell-ground) behind the rail and around the panel; main becomes a rounded-lg panel with a hairline border and shadow-sm, inset by a spacing step from the window edges, that scrolls inside itself (scrollbar-quiet) while the rail stays put. The Sidebar in the sidebar slot drops its right border and fills the row. main stays the #main-content target (tabIndex -1, so the skip link lands focus in the scroller) and the inline-size query container; sticky children stick to the panel's top; banners and the dock stay in flow, so the panel's bottom gap sits above a dock. With Sidebar surface="page" the ground is the page colour and the panel's border alone lifts it.`
     }
   ],
   subcomponents: [
@@ -126,9 +150,10 @@ var appShellMeta = {
     "Renders a skip link to #main-content as the first focusable element.",
     'Wraps content in a <main id="main-content"> landmark.',
     "Slot components own their own ARIA (nav landmarks, labels).",
-    "The dock follows <main> in DOM order, so keyboard and screen-reader users reach the player after the page content, not before it."
+    "The dock follows <main> in DOM order, so keyboard and screen-reader users reach the player after the page content, not before it.",
+    'With frame="inset", <main> is the desktop scroll container and takes tabIndex -1: the skip link moves focus into it, so PageDown and the arrow keys scroll the content, without adding a tab stop.'
   ],
-  tokensUsed: ["background", "foreground", "primary", "primary-foreground"],
+  tokensUsed: ["background", "foreground", "primary", "primary-foreground", "sidebar", "shell-ground", "border"],
   examples: [
     {
       label: "Full frame",
@@ -154,6 +179,65 @@ var appShellMeta = {
   <Region max="feed">
     <PageHeader title="Home" description="Latest posts from people you follow." />
   </Region>
+</AppShell>`
+    },
+    {
+      label: "Inset frame",
+      code: `<AppShell
+  frame="inset"
+  header={<AppHeader title="Pipeline" />}
+  sidebar={
+    <Sidebar>
+      <SidebarHeader>
+        <SidebarBrand mark={<Icon name="gem" variant="solid" />} label="Relay" render={<Link to="/" />} />
+      </SidebarHeader>
+      <SidebarNav>
+        <SidebarItem icon={<Icon name="inbox" />} label="Inbox" render={<Link to="/inbox" />} />
+        <SidebarItem icon={<Icon name="user" />} label="People" active render={<Link to="/people" />} />
+        <SidebarItem icon={<Icon name="folder" />} label="Companies" render={<Link to="/companies" />} />
+      </SidebarNav>
+    </Sidebar>
+  }
+  bottomNav={
+    <BottomNav>
+      <BottomNavItem icon={<Icon name="inbox" />} label="Inbox" render={<Link to="/inbox" />} />
+      <BottomNavItem icon={<Icon name="user" />} label="People" active render={<Link to="/people" />} />
+      <BottomNavItem icon={<Icon name="folder" />} label="Companies" render={<Link to="/companies" />} />
+    </BottomNav>
+  }
+>
+  <Page max="wide" gap={4} className="py-6">
+    <PageHeader
+      title="People"
+      description="Everyone in your pipeline, newest first."
+      actions={<Button><Icon name="plus" />Add person</Button>}
+    />
+    <Card>
+      <CardContent flush>
+        <Table>
+          <TableHeader>
+            <TableRow>
+              <TableHead>Name</TableHead>
+              <TableHead>Company</TableHead>
+              <TableHead numeric>Deals</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            <TableRow>
+              <TableCell>Ada Lovelace</TableCell>
+              <TableCell>Northwind</TableCell>
+              <TableCell numeric>4</TableCell>
+            </TableRow>
+            <TableRow>
+              <TableCell>Grace Hopper</TableCell>
+              <TableCell>Harbor Labs</TableCell>
+              <TableCell numeric>2</TableCell>
+            </TableRow>
+          </TableBody>
+        </Table>
+      </CardContent>
+    </Card>
+  </Page>
 </AppShell>`
     },
     {

package/dist/components/area-chart/area-chart.meta.js

@@ -176,7 +176,12 @@ var areaChartMeta = {
     "popover",
     "popover-foreground",
     "foreground",
-    "background"
+    "background",
+    "tone-warning-mark",
+    "tone-info-mark",
+    "tone-1-mark",
+    "tone-2-mark",
+    "tone-3-mark"
   ],
   motion: [
     {

package/dist/components/attachment/attachment.meta.js

@@ -146,7 +146,8 @@ var attachmentMeta = {
     "destructive",
     "overlay",
     "overlay-foreground",
-    "ring"
+    "ring",
+    "destructive-mark"
   ],
   motion: [
     {

package/dist/components/attachment/attachment.variants.js

@@ -13,7 +13,7 @@ var attachmentVariants = cva(
       status: {
         idle: "border-border bg-card",
         uploading: "border-border bg-card",
-        error: "border-destructive/40 bg-destructive/5"
+        error: "border-destructive-mark/40 bg-destructive-mark/5"
       },
       interactive: {
         true: "hover:border-border-strong",