@starci/grammar 0.12.14 → 0.14.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 StarCi
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 StarCi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,7 +2,7 @@
 
 `@starci/grammar` splits a UI kit into one shared contract and several visual families. The
 contract has no business logic. Common owns the typed props, semantics, renderer anatomy, universal
-states and scales, and the family registry. Core, Heritage and Offset Pop are sibling families.
+states and scales, and the family registry. Core and Offset Pop are sibling families.
 Each one implements the same contract with its own scoped visual DNA. The package contains no
 routes, domain entities, product decisions or feature-named shells.
 
@@ -13,8 +13,6 @@ only: props, DOM, ARIA and keyboard behaviour stay the same.
 
 ```sh
 npm install @starci/grammar @heroui/react react react-dom
-# while developing inside this repository:
-npm install ./.claude/packages/grammar
 ```
 
 The package needs Node.js 22 or newer. Its peer dependencies are React 18+, `@xyflow/react` 12 (for `FlowGraph`) and `@heroui/react`
@@ -25,14 +23,10 @@ exactly one Grammar family stylesheet. Each family sheet already imports Common
 | --- | --- | --- |
 | `@starci/grammar/common` | `GrammarRoot` (neutral) | `@starci/grammar/common/styles.css` (`common.css`) |
 | `@starci/grammar/core` | `CoreGrammarRoot` | `@starci/grammar/core/styles.css` (`core.css`) |
-| `@starci/grammar/heritage` | `HeritageGrammarRoot` | `@starci/grammar/heritage/styles.css` (`heritage.css`) |
 | `@starci/grammar/offset-pop` | `OffsetPopGrammarRoot` | `@starci/grammar/offset-pop/styles.css` (`offset-pop.css`) |
 
 The Core and Offset Pop entry points re-export all of Common, so an app imports its components and
-its root from one place. Heritage does not re-export Common. It exports `heritageGrammar`,
-`HeritageGrammarRoot`, its `Brand` extension (`HeritageBrand`), the `HeritageButton` and
-`HeritageHeading` aliases and its conformance, so import the other renderers from
-`@starci/grammar/common`.
+its root from one place.
 
 ## Usage
 
@@ -57,7 +51,7 @@ the complete placement mapping in light and dark, including destination, pending
 
 ### App shell
 
-The [app-shell canon](../../knowledge/ui/composition/app-shell.yaml) owns `FE-APP-SHELL-1` through `FE-APP-SHELL-7`.
+The [app-shell canon](../../contexts/ui/composition.md) owns `FE-APP-SHELL-1` through `FE-APP-SHELL-7`.
 The `Compositions/App shell` stories show the fixed shell, grouped sidebar, icon rail and mobile drawer.
 
 - `size="control"` is available on `Button`, `IconButton`, `TextAction`, `PlainPressable`, `IdentityLockup`, `Input` and `SearchField`, alongside `Switch`, `Avatar` and `AvatarButton`.
@@ -127,23 +121,6 @@ export const ProductSurface = () => (
 Core's DNA declares a shadow without a border at top surface depth, and a border without a shadow
 at nested depth.
 
-### Heritage
-
-```tsx
-import { TopBar } from "@starci/grammar/common"
-import { HeritageBrand, HeritageGrammarRoot } from "@starci/grammar/heritage"
-import "@starci/grammar/heritage/styles.css"
-
-export const Masthead = () => (
-  <HeritageGrammarRoot>
-    <TopBar brand={<a href="/"><HeritageBrand name="…" descriptor="…" logo={{ src: "/logo.svg", width: 40, height: 40 }} /></a>} />
-  </HeritageGrammarRoot>
-)
-```
-
-Heritage replaces only the root. It adds one extension, `Brand`, which is non-interactive brand
-content for a destination the consumer owns.
-
 ### Offset Pop
 
 ```tsx
@@ -167,11 +144,37 @@ offset shadow and a pink decision accent. Text that uses the accent is drawn in
 `OFFSET_POP_TOKEN_DEFAULTS`, `OFFSET_POP_DARK_TOKEN_DEFAULTS`, `OFFSET_POP_BAND_TOKEN_NAMES`,
 `offsetPopGrammar` and `offsetPopRuleConformance`.
 
+## Client-side navigation
+
+Every Grammar root (`GrammarRoot`, `CoreGrammarRoot`, `OffsetPopGrammarRoot`) accepts `navigate(path)` and `useHref(href)` and
+mounts react-aria's `RouterProvider`. Pass your router's functions once at the root and every Grammar `Link`, `Button href`,
+`Breadcrumbs` item, `ListBox`/`Menu` item `href` and `FlowGraph` node `href` navigates inside the app without a reload.
+
+```tsx
+import { useHref, useNavigate } from "react-router-dom"
+import { CoreGrammarRoot } from "@starci/grammar/core"
+
+export const Root = ({ children }: { children: React.ReactNode }) => {
+  const navigate = useNavigate()
+  return <CoreGrammarRoot navigate={(path) => navigate(path)} useHref={useHref}>{children}</CoreGrammarRoot>
+}
+```
+
+Mount the root inside the router. Without `navigate` the links behave as plain anchors.
+
+### FlowGraph layouts
+
+`FlowGraph` places nodes with `layout`: `radial` (the default), `layered` (a DAG in layers) or `manual` (each node's `position`).
+`direction="TB" | "LR"` puts the target handle on the entering side and the source handle on the leaving side so edges run along the
+layout, and selects `layered` when no layout is given. `headers={[{ label, at }]}` draws a column header above each layer for `LR` and
+a lane header beside it for `TB` (`at` is the layer index in `layered`, graph units in `manual`). `height` takes `sm | md | lg`, a number
+(pixels) or any CSS length. A node with `href` is a link through the root's router and one keyboard stop.
+
 ## Family scope and the overlay portal rule
 
 A family paints only inside its root. Each family stylesheet is scoped to
 `.grammar-common-root[data-grammar-family="<id>"]` inside its own cascade layer:
-`starci-grammar-common` comes first, then `-core`, `-heritage` and `-offset-pop`. No family sheet
+`starci-grammar-common` comes first, then `-core` and `-offset-pop`. No family sheet
 imports a sibling family's sheet. So two families can share a page, each inside its own root, and
 nested roots resolve to the innermost one.
 
@@ -246,7 +249,7 @@ className and no size. An item takes `id`, `label`, `description`, `descriptionL
   `size-4`, which is example content and not a component default, so 20px is StarCi's icon rule and not a vendor override.
 - `mark`: a decorative node instead of `iconSource`, e.g. an identity mark (`<Avatar size="sm" shape="rounded" isDecorative />`). The public type rejects both props together.
 - `tone: "danger"`: HeroUI's `danger` variant, which colours the label and the glyph. Sign out, delete, remove, leave workspace
-  and revoke are destructive; the lint rule `starci-grammar/destructive-menu-entry-needs-danger-tone` of `@starci/eslint-grammar-starci` refuses such an entry without it.
+  and revoke are destructive; the lint rule `starci-grammar/destructive-menu-entry-needs-danger-tone` of `@starci/eslint-grammar-core` refuses such an entry without it.
 
 A section takes `label` and optionally `selection` (`mode: "single" | "multiple"`, `selectedIds`, `onChange`). Between two
 adjacent entries, when either is a section, Grammar always inserts HeroUI's own `Separator`: the app cannot forget one. The selection
@@ -267,7 +270,7 @@ an item with a submenu).
 ```
 
 **HeroUI parity.** Grammar is a wrapper of HeroUI, so a wrapper keeps HeroUI's anatomy and defaults. The vendor reference
-(`knowledge/vendor/heroui/<component>.yaml` in the StarCi runtime) is measured from the installed `@heroui/react` and
+(`contexts/vendor/` of the StarCi harness) is measured from the installed `@heroui/react` and
 `@heroui/styles`; the gate `GRAMMAR_VENDOR_PARITY` fails a wrapper that renders a part HeroUI does not have, omits one it
 requires, restyles what the vendor decides, or replaces a vendor default, unless an owner-pinned override declares it. `ListBox`
 and `Select` are HeroUI's own list-box items (a `Label`, a `Description`, the item indicator at the end of the row).
@@ -430,8 +433,8 @@ person uses Avatar. The default `layout="row"` keeps the overlapping member row
 
 ## Theming
 
-- **Tokens.** Each family writes its DNA as CSS custom properties on its root: `--starci-core-*`,
-  `--heritage-*` or `--offset-pop-*`. It feeds those into the Common semantic variables that
+- **Tokens.** Each family writes its DNA as CSS custom properties on its root: `--starci-core-*`
+  or `--offset-pop-*`. It feeds those into the Common semantic variables that
   renderers read: `--accent`, `--accent-foreground`, `--focus`, `--background`, `--surface`,
   `--surface-secondary`, `--foreground`, `--muted`, `--border`, `--separator`, the status
   colours and their foregrounds, radii and shadow. Core also publishes a tertiary face under its own

package/dist/.build-stamp.json

@@ -1,9 +1,9 @@
 {
   "schema": "starci/grammar-build-stamp@1",
   "package": "@starci/grammar",
-  "version": "0.12.14",
+  "version": "0.14.0",
   "algorithm": "starci/grammar-source-digest@1",
-  "sourceDigest": "sha256:d0f747302686e5391934ba97b7fb91f582e15260a9b8e0eb4a25f365163bfdde",
-  "distDigest": "sha256:291edd4443f66c843492626af0a8d95c55549f58db0520c2d4d16273fb0b85d6",
-  "builtAt": "2026-10-26T21:41:52.449Z"
+  "sourceDigest": "sha256:abe48ef178e3f654d64eda3138e1bbc98b0d48d7f8fd27c09432d9966a6a99ec",
+  "distDigest": "sha256:d0879914392be475eacac5872c11615e3528982f7bae31376fc96801d23c97c9",
+  "builtAt": "2026-10-27T19:22:38.977Z"
 }

package/dist/common/components-forms.css

@@ -6,7 +6,7 @@
  *
  * Only structure, rhythm and the touch floor live here. Paint resolves through the semantic
  * variables every family binds (`--field-*`, `--accent`, `--danger`, `--muted`, `--focus`,
- * `--border`), so Core, Heritage and Offset Pop each get their own look without a Common colour.
+ * `--border`), so Core and Offset Pop each get their own look without a Common colour.
  * Spacing uses the Common 4px scale (0.25 / 0.5 / 0.75 / 1 / 1.5rem).
  *
  * `!important` appears only on the few declarations the vendor's field roots also set (display and
@@ -124,58 +124,42 @@
     }
 
     /*
-     * Loading field (knowledge STATE-8, Select and Textarea `isSkeleton`): the label stays real, the control is one
-     * Skeleton block of the loaded control's height (the select trigger 2.5rem, with the touch floor below; the textarea
-     * `rows` at 1.25rem a line plus its padding, never under the 5rem field minimum). Not focusable: no control exists.
+     * Loading field (knowledge STATE-8) with skeleton parity: the control renders its ready anatomy inside
+     * `.starci-core-field-skeleton-scope` (layout-neutral, inert), so label, description and control box keep the ready
+     * geometry by construction. Every control box in the scope is painted as a Skeleton (the vendor skeleton tint and
+     * shimmer); what it holds - a value, a placeholder, an indicator, a thumb - is not drawn. Its border stays, so a
+     * family's outline keeps the field box.
      */
-    /* The loading root (Field, Select, NumberField, SearchField, SegmentedControl, CheckboxGroup, Switch, Textarea): inert geometry that can shrink inside its row or column. */
-    .starci-core-field-skeleton {
-        min-width: 0;
-        pointer-events: none;
-        user-select: none;
-    }
-
-    .starci-core-field-skeleton-control { display: block; min-width: 0; }
+    .starci-core-field-skeleton-scope { display: contents; }
 
-    .starci-core-field-skeleton-control > .starci-core-skeleton {
-        block-size: 100%;
-        aspect-ratio: auto;
+    .starci-core-field-skeleton-scope :is([data-grammar-field-control="true"]:not(.starci-core-choice-group-options), .starci-core-input-field, [data-grammar-choice-control], [data-grammar-tag-id]) {
+        position: relative;
+        overflow: hidden;
+        background: color-mix(in oklab, var(--surface-tertiary, #e4e4e7) 70%, transparent) !important;
+        color: transparent !important;
+        user-select: none;
     }
 
-    .starci-core-field-skeleton-control:is([data-grammar-field-skeleton="input"]) { block-size: 2.5rem; }
-
-    /* The select trigger is HeroUI's own (min-h-9). */
-    .starci-core-field-skeleton-control[data-grammar-field-skeleton="select"] { block-size: var(--starci-core-control-min-size, 2.5rem); }
-
-    /* Joined segments: one block, a segment-width (5rem) per option, never wider than the field; `fill` takes the whole row. */
-    .starci-core-field-skeleton-control[data-grammar-field-skeleton="segmented"] {
-        block-size: 2.5rem;
-        inline-size: min(100%, calc(var(--starci-core-skeleton-segments, 2) * 5rem));
+    /* A control box whose rounded part is inside it (a ComboBox or SegmentedControl group, a Field control slot) takes the field radius. */
+    .starci-core-field-skeleton-scope [data-grammar-field-control="true"]:is(.starci-core-combo-box-group, .starci-core-segmented-control-group, .starci-core-field-control) {
+        border-radius: var(--field-radius, calc(var(--radius, 0.5rem) * 1.5));
     }
 
-    .starci-core-field-skeleton-control[data-grammar-field-skeleton="segmented"][data-width="fill"] { inline-size: 100%; }
-    .starci-core-field-skeleton-control[data-grammar-field-skeleton="segmented"][data-grammar-segmented-size="control"] { block-size: var(--starci-core-control-min-size, 2.75rem); }
-
-    /* A checkbox box and a switch track beside their real labels. */
-    .starci-core-field-skeleton-control[data-grammar-field-skeleton="choice"] { flex: none; block-size: 1rem; inline-size: 1rem; }
-    .starci-core-field-skeleton-control[data-grammar-field-skeleton="switch"] { flex: none; block-size: 1.25rem; inline-size: 2rem; }
-    .starci-core-field-skeleton-control[data-grammar-field-skeleton="switch"][data-grammar-switch-size="lg"] { block-size: 1.5rem; inline-size: 3rem; }
-    .starci-core-field-skeleton-control[data-grammar-field-skeleton="switch"][data-grammar-switch-size="control"] { block-size: var(--starci-core-control-min-size, 2.5rem); inline-size: 4.5rem; }
+    .starci-core-field-skeleton-scope :is([data-grammar-field-control="true"]:not(.starci-core-choice-group-options), [data-grammar-choice-control], [data-grammar-tag-id]) > * { visibility: hidden; }
+    .starci-core-field-skeleton-scope :is(input, textarea)::placeholder { color: transparent; }
 
-    .starci-core-field-skeleton-choice-label {
-        color: var(--foreground, CanvasText);
-        font-size: 0.875rem;
-        line-height: 1.25;
-    }
-
-    .starci-core-field-skeleton-control[data-grammar-field-skeleton="textarea"] {
-        block-size: max(5rem, calc(var(--starci-core-skeleton-rows, 4) * 1.25rem + 1rem));
+    .starci-core-field-skeleton-scope :is([data-grammar-field-control="true"]:not(.starci-core-choice-group-options, textarea), [data-grammar-choice-control], [data-grammar-tag-id])::after {
+        content: "";
+        position: absolute;
+        inset: 0;
+        visibility: visible;
+        background-image: linear-gradient(to right, transparent, var(--surface-tertiary, #e4e4e7), transparent);
+        translate: -100%;
+        animation: skeleton 2s linear infinite;
     }
 
-    @media (pointer: coarse), (max-width: 40rem) {
-        .starci-core-field-skeleton-control:is([data-grammar-field-skeleton="select"], [data-grammar-field-skeleton="input"], [data-grammar-field-skeleton="segmented"]) {
-            min-block-size: var(--starci-core-control-min-size, 2.5rem);
-        }
+    @media (prefers-reduced-motion: reduce) {
+        .starci-core-field-skeleton-scope :is([data-grammar-field-control="true"], [data-grammar-choice-control])::after { animation: none; content: none; }
     }
 
     .starci-core-combo-box-group,

package/dist/common/components-list-panel.css

@@ -21,6 +21,14 @@
         line-clamp: 2;
     }
 
+    .grammar-common-root [data-slot="description"][data-grammar-description-lines="wrap"] {
+        display: block;
+        -webkit-line-clamp: none;
+        line-clamp: none;
+        overflow: visible;
+        overflow-wrap: anywhere;
+    }
+
     .grammar-common-root [data-slot="description"][data-grammar-description-lines="3"] {
         -webkit-line-clamp: 3;
         line-clamp: 3;

package/dist/common/components-navigation.css

@@ -112,7 +112,7 @@
     /* A crumb whose label is not known yet (knowledge STATE-8): a short Skeleton text line of the label's size. */
     .starci-core-breadcrumb-skeleton { display: inline-block; inline-size: 6rem; }
     .starci-core-breadcrumb-skeleton > .starci-core-skeleton-group { gap: 0; }
-    .starci-core-breadcrumb-skeleton .starci-core-skeleton { block-size: 0.875rem; }
+    .starci-core-breadcrumb-skeleton .starci-core-skeleton { --starci-core-skeleton-line: 0.875rem; }
 
     @media (max-width: 30rem) {
         .starci-core-breadcrumb-label {
@@ -269,7 +269,7 @@
     .starci-core-step-skeleton-marker { border: 0; background: transparent; }
     .starci-core-step-skeleton-label { display: block; inline-size: 5rem; }
     .starci-core-step-skeleton-label > .starci-core-skeleton-group { gap: 0; }
-    .starci-core-step-skeleton-label .starci-core-skeleton { block-size: 0.875rem; }
+    .starci-core-step-skeleton-label .starci-core-skeleton { --starci-core-skeleton-line: 0.875rem; }
 
     .starci-core-step-copy {
         display: flex;
@@ -779,6 +779,26 @@
         white-space: nowrap;
     }
 
+    /* The reorder layer's event wrapper takes no box: the TagGroup lays out as if it were not there. */
+    .starci-core-tag-group-reorder {
+        display: contents;
+    }
+
+    /* Reorderable tags: the grab cursor, the lifted tag and the tag a drop would replace. */
+    .starci-core-tag-group[data-grammar-tag-reorderable="true"] .starci-core-tag[draggable="true"] {
+        cursor: grab;
+    }
+
+    .starci-core-tag-group[data-grammar-tag-reorderable="true"] .starci-core-tag[data-grammar-tag-dragging="true"] {
+        opacity: 0.5;
+        cursor: grabbing;
+    }
+
+    .starci-core-tag-group[data-grammar-tag-reorderable="true"] .starci-core-tag[data-grammar-tag-drop-target="true"] {
+        outline: 2px solid var(--accent, Highlight);
+        outline-offset: 2px;
+    }
+
     /*
      * Selectable chips (0.9.6, selectionMode single or multiple): a group of choices carries a 1px inset ring,
      * --border when unselected and --accent when selected. The chip face, hover and selected paint are HeroUI's own.
@@ -850,6 +870,15 @@
         width: max-content;
     }
 
+    /*
+     * A table that hosts editors, or has folded its low columns for a narrow container, fits the container instead:
+     * at max-content an editor's TagGroup never wraps its chips and the folded text never wraps, so the table ran
+     * past its container. It still scrolls sideways once its columns cannot shrink further.
+     */
+    .starci-core-data-table:is([data-grammar-table-editors="true"], [data-grammar-table-narrow="true"]) .starci-core-data-table-content {
+        width: 100%;
+    }
+
     .starci-core-data-table[data-grammar-table-sticky="true"] .starci-core-data-table-header {
         position: sticky;
         z-index: 1;
@@ -892,6 +921,65 @@
         box-sizing: border-box;
     }
 
+    /* A whole-row link target reads as one pressable row. */
+    .starci-core-data-table-row[data-grammar-table-row-link="true"] {
+        cursor: pointer;
+    }
+
+    /* An editor cell hosts a field; the field keeps its own control height and fills the column, never wider. */
+    .starci-core-data-table-editor {
+        display: flex;
+        min-width: 0;
+        max-inline-size: 100%;
+        align-items: center;
+        white-space: normal;
+    }
+
+    .starci-core-data-table-editor > * {
+        flex: 1 1 auto;
+        min-width: 0;
+    }
+
+    /*
+     * A text input's intrinsic width is its `size` (20 characters, about 11rem), which an auto-layout table takes as the
+     * column's minimum: a NumberField editor alone pushed the table past its container, even in narrow mode. In an editor
+     * cell the input asks for no width of its own and fills its track through its minimum (a percentage minimum does not
+     * count toward the column's intrinsic width), so the column can shrink to the room the table has and the input still
+     * fills what it gets, never less than three characters beside its own inline padding.
+     */
+    .starci-core-data-table-editor input {
+        inline-size: 0;
+        min-inline-size: max(calc(3ch + 1.5rem), 100%);
+    }
+
+    /* Narrow mode: low-priority columns stack under the first column's content as secondary text. */
+    .starci-core-data-table-secondary {
+        display: flex;
+        flex-direction: column;
+        gap: 0.125rem;
+        margin-block-start: 0.25rem;
+        color: var(--muted, GrayText);
+        font-size: 0.875em;
+        white-space: normal;
+    }
+
+    /* A long value (an email, an id) may break anywhere, so the folded text never sets the first column's minimum. */
+    .starci-core-data-table-secondary-item {
+        display: flex;
+        min-width: 0;
+        flex-wrap: wrap;
+        gap: 0.25rem;
+        overflow-wrap: anywhere;
+    }
+
+    .starci-core-data-table-secondary-value {
+        min-width: 0;
+    }
+
+    .starci-core-data-table-secondary-label::after {
+        content: ":";
+    }
+
     .starci-core-drag-item {
         display: flex;
         min-width: 0;
@@ -1021,6 +1109,9 @@
         line-height: 1.25rem;
     }
 
+    /* A loading stat keeps its unit's place, unseen (skeleton parity). */
+    .starci-core-description-list[data-loading="true"] .starci-core-description-unit { visibility: hidden; }
+
     .starci-core-description-meta {
         min-width: 0;
         margin: 0;
@@ -1112,12 +1203,12 @@
         display: flex;
         min-width: 0;
         flex-direction: column;
+        gap: 0.25rem;
     }
 
     /* Loading options (knowledge STATE-8): a label line and a description line, at the loaded option's height. */
     .starci-core-list-box-skeleton-option {
         display: flex;
-        min-block-size: 2.25rem;
         align-items: center;
         padding-inline: 0.5rem;
         padding-block: 0.375rem;
@@ -1128,8 +1219,10 @@
     .starci-core-list-box-skeleton-option .starci-core-list-box-description { display: block; }
     .starci-core-list-box-skeleton-option .starci-core-list-box-label > .starci-core-skeleton-group { inline-size: 55%; }
     .starci-core-list-box-skeleton-option .starci-core-list-box-description > .starci-core-skeleton-group { inline-size: 80%; }
-    .starci-core-list-box-skeleton-option .starci-core-skeleton { block-size: 0.75rem; }
-    .starci-core-list-box-skeleton-option .starci-core-skeleton-group { gap: 0; margin-block: 0.125rem; }
+    /* Skeleton parity: each line takes the line box of the vendor label (0.875rem / 1.25rem) and description (0.75rem / 1rem). */
+    .starci-core-list-box-skeleton-option .starci-core-list-box-label { font-size: 0.875rem; line-height: 1.25rem; }
+    .starci-core-list-box-skeleton-option .starci-core-list-box-description { font-size: 0.75rem; line-height: 1rem; }
+    .starci-core-list-box-skeleton-option .starci-core-skeleton-group { gap: 0; }
 
     .starci-core-list-box-empty {
         padding: var(--grammar-section-gap, 1rem);
@@ -1379,6 +1472,34 @@
         background: currentColor;
     }
 
+    /*
+     * Attention entry: the whole row takes a tone background (the marker alone is too small to catch the eye). The
+     * row grows 0.5rem each side and gives the same back as negative margin, so the markers and the copy keep their
+     * column; the connector moves with the padding and reaches the next entry.
+     */
+    .starci-core-timeline-item[data-grammar-attention="true"] {
+        --starci-core-timeline-attention-tone: var(--warning, CanvasText);
+        margin-inline: -0.5rem;
+        margin-block-end: 0.5rem;
+        padding: 0.5rem;
+        border-radius: 0.75rem;
+        background: color-mix(in oklab, var(--starci-core-timeline-attention-tone) 14%, transparent);
+    }
+
+    .starci-core-timeline-item[data-grammar-attention="true"][data-grammar-timeline-state="negative"] { --starci-core-timeline-attention-tone: var(--danger, CanvasText); }
+    .starci-core-timeline-item[data-grammar-attention="true"][data-grammar-timeline-state="affirmative"] { --starci-core-timeline-attention-tone: var(--success, CanvasText); }
+    .starci-core-timeline-item[data-grammar-attention="true"][data-grammar-timeline-state="informative"] { --starci-core-timeline-attention-tone: var(--info, CanvasText); }
+
+    .starci-core-timeline-item[data-grammar-attention="true"]:not(:last-child)::before {
+        top: 2rem;
+        bottom: -0.5rem;
+        inset-inline-start: calc(1.25rem - 1px);
+    }
+
+    .starci-core-timeline-item[data-grammar-attention="true"] .starci-core-timeline-marker {
+        background: transparent;
+    }
+
     /* Loading timeline (knowledge STATE-8): static mark and connector tint, three Skeleton lines of the entry's rhythm. */
     .starci-core-timeline-skeleton-marker > .starci-core-skeleton { inline-size: 1rem; block-size: 1rem; }
     .starci-core-timeline[data-loading="true"] .starci-core-timeline-item:not(:last-child)::before { background: color-mix(in srgb, var(--foreground, CanvasText) 9%, transparent); }
@@ -1386,7 +1507,7 @@
     .starci-core-timeline-item[data-grammar-skeleton="true"] .starci-core-timeline-time > .starci-core-skeleton-group { inline-size: 25%; }
     .starci-core-timeline-item[data-grammar-skeleton="true"] .starci-core-timeline-description > .starci-core-skeleton-group { inline-size: 80%; }
     .starci-core-timeline-item[data-grammar-skeleton="true"] .starci-core-skeleton-group { gap: 0; }
-    .starci-core-timeline-item[data-grammar-skeleton="true"] .starci-core-skeleton { block-size: 0.8125rem; }
+    .starci-core-timeline-item[data-grammar-skeleton="true"] .starci-core-skeleton { --starci-core-skeleton-line: 0.8125rem; }
 
     .starci-core-timeline-copy {
         display: flex;
@@ -1395,10 +1516,13 @@
         gap: 0.125rem;
     }
 
+    /* The list title scale (the ListBox and panel row label, text-sm), not whatever size the page body inherits. */
     .starci-core-timeline-title {
         margin: 0;
         overflow-wrap: anywhere;
+        font-size: 0.875rem;
         font-weight: 600;
+        line-height: 1.25rem;
     }
 
     .starci-core-timeline-time,
@@ -1479,6 +1603,9 @@
 
     .starci-core-flow-graph[data-grammar-flow-height="sm"] .starci-core-flow-graph-canvas { block-size: 16rem; }
     .starci-core-flow-graph[data-grammar-flow-height="lg"] .starci-core-flow-graph-canvas { block-size: 32rem; }
+    .starci-core-flow-graph[data-grammar-flow-height="custom"] .starci-core-flow-graph-canvas { block-size: var(--starci-flow-height, 24rem); }
+    /* The readable fit grew the canvas to the graph's aspect at its width rather than shrink the text below 12px. */
+    .starci-core-flow-graph[data-grammar-flow-grown="true"] .starci-core-flow-graph-canvas { block-size: var(--starci-flow-grown-height); }
 
     .starci-core-flow-graph-loading > .starci-core-skeleton { block-size: 100%; aspect-ratio: auto; }
 
@@ -1568,6 +1695,36 @@
         line-height: 1.25;
     }
 
+    .starci-core-flow-graph-link {
+        display: inline-flex;
+        align-items: center;
+        gap: 0.5rem;
+        min-inline-size: 0;
+        border-radius: inherit;
+        color: inherit;
+        text-decoration: none;
+        outline: none;
+        cursor: pointer;
+    }
+
+    .starci-core-flow-graph-node:has(.starci-core-flow-graph-link:focus-visible) {
+        outline: 2px solid var(--focus, var(--starci-core-focus, Highlight));
+        outline-offset: 2px;
+    }
+
+    .starci-core-flow-graph-header {
+        padding: 0.125rem 0.625rem;
+        color: var(--muted, GrayText);
+        font-size: 0.6875rem;
+        font-weight: 600;
+        letter-spacing: 0.04em;
+        text-transform: uppercase;
+        white-space: nowrap;
+        pointer-events: none;
+    }
+
+    .starci-core-flow-graph-header[data-direction="TB"] { text-align: end; }
+
     .starci-core-flow-graph-node[data-size="sm"] { padding: 0.25rem 0.625rem; font-size: 0.75rem; }
     .starci-core-flow-graph-node[data-size="lg"] { padding: 0.625rem 1.25rem; font-size: 1rem; font-weight: 600; }
     .starci-core-flow-graph-node[data-tone="accent"] { --starci-flow-tint: var(--accent-soft, transparent); --starci-flow-ink: var(--accent-soft-foreground, CanvasText); }

package/dist/common/components-overlays.css

@@ -547,6 +547,14 @@
         flex: none;
     }
 
+    /* A loading Alert (skeleton parity): the glyph keeps its place as a round Skeleton tint. */
+    .starci-core-alert[data-loading="true"] .starci-core-alert-indicator {
+        border-radius: 999px;
+        background: color-mix(in oklab, var(--surface-tertiary, #e4e4e7) 70%, transparent);
+    }
+
+    .starci-core-alert[data-loading="true"] .starci-core-alert-indicator > * { visibility: hidden; }
+
     .starci-core-alert-title {
         margin: 0;
     }
@@ -663,11 +671,16 @@
     }
 
     /* ---------------------------------------------------------------- skeleton */
+    /*
+     * Skeleton parity: a text skeleton takes the line box of the copy it stands for. Each line occupies exactly `1lh` of
+     * the inherited type (the bar, `--starci-core-skeleton-line` tall, is centred in it by its margins), so `lines={n}`
+     * is as tall as n lines of that copy. A context sizes the bar through the variable, never the block size.
+     */
     .starci-core-skeleton-group {
         display: flex;
         width: 100%;
         flex-direction: column;
-        gap: 0.5rem;
+        gap: 0;
     }
 
     .starci-core-skeleton {
@@ -678,9 +691,32 @@
 
     .starci-core-skeleton-group > .starci-core-skeleton {
         width: 100%;
-        height: 0.875em;
+        height: var(--starci-core-skeleton-line, 0.875em);
+        margin-block: calc((1lh - var(--starci-core-skeleton-line, 0.875em)) / 2);
     }
 
+    /*
+     * The measured placeholder (internal `SkeletonPlaceholder`): the ready content is laid out unseen and the shimmer
+     * paints its box. A text run is an inline block one line box per line (`vertical-align: top` keeps it from growing
+     * the line box); a block or circle sizes to its control or mark.
+     */
+    .starci-core-skeleton-placeholder {
+        display: inline-block;
+        max-inline-size: 100%;
+        vertical-align: top;
+        color: transparent;
+        user-select: none;
+    }
+
+    .starci-core-skeleton-placeholder > * { visibility: hidden; }
+    .starci-core-skeleton-placeholder[data-shape="block"] { display: inline-flex; }
+    .starci-core-skeleton-placeholder[data-shape="circle"] { display: inline-flex; border-radius: 999px; }
+    .starci-core-skeleton-placeholder[data-shape="region"] { display: block; }
+    .starci-core-skeleton-placeholder[data-shape="text"]:empty { inline-size: min(100%, 8rem); block-size: 1lh; }
+
+    /* A skeleton root that keeps its content as a measured placeholder (Button, Badge, StatusDot) paints none of it. */
+    :is(.starci-core-button, [data-component="Badge"], [data-component="StatusDot"])[data-loading="true"] > * { visibility: hidden; }
+
     .starci-core-skeleton[data-grammar-skeleton-line="last"] {
         width: 60%;
     }
@@ -793,6 +829,9 @@
     /* Loading meter (knowledge STATE-8, `isSkeleton`): the label stays real, the bar is a static Skeleton bar of the track height. */
     .starci-core-meter-skeleton-bar { display: block; block-size: 0.5rem; overflow: hidden; border-radius: 999px; }
 
+    /* `size="sm"`: the thin track is HeroUI's own `.meter--sm` (h-1); only the loading bar, which is ours, follows it. */
+    .starci-core-meter-skeleton[data-size="sm"] .starci-core-meter-skeleton-bar { block-size: 0.25rem; }
+
     .starci-core-meter-skeleton-bar > .starci-core-skeleton {
         block-size: 100%;
         aspect-ratio: auto;