@mkbabb/glass-ui 4.1.0 → 5.0.0

package/dist/components/dock/DockCrossfade.vue.d.ts

@@ -0,0 +1,50 @@
+import { type DockFaceDescriptor } from "./composables/dockCrossfadeContext";
+/**
+ * <DockCrossfade :active> — the THIN controlled face-swap core (BI.W-DOCK-CROSSFADE,
+ * PASS-1 §2.6 / PASS-4B ruling 3).
+ *
+ * The content layer hosts ONE active face; a switch is a two-child OPACITY OVERLAP on
+ * the per-face `--dock-t` scalar — driven by the ONE dock spring (`useDockSpring`,
+ * velocity-continuous + interruptible), NOT a UA-eased View Transition. G6 CLOSED:
+ * `startViewTransition` is non-interruptible (a hard cut on rapid re-toggle — a direct
+ * violation of the liquid-weight edict) and its snapshot of a live `backdrop-filter`
+ * plate over aurora is unproven (blur ghost / edge pop); the two-child crossfade needs
+ * no VT and stays spring-driven. The reserved box is sized to the PEAK face as a
+ * MEASURE-ONCE `min-block-size` (a running max — NOT a per-swap FLIP). A dissolving
+ * focus-holding face transfers focus to its successor, else the body
+ * (un-inert-before-focus is load-bearing).
+ *
+ * Faces register through the crossfade context (`<DockLayer>` children). Where a rail
+ * exists, `useSelectionGroup` (the switcher run) drives `:active` — the composing
+ * `<DockLayerGroup>` case. The controlled-no-rail 5-pane case (speedtest) consumes this
+ * DIRECTLY: a no-selection face-swap does NOT route through a selection engine (the
+ * roving machine + indicator + selection model are all inert in that mode; don't
+ * abstract them over a case that never selects).
+ */
+type __VLS_Props = {
+    /** The active face id — the caller-owned model (the ONE registry, no shadow state). */
+    active: string;
+    /**
+     * The reserve axis. `block` (default) reserves the peak face HEIGHT; `inline`
+     * reserves the peak WIDTH (a horizontal control run). The opacity crossfade is
+     * axis-agnostic — only the peak reserve axis differs.
+     */
+    reserve?: "block" | "inline";
+};
+declare var __VLS_1: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
+    faces: import("vue").ComputedRef<DockFaceDescriptor[]>;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    reserve: "block" | "inline";
+}, {}, {}, {}, 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;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/dock/DockLayer.vue.d.ts

@@ -0,0 +1,33 @@
+import type { Component } from "vue";
+/**
+ * <DockLayer> — a named content pane (a "face") inside a <DockCrossfade> /
+ * <DockLayerGroup>.
+ *
+ * BI.W-DOCK-CROSSFADE — the FLIP/registration engine is RETIRED. A face now does one
+ * thing: it registers its id + label + icon + host element with the crossfade slot on
+ * mount, renders its content in a `.dock-face` host, and reads its active/leaving state
+ * off the context. The crossfade slot (`<DockCrossfade>`) owns the two-child opacity
+ * overlap, the peak reserve, and the focus-transfer-on-dissolve — this component holds
+ * no spring, no measure, no orphan-focus watch (all folded to the ONE crossfade slot).
+ */
+type __VLS_Props = {
+    /** Stable identifier — referenced by the crossfade's `active` id. */
+    id: string;
+    /** Human-readable label; used for tooltip + the switcher rail glyph. */
+    label?: string;
+    /** Optional icon: a Vue component, or a raw string (rendered as text). */
+    icon?: Component | string;
+};
+declare var __VLS_1: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & 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;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/dock/DockLayerGroup.vue.d.ts

@@ -0,0 +1,65 @@
+import type { Motion } from "../_shared/axes";
+/**
+ * <DockLayerGroup> — a stack of <DockLayer> faces with an optional Figma-style
+ * switcher rail built from each face's metadata.
+ *
+ * BI.W-DOCK-CROSSFADE — the FLIP/registration engine is RETIRED. The face-swap is now
+ * ONE crossfade slot: this component COMPOSES `<DockCrossfade :active>` (the thin
+ * controlled core — two-child opacity overlap, peak reserve, focus-transfer) and reads
+ * the registered face descriptors off it for the rail.
+ *
+ * BI.W-DOCK-FOLD — the switcher rail is driven by the library's ONE headless selection
+ * engine `useSelectionGroup` (the dock IS SegmentedTabs/ToggleGroup wearing chrome). The
+ * reka `ui/tabs` substrate + its `--reka-tabs-indicator-*` position path are DEFINITION-
+ * ABSENT (retired); the rail is a plain `role="tablist"` of `role="tab"` buttons whose
+ * roving focus (Arrow/Home/End), role-per-mode ARIA, and the ONE traveling-indicator
+ * writer (`useSelectionIndicator`, Safari-identical by construction) come from the engine.
+ * Selecting a tab writes the SAME `activeLayer` the crossfade slot reads — one registry,
+ * no second source of truth.
+ *
+ * Usage:
+ *   <DockLayerGroup v-model:active="layer">
+ *     <DockLayer id="assets" label="Assets" :icon="AssetsIcon">...</DockLayer>
+ *     <DockLayer id="layers" label="Layers" :icon="LayersIcon">...</DockLayer>
+ *   </DockLayerGroup>
+ */
+type __VLS_Props = {
+    /** Layout axis; matches `GlassDock.orientation`. Drives the rail + face axis. */
+    orientation?: "horizontal" | "vertical";
+    /** Render the embedded switcher rail. Hidden when there is 0 or 1 face. */
+    showRail?: boolean;
+    /** Rail placement relative to the face stack. */
+    railPosition?: "start" | "end";
+    /**
+     * BH.W-MOTION-AXIS — the ONE motion-weight axis. `full` (default) arms
+     * pull-to-switch: the switcher-rail indicator is draggable — pull along the rail
+     * axis to the next face chip, the fling-to-nearest on release writes `active`
+     * (`useDragMorph`, consumer #2). `reduced`/`off` opt DOWN to click/keyboard-only
+     * (the roving tabindex + Arrow keys stay). PRM forces `full → reduced`.
+     */
+    motion?: Motion;
+};
+type __VLS_ModelProps = {
+    "active": string;
+};
+type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
+declare var __VLS_14: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_14) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:active": (value: string) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    "onUpdate:active"?: ((value: string) => any) | undefined;
+}>, {
+    showRail: boolean;
+    railPosition: "start" | "end";
+}, {}, {}, {}, 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;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/dock/DockStack.vue.d.ts

@@ -0,0 +1,73 @@
+import { type Component } from "vue";
+import type { DockStackItem } from "./constants";
+/**
+ * <DockStack> — BI.W-DOCK-ESCAPE. The dock's satellite fan / facet strip, rebuilt as a
+ * TOP-LAYER POPOVER.
+ *
+ * The CORE anchor is a normal in-flow dock control (the popover invoker). Its members FAN
+ * OUT of a native `popover` surface promoted to the TOP LAYER — exempt from ancestor
+ * `overflow`/`clip`/`contain`/`transform`/`filter` BY SPEC. "Chips overlap the dock body"
+ * / "the fan clips at the port end" (UF-C2) are impossible once the surface is in the top
+ * layer: there is nothing to escape from. The dock box stays INVIOLATE — the fan feeds NO
+ * size into the dock's intrinsic box (it is a fixed-positioned top-layer element).
+ *
+ * This REPLACES the retired `.glass-dock-frame` `display:contents` sibling + the
+ * `railProjection.ts` φ²-crossing ring math (PASS-4B ruling 4 — an anchored flex strip
+ * needs no tier math; the fan is a plain anchored flex strip in the popover).
+ *
+ * PLACEMENT is the JS one-shot (`useDockPopover` — a `getBoundingClientRect` on open + a
+ * resize/scroll re-place, viewport-clamped). NO native CSS anchor positioning
+ * (`anchor()`/`position-anchor`/`@position-try` BANKED — the SAF-1 Safari-transform-chain
+ * fence). HOVER-INTENT + light-dismiss + focus-return are wired in the composable.
+ *
+ *   • `mode="stack"` (DEFAULT) — the macOS Dock hover-expand glyph fan: N members, each a
+ *     clear `--glass-bg-floating` glass icon.
+ *   • `mode="facets"` — the context carousel: each member is an ACCENT-tinted context chip
+ *     writing its OWN `--glass-accent` hue (the BB.W-GLASS-ACCENT per-instance
+ *     chromatic-rim axis), the active facet on the selected-as-glass tier.
+ *
+ * ONE REGISTRY (KEPT). The members write the consumer-owned `v-model:selected`; this
+ * primitive owns NO internal selection shadow. The hover `open` is a transient UI state.
+ */
+type __VLS_Props = {
+    /** The stack/facet members — the fan-out contents. */
+    items: readonly DockStackItem[];
+    /**
+     * The render mode. `"stack"` (default) = the macOS hover-expand glyph fan.
+     * `"facets"` = the accent-tinted context carousel (each chip writes its own
+     * `--glass-accent` hue).
+     */
+    mode?: "stack" | "facets";
+    /** The core anchor glyph (the always-visible dock(1) invoker). Default: a layers glyph. */
+    core?: Component;
+    /** The core's accessible label (the stack's name). */
+    coreLabel?: string;
+    /** Members visible in the fan before it overflows the `<FadingScroll>` port. */
+    visibleCount?: number;
+    /** WRAP a >`visibleCount` fan into a second rank instead of scrolling. */
+    wrap?: boolean;
+    /**
+     * Which end of the anchor the fan aligns to (the cross-axis alignment of the
+     * top-layer placement). `"end"` (default) trails the anchor's leading edge.
+     */
+    position?: "start" | "end";
+};
+type __VLS_ModelProps = {
+    "selected"?: string;
+};
+type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
+declare const __VLS_export: import("vue").DefineComponent<__VLS_PublicProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    select: (id: string) => any;
+    "update:selected": (value: string | undefined) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    onSelect?: ((id: string) => any) | undefined;
+    "onUpdate:selected"?: ((value: string | undefined) => any) | undefined;
+}>, {
+    position: "start" | "end";
+    wrap: boolean;
+    mode: "stack" | "facets";
+    visibleCount: number;
+    coreLabel: string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/dock/DockTrigger.vue.d.ts

@@ -0,0 +1,27 @@
+import { type HTMLAttributes } from "vue";
+type __VLS_Props = {
+    /** Which overlay this trigger opens. */
+    for?: "select" | "dropdown" | "popover";
+    class?: HTMLAttributes["class"];
+};
+declare var __VLS_8: {}, __VLS_16: {}, __VLS_30: {}, __VLS_39: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_8) => any;
+} & {
+    icon?: (props: typeof __VLS_16) => any;
+} & {
+    default?: (props: typeof __VLS_30) => any;
+} & {
+    default?: (props: typeof __VLS_39) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    for: "select" | "dropdown" | "popover";
+}, {}, {}, {}, 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;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

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

@@ -0,0 +1,33 @@
+import { type DockProps } from "./composables/useDockShellProps";
+declare var __VLS_1: {}, __VLS_3: {}, __VLS_5: {}, __VLS_7: {}, __VLS_9: {};
+type __VLS_Slots = {} & {
+    persistent?: (props: typeof __VLS_1) => any;
+} & {
+    default?: (props: typeof __VLS_3) => any;
+} & {
+    collapsed?: (props: typeof __VLS_5) => any;
+} & {
+    search?: (props: typeof __VLS_7) => any;
+} & {
+    'persistent-end'?: (props: typeof __VLS_9) => any;
+};
+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>;
+    isTransitioning: import("vue").Ref<boolean, boolean>;
+    expand: () => void;
+    collapse: () => void;
+    keepOpen: () => void;
+    release: () => void;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<DockProps> & Readonly<{}>, {
+    autoLuminance: boolean;
+}, {}, {}, {}, 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;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/dock/composables/dockContext.d.ts

@@ -0,0 +1,48 @@
+import type { ComputedRef } from "vue";
+export type DockOrientation = "horizontal" | "vertical";
+export type DockLayout = "linear" | "grid";
+/**
+ * Dock context surfaces the dock id + orientation + held-state coordination
+ * to descendants.
+ *
+ * O.W2 — canonical typed-key + helper-pair DI shape per invariant 25.
+ * The 6 prior string-keyed provides (`glassDockContext`, `glassDockId`,
+ * `dockKeepOpen`, `dockRelease`, `dockHeld`, `dockExpanded`) collapse into
+ * the single `DOCK_CONTEXT_KEY` typed `InjectionKey<DockContext>`.
+ * `dockExpanded` is retired (zero downstream consumers per Rδ audit).
+ * `glassDockId` is dedup'd with `context.id`.
+ *
+ * Paired helpers:
+ *  - `useDockContext()` — strict; throws when used outside `<GlassDock>`.
+ *  - `useOptionalDockContext()` — befitting silent default for primitives
+ *    that may render outside a dock (Slider, popovers, …).
+ *
+ * J.W3.B — `registerPopover` / `closeOtherPopovers` retired. Hover-driven
+ * dock popovers compose `<Popover trigger="hover" keep-dock-open>` (the
+ * BI.W-OVERLAY-UNION sealed union; the fine-hover branch is reka's
+ * HoverCardRoot). Open/close cadence is owned by reka's hover primitives;
+ * cooperative dismissal between sibling popovers is no longer needed (the
+ * pointer-leave timer handles the cluster transit case).
+ */
+export interface DockContext {
+    id: string;
+    orientation: ComputedRef<DockOrientation>;
+    /**
+     * In-cap arrangement (`linear` row/column vs `grid` tile panel). AX.W45 —
+     * `<DockSeparator>` reads this to paint a full-row section break in a grid dock
+     * (a 1px perpendicular hairline is useless in a 2D tile grid).
+     */
+    layout: ComputedRef<DockLayout>;
+    /** Acquire a keep-open token; suppresses timer-based collapse. */
+    keepOpen: () => void;
+    /** Release a previously-acquired keep-open token. */
+    release: () => void;
+    /** Reactive `keepOpenCount > 0` flag; descendants reflect via `data-held`. */
+    held: ComputedRef<boolean>;
+}
+export declare const DOCK_CONTEXT_KEY: import("vue").InjectionKey<DockContext>;
+export declare function provideDockContext(context: DockContext): void;
+/** Strict — throws when used outside `<GlassDock>`. */
+export declare const useDockContext: () => DockContext;
+/** Befitting silent default for primitives that may render outside a dock. */
+export declare const useOptionalDockContext: () => DockContext | null;

package/dist/components/dock/composables/dockCrossfadeContext.d.ts

@@ -0,0 +1,57 @@
+import type { Component, Ref } from "vue";
+/**
+ * BI.W-DOCK-CROSSFADE — the crossfade face-registration context.
+ *
+ * `<DockCrossfade :active>` provides this; each face host (`<DockLayer>`) registers
+ * its id + label + icon + host element on mount. The crossfade slot owns ONE face
+ * registry — the registration machinery FOLDED here from the retired
+ * `DockLayerGroup` `register`/`unregister` + `useLayerTransition` FLIP (PASS-1 §2.6).
+ * A switcher rail (where one exists — `<DockLayerGroup>`) reads `faces` for its chip
+ * run; the controlled-no-rail 5-pane case (speedtest) consumes `<DockCrossfade>`
+ * DIRECTLY and reads only `activeId`/`leavingId` (no rail, no selection engine).
+ *
+ * The context is DISTINCT from `DockContext` (a `<DockCrossfade>` need not live inside
+ * a `<GlassDock>`) and from `DockMorphContext` (the plate collapse orchestrator) — the
+ * face crossfade is orthogonal to the box morph (the compound: a face-swap DURING a
+ * simultaneous collapse rides two independent scalars — per-face `--dock-t` for the
+ * opacity overlap, the inheriting `--dock-morph-t` for the plate clip). It keeps its
+ * own module-local key (canonical typed-key DI, invariant 25).
+ */
+export interface DockFaceDescriptor {
+    id: string;
+    label?: string;
+    icon?: Component | string;
+}
+export interface DockFaceRegistration extends DockFaceDescriptor {
+    /**
+     * The face host element. The crossfade slot writes the per-face `--dock-t`
+     * opacity scalar here + measures its `scrollHeight` for the peak reserve.
+     */
+    el: HTMLElement;
+}
+export interface DockCrossfadeContext {
+    /** Announce a face host (idempotent per id) — kicks a peak re-measure. */
+    register(reg: DockFaceRegistration): void;
+    /** Retract a face host on unmount — kicks a peak re-measure. */
+    unregister(id: string): void;
+    /**
+     * The active face id (the one shown at rest). Exposed READ-ONLY: a `<DockLayer>`
+     * child reads its active state but never writes the controlled `active` value
+     * (the ONE registry lives on the caller's model).
+     */
+    activeId: Readonly<Ref<string>>;
+    /** The face currently dissolving out, or `null`. READ-ONLY to faces. */
+    leavingId: Readonly<Ref<string | null>>;
+    /**
+     * The registered face descriptors in registration order — the switcher rail's
+     * chip source (a `<DockLayerGroup>` reads this; the controlled-no-rail case
+     * ignores it).
+     */
+    faces: Readonly<Ref<DockFaceDescriptor[]>>;
+}
+export declare const DOCK_CROSSFADE_KEY: import("vue").InjectionKey<DockCrossfadeContext>;
+export declare function provideDockCrossfadeContext(context: DockCrossfadeContext): void;
+/** Strict — throws when used outside `<DockCrossfade>`. */
+export declare const useDockCrossfadeContext: () => DockCrossfadeContext;
+/** Befitting silent default; reserved for future consumers. */
+export declare const useOptionalDockCrossfadeContext: () => DockCrossfadeContext | null;

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

@@ -0,0 +1,89 @@
+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`),
+ * ONE clock. No second engine.
+ *
+ * BD.W-DOCK-CORE (the size re-invent) — the orchestrator no longer MEASURES a
+ * per-swap `from/to` span. The visible size is a ratio-free convex blend of two
+ * endpoints measured ONCE per content change (`useDockExpandedSize` writes
+ * `--dock-expanded-px`/`--dock-collapsed-px`; layers.css blends them on
+ * `--dock-morph-t`). So this driver shrinks to its essence: on a layer swap it
+ * arms `[data-morphing]`, swaps the crossfade classes (the a11y-006 3-state
+ * hit-test contract, LOAD-BEARING — KEPT verbatim), and runs ONE `SpringProgress`
+ * gliding `--dock-morph-t` 0→1; on settle it clears the morph state. A re-toggle
+ * mid-flight re-bases the live solver onto a fresh spring CARRYING the prior
+ * velocity (the iOS interruptible-physics continuity).
+ *
+ * LIGHT-surface only: the `useDockSpring` factory's `SpringProgress` owns its own
+ * rAF via `.play(onFrame)` and carries no static value.js edge — the factory never
+ * imports `AnimationGroup` / `./engine`.
+ *
+ * `DOCK_SPRING` is byte-fenced — it lives in `../constants`.
+ */
+export interface DockMorphGroupRegistration {
+    /** The container element owning this group's grid-stacked panes. */
+    containerEl: Ref<HTMLElement | null>;
+    /** The group's currently-active pane id (its `v-model:active`). */
+    activeLayer: Ref<string>;
+    /** Layout axis of the group; matches the group's `orientation`. */
+    axis: Ref<"horizontal" | "vertical">;
+}
+export interface DockMorphGroupHandle {
+    /** The active pane id post-swap (the orchestrator mutates it). */
+    currentLayer: Readonly<Ref<string>>;
+    /** The pane id currently fading out, or null. */
+    leavingLayer: Readonly<Ref<string | null>>;
+    /** Detach this group from the orchestrator (on the group's unmount). */
+    release(): void;
+}
+/**
+ * The provided morph seam. A nested `<DockLayerGroup>` injects this and DEFERS
+ * its pane-swap morph to the dock's single orchestrator via `registerGroup`.
+ */
+export interface DockMorphContext {
+    registerGroup(group: DockMorphGroupRegistration): DockMorphGroupHandle;
+}
+export declare const DOCK_MORPH_KEY: import("vue").InjectionKey<DockMorphContext>;
+export declare function provideDockMorphContext(context: DockMorphContext): void;
+/**
+ * Befitting-silent — returns `null` for a `<DockLayerGroup>` rendered outside a
+ * `<GlassDock>` (the standalone self-orchestrate path).
+ */
+export declare const useOptionalDockMorphContext: () => DockMorphContext | null;
+export interface UseDockMorphOrchestratorOptions {
+    /** The `.glass-dock` root that carries the shared scalar + clip aperture. */
+    rootEl: Ref<HTMLElement | null>;
+    /** The outer collapse↔expand container (`.dock-layers`). */
+    outerEl: Ref<HTMLElement | null>;
+    /** The outer active "layer" id — `(expandedState)` projected to a string. */
+    outerActiveLayer: Ref<string>;
+    /** The outer pair morphs the inline axis (a horizontal dock). */
+    outerAxis: Ref<"horizontal" | "vertical">;
+    /**
+     * BG.NF.1 W-FALLBACK-EXCISE — a NOTIFY seam (NOT a busy-flag shadow): the
+     * orchestrator calls `onMorphActiveChange(true)` when the outer morph spring ARMS
+     * (alongside `setAttribute("data-morphing")`) and `(false)` when it SETTLES
+     * (alongside `removeAttribute`), so a consumer (GlassDock) can drive its OWN
+     * `isTransitioning` off the morph's OWN spring settle — the CSS-transition-era
+     * wrong-clock settle timer + dead `@transitionend` resolver are excised. The
+     * orchestrator holds NO parallel boolean (the single busy signal stays the
+     * `[data-morphing]` attr + the factory's `.live` — proof:dock-engine-unify U3).
+     */
+    onMorphActiveChange?: (active: boolean) => void;
+}
+export interface UseDockMorphOrchestratorReturn {
+    /** Provide-able context: a nested `<DockLayerGroup>` registers through it. */
+    context: DockMorphContext;
+    /** The outer pair's post-swap active layer id (call-site parity). */
+    outerCurrentLayer: Readonly<Ref<string>>;
+}
+/**
+ * The ONE morph engine for a dock instance. Drives a single `useDockSpring` handle
+ * that glides the one `--dock-morph-t` scalar 0→1 on a layer swap; the size is a
+ * ratio-free blend of the measure-ONCE endpoints (layers.css). Crossfade classes
+ * (the 3-state a11y hit-test contract) swap on the swap; the spring is the clock.
+ */
+export declare function useDockMorphOrchestrator(options: UseDockMorphOrchestratorOptions): UseDockMorphOrchestratorReturn;

package/dist/components/dock/composables/dockMorphMeasure.d.ts

@@ -0,0 +1,86 @@
+import { type Ref } from "vue";
+/**
+ * BD.W-DOCK-CORE (the width-seizure cure) — the dock morph SIZE measure.
+ *
+ * THE BUG THIS RETIRES (the year-old seizure): the prior pipeline measured a
+ * per-swap `from/to` FLIP ratio and drove the visible size by
+ * `--dock-root-scale = max(ratio + (1−ratio)·t, 0.06)` — a FLOOR with NO CEILING.
+ * When the morph target measured small (a degenerate `to` racing the content
+ * layout), `ratio = from/max(to,1px)` ran to ~56 → `scaleX(56)` = a ~2451px
+ * detonation on collapse / an inversion at the spring overshoot peak. The
+ * `transform-origin: center` kept the centroid clean (`cxRange 0`), which is
+ * exactly why every prior judge measuring the centroid PASSED while the WIDTH
+ * detonated. The whole measure-and-arm FLIP machinery
+ * (`measureAndArmMorph`/`seatTargetSync`/`rebaseSiblingSpans`/
+ * `forceNestedMaxContent`/`nestedTargetsWithin`/`measureTo`/`armRootMorphSpan`/
+ * `clearRootMorphSpan`/`morphMinFloorPx`/the per-target generation gating) is
+ * DELETED — clean break, no legacy, no floor that masks a bad measurement.
+ *
+ * THE CURE — a ratio-FREE measure-ONCE convex blend. The dock measures its two
+ * KNOWN footprints ONCE per content change (a `ResizeObserver`, NOT a per-swap
+ * rAF race): `--dock-expanded-px` (the expanded content width, read behind the
+ * clip aperture) and `--dock-collapsed-px` (the collapsed summary box). The
+ * visible size is the convex blend `--dock-live = collapsed + (expanded −
+ * collapsed)·--dock-morph-t` and `--dock-size-scale = --dock-live / expanded`
+ * (layers.css). A convex blend of two POSITIVE endpoints can NEVER exceed the
+ * larger nor invert below the smaller — BOUNDED by construction, no ratio, no
+ * `scaleX` explosion, regardless of spring overshoot (the `clamp(0,t,1)` caps the
+ * size term; the >1 excursion routes to the orthogonal punch channel).
+ *
+ * THE FRESHNESS GUARD (challenge 3·R2): a measure-ONCE endpoint can still be read
+ * stale — before `fonts.ready`, before async icon SVGs lay out, on a
+ * `display:none`→0 route swap, or on a `content-visibility:auto` parent (the RO
+ * fires 0). A 0 expanded would give `collapsed/0 = ∞`. So FLOOR `--dock-expanded-px`
+ * at `max(measured, --dock-collapsed-px)` and re-measure on `fonts.ready` + the
+ * FIRST non-zero RO callback + visibility-enter. This is NOT the deleted magic
+ * floor (which masked a per-frame measurement); it is a one-shot endpoint
+ * sanity bound on a value that is otherwise stable across the whole morph.
+ *
+ * `DOCK_SPRING` is byte-fenced — it lives in `../constants`, never touched here.
+ */
+export declare function dimOf(axis: "horizontal" | "vertical"): "width" | "height";
+export declare function getSize(el: HTMLElement, axis: "horizontal" | "vertical"): number;
+export interface UseDockExpandedSizeOptions {
+    /** The `.glass-dock` root the `--dock-expanded-px`/`--dock-collapsed-px` write to. */
+    rootEl: Ref<HTMLElement | null>;
+    /**
+     * The content element whose intrinsic morph-axis span is observed for size
+     * changes (the active full-pane container — `.dock-layers`). Its resizes are the
+     * RO trigger; the ENDPOINTS are read off the ROOT box (content + chrome), keyed
+     * by the dock's at-rest expanded/collapsed state.
+     */
+    contentEl: Ref<HTMLElement | null>;
+    /**
+     * The morph axis (a horizontal dock blends width; a vertical dock blends height).
+     */
+    axis: Ref<"horizontal" | "vertical">;
+    /**
+     * Whether the dock is currently in its EXPANDED visual state (a `Ref<boolean>`).
+     * The endpoint captured at rest is keyed off this: at rest expanded → the root
+     * box is the `--dock-expanded-px` endpoint; at rest collapsed → the
+     * `--dock-collapsed-px` endpoint. (A reactive read, so a state flip re-captures.)
+     */
+    expanded: Ref<boolean>;
+}
+/**
+ * BD.W-DOCK-CORE — capture the two convex-blend endpoints ONCE PER STATE off the
+ * ROOT box.
+ *
+ * The visible morph scales the ROOT (chrome + content), so the two blend endpoints
+ * must be the ROOT's OWN expanded/collapsed footprints — NOT the bare content span
+ * (which omits the padding/min-width chrome). The endpoints are captured at REST
+ * (when `[data-morphing]` is OFF): the dock's settled root box in its current
+ * expanded/collapsed state IS that state's endpoint. A `ResizeObserver` on the
+ * content re-captures the CURRENT state's endpoint whenever the content reflows
+ * (more controls, a font swap), so the blend stays fresh — but it never reads the
+ * box MID-MORPH (the scaled box would feed back a degenerate endpoint, the seizure's
+ * cousin). The expanded endpoint is FLOORED at `max(captured, collapsed)` — the
+ * freshness guard against a 0/degenerate read giving `collapsed/0 = ∞`.
+ *
+ * The collapsed endpoint starts at the resolved `--dock-morph-min` icon-square floor
+ * and is refined to the real collapsed root box the first time the dock rests
+ * collapsed; the expanded endpoint is captured the first (and every) time it rests
+ * expanded. So the FIRST morph from a freshly-mounted expanded dock already has a
+ * real expanded endpoint + a sane collapsed floor — bounded by construction.
+ */
+export declare function useDockExpandedSize(options: UseDockExpandedSizeOptions): void;

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

@@ -0,0 +1,10 @@
+export { useDockState } from "./useDockState";
+export type { UseDockStateOptions, UseDockStateReturn, DockState } from "./useDockState";
+export { useDockSearch } from "./useDockSearch";
+export type { UseDockSearchOptions, UseDockSearchReturn } from "./useDockSearch";
+export { useDockHold } from "./useDockHold";
+export type { UseDockHoldOptions, UseDockHoldReturn } from "./useDockHold";
+export { isTeleportedTarget } from "./isTeleportedTarget";
+export { provideDockContext, useDockContext, useOptionalDockContext, DOCK_CONTEXT_KEY, type DockContext, type DockOrientation, } from "./dockContext";
+export { provideDockCrossfadeContext, useDockCrossfadeContext, useOptionalDockCrossfadeContext, DOCK_CROSSFADE_KEY, type DockFaceDescriptor, type DockFaceRegistration, type DockCrossfadeContext, } from "./dockCrossfadeContext";
+export { useDockMorphOrchestrator, provideDockMorphContext, useOptionalDockMorphContext, DOCK_MORPH_KEY, type DockMorphContext, type DockMorphGroupRegistration, type DockMorphGroupHandle, type UseDockMorphOrchestratorOptions, type UseDockMorphOrchestratorReturn, } from "./dockMorphContext";

package/dist/components/dock/composables/useDockFisheye.d.ts

@@ -0,0 +1,24 @@
+import { type Ref } from "vue";
+export interface UseDockFisheyeOptions {
+    /** Arm gate (default always). A parked-until-DEVICE consumer passes `() => false`. */
+    enabled?: () => boolean;
+}
+export interface UseDockFisheyeReturn {
+    /** Re-write each item's layout-time `--x` (call after a content/layout change). */
+    remeasure: () => void;
+}
+/**
+ * useDockFisheye — the ONE rAF-coalesced pointermove `--dock-px` writer for the fits-branch
+ * pure-CSS Gaussian fisheye (BI.W-DOCK-OVERFLOW, G4). It writes exactly ONE per-frame
+ * scalar — `--dock-px` (the pointer's inline position relative to the scroll port, a
+ * unitless number) on the dock; each item carries a LAYOUT-TIME `--x` (its center, unitless,
+ * (re)written on the RO — NOT per frame). The pure-CSS Gaussian in fisheye.css does the
+ * per-item scale. The JS owns NO scale math and NO layout write — it writes two custom
+ * properties and adds the `.dock-fisheye-item` marker class.
+ *
+ * The writer is the ENHANCEMENT layer over the universal native-scroll floor (overflow.css):
+ * the CSS gates the scale on `:not([data-dock-overflow])` + `(hover: hover) and (pointer:
+ * fine)` + PRM-off, so a scrollable / coarse / reduced-motion dock paints flat regardless of
+ * this writer. G9/O5 — this is a `pointermove` listener, NEVER a `scroll` listener.
+ */
+export declare function useDockFisheye(dockEl: Ref<HTMLElement | null>, options?: UseDockFisheyeOptions): UseDockFisheyeReturn;

package/dist/components/dock/composables/useDockOverflowFit.d.ts

@@ -0,0 +1,22 @@
+import { type Ref } from "vue";
+/**
+ * useDockOverflowFit — the fits-vs-scrollable mode resolution for the dock's native
+ * scroll track (BI.W-DOCK-OVERFLOW, PASS-1 §2.5). A MEASURED branch (the wave's "single
+ * container-query / measured branch"): it toggles `[data-dock-overflow]` on the dock root
+ * when the active full layer's over-cap inline content exceeds its clamped port width.
+ * The overflow.css scroll track + FadingScroll edge mask engage ONLY under that attr, so
+ * at rest (fits) the mask is `none` (T-52 a — no 0px-fade shave) and the fisheye is FREE
+ * (fisheye.css gates on `:not([data-dock-overflow])`, the exclusive-mode ruling).
+ *
+ * G9 / O5 — ZERO SCROLL LISTENER. The measure is RESIZE- and CONTENT-driven (a
+ * `ResizeObserver` on the dock + the port, plus a `MutationObserver` on the port's
+ * content). It never listens to `scroll` — the traveling indicator (`useSelectionIndicator`)
+ * lives inside the scroll port and travels WITH scroll in content coordinates, needing no
+ * scroll listener; this fit measure adds none either.
+ *
+ * The scroll port is discovered from the dock root (`.dock-layer--full`) so the composable
+ * needs only the dock element — no extra template ref threads through GlassDock.
+ */
+export declare function useDockOverflowFit(dockEl: Ref<HTMLElement | null>): {
+    measure: () => void;
+};