@n-uf/hypr-tiling 26.7.0

package/dist/tiling-renderer-kTlSm4H4.d.mts

@@ -0,0 +1,2185 @@
+import * as React from 'react';
+
+/**
+ * Per-accent HUE tokens — the raw color atoms a theme composes. Decoupled from
+ * the previous bundled accent theme so a calm theme can borrow an accent's hue
+ * (border/text/ring) WITHOUT inheriting its heavy neon glow, and a refined
+ * theme can pick the softened glow. Every field is a literal Tailwind class so
+ * the JIT emits it.
+ */
+interface TilingAccentHue {
+    /** Human-facing palette label (also the picker swatch label). */
+    readonly label: string;
+    /** Solid background for a palette swatch dot. */
+    readonly swatch: string;
+    /** Resting pane border tint (low alpha). */
+    readonly surfaceBorder: string;
+    /** Resting pane colored drop-shadow tint. */
+    readonly surfaceShadow: string;
+    /** Accent title / metadata text. */
+    readonly text: string;
+    /** Strong accent text used on active chips. */
+    readonly textStrong: string;
+    /** Focused-pane border color. */
+    readonly focusBorder: string;
+    /** Focused-pane focus-ring color. */
+    readonly focusRing: string;
+    /** Full-intensity neon focus glow (box-shadow). */
+    readonly focusGlow: string;
+    /** Dialed-back focus glow for refined / calm themes (box-shadow). */
+    readonly focusGlowSoft: string;
+    /** Active tab/switcher chip border. */
+    readonly tabBorder: string;
+    /** Active tab/switcher chip translucent fill. */
+    readonly tabBg: string;
+    /** Subtle active-tab fill for low-contrast themes. */
+    readonly tabBgSoft: string;
+}
+/** Renderer-root + viewport surfaces. */
+interface TilingThemeRootTokens {
+    /** Outer renderer container: bg/gradient, radius, padding, outline. */
+    readonly container: string;
+    /** Inner viewport (where the pane tree lays out): bg + radius. */
+    readonly viewport: string;
+}
+/** Pane host shell surfaces + interaction-state rings. */
+interface TilingThemePaneShellTokens {
+    /** Pane article shell: bg/gradient, radius, shadow/rim, backdrop-filter. */
+    readonly surface: string;
+    /** Pane body scroll region text color/leading. */
+    readonly bodyText: string;
+    /** Pane subtitle text color. */
+    readonly subtitleText: string;
+    /** Ring on an invalid drop target. */
+    readonly invalidDropRing: string;
+    /** Opacity applied to the drag-source pane while it is picked up. */
+    readonly dragSourceOpacity: string;
+}
+/** Pane header chrome — resting + focused + the per-pane control buttons. */
+interface TilingThemePaneHeaderTokens {
+    /** Resting header bar: border-b, bg, inset sheen. */
+    readonly base: string;
+    /** Additive classes when the pane is focused. */
+    readonly focused: string;
+    /** Pane title base typography (accent color applied separately). */
+    readonly titleText: string;
+    /** Resting header control button (maximize etc.). */
+    readonly controlIdle: string;
+    /** Active/pressed header control button. */
+    readonly controlActive: string;
+    /**
+     * Additive header classes when the pane is part of the Alt/Opt+click
+     * multi-selection set. Deliberately NEUTRAL (no accent) so it never collides
+     * with the accent focus frame — multi-selection and focus are orthogonal
+     * states a pane can hold simultaneously.
+     */
+    readonly selected: string;
+    /**
+     * The small neutral "selected" check affordance rendered in the header of a
+     * multi-selected pane. Neutral tone, distinct from any accent control.
+     */
+    readonly selectedBadge: string;
+}
+/** Drag-ghost shell — the lifted, portaled copy of the dragged pane. */
+interface TilingThemeGhostTokens {
+    /** Ghost article shell (a touch more opaque + deeper shadow than a pane). */
+    readonly surface: string;
+    /** Ghost header bar. */
+    readonly header: string;
+    /** Ghost body text color. */
+    readonly bodyText: string;
+    /** Ghost subtitle text color. */
+    readonly subtitleText: string;
+}
+/** Split-divider / gap handle chrome across visible + hidden states. */
+interface TilingThemeDividerTokens {
+    /** Structural base incl. focus-visible ring color. */
+    readonly base: string;
+    /** Visible + resizable handle (resting + hover). */
+    readonly visibleInteractive: string;
+    /** Visible but resize-disabled handle. */
+    readonly visibleStatic: string;
+    /** Hidden handle (no chrome, hit-area only). */
+    readonly hidden: string;
+}
+/** Top-bar / tab-strip chrome. */
+interface TilingThemeTopBarTokens {
+    /** Tab-strip container: border, bg, shadow, backdrop. */
+    readonly container: string;
+    /** Strip title text. */
+    readonly titleText: string;
+    /** Accent-picker group wrapper. */
+    readonly pickerGroup: string;
+    /** Switcher-control group wrapper (theme picker etc.). */
+    readonly controlGroup: string;
+    /** Tab chip base typography/layout. */
+    readonly tabBase: string;
+    /** Inactive tab chip. */
+    readonly tabInactive: string;
+    /** Centered pane-switcher overlay card. */
+    readonly switcherCard: string;
+    /** Switcher card when the pane is NOT selected. */
+    readonly switcherCardInactive: string;
+}
+/**
+ * A complete theme: the static surface token groups plus the accent-composition
+ * resolvers. The resolvers are the contract for "how per-pane accents compose
+ * with the theme" — each theme decides how much of an accent's hue/glow it
+ * spends on the resting surface, title text, focus frame, and active tab.
+ */
+interface TilingTheme {
+    /**
+     * The theme's id. A built-in theme uses a `TilingThemeId` member; a
+     * consumer-authored theme mints its own id string (the `string & {}`
+     * widening keeps built-in ids autocompletable while admitting any id).
+     * `TILING_THEME_REGISTRY` stays keyed by the closed `TilingThemeId` union,
+     * so the compile-time built-in coverage guarantee is unaffected.
+     */
+    readonly id: TilingThemeId | (string & {});
+    /** Human-readable theme label (e.g. for a theme picker). */
+    readonly label: string;
+    /** Renderer-root + viewport surface tokens. */
+    readonly root: TilingThemeRootTokens;
+    /** Pane host shell surface + interaction-state tokens. */
+    readonly paneShell: TilingThemePaneShellTokens;
+    /** Pane header chrome tokens. */
+    readonly paneHeader: TilingThemePaneHeaderTokens;
+    /** Drag-ghost shell tokens. */
+    readonly ghost: TilingThemeGhostTokens;
+    /** Split-divider / gap handle tokens. */
+    readonly divider: TilingThemeDividerTokens;
+    /** Top-bar / tab-strip chrome tokens. */
+    readonly topBar: TilingThemeTopBarTokens;
+    /** Resting pane accent composition (border tint + colored shadow). */
+    readonly resolvePaneAccentSurface: (accent: TilingTileAccent | undefined) => string;
+    /** Accent title-text color. */
+    readonly resolveAccentText: (accent: TilingTileAccent | undefined) => string;
+    /** Full focused-pane frame (structural border/ring + accent glow). */
+    readonly resolveFocusFrame: (accent: TilingTileAccent | undefined) => string;
+    /** Active tab / switcher / group-member chip. */
+    readonly resolveTabActive: (accent: TilingTileAccent | undefined) => string;
+}
+/** First palette member — the fallback when a tile omits `accent`. */
+declare const DEFAULT_TILE_ACCENT: TilingTileAccent;
+/**
+ * Ordered, enumerable accent palette — the generic capability a consumer
+ * iterates to build an accent picker.
+ */
+declare const TILING_TILE_ACCENTS: readonly TilingTileAccent[];
+/**
+ * The hue atoms for every accent. Keyed by the closed `TilingTileAccent`
+ * union so the compiler enforces full coverage. Theme-independent: themes
+ * choose which atoms to apply.
+ */
+declare const TILING_ACCENT_HUES: Record<TilingTileAccent, TilingAccentHue>;
+/** Picker-ready metadata (accent + label + swatch class) for every accent. */
+declare const TILING_TILE_ACCENT_SWATCHES: readonly TilingTileAccentSwatch[];
+/** Resolve an accent (or the default fallback) to its hue atoms. */
+declare function accentHue(accent: TilingTileAccent | undefined): TilingAccentHue;
+/**
+ * Built-in theme registry, keyed by the closed `TilingThemeId` union. Adding a
+ * member to `TilingThemeId` forces a new entry here (the `Record` fails to
+ * compile until filled in).
+ */
+declare const TILING_THEME_REGISTRY: Record<TilingThemeId, TilingTheme>;
+/** Default library theme id (preserves the prior look at the round-1 checkpoint). */
+declare const DEFAULT_TILING_THEME_ID: TilingThemeId;
+/** Ordered, enumerable theme list — the generic capability a theme switcher iterates. */
+declare const TILING_THEMES: readonly TilingTheme[];
+/** Resolve a theme id (or the default) to its `TilingTheme`. */
+declare function resolveTilingTheme(themeId: TilingThemeId | undefined): TilingTheme;
+/** Provides the active theme to every renderer subcomponent. */
+declare function TilingThemeProvider({ theme, children, }: {
+    theme: TilingTheme;
+    children: React.ReactNode;
+}): React.ReactElement;
+/** Reads the active theme from context (defaults to the library default). */
+declare function useTilingTheme(): TilingTheme;
+
+/**
+ * Orientation of a binary split. `"horizontal"` places its two children
+ * side-by-side (a `flex-row`, resized by a width divider); `"vertical"` stacks
+ * them (a `flex-col`, resized by a height divider).
+ */
+type TilingSplitAxis = "horizontal" | "vertical";
+/**
+ * Arrangement of a split subtree's slots:
+ *
+ * - `"dwindle"` — the default recursive binary-split layout: each split
+ *   distributes its two children along its `axis` by `ratio` (the original and
+ *   only Phase-1/2 algorithm).
+ * - `"master"` — a master-area + stack layout (the Hyprland `master` analog).
+ *   The split's descendant slots (leaves / groups, flattened in reading order)
+ *   are laid out as `masterCount` master tiles in a master area plus the
+ *   remaining tiles in a stack; the split's `ratio` is reused as the master-area
+ *   fraction and `masterOrientation` places the master area. The binary
+ *   structure beneath a master split is flattened (ignored for geometry); it
+ *   still defines slot membership + order + identity, and the reducers still
+ *   operate on it.
+ */
+type TilingLayoutMode = "dwindle" | "master";
+/**
+ * Where the master area sits in `layoutMode: "master"`. `left`/`right` divide
+ * the container along WIDTH (master area a column, members stacked vertically);
+ * `top`/`bottom` divide along HEIGHT (master area a row, members stacked
+ * horizontally). The complement holds the stack.
+ */
+type TilingMasterOrientation = "left" | "right" | "top" | "bottom";
+/** The two layout dimensions a pane can be sized along, independent of split axis. */
+type TilingDimension = "width" | "height";
+/**
+ * Per-dimension sizing mode for a node placed inside a split.
+ *
+ * - `"flexible"` — the node shares space by ratio along the split axis and
+ *   stretches/reflows along the cross axis (the default for every dimension).
+ * - `"static"` — the node is sized to its INTRINSIC/CONTENT extent along that
+ *   dimension; it is excluded from ratio distribution and resize dividers when
+ *   the static dimension runs ALONG the parent split axis, and simply
+ *   content-sizes (no stretch) when the static dimension is the CROSS axis.
+ */
+type TilingPaneSizingMode = "static" | "flexible";
+/**
+ * Per-dimension sizing declaration for a node. Each dimension is independent:
+ * a pane can be static in `height`, in `width`, or in both. An undefined
+ * dimension defaults to `"flexible"`.
+ *
+ * The object shape is chosen over an axis list (e.g. `staticAxes: ("width" |
+ * "height")[]`) because it is explicit per-dimension, self-documenting at the
+ * call site (`sizing: { height: "static" }`), and lets a dimension be stated
+ * `"flexible"` explicitly rather than only inferred from absence.
+ */
+interface TilingPaneSizing {
+    /** Sizing mode for the WIDTH dimension. Undefined → `"flexible"`. */
+    width?: TilingPaneSizingMode;
+    /** Sizing mode for the HEIGHT dimension. Undefined → `"flexible"`. */
+    height?: TilingPaneSizingMode;
+    /**
+     * Pinned WIDTH in CSS px, captured from the pane's measured bounding box at the
+     * moment the user freezes the pane via the title-bar STATIC W / BOTH control.
+     * Only meaningful when `width === "static"`. When present, the static-width
+     * pane renders at exactly this pixel extent (a measured bbox FREEZE) instead of
+     * being content-sized. Undefined → the static dimension is content-sized (the
+     * legacy intrinsic behavior).
+     */
+    widthPx?: number;
+    /**
+     * Pinned HEIGHT in CSS px, captured from the pane's measured bounding box at the
+     * moment the user freezes the pane via the title-bar STATIC H / BOTH control.
+     * Only meaningful when `height === "static"`. See `widthPx`.
+     */
+    heightPx?: number;
+}
+/**
+ * The four title-bar sizing actions a pane offers for ITSELF (no target-pane
+ * indirection — the pane the control lives in is the target):
+ *
+ * - `"flexible"` — clear any pinned dimension and return the pane to ratio
+ *   distribution (FLEX).
+ * - `"static-height"` — freeze the pane's height to its measured bbox px.
+ * - `"static-width"` — freeze the pane's width to its measured bbox px.
+ * - `"static-both"` — freeze both dimensions to the measured bbox.
+ */
+type TilingTitleBarSizingMode = "flexible" | "static-height" | "static-width" | "static-both";
+/**
+ * Resize capability across the two divider orientations.
+ *
+ * RESIZE AXIS CONVENTION (read carefully — the divider orientation and the
+ * resize axis are deliberately the opposite words):
+ *
+ * - A **vertical divider** sits between **side-by-side** panes. Dragging it
+ *   changes their **widths** → this is a **horizontal** resize (x-axis). In the
+ *   layout tree this is a split whose `axis` is `"horizontal"` (a `flex-row`
+ *   container with a `cursor-col-resize` handle).
+ * - A **horizontal divider** sits between **stacked** panes. Dragging it changes
+ *   their **heights** → this is a **vertical** resize (y-axis). In the layout
+ *   tree this is a split whose `axis` is `"vertical"` (a `flex-col` container
+ *   with a `cursor-row-resize` handle).
+ *
+ * The resize-capability token therefore matches the split `axis` token directly:
+ * `"horizontal"` gates width dividers, `"vertical"` gates height dividers.
+ *
+ * - `"both"` — every divider is resizable (this is the "entire" option). Default.
+ * - `"horizontal"` — only width dividers (side-by-side panes) are resizable.
+ * - `"vertical"` — only height dividers (stacked panes) are resizable.
+ * - `"none"` — no divider is resizable.
+ */
+type TilingResizeCapability = "both" | "horizontal" | "vertical" | "none";
+/**
+ * Drag-to-rearrange feedback mode — how a pending move is shown WHILE dragging,
+ * before it is committed on drop.
+ *
+ * - `"preview"` — non-committing preview (default). The pending result is shown
+ *   via the translucent PROJECTED landing overlays (S' / T' / successor) painted
+ *   over the unchanged layout; the layout tree is NOT mutated until drop.
+ * - `"live"` — Hyprland-faithful detach drag. On pickup the dragged source leaf
+ *   is detached and the remaining tree reflows ONCE to close the gap
+ *   (`removeLeafTile`); that frozen provisional tree is held for the whole drag
+ *   (it does NOT re-reflow as the cursor moves). The detached source follows the
+ *   cursor as a ghost, and the drop is resolved + committed exactly ONCE on
+ *   release against the original layout via the SAME resolver + reducers preview
+ *   uses (`swapLeafTiles` / `insertLeafAdjacent`), so the live commit equals the
+ *   preview commit for the same intent. The prop tree is never mutated pre-commit,
+ *   so cancel / Escape / dragleave-abort / off-viewport revert is lossless.
+ *
+ * NOTE on vocabulary: "projected" names the RENDERING TECHNIQUE for the preview
+ * overlays (projected geometry, S' / T' / successor). "preview" vs "live" is the
+ * interaction MODE. The mode is never called "projected".
+ */
+type TilingDragMode = "preview" | "live";
+/**
+ * Live-drag slot re-resolution / commitment policy after the single ghost hops
+ * INTO and FILLS a resolved slot (see
+ * `_agent/single-instance-hop-in-drag-design.md` §8):
+ *
+ * - `"zone-exit-hold"` — anchored / sticky: the seated slot is pinned through
+ *   small cursor movements and re-resolves only when the cursor crosses OUT of
+ *   the seated target's hit footprint (high hysteresis).
+ * - `"delta-responsive"` — DEFAULT: the seated slot re-resolves eagerly once the
+ *   cursor travels beyond `reresolveDeltaPx` from the seat anchor (or exits the
+ *   footprint), so the user can re-aim without fully exiting the pane.
+ *
+ * Only meaningful in `dragMode: "live"`.
+ */
+type TilingSlotCommitmentMode = "zone-exit-hold" | "delta-responsive";
+/**
+ * Live-drag slot-commitment configuration. `mode` selects the re-resolution
+ * policy; `reresolveDeltaPx` is the `delta-responsive` movement threshold (CSS
+ * px) — a coarse "should I re-aim" gate distinct from the fine 6px geometric
+ * zone hysteresis, so the two never double-count.
+ */
+interface TilingSlotCommitmentCapability {
+    /** Re-resolution policy after the ghost seats in a slot. Default `"delta-responsive"`. */
+    mode?: TilingSlotCommitmentMode;
+    /** `delta-responsive` re-aim threshold in CSS px. Default `24`. */
+    reresolveDeltaPx?: number;
+}
+/** Fully-resolved slot-commitment configuration (no optional fields). */
+interface ResolvedTilingSlotCommitmentCapability {
+    /** Resolved re-resolution policy after the ghost seats in a slot. */
+    mode: TilingSlotCommitmentMode;
+    /** Resolved `delta-responsive` re-aim threshold in CSS px. */
+    reresolveDeltaPx: number;
+}
+/**
+ * Touch-drag hardening configuration. The drag FSM runs on Pointer Events, so it
+ * already covers touch uniformly with mouse/pen — this capability tunes the
+ * touch-only choreography that must differ from mouse:
+ *
+ * - `enable` — when `false`, a touch press on the drag handle never starts a
+ *   drag (touch is reserved for tap/scroll); mouse/pen drag is unaffected.
+ *   Default `true`.
+ * - `longPressMs` — how long a finger must be held before the press becomes a
+ *   drag pickup (the tap/scroll-vs-drag disambiguator). A pre-long-press
+ *   scroll-axis flick releases to the page; mouse/pen skip this delay entirely.
+ *   Default `220`.
+ */
+interface TilingTouchDragCapability {
+    /** Allow touch pointers to start a drag. Default `true`. */
+    enable?: boolean;
+    /** Long-press delay (ms) before a held touch becomes a drag. Default `220`. */
+    longPressMs?: number;
+}
+/** Fully-resolved touch-drag configuration (no optional fields). */
+interface ResolvedTilingTouchDragCapability {
+    /** Resolved touch-drag enable flag. */
+    enable: boolean;
+    /** Resolved long-press delay (ms) before a held touch becomes a drag. */
+    longPressMs: number;
+}
+/**
+ * Drag / transition self-healing recovery configuration. Hardens the live-drag
+ * ANIMATION + TIMING layer (not the FSM, which is already un-wedgeable) against
+ * frame starvation — background-tab `requestAnimationFrame` suspension, CPU
+ * throttling, long tasks, dropped/late pointer events, interrupted transitions.
+ * The recovery primitives live in `drag-recovery.ts`; this is their typed knob
+ * surface. All deadlines are documented multiples of the animation duration or
+ * of a frame, never symptom-tuned constants. Only meaningful in
+ * `dragMode: "live"`.
+ *
+ * - `enable` — master gate for the recovery layer (idle watchdog +
+ *   rAF-with-timeout arming + idempotent style teardown). Default `true`.
+ * - `maxDraggingIdleMs` — the drag idle-watchdog deadline: `armed` / `dragging`
+ *   with no `POINTER_MOVE` / `TARGET_RESOLVED` progress for longer than this
+ *   (measured MONOTONICALLY, so throttle-robust) force-reconciles to `idle` via
+ *   the existing `POINTER_CANCEL` edge with pointer capture released. Default
+ *   `30 × BASELINE_DRAG_HOP_DURATION_MS ≈ 5100ms`.
+ * - `frameDeadlineMs` — the rAF-fallback slack: each FLIP "play-to-identity"
+ *   write is armed as a `requestAnimationFrame` racing a `setTimeout` of this
+ *   long, first-wins + idempotent, so a starved frame never leaves an element
+ *   frozen at its inverted `First`. Default `~2 frames ≈ 32ms`.
+ * - `transitionSlackMs` — the transition-completion slack: style cleanup fires
+ *   on `transitionend` OR `duration + transitionSlackMs`, whichever first.
+ *   Default `60ms` (names the existing `+60` mask-close slack).
+ */
+interface TilingDragRecoveryCapability {
+    /** Enable the self-healing recovery layer. Default `true`. */
+    enable?: boolean;
+    /** Idle-watchdog deadline (ms). Default `30 × BASELINE_DRAG_HOP_DURATION_MS ≈ 5100`. */
+    maxDraggingIdleMs?: number;
+    /** rAF-fallback slack (ms). Default `~2 frames ≈ 32`. */
+    frameDeadlineMs?: number;
+    /** Transition-completion slack (ms). Default `60`. */
+    transitionSlackMs?: number;
+}
+/** Fully-resolved drag-recovery configuration (no optional fields). */
+interface ResolvedTilingDragRecoveryCapability {
+    /** Resolved self-healing recovery enable flag. */
+    enable: boolean;
+    /** Resolved idle-watchdog deadline (ms). */
+    maxDraggingIdleMs: number;
+    /** Resolved rAF-fallback slack (ms). */
+    frameDeadlineMs: number;
+    /** Resolved transition-completion slack (ms). */
+    transitionSlackMs: number;
+}
+/**
+ * A single keyboard chord: a PHYSICAL `KeyboardEvent.code` value plus the
+ * modifier state required to match it. Absent modifiers resolve to `false` (the
+ * modifier must NOT be held) — a chord fully specifies its modifier requirements.
+ *
+ * The chord matches on `event.code` (the physical key, e.g. `"Enter"`,
+ * `"Escape"`, `"BracketLeft"`, `"BracketRight"`), NOT `event.key` (the produced
+ * character). This is mandatory on macOS, where holding Option(Alt) rewrites
+ * `event.key` into dead-key glyphs (Option+`]` → `"‘"`, Option+digits → special
+ * glyphs), so a `event.key`-based comparison never matches. `event.code` is
+ * stable across keyboard layouts and modifier state.
+ */
+interface TilingKeyChord {
+    /** Matches `KeyboardEvent.code` (e.g. `"Enter"`, `"Escape"`, `"BracketLeft"`, `"BracketRight"`, `"Digit1"`). */
+    code: string;
+    /** Require the Alt key. Default `false`. */
+    alt?: boolean;
+    /** Require the Ctrl key. Default `false`. */
+    ctrl?: boolean;
+    /** Require the Meta (Cmd / Win) key. Default `false`. */
+    meta?: boolean;
+    /** Require the Shift key. Default `false`. */
+    shift?: boolean;
+}
+/**
+ * Modifier requirements for the jump-to-pane digit family (`Alt+1`..`Alt+9`).
+ * The `1`..`9` digit is implied (matched against the physical `Digit1`..`Digit9`
+ * codes); only the modifier state is configurable.
+ */
+interface TilingKeyChordModifiers {
+    /** Require the Alt key. Default `false`. */
+    alt?: boolean;
+    /** Require the Ctrl key. Default `false`. */
+    ctrl?: boolean;
+    /** Require the Meta (Cmd / Win) key. Default `false`. */
+    meta?: boolean;
+    /** Require the Shift key. Default `false`. */
+    shift?: boolean;
+}
+/**
+ * Public, reactive keymap. Every field is optional; an `undefined` field
+ * resolves to its documented default via `resolveKeymap`. Action-level merge:
+ * supplying one binding leaves the others at their defaults.
+ */
+interface TilingKeymap {
+    /** Toggle maximize on the focused pane. Default `Alt+Enter` (code `Enter`). */
+    toggleMaximize?: TilingKeyChord;
+    /** Restore from maximize. Default `Escape`. */
+    restore?: TilingKeyChord;
+    /** Cycle to the previous pane. Default `Alt+[`. */
+    previousPane?: TilingKeyChord;
+    /** Cycle to the next pane. Default `Alt+]`. */
+    nextPane?: TilingKeyChord;
+    /** Modifier set for the `Alt+1`..`Alt+9` jump family. Default `Alt`. */
+    jumpToPane?: TilingKeyChordModifiers;
+    /** Move focus to the geometric neighbor on the LEFT. Default bare `ArrowLeft`. */
+    focusLeft?: TilingKeyChord;
+    /** Move focus to the geometric neighbor on the RIGHT. Default bare `ArrowRight`. */
+    focusRight?: TilingKeyChord;
+    /** Move focus to the geometric neighbor ABOVE. Default bare `ArrowUp`. */
+    focusUp?: TilingKeyChord;
+    /** Move focus to the geometric neighbor BELOW. Default bare `ArrowDown`. */
+    focusDown?: TilingKeyChord;
+    /**
+     * Enter keyboard MOVE MODE on the focused pane (the keyboard analog of a drag
+     * pickup). Default `Alt+M` (code `KeyM`). While in move mode the focus arrows
+     * pick a destination, `Enter` commits the relocation (`insertLeafAdjacent`),
+     * and `Escape` cancels. Only meaningful when `rearrange` is enabled.
+     */
+    enterMoveMode?: TilingKeyChord;
+    /**
+     * Toggle focus between the current pane and the most-recently-focused other
+     * pane (the MRU "focus current-or-last" toggle; Hyprland `focuscurrentorlast`
+     * analog). Default `Alt+\`` (code `Backquote`). Only meaningful when `focus`
+     * is enabled.
+     */
+    focusCurrentOrLast?: TilingKeyChord;
+    /**
+     * Toggle the focused subtree's layout mode dwindle ⇄ master (the Hyprland
+     * layout-toggle analog). Default `Alt+L` (code `KeyL`). Only meaningful when
+     * `masterLayout` is enabled.
+     */
+    cycleLayoutMode?: TilingKeyChord;
+    /**
+     * Cycle the master-area orientation left → top → right → bottom → left.
+     * Default `Alt+Shift+O` (code `KeyO` + Shift). Bare `Alt+O` is avoided
+     * because Chrome/Edge on Windows/Linux reserve it for the browser menu.
+     * Switches to master layout mode automatically when invoked from dwindle.
+     */
+    cycleMasterOrientation?: TilingKeyChord;
+    /** Add one tile to the master area (`+1` master count). Default `Alt+=` (code `Equal`). */
+    incrementMasterCount?: TilingKeyChord;
+    /** Remove one tile from the master area (`-1` master count). Default `Alt+-` (code `Minus`). */
+    decrementMasterCount?: TilingKeyChord;
+    /** Grow the master-area fraction (`+0.05` ratio). Default `Alt+.` (code `Period`). */
+    incrementMasterRatio?: TilingKeyChord;
+    /** Shrink the master-area fraction (`-0.05` ratio). Default `Alt+,` (code `Comma`). */
+    decrementMasterRatio?: TilingKeyChord;
+    /**
+     * Toggle grouping for the focused pane: group it with its reading-order
+     * neighbor, or ungroup it if already grouped (the Hyprland `togglegroup`
+     * analog). Default `Alt+G` (code `KeyG`). Only meaningful when `grouping`
+     * is enabled.
+     */
+    toggleGroup?: TilingKeyChord;
+    /** Activate the next member tab of the focused group. Default `Alt+K` (code `KeyK`). */
+    groupTabNext?: TilingKeyChord;
+    /** Activate the previous member tab of the focused group. Default `Alt+J` (code `KeyJ`). */
+    groupTabPrevious?: TilingKeyChord;
+}
+/** Fully-resolved key chord (every modifier explicit). Matches `KeyboardEvent.code`. */
+interface ResolvedTilingKeyChord {
+    /** Physical `KeyboardEvent.code` this chord matches. */
+    code: string;
+    /** Whether the Alt key must be held. */
+    alt: boolean;
+    /** Whether the Ctrl key must be held. */
+    ctrl: boolean;
+    /** Whether the Meta (Cmd / Win) key must be held. */
+    meta: boolean;
+    /** Whether the Shift key must be held. */
+    shift: boolean;
+}
+/** Fully-resolved jump-to-pane modifier set. */
+interface ResolvedTilingKeyChordModifiers {
+    /** Whether the Alt key must be held. */
+    alt: boolean;
+    /** Whether the Ctrl key must be held. */
+    ctrl: boolean;
+    /** Whether the Meta (Cmd / Win) key must be held. */
+    meta: boolean;
+    /** Whether the Shift key must be held. */
+    shift: boolean;
+}
+/** Fully-resolved keymap (no optional fields). */
+interface ResolvedTilingKeymap {
+    /** Resolved chord to toggle maximize on the focused pane. */
+    toggleMaximize: ResolvedTilingKeyChord;
+    /** Resolved chord to restore from maximize. */
+    restore: ResolvedTilingKeyChord;
+    /** Resolved chord to cycle to the previous pane. */
+    previousPane: ResolvedTilingKeyChord;
+    /** Resolved chord to cycle to the next pane. */
+    nextPane: ResolvedTilingKeyChord;
+    /** Resolved modifier set for the `Alt+1`..`Alt+9` jump family. */
+    jumpToPane: ResolvedTilingKeyChordModifiers;
+    /** Resolved chord to move focus to the LEFT neighbor. */
+    focusLeft: ResolvedTilingKeyChord;
+    /** Resolved chord to move focus to the RIGHT neighbor. */
+    focusRight: ResolvedTilingKeyChord;
+    /** Resolved chord to move focus to the neighbor ABOVE. */
+    focusUp: ResolvedTilingKeyChord;
+    /** Resolved chord to move focus to the neighbor BELOW. */
+    focusDown: ResolvedTilingKeyChord;
+    /** Resolved chord to enter keyboard move mode. */
+    enterMoveMode: ResolvedTilingKeyChord;
+    /** Resolved chord for the MRU focus current-or-last toggle. */
+    focusCurrentOrLast: ResolvedTilingKeyChord;
+    /** Resolved chord to toggle the focused subtree dwindle ⇄ master. */
+    cycleLayoutMode: ResolvedTilingKeyChord;
+    /** Resolved chord to cycle the master-area orientation. */
+    cycleMasterOrientation: ResolvedTilingKeyChord;
+    /** Resolved chord to add one tile to the master area. */
+    incrementMasterCount: ResolvedTilingKeyChord;
+    /** Resolved chord to remove one tile from the master area. */
+    decrementMasterCount: ResolvedTilingKeyChord;
+    /** Resolved chord to grow the master-area fraction. */
+    incrementMasterRatio: ResolvedTilingKeyChord;
+    /** Resolved chord to shrink the master-area fraction. */
+    decrementMasterRatio: ResolvedTilingKeyChord;
+    /** Resolved chord to group/ungroup the focused pane. */
+    toggleGroup: ResolvedTilingKeyChord;
+    /** Resolved chord to activate the next member tab of the focused group. */
+    groupTabNext: ResolvedTilingKeyChord;
+    /** Resolved chord to activate the previous member tab of the focused group. */
+    groupTabPrevious: ResolvedTilingKeyChord;
+}
+/**
+ * A keyboard-event shape sufficient for pure keymap matching. Matching keys off
+ * the physical `code`; `key` is retained only for form-field / diagnostic use
+ * and is NOT consulted by `matchKeyChord` / `matchJumpToPaneNumber`.
+ */
+interface TilingKeyboardEventLike {
+    /** Physical `KeyboardEvent.code` (the key that matching consults). */
+    code: string;
+    /** Produced `KeyboardEvent.key` glyph; diagnostic only, never matched. */
+    key: string;
+    /** Whether the Alt key was held. */
+    altKey: boolean;
+    /** Whether the Ctrl key was held. */
+    ctrlKey: boolean;
+    /** Whether the Meta (Cmd / Win) key was held. */
+    metaKey: boolean;
+    /** Whether the Shift key was held. */
+    shiftKey: boolean;
+}
+/**
+ * The subset of modifier flags needed to decide whether a held-modifier switch
+ * flow (the macOS Cmd+Tab-style pane switcher) should commit on key release.
+ */
+interface TilingKeyboardModifierState {
+    /** Whether the Alt key is held. */
+    altKey: boolean;
+    /** Whether the Ctrl key is held. */
+    ctrlKey: boolean;
+    /** Whether the Meta (Cmd / Win) key is held. */
+    metaKey: boolean;
+    /** Whether the Shift key is held. */
+    shiftKey: boolean;
+}
+/** Discriminated logical keyboard actions resolved from a key event. */
+type TilingKeyboardAction = {
+    kind: "toggle-maximize";
+} | {
+    kind: "restore";
+} | {
+    kind: "previous-pane";
+} | {
+    kind: "next-pane";
+} | {
+    kind: "jump-to-pane";
+    paneNumber: number;
+} | {
+    kind: "focus-direction";
+    direction: TilingFocusDirection;
+} | {
+    kind: "focus-current-or-last";
+} | {
+    kind: "enter-move-mode";
+} | {
+    kind: "cycle-layout-mode";
+} | {
+    kind: "cycle-master-orientation";
+} | {
+    kind: "adjust-master-count";
+    delta: number;
+} | {
+    kind: "adjust-master-ratio";
+    delta: number;
+} | {
+    kind: "toggle-group";
+} | {
+    kind: "group-tab-cycle";
+    direction: TilingPaneCycleDirection;
+};
+/** Pane cycle direction for the reading-order ring (next / previous, wraparound). */
+type TilingPaneCycleDirection = "next" | "previous";
+/**
+ * The public, typed, dispatch-style command set — the public API's imperative
+ * entry point (the Hyprland `dispatch` analog). Every internal renderer action is
+ * enumerated here so an embedding app can invoke tiler behavior programmatically
+ * (via the `TilingCommandHandle`) and so a keyboard binding can target any of
+ * them (`TilingKeyBinding`).
+ *
+ * Context-dependent commands carry an OPTIONAL `leafId`; when omitted the
+ * renderer resolves it against the CURRENT focused leaf at dispatch time (the
+ * "act on the focused pane" ergonomic). Commands that need explicit operands
+ * (swap / insert / split ops) require them.
+ */
+type TilingCommand = {
+    kind: "focus-pane";
+    leafId: string;
+} | {
+    kind: "focus-direction";
+    direction: TilingFocusDirection;
+} | {
+    kind: "focus-cycle";
+    direction: TilingPaneCycleDirection;
+} | {
+    kind: "focus-jump";
+    paneNumber: number;
+} | {
+    kind: "focus-current-or-last";
+} | {
+    kind: "toggle-maximize";
+    leafId?: string;
+} | {
+    kind: "maximize";
+    leafId?: string;
+} | {
+    kind: "restore";
+} | {
+    kind: "enter-move-mode";
+    leafId?: string;
+} | {
+    kind: "move-aim";
+    direction: TilingFocusDirection;
+} | {
+    kind: "commit-move-mode";
+} | {
+    kind: "cancel-move-mode";
+} | {
+    kind: "swap-panes";
+    sourceLeafId: string;
+    targetLeafId: string;
+} | {
+    kind: "insert-adjacent";
+    sourceLeafId: string;
+    targetLeafId: string;
+    placement: TilingMovePlacement;
+} | {
+    kind: "acquire-space";
+    leafId?: string;
+    direction: TilingFocusDirection;
+} | {
+    kind: "set-sizing";
+    leafId?: string;
+    mode: TilingTitleBarSizingMode;
+} | {
+    kind: "set-split-ratio";
+    splitId: string;
+    ratio: number;
+} | {
+    kind: "toggle-split-axis";
+    splitId: string;
+} | {
+    kind: "set-layout-mode";
+    splitId?: string;
+    mode: TilingLayoutMode;
+} | {
+    kind: "cycle-layout-mode";
+    splitId?: string;
+} | {
+    kind: "set-master-count";
+    splitId?: string;
+    count: number;
+} | {
+    kind: "adjust-master-count";
+    splitId?: string;
+    delta: number;
+} | {
+    kind: "set-master-orientation";
+    splitId?: string;
+    orientation: TilingMasterOrientation;
+} | {
+    kind: "cycle-master-orientation";
+    splitId?: string;
+} | {
+    kind: "adjust-master-ratio";
+    splitId?: string;
+    delta: number;
+} | {
+    kind: "group-leaves";
+    leafIds: ReadonlyArray<string>;
+    hostLeafId?: string;
+} | {
+    kind: "toggle-group";
+    leafId?: string;
+} | {
+    kind: "ungroup";
+    groupId?: string;
+} | {
+    kind: "add-to-group";
+    groupId: string;
+    sourceLeafId: string;
+} | {
+    kind: "remove-from-group";
+    groupId: string;
+    memberId: string;
+} | {
+    kind: "group-tab-cycle";
+    groupId?: string;
+    direction: TilingPaneCycleDirection;
+} | {
+    kind: "group-tab-jump";
+    groupId?: string;
+    memberNumber: number;
+};
+/**
+ * The imperative handle exposed via `ref` on `TilingRenderer`. A consumer
+ * holds the ref and drives the tiler programmatically — `dispatch` routes a
+ * command through the SAME internal router the keyboard layer uses, so a
+ * disabled-capability command is a safe no-op (it never mutates the layout).
+ */
+interface TilingCommandHandle {
+    /** Route a {@link TilingCommand} through the renderer's command router. */
+    dispatch: (command: TilingCommand) => void;
+}
+/**
+ * A single keyboard binding: an arbitrary chord mapped to an arbitrary command.
+ * The public chord→command registration surface (the Hyprland `bind` analog),
+ * distinct from the fixed `TilingKeymap` chord overrides (which only re-chord
+ * the built-in action set). The chord matches on `KeyboardEvent.code` exactly
+ * like `TilingKeyChord`.
+ */
+interface TilingKeyBinding {
+    /** The chord that triggers this binding (matched on `KeyboardEvent.code`). */
+    chord: TilingKeyChord;
+    /** The command dispatched when the chord matches. */
+    command: TilingCommand;
+}
+/**
+ * Consumer keyboard-binding registry. `bindings` augment (and, on a chord
+ * collision, override) the default keymap bindings; setting `replaceDefaults`
+ * suppresses the built-in keymap path entirely so ONLY these bindings are live.
+ */
+interface TilingKeyBindings {
+    /** Consumer chord→command bindings; augment (or override on collision) the defaults. */
+    bindings?: ReadonlyArray<TilingKeyBinding>;
+    /** When `true`, the default keymap bindings are NOT consulted. Default `false` (augment). */
+    replaceDefaults?: boolean;
+}
+/**
+ * Maximize (expand-to-viewport) capability. The maximize render-mode is
+ * non-destructive — it hides sibling panes and renders the focused pane filling
+ * the tiling viewport without mutating the layout tree.
+ */
+interface TilingMaximizeCapability {
+    /** Enable the per-pane maximize/restore control + shortcuts. Default `true`. */
+    enable?: boolean;
+    /**
+     * Per-capability keybinding overrides for `toggleMaximize` / `restore`. These
+     * take precedence over the top-level `keymap`, which takes precedence over the
+     * documented defaults.
+     */
+    keymap?: Pick<TilingKeymap, "toggleMaximize" | "restore">;
+}
+/**
+ * Tab-like pane-switching capability. Renders a tab strip across the top of the
+ * tiling region and binds the cycle / jump shortcuts. When maximized, switching
+ * panes also switches which pane is maximized.
+ */
+interface TilingPaneSwitchingCapability {
+    /** Enable pane switching (tab strip + cycle/jump shortcuts). Default `true`. */
+    enable?: boolean;
+    /**
+     * Render the TOP-LEVEL tab strip (the single strip across the top of the
+     * tiling region listing every pane). Default `true`. The cycle/jump shortcuts
+     * work regardless. This flag does NOT govern the per-group tab strip a
+     * tabbed-stacking group renders above its active member — that strip is
+     * governed by `grouping.showGroupTabStrip` (see
+     * {@link TilingGroupingCapability}).
+     */
+    showTabStrip?: boolean;
+    /**
+     * Render the tab strip's pane-content visibility checkbox (the "content"
+     * toggle that flips the default-tile body between content and empty). Default
+     * `true`. Set `false` to suppress the control for embeddings that always paint
+     * their own content via a custom `renderTile` (e.g. a docs/SEO surface), where
+     * the toggle is inert chrome. Suppressing the toggle hands content ownership to
+     * the embedding: pane-content is treated as VISIBLE by default
+     * (`isPaneContentVisible` initializes `true`) for ALL drag surfaces — in-tree
+     * panes, the source slot, the hop-in slot, and the portaled drag ghost — so the
+     * ghost body matches the seated body. With no control rendered, the flag cannot
+     * be flipped off, so this default holds for the lifetime of the embedding.
+     * (Ghost-seat reservation slots still render empty — that is a drag mechanic
+     * resolved by `resolvePaneBodyRenderMode`, independent of this flag.)
+     */
+    showContentToggle?: boolean;
+    /**
+     * Render the macOS Cmd+Tab-style visual switcher overlay while cycling panes
+     * with a held modifier (`Alt+]` / `Alt+[`). Default `true`. When `true`, a
+     * cycle press opens a centered overlay listing the panes and advances the
+     * highlight; the selection commits (focus / activate, and switch the maximized
+     * pane when maximized) on modifier release, and `Escape` cancels. When
+     * `false`, cycle presses activate the next/previous pane immediately (no
+     * overlay). The shortcuts work regardless of this flag.
+     */
+    showSwitcherOverlay?: boolean;
+    /**
+     * Toggle a pane's maximize/restore state when its TAB in the tab strip is
+     * double-clicked. Default `true`. The double-click dispatches the SAME
+     * `toggle-maximize` command (targeting the tab's leaf) the `Alt+Enter`
+     * keybinding dispatches, so the two converge on one maximize state — a
+     * double-click maximizes, a second double-click (or `Alt+Enter`, or `Escape`)
+     * restores. Single-click tab activation is unaffected. Also gated by the
+     * `maximize` capability: with `maximize.enable: false` the double-click is a
+     * no-op even when this is `true`. Set `false` to opt out (single-click tab
+     * activation only).
+     */
+    tabDoubleClickMaximize?: boolean;
+    /**
+     * Alt/Opt+click a pane HEADER to toggle that pane into a multi-selection set,
+     * then group the selected panes into one flat tabbed group via the existing
+     * `group-leaves` command (the same chord family as the `Alt+G` group key).
+     * Default `true`. A plain (no-modifier) header click keeps its normal
+     * focus/drag-pickup behavior; only `altKey` (Opt on macOS, Alt on
+     * Windows/Linux) presses participate in multi-selection. When `≥2`
+     * groupable panes are selected, a "Group" control appears in each selected
+     * pane's header; clicking it dispatches `group-leaves` (the clicked pane is the
+     * host slot) and clears the selection. The selection also clears on Escape, on
+     * a drag pickup, and on a plain click that establishes a single focus. When
+     * `false`, Alt/Opt+click and the Group control are no-ops. The grouping itself
+     * is independently gated by
+     * the `grouping` capability — with grouping disabled the Group control is
+     * suppressed (the multi-select dispatch is a safe no-op).
+     */
+    multiSelectGrouping?: boolean;
+    /**
+     * Per-capability keybinding overrides for `previousPane` / `nextPane` /
+     * `jumpToPane`. These take precedence over the top-level `keymap`.
+     */
+    keymap?: Pick<TilingKeymap, "previousPane" | "nextPane" | "jumpToPane">;
+}
+/**
+ * Per-pane TITLE-BAR control capability. These controls render directly in each
+ * pane's own header (next to maximize), so they target THAT pane (no central
+ * target-pane selector). Two independent control groups:
+ *
+ * - `sizing` — the FLEX / STATIC H / STATIC W / BOTH segmented control. STATIC
+ *   actions measure the pane's current rendered bbox and pin the chosen
+ *   dimension(s) to that pixel value; FLEX clears the pin.
+ * - `acquireSpace` — the four directional (→ ← ↑ ↓) "grow to claim space"
+ *   buttons, driven by the `growLeafToward` reducer.
+ */
+interface TilingPaneTitleBarControlsCapability {
+    /** Render the per-pane FLEX / STATIC H / STATIC W / BOTH sizing control. Default `true`. */
+    sizing?: boolean;
+    /** Render the per-pane directional (→ ← ↑ ↓) acquire-space controls. Default `true`. */
+    acquireSpace?: boolean;
+}
+/** Resolved per-pane title-bar control capability (no optional fields). */
+interface ResolvedTilingPaneTitleBarControlsCapability {
+    /** Whether the per-pane FLEX / STATIC H / STATIC W / BOTH sizing control renders. */
+    sizing: boolean;
+    /** Whether the per-pane directional acquire-space controls render. */
+    acquireSpace: boolean;
+}
+/** Resolved maximize capability (no optional fields). */
+interface ResolvedTilingMaximizeCapability {
+    /** Whether the maximize/restore control + shortcuts are live. */
+    enable: boolean;
+}
+/** Resolved pane-switching capability (no optional fields). */
+interface ResolvedTilingPaneSwitchingCapability {
+    /** Whether pane switching (tab strip + cycle/jump shortcuts) is live. */
+    enable: boolean;
+    /** Whether the tab strip renders. */
+    showTabStrip: boolean;
+    /** Whether the tab strip's pane-content visibility checkbox renders. */
+    showContentToggle: boolean;
+    /** Whether the Cmd+Tab-style switcher overlay renders while cycling. */
+    showSwitcherOverlay: boolean;
+    /** Whether double-clicking a tab toggles that pane's maximize state. */
+    tabDoubleClickMaximize: boolean;
+    /** Whether Alt/Opt+click header multi-selection grouping is live. */
+    multiSelectGrouping: boolean;
+}
+/**
+ * In-flight state of the macOS Cmd+Tab-style pane switcher. Present only while
+ * the operator is mid-cycle (a held-modifier switch flow is open). `null` =
+ * not switching.
+ *
+ * - `selectedLeafId` — the pane the highlight currently rests on; commit
+ *   activates it.
+ * - `holdModifiers` — the modifier set captured from the chord that opened the
+ *   switcher; the switch commits when any of these modifiers is released (so a
+ *   custom non-Alt cycle binding still commits on release of its own modifier).
+ */
+interface TilingPaneSwitcherState {
+    /** The pane the highlight currently rests on; commit activates it. */
+    selectedLeafId: string;
+    /** Modifier set captured from the opening chord; commit fires on their release. */
+    holdModifiers: ResolvedTilingKeyChordModifiers;
+}
+/**
+ * In-flight state of keyboard MOVE MODE — the keyboard analog of a drag pickup,
+ * present only while the operator is relocating a pane by keyboard. `null` =
+ * not in move mode.
+ *
+ * - `sourceLeafId` — the pane being moved (the keyboard "drag source").
+ * - `targetLeafId` — the destination neighbor chosen by the last focus-arrow
+ *   press (`findLeafByDirection` from the source), or `null` before any arrow.
+ * - `placement` — which edge of the target the source lands on when committed
+ *   (`insertLeafAdjacent`), derived from the arrow direction, or `null` before
+ *   any arrow. Commit is a no-op when either is `null`.
+ */
+interface TilingMoveModeState {
+    /** The pane being moved (the keyboard "drag source"). */
+    sourceLeafId: string;
+    /** Destination neighbor chosen by the last focus-arrow press, or `null` before any arrow. */
+    targetLeafId: string | null;
+    /** Edge of the target the source lands on when committed, or `null` before any arrow. */
+    placement: TilingMovePlacement | null;
+}
+/**
+ * Adjustable drag-drop HIT-ZONE GEOMETRY. These knobs shape the five-region
+ * partition every pane uses to map a cursor position to a drop intent: one
+ * central SWAP rectangle plus four directional INSERT trapezoids (top / right /
+ * bottom / left) formed by the diagonals from each pane corner to the nearest
+ * center-rectangle corner (see `drop-intent-resolver.ts`). The partition tiles
+ * the full pane with no gaps; the same geometry drives both resolution and the
+ * visual overlay, so the drawn zone is exactly the resolved zone.
+ *
+ * The model is SYMMETRIC: a single `centerRatio` sizes the center rectangle on
+ * BOTH axes, which means the directional edge band depth is fully derived from
+ * it as `(1 - centerRatio) / 2` per axis (there is no independent edge-band
+ * knob, and no separate horizontal/vertical asymmetry — the diagonal-trapezoid
+ * construction uses one ratio). CORNERS are not a distinct zone: a corner
+ * resolves to whichever edge trapezoid contains it, with a deterministic
+ * tie-break order (top → right → bottom → left) on an exact diagonal.
+ *
+ * Every field is optional; an `undefined` field resolves to the documented
+ * default (which equals today's `TILING_DROP_INTENT_CONFIG`), so omitting this
+ * object leaves drop-zone behavior exactly as it was.
+ */
+interface TilingDropHitZoneGeometryCapability {
+    /**
+     * Fraction of each pane axis spanned by the central SWAP rectangle. The
+     * directional INSERT edge band depth is the complement, `(1 - centerRatio) /
+     * 2`. Clamped to `[0.05, 0.95]` by the resolver. Default `0.34`. Acts as the
+     * SYMMETRIC convenience: it sets BOTH axes unless a per-axis override
+     * (`centerRatioX` / `centerRatioY`) is supplied for that axis.
+     */
+    centerRatio?: number;
+    /**
+     * Per-axis HORIZONTAL (width) swap-zone fraction override. When set, it sizes
+     * the center rectangle's X extent independently of `centerRatio`, letting a
+     * non-square pane carry an axis-specific swap-zone proportion. Falls back to
+     * `centerRatio` then the default `0.34`. Clamped to `[0.05, 0.95]`.
+     */
+    centerRatioX?: number;
+    /**
+     * Per-axis VERTICAL (height) swap-zone fraction override. When set, it sizes
+     * the center rectangle's Y extent independently of `centerRatio`. Falls back
+     * to `centerRatio` then the default `0.34`. Clamped to `[0.05, 0.95]`.
+     */
+    centerRatioY?: number;
+    /**
+     * Floor (CSS px) for the center rectangle's extent on each axis so tiny panes
+     * keep a usable swap target even when `width * centerRatio` would collapse it.
+     * Default `24`.
+     */
+    centerMinPx?: number;
+    /**
+     * Boundary stickiness (pane-local CSS px): once the cursor is in a zone it
+     * must cross the boundary by this much before the classification switches,
+     * suppressing sub-pixel flicker at the trapezoid edges. `0` disables
+     * hysteresis. Default `6`.
+     */
+    hysteresisPx?: number;
+}
+/**
+ * Fully-resolved drop hit-zone geometry (no optional fields). `centerRatio` is
+ * retained as the symmetric/representative value (equals `centerRatioX` when no
+ * per-axis override diverges them) for telemetry + the single-knob showcase
+ * display; `centerRatioX` / `centerRatioY` are the per-axis values the resolver
+ * actually consumes.
+ */
+interface ResolvedTilingDropHitZoneGeometryCapability {
+    /** Resolved symmetric/representative center swap-zone fraction. */
+    centerRatio: number;
+    /** Resolved per-axis HORIZONTAL swap-zone fraction the resolver consumes. */
+    centerRatioX: number;
+    /** Resolved per-axis VERTICAL swap-zone fraction the resolver consumes. */
+    centerRatioY: number;
+    /** Resolved floor (CSS px) for the center rectangle extent. */
+    centerMinPx: number;
+    /** Resolved boundary stickiness (pane-local CSS px). */
+    hysteresisPx: number;
+}
+/**
+ * Public, reactive interaction-capability flags for the tiling renderer. All
+ * fields are optional; an `undefined` field (or an `undefined` config object)
+ * resolves to the all-enabled default via `resolveInteractionCapabilities`.
+ */
+interface TilingInteractionCapabilities {
+    /** Divider resize capability. Default `"both"` (every divider resizable). */
+    resize?: TilingResizeCapability;
+    /**
+     * Whether split-divider resize handles are visibly rendered. `false` hides
+     * handle chrome (separator paint / hover affordance) while preserving the
+     * divider hit-target and resize capability gating from `resize`.
+     * Default `false`.
+     */
+    resizeHandlesVisible?: boolean;
+    /**
+     * Live-drag slot hop-in. Selects between the two drag-presentation behaviors
+     * for the dragged pane:
+     *
+     * - `true` (default, ORIGINAL): the single content-honoring ghost HOPS INTO
+     *   and FILLS the resolved slot — the seat rect is measured so the ghost seats
+     *   as the single instance and no separate empty reservation lingers beside a
+     *   free-following ghost.
+     * - `false` (the seat-measurement is deliberately skipped): the ghost
+     *   free-follows the cursor and the in-tree content-less reservation slot stays
+     *   shown — the reservation-plus-ghost duality.
+     *
+     * Orthogonal to the CONTENT toggle: in BOTH modes the pane body honors content
+     * uniformly (see `resolvePaneBodyRenderMode`). Only meaningful in
+     * `dragMode: "live"`. Default `true`.
+     */
+    slotHopInEnabled?: boolean;
+    /**
+     * Drag-to-rearrange (move / swap / edge-insert) capability. When `false`,
+     * panes are not draggable and no drop overlays / hit-zones activate.
+     * Default `true`.
+     */
+    rearrange?: boolean;
+    /**
+     * Drag-to-rearrange feedback mode: `"preview"` (non-committing projected
+     * overlays) vs `"live"` (Hyprland detach: source detached on pickup, frozen
+     * tree, cursor-following ghost, commit on release). Default `"live"` (the
+     * resolved default in `TILING_INTERACTION_CAPABILITY_DEFAULTS`).
+     * Only meaningful when `rearrange` is enabled; live mode is also unreachable
+     * for static-pane layouts (drag-rearrange is auto-gated off there).
+     */
+    dragMode?: TilingDragMode;
+    /**
+     * Live-drag slot re-resolution / commitment policy (the single ghost hops INTO
+     * and FILLS the resolved slot). Only meaningful in `dragMode: "live"`. Default
+     * all-resolved (`mode: "delta-responsive"`, `reresolveDeltaPx: 24`).
+     */
+    slotCommitment?: TilingSlotCommitmentCapability;
+    /**
+     * Touch-drag hardening (touch enable + long-press disambiguation). Only
+     * meaningful when `rearrange` is enabled. Default all-resolved
+     * (`enable: true`, `longPressMs: 220`).
+     */
+    touchDrag?: TilingTouchDragCapability;
+    /**
+     * Drag / transition self-healing recovery (idle watchdog + rAF-with-timeout
+     * animation arming + idempotent transient-style teardown). Hardens the
+     * live-drag animation/timing layer against frame starvation. Only meaningful
+     * in `dragMode: "live"`. Default all-resolved (`enable: true`,
+     * `maxDraggingIdleMs ≈ 5100`, `frameDeadlineMs ≈ 32`, `transitionSlackMs: 60`).
+     */
+    dragRecovery?: TilingDragRecoveryCapability;
+    /**
+     * Custom-rendered drag cursor (interaction tier "c"). When `true` (default),
+     * an active live drag hides the OS cursor (`cursor: none` on the tiling root)
+     * and renders a transform-pinned cursor element that follows the pointer and
+     * reflects the drag FSM + drop validity (neutral grab / directional arrow /
+     * swap / blocked). When `false`, the native OS cursor is used during drag.
+     * Only meaningful in `dragMode: "live"`.
+     */
+    customCursor?: boolean;
+    /**
+     * Ghost pickup scale as a percent of the source pane's full bbox. On drag
+     * start the live-mode ghost animates from the source pane's full bbox to this
+     * fraction of it; values <100% read as lifted/shrunk. The free-following ghost
+     * rests at this scale and morphs toward the resolved slot's bbox on hop-in.
+     * Range `[10, 150]`; clamped where consumed. Default `90`. Only meaningful in
+     * `dragMode: "live"`; skipped under `prefers-reduced-motion`.
+     */
+    ghostPickupScalePercent?: number;
+    /**
+     * Coherent non-intersecting transit. When `true` (default), the moving source
+     * ghost and the displaced target never visually OVERLAP mid-transition: on a
+     * SWAP both moving boxes scale down toward ~70% mid-transit (best-effort) then
+     * scale back into place, coordinated with the survivor reflow so even if their
+     * paths cross the shrunk boxes do not collide. Trivial / no-op for edge-insert
+     * (the boxes never trade places). Only meaningful in `dragMode: "live"`;
+     * skipped under `prefers-reduced-motion`.
+     */
+    coherentTransit?: boolean;
+    /** Pane focus selection. When `false`, focus selection is suppressed. Default `true`. */
+    focus?: boolean;
+    /** Maximize-to-viewport capability. Default all-enabled. */
+    maximize?: TilingMaximizeCapability;
+    /** Tab-like pane-switching capability. Default all-enabled. */
+    paneSwitching?: TilingPaneSwitchingCapability;
+    /**
+     * Per-pane title-bar controls (in-header sizing + acquire-space). Default
+     * all-enabled. Reactive: toggling a flag at runtime shows/hides the controls
+     * without remount.
+     */
+    paneTitleBarControls?: TilingPaneTitleBarControlsCapability;
+    /**
+     * Adjustable drag-drop hit-zone geometry (center swap fraction, center floor,
+     * boundary hysteresis). Undefined → today's `TILING_DROP_INTENT_CONFIG`
+     * defaults. Reactive: changing it at runtime re-shapes the drop zones (and
+     * their visual overlay) immediately.
+     */
+    dropHitZoneGeometry?: TilingDropHitZoneGeometryCapability;
+    /**
+     * Top-level keymap. Capability-level `keymap` overrides take precedence over
+     * this; this takes precedence over the documented defaults.
+     */
+    keymap?: TilingKeymap;
+    /**
+     * Public chord→command binding registry. Consumer bindings augment (and on a
+     * chord collision override) the default keymap bindings; set
+     * `replaceDefaults` to drop the built-in keymap path entirely. Undefined → the
+     * default keymap bindings only.
+     */
+    keyBindings?: TilingKeyBindings;
+    /**
+     * Master/stack layout engine (HT-LAYOUT-MASTER-STACK). When `true` (default),
+     * the layout-mode + master commands (`cycle-layout-mode`,
+     * `adjust-master-count`, `cycle-master-orientation`, `adjust-master-ratio`, …)
+     * and their default keybindings are live, and a subtree set to
+     * `layoutMode: "master"` renders as a master area + stack. When `false`, those
+     * commands are no-ops (a `master`-mode tree still renders via the resolver, but
+     * the operator cannot change the mode/params). Default `true`.
+     */
+    masterLayout?: boolean;
+    /**
+     * Group / tabbed-stacking (HT-GROUP-TABBED-STACKING). A bare boolean is
+     * shorthand for `{ enable }`; the object form additionally governs the
+     * per-group tab strip via `showGroupTabStrip` (see
+     * {@link TilingGroupingCapability}). Default `true` (grouping enabled, strip
+     * rendered).
+     */
+    grouping?: boolean | TilingGroupingCapability;
+}
+/**
+ * Group / tabbed-stacking capability (HT-GROUP-TABBED-STACKING), the object
+ * form of the `grouping` capability. A bare boolean at the `grouping` slot is
+ * shorthand for `{ enable }`.
+ */
+interface TilingGroupingCapability {
+    /**
+     * Enable grouping. When `true` (default), the grouping commands
+     * (`toggle-group`, `ungroup`, `add-to-group`, `group-tab-cycle`,
+     * `group-tab-jump`, `group-leaves`) and their default keybindings are live,
+     * and drag-onto-a-group's-tab-strip merges into the group. When `false`,
+     * those commands are no-ops and drag-into-group is disabled (an existing
+     * group still renders per this capability's `showGroupTabStrip`).
+     */
+    enable?: boolean;
+    /**
+     * Render the per-group tab strip (the member tabs a tabbed-stacking group
+     * paints above its active member). Default `true`. When `false`, the strip
+     * is suppressed and the group renders only its active member; the keyboard
+     * group commands (`group-tab-cycle`, `group-tab-jump`, `remove-from-group`,
+     * `ungroup`) keep working, so a consumer that hides the strip can paint its
+     * own group chrome and route it through the same commands. Note:
+     * drag-onto-the-strip group merge requires a mounted strip, so hiding the
+     * strip also removes that drop target. Distinct from
+     * `paneSwitching.showTabStrip`, which governs the TOP-LEVEL tab strip only.
+     */
+    showGroupTabStrip?: boolean;
+}
+/** Resolved group / tabbed-stacking capability (no optional fields). */
+interface ResolvedTilingGroupingCapability {
+    /** Whether group / tabbed-stacking is enabled. */
+    enable: boolean;
+    /** Whether the per-group tab strip renders. */
+    showGroupTabStrip: boolean;
+}
+/**
+ * Fully-resolved interaction capabilities (no optional fields). The resolved
+ * shape is a structural superset of `TilingInteractionCapabilities`, so a
+ * resolved object can be re-fed to `resolveInteractionCapabilities` (idempotent)
+ * and passed straight back into the `interaction` prop.
+ */
+interface ResolvedTilingInteractionCapabilities {
+    /** Resolved divider resize capability. */
+    resize: TilingResizeCapability;
+    /** Whether split-divider resize handles are visibly rendered. */
+    resizeHandlesVisible: boolean;
+    /** Whether the single ghost hops into and fills the resolved slot. */
+    slotHopInEnabled: boolean;
+    /** Whether drag-to-rearrange is enabled. */
+    rearrange: boolean;
+    /** Resolved drag feedback mode (`"preview"` vs `"live"`). */
+    dragMode: TilingDragMode;
+    /** Resolved live-drag slot-commitment configuration. */
+    slotCommitment: ResolvedTilingSlotCommitmentCapability;
+    /** Resolved touch-drag hardening configuration. */
+    touchDrag: ResolvedTilingTouchDragCapability;
+    /** Resolved drag/transition self-healing recovery configuration. */
+    dragRecovery: ResolvedTilingDragRecoveryCapability;
+    /** Whether the custom-rendered drag cursor is used during live drag. */
+    customCursor: boolean;
+    /** Resolved ghost pickup scale as a percent of the source pane bbox. */
+    ghostPickupScalePercent: number;
+    /** Whether coherent non-intersecting transit is enabled. */
+    coherentTransit: boolean;
+    /** Whether pane focus selection is enabled. */
+    focus: boolean;
+    /** Resolved maximize-to-viewport capability. */
+    maximize: ResolvedTilingMaximizeCapability;
+    /** Resolved tab-like pane-switching capability. */
+    paneSwitching: ResolvedTilingPaneSwitchingCapability;
+    /** Resolved per-pane title-bar controls capability. */
+    paneTitleBarControls: ResolvedTilingPaneTitleBarControlsCapability;
+    /** Resolved adjustable drop hit-zone geometry. */
+    dropHitZoneGeometry: ResolvedTilingDropHitZoneGeometryCapability;
+    /** Resolved keymap (every chord explicit). */
+    keymap: ResolvedTilingKeymap;
+    /**
+     * Resolved consumer key bindings (the raw registry passed through; an empty
+     * binding list + `replaceDefaults: false` when omitted). The renderer matches
+     * these before the default keymap path.
+     */
+    keyBindings: ResolvedTilingKeyBindings;
+    /** Whether the master/stack layout engine is enabled. */
+    masterLayout: boolean;
+    /** Resolved group / tabbed-stacking capability. */
+    grouping: ResolvedTilingGroupingCapability;
+}
+/** Fully-resolved key-binding registry (no optional fields). */
+interface ResolvedTilingKeyBindings {
+    /** Resolved consumer chord→command bindings (empty when none supplied). */
+    bindings: ReadonlyArray<TilingKeyBinding>;
+    /** Whether the default keymap bindings are suppressed. */
+    replaceDefaults: boolean;
+}
+/**
+ * Per-pane identity accent. A closed, typed palette so a consumer can drive a
+ * picker from the enumerable `TILING_TILE_ACCENTS` list (exported from the
+ * renderer) with exhaustive type-checking — adding a member here forces every
+ * accent theme map to cover it.
+ */
+type TilingTileAccent = "cyan" | "sky" | "violet" | "indigo" | "emerald" | "amber" | "rose" | "pink";
+/**
+ * Closed set of built-in visual theme ids for the renderer. A theme bundles the
+ * class-string tokens for every surface (pane shell, header, focus frame,
+ * ghost, dividers, root, tab strip) plus the accent-composition resolvers. The
+ * token interfaces + registry live in `./theme`; this union is the central
+ * contract a consumer types its `themeId` state against.
+ */
+type TilingThemeId = "neon-terminal" | "clean-flat" | "mosaic";
+/**
+ * A pickable accent paired with a human label and a solid Tailwind background
+ * class for rendering a swatch dot — the generic metadata a palette control
+ * (e.g. the showcase top-bar picker) iterates to offer accent selection.
+ */
+interface TilingTileAccentSwatch {
+    /** The accent this swatch selects. */
+    accent: TilingTileAccent;
+    /** Human-readable label for the swatch (e.g. in a picker). */
+    label: string;
+    /** Tailwind background class rendering the solid swatch dot. */
+    swatchClassName: string;
+}
+/**
+ * Generic tile payload. Only `id` + `title` are required so a product consumer
+ * (e.g. a dashboard) can supply a minimal `{ id, title, content }` tile and a
+ * custom `renderTile`. The `accent` / `rows` fields drive `DefaultTilingTile`
+ * and the drag-pane snapshot chrome; when omitted they fall back (accent →
+ * `"cyan"`, rows → `[]`), so a tile without them renders correctly under the
+ * default tile surface. `content` is the slot a custom `renderTile` reads.
+ */
+interface TilingTile {
+    /** Stable tile identity; leaf nodes reference a tile by this `id`. */
+    id: string;
+    /** Title shown in the pane header / tab. */
+    title: string;
+    /** Optional one-line description surfaced by the default tile chrome. */
+    description?: string;
+    /** Optional per-tile identity accent. Falls back to `"cyan"` when omitted. */
+    accent?: TilingTileAccent;
+    /** Optional text rows for the default tile body. Falls back to `[]`. */
+    rows?: ReadonlyArray<string>;
+    /** Rich body a custom `renderTile` reads (and the drag ghost paints). */
+    content?: React.ReactNode;
+}
+/**
+ * A leaf slot: a single pane that renders one tile. The renderer's smallest
+ * addressable layout unit — focus, drag, resize, and sizing all target a leaf
+ * by its `id`.
+ */
+interface TilingLeafNode {
+    /** Node discriminant. Always `"leaf"`. */
+    kind: "leaf";
+    /** Stable node identity, unique within the layout tree. */
+    id: string;
+    /** The `TilingTile.id` this leaf renders. */
+    tileId: string;
+    /** Per-dimension static/flexible sizing. Undefined dimensions are flexible. */
+    sizing?: TilingPaneSizing;
+}
+/**
+ * A binary split node: divides its region between two child subtrees along
+ * `axis` by `ratio`. In `layoutMode: "master"` the binary structure defines
+ * slot membership/order while the master resolver drives geometry.
+ */
+interface TilingSplitNode {
+    /** Node discriminant. Always `"split"`. */
+    kind: "split";
+    /** Stable node identity, unique within the layout tree. */
+    id: string;
+    /** Split orientation (`"horizontal"` = side-by-side, `"vertical"` = stacked). */
+    axis: TilingSplitAxis;
+    /** Fraction `[0, 1]` of the region allotted to `first` along `axis`. */
+    ratio: number;
+    /** The first (top/left) child subtree. */
+    first: TilingLayoutNode;
+    /** The second (bottom/right) child subtree. */
+    second: TilingLayoutNode;
+    /** Optional per-split gap override (CSS px) between the two children. */
+    gapPx?: number;
+    /** Optional per-split minimum pane extent (CSS px) enforced on resize. */
+    minPaneSizePx?: number;
+    /** Per-dimension static/flexible sizing. Undefined dimensions are flexible. */
+    sizing?: TilingPaneSizing;
+    /**
+     * Arrangement of this subtree's slots. Undefined → `"dwindle"` (the binary
+     * split layout — every hand-authored tree + the test baseline is unchanged).
+     * `"master"` lays the subtree's descendant slots out as master area + stack.
+     */
+    layoutMode?: TilingLayoutMode;
+    /**
+     * `layoutMode: "master"` only — number of slots in the master area. Undefined
+     * → `1`. Clamped to `[1, slotCount]` by the resolver / reducers.
+     */
+    masterCount?: number;
+    /**
+     * `layoutMode: "master"` only — where the master area sits. Undefined →
+     * `"left"`. In master mode the split's `ratio` is reused as the master-area
+     * fraction along this orientation's primary axis.
+     */
+    masterOrientation?: TilingMasterOrientation;
+}
+/**
+ * A group/member slot (HT-GROUP-TABBED-STACKING): N leaves share ONE layout slot
+ * as a stacked group with a tab strip — only `activeMemberId` renders / is
+ * hit-tested, the tabs switch the active member. A group is a SLOT (like a leaf),
+ * so a slot in either dwindle or master layout can hold a group. Members are
+ * leaves only (no nested split/group — a group of one is degenerate and collapses
+ * back to a bare leaf).
+ */
+interface TilingGroupNode {
+    /** Node discriminant. Always `"group"`. */
+    kind: "group";
+    /** Stable node identity, unique within the layout tree. */
+    id: string;
+    /** ≥1 member; array order is the tab order. */
+    members: ReadonlyArray<TilingLeafNode>;
+    /** Always one of `members[].id` — the single rendered/hit-tested member. */
+    activeMemberId: string;
+    /** A group can be static like a leaf (per-dimension static/flexible sizing). */
+    sizing?: TilingPaneSizing;
+}
+/**
+ * A node in the layout tree: a leaf (single pane), a split (two subtrees), or a
+ * group (tabbed leaves in one slot). The recursive union you own in state and
+ * feed to `TilingRenderer` via the `layout` prop.
+ */
+type TilingLayoutNode = TilingLeafNode | TilingSplitNode | TilingGroupNode;
+/** Global geometry configuration for the renderer (the `config` prop). */
+interface TilingLayoutConfig {
+    /** Gap (CSS px) painted in the gutters between panes. */
+    gapPx: number;
+    /** Minimum pane extent (CSS px) a resize divider will not shrink a pane below. */
+    minPaneSizePx: number;
+    /** Resize-handle hit-target thickness (CSS px). */
+    handleSizePx: number;
+}
+/**
+ * The renderer surface a `renderTile` invocation paints:
+ *
+ * - `"pane"` — the seated in-tree pane (the normal, interactive case).
+ * - `"drag-ghost"` — the floating, portaled pickup ghost that travels with the
+ *   cursor during a drag. `aria-hidden` + `pointer-events-none`: handlers are
+ *   inert no-ops, capability display flags stay real.
+ * - `"drag-cancel"` — the cancel fly-back overlay (the ghost gliding home after
+ *   a cancelled drag). Same inert-handlers / real-flags semantics as
+ *   `"drag-ghost"`.
+ */
+type TilingRenderSurface = "pane" | "drag-ghost" | "drag-cancel";
+/**
+ * One member of a tabbed group, as seen by a custom `renderTile` through
+ * {@link TilingRenderTileGroupContext.members}. Mirrors what the built-in
+ * group tab strip paints per tab: the member's identity, its resolved tile
+ * payload, its 1-based position (the `group-tab-jump` operand — also the
+ * keyboard `Alt+<n>` label), and whether it is the active (rendered) member.
+ */
+interface TilingGroupMemberView {
+    /** The member's leaf node id. */
+    readonly leafId: string;
+    /** The tile id the member's leaf points at. */
+    readonly tileId: string;
+    /** The resolved tile payload, or `null` when the tile map has no match. */
+    readonly tile: TilingTile | null;
+    /**
+     * 1-based position in the group's member order — the operand
+     * {@link TilingRenderTileGroupContext.activateMember} takes (and the number
+     * the built-in strip / keyboard `Alt+<n>` jump display).
+     */
+    readonly memberNumber: number;
+    /** Whether this member is the group's active (rendered) member. */
+    readonly isActive: boolean;
+}
+/**
+ * Group context on {@link TilingRenderTileProps.group}: present when the pane
+ * being rendered is a tabbed group's ACTIVE member (the only member that
+ * renders, per the stacking contract), `null` for loose leaves and for the
+ * drag-ghost / drag-cancel surfaces. A custom pane uses it to paint its own
+ * group chrome (tabs, member list, eject/ungroup controls) instead of the
+ * built-in strip — typically with the strip suppressed via the `grouping`
+ * capability's `showGroupTabStrip: false`.
+ *
+ * The callbacks route through the SAME internal command router the built-in
+ * strip and the keyboard layer use (`group-tab-jump` / `remove-from-group` /
+ * `ungroup`), so capability gating and observability stay uniform.
+ */
+interface TilingRenderTileGroupContext {
+    /** The group node id. */
+    readonly groupId: string;
+    /** The group's members in member order (see {@link TilingGroupMemberView}). */
+    readonly members: ReadonlyArray<TilingGroupMemberView>;
+    /**
+     * Activate the member at `memberNumber` (1-based; a
+     * {@link TilingGroupMemberView.memberNumber}) — dispatches `group-tab-jump`.
+     */
+    readonly activateMember: (memberNumber: number) => void;
+    /**
+     * Eject the member with `leafId` from the group (it re-seats as a loose
+     * pane) — dispatches `remove-from-group`.
+     */
+    readonly removeMember: (leafId: string) => void;
+    /** Dissolve the whole group into loose panes — dispatches `ungroup`. */
+    readonly ungroup: () => void;
+}
+/**
+ * The argument object passed to a custom `renderTile`. This is the clean,
+ * consumer-facing pane contract: the tile payload, this pane's derived state
+ * (focus / drag / drop / sizing), and the imperative callbacks a custom pane
+ * surface wires to its header, drag handle, and controls. Every field is
+ * something a custom pane legitimately reads to style itself or wires to drive
+ * an interaction — nothing here is a debug, observability, or showcase concern
+ * (those live on the internal render path and the `/devtools` surface).
+ *
+ * @remarks
+ * A minimal custom pane needs only three wiring rules, each of which the
+ * optional public helper primitives ({@link TilingPaneRoot},
+ * {@link TilingDragHandle}, {@link TilingPaneAction}, {@link TilingPaneBody})
+ * encode so they cannot be gotten wrong:
+ * - the pane root must carry `data-leaf-id={leafId}` (the renderer resolves the
+ *   drag source through the `[data-leaf-id]` attribute) and wire `onFocus`,
+ *   `onPointerMove`, `onPointerLeave`;
+ * - the drag handle wires `onHandlePointerDown` with `touch-action: none`;
+ * - header action buttons must `stopPropagation` on pointer-down + click so a
+ *   click does not start a drag or steal focus;
+ * - the body renders only when `paneBodyRenderMode === "render-content"` (the
+ *   drag ghost reuses the same render path).
+ */
+interface TilingRenderTileProps {
+    /**
+     * Which renderer surface these args paint (see {@link TilingRenderSurface}).
+     * `"pane"` for the seated in-tree pane; `"drag-ghost"` for the floating
+     * pickup ghost that follows the cursor; `"drag-cancel"` for the cancel
+     * fly-back overlay. On the two drag surfaces every interaction handler is an
+     * inert no-op while the capability display flags stay REAL (reflecting the
+     * resolved capabilities), so capability-keyed chrome does not vanish
+     * mid-drag; a custom pane that wants different drag chrome branches on this
+     * discriminator.
+     */
+    readonly surface: TilingRenderSurface;
+    /** The leaf node id this render targets. */
+    leafId: string;
+    /** The resolved tile payload for this leaf. */
+    tile: TilingTile;
+    /** 1-based pane ordinal in current tab order (for generic pane labels). */
+    paneOrdinal: number;
+    /** Current pane viewport width in pixels (for responsive header/control density). */
+    paneWidthPx: number;
+    /**
+     * Global pane-content visibility toggle from the tab strip checkbox.
+     * `false` hides pane body content by default.
+     */
+    isPaneContentVisible: boolean;
+    /**
+     * Canonical pane-body visibility decision resolved by the renderer policy.
+     * Keeps custom tile renderers aligned with the default drag/hidden semantics.
+     */
+    paneBodyRenderMode: TilingPaneBodyRenderMode;
+    /** Whether this pane is the source of the in-flight drag. */
+    isDragSource: boolean;
+    /** Whether this pane is the resolved drop target of the in-flight drag. */
+    isDropTarget: boolean;
+    /** Whether this pane is a valid drop destination for the current drag. */
+    isDropEligible: boolean;
+    /** Whether the cursor is currently hovering this pane as a drop candidate. */
+    isHoveringDropCandidate: boolean;
+    /** Whether the current hover over this pane would be an invalid drop. */
+    isInvalidDrop: boolean;
+    /** Whether this pane currently holds focus. */
+    isFocused: boolean;
+    /** Whether drag-to-rearrange is enabled (drives handle affordance). */
+    isRearrangeEnabled: boolean;
+    /**
+     * Whether this pane is the SOURCE of an in-flight keyboard move (the keyboard
+     * analog of a drag source). Drives the "MOVING" affordance.
+     */
+    isMoveSource: boolean;
+    /**
+     * When this pane is the pending move-mode DESTINATION, the edge of this pane
+     * the moved source will land on (`insertLeafAdjacent` placement). `null` when
+     * this pane is not the current move-mode target.
+     */
+    moveTargetPlacement: TilingMovePlacement | null;
+    /** Whether this pane is currently maximized (fills the tiling viewport). */
+    isMaximized: boolean;
+    /** Whether the maximize capability is enabled (controls header button visibility). */
+    isMaximizeEnabled: boolean;
+    /** Toggle maximize/restore for this pane. */
+    onToggleMaximize: () => void;
+    /** Whether the per-pane title-bar sizing control (FLEX / STATIC H / STATIC W / BOTH) is enabled. */
+    isTitleBarSizingEnabled: boolean;
+    /** Whether the per-pane title-bar directional acquire-space controls (→ ← ↑ ↓) are enabled. */
+    isTitleBarAcquireSpaceEnabled: boolean;
+    /** This pane's current WIDTH sizing mode (static/flexible) — drives the active control state. */
+    widthSizingMode: TilingPaneSizingMode;
+    /** This pane's current HEIGHT sizing mode (static/flexible) — drives the active control state. */
+    heightSizingMode: TilingPaneSizingMode;
+    /**
+     * Set THIS pane's sizing mode. STATIC modes measure the pane's current bbox
+     * (getBoundingClientRect on its `[data-leaf-id]` element) and pin the chosen
+     * dimension(s) to that pixel value; FLEX clears the pin and returns the pane
+     * to ratio distribution. Emits via `onLayoutChange` (controlled).
+     */
+    onSetSizingMode: (mode: TilingTitleBarSizingMode) => void;
+    /**
+     * Grow THIS pane to claim the maximum available space in `direction` by
+     * pushing matching-axis ancestor dividers toward the limit (siblings clamped
+     * to their minimum). Emits via `onLayoutChange` (controlled).
+     */
+    onAcquireSpace: (direction: TilingFocusDirection) => void;
+    /** The resolved drop zone under the cursor for this pane, or `null`. */
+    dropZone: TilingLeafDropZone | null;
+    /** The projected landing/result preview for this pane, or `null`. */
+    preview: TilingLeafDropPreview | null;
+    /**
+     * Group context when this pane is a tabbed group's ACTIVE member (the only
+     * member that renders, per the stacking contract); `null` for loose leaves
+     * and on the `"drag-ghost"` / `"drag-cancel"` surfaces. See
+     * {@link TilingRenderTileGroupContext}.
+     */
+    readonly group: TilingRenderTileGroupContext | null;
+    /**
+     * Establish single focus on this pane (and clear any in-progress
+     * multi-selection). Wire to the pane root's `onFocus`. The renderer reads the
+     * focus event's `target`: when a multi-selection is active and focus landed on
+     * a header CONTROL button (Group / maximize), it is a no-op, so a click on the
+     * Group button is not nullified by the button stealing focus first.
+     */
+    onFocus: (event?: React.SyntheticEvent<HTMLElement>) => void;
+    /**
+     * Whether the Alt/Opt+click header multi-selection feature is live
+     * (`paneSwitching.multiSelectGrouping` AND the `grouping` capability). When
+     * `false`, the header click handler must treat a modified click as a plain
+     * click and never render the Group control.
+     */
+    isMultiSelectGroupingEnabled: boolean;
+    /** Whether THIS pane is currently a member of the multi-selection set. */
+    isMultiSelected: boolean;
+    /**
+     * Whether the current multi-selection (`≥2` panes) can be folded into one
+     * flat group right now — i.e. `group-leaves` would change the layout. Any mix
+     * of loose panes and/or existing-group members flattens into ONE group (groups
+     * the selection touches are dissolved and their members folded in). Drives
+     * whether the Group control is offered; `false` hides it rather than offering a
+     * no-op (e.g. the selection is already exactly one group).
+     */
+    canGroupMultiSelection: boolean;
+    /**
+     * Toggle THIS pane in/out of the multi-selection set. Wire to an
+     * Alt/Opt+click on the pane header. Does not change focus.
+     */
+    onToggleMultiSelect: () => void;
+    /**
+     * Group the current multi-selection into ONE flat tabbed group occupying the
+     * CLICKED pane's slot (pass this pane's `leafId`), then clear the selection.
+     * The clicked pane becomes the host (active tab); any existing group in the
+     * selection is dissolved and folded in. Wire to the Group control.
+     */
+    onGroupMultiSelection: (clickedLeafId: string) => void;
+    /**
+     * Pointer-Events drag pickup on the pane's drag handle (the title-bar grip).
+     * Wire this to the handle's `onPointerDown`; the renderer arms the drag FSM,
+     * crosses the pickup threshold, and takes pointer capture on a stable element
+     * so reflow moving panes under the cursor can never lose or hijack the drag.
+     * Replaces the former HTML5 `draggable` + `onDragStart`/`onDragEnd` plumbing.
+     */
+    onHandlePointerDown: (event: React.PointerEvent<HTMLElement>) => void;
+    /** Pre-drag hover telemetry (drop-intent hit-log); inert while a drag is in flight. */
+    onPointerMove: (event: React.PointerEvent<HTMLElement>) => void;
+    /** Clears this pane's hover telemetry when the pointer leaves it. */
+    onPointerLeave: (event: React.PointerEvent<HTMLElement>) => void;
+}
+/** The five drop regions of a pane: a central swap zone plus four insert edges. */
+type TilingLeafDropZone = "center" | "left" | "right" | "top" | "bottom";
+/**
+ * Resolved pane-body render decision:
+ * - `"render-content"` — paint the tile body,
+ * - `"render-empty"` — hidden body (content toggle off),
+ * - `"render-reservation"` — empty ghost-seat reservation slot during a drag.
+ */
+type TilingPaneBodyRenderMode = "render-content" | "render-empty" | "render-reservation";
+/** Which edge of a target pane an inserted/moved pane lands on. */
+type TilingMovePlacement = "left" | "right" | "top" | "bottom";
+/** A directional focus / move target relative to the current pane. */
+type TilingFocusDirection = "left" | "right" | "up" | "down";
+/** Which side of a preview a shadow represents (drag source vs drop target). */
+type TilingLeafPreviewRole = "drag-source-landing-shadow" | "drop-target-result-shadow";
+/** Whether a preview depicts a swap or an edge-insert result. */
+type TilingLeafPreviewMode = "swap" | "edge-insert";
+/**
+ * The outcome a drop resolves to: exchange tiles (`"swap"`), insert at an edge
+ * (`"edge-insert"`), insert into an existing split container
+ * (`"split-container-insert"`), merge into a tabbed group (`"group-merge"`), or
+ * no valid action (`"none"`).
+ */
+type TilingDropAction = "swap" | "edge-insert" | "split-container-insert" | "group-merge" | "none";
+/** Snapshot of the tuning knobs that shaped a drop-intent resolution. */
+interface TilingDropIntentTuningState {
+    /** Symmetric center swap-zone fraction in effect. */
+    centerRatio: number;
+    /** Edge threshold fraction derived from the center ratio. */
+    edgeThresholdRatio: number;
+    /** Boundary stickiness (pane-local CSS px) in effect. */
+    hysteresisPx: number;
+    /** `window.devicePixelRatio` the geometry snapped to. */
+    devicePixelRatio: number;
+}
+/** Full diagnostic snapshot of a single drop-intent resolution (observability). */
+interface TilingDropIntentDebugState {
+    /** The hovered leaf this resolution targets. */
+    leafId: string;
+    /** The resolved drop zone under the cursor. */
+    zone: TilingLeafDropZone;
+    /** The resolved drop action. */
+    action: TilingDropAction;
+    /** The nearest edge the cursor points toward (pre-fallback). */
+    dominantEdge: Exclude<TilingLeafDropZone, "center">;
+    /** The edge finally selected after fallbacks, or `null`. */
+    finalEdge: Exclude<TilingLeafDropZone, "center"> | null;
+    /** Why the dominant edge was replaced by a fallback, or `null`. */
+    fallbackReason: string | null;
+    /** Why the action was blocked, or `null` when unblocked. */
+    blockedReason: string | null;
+    /** Split axes from the root to the target, describing the containment path. */
+    axisPath: ReadonlyArray<TilingSplitAxis>;
+    /** Edge threshold fraction in effect. */
+    edgeThresholdRatio: number;
+    /** Center rectangle width (CSS px), or `null` when unmeasured. */
+    centerRectWidthPx: number | null;
+    /** Center rectangle height (CSS px), or `null` when unmeasured. */
+    centerRectHeightPx: number | null;
+    /** Cursor distance to the center rectangle (CSS px), or `null`. */
+    centerDistancePx: number | null;
+    /** Cursor distance to the nearest edge (CSS px), or `null`. */
+    nearestEdgeDistancePx: number | null;
+    /** Pane-local cursor X (CSS px), or `null`. */
+    paneLocalX: number | null;
+    /** Pane-local cursor Y (CSS px), or `null`. */
+    paneLocalY: number | null;
+    /** The ancestor split chosen for a split-container insert, or `null`. */
+    targetSplitId: string | null;
+    /** Which child slot of that split the insert targets, or `null`. */
+    targetSplitPlacement: "first" | "second" | null;
+    /** The edge zone selected on the chosen split, or `null`. */
+    selectedSplitZone: Exclude<TilingLeafDropZone, "center"> | null;
+    /** Cursor distance to the selected split edge (CSS px), or `null`. */
+    selectedSplitDistancePx: number | null;
+    /** Reasons candidate splits were rejected during resolution. */
+    rejectedSplitReasons: ReadonlyArray<string>;
+    /** The tuning knobs that shaped this resolution. */
+    tuning: TilingDropIntentTuningState;
+}
+/** Per-edge validity diagnostic for the live drag hit-log. */
+interface TilingLiveHitEdgeDebugState {
+    /** The edge zone this diagnostic describes. */
+    zone: Exclude<TilingLeafDropZone, "center">;
+    /** Whether an insert on this edge is currently valid. */
+    isValid: boolean;
+    /** Why the edge was rejected, or `null` when valid. */
+    rejectionReason: string | null;
+}
+/** A cursor position in viewport (client) coordinates. */
+interface TilingViewportCursorState {
+    /** Client X (CSS px). */
+    x: number;
+    /** Client Y (CSS px). */
+    y: number;
+}
+/**
+ * Live drag/hover hit-log snapshot streamed via `onLiveHitLogChange` — the
+ * observability feed the `/devtools` panel renders. `null` when there is no
+ * active hover/drag.
+ */
+interface TilingLiveHitLogState {
+    /** The leaf currently under the cursor. */
+    hoveredLeafId: string;
+    /** The pre-drag hover source leaf, or `null`. */
+    sourceLeafId: string | null;
+    /** The in-flight drag source leaf, or `null` when not dragging. */
+    dragSourceLeafId: string | null;
+    /** Current cursor position (client coords). */
+    cursorViewport: TilingViewportCursorState;
+    /** Measured footprint of the hover source pane, or `null`. */
+    sourcePaneFootprint: TilingPaneFootprint | null;
+    /** Measured footprint of the drag source pane, or `null`. */
+    dragSourcePaneFootprint: TilingPaneFootprint | null;
+    /** Whether a drag is currently in flight. */
+    isDragging: boolean;
+    /** The resolver's zone under the cursor, or `"none"`. */
+    resolverZone: TilingLeafDropZone | "none";
+    /** Symmetric center swap-zone fraction in effect. */
+    centerRatio: number;
+    /** Edge threshold fraction in effect. */
+    edgeThresholdRatio: number;
+    /** Center rectangle width (CSS px). */
+    centerRectWidthPx: number;
+    /** Center rectangle height (CSS px). */
+    centerRectHeightPx: number;
+    /** Whether the center (swap) zone is currently a valid target. */
+    centerIsValid: boolean;
+    /** Why the center zone is blocked, or `null`. */
+    centerBlockedReason: string | null;
+    /** Per-edge validity diagnostics for the four insert edges. */
+    edgeDiagnostics: ReadonlyArray<TilingLiveHitEdgeDebugState>;
+    /** The full resolved drop-intent snapshot, or `null`. */
+    intent: TilingDropIntentDebugState | null;
+    /** Leaf whose in-tree slot the ghost seats into (swap target or edge-insert source). */
+    ghostSeatLeafId?: string | null;
+    /** Resolved drop action for the active hover target (observability). */
+    presentationDropAction?: TilingDropAction | null;
+}
+/** Per-edge validity candidate for the pane hit-zone overlay. */
+interface TilingPaneHitZoneCandidateDebugState {
+    /** The edge zone this candidate describes. */
+    zone: Exclude<TilingLeafDropZone, "center">;
+    /** Whether an insert on this edge is currently valid. */
+    isValid: boolean;
+    /** Why the edge was rejected, or `null` when valid. */
+    rejectionReason: string | null;
+}
+/** Per-pane hit-zone overlay state driving the five-region debug visualization. */
+interface TilingPaneHitZoneOverlayDebugState {
+    /** The leaf this overlay is drawn over. */
+    leafId: string;
+    /** The active drag source leaf, or `null`. */
+    dragSourceLeafId: string | null;
+    /** Symmetric center swap-zone fraction. */
+    centerRatio: number;
+    /** Per-axis HORIZONTAL swap-zone fraction (drives the X clip-path boundaries). */
+    centerRatioX: number;
+    /** Per-axis VERTICAL swap-zone fraction (drives the Y clip-path boundaries). */
+    centerRatioY: number;
+    /** Center rectangle width (CSS px). */
+    centerRectWidthPx: number;
+    /** Center rectangle height (CSS px). */
+    centerRectHeightPx: number;
+    /** Whether the center (swap) zone is a valid target. */
+    centerIsValid: boolean;
+    /** Why the center zone is blocked, or `null`. */
+    centerBlockedReason: string | null;
+    /** Per-edge validity candidates for the four insert edges. */
+    edgeCandidates: ReadonlyArray<TilingPaneHitZoneCandidateDebugState>;
+}
+/** A projected landing/result preview shown on a pane during a drag. */
+interface TilingLeafDropPreview {
+    /** Whether this preview is the drag-source landing or the drop-target result. */
+    role: TilingLeafPreviewRole;
+    /** Whether the preview depicts a swap or an edge-insert. */
+    mode: TilingLeafPreviewMode;
+    /** The drop zone the preview corresponds to. */
+    zone: TilingLeafDropZone;
+    /** The other leaf involved (swap counterpart or insert neighbor). */
+    partnerLeafId: string;
+}
+/** Options controlling how `insertLeafAdjacent` places an inserted leaf. */
+interface TilingInsertionOptions {
+    /** When `true`, reuse the parent split's axis instead of the placement axis. */
+    preserveParentSplitAxis: boolean;
+    /** Ratio `[0, 1]` allotted to the inserted leaf in the new split. */
+    splitRatio: number;
+}
+/** A measured pane rectangle in client coordinates (CSS px). */
+interface TilingPaneFootprint {
+    /** Left edge (client X). */
+    left: number;
+    /** Top edge (client Y). */
+    top: number;
+    /** Width (CSS px). */
+    width: number;
+    /** Height (CSS px). */
+    height: number;
+}
+/**
+ * Hex colors for the drag/drop observability overlays (borders, projected
+ * landing fills, and hit-zone tints). Consumed by the renderer overlays and the
+ * `/devtools` observability panel; see `TILING_OBSERVABILITY_COLOR_DEFAULTS`.
+ */
+interface TilingObservabilityColorConfig {
+    /** Border color of the drag source pane. */
+    dragSourceBorderColorHex: string;
+    /** Border color of the drag target pane. */
+    dragTargetBorderColorHex: string;
+    /** Border color of the projected source (S') landing. */
+    projectedSourceBorderColorHex: string;
+    /** Border color of the projected target (T') landing. */
+    projectedTargetBorderColorHex: string;
+    /** Border color of the projected successor landing. */
+    projectedSuccessorBorderColorHex: string;
+    /** Fill color of the projected source (S') landing. */
+    projectedSourceFillColorHex: string;
+    /** Fill color of the projected target (T') landing. */
+    projectedTargetFillColorHex: string;
+    /** Fill color of the projected successor landing. */
+    projectedSuccessorFillColorHex: string;
+    /** Tint of the left insert hit zone. */
+    hitZoneLeftColorHex: string;
+    /** Tint of the right insert hit zone. */
+    hitZoneRightColorHex: string;
+    /** Tint of the top insert hit zone. */
+    hitZoneTopColorHex: string;
+    /** Tint of the bottom insert hit zone. */
+    hitZoneBottomColorHex: string;
+    /** Tint of the center swap hit zone. */
+    hitZoneCenterColorHex: string;
+    /** Tint applied when a hit zone is blocked. */
+    hitZoneBlockedColorHex: string;
+}
+/** Per-subject overlay/border visibility toggles for the showcase observability panel. */
+interface TilingObservabilityColorEnableConfig {
+    /** Whether the drag source border overlay is drawn. */
+    dragSourceBorderEnabled: boolean;
+    /** Whether the drag target border overlay is drawn. */
+    dragTargetBorderEnabled: boolean;
+    /** Whether the projected source (S') border overlay is drawn. */
+    projectedSourceBorderEnabled: boolean;
+    /** Whether the projected target (T') border overlay is drawn. */
+    projectedTargetBorderEnabled: boolean;
+    /** Whether the projected source (S') fill overlay is drawn. */
+    projectedSourceFillEnabled: boolean;
+    /** Whether the projected target (T') fill overlay is drawn. */
+    projectedTargetFillEnabled: boolean;
+    /** Whether the projected successor border overlay is drawn. */
+    projectedSuccessorBorderEnabled: boolean;
+    /** Whether the projected successor fill overlay is drawn. */
+    projectedSuccessorFillEnabled: boolean;
+}
+/**
+ * Props for the {@link TilingRenderer} component — the full controlled-component
+ * surface. `layout` + `tiles` + `config` + `onLayoutChange` are the four
+ * required props; everything else is optional and resolves to a documented
+ * default.
+ *
+ * @remarks
+ * The renderer is a CONTROLLED component: you hold the layout tree in state and
+ * apply every edit it reports through `onLayoutChange`. Focus, maximize, theme,
+ * and accent can each be left uncontrolled (renderer-managed) or lifted into
+ * your state via the matching `on*Change` callback. Interaction behavior is
+ * tuned entirely through the single `interaction` prop
+ * ({@link TilingInteractionCapabilities}). This surface is debug-free: the
+ * drag/drop observability overlays, hit-zone visualizations, and telemetry
+ * feeds are a devtools concern, exposed through `TilingRendererObservabilityProps`
+ * on the `@n-uf/hypr-tiling/devtools` entry rather than here.
+ *
+ * @example
+ * ```tsx
+ * const [layout, setLayout] = useState<TilingLayoutNode>(initialLayout);
+ * return (
+ *   <TilingRenderer
+ *     layout={layout}
+ *     tiles={tiles}
+ *     config={DEFAULT_TILING_LAYOUT_CONFIG}
+ *     onLayoutChange={setLayout}
+ *   />
+ * );
+ * ```
+ *
+ * @see {@link TilingRenderer}
+ * @see {@link TilingInteractionCapabilities}
+ */
+interface TilingRendererProps {
+    /** The controlled layout tree to render. Apply every reported edit back here. */
+    layout: TilingLayoutNode;
+    /**
+     * Tile registry, accepted as either an ordered array (resolved by `id`) or a
+     * `Map` keyed by tile id. A dashboard can pass a plain `ReadonlyArray` of
+     * `{ id, title, content }` tiles; the interactive lab passes a `Map`.
+     */
+    tiles: ReadonlyArray<TilingTile> | ReadonlyMap<string, TilingTile>;
+    /** Global geometry configuration (gap, min pane size, handle size). */
+    config: TilingLayoutConfig;
+    /** Called with the next layout tree whenever the renderer edits it (controlled). */
+    onLayoutChange: (layout: TilingLayoutNode) => void;
+    /** Optional class name applied to the tiling root element. */
+    className?: string;
+    /**
+     * Active visual theme id. Selects which built-in `TilingTheme` paints every
+     * renderer surface (pane shells, header, focus frame, ghost, dividers, root,
+     * tab strip) and how per-pane accents compose with it. Undefined resolves to
+     * the library default (`"neon-terminal"`). Reacts to prop changes without
+     * remount — a live switch re-themes the whole tree.
+     */
+    themeId?: TilingThemeId;
+    /**
+     * Full consumer-authored theme; takes precedence over `themeId`. Every
+     * renderer-painted surface (pane shells, header, focus frame, ghost,
+     * dividers, root, tab strip) and every accent-composition resolver comes
+     * from this object, so a consumer owns the complete chrome without touching
+     * library internals. Undefined → the built-in theme selected by `themeId`.
+     */
+    theme?: TilingTheme;
+    /**
+     * Notified when the in-renderer theme switcher (top-bar control) requests a
+     * different theme. Present this control only when wired; the consumer owns
+     * the `themeId` state (controlled). Omit to hide the switcher — the theme
+     * stays whatever `themeId` (or the `theme` prop) resolves to. Generic
+     * mechanism; the demo theme composition lives with the consumer. BUILT-INS
+     * ONLY: the switcher enumerates the built-in registry and reports
+     * `TilingThemeId` members — a consumer running a custom `theme` object does
+     * not wire this callback (its theme never appears in the switcher).
+     */
+    onThemeChange?: (themeId: TilingThemeId) => void;
+    /**
+     * Reactive interaction-capability flags. Undefined resolves to all-enabled.
+     * Changing this prop at runtime updates renderer behavior immediately.
+     */
+    interaction?: TilingInteractionCapabilities;
+    /** Custom pane renderer. Receives {@link TilingRenderTileProps}; omit to use the default tile. */
+    renderTile?: (args: TilingRenderTileProps) => React.ReactNode;
+    /** Controlled focused-leaf id. `undefined` → uncontrolled; `null` → nothing focused. */
+    focusedLeafId?: string | null;
+    /** Notified whenever the focused leaf changes. */
+    onFocusedLeafChange?: (leafId: string) => void;
+    /**
+     * When provided, the top-bar tab strip surfaces an accent palette picker
+     * (the enumerable `TILING_TILE_ACCENTS` swatches) that recolors the
+     * currently-focused pane's tile. The renderer resolves the focused tile id;
+     * the consumer owns the tile registry and applies the new accent (e.g. by
+     * updating its tiles state). Omit to hide the picker — accent remains a
+     * static per-tile property. Generic mechanism; the demo palette composition
+     * lives with the consumer.
+     */
+    onTileAccentChange?: (tileId: string, accent: TilingTileAccent) => void;
+    /**
+     * Controlled maximized-pane id. `undefined` → uncontrolled (renderer-managed
+     * internal state). `null` → controlled, nothing maximized. A leaf id →
+     * controlled, that pane maximized. Reacts to prop changes without remount.
+     */
+    maximizedLeafId?: string | null;
+    /** Notified whenever the maximized pane changes (`null` on restore). */
+    onMaximizedLeafChange?: (leafId: string | null) => void;
+    /** Whether translucent projected landing overlays are shown during a drag. */
+    showDropPreviewOverlays?: boolean;
+    /** Background opacity `[0, 1]` for the projected landing overlays. */
+    projectedOverlayBackgroundAlpha?: number;
+    /**
+     * Master gate for all drag-motion choreography. When `false`, the ghost hop,
+     * survivor reflow, pickup-entrance, and swap dip collapse to instant placement
+     * (durations → ~0). Default `true`. The per-knob values (speeds, bounce) are
+     * preserved and re-apply when re-enabled.
+     */
+    dragAnimationEnabled?: boolean;
+    /**
+     * CSS `<easing-function>` for the dragged GHOST's hop transit (hop-in /
+     * hop-out / pickup entrance) and the swap/edge-insert ghost motion. Undefined
+     * → the default snappy decel `cubic-bezier(0.2, 0.8, 0.2, 1)`. An invalid /
+     * empty string falls back to that default (never reaches the compositor as a
+     * broken `transition`). The seated-ghost magnetic `linear()` curve and the
+     * swap-bounce curve are NOT replaced by this knob (sampled non-bezier curves).
+     */
+    dragHopEasing?: string;
+    /**
+     * CSS `<easing-function>` for the affected ("survivor") panes' FLIP reflow
+     * settle. Undefined → defaults to the same curve as `dragHopEasing` so the
+     * ghost and survivors read as one coordinated motion. Invalid / empty falls
+     * back to the default.
+     */
+    dragReflowEasing?: string;
+    /**
+     * Speed of the dragged GHOST's transit animation (hop-in / hop-out / pickup
+     * entrance) as a percent of the 170ms baseline (`100` = baseline). Lower is
+     * slower; higher is faster. Clamped to `[10, 400]`. Default `100`.
+     */
+    ghostTransitSpeedPercent?: number;
+    /**
+     * Speed of the affected ("survivor") panes' REFLOW transform animation as a
+     * percent of the 170ms baseline (`100` = baseline). Lower is slower; higher is
+     * faster. Clamped to `[10, 400]`. Default `100`. When this equals
+     * `ghostTransitSpeedPercent` the two parties are at PARITY, which the coherent
+     * non-intersecting transit dip requires (see `coherentTransit`).
+     */
+    survivorReflowSpeedPercent?: number;
+    /**
+     * Swap-landing bounce magnitude as a percent of full overshoot (`0` = no
+     * overshoot, today's monotonic settle; `100` = pronounced bounce). Applies an
+     * easeOutBack overshoot to the ghost seated hop-in and the survivor reflow
+     * settle. Per-element (no cross-element coupling), so it is NOT gated by speed
+     * parity. Inert while the coherent-transit dip owns the landing. Clamped to
+     * `[0, 100]`. Default `0`. Skipped under `prefers-reduced-motion`.
+     */
+    swapBounceMagnitudePercent?: number;
+    /** Whether drop border hints are painted on candidate panes during a drag. */
+    showDropBorderHints?: boolean;
+}
+/**
+ * The debug / observability inputs to {@link TilingRenderer}. Deliberately OFF
+ * the consumer {@link TilingRendererProps} contract — they drive the drag/drop
+ * observability overlays, hit-zone visualizations, and telemetry feeds that the
+ * `/devtools` observability panel consumes, not any consumer-facing behavior.
+ * Reach for them through the `@n-uf/hypr-tiling/devtools` entry (which exports
+ * the renderer typed to also accept these); the curated `.` renderer surface
+ * stays free of debug cruft.
+ *
+ * @public
+ */
+interface TilingRendererObservabilityProps {
+    /** Observability hook: notified with the current projected-overlay count. */
+    onProjectedOverlayCountChange?: (count: number) => void;
+    /** Override colors (hex) for the drag/drop observability overlays. */
+    observabilityColors?: TilingObservabilityColorConfig;
+    /** Per-subject visibility toggles for the observability overlays. */
+    observabilityColorEnables?: TilingObservabilityColorEnableConfig;
+    /** Whether the translucent drop-intent background tint is shown during a drag. */
+    showDropIntentTranslucentBg?: boolean;
+    /** Whether the drop-intent debug overlay is shown. */
+    showDropIntentDebug?: boolean;
+    /** Whether the five-region pane hit-zone debug overlay is shown. */
+    showPaneHitZones?: boolean;
+    /** Opacity `[0, 1]` for the pane hit-zone debug overlay. */
+    paneHitZonesAlpha?: number;
+    /** Force the hit-zone overlay to treat this leaf as the drag source (debug). */
+    paneHitZoneSourceLeafId?: string | null;
+    /** Observability hook: notified with the resolved drop intent (or `null`). */
+    onDropIntentChange?: (intent: TilingDropIntentDebugState | null) => void;
+    /** Observability hook: notified with the live drag/hover hit-log (or `null`). */
+    onLiveHitLogChange?: (state: TilingLiveHitLogState | null) => void;
+}
+
+declare const TILING_OBSERVABILITY_COLOR_DEFAULTS: TilingObservabilityColorConfig;
+declare const TILING_OBSERVABILITY_COLOR_ENABLE_DEFAULTS: TilingObservabilityColorEnableConfig;
+/**
+ * Recommended baseline layout config — the generic gap / min-pane / handle
+ * scale. `config` stays a required renderer prop (spacing is explicit at the
+ * call site), but consumers that don't tune spacing can spread this for a
+ * tasteful, well-readable inter-pane gutter out of the box instead of inventing
+ * their own magic numbers. `gapPx` + `handleSizePx` together form the visible
+ * inter-pane gap (the divider element occupies `handleSizePx` flanked by
+ * `gapPx / 2` margins; each child subtracts `(gapPx + handleSizePx) / 2` of
+ * basis — see `splitGapOffsetPx` in the split renderer for the balancing math).
+ */
+declare const DEFAULT_TILING_LAYOUT_CONFIG: TilingLayoutConfig;
+/** Baseline ghost-hop / survivor-reflow duration at `DEFAULT_DRAG_ANIMATION_SPEED_PERCENT`. */
+declare const BASELINE_DRAG_HOP_DURATION_MS: number;
+/** Default drag animation speed percent (`100` = the baseline duration). */
+declare const DEFAULT_DRAG_ANIMATION_SPEED_PERCENT: number;
+/** Slowest (floor) drag animation speed percent the slider + clamp allow. */
+declare const DRAG_ANIMATION_SPEED_MIN_PERCENT: number;
+/** Fastest (ceiling) drag animation speed percent the slider + clamp allow. */
+declare const DRAG_ANIMATION_SPEED_MAX_PERCENT: number;
+/** Duration the drag-motion timings collapse to when `dragAnimationEnabled` is `false`. */
+declare const INSTANT_DRAG_DURATION_MS: number;
+/**
+ * The controlled tiling renderer — the single component a consumer mounts. Its
+ * public prop surface ({@link TilingRendererProps}) is the curated, debug-free
+ * contract. The underlying component also accepts the devtools-tier
+ * `TilingRendererObservabilityProps`; that widened view is exported as
+ * `TilingRenderer` from `@n-uf/hypr-tiling/devtools` for the observability panel.
+ */
+declare const TilingRenderer: React.ForwardRefExoticComponent<TilingRendererProps & React.RefAttributes<TilingCommandHandle>>;
+/**
+ * The observability-instrumented view of {@link TilingRenderer}: the SAME
+ * component, typed to also accept {@link TilingRendererObservabilityProps} (the
+ * drag/drop observability overlays, hit-zone visualizations, and telemetry
+ * feeds). Exported through `@n-uf/hypr-tiling/devtools` for the observability
+ * panel; consumers use the clean `.` renderer instead.
+ */
+declare const TilingRendererWithObservability: React.ForwardRefExoticComponent<TilingRendererProps & TilingRendererObservabilityProps & React.RefAttributes<TilingCommandHandle>>;
+
+export { type ResolvedTilingSlotCommitmentCapability as $, type TilingPaneSizingMode as A, BASELINE_DRAG_HOP_DURATION_MS as B, type TilingAccentHue as C, type TilingKeyboardAction as D, type TilingKeyboardModifierState as E, type TilingMoveModeState as F, type TilingPaneSwitcherState as G, accentHue as H, INSTANT_DRAG_DURATION_MS as I, type TilingRenderTileProps as J, DEFAULT_DRAG_ANIMATION_SPEED_PERCENT as K, DEFAULT_TILE_ACCENT as L, DEFAULT_TILING_LAYOUT_CONFIG as M, DEFAULT_TILING_THEME_ID as N, DRAG_ANIMATION_SPEED_MAX_PERCENT as O, DRAG_ANIMATION_SPEED_MIN_PERCENT as P, type ResolvedTilingDragRecoveryCapability as Q, type ResolvedTilingInteractionCapabilities as R, type ResolvedTilingDropHitZoneGeometryCapability as S, type TilingLayoutNode as T, type ResolvedTilingGroupingCapability as U, type ResolvedTilingKeyBindings as V, type ResolvedTilingKeyChord as W, type ResolvedTilingKeyChordModifiers as X, type ResolvedTilingMaximizeCapability as Y, type ResolvedTilingPaneSwitchingCapability as Z, type ResolvedTilingPaneTitleBarControlsCapability as _, type TilingLayoutConfig as a, type ResolvedTilingTouchDragCapability as a0, TILING_ACCENT_HUES as a1, TILING_THEMES as a2, TILING_THEME_REGISTRY as a3, TILING_TILE_ACCENTS as a4, TILING_TILE_ACCENT_SWATCHES as a5, type TilingCommandHandle as a6, type TilingDragMode as a7, type TilingDragRecoveryCapability as a8, type TilingDropHitZoneGeometryCapability as a9, type TilingSlotCommitmentMode as aA, type TilingTheme as aB, type TilingThemeDividerTokens as aC, type TilingThemeGhostTokens as aD, type TilingThemeId as aE, type TilingThemePaneHeaderTokens as aF, type TilingThemePaneShellTokens as aG, TilingThemeProvider as aH, type TilingThemeRootTokens as aI, type TilingThemeTopBarTokens as aJ, type TilingTile as aK, type TilingTileAccent as aL, type TilingTileAccentSwatch as aM, type TilingTitleBarSizingMode as aN, type TilingTouchDragCapability as aO, resolveTilingTheme as aP, useTilingTheme as aQ, type TilingInsertionOptions as aR, type TilingGroupMemberView as aa, type TilingGroupNode as ab, type TilingGroupingCapability as ac, type TilingInteractionCapabilities as ad, type TilingKeyBindings as ae, type TilingKeyChord as af, type TilingKeyChordModifiers as ag, type TilingKeymap as ah, type TilingLayoutMode as ai, type TilingLeafDropPreview as aj, type TilingLeafNode as ak, type TilingLeafPreviewMode as al, type TilingLeafPreviewRole as am, type TilingMasterOrientation as an, type TilingMaximizeCapability as ao, type TilingMovePlacement as ap, type TilingPaneBodyRenderMode as aq, type TilingPaneCycleDirection as ar, type TilingPaneSwitchingCapability as as, type TilingPaneTitleBarControlsCapability as at, type TilingRenderSurface as au, type TilingRenderTileGroupContext as av, TilingRenderer as aw, type TilingRendererProps as ax, type TilingResizeCapability as ay, type TilingSlotCommitmentCapability as az, type TilingObservabilityColorConfig as b, type TilingObservabilityColorEnableConfig as c, type TilingDropIntentDebugState as d, type TilingLiveHitLogState as e, type TilingSplitNode as f, type TilingFocusDirection as g, TILING_OBSERVABILITY_COLOR_DEFAULTS as h, TILING_OBSERVABILITY_COLOR_ENABLE_DEFAULTS as i, type TilingDropIntentTuningState as j, type TilingLiveHitEdgeDebugState as k, type TilingPaneFootprint as l, type TilingPaneHitZoneCandidateDebugState as m, type TilingPaneHitZoneOverlayDebugState as n, TilingRendererWithObservability as o, type TilingRendererObservabilityProps as p, type TilingViewportCursorState as q, type TilingLeafDropZone as r, type TilingDropAction as s, type TilingSplitAxis as t, type ResolvedTilingKeymap as u, type TilingKeyBinding as v, type TilingKeyboardEventLike as w, type TilingCommand as x, type TilingDimension as y, type TilingPaneSizing as z };