@aceshooting/lyra-ui 5.0.0 → 5.1.0

package/llms/components/lr-agent-workspace.md

@@ -0,0 +1,109 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/conversation.md — do not edit this file. -->
+
+# `lr-agent-workspace`
+
+- **Import** `import '@aceshooting/lyra-ui/components/conversation/agent-workspace/agent-workspace.js';` (registers the tag; side-effect import)
+- **Class** `LyraAgentWorkspace`, also available unregistered from `@aceshooting/lyra-ui/components/conversation/agent-workspace/agent-workspace.class.js`
+- **Family** `components/conversation/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-agent-workspace`
+
+Responsive, fully controlled shell for an AI conversation and its supporting run, tool, retrieval,
+grounding, and context state: transcript + composer in the main pane, and a details pane composing
+`lr-agent-run`, `lr-tool-timeline`, `lr-retrieval-results`, `lr-grounding-summary`, and
+`lr-context-inspector`. Performs no network requests, model calls, retrieval, or persistence —
+assign new data to the properties as the host receives updates.
+
+This is the single component that binds the most of the provider-neutral vocabulary exported from
+`@aceshooting/lyra-ui/ai` (`src/ai/types.ts`) at once; a host that already holds `ChatMessage[]`,
+`AgentRun`, `RetrievalChunk[]`, `Citation[]`, and `GroundingAssessment` can wire this up with no
+adapters.
+
+**Properties (transcript):**
+- `messages: ChatMessage[] = []` (attribute: false) — **`ChatMessage` from
+  `@aceshooting/lyra-ui/ai`**: `{ id: string; role: ChatMessageRole; status?: ChatMessageStatus;
+  timestamp?: Date | string; text?: string; attachments?: DocumentRef[] }`. Each entry renders as an
+  `lr-chat-message` whose `role`/`status`/`timestamp` come straight across, with `text` rendered as
+  sanitized Markdown through `lr-markdown`. Replace the whole region with the `messages` slot for
+  richer bodies. Host owns ordering, updates, and persistence
+- `follow: boolean = true` (reflected) — forwarded to the internal `lr-chat-viewport`
+- `unreadStartIndex: number | null = null` (attribute `unread-start-index`) — forwarded to the viewport
+
+**Properties (details pane):**
+- `run: AgentRun | null = null` (attribute: false) — **`AgentRun` from `@aceshooting/lyra-ui/ai`**:
+  `{ id: string; status: AgentStatus; startedAt?: number; endedAt?: number; model?: string;
+  costEstimate?: number; steps: AgentStep[] }` (epoch-ms timestamps). `null` omits the run section
+- `metrics: AgentRunMetric[] = []` (attribute: false) — `lr-agent-run`'s own
+  `AgentRunMetric { id: string; label: string; value: string | number; variant?: BadgeVariant }`,
+  e.g. token counts or latency
+- `tools: ToolTimelineEntry[] = []` (attribute: false) — `lr-tool-timeline`'s
+  `ToolTimelineEntry extends ToolInvocation` (i.e. `{ id, name, args, status, result?, error? }` from
+  `@aceshooting/lyra-ui/ai`) plus `{ startedAt?: number; endedAt?: number; retryCount?: number;
+  redactedFields?: string[]; needsApproval?: boolean; approved?: boolean }`
+- `retrievalChunks: RetrievalChunk[] = []` (attribute: false) — **`RetrievalChunk` from
+  `@aceshooting/lyra-ui/ai`**: `{ id, text, score, source: DocumentRef, metadata? }`, forwarded to
+  `lr-retrieval-results`
+- `selectedRetrievalIds: string[] = []` (attribute: false) — controlled selection forwarded to
+  `lr-retrieval-results.selectedIds`
+- `retrievalLoading: boolean = false` (attribute `retrieval-loading`), `retrievalHasMore: boolean =
+  false` (attribute `retrieval-has-more`), `retrievalError: string = ''` (attribute
+  `retrieval-error`, caller-supplied text) — all forwarded to `lr-retrieval-results`
+- `groundingAssessment: GroundingAssessment | null = null` (attribute: false) — **`GroundingAssessment`
+  from `@aceshooting/lyra-ui/ai`**: `{ supportedClaims, unsupportedClaims, coverage, confidence?,
+  warnings? }`
+- `citations: Citation[] = []` (attribute: false) — **`Citation` from `@aceshooting/lyra-ui/ai`**,
+  shown alongside the grounding summary
+- `contextSegments: ContextInspectorSegment[] = []` (attribute: false) — `lr-context-inspector`'s
+  `{ id: string; label: string; text: string; tokens: number; tone?: ContextMeterTone; citation?:
+  Citation; truncated?: boolean; omittedTokens?: number; redactions?: ContextInspectorRedaction[] }`
+- `contextTotal: number = 0` (attribute `context-total`) — the overall context-window token budget
+- `showDetails: boolean = true` (attribute `show-details`, reflected) — whether the details pane is
+  available at all when data is present
+
+**Properties (composer / chrome):**
+- `showComposer: boolean = true` (attribute `show-composer`, reflected) — whether the built-in
+  composer renders when no `composer` slot is supplied
+- `composerValue: string = ''` (attribute `composer-value`) — controlled composer value
+- `composerStatus: ChatComposerStatus = 'idle'` (attribute `composer-status`) — `'idle' | 'sending' |
+  'streaming'`, `lr-chat-composer`'s own union
+- `composerPlaceholder: string = ''` (attribute `composer-placeholder`)
+- `composerMinRows: number = 1` (attribute `composer-min-rows`), `composerMaxRows: number = 8`
+  (attribute `composer-max-rows`)
+- `label: string = ''` — accessible name and visible heading
+- `accessibleLabel: string | null = null` (attribute `aria-label`) — host-level accessible-name
+  override for the internal `role="region"` root
+
+**Events:**
+- `lr-input` (`detail: { value: string }`) / `lr-submit` (`detail: { value: string }`) / `lr-stop`
+  (`detail: undefined`) — forwarded from the built-in composer.
+- `lr-message-retry` (`detail: { messageId: string }`) — a data-driven message's retry action.
+- `lr-follow-change` (`detail: { following: boolean }`) — forwarded from the transcript viewport.
+- `lr-retrieval-select` (`detail: RetrievalResultsSelectDetail` = `{ ids: string[]; chunks:
+  RetrievalChunk[] }`) — forwarded from the built-in retrieval results.
+- `lr-citation-select` (`detail: CitationSelectEventDetail` = `{ citation: Citation }`, from
+  `@aceshooting/lyra-ui/ai`) — forwarded from the built-in grounding summary.
+- `lr-tool-approval-decide` (`detail: ToolTimelineApprovalDetail` = `ToolApprovalEventDetail &
+  { args?: unknown }` = `{ invocationId: string; approved: boolean; args?: unknown }`) — forwarded
+  from the built-in tool timeline; `args` is present only on approval and may differ from what the
+  entry originally proposed (the dialog's inline edit step).
+- `lr-cancel` (`detail: undefined`) / `lr-retry` (`detail: RetryEventDetail` = `{ attempt: number;
+  messageId?: string }`, from `@aceshooting/lyra-ui/ai`) — forwarded from the built-in agent run.
+
+**Slots:** `messages` (replaces the data-driven transcript message list), `details` (replaces the
+built-in run/tool/retrieval/grounding/context details pane while keeping the responsive shell),
+`composer` (replaces the built-in `lr-chat-composer`), `header-actions` (model selection, settings,
+export controls).
+
+**CSS parts:** `base`, `header`, `heading`, `header-actions`, `body`, `conversation`, `viewport` (the
+composed `lr-chat-viewport`), `messages`, `messages-empty`, `details`, `details-content`, `section`
+(one run/tools/retrieval/grounding/context section), `section-heading`, `composer`, `composer-input`
+(the composed `lr-chat-composer`).
+
+**Themeable custom properties:** shared tokens only.
+
+**Optional peer deps:** none of its own; the composed `lr-markdown` keeps its `marked`/`dompurify`
+optional-peer fallback.

package/llms/components/lr-animated-image.md

@@ -0,0 +1,66 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/media.md — do not edit this file. -->
+
+# `lr-animated-image`
+
+- **Import** `import '@aceshooting/lyra-ui/components/media/animated-image/animated-image.js';` (registers the tag; side-effect import)
+- **Class** `LyraAnimatedImage`, also available unregistered from `@aceshooting/lyra-ui/components/media/animated-image/animated-image.class.js`
+- **Family** `components/media/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-animated-image`
+
+An animated GIF/APNG/WebP with a play/pause control, frozen to a captured still frame at rest and
+automatically under `prefers-reduced-motion: reduce`.
+
+**Properties:**
+- `src: string = ''` — re-validated through `safeMediaSrc()` (same allowlist as `lr-media-card`)
+  before reaching the real `<img src>`.
+- `alt: string = ''` — falls back to the localized `animatedImageDefaultAlt` when empty; an explicit
+  `alt=""` does **not** mark the image decorative.
+- `play: boolean = false` — the caller's *intent*. Not reflected.
+- `playing: boolean` (readonly getter, reflected as a `playing` host attribute) — the *effective*
+  state after reduced-motion arbitration: `play && !(respectReducedMotion && <OS prefers reduce>)`.
+  Assigning to it is a silent no-op; drive playback via `play`.
+- `respectReducedMotion: boolean = true` (reflected, attribute `respect-reduced-motion`) — while
+  `true` and the OS reports `prefers-reduced-motion: reduce`, playback stays frozen and
+  `[part="play-button"]` is `disabled` regardless of `play`.
+- `accessibleLabel: string = ''` (attribute `aria-label`) — overrides `[part="play-button"]`'s
+  computed Play/Pause label verbatim in *both* states (it does not itself vary by state). Never
+  touches the image's `alt`/the canvas's `aria-label`. For state-sensitive custom wording, override
+  the `playWithContext`/`pauseWithContext`/`animatedImageDefaultAlt` strings instead.
+
+**Methods:** `focus(options?)` and `blur()` forward to the play/pause button.
+
+**Events:** `lr-load` (the live `<img>` loaded; fires again on every successful `src` change),
+`lr-error` (native decode failure, or a non-empty `src` that failed the safe-URL check — never for
+an empty `src`), `lr-play`/`lr-pause` (real transitions of the effective `playing` value only, so a
+`play = true` that reduced motion blocks emits nothing, while a live reduced-motion change that
+forces a freeze does emit `lr-pause`); internal `focus`/`blur` are re-dispatched as bubbling,
+composed host events.
+
+**Slots:** `play-icon`, `pause-icon` — custom glyphs on `[part="play-button"]` for the
+frozen/paused and playing states. Both are always rendered and toggled via the native `hidden`
+attribute, so slotted content for both stays mounted.
+
+**CSS parts:** `base` (positioning context), `image` (the live `<img>`), `canvas` (the
+frozen-frame `<canvas>`, shown in place of `image` while not playing), `control-box` (the
+backgrounded circle around the button; only rendered once loaded and error-free), `play-button`.
+
+**Themeable custom properties:** `--lr-animated-image-control-box-size` (default
+`var(--lr-icon-button-size)`), `--lr-animated-image-icon-size` (default
+`calc(var(--lr-icon-button-size) * 0.35)`), `--lr-animated-image-max-height` (default
+`var(--lr-size-20rem)` — caps the rendered media's block-size, same contract as
+`--lr-media-card-max-height`).
+
+**Optional peer deps:** none.
+
+**Known gotchas:**
+- the freeze frame is captured once per successful `src` load, in the `<img>`'s own `load` handler
+  (a DPR-aware `drawImage()`), not re-captured on each pause — pausing always reverts to that first
+  frame, never to the frame that was on screen.
+- both `image` and `canvas` stay mounted at all times (never `display: none`/removed) so the
+  browser's native decode loop keeps running while visually covered; only opacity and `aria-hidden`
+  swap.

package/llms/components/lr-animation.md

@@ -0,0 +1,73 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/media.md — do not edit this file. -->
+
+# `lr-animation`
+
+- **Import** `import '@aceshooting/lyra-ui/components/media/animation/animation.js';` (registers the tag; side-effect import)
+- **Class** `LyraAnimation`, also available unregistered from `@aceshooting/lyra-ui/components/media/animation/animation.class.js`
+- **Family** `components/media/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-animation`
+
+Declaratively animates one slotted element through the native Web Animations API.
+
+**Properties:**
+- `name: LyraAnimationPreset = 'none'` — `'none' | 'fade-in' | 'fade-out' | 'zoom-in' | 'zoom-out' |
+  'slide-in-start' | 'slide-in-end' | 'slide-out-start' | 'slide-out-end' | 'slide-in-up' |
+  'slide-in-down' | 'bounce' | 'pulse' | 'spin' | 'shake'`. The four `-start`/`-end` slide presets
+  are logical: "start" is physically left under `ltr`, right under `rtl`.
+- `keyframes?: Keyframe[]` (attribute: false) — raw WAAPI keyframes; always wins over `name`.
+- `play: boolean = false` (reflected) — playback intent.
+- `delay: number = 0`, `duration: number = 1000`, `endDelay: number = 0` (attribute `end-delay`),
+  `easing: string = 'linear'`, `fill: FillMode = 'auto'`, `direction: PlaybackDirection = 'normal'`,
+  `iterations: number = Infinity`, `iterationStart: number = 0` (attribute `iteration-start`),
+  `playbackRate: number = 1` (attribute `playback-rate`) — straight WAAPI timing. `direction` is
+  the WAAPI `PlaybackDirection`, unrelated to text direction.
+- `timingPreset: LyraAnimationTimingPreset = 'custom'` (attribute `timing-preset`, reflected) —
+  `'custom' | 'fast' | 'base' | 'ambient'`. Anything other than `'custom'` derives `duration` and
+  `easing` from the matching `--lr-transition-*` token (read off computed style and decomposed into
+  the numeric ms + easing string WAAPI needs), ignoring the `duration`/`easing` properties.
+- `respectReducedMotion: boolean = true` (attribute `respect-reduced-motion`, reflected) — under
+  `prefers-reduced-motion: reduce`, caps playback at one iteration and calls `finish()` immediately
+  instead of playing, so the target snaps to its resolved end state; `lr-start`/`lr-finish` still
+  fire in order.
+- `playOnVisible: boolean = false` (attribute `play-on-visible`, reflected) — starts playback via
+  `IntersectionObserver` once the target intersects. `playOnVisibleRepeat: boolean = false`
+  (attribute `play-on-visible-repeat`, reflected) — re-plays on each re-entry and pauses on exit;
+  when unset the observer disconnects after the first trigger. `root: Element | null = null` and
+  `threshold: number | number[] = 0` (both attribute: false) plus `rootMargin: string = '0px'`
+  (attribute `root-margin`) configure that observer.
+- `currentTime: number` — the underlying `Animation.currentTime` (`0` when no animation exists);
+  writable, forwarded to the animation when one exists.
+
+**Methods:** `start()` (sugar for `play = true` — named `start` because `play` is already a
+property), `pause()` (`play = false`), `finish()`, `cancel()`.
+
+**Events:** `lr-start` (a new animation was created and playback began/restarted), `lr-finish`
+(natural end, including the reduced-motion instant-finish path), `lr-cancel` (the public `cancel()`
+method or external cancellation). `lr-finish`/`lr-cancel` both reset `play` to `false`.
+
+**Slots:** default slot — the element to animate. A second slotted element is accepted without
+error but ignored.
+
+**CSS parts:** none (`:host { display: contents }`; the animated element is light-DOM content).
+
+**Themeable custom properties:** `--lr-animation-slide-distance` (default `100%` — travel distance
+for the slide presets), `--lr-animation-zoom-scale` (default `0.5` — start/end scale for
+`zoom-in`/`zoom-out`), `--lr-animation-bounce-height` (default `25%` — peak lift of `bounce`),
+`--lr-animation-shake-distance` (default `4%` — horizontal travel of `shake`).
+
+**Optional peer deps:** none.
+
+**Known gotchas:**
+- `iterations` defaults to `Infinity` (mirrors the upstream Web Awesome/Shoelace contract) — a named
+  preset plays forever unless you set `iterations="1"`.
+- changing any timing/keyframe property rebuilds the animation from scratch; the rebuild's internal
+  `cancel()` is deliberately silent (no `lr-cancel`), only the public `cancel()` emits.
+- the slide presets read the inherited text direction only when the animation is (re)built — an
+  animation already mid-flight is not re-mirrored if an ancestor `dir` flips.
+- reduced-motion handling is entirely in JS; the shared shadow-DOM reduced-motion CSS block can't
+  reach light-DOM slotted content driven by `Element.animate()`.

package/llms/components/lr-app-rail-item.md

@@ -0,0 +1,218 @@
+<!-- GENERATED by scripts/build-llms.mjs from llms/layout.md — do not edit this file. -->
+
+# `lr-app-rail-item`
+
+- **Import** `import '@aceshooting/lyra-ui/components/layout/app-rail/app-rail-item.js';` (registers the tag; side-effect import)
+- **Class** `LyraAppRailItem`, also available unregistered from `@aceshooting/lyra-ui/components/layout/app-rail/app-rail-item.class.js`
+- **Family** `components/layout/` — see `llms/index.md` for its siblings
+- **Optional peers** none
+- **Documented with** `lr-app-rail` (same section below)
+- **Library-wide behavior** (events, form association, `locale`/`strings`, tokens, TS types): `llms/shared.md`
+
+---
+
+## `lr-app-rail`
+
+A responsive navigation rail that adapts across three presentations as the *viewport* narrows (not
+this element's own inline size): `'full'` (nav items show icon + label, inline), `'icon-only'` (a
+narrower inline rail, icons only), and `'mobile'` (hidden behind a toggle button; opening it shows a
+focus-trapped floating overlay over the page). First-party invention (no Web Awesome equivalent).
+Breakpoints are viewport-width `matchMedia()` queries against `icon-only-breakpoint`/
+`mobile-breakpoint`, not a `ResizeObserver` on this element — presentation tracks the actual device/
+window width the way a native OS shell's navigation does, not however much horizontal space a
+particular layout happens to give it. `[part="base"]` (the inline `'full'`/`'icon-only'`
+presentation) and `[part="panel"]` (the mobile overlay) are the *same* element promoted in place
+across modes (mirrors `<lr-widget>`'s fullscreen mode) — never both at once, and slotted nav
+content is never duplicated.
+
+Opting in to `resizable` adds a continuously draggable width for the `'full'` state: a
+`[part="resizer"]` handle (pointer-drag and Left/Right-arrow keyboard stepping, RTL-aware) clamped to
+`[minRailWidthPx, maxRailWidthPx]`, with no built-in persistence — a consumer that wants the chosen
+width to survive a reload listens for `lr-rail-resize` and persists `railWidthPx` itself.
+`preferredMode` separately lets a host manually prefer `'full'`/`'icon-only'` for the non-mobile
+breakpoint axis (e.g. a user's own collapse toggle) while `mobile-breakpoint` continues to be tracked
+automatically regardless — it's only consulted while `mode` isn't force-pinned via the `mode`
+accessor itself, which still takes full priority.
+
+**Properties:**
+- `mode: AppRailMode` (custom accessor, reflected) — the getter always returns one of the three real
+  modes (`'full'|'icon-only'|'mobile'`), never `'auto'`. The setter accepts
+  `AppRailModeInput` (`AppRailMode | 'auto'`): assigning `'full'`/`'icon-only'`/`'mobile'` forces
+  that mode and stops the element responding to breakpoint changes; assigning the write-only
+  sentinel `'auto'` releases the force and immediately re-syncs to the current viewport width,
+  resuming automatic tracking. Settable via the `mode` attribute too (`mode="icon-only"`,
+  `mode="auto"`).
+- `iconOnlyBreakpoint: string = '960px'` (attribute `icon-only-breakpoint`) — any valid CSS length,
+  used directly in a `(max-width: ...)` media query; below it the rail switches from `'full'` to
+  `'icon-only'`.
+- `mobileBreakpoint: string = '600px'` (attribute `mobile-breakpoint`) — same mechanism; below it the
+  rail switches from `'icon-only'` to `'mobile'`. Should be smaller than `iconOnlyBreakpoint` to
+  produce all three states as the viewport narrows.
+- `open: boolean = false` (reflected) — whether the mobile floating overlay is shown. Only meaningful
+  while `mode` is `'mobile'` — the value is preserved (not reset) while another mode is active, but
+  no overlay chrome renders until `mode` is `'mobile'` again. Set this directly, or use the built-in
+  toggle button — there is no separate `show()`/`hide()` pair.
+- `label: string = 'Navigation'` — accessible name for the rail's navigation landmark, and for its
+  dialog role while the mobile overlay is open. A host-level `aria-label` attribute (see below)
+  takes precedence over this when both are set.
+- `preferredMode?: 'full' | 'icon-only' | null` (attribute `preferred-mode`) — manually prefers
+  `'full'` or `'icon-only'` for the non-mobile breakpoint axis, while `mobile-breakpoint` continues to
+  be tracked automatically regardless — e.g. a user's manual collapse toggle that should still yield
+  to a genuinely too-narrow-for-any-inline-rail viewport. Only consulted while `mode` isn't
+  force-pinned via its own accessor (see above) — that continues to take full priority, unchanged.
+  Unset (the default, `null`) reproduces the original breakpoint-only behavior exactly.
+- `hideToggle: boolean = false` (reflected, attribute `hide-toggle`) — suppresses the built-in mobile
+  `[part='toggle']` hamburger/close button entirely, for a consumer that already owns an external
+  mobile-menu toggle wired to this rail's own `open` property. `false` (the default) reproduces the
+  exact existing output; note `open` still has no built-in external trigger of its own once this is
+  set, since `lr-toggle` only fires from the toggle button being activated.
+- `resizable: boolean = false` (reflected) — opts a continuously draggable width in for the `'full'`
+  state, exposing a `[part='resizer']` handle clamped to `[minRailWidthPx, maxRailWidthPx]`. `false`
+  (the default) renders no resizer and leaves the fixed-width `--lr-app-rail-width` CSS token
+  exactly as before this property existed.
+- `railWidthPx?: number` (attribute `rail-width-px`) — the rail's current width in px while
+  `resizable`; settable/gettable directly. Unset defers to `--lr-app-rail-width`'s own resolved
+  width.
+- `minRailWidthPx: number = 190` (attribute `min-rail-width-px`) — minimum `railWidthPx` a
+  drag/keyboard resize can reach.
+- `maxRailWidthPx: number = 440` (attribute `max-rail-width-px`) — maximum `railWidthPx` a
+  drag/keyboard resize can reach.
+- `dragging: boolean = false` (reflected) — `true` for the duration of an active pointer-driven
+  resize drag (not a keyboard step); reflected so a consumer (or this component's own styles) can
+  suppress `[part='base']`'s `transition: inline-size` during the drag, which otherwise visibly
+  "chases" the pointer instead of tracking it 1:1. Effectively read-only (this component owns the
+  transitions), but a plain reflected property like every other boolean here.
+
+Also settable as a plain `aria-label` attribute (not a reactive property): overrides the computed
+`label`/localized-default accessible name on both the navigation landmark and the mobile dialog
+role, matching `<lr-date-input>`'s `accessibleLabel`.
+
+**Events:** `lr-mode-change` (`detail: AppRailModeChangeDetail` = `{ mode: AppRailMode }`; the
+effective mode changed, whether from a breakpoint crossing or an explicit `mode` assignment — not
+fired for a redundant reassignment to the mode already in effect), `lr-toggle`
+(`detail: AppRailToggleDetail` = `{ open: boolean }`; the mobile overlay opened or closed — via the
+built-in toggle button, Escape, a backdrop click, a nav-item click while open, or a breakpoint/forced
+mode change leaving `'mobile'` while open — not fired when a consumer sets `open` directly),
+`lr-rail-resize` (`detail: AppRailResizeDetail` = `{ widthPx: number }`; the `resizable` rail's
+width changed via drag or keyboard stepping — not fired when a consumer sets `railWidthPx` directly).
+
+**Slots:** default (nav items — generic slotted content, e.g. `<a>`/`<button>` elements the consumer
+builds with its own icon+label structure; clicking anywhere in this slot closes the mobile overlay if
+open), `header` (logo/brand content, shown above the nav items in every mode), `footer` (a trailing
+user/settings trigger, shown below the nav items).
+
+**CSS parts:** `base`, `header`, `nav`, `footer`, `toggle` (hidden via CSS outside `'mobile'` mode, or
+entirely via `hideToggle`), `backdrop`, `panel` (`base`/`panel` are mutually exclusive on the same
+underlying element — see above), `resizer` (the `resizable` opt-in's drag handle, only rendered while
+`resizable` and `mode` is `'full'`; its hit target is `--lr-icon-button-size`-wide), `resizer-track`
+(the slim 3px visible drag line centered inside that hit target, tinted `--lr-color-brand` on hover).
+
+**Themeable custom properties:** `--lr-app-rail-width` (default `15rem` — the inline rail width in
+`'full'` mode), `--lr-app-rail-icon-width` (default `4rem` — the inline rail width in `'icon-only'`
+mode), `--lr-app-rail-mobile-width` (default `18rem`, capped at `85vw` — the mobile overlay panel
+width), `--lr-app-rail-overlay-color` (default `var(--lr-color-overlay)` — the mobile backdrop scrim
+color; component-specific since no shared token exists), plus shared tokens (`--lr-color-border`,
+`--lr-color-surface`, `--lr-color-text`, `--lr-color-brand`, `--lr-color-brand-quiet`,
+`--lr-space-*`, `--lr-radius`, `--lr-shadow`, `--lr-icon-button-size`,
+`--lr-focus-ring-*`, `--lr-transition-base`). `resizable`'s width is driven entirely by
+`railWidthPx`'s inline `inline-size` style rather than a new custom property.
+
+**Optional peer deps:** none.
+
+```html
+<lr-app-rail label="Main navigation" icon-only-breakpoint="960px" mobile-breakpoint="600px" resizable>
+  <span slot="header"><img src="/logo.svg" alt="Acme" /></span>
+  <a href="/inbox" aria-label="Inbox"><svg aria-hidden="true">...</svg><span>Inbox</span></a>
+  <a href="/settings" aria-label="Settings"><svg aria-hidden="true">...</svg><span>Settings</span></a>
+  <span slot="footer"><button>Profile</button></span>
+</lr-app-rail>
+<script type="module">
+  const rail = document.querySelector('lr-app-rail');
+  rail.addEventListener('lr-rail-resize', (e) => localStorage.setItem('railWidthPx', String(e.detail.widthPx)));
+</script>
+```
+```ts
+rail.mode = 'icon-only'; // force a presentation regardless of viewport width
+rail.mode = 'auto';      // release the force, resume live breakpoint tracking
+```
+
+The package root also exports a pure `computeAppRailMode(iconOnlyMatches: boolean, mobileMatches:
+boolean, preferredMode?: 'full' | 'icon-only' | null): AppRailMode` resolver (plus the
+`AppRailMode`/`AppRailModeInput`/`AppRailModeChangeDetail`/`AppRailToggleDetail`/`AppRailResizeDetail`
+types) — the same logic the element's internal `matchMedia` listeners call, exposed standalone so a
+consumer can compute or unit-test the same resolution without a real browser window. `mobileMatches`
+wins over everything else when true (the viewport is narrower than both breakpoints at once);
+otherwise `preferredMode` (when set) wins over `iconOnlyMatches`.
+
+The mobile state keeps its own panel template rather than nesting `<lr-dialog>`, while its modal
+behavior participates in the shared overlay stack. It is a plain `<div>` with an explicit
+`role="navigation"` (swapping to `role="dialog"` while the overlay is open) rather than a literal
+`<nav>` tag, since a
+`<nav>`'s implicit role can't be overridden to `role="dialog"` without an `aria-allowed-role`
+violation. In `'icon-only'` mode, slotted nav items lose their visible text label — give each one a
+real accessible name (`aria-label`, visually hidden text, or `title`) regardless, since this
+component only lays out whatever is slotted and can't inspect or fix up a consumer's own markup.
+
+**Known gotchas:**
+- `mode`'s setter accepts the wider `AppRailModeInput` (including the `'auto'` sentinel) but the
+  getter's return type is the narrower `AppRailMode` — assigning `'auto'` is a one-way instruction,
+  not a value read back later; there is no `isForced`-style property to check whether the rail is
+  currently locked to a mode or tracking the viewport.
+- reassigning `icon-only-breakpoint`/`mobile-breakpoint` after first render tears down and rebuilds
+  the `matchMedia` listeners, but does not itself un-force a previously-forced `mode` — if a consumer
+  set `mode = 'icon-only'`, changing the breakpoints won't resume auto-tracking until `mode = 'auto'`
+  is set explicitly.
+- leaving `'mobile'` mode while `open` (via a breakpoint crossing or a forced `mode` reassignment)
+  auto-closes the overlay through the same path as the toggle button, so `lr-toggle` still fires
+  and the scroll lock/focus trap still release normally — a consumer listening only for explicit
+  toggle-button clicks would miss this closure.
+- the mobile panel is also given `inert` whenever `mode === 'mobile'` and `open` is `false` — it's
+  removed from the accessibility tree and tab order via `inert` at the same time it's hidden visually
+  via `transform: translateX(-100%)`, both applied simultaneously rather than one implying the other.
+- the offscreen slide direction for the mobile panel is flipped for RTL via a `:dir(rtl)` CSS
+  selector (`translateX(100%)`), not through the shared `internal/rtl.ts` JS helper used for pointer/
+  keyboard math elsewhere in this library — a physical `transform` isn't expressible with logical
+  properties, so this one case is handled purely in CSS.
+- a reconnect that preserves the same element instance (e.g. a drag-and-drop reparent) resumes its
+  shared overlay registration and re-acquires the scroll lock if the overlay was still active
+  across the move — `disconnectedCallback`/`connectedCallback` fire back-to-back with no update in
+  between, so `willUpdate()` alone wouldn't otherwise notice.
+- `resizable`'s drag handle is pointer-only (`pointerdown`/`pointermove`/`pointerup`/
+  `pointercancel`/`lostpointercapture`) plus discrete Left/Right-arrow keyboard stepping (8px per
+  press, RTL-aware) — there's no dedicated touch gesture beyond what Pointer Events already unify.
+- reassigning `railWidthPx` while `resizable` is unset has no visible effect on the rendered width —
+  the fixed-width `--lr-app-rail-width` token still governs `'full'`-mode width until `resizable`
+  is also set.
+- reassigning `icon-only-breakpoint`/`mobile-breakpoint`/`preferredMode` does not itself un-force a
+  previously-forced `mode` — same caveat as above, `preferredMode` is only consulted while `mode`
+  isn't force-pinned.
+
+### `lr-app-rail-item`
+
+An explicit navigation item for `<lr-app-rail>`. It renders an accessible link when `href` is
+set and enabled, otherwise a button; the rail can add its `icon-only` presentation state without
+removing the label from the accessibility tree.
+
+**Properties:**
+- `href: string = ''` — optional destination. Without it, the item renders as a button.
+- `target: string = ''` — optional link target.
+- `disabled: boolean = false` (reflected) — prevents activation while retaining the item in the rail.
+- `active: boolean = false` (reflected) — marks this as the destination for the current page/view;
+  reflects `aria-current="page"` on `[part='base']` and drives the active visual treatment. The rail
+  has no built-in routing, so the consumer sets this per item (e.g. by comparing `href` against the
+  current location).
+- `tooltip: boolean = false` (reflected) — opt-in hover/focus flyout (`[part='tooltip']`) showing
+  this item's label text while the rail's `icon-only` mode (set externally by the parent
+  `<lr-app-rail>` as the viewport narrows) hides it from view. No effect outside icon-only mode,
+  since the label is already visible there. `false` (the default) reproduces the exact existing
+  output.
+
+**Slots:** default (the visible label), `icon` (the leading icon, hidden from assistive technology
+when the item has an explicit `aria-label`).
+
+**CSS parts:** `base`, `icon`, `label`, `tooltip` (the hover/focus label flyout, only rendered while
+`tooltip` is set, the item is `icon-only`, and it is hovered or focused).
+
+**Optional peer deps:** none.
+
+---