@mkbabb/glass-ui 3.11.2 → 3.13.0

package/dist/components/custom/dock/DockRail.vue.d.ts

@@ -0,0 +1,88 @@
+import { type Component } from "vue";
+import type { DockRailItem } from "./constants";
+/**
+ * <DockRail> — AZ.W-RAIL-EXTEND → AZ.W-RAIL3. The hairline-borne, floating
+ * CAROUSEL-LIKE chip STRIP: a row/column of detached glass chips that ride a
+ * VISIBLE hairline running BEYOND the dock edge, OUTSIDE the dock box. Each chip
+ * is one context/facet; clicking it switches the dock's layer context. The strip
+ * is rendered in `GlassDock`'s `#rail` slot OUTSIDE the clipped morph aperture (the
+ * `.glass-dock-frame` escape), so it NEVER changes the dock's width/height — the
+ * dock box is INVIOLATE (R6 §"design REDIRECT" item 1) — and it PERSISTS when the
+ * dock collapses (the in-pane switcher rail vanishes on collapse; this one does not).
+ *
+ * W-RAIL3 EVOLUTION (the third-rail redirect). The prior facility was a single
+ * end-icon (one `DockIconButton` cycling `entries` through an invisible list behind
+ * a chevron). The contextual facets used to mount as an in-dock `<DockLayerGroup>`,
+ * which stretched the dock box ~2× (the R6-1/R6-2 inflation). This wave MOVES the
+ * facets OUT of the dock onto THIS rail as the visible chips — "a floating carousel
+ * almost" (the user's words). The chips ARE the facets (id + label + icon); the
+ * active one is highlighted; when a context carries more chips than fit inline the
+ * strip scrolls/cycles (CSS `overflow` + `scroll-snap`).
+ *
+ * Axis-aware (the `<DockSeparator>` idiom, read via `useOptionalDockContext()`):
+ *   - column dock (vertical)  → the strip hangs BELOW the dock as a horizontal row
+ *     of chips on a horizontal hairline (the dock is a narrow column; a horizontal
+ *     chip row reads as the carousel below it).
+ *   - row dock (horizontal)   → the strip runs BELOW the dock's bottom edge as a
+ *     horizontal row of chips on the connective hairline.
+ * The hairline is composed from the `--border-hairline` token pair (the 0.5px
+ * catch-light + under-shadow the dock + instrument-chassis already speak) — a
+ * whisper, NEVER a hard `1px solid` rule (R3). The beyond-edge overrun is
+ * `--dock-rail-extend-length` (a dock-scoped geometry knob, consumer-overridable).
+ *
+ * The layer-context binding (R2 — one registry, NOT a parallel state path):
+ *   The chips write the consumer-owned `v-model:context` — the SAME ref the consumer
+ *   binds to its navigation state (or `<DockLayerGroup v-model:active>`). There is no
+ *   internal `ref()`/`reactive()` shadow of the active state inside this facility; the
+ *   context ref lives in the consumer, and `<DockRail>` only writes it. Pass `items`
+ *   (the facet descriptors → the visible chips); a chip click writes its id AND emits
+ *   `@advance` with it so a consumer can wire its own selection logic. (The prior
+ *   single-end-icon `entries?: string[]` prop died with the evolution — a clean
+ *   break, no alias; every consumer passes `items`.)
+ */
+type __VLS_Props = {
+    /**
+     * `"beyond"` (default) overruns the hairline past the dock content box by
+     * `--dock-rail-extend-length`; `"inset"` keeps it flush at the edge (the
+     * separator-like length).
+     */
+    extent?: "beyond" | "inset";
+    /** Which dock edge the rail anchors to (the leading/trailing end). */
+    position?: "start" | "end";
+    /**
+     * The chip descriptors — the visible facets the strip renders. When present,
+     * the strip is a CAROUSEL of these chips (the W-RAIL3 evolution). The active
+     * chip (matching `v-model:context`) is highlighted; a click writes its id.
+     */
+    items?: readonly DockRailItem[];
+    /**
+     * The fallback chevron glyph (the cycle end-cap shown when no `items`
+     * entry carries an icon). Default: a chevron.
+     */
+    icon?: Component;
+    /** Accessible label for the strip group. */
+    iconLabel?: string;
+};
+type __VLS_ModelProps = {
+    /**
+     * The dock's active layer context — a CONSUMER-OWNED model (the R2 sanctioned seam).
+     * The consumer binds the SAME ref here and to its navigation state; this facility
+     * owns NO shadow store of the active state. `defineModel` is the consumer's ref
+     * reached through the v-model contract, not an internal `ref()`.
+     */
+    "context"?: string;
+};
+type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
+declare const __VLS_export: import("vue").DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    advance: (next: string | undefined) => any;
+    "update:context": (value: string | undefined) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    onAdvance?: ((next: string | undefined) => any) | undefined;
+    "onUpdate:context"?: ((value: string | undefined) => any) | undefined;
+}>, {
+    position: "start" | "end";
+    extent: "beyond" | "inset";
+    iconLabel: string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/custom/dock/DockTabButton.vue.d.ts

@@ -12,10 +12,9 @@ import { type HTMLAttributes } from "vue";
  *
  * K.W6 Lane B — when the consumer attaches `data-tier="primary"`, the
  * button composes the canonical `btn-audacious` utility (the lifted
- * disco-grain + specular-highlight recipe at `utilities.css`; the
- * sparkle-sweep star was excised at D6 — the gold identity now rides the
- * `--gold-rim` gilt edge). `dock.css` retains the dock-local
- * phase-tinting + structural shell on top of the canonical recipe.
+ * disco-grain + sparkle-sweep + specular-highlight recipe at
+ * `utilities.css`). `dock.css` retains the dock-local phase-tinting +
+ * structural shell on top of the canonical recipe.
  */
 type __VLS_Props = {
     as?: string;

package/dist/components/custom/dock/GlassDock.vue.d.ts

@@ -1,112 +1,5 @@
-type DockDensity = "compact" | "comfortable" | "spacious" | "audacious";
-interface DockCommonProps {
-    fitContent?: boolean;
-    position?: "fixed" | "inline" | "sticky";
-    alwaysExpanded?: boolean;
-    /**
-     * Corner treatment.
-     *   `"pill"`    — the stadium silhouette (default).
-     *   `"rounded"` — a finite rounded radius (`--radius-xl`).
-     *   `"card"`    — the AW.W3b big-dock card shell: a finite concentric
-     *                 radius (`--dock-card-radius`, default `--radius-3xl`)
-     *                 ABOVE 2xl, below pill — does NOT collapse to a stadium.
-     *                 Collapsed it returns to a pill; the pill↔card swap
-     *                 morphs on the `--dock-motion-resize` spring. AX.W56's
-     *                 squircle policy applies `corner-shape:
-     *                 var(--corner-shape-bigdock)` here under `@supports
-     *                 (corner-shape: superellipse(2))` — the big-dock is the ONE
-     *                 surface where the superellipse reads (cards/pills stay
-     *                 round); the border-radius arc is the cross-engine contract.
-     *
-     * `"pill"`/`"rounded"` previously bound ONLY under the vertical rail
-     * variant — on a horizontal dock the prop silently no-op'd. AW.W3b adds
-     * the horizontal-root shape rules (closing that documented-but-dead prop),
-     * so `shape` now paints on a horizontal dock too.
-     */
-    shape?: "pill" | "rounded" | "card";
-    /**
-     * Layout axis of the dock. `"horizontal"` (default) lays items out
-     * left-to-right and animates `width`; `"vertical"` lays items out
-     * top-to-bottom and animates `height`. IGNORED under `variant="rail"` /
-     * `"instrument-strip"` (those force vertical by construction).
-     */
-    orientation?: "horizontal" | "vertical";
-    /**
-     * Density controls dock padding, gaps, layer height, and inherited
-     * dock control sizing. Root CSS variables can override each density.
-     */
-    density?: DockDensity;
-    /**
-     * Overflow strategy when the expanded content exceeds the dock's
-     * axis cap (`--dock-max-inline-size` horizontally,
-     * `--dock-max-block-size` vertically). The ONE knob governing every
-     * overflow behaviour (AT.W7-dock-a clean break — collapsed from the
-     * prior `wrap` boolean + `overflow` pair + `containerName` clip-lift,
-     * which all touched overflow divergently).
-     *   `"grow"`   — content grows to fit then overflows visibly past
-     *                the cap (the default; nothing clips or scrolls).
-     *   `"wrap"`   — expanded content wraps to multiple rows via CONTENT-DRIVEN
-     *                intrinsic flex-wrap (the `.dock-overflow-wrap` recipe). The
-     *                dock shrink-wraps to content and caps that intrinsic width
-     *                at `max-inline-size: var(--dock-max-inline-size)`, so the row
-     *                reflows to N rows EXACTLY when its intrinsic width exceeds
-     *                the cap — at ANY viewport width — and collapses to one row
-     *                when it fits (no viewport breakpoint). The wrapped multi-row silhouette lifts
-     *                onto the card/floating shadow tier as the dock expands.
-     *                HORIZONTAL-ONLY: a vertical rail grows-to-fit + clamps via
-     *                `--dock-max-block-size` (its own overflow story), so the
-     *                `.dock-overflow-wrap` class is not emitted for a vertical
-     *                orientation.
-     *   `"scroll"` — the dock becomes the scroll port. Horizontal docks
-     *                scroll the active layer on the inline axis
-     *                (`.dock-scroll-x`); vertical rails scroll on the
-     *                block axis (`.dock-scroll-y`), keeping the
-     *                `max-block-size` cap. The rounded pill masks the
-     *                scroll edge; the scrollbar is hidden. The axis is
-     *                chosen automatically from `orientation`.
-     */
-    overflow?: "grow" | "wrap" | "scroll";
-    /**
-     * When set, the dock root establishes an inline-size container query
-     * subject (`container-type: inline-size; container-name: <value>`) so
-     * descendants can query the named container via `@container <value>
-     * (...)` rules. ORTHOGONAL to the `overflow` clip: opting into a
-     * container subject does NOT silently change the dock's clip shell
-     * (AT.W7-dock-a — the prior clip-lift was folded out; use
-     * `overflow="wrap"` to allow multi-line content).
-     *
-     * T.B audit §1.3 cornerstone: the cluster's container subject must
-     * live on the dock primitive, never on a descendant whose intrinsic
-     * size the dock relies on.
-     */
-    containerName?: string;
-}
-interface DockVariantProps extends DockCommonProps {
-    variant?: "dock";
-    /** Idle-collapse delay in ms (default 2000). DOCK-ONLY — a rail never collapses. */
-    collapseDelay?: number;
-    /** Start in the collapsed state (default true). DOCK-ONLY — a rail is always expanded. */
-    startCollapsed?: boolean;
-    /**
-     * In-cap arrangement. `"linear"` (default) lays the active layer out as a
-     * linear row/column. `"grid"` makes the active layer a self-wrapping tile
-     * grid (Launchpad/Stage-Manager track symmetry — `auto-fill` columns of
-     * `--dock-tile-min`). ORTHOGONAL to `overflow` (the OVER-cap strategy):
-     * `layout` is the IN-cap arrangement.
-     *
-     * Hard contract: a `layout="grid"` dock is `alwaysExpanded` (a 2D panel
-     * does not read as a collapsible pill, and no width morph means no
-     * per-frame grid reflow). The canonical pairing is
-     * `shape="card" layout="grid"` (the props stay independent — no
-     * auto-implication of `shape`). DOCK-ONLY — the grid is a horizontal big-dock
-     * arrangement, never a rail's.
-     */
-    layout?: "linear" | "grid";
-}
-interface DockRailProps extends DockCommonProps {
-    variant: "rail" | "instrument-strip";
-}
-declare var __VLS_1: {}, __VLS_3: {}, __VLS_5: {}, __VLS_7: {}, __VLS_14: {}, __VLS_16: {}, __VLS_18: {};
+import { type DockProps } from "./composables/useDockShellProps";
+declare var __VLS_1: {}, __VLS_3: {}, __VLS_5: {}, __VLS_7: {};
 type __VLS_Slots = {} & {
     persistent?: (props: typeof __VLS_1) => any;
 } & {
@@ -114,15 +7,9 @@ type __VLS_Slots = {} & {
 } & {
     collapsed?: (props: typeof __VLS_5) => any;
 } & {
-    default?: (props: typeof __VLS_7) => any;
-} & {
-    collapsed?: (props: typeof __VLS_14) => any;
-} & {
-    default?: (props: typeof __VLS_16) => any;
-} & {
-    collapsed?: (props: typeof __VLS_18) => any;
+    rail?: (props: typeof __VLS_7) => any;
 };
-declare const __VLS_base: import("vue").DefineComponent<DockVariantProps | DockRailProps, {
+declare const __VLS_base: import("vue").DefineComponent<DockProps, {
     expanded: import("vue").Ref<boolean, boolean>;
     isPinned: import("vue").Ref<boolean, boolean>;
     isHeld: import("vue").ComputedRef<boolean>;
@@ -131,7 +18,7 @@ declare const __VLS_base: import("vue").DefineComponent<DockVariantProps | DockR
     collapse: () => void;
     keepOpen: () => void;
     release: () => void;
-}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<DockVariantProps | DockRailProps> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<DockProps> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;
 export default _default;

package/dist/components/custom/dock/composables/dockMorphContext.d.ts

@@ -1,4 +1,40 @@
 import type { Ref } from "vue";
+/**
+ * AX.W02 — ONE morph orchestrator per dock. The dock is a single morph stack
+ * whose active "layer" is `(expandedState × activePane)`: the outer
+ * collapse↔expand swap and the inner `<DockLayerGroup>` pane swaps are
+ * transitions in the SAME group — ONE spring, ONE scalar (`--dock-morph-t`,
+ * established by W01), ONE clock. No second engine.
+ *
+ * Re-derived from first principles on W01's settled single-scalar substrate:
+ *  - `--dock-morph-t` is written to the `.glass-dock` root and INHERITS to every
+ *    descendant (dock.css `@property … inherits:true`), so ONE spring writing
+ *    that one scalar drives EVERY registered container's size calc at once.
+ *  - Each morphing container carries its OWN `--dock-morph-from`/`--dock-morph-to`
+ *    px span (the allowed one-time FLIP measurement) and interpolates it against
+ *    the shared scalar — `from + (to − from) · t`. So a simultaneous
+ *    collapse + pane-swap reads as one continuous spring: the box, the nested
+ *    stack, and every child stagger ramp on the same `t`.
+ *
+ * The orchestrator OWNS one `SpringProgress`. The OUTER collapse↔expand pair
+ * registers as a target; a NESTED `<DockLayerGroup>` registers a SECOND target
+ * instead of minting its own `useLayerTransition` engine. A re-toggle mid-flight
+ * re-bases the live solver onto the new span from its current velocity (the iOS
+ * interruptible-physics contract W01 keeps), so even an interrupted morph stays
+ * one continuous trajectory.
+ *
+ * This is the dock-flavored first instance of the general `MorphGroup` /
+ * `GlassEffectContainer` facility (the iOS-26 Liquid-Glass corpus, facet 26 —
+ * the `provideMorphGroup` two-part seam: a per-element driver + a provide/inject
+ * orchestrator). AX.W42 generalizes it; W02 establishes the seam it builds on.
+ *
+ * LIGHT-surface only: `SpringProgress` owns its own rAF via `.play(onFrame)` and
+ * carries no static value.js edge — never import `AnimationGroup` / `./engine`
+ * (that pulls value.js into the dock bundle).
+ *
+ * The `DOCK_SPRING` tuning this orchestrator drives is the ONE authority shared with
+ * `useLayerTransition` — it lives in `../constants` (the feature-dir constants home).
+ */
 export interface DockMorphGroupRegistration {
     /** The container element owning this group's grid-stacked panes. */
     containerEl: Ref<HTMLElement | null>;

package/dist/components/custom/dock/composables/index.d.ts

@@ -8,3 +8,4 @@ export { isTeleportedTarget } from "./isTeleportedTarget";
 export { provideDockContext, useDockContext, useOptionalDockContext, DOCK_CONTEXT_KEY, type DockContext, type DockOrientation, } from "./dockContext";
 export { provideDockLayerGroupContext, useDockLayerGroupContext, useOptionalDockLayerGroupContext, DOCK_LAYER_GROUP_KEY, type DockLayerDescriptor, type DockLayerGroupContext, } from "./dockLayerContext";
 export { useDockMorphOrchestrator, provideDockMorphContext, useOptionalDockMorphContext, DOCK_MORPH_KEY, type DockMorphContext, type DockMorphGroupRegistration, type DockMorphGroupHandle, type UseDockMorphOrchestratorOptions, type UseDockMorphOrchestratorReturn, } from "./dockMorphContext";
+export { useDockOrientationMorph, type DockMorphOrientation, type UseDockOrientationMorphOptions, type UseDockOrientationMorphReturn, } from "./useDockOrientationMorph";

package/dist/components/custom/dock/composables/useDockClickIntegrity.d.ts

@@ -0,0 +1,23 @@
+import { type Ref } from "vue";
+export interface DockClickIntegrity {
+    /** Capture-phase `pointerdown` handler — records the press-time element + state. */
+    onPointerDownCapture: (event: PointerEvent) => void;
+    /** Capture-phase `click` handler — swallows an identity-changed post-swap click. */
+    onClickCapture: (event: MouseEvent) => void;
+    /** Mark the collapsed→expanded flip so the settle window opens (call on expand). */
+    markExpandFlip: () => void;
+}
+export interface UseDockClickIntegrityOptions {
+    /** The dock root element ref — the morph-state owner (`[data-morphing]`). */
+    rootEl: Ref<HTMLElement | null>;
+    /** `true` whenever the dock is visually expanded (collapsed = !this). */
+    visualExpanded: Ref<boolean>;
+}
+/**
+ * The dock click-integrity guard (R5-3). Returns the three capture-phase handlers
+ * the GlassDock SFC wires onto its root. The guard is a pure DOM-timing concern: it
+ * holds the press-time element identity + the settle-window deadline and decides, on
+ * the click, whether the click landed on the SAME control it was aimed at. Owns its
+ * own unmount cleanup.
+ */
+export declare function useDockClickIntegrity(options: UseDockClickIntegrityOptions): DockClickIntegrity;

package/dist/components/custom/dock/composables/useDockMorphWindow.d.ts

@@ -0,0 +1,15 @@
+import { type Ref } from "vue";
+/** The morph-window handlers the GlassDock SFC wires. */
+export interface DockMorphWindow {
+    markTransitioning: () => void;
+    onDockTransitionDone: (event: TransitionEvent) => void;
+    clearTransitionTimer: () => void;
+}
+/**
+ * Own the `isTransitioning` flag's morph-window lifecycle. `markTransitioning`
+ * (every `visualExpanded` flip) bumps a private generation so any in-flight
+ * morph's pending timer / `transitionend` self-cancels (the A→B→A no-skip /
+ * no-queue invariant); `onDockTransitionDone` resolves the flag on a resize-morph
+ * property finishing. Clears its timer on unmount.
+ */
+export declare function useDockMorphWindow(dockEl: Ref<HTMLElement | null>, isTransitioning: Ref<boolean>): DockMorphWindow;

package/dist/components/custom/dock/composables/useDockOrientationMorph.d.ts

@@ -0,0 +1,44 @@
+import { type ComputedRef, type Ref } from "vue";
+export type DockMorphOrientation = "vertical" | "horizontal";
+export interface UseDockOrientationMorphOptions {
+    /**
+     * The host root the scalar is written to (`--dock-morph-t`). Both docks + the
+     * bridge live under it and read the inheriting scalar.
+     */
+    rootEl: Ref<HTMLElement | null>;
+    /** The vertical dock's full (expanded) block size in px — the `t=0` height. */
+    verticalSize: number | (() => number);
+    /** The horizontal dock's full (expanded) inline size in px — the `t=1` width. */
+    horizontalSize: number | (() => number);
+}
+export interface UseDockOrientationMorphReturn {
+    /** The current target orientation. Set via `toggle()`/`morphTo()`. */
+    orientation: Readonly<Ref<DockMorphOrientation>>;
+    /** The live normalized scalar (0 = vertical, 1 = horizontal). */
+    t: Readonly<Ref<number>>;
+    /** True while the spring is in flight (the host arms `data-morphing`). */
+    morphing: Readonly<Ref<boolean>>;
+    /** The vertical dock's live height style (`{ height: "Npx" }`), collapsing 0. */
+    verticalStyle: ComputedRef<Record<string, string>>;
+    /** The horizontal dock's live width style (`{ width: "Npx" }`), growing 0→full. */
+    horizontalStyle: ComputedRef<Record<string, string>>;
+    /** The vertical dock's crossfade opacity (`{ opacity: "…" }`), 1→0 over the morph. */
+    verticalOpacity: ComputedRef<Record<string, string>>;
+    /** The horizontal dock's crossfade opacity (`{ opacity: "…" }`), 0→1 over the morph. */
+    horizontalOpacity: ComputedRef<Record<string, string>>;
+    /** The teardrop squish scalar (the bridge reads it for the liquid swell). */
+    stretch: ComputedRef<number>;
+    /** Morph to the explicit orientation (a no-op if already there). */
+    morphTo(next: DockMorphOrientation): void;
+    /** Toggle V↔H. The bidirectional driver — the SAME scalar both ways. */
+    toggle(): void;
+    /**
+     * PIN the morph to an EXACT scalar value (0→1) with NO spring — the deterministic
+     * capture seam (HG1). Disposes any live spring, writes the scalar + both flex
+     * spans + the crossfade to exactly `value`, so a frame captured at a given `t` is
+     * byte-reproducible (no wall-clock, no spring asynchrony). The orientation is set
+     * to the side `value` lands on for the inert/a11y contract.
+     */
+    pin(value: number): void;
+}
+export declare function useDockOrientationMorph(options: UseDockOrientationMorphOptions): UseDockOrientationMorphReturn;

package/dist/components/custom/dock/composables/useDockShellProps.d.ts

@@ -0,0 +1,165 @@
+import { type ComputedRef } from "vue";
+export type DockDensity = "compact" | "comfortable" | "spacious" | "audacious";
+/**
+ * The ONE GlassDock prop shape (AZ.W-DOCK-TAXONOMY — the discriminated union is
+ * gone). Every dock — horizontal or vertical — reads the SAME surface; orientation
+ * is the single layout axis and the collapse surface applies on both.
+ */
+export interface DockProps {
+    fitContent?: boolean;
+    position?: "fixed" | "inline" | "sticky";
+    /**
+     * Never collapse — render permanently expanded; the single opt-OUT of the
+     * collapse↔expand machinery. Default `false` (every dock is collapsible).
+     * AZ.W-DOCK-TAXONOMY — vertical docks are NO LONGER force-pinned here (a
+     * vertical dock morphs its height too; the prior `variant="rail"`
+     * always-expanded-by-construction is removed). A `layout="grid"` dock is
+     * `alwaysExpanded` BY CONTRACT (a 2D tile panel does not read as a collapsible
+     * pill). A vertical nav column that wants the static always-expanded look opts
+     * in via this prop. (A positive `collapsible` boolean was considered and
+     * rejected: Vue coerces an absent boolean prop to `false`, so a `collapsible`
+     * defaulting to `true` would need a `withDefaults` second default-path; the
+     * existing `alwaysExpanded` opt-out — which correctly defaults `false` — is the
+     * one knob, no Vue boolean-trap.)
+     */
+    alwaysExpanded?: boolean;
+    /**
+     * Corner treatment.
+     *   `"pill"`    — the stadium silhouette (default).
+     *   `"rounded"` — a finite rounded radius (`--radius-xl`).
+     *   `"card"`    — the AW.W3b big-dock card shell: a finite concentric
+     *                 radius (`--dock-card-radius`, default `--radius-3xl`)
+     *                 ABOVE 2xl, below pill — does NOT collapse to a stadium.
+     *                 Collapsed it returns to a pill; the pill↔card swap
+     *                 morphs on the `--dock-motion-resize` spring. AX.W56's
+     *                 squircle policy applies `corner-shape:
+     *                 var(--corner-shape-bigdock)` here under `@supports
+     *                 (corner-shape: superellipse(2))` — the big-dock is the ONE
+     *                 surface where the superellipse reads (cards/pills stay
+     *                 round); the border-radius arc is the cross-engine contract.
+     *
+     * Paints on BOTH orientations (AZ.W-DOCK-TAXONOMY — `shape` is no longer
+     * variant-gated; a vertical dock reads `shape="rounded"` for the tool-palette
+     * look, a horizontal dock reads `shape="card"` for the big-dock shell).
+     */
+    shape?: "pill" | "rounded" | "card";
+    /**
+     * Layout axis of the dock. `"horizontal"` (default) lays items out
+     * left-to-right and animates `width`; `"vertical"` lays items out
+     * top-to-bottom and animates `height`. This is the SINGLE layout axis — there
+     * is no `variant` second-way to express "vertical" (AZ.W-DOCK-TAXONOMY).
+     */
+    orientation?: "horizontal" | "vertical";
+    /**
+     * Density controls dock padding, gaps, layer height, and inherited
+     * dock control sizing. Root CSS variables can override each density.
+     */
+    density?: DockDensity;
+    /**
+     * Overflow strategy when the expanded content exceeds the dock's
+     * axis cap (`--dock-max-inline-size` horizontally,
+     * `--dock-max-block-size` vertically). The ONE knob governing every
+     * overflow behaviour (AT.W7-dock-a clean break — collapsed from the
+     * prior `wrap` boolean + `overflow` pair + `containerName` clip-lift,
+     * which all touched overflow divergently).
+     *   `"grow"`   — content grows to fit then overflows visibly past
+     *                the cap (the default; nothing clips or scrolls).
+     *   `"wrap"`   — expanded content wraps to multiple rows via CONTENT-DRIVEN
+     *                intrinsic flex-wrap (the `.dock-overflow-wrap` recipe). The
+     *                dock shrink-wraps to content and caps that intrinsic width
+     *                at `max-inline-size: var(--dock-max-inline-size)`, so the row
+     *                reflows to N rows EXACTLY when its intrinsic width exceeds
+     *                the cap — at ANY viewport width — and collapses to one row
+     *                when it fits (no viewport breakpoint). The wrapped multi-row silhouette lifts
+     *                onto the card/floating shadow tier as the dock expands.
+     *                HORIZONTAL-ONLY: a vertical dock grows-to-fit + clamps via
+     *                `--dock-max-block-size` (its own overflow story), so the
+     *                `.dock-overflow-wrap` class is not emitted for a vertical
+     *                orientation.
+     *   `"scroll"` — the dock becomes the scroll port. Horizontal docks
+     *                scroll the active layer on the inline axis
+     *                (`.dock-scroll-x`); vertical docks scroll on the
+     *                block axis (`.dock-scroll-y`), keeping the
+     *                `max-block-size` cap. The rounded pill masks the
+     *                scroll edge; the scrollbar is hidden. The axis is
+     *                chosen automatically from `orientation`.
+     */
+    overflow?: "grow" | "wrap" | "scroll";
+    /**
+     * When set, the dock root establishes an inline-size container query
+     * subject (`container-type: inline-size; container-name: <value>`) so
+     * descendants can query the named container via `@container <value>
+     * (...)` rules. ORTHOGONAL to the `overflow` clip: opting into a
+     * container subject does NOT silently change the dock's clip shell
+     * (AT.W7-dock-a — the prior clip-lift was folded out; use
+     * `overflow="wrap"` to allow multi-line content).
+     *
+     * ALWAYS-EXPANDED-ONLY (AY.W-DOCK2 §F1): `container-type: inline-size`
+     * clamps the box to its contained intrinsic size, so on a COLLAPSIBLE
+     * dock the collapse↔expand FLIP measures collapsed→collapsed and the
+     * morph FREEZES. A collapsible dock that needs deterministic targeting
+     * uses a plain `data-testid` (no layout side-effect).
+     */
+    containerName?: string;
+    /**
+     * Idle-collapse delay in ms (default 2000). Inert on an always-expanded dock.
+     */
+    collapseDelay?: number;
+    /**
+     * Start in the collapsed state (default true). Applies on BOTH orientations
+     * (AZ.W-DOCK-TAXONOMY — a vertical dock starts collapsed and morphs its block
+     * axis open too). Inert on an always-expanded dock.
+     */
+    startCollapsed?: boolean;
+    /**
+     * In-cap arrangement. `"linear"` (default) lays the active layer out as a
+     * linear row/column. `"grid"` makes the active layer a self-wrapping tile
+     * grid (Launchpad/Stage-Manager track symmetry — `auto-fill` columns of
+     * `--dock-tile-min`). ORTHOGONAL to `overflow` (the OVER-cap strategy):
+     * `layout` is the IN-cap arrangement.
+     *
+     * Hard contract: a `layout="grid"` dock is `alwaysExpanded` (a 2D panel
+     * does not read as a collapsible pill, and no width morph means no
+     * per-frame grid reflow). The canonical pairing is
+     * `shape="card" layout="grid"` (the props stay independent — no
+     * auto-implication of `shape`).
+     */
+    layout?: "linear" | "grid";
+    /**
+     * AZ.W-ADAPTIVE-AUTO Arm 2 (H3 arm a) — the sampled-luminance observer that
+     * DYNAMICALLY refines the W55 declarative bright-bucket darken (the iOS-27
+     * "darken dynamically" register). Default `true` (default-ON for the dock — the
+     * surface most often over a live/bright backdrop). It REFINES the floor (the
+     * unconditional self-engage + the declarative bucket stay the guarantee); a
+     * dark-substrate consumer opts out with `:auto-luminance="false"` (or
+     * `--glass-tint-strength: 0%` on the dock). The observer is rAF-throttled ≤ 4 Hz,
+     * IntersectionObserver-gated, and parks under `prefers-reduced-motion: reduce`.
+     */
+    autoLuminance?: boolean;
+    /**
+     * The KNOWN background-layer canvas the dock floats over (an aurora/blob
+     * `<canvas>`) — an element, a getter, or a CSS selector. When present, the
+     * observer downsamples it under the dock's box each settle (the ANIMATED-backdrop
+     * case); absent, it stack-walks the painted page background (the static case).
+     */
+    backgroundCanvas?: HTMLCanvasElement | (() => HTMLCanvasElement | null) | string | null;
+}
+/** The resolved shell-prop computeds the GlassDock SFC binds. */
+export interface DockShellProps {
+    containerStyle: ComputedRef<Record<string, string> | undefined>;
+    collapseDelay: ComputedRef<number>;
+    startCollapsed: ComputedRef<boolean>;
+    layoutValue: ComputedRef<"linear" | "grid">;
+    shape: ComputedRef<"pill" | "rounded" | "card">;
+    orientation: ComputedRef<"horizontal" | "vertical">;
+    density: ComputedRef<DockDensity>;
+    scrollClass: ComputedRef<string | null>;
+    alwaysExpanded: ComputedRef<boolean>;
+    fitContent: ComputedRef<boolean>;
+}
+/**
+ * Derive the dock's resolved shell props off the raw `props`. The defaults are
+ * applied at each read site via `?? default` (every shared default has exactly one
+ * resolution point — the one-path precept).
+ */
+export declare function useDockShellProps(props: DockProps): DockShellProps;

package/dist/components/custom/dock/composables/useLayerTransition.d.ts

@@ -1,4 +1,48 @@
 import type { Ref } from "vue";
+/**
+ * AX.W01 — the dock single-scalar morph: ONE spring, ONE clock, the whole box.
+ *
+ * Re-derived from first principles (the e8380d7 single-clock high-water; the
+ * 479-line VT-fork accretion is gone). The collapse↔expand (and inner pane-swap)
+ * morph runs off ONE normalized analytic spring whose progress scalar (0→1) is
+ * written once per frame to `--dock-morph-t` on the `.glass-dock` root. EVERY
+ * animated axis — inline-size, padding, border-radius, scale, background / border
+ * color, AND the child stagger — is a pure `calc()` read off that one scalar in
+ * `dock.css`. NO CSS `transition` on the root morph props; NO View-Transitions
+ * fork: the live `SpringProgress` ODE is the single authority on every engine, so
+ * iOS interruptible-physics + velocity-continuity retarget are universal, not
+ * capability-gated.
+ *
+ * The morph is a FLIP — the from→to size is measured ONCE per swap (the allowed
+ * one-time measurement primitive, never a co-driver), written as `--dock-morph-from`
+ * / `--dock-morph-to` px vars on the morphing element, and the live scalar
+ * interpolates between them in CSS. Content lays out once at natural size;
+ * `overflow:clip` on the morph axis (dock.css, gated on `data-morphing`) makes the
+ * box the reveal aperture; the spring-keyed stagger fades the children in-step.
+ *
+ * Velocity-continuity (the ONE load-bearing iOS piece): a re-toggle mid-flight
+ * re-bases the live solver onto the new span from its current velocity (the
+ * analytic re-seat keyframes.js owns) — inertia carries, no snap-from-rest. The
+ * spring constant is the published `--spring-dock` (response 0.32, ζ 0.7, ~+4.6%
+ * overshoot), the SAME analytic ODE the build-time linear() token samples.
+ *
+ * LIGHT-surface only: `SpringProgress` owns its own rAF via `.play(onFrame)` and
+ * carries no static value.js edge. NEVER import `AnimationGroup` / the `./engine`
+ * boundary — that pulls value.js into the dock bundle.
+ *
+ * BOOKED: AY.W-GOD1 — the FLIP-engine FOLD. This standalone engine is a
+ * near-duplicate of the orchestrator's FLIP-pin-measure-arm dance
+ * (`dockMorphContext.ts:onSwap`), which is the SUPERSET (it carries sibling-rebase
+ * this copy lacks). W-DOCK2 found the duplication (H-dock §D3) and BOOKED the fold
+ * to W-GOD1 (the GlassDock.vue carve touches the same FLIP code, so the carve is
+ * cleaner over ONE engine; folding now would also break the `/dock` `useLayerTransition`
+ * public re-export an external consumer reads). Until W-GOD1 lands, `proof:dock-orchestrator-single`'s
+ * FLIP DRIFT-GUARD asserts this engine and the orchestrator stay byte-faithful on
+ * the load-bearing pin-measure-arm markers, so a divergence in the shared dance REDs.
+ * The CANONICAL `DOCK_SPRING` authority is `dock/constants.ts` (the colocation home
+ * BOTH this engine and the orchestrator import); `proof:spring-tokens-synced` reads
+ * it there, NOT a per-composable copy (W-COLOCATE — the dead-witness fix, continued).
+ */
 export interface UseLayerTransitionOptions {
     /** The container element that owns the stacked layer panes. */
     containerEl: Ref<HTMLElement | null>;

package/dist/components/custom/dock/constants.d.ts

@@ -0,0 +1,48 @@
+import type { Component } from "vue";
+/**
+ * AZ.W-RAIL3 — one `<DockRail>` chip descriptor: the visible facet the floating
+ * carousel strip renders (id + label + glyph). A `<script setup>` SFC cannot
+ * re-export a named type through the `export { default }` barrel, so the chip
+ * descriptor lives here (the colocated types home) and the SFC imports it; the
+ * barrel re-exports it for consumers typing their `items` array.
+ */
+export interface DockRailItem {
+    /** The context id this chip selects (written to `v-model:context`). */
+    id: string;
+    /** The chip label. */
+    label: string;
+    /** The chip glyph (a `@lucide/vue` icon or any component). */
+    icon?: Component;
+}
+/**
+ * The ONE dock-morph spring authority — the iOS-26 interruptible-physics tuning the
+ * dock's single `SpringProgress` orchestrator (`dockMorphContext.ts`) AND the
+ * `useLayerTransition` engine both read. Co-located here so the `response`/`damping`
+ * pair is defined ONCE rather than duplicated at the top of each composable (the two
+ * prior copies were a DRY hazard — a re-tune had to touch both).
+ */
+export declare const DOCK_SPRING: {
+    readonly response: 0.32;
+    readonly dampingFraction: 0.7;
+};
+/**
+ * The CSS properties whose `transitionend` the dock-morph window watches to know a
+ * resize-morph has settled (`useDockMorphWindow.ts`). A `transitionend` on any other
+ * property is ignored.
+ */
+export declare const RESIZE_MORPH_PROPS: Set<string>;
+/** `Symbol()` label for the `DockContext` injection key (`dockContext.ts`). */
+export declare const DOCK_CONTEXT_LABEL = "glass-ui:dock-context";
+/** `Symbol()` label for the `DockLayerGroupContext` injection key (`dockLayerContext.ts`). */
+export declare const DOCK_LAYER_GROUP_LABEL = "glass-ui:dock-layer-group";
+/** `Symbol()` label for the `DockMorphContext` injection key (`dockMorphContext.ts`). */
+export declare const DOCK_MORPH_LABEL = "glass-ui:dock-morph-context";
+/** AZ.W-DOCK-FLICKER — the hover-hysteresis tuning pair (useDockState).
+ *  HOVER_INTENT_MS: the intent-dwell before a collapsed→hover expand commits
+ *  (a sweeping-edge enter is canceled by the chasing leave inside this window).
+ *  EDGE_BAND_PX: the morphing-edge-sweep recheck band — a mid-morph leave with
+ *  the pointer still inside (within this band of the moving edge) is the box
+ *  edge sweeping past the cursor, not a real exit. */
+export declare const HOVER_INTENT_MS = 60;
+export declare const EDGE_BAND_PX = 24;
+export declare const MORPH_SETTLE_MS = 320;