Render a tiling layout in React — in one paste.

The controlled tiling renderer — the single component a consumer mounts. Its public prop surface (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.

Signature:

TilingRenderer: React.ForwardRefExoticComponent<TilingRendererProps & React.RefAttributes<TilingCommandHandle>>

Props for the 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.

Signature:

interface TilingRendererProps 

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 (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

const [layout, setLayout] = useState<TilingLayoutNode>(initialLayout);
return (
  <TilingRenderer
    layout={layout}
    tiles={tiles}
    config={DEFAULT_TILING_LAYOUT_CONFIG}
    onLayoutChange={setLayout}
  />
);

Properties

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).

Signature:

interface TilingRenderTileProps 

Remarks

A minimal custom pane needs only three wiring rules, each of which the optional public helper primitives (TilingPaneRoot(), TilingDragHandle(), TilingPaneAction(), 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).

Properties

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.

Signature:

interface TilingTile 

Properties

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.

Signature:

type TilingTileAccent = "cyan" | "sky" | "violet" | "indigo" | "emerald" | "amber" | "rose" | "pink";

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).

Signature:

DEFAULT_TILING_LAYOUT_CONFIG: TilingLayoutConfig

Build a read-only TilingLayoutQuery over layout. The single higher-level layout-inspection helper on the public API: it composes the low-level tree walkers (which stay on the ./engine escape hatch) into the leaf/tile/group/split views and directional-neighbor lookup an app needs to render layout-aware controls.

Signature:

declare function queryTilingLayout(layout: TilingLayoutNode): TilingLayoutQuery;

Parameters

Returns:

TilingLayoutQuery

Example

Inspect the tree you own in state — count panes, list groups, or find a directional neighbor — without walking it by hand:

import { queryTilingLayout, type TilingLayoutNode } from "@n-uf/hypr-tiling";

function paneCount(layout: TilingLayoutNode): number {
  return queryTilingLayout(layout).leafIds.length;
}

const query = queryTilingLayout(layout);
const rightOfFocus = query.neighborLeafId(focusedLeafId, "right");

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).

Signature:

interface TilingGroupNode 

Properties

Global geometry configuration for the renderer (the config prop).

Signature:

interface TilingLayoutConfig 

Properties

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.

Signature:

type TilingLayoutNode = TilingLeafNode | TilingSplitNode | TilingGroupNode;

References: TilingLeafNode, TilingSplitNode, TilingGroupNode

A read-only structural view of a TilingLayoutNode tree, aggregating the queries an app typically needs to drive layout-aware UI (shortcut chips, pane counters, directional focus) without walking the tree by hand or reaching for the low-level ./engine walkers.

Signature:

interface TilingLayoutQuery 

Properties

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.

Signature:

interface TilingLeafNode 

Properties

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.

Signature:

interface TilingSplitNode 

Properties

Default library theme id (preserves the prior look at the round-1 checkpoint).

Signature:

DEFAULT_TILING_THEME_ID: TilingThemeId

Resolve a theme id (or the default) to its TilingTheme.

Signature:

declare function resolveTilingTheme(themeId: TilingThemeId | undefined): TilingTheme;

Parameters

Returns:

TilingTheme

Ordered, enumerable theme list — the generic capability a theme switcher iterates.

Signature:

TILING_THEMES: readonly TilingTheme[]

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.

Signature:

interface TilingTheme 

Properties

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.

Signature:

type TilingThemeId = "neon-terminal" | "clean-flat" | "mosaic";

Provides the active theme to every renderer subcomponent.

Signature:

declare function TilingThemeProvider(input: {
    theme: TilingTheme;
    children: React.ReactNode;
}): React.ReactElement;

Parameters

Returns:

React.ReactElement

Reads the active theme from context (defaults to the library default).

Signature:

declare function useTilingTheme(): TilingTheme;

Returns:

TilingTheme

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.

Signature:

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;
};

References: TilingFocusDirection, TilingPaneCycleDirection, TilingMovePlacement, TilingTitleBarSizingMode, TilingLayoutMode, TilingMasterOrientation

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).

Signature:

interface TilingCommandHandle 

Properties

Default drag animation speed percent (100 = the baseline duration).

Signature:

DEFAULT_DRAG_ANIMATION_SPEED_PERCENT: number

The default ghost hop / pickup / hop-out timing function (a snappy decel).

Signature:

DEFAULT_DRAG_HOP_EASING: string

The default survivor-reflow settle timing function. Equals the hop curve so the ghost and the survivors read as one coordinated motion (the renderer's dragReflowEasing prop falls back to the resolved dragHopEasing when undefined, so this default only applies when BOTH are unset).

Signature:

DEFAULT_DRAG_REFLOW_EASING: string

First palette member — the fallback when a tile omits accent.

Signature:

DEFAULT_TILE_ACCENT: TilingTileAccent

Fastest (ceiling) drag animation speed percent the slider + clamp allow.

Signature:

DRAG_ANIMATION_SPEED_MAX_PERCENT: number

Slowest (floor) drag animation speed percent the slider + clamp allow.

Signature:

DRAG_ANIMATION_SPEED_MIN_PERCENT: number

Whether command would do anything given the current capability gates: true when the command's required capability is enabled (or it requires none). A keyboard binding to a disabled-capability command stays browser-graceful (the caller does not preventDefault); an imperative dispatch of one is a no-op.

Signature:

declare function isCommandEnabled(command: TilingCommand, gates: TilingCommandGates): boolean;

Parameters

Returns:

boolean

Example

Build your own command bar / keyboard shortcut that only fires (and only renders its button) when the target command is actually enabled — the gate the renderer itself uses for its shortcut chips:

import {
  resolveInteractionCapabilities,
  isCommandEnabled,
  type TilingCommand,
  type TilingCommandGates,
  type TilingCommandHandle,
  type TilingInteractionCapabilities,
} from "@n-uf/hypr-tiling";

function gatesFor(interaction?: TilingInteractionCapabilities): TilingCommandGates {
  const caps = resolveInteractionCapabilities(interaction);
  return {
    maximizeEnabled: caps.maximize.enable,
    paneSwitchingEnabled: caps.paneSwitching.enable,
    focusEnabled: caps.focus,
    rearrangeEnabled: caps.rearrange,
    sizingEnabled: caps.paneTitleBarControls.sizing,
    acquireSpaceEnabled: caps.paneTitleBarControls.acquireSpace,
    resizeEnabled: caps.resize !== "none",
    layoutEnabled: caps.masterLayout,
    groupingEnabled: caps.grouping.enable,
  };
}

function MaximizeButton(props: {
  handle: React.RefObject<TilingCommandHandle | null>;
  interaction?: TilingInteractionCapabilities;
}) {
  const command: TilingCommand = { kind: "toggle-maximize" };
  if (!isCommandEnabled(command, gatesFor(props.interaction))) {
    return null; // maximize is disabled — don't render a dead control
  }
  return <button onClick={() => props.handle.current?.dispatch(command)}>Maximize</button>;
}

true when the event carries the multi-select modifier — Alt/Opt (altKey), the single chord both the header toggle and the Alt+G group key key off.

Signature:

declare function isMultiSelectModifierActive(event: MultiSelectModifierState): boolean;

Parameters

Returns:

boolean

Example

In a custom renderTile, add the clicked pane to the multi-selection only when the platform multi-select modifier is held (a plain click falls through to focus):

import { isMultiSelectModifierActive } from "@n-uf/hypr-tiling";

<header
  onClick={(event) => {
    if (args.isMultiSelectGroupingEnabled && isMultiSelectModifierActive(event)) {
      event.preventDefault();
      args.onToggleMultiSelect();
    }
  }}
/>

The modifier-key subset of a pointer/mouse event that discriminates a multi-select click from a plain click. The multi-select / grouping modifier is unified on Alt/Opt across every surface (header click + the Alt+G key), chosen for minimal cross-browser interference: altKey = Opt on macOS, Alt on Windows/Linux.

Signature:

interface MultiSelectModifierState 

Properties

Fully-resolved drag-recovery configuration (no optional fields).

Signature:

interface ResolvedTilingDragRecoveryCapability 

Properties

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.

Signature:

interface ResolvedTilingDropHitZoneGeometryCapability 

Properties

Resolved group / tabbed-stacking capability (no optional fields).

Signature:

interface ResolvedTilingGroupingCapability 

Properties

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.

Signature:

interface ResolvedTilingInteractionCapabilities 

Properties

Fully-resolved key-binding registry (no optional fields).

Signature:

interface ResolvedTilingKeyBindings 

Properties

Fully-resolved key chord (every modifier explicit). Matches KeyboardEvent.code.

Signature:

interface ResolvedTilingKeyChord 

Properties

Fully-resolved jump-to-pane modifier set.

Signature:

interface ResolvedTilingKeyChordModifiers 

Properties

Fully-resolved keymap (no optional fields).

Signature:

interface ResolvedTilingKeymap 

Properties

Resolved maximize capability (no optional fields).

Signature:

interface ResolvedTilingMaximizeCapability 

Properties

Resolved pane-switching capability (no optional fields).

Signature:

interface ResolvedTilingPaneSwitchingCapability 

Properties

Resolved per-pane title-bar control capability (no optional fields).

Signature:

interface ResolvedTilingPaneTitleBarControlsCapability 

Properties

Fully-resolved slot-commitment configuration (no optional fields).

Signature:

interface ResolvedTilingSlotCommitmentCapability 

Properties

Fully-resolved touch-drag configuration (no optional fields).

Signature:

interface ResolvedTilingTouchDragCapability 

Properties

Single defaulting helper for TilingInteractionCapabilities. undefined / null → all enabled; a partial override merges field-by-field over the all-enabled defaults. Uses nullish coalescing so an explicit false (e.g. rearrange: false, maximize.enable: false) is preserved and never overridden by the default. Idempotent: re-resolving a resolved object yields the same result.

Signature:

declare function resolveInteractionCapabilities(capabilities?: TilingInteractionCapabilities | null): ResolvedTilingInteractionCapabilities;

Parameters

Returns:

ResolvedTilingInteractionCapabilities

Resolve the jump-to-N leaf id (1-based), or null when out of range (no-op).

Signature:

declare function resolveJumpedPaneId(leafIds: ReadonlyArray<string>, paneNumber: number): string | null;

Parameters

Returns:

string | null

Example

Wire your own "jump to pane N" buttons against the leaf order from queryTilingLayout(), dispatching the built-in focus-jump command:

import { queryTilingLayout, resolveJumpedPaneId } from "@n-uf/hypr-tiling";

const { leafIds } = queryTilingLayout(layout);
leafIds.forEach((_, i) => {
  const paneNumber = i + 1;
  const targetLeafId = resolveJumpedPaneId(leafIds, paneNumber); // null → out of range
  // render a button that dispatches { kind: "focus-jump", paneNumber } when targetLeafId != null
});

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.

Signature:

TILING_ACCENT_HUES: Record<TilingTileAccent, TilingAccentHue>

Interaction preset for static (config-driven) product dashboards: only height dividers resize (resize: "vertical"), and every interactive surface that assumes a rearrangeable/maximizable lab layout is off (no drag-rearrange, no pane focus selection, no maximize, no pane switching / tab strip). Dashboards pass this instead of hand-repeating the disable set.

Per-pane title-bar controls (sizing + acquire-space) are OFF here too: dashboards ship a curated layout with PRE-CONFIGURED static panes and are resize-only by intent, so letting an end-user re-pin a pane's bbox or have one pane absorb its siblings' space would fight the authored composition. End-user per-pane sizing belongs to interactive workspaces (the showcase default), not config-driven dashboards.

Signature:

TILING_DASHBOARD_PRESET: TilingInteractionCapabilities

All-enabled defaults. An undefined capability config (or any undefined field) resolves to these via resolveInteractionCapabilities.

The lone opt-IN exception is paneSwitching.showContentToggle: it defaults to false. That checkbox (a group tab strip's "show pane body" toggle) is a development / demo affordance — a consumer app renders its own pane content and never wants an end-user control that blanks it. Suppressed by default, the initial pane-content-visible flag pins ON (see resolveInitialPaneContentVisible), so panes paint their content at rest with no wiring. A tooling surface that genuinely wants the toggle (e.g. the interactive showcase) opts back in with paneSwitching: { showContentToggle: true }.

Signature:

TILING_INTERACTION_CAPABILITY_DEFAULTS: ResolvedTilingInteractionCapabilities

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).

Signature:

TILING_THEME_REGISTRY: Record<TilingThemeId, TilingTheme>

Picker-ready metadata (accent + label + swatch class) for every accent.

Signature:

TILING_TILE_ACCENT_SWATCHES: readonly TilingTileAccentSwatch[]

Ordered, enumerable accent palette — the generic capability a consumer iterates to build an accent picker.

Signature:

TILING_TILE_ACCENTS: readonly TilingTileAccent[]

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.

Signature:

interface TilingAccentHue 

Properties

The capability enable-flags a command may require. Superset of TilingKeymapActionGuards (which only covers the keyboard-reachable actions) with the sizing / acquire-space / resize gates the programmatic command set also touches. The renderer builds this from its resolved capabilities.

Signature:

interface TilingCommandGates 

Properties

The drag-pickup surface of a custom pane (typically the header). Wires the renderer's onHandlePointerDown and sets touch-action: none so a touch press starts a drag instead of scrolling, and folds in the Alt/Opt+click multi-select toggle (which must not establish focus). Renders a <div>; bring your own className / style / children.

Signature:

declare function TilingDragHandle(input: TilingDragHandleProps): React.ReactElement;

Parameters

Returns:

React.ReactElement

Props for TilingDragHandle().

Signature:

interface TilingDragHandleProps extends Omit<React.HTMLAttributes<HTMLElement>, "onPointerDown" | "onClick"> 

Extends: Omit<React.HTMLAttributes<HTMLElement>, "onPointerDown" | "onClick">

Properties

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".

Signature:

type TilingDragMode = "preview" | "live";

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).

Signature:

interface TilingDragRecoveryCapability 

Properties

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").

Signature:

type TilingDropAction = "swap" | "edge-insert" | "split-container-insert" | "group-merge" | "none";

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.

Signature:

interface TilingDropHitZoneGeometryCapability 

Properties

A directional focus / move target relative to the current pane.

Signature:

type TilingFocusDirection = "left" | "right" | "up" | "down";

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 }.

Signature:

interface TilingGroupingCapability 

Properties

One member of a tabbed group, as seen by a custom renderTile through 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.

Signature:

interface TilingGroupMemberView 

Properties

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.

Signature:

interface TilingInteractionCapabilities 

Properties

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.

Signature:

interface TilingKeyBinding 

Properties

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.

Signature:

interface TilingKeyBindings 

Properties

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.

Signature:

interface TilingKeyChord 

Properties

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.

Signature:

interface TilingKeyChordModifiers 

Properties

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.

Signature:

interface TilingKeymap 

Properties

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.

Signature:

type TilingLayoutMode = "dwindle" | "master";

A projected landing/result preview shown on a pane during a drag.

Signature:

interface TilingLeafDropPreview 

Properties

The five drop regions of a pane: a central swap zone plus four insert edges.

Signature:

type TilingLeafDropZone = "center" | "left" | "right" | "top" | "bottom";

Whether a preview depicts a swap or an edge-insert result.

Signature:

type TilingLeafPreviewMode = "swap" | "edge-insert";

Which side of a preview a shadow represents (drag source vs drop target).

Signature:

type TilingLeafPreviewRole = "drag-source-landing-shadow" | "drop-target-result-shadow";

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.

Signature:

type TilingMasterOrientation = "left" | "right" | "top" | "bottom";

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.

Signature:

interface TilingMaximizeCapability 

Properties

Which edge of a target pane an inserted/moved pane lands on.

Signature:

type TilingMovePlacement = "left" | "right" | "top" | "bottom";

A header action button (maximize, group, …) that stopPropagations on both pointer-down and click, so activating it never starts a drag or steals pane focus. Defaults type to "button" and calls your onClick after stopping propagation. Bring your own className / style / children.

Signature:

declare function TilingPaneAction(input: TilingPaneActionProps): React.ReactElement;

Parameters

Returns:

React.ReactElement

Props for TilingPaneAction().

Signature:

type TilingPaneActionProps = React.ButtonHTMLAttributes<HTMLButtonElement>;

The body wrapper of a custom pane. Always renders its wrapper <div> (so the pane keeps its layout), but renders children ONLY when paneBodyRenderMode === "render-content". This keeps a custom pane aligned with the renderer's drag-ghost / hidden-body semantics — the ghost reuses the same render path, so an empty body never rides along. Bring your own className / style.

Signature:

declare function TilingPaneBody(input: TilingPaneBodyProps): React.ReactElement;

Parameters

Returns:

React.ReactElement

Props for TilingPaneBody().

Signature:

interface TilingPaneBodyProps extends React.HTMLAttributes<HTMLDivElement> 

Extends: React.HTMLAttributes<HTMLDivElement>

Properties

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.

Signature:

type TilingPaneBodyRenderMode = "render-content" | "render-empty" | "render-reservation";

Pane cycle direction for the reading-order ring (next / previous, wraparound).

Signature:

type TilingPaneCycleDirection = "next" | "previous";

The root element of a custom pane. Renders an <article data-leaf-id> (the attribute the renderer resolves the drag source from) and wires the pane's onFocus (on both focus and click), onPointerMove, and onPointerLeave handlers, so focus, resize, and pre-drag hover telemetry keep working. Bring your own className / style / children; defaults tabIndex to -1.

Signature:

declare function TilingPaneRoot(input: TilingPaneRootProps): React.ReactElement;

Parameters

Returns:

React.ReactElement

Props for TilingPaneRoot().

Signature:

interface TilingPaneRootProps extends Omit<React.HTMLAttributes<HTMLElement>, "onFocus" | "onClick" | "onPointerMove" | "onPointerLeave"> 

Extends: Omit<React.HTMLAttributes<HTMLElement>, "onFocus" | "onClick" | "onPointerMove" | "onPointerLeave">

Properties

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.

Signature:

interface TilingPaneSizing 

Properties

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.

Signature:

type TilingPaneSizingMode = "static" | "flexible";

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.

Signature:

interface TilingPaneSwitchingCapability 

Properties

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.

Signature:

interface TilingPaneTitleBarControlsCapability 

Properties

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".

Signature:

type TilingRenderSurface = "pane" | "drag-ghost" | "drag-cancel";

Group context on 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.

Signature:

interface TilingRenderTileGroupContext 

Properties

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.

Signature:

type TilingResizeCapability = "both" | "horizontal" | "vertical" | "none";

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.

Signature:

interface TilingSlotCommitmentCapability 

Properties

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".

Signature:

type TilingSlotCommitmentMode = "zone-exit-hold" | "delta-responsive";

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).

Signature:

type TilingSplitAxis = "horizontal" | "vertical";

Split-divider / gap handle chrome across visible + hidden states.

Signature:

interface TilingThemeDividerTokens 

Properties

Drag-ghost shell — the lifted, portaled copy of the dragged pane.

Signature:

interface TilingThemeGhostTokens 

Properties

Pane header chrome — resting + focused + the per-pane control buttons.

Signature:

interface TilingThemePaneHeaderTokens 

Properties

Pane host shell surfaces + interaction-state rings.

Signature:

interface TilingThemePaneShellTokens 

Properties

Renderer-root + viewport surfaces.

Signature:

interface TilingThemeRootTokens 

Properties

Top-bar / tab-strip chrome.

Signature:

interface TilingThemeTopBarTokens 

Properties

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.

Signature:

interface TilingTileAccentSwatch 

Properties

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.

Signature:

type TilingTitleBarSizingMode = "flexible" | "static-height" | "static-width" | "static-both";

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.

Signature:

interface TilingTouchDragCapability 

Properties