@xenosystem/blocks 0.4.1 → 0.5.0

package/dist/time/index.d.ts

@@ -0,0 +1,2261 @@
+import { PanelHost, PanelModule, PanelManifest } from '@xenosystem/panel-sdk';
+import { ThrottleClock, XenoPlayheadClock, XenoTimebase, XenoTransportState, XenoTick, XenoStepUnit, XenoLoopRange } from '@xenosystem/time-core';
+export { BAR_SUBDIVISION, BarsBeats, DEFAULT_TIMEBASE, DISPLAY_CYCLE, ExtrapolateInput, IDLE_CLOCK, ThrottleClock, Throttled, XenoLoopRange, XenoPlayheadClock, XenoStepUnit, XenoTempoEntry, XenoTick, XenoTimeDisplay, XenoTimeSignature, XenoTimebase, XenoTransportIntent, XenoTransportState, clampTick, clockAt, createThrottle, displayLabel, effectiveFps, extrapolateTick, formatBars, formatFrames, formatSeconds, formatTick, formatTimecode, frameToTick, isAnimating, nextDisplay, normalizeClock, normalizeTimebase, secondsToTicks, tickToFrame, ticksToBarsBeats, ticksToSeconds, toTick, wrapIntoLoop } from '@xenosystem/time-core';
+import { ReactElement, ReactNode } from 'react';
+import { XenoValue, XenoRow, XenoResultSet, XenoColumn } from '@xenosystem/data-core';
+
+/**
+ * `TransportPanelController` — the framework-free brain of the Transport panel.
+ *
+ * It owns display state only. The clock, playback and every transport decision are the host's; the
+ * panel extrapolates a tick for the readout and emits {@link XenoTransportIntent}s.
+ *
+ * @module
+ */
+
+/** Options for {@link TransportPanelController}. */
+interface TransportPanelControllerOptions {
+    /** Injectable clock for deterministic throttle + extrapolation tests. */
+    throttleClock?: ThrottleClock;
+    /**
+     * Reads "now" in the same domain as `clock.originTime`. Defaults to `performance.now()`
+     * (falling back to `Date.now()`); tests inject a fake.
+     */
+    now?: () => number;
+}
+/** A keyboard event, framework-free. */
+interface TransportKeyEvent {
+    key: string;
+    ctrl?: boolean;
+    meta?: boolean;
+    shift?: boolean;
+    alt?: boolean;
+}
+/** Serialized panel state (for the `.xapp`). */
+interface TransportPanelSerialized {
+    displayOverride?: XenoTimebase['display'] | null;
+}
+declare class TransportPanelController {
+    private readonly host;
+    private readonly nowFn;
+    private readonly seekThrottle;
+    private clock;
+    private timebase;
+    private durationTicks;
+    private state;
+    private displayOverride;
+    private scrubbing;
+    private scrubTick;
+    private shuttleIndex;
+    private lastRenderedTick;
+    /** J/K/L: `true` while K is held (K+J / K+L are nudges, not shuttles). */
+    private kHeld;
+    private configDisplay;
+    private clickReadoutCycles;
+    private showRecord;
+    private showLoop;
+    private showMetronome;
+    private showPunch;
+    private showPreroll;
+    private showBpm;
+    private showShuttle;
+    private showScrubber;
+    private showInOut;
+    private shuttleRates;
+    private jklShuttle;
+    private stepUnit;
+    private revision;
+    private disposed;
+    private readonly listeners;
+    private unsubConfig;
+    constructor(host: PanelHost, options?: TransportPanelControllerOptions);
+    /** Load the persisted display-unit preference. */
+    load(): Promise<void>;
+    private readConfig;
+    /** Accept a clock push. Each push SNAPS the extrapolation to host truth. */
+    setClock(input: unknown): void;
+    /** Accept a timebase push. */
+    setTimebase(input: unknown): void;
+    /** Accept the live duration (ticks). */
+    setDuration(input: unknown): void;
+    /** Accept the transport state. Absent keys hide their controls. */
+    setState(input: unknown): void;
+    /** The current clock (host truth, not the extrapolation). */
+    getClock(): XenoPlayheadClock;
+    /** The current timebase. */
+    getTimebase(): XenoTimebase;
+    /** The live duration in ticks. */
+    getDuration(): number;
+    /** The transport state. */
+    getState(): XenoTransportState;
+    /** `playing` is HOST-authoritative — the panel only reports it. */
+    isPlaying(): boolean;
+    /** Whether the display should keep animating (a moving playhead only). */
+    isAnimating(): boolean;
+    /**
+     * The tick to display right now: the scrub position while scrubbing, else the dead-reckoned
+     * extrapolation, always clamped against the LIVE duration.
+     */
+    getCurrentTick(): XenoTick;
+    /**
+     * Advance the display. The view calls this each animation frame; it notifies **only when the
+     * integer tick actually changed**, so a paused transport or a sub-tick frame costs nothing.
+     *
+     * @returns `true` if listeners were notified.
+     */
+    pump(): boolean;
+    /** The formatted readout for the current position. */
+    getReadout(): string;
+    /** The formatted duration. */
+    getDurationReadout(): string;
+    /** Playback progress `0..1` (0 when the duration is unknown). */
+    getProgress(): number;
+    /** The effective display unit: panel override → config → the host timebase. */
+    getDisplay(): XenoTimebase['display'];
+    /** Set the display unit (persisted). */
+    setDisplay(display: XenoTimebase['display']): Promise<void>;
+    /** Cycle to the next display unit (the readout click). */
+    cycleDisplay(): void;
+    private emit;
+    /** Start playback. */
+    play(): void;
+    /** Pause playback. */
+    pause(): void;
+    /** Toggle playback. The host decides — the panel never flips `playing` itself. */
+    togglePlay(): void;
+    /** Stop (the host decides whether that returns to start). */
+    stop(): void;
+    /** Start/stop recording. */
+    record(recording?: boolean): void;
+    /** Seek to a tick (clamped to the live duration). */
+    seek(tick: XenoTick): void;
+    /** Step by whole units. */
+    step(delta: number, unit?: XenoStepUnit): void;
+    /** Jump to the start. */
+    goToStart(): void;
+    /** Jump to the end. */
+    goToEnd(): void;
+    /** Set the shuttle rate directly (negative reverses). */
+    shuttle(rate: number): void;
+    /** The configured shuttle rates. */
+    getShuttleRates(): readonly number[];
+    /**
+     * Step through the shuttle rates in a direction — the classic J/L behaviour: each press moves one
+     * notch up the ladder, crossing zero to reverse.
+     *
+     * @param direction - `+1` faster forward, `-1` faster reverse.
+     * @returns The rate emitted.
+     */
+    shuttleStep(direction: number): number;
+    /** The current shuttle ladder position (0 = stopped). */
+    getShuttleIndex(): number;
+    /** Set (or clear) the loop range. */
+    setLoop(loop: XenoLoopRange | null): void;
+    /** Toggle looping, preserving the existing range. */
+    toggleLoop(): void;
+    /** Set the in point (defaults to the playhead). */
+    setInPoint(tick?: XenoTick): void;
+    /** Set the out point (defaults to the playhead). */
+    setOutPoint(tick?: XenoTick): void;
+    /** Clear both in/out points. */
+    clearInOut(): void;
+    /** Toggle the metronome. */
+    toggleMetronome(): void;
+    /** Set the tempo. */
+    setTempo(bpm: number): void;
+    /** Whether a scrub is in progress. */
+    isScrubbing(): boolean;
+    /** Begin a scrub at a tick. */
+    beginScrub(tick: XenoTick): void;
+    /** Update the scrub — emits a throttled `seekPreview`, never a commit. */
+    updateScrub(tick: XenoTick): void;
+    /** Finish the scrub — flushes the preview and commits ONE `seek` intent. */
+    endScrub(): void;
+    /** Abandon the scrub without seeking. */
+    cancelScrub(): void;
+    /** Convert a scrubber fraction `0..1` to a tick. */
+    fractionToTick(fraction: number): XenoTick;
+    /** Whether a control renders: its config flag AND the host declaring the state key. */
+    showsControl(control: 'record' | 'loop' | 'metronome' | 'punch' | 'preroll' | 'bpm' | 'shuttle' | 'scrubber' | 'inOut'): boolean;
+    /**
+     * Handle a key. Returns `true` when consumed.
+     *
+     * Space toggles; Home/End jump; ←/→ step; and with `jklShuttle` on, J/K/L drive the Motion /
+     * Resolve shuttle — **K held + J or L nudges one frame** instead of shuttling.
+     */
+    handleKey(event: TransportKeyEvent, phase?: 'down' | 'up'): boolean;
+    /** Whether K is currently held (the J/K/L nudge modifier). */
+    isKHeld(): boolean;
+    /** Route a host `onInput(id, value)` call. */
+    onInput(id: string, value: unknown): void;
+    /** Route a host `onCommand(id, params)` call. */
+    onCommand(id: string, params: Record<string, unknown>): Promise<unknown>;
+    serialize(): TransportPanelSerialized;
+    deserialize(state: unknown): void;
+    subscribe(listener: () => void): () => void;
+    getRevision(): number;
+    private notify;
+    /** Release timers and subscriptions. Idempotent. */
+    dispose(): void;
+}
+/** Ticks for one step of a unit (host bridges may use this for `step` intents). */
+declare function ticksPerStep(unit: XenoStepUnit, timebase: XenoTimebase): number;
+
+/**
+ * `createTransportPanel` — the `PanelModule` factory for `xeno.core.transport`.
+ *
+ * @module
+ */
+
+/** Options for {@link createTransportPanel}. */
+type CreateTransportPanelOptions = TransportPanelControllerOptions;
+/**
+ * Build the Transport panel module.
+ *
+ * @param options - Controller options (an injectable `now` / throttle clock for tests).
+ * @returns A {@link PanelModule} ready to register with a `PanelRegistry`.
+ */
+declare function createTransportPanel(options?: CreateTransportPanelOptions): PanelModule;
+/** The default Transport panel module. */
+declare const transportPanel: PanelModule;
+
+/**
+ * The `xeno.core.transport` manifest (timeline-family union spec §3).
+ *
+ * The smallest, most universal panel in the catalog — five hosts adopt it day one (Motion, Sound,
+ * Pixel, 3D, harness). Capabilities are `storage.local` ONLY: the host owns the clock and playback
+ * by construction, so there is nothing a transport capability could grant.
+ *
+ * @module
+ */
+
+declare const transportManifest: PanelManifest;
+
+/**
+ * `TransportPanelView` — the React rendering half of the Transport panel.
+ *
+ * It runs the **display-only animation frame**: each frame calls `controller.pump()`, which
+ * re-renders only when the integer tick actually changed, and the loop stops entirely when the
+ * transport is not moving. That is the whole 60fps-without-streaming trick — no per-frame IPC, no
+ * idle wakeups.
+ *
+ * Monochrome, dense, rectangles with small corner radius, square knobs, no circles, no shadows
+ * (DESIGN_SYSTEM §2/§3/§4).
+ *
+ * @module
+ */
+
+/** Props for the view. */
+interface TransportPanelViewProps {
+    controller: TransportPanelController;
+}
+declare function TransportPanelView({ controller }: TransportPanelViewProps): ReactElement;
+
+/**
+ * `XenoTimeScale` — **the only thing in this package that converts between pixels and ticks.**
+ *
+ * ## Why one object
+ *
+ * Every timeline that scatters `clientX → time` arithmetic through its event handlers ships the same
+ * bug: `WheelEvent.clientX` is *viewport*-relative, the lane area starts after a track-header gutter,
+ * and forgetting to subtract it makes the content **slide under the cursor** on every zoom notch. The
+ * error is proportional to the visible span, so it never converges — measured on a 240 px gutter at
+ * 10 % per notch, the content slips ~1.3 s on the first notch and is still slipping 0.5 s on the
+ * tenth.
+ *
+ * Two shipping products solve it structurally rather than by remembering:
+ *
+ * - **Ardour** keeps two deliberately *differently-named* converters — `pixel_to_sample_from_event`
+ *   subtracts the timeline origin, `pixel_to_sample` does not — so the two spaces cannot be silently
+ *   mixed.
+ * - **Perfetto** puts the gutter *inside* the scale object, so there is nothing to forget.
+ *
+ * This is Perfetto's approach. The gutter is a field; `xToTick` takes a **container-relative** x and
+ * accounts for it. Nothing else in the package does this arithmetic.
+ *
+ * ## Why the state is `(pxPerTick, scrollTick)` and not `(startTick, endTick)`
+ *
+ * Storing the visible window as a pair of edges loses precision catastrophically under repeated
+ * zoom: once the span shrinks far below the absolute offset, both endpoints round to the same double
+ * and all relative information is gone. Measured over 300 zoom-ins and 300 zoom-outs about a cursor,
+ * `(left, right)` drifts by ~1.3 ms while `(pxPerTick, scroll)` drifts by ~1.8e-14 s. Ticks are
+ * integers here, which removes the rest.
+ *
+ * @module
+ */
+
+/** How the visible window is described. */
+interface XenoTimeScaleState {
+    /** Horizontal zoom. The single scalar — ticks are linear wall-clock, so tempo never enters here. */
+    pxPerTick: number;
+    /** The tick at the left edge of the LANE area (not of the container). */
+    scrollTick: number;
+    /** Vertical scroll, in CSS px. */
+    scrollTopPx: number;
+}
+/** Construction geometry. */
+interface XenoTimeScaleGeometry {
+    /** Full container width in CSS px, gutter included. */
+    widthPx: number;
+    /** Container height in CSS px. */
+    heightPx: number;
+    /**
+     * Width of the track-header gutter in CSS px.
+     *
+     * The field that exists so no caller has to remember it.
+     */
+    gutterPx: number;
+}
+/** Zoom bounds, in px per tick. */
+interface XenoZoomBounds {
+    min: number;
+    max: number;
+}
+/** The default zoom range: from ~1 tick per pixel out to 64 px per tick. */
+declare const DEFAULT_ZOOM: XenoZoomBounds;
+/**
+ * An immutable view→time mapping.
+ *
+ * Cheap to construct; make a new one rather than mutating, so a render never sees a half-updated
+ * scale.
+ */
+declare class XenoTimeScale {
+    readonly pxPerTick: number;
+    readonly scrollTick: number;
+    readonly scrollTopPx: number;
+    readonly widthPx: number;
+    readonly heightPx: number;
+    readonly gutterPx: number;
+    constructor(state: XenoTimeScaleState, geometry: XenoTimeScaleGeometry);
+    /** Width of the lane area — the container minus the gutter. Always ≥ 1. */
+    get lanePx(): number;
+    /** Ticks visible in the lane area. */
+    get spanTicks(): number;
+    /** The tick at the right edge of the lane area. */
+    get endTick(): number;
+    /**
+     * Container-relative x → tick.
+     *
+     * @param x - Pixels from the **container's** left edge (`event.clientX - rect.left`).
+     * @returns The tick under that pixel. May be negative left of the origin.
+     *
+     * @example
+     * ```ts
+     * const rect = el.getBoundingClientRect()
+     * const tick = scale.xToTick(event.clientX - rect.left)
+     * ```
+     */
+    xToTick(x: number): number;
+    /**
+     * Tick → container-relative x.
+     *
+     * @param tick - A tick.
+     * @returns Pixels from the container's left edge.
+     */
+    tickToX(tick: number): number;
+    /**
+     * A tick DURATION → a pixel width.
+     *
+     * Deliberately separate from {@link tickToX}, because rounding is **not associative**:
+     * `durationToPx(b - a)` and `tickToX(b) - tickToX(a)` differ by up to a pixel, and mixing them is
+     * how a clip's right edge ends up one pixel from its neighbour's left edge at some zoom levels and
+     * overlapping at others. Pick one per axis and never mix.
+     *
+     * @param ticks - A duration in ticks.
+     * @returns Width in CSS px.
+     */
+    durationToPx(ticks: number): number;
+    /** A pixel distance → a tick distance. Used for screen-space thresholds. */
+    pxToTicks(px: number): number;
+    /** Is this x inside the lane area (rather than the gutter)? */
+    isInLane(x: number): boolean;
+    /** A copy with new state. */
+    with(state: Partial<XenoTimeScaleState>): XenoTimeScale;
+    /** A copy with new geometry. */
+    resized(geometry: Partial<XenoTimeScaleGeometry>): XenoTimeScale;
+}
+/**
+ * Zoom about a cursor, keeping the tick under the pointer **exactly** where it was.
+ *
+ * The whole formula, and the reason the gutter lives in the scale:
+ *
+ * ```
+ * anchorTick = scale.xToTick(x)                  // BEFORE the zoom, gutter accounted for
+ * pxPerTick' = clamp(pxPerTick * factor)         // clamp FIRST
+ * scrollTick' = anchorTick - (x - gutter) / pxPerTick'
+ * ```
+ *
+ * 🔴 The factor must come from the **clamped** zoom, not the requested one. Deriving the new scroll
+ * from a zoom that was then clamped moves the content under a stationary cursor at both ends of the
+ * range — which is the moment a user is most likely to be zoomed in on something they care about.
+ * Neither surveyed incumbent has zoom-to-cursor at all, so there is no prior art to inherit the bug
+ * from; this is written from the correct form.
+ *
+ * @param scale - The current scale.
+ * @param x - Container-relative pointer x.
+ * @param factor - Requested multiplier (>1 zooms in).
+ * @param bounds - Zoom limits.
+ * @param maxTick - Content duration, so scroll cannot run past the end.
+ * @returns The new state.
+ *
+ * @example
+ * ```ts
+ * const next = zoomAboutCursor(scale, event.clientX - rect.left, 1.2, DEFAULT_ZOOM, durationTicks)
+ * ```
+ */
+declare function zoomAboutCursor(scale: XenoTimeScale, x: number, factor: number, bounds?: XenoZoomBounds, maxTick?: number): XenoTimeScaleState;
+/**
+ * Normalize a wheel event into a zoom factor.
+ *
+ * Two things every implementation has to get right and both surveyed incumbents get wrong today:
+ *
+ * 1. **Clamp `deltaY` before using it.** A single trackpad flick can deliver a delta in the
+ *    hundreds; feeding that to an exponential produces a zoom jump of several orders of magnitude in
+ *    one frame, and the user has no idea where they are. Clamping to ±10 first bounds one event to
+ *    one sane step.
+ * 2. **`ctrlKey` means pinch, not control-click.** The browser reports a trackpad pinch as a wheel
+ *    event with `ctrlKey: true` — including when the user never touched a key. Treating it as a
+ *    modifier makes pinch-zoom do something else entirely.
+ *
+ * @param deltaY - The raw wheel delta.
+ * @param sensitivity - Exponent scale. Default `0.01`.
+ * @returns A multiplier for {@link zoomAboutCursor}.
+ *
+ * @example
+ * ```ts
+ * wheelZoomFactor(-53)   // ≈ 1.43 — one notch in
+ * wheelZoomFactor(9999)  // clamped: never more than one step out
+ * ```
+ */
+declare function wheelZoomFactor(deltaY: number, sensitivity?: number): number;
+/**
+ * Is this wheel event a zoom, or a scroll?
+ *
+ * @param event - The wheel event's relevant fields.
+ * @param zoomModifier - Which key means zoom when it is not a pinch.
+ * @returns Whether to zoom.
+ */
+declare function isZoomGesture(event: {
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    altKey?: boolean;
+}, zoomModifier?: 'alt' | 'meta' | 'none'): boolean;
+/**
+ * Clamp horizontal scroll so the lane cannot be scrolled past the content.
+ *
+ * Allows scrolling until the content's end reaches the **left** edge is *not* the rule — the end is
+ * kept at least one lane-width from running away, so there is always something on screen.
+ *
+ * @param scrollTick - The requested scroll.
+ * @param pxPerTick - Current zoom.
+ * @param lanePx - Lane width.
+ * @param maxTick - Content duration.
+ * @returns A safe scroll position.
+ */
+declare function clampScroll(scrollTick: number, pxPerTick: number, lanePx: number, maxTick: number): number;
+/**
+ * The zoom that fits a tick range into the lane.
+ *
+ * @param fromTick - Range start.
+ * @param toTick - Range end.
+ * @param lanePx - Lane width.
+ * @param bounds - Zoom limits.
+ * @returns The state that shows exactly that range.
+ */
+declare function zoomToFit(fromTick: number, toTick: number, lanePx: number, bounds?: XenoZoomBounds): {
+    pxPerTick: number;
+    scrollTick: number;
+};
+/**
+ * Scroll the minimum distance needed to bring a tick into view.
+ *
+ * @param scale - Current scale.
+ * @param tick - The tick to reveal.
+ * @param marginPx - Keep this much clearance from the edge.
+ * @param maxTick - Content duration.
+ * @returns The new scroll tick.
+ */
+declare function scrollToReveal(scale: XenoTimeScale, tick: XenoTick, marginPx?: number, maxTick?: number): number;
+
+/**
+ * The `xeno.core.timeline` wire contract.
+ *
+ * The arrangement is **host-owned and read-only**. The panel renders a projection of it and emits
+ * {@link XenoTimelineOp} intents; it never mutates a clip, never decodes a frame, and never asks for
+ * a capability beyond `storage.local`. Lane pixels arrive through the tile round-trip, which is the
+ * Layers thumbnail round-trip generalized: *pixel access stays host-side.*
+ *
+ * @module
+ */
+
+/** What a track is for. Drives default adornments only — the host's own type is authoritative. */
+type XenoTrackKind = 'video' | 'audio' | 'midi' | 'automation' | 'subtitle' | 'other';
+/** One track / lane. */
+interface XenoTrack {
+    id: string;
+    name: string;
+    kind: XenoTrackKind;
+    /**
+     * The host's own type string, carried **verbatim and never interpreted**.
+     *
+     * The panel round-trips it in every op so a host can tell its own subtypes apart without the
+     * panel needing to learn a vocabulary that differs per product.
+     */
+    nativeType?: string;
+    /** Row height in CSS px. Variable per track — the reason row layout is a prefix sum. */
+    heightPx: number;
+    /**
+     * Clip ids on this track, **in start order**.
+     *
+     * 🔴 The bridge pre-builds this join. The alternative — filtering the clip map by `trackId` on
+     * every render — is O(tracks × clips) per frame, which is what makes the reference implementation
+     * stall at a few hundred clips. Ordering is also what lets culling walk backwards and stop early.
+     */
+    clipIds: string[];
+    muted?: boolean;
+    solo?: boolean;
+    locked?: boolean;
+    visible?: boolean;
+    armed?: boolean;
+    targeted?: boolean;
+    /** A colour token, not a raw hex — the panel is monochrome and the host owns accent policy. */
+    color?: string;
+    /** Collapsed to a header with no lane. */
+    collapsed?: boolean;
+}
+/** A clip's fade shape. */
+interface XenoClipFade {
+    /** Length in ticks from the clip's own edge. */
+    ticks: number;
+    curve?: 'linear' | 'equalPower' | 'exponential';
+}
+/** One clip on a track. */
+interface XenoClip {
+    id: string;
+    trackId: string;
+    /** Position on the timeline. Integer ticks, always. */
+    startTick: XenoTick;
+    /** Exclusive end. `endTick - startTick` is the duration. */
+    endTick: XenoTick;
+    name?: string;
+    /**
+     * Where the clip reads from within its source.
+     *
+     * **Absence disables slip and slide**, because without a source window there is nothing to slide
+     * within — and offering a tool that silently does nothing is worse than not offering it.
+     */
+    sourceInTick?: XenoTick;
+    sourceOutTick?: XenoTick;
+    /** The source this clip reads. Part of the tile cache key. */
+    sourceId?: string;
+    /** Clips that move with this one — an A/V pair. */
+    linkedIds?: string[];
+    /**
+     * Keyframe positions, **pre-flattened by the host**.
+     *
+     * The panel draws diamonds; it never walks a property tree to find them.
+     */
+    keyframeTicks?: XenoTick[];
+    fadeIn?: XenoClipFade;
+    fadeOut?: XenoClipFade;
+    /** Opaque key naming the lane content, for the tile round-trip. */
+    tileKey?: string;
+    color?: string;
+    /** Short badges drawn on the clip at the largest render tier. */
+    adornments?: string[];
+    locked?: boolean;
+    /** Per-clip capability overrides. Absent means "whatever the track allows". */
+    caps?: {
+        move?: boolean;
+        trim?: boolean;
+        split?: boolean;
+        delete?: boolean;
+    };
+}
+/** A named point in time. */
+interface XenoMarker {
+    id: string;
+    tick: XenoTick;
+    name?: string;
+    color?: string;
+    /** A range marker, when it has an end. */
+    endTick?: XenoTick;
+}
+/** A host-drawn strip over a time range — cache bars, loop brace, punch region. */
+interface XenoOverlaySpan {
+    id: string;
+    startTick: XenoTick;
+    endTick: XenoTick;
+    kind: string;
+    /** Which track, or the ruler when absent. */
+    trackId?: string;
+    label?: string;
+}
+/** The whole arrangement. Host-owned, read-only, re-walked only when `rev` changes. */
+interface XenoArrangement {
+    timebase: XenoTimebase;
+    durationTicks: number;
+    tracks: XenoTrack[];
+    /** Every clip, by id. Tracks reference them through `clipIds`. */
+    clips: Record<string, XenoClip>;
+    markers?: XenoMarker[];
+    /** Monotonic. The panel re-walks only when this moves — the throttled re-read gate. */
+    rev: number;
+}
+/** How a trim affects everything downstream. */
+type XenoTrimMode = 'standard' | 'ripple' | 'roll';
+/**
+ * A requested mutation. **An intent, never a mutation** — the host may refuse, clamp, or
+ * reinterpret it, and the panel renders nothing until a new `arrangement` arrives.
+ */
+type XenoTimelineOp = {
+    kind: 'move';
+    clipIds: string[];
+    deltaTicks: number;
+    toTrackId?: string;
+} | {
+    kind: 'trim';
+    clipId: string;
+    edge: 'start' | 'end';
+    toTick: XenoTick;
+    mode: XenoTrimMode;
+} | {
+    kind: 'split';
+    clipIds: string[];
+    atTick: XenoTick;
+} | {
+    kind: 'splitAll';
+    atTick: XenoTick;
+} | {
+    kind: 'delete';
+    clipIds: string[];
+    ripple?: boolean;
+} | {
+    kind: 'duplicate';
+    clipIds: string[];
+    deltaTicks: number;
+} | {
+    kind: 'slip';
+    clipId: string;
+    deltaTicks: number;
+} | {
+    kind: 'slide';
+    clipId: string;
+    deltaTicks: number;
+} | {
+    kind: 'setTrackProp';
+    trackId: string;
+    prop: 'muted' | 'solo' | 'locked' | 'visible' | 'armed' | 'targeted';
+    value: boolean;
+} | {
+    kind: 'setTrackHeight';
+    trackId: string;
+    heightPx: number;
+} | {
+    kind: 'reorderTrack';
+    trackId: string;
+    toIndex: number;
+} | {
+    kind: 'addMarker';
+    tick: XenoTick;
+    name?: string;
+} | {
+    kind: 'moveMarker';
+    markerId: string;
+    toTick: XenoTick;
+} | {
+    kind: 'removeMarker';
+    markerId: string;
+};
+/** The panel's ask for lane pixels. */
+interface XenoLaneTileRequest {
+    /** Cache key. Derived from SOURCE position — see `tiles.ts`. */
+    key: string;
+    clipId: string;
+    trackId: string;
+    /** The SOURCE range this tile covers, not the screen range. */
+    startTick: XenoTick;
+    endTick: XenoTick;
+    widthPx: number;
+    heightPx: number;
+    dpr: number;
+}
+/** The host's answer. The panel **blits it and never interprets it**. */
+interface XenoLaneTile {
+    key: string;
+    /** `null` means "there is genuinely nothing to draw" — distinct from "not asked yet". */
+    bitmap: ImageBitmap | ImageData | null;
+}
+/** What is selected. */
+interface XenoTimelineSelection {
+    clipIds: string[];
+    trackIds?: string[];
+    /** A time range selection, when the user dragged in the ruler. */
+    range?: {
+        startTick: XenoTick;
+        endTick: XenoTick;
+    };
+}
+/** What is on screen. Emitted so a host can prefetch decode and render caches. */
+interface XenoTimelineViewport {
+    startTick: XenoTick;
+    endTick: XenoTick;
+    pxPerTick: number;
+    scrollTopPx: number;
+    /** Track ids currently rendered, after row virtualization. */
+    trackIds: string[];
+}
+/** The active tool. Frozen at mousedown for the duration of a gesture. */
+type XenoTimelineTool = 'select' | 'razor' | 'ripple' | 'roll' | 'slip' | 'slide' | 'hand' | 'zoom';
+/** Snapping mode. */
+type XenoSnapMode = 'off' | 'grid' | 'targets' | 'both';
+/**
+ * Are two clips overlapping?
+ *
+ * Half-open intervals: a clip ending exactly where the next begins is **adjacent, not overlapping**.
+ * Getting this wrong makes every butt-joined cut in a sequence report a collision.
+ *
+ * @param a - One clip.
+ * @param b - Another.
+ * @returns Whether they genuinely overlap.
+ */
+declare function clipsOverlap(a: {
+    startTick: number;
+    endTick: number;
+}, b: {
+    startTick: number;
+    endTick: number;
+}): boolean;
+/** A clip's duration in ticks. */
+declare function clipDuration(clip: XenoClip): number;
+/**
+ * Can this clip be slipped or slid?
+ *
+ * Only when the host declared a source window. Offering the tool without one produces a gesture that
+ * appears to work and changes nothing.
+ */
+declare function hasSourceWindow(clip: XenoClip): boolean;
+
+/**
+ * Row virtualization and clip culling — **both from day one**, not as a later optimization.
+ *
+ * The reference implementation has neither: it renders every track and every clip, and its
+ * purpose-built virtualizer is dead code that was never wired up. The parity gate is 50 tracks ×
+ * 2000 clips, which is not reachable by rendering 2000 rectangles per frame.
+ *
+ * @module
+ */
+
+/** Where each track sits vertically. */
+interface XenoRowLayout {
+    /** `offsets[i]` is the top of track `i`; `offsets[n]` is the total height. One entry longer. */
+    offsets: Float64Array;
+    /** Total content height in CSS px. */
+    totalPx: number;
+}
+/**
+ * Build the row offset table.
+ *
+ * A prefix sum plus binary search, which is what every shipping virtualizer converged on for
+ * variable heights — vertical layout is a partition, so nothing fancier is warranted. A collapsed
+ * track keeps a header row but no lane.
+ *
+ * @param tracks - The tracks, in display order.
+ * @param collapsedPx - Height of a collapsed track's header.
+ * @returns Offsets and total height.
+ *
+ * @example
+ * ```ts
+ * const rows = buildRowLayout(tracks)
+ * const { first, last } = visibleRows(rows, scrollTopPx, viewportHeightPx)
+ * ```
+ */
+declare function buildRowLayout(tracks: readonly XenoTrack[], collapsedPx?: number): XenoRowLayout;
+/**
+ * Which rows intersect the viewport.
+ *
+ * 🔴 The rejection test uses a track's **whole height**, not just its top. Testing only the top
+ * makes a row disappear the instant it is one pixel above the fold, so the topmost track flickers
+ * out while half of it is still visible.
+ *
+ * @param layout - From {@link buildRowLayout}.
+ * @param scrollTopPx - Vertical scroll.
+ * @param viewportPx - Visible height.
+ * @param overscan - Extra rows above and below. Default 1.
+ * @returns Inclusive `first`, exclusive `last`.
+ */
+declare function visibleRows(layout: XenoRowLayout, scrollTopPx: number, viewportPx: number, overscan?: number): {
+    first: number;
+    last: number;
+};
+/** The row containing a y offset, or -1. */
+declare function rowAtY(layout: XenoRowLayout, y: number): number;
+/**
+ * Clips of one track that intersect the visible tick window.
+ *
+ * 🔴 **This walks BACKWARD, and that is the whole point.** The obvious implementation —
+ * binary-search to the first clip whose `startTick >= viewportStart`, then scan forward — silently
+ * drops the clip that *begins before the viewport and extends into it*. On a timeline that is the
+ * long clip you are currently looking at: scroll into the middle of a five-minute take and it
+ * vanishes.
+ *
+ * Because clips on one track are non-overlapping and ordered, walking left from the last clip
+ * starting before `viewportEnd` and stopping at the first clip that ends at or before
+ * `viewportStart` is **provably complete** — the straddling clip is the last one visited before the
+ * break. O(log n + k), and it needs no extra index.
+ *
+ * @param track - The track, with `clipIds` in start order.
+ * @param clips - The clip map.
+ * @param startTick - Viewport start.
+ * @param endTick - Viewport end.
+ * @returns The visible clips, in display order.
+ *
+ * @example
+ * ```ts
+ * const visible = visibleClips(track, arrangement.clips, scale.scrollTick, scale.endTick)
+ * ```
+ */
+declare function visibleClips(track: XenoTrack, clips: Readonly<Record<string, XenoClip>>, startTick: number, endTick: number): XenoClip[];
+/** How much detail a clip's width can carry. */
+type XenoRenderTier = 'sliver' | 'compact' | 'full';
+/**
+ * Pick a render tier from a clip's pixel width.
+ *
+ * Below the first breakpoint a clip is a bare rectangle: no label, no waveform, no keyframes, no
+ * fade handles. Drawing text into eight pixels costs a text-shaping pass to produce an ellipsis.
+ *
+ * @param widthPx - The clip's drawn width.
+ * @param breakpoints - `[compact, full]`. Default `[40, 120]`.
+ * @returns The tier.
+ */
+declare function renderTier(widthPx: number, breakpoints?: readonly [number, number]): XenoRenderTier;
+/**
+ * Collapse clips that would land on the same pixel column.
+ *
+ * At a zoom where a whole sequence fits on screen, a thousand clips occupy a few hundred pixels and
+ * most draw calls land on a column already painted. Keeping one per column turns "draw every clip"
+ * into "draw at most lane-width clips" and is worth more than any smarter search.
+ *
+ * @param clips - Visible clips, in order.
+ * @param scale - The scale.
+ * @param minGapPx - Minimum distance between kept clips. Default 1.
+ * @returns The clips worth drawing.
+ */
+declare function dedupeByColumn(clips: readonly XenoClip[], scale: XenoTimeScale, minGapPx?: number): XenoClip[];
+/** One track's worth of what to draw. */
+interface XenoVisibleTrack {
+    track: XenoTrack;
+    index: number;
+    /** Top of this row in content space. */
+    topPx: number;
+    heightPx: number;
+    clips: XenoClip[];
+}
+/**
+ * Everything on screen, culled on both axes.
+ *
+ * @param arrangement - The host's arrangement.
+ * @param scale - The current scale.
+ * @param options - Overscan, collapsed height, dedupe.
+ * @returns Visible tracks with their visible clips.
+ */
+declare function computeVisible(arrangement: XenoArrangement, scale: XenoTimeScale, options?: {
+    overscan?: number;
+    collapsedPx?: number;
+    dedupe?: boolean;
+    rulerPx?: number;
+}): {
+    rows: XenoRowLayout;
+    tracks: XenoVisibleTrack[];
+};
+
+/**
+ * Snapping — **the threshold is constant in SCREEN space, always.**
+ *
+ * A threshold expressed in time is unusable, and the numbers say why. With a fixed 50 ms window:
+ *
+ * | zoom | 10 px is | 50 ms is |
+ * |---|---|---|
+ * | far out | 5 s | **0.1 px** — snapping never fires |
+ * | normal | 50 ms | 10 px ✓ |
+ * | far in | 0.2 ms | **2205 px** — everything snaps |
+ *
+ * So the threshold is declared in CSS pixels and converted through the scale on every call. A DAW
+ * that gets this right documents the second reason too: a magnetic distance also *"helps to avoid
+ * snapping to somewhere the user can't see — i.e. I clicked on a region and it disappeared."*
+ *
+ * @module
+ */
+
+/** Something a drag can snap to. */
+interface XenoSnapCandidate {
+    tick: XenoTick;
+    kind: 'grid' | 'clipStart' | 'clipEnd' | 'playhead' | 'marker' | 'origin';
+    /** For reporting which clip won, so the view can highlight it. */
+    id?: string;
+}
+/** A resolved snap. */
+interface XenoSnapResult {
+    /** The delta to apply — **snapped, then returned as a delta**. */
+    deltaTicks: number;
+    /** What it snapped to, or `null` when nothing was near enough. */
+    target: XenoSnapCandidate | null;
+    /** Which of the dragged edges did the snapping. */
+    sourceTick?: XenoTick;
+}
+/** Snap configuration. */
+interface XenoSnapConfig {
+    mode: XenoSnapMode;
+    /** In CSS px. 8–12 is the consensus band; trim wants tighter than move. */
+    thresholdPx: number;
+    /** Grid spacing in ticks. `0` disables grid snapping. */
+    gridTicks: number;
+}
+/** Sensible defaults. Trim uses a tighter threshold than move — a frame matters more at an edge. */
+declare const DEFAULT_SNAP: XenoSnapConfig;
+/** The tighter threshold used while trimming. */
+declare const TRIM_SNAP_PX = 5;
+/**
+ * Collect snap targets from the arrangement.
+ *
+ * 🔴 The dragged clips' own edges are **excluded**. Without that a clip snaps to itself, the delta
+ * resolves to zero, and the drag feels stuck — which reads as a broken timeline rather than as
+ * snapping.
+ *
+ * @param arrangement - The host's arrangement.
+ * @param excludeClipIds - The clips being dragged.
+ * @param playheadTick - The playhead, added as a target only for this query.
+ * @param window - Only collect targets in this tick range.
+ * @returns Candidates, unsorted.
+ */
+declare function collectSnapTargets(arrangement: XenoArrangement, excludeClipIds: readonly string[], playheadTick: XenoTick | null, window: {
+    startTick: number;
+    endTick: number;
+}): XenoSnapCandidate[];
+/**
+ * Snap a **delta**, given every edge that is moving.
+ *
+ * 🔴 Snapping the *position* of one clip is wrong when several are selected: the group would tear,
+ * because each clip would land on its own nearest target. Snapping the shared **delta** keeps the
+ * selection rigid — every edge is tested against every candidate, the closest pairing wins, and the
+ * whole group moves by that one delta.
+ *
+ * @param sourceTicks - Every edge that is moving, at its ORIGINAL position.
+ * @param rawDelta - The unsnapped delta from the pointer.
+ * @param candidates - Targets from {@link collectSnapTargets}.
+ * @param scale - For the screen-space threshold.
+ * @param config - Mode, threshold, grid.
+ * @returns The delta to apply and what it snapped to.
+ *
+ * @example
+ * ```ts
+ * const snap = snapDelta(
+ *   selected.flatMap((c) => [c.startTick, c.endTick]),
+ *   rawDelta, candidates, scale, DEFAULT_SNAP,
+ * )
+ * ```
+ */
+declare function snapDelta(sourceTicks: readonly XenoTick[], rawDelta: number, candidates: readonly XenoSnapCandidate[], scale: XenoTimeScale, config?: XenoSnapConfig): XenoSnapResult;
+/**
+ * Snap a single absolute tick — for a trim edge, a marker drag, or a razor cut.
+ *
+ * @param tick - The unsnapped position.
+ * @param candidates - Targets.
+ * @param scale - For the threshold.
+ * @param config - Mode, threshold, grid.
+ * @returns The snapped tick and its target.
+ */
+declare function snapTick(tick: number, candidates: readonly XenoSnapCandidate[], scale: XenoTimeScale, config?: XenoSnapConfig): {
+    tick: XenoTick;
+    target: XenoSnapCandidate | null;
+};
+/**
+ * Should snapping be suppressed at this zoom?
+ *
+ * Once a single tick is wide enough to click precisely, snapping stops helping and starts fighting
+ * the user — they can already hit the frame they want, and the magnet drags them off it. A shipping
+ * NLE disables snapping entirely past this point for exactly that reason.
+ *
+ * @param scale - Current scale.
+ * @param ticksPerFrame - Ticks in one displayable frame. Default 1.
+ * @returns Whether to turn snapping off.
+ */
+declare function snapWouldFight(scale: XenoTimeScale, ticksPerFrame?: number): boolean;
+/**
+ * Apply the snap-invert modifier.
+ *
+ * Held, it **inverts** rather than disables: a user who works with snapping off still wants a way to
+ * land exactly on a cut. This is also the one modifier that is re-read on every move rather than
+ * frozen at mousedown — every surveyed product lets it change mid-drag.
+ *
+ * @param config - The configured snapping.
+ * @param inverted - Whether the modifier is down right now.
+ * @returns The effective config.
+ */
+declare function withSnapModifier(config: XenoSnapConfig, inverted: boolean): XenoSnapConfig;
+
+/**
+ * The gesture state machine — **mode frozen at mousedown, bookkeeping in one object.**
+ *
+ * ## The two bugs this file exists to prevent
+ *
+ * 1. **Re-deciding the mode mid-drag.** If the handler asks "am I over an edge?" on every move, then
+ *    a move that starts in the middle of a clip and passes over its edge silently becomes a trim.
+ *    Every shipping editor instead instantiates a gesture *object* at button-press, chosen once by
+ *    hit-target, and never re-decides. Here that object is {@link XenoDragState} and the decision is
+ *    {@link beginDrag}.
+ *
+ * 2. **Bookkeeping in closure locals.** The reference implementation keeps drag state in variables
+ *    captured by the move handler, and has a documented bug where the commit is dropped because a
+ *    re-render replaced the closure. State lives in **one plain object owned by the caller** — a ref,
+ *    never a captured local — so a re-render cannot lose it.
+ *
+ * ## One undo entry per drag
+ *
+ * The model is never mutated during a gesture. `update()` produces a **preview** the renderer reads
+ * through; only `commit()` returns an op. A cancel is therefore free — nothing was written — and a
+ * drag that never moved returns `null`, so a click-to-select can never leave an undo entry behind.
+ *
+ * @module
+ */
+
+/**
+ * Movement, in CSS px, before a press becomes a drag.
+ *
+ * Compared **squared**, so no `sqrt` runs per pointermove. Below this a press is a click: without a
+ * dead zone, magnet snapping nudges the clip during a click-to-select, and at normal zoom a
+ * sub-pixel nudge is already one or two frames — committing that creates a tiny accidental edit.
+ */
+declare const DRAG_THRESHOLD_PX = 4;
+/** Width of the trim grab zone at each clip edge, in CSS px. */
+declare const EDGE_ZONE_PX = 10;
+/**
+ * Below this clip width the edge zones are **hidden entirely**.
+ *
+ * Two 10 px handles on a 24 px clip leave 4 px of body, so the clip becomes un-draggable — the
+ * gesture the user wants most is the one they can no longer start.
+ */
+declare const EDGE_ZONE_MIN_CLIP_PX: number;
+/** The kind of gesture, decided once. */
+type XenoDragKind = 'move' | 'trimStart' | 'trimEnd' | 'marquee' | 'scrub' | 'pan' | 'trackHeight' | 'marker';
+/** What was under the pointer at mousedown. */
+interface XenoHitTarget {
+    kind: 'clip' | 'clipEdgeStart' | 'clipEdgeEnd' | 'lane' | 'ruler' | 'trackDivider' | 'marker';
+    clipId?: string;
+    trackId?: string;
+    markerId?: string;
+}
+/**
+ * Decide which edge zone — if any — a pointer is in.
+ *
+ * @param offsetPx - Pointer distance from the clip's left edge.
+ * @param widthPx - The clip's drawn width.
+ * @returns The zone, or `null` for the body.
+ *
+ * @example
+ * ```ts
+ * edgeZone(3, 200)  // → 'start'
+ * edgeZone(3, 24)   // → null — too narrow to carry handles
+ * ```
+ */
+declare function edgeZone(offsetPx: number, widthPx: number): 'start' | 'end' | null;
+/** Modifier keys, split by when they are read. */
+interface XenoDragModifiers {
+    /** Add to selection. Read at mousedown — it changes *what* the gesture is. */
+    additive?: boolean;
+    /** Copy rather than move. Read at mousedown. */
+    copy?: boolean;
+    /** Invert snapping. **Re-read on every move** — every product lets this change mid-drag. */
+    snapInvert?: boolean;
+    /** Constrain to one axis. Re-read on every move. */
+    constrain?: boolean;
+}
+/**
+ * Everything a drag needs to remember.
+ *
+ * Owned by the caller and stored in a ref. Deliberately a plain, serializable-ish object rather than
+ * a class with captured state.
+ */
+interface XenoDragState {
+    kind: XenoDragKind;
+    tool: XenoTimelineTool;
+    /** Frozen at mousedown. */
+    startX: number;
+    startY: number;
+    startTick: XenoTick;
+    /** The clips this gesture moves. Frozen at mousedown. */
+    clipIds: string[];
+    /** Their original positions, so a preview is computed from the ORIGINAL, never cumulatively. */
+    origin: Record<string, {
+        startTick: XenoTick;
+        endTick: XenoTick;
+        trackId: string;
+    }>;
+    /** Track index the press started on, for cross-track drags. */
+    startTrackIndex: number;
+    /** Modifiers captured at mousedown. */
+    modifiers: XenoDragModifiers;
+    /** Set once the movement threshold is passed. */
+    moved: boolean;
+    /** Live delta after snapping. */
+    deltaTicks: number;
+    /** Live track delta for a cross-track move. */
+    deltaTracks: number;
+    /** For a trim: where the edge currently is. */
+    edgeTick?: XenoTick;
+    /** For a marquee: the live rectangle in content space. */
+    marquee?: {
+        fromTick: number;
+        toTick: number;
+        fromY: number;
+        toY: number;
+    };
+    markerId?: string;
+    trackId?: string;
+    /** For a track-height drag. */
+    startHeightPx?: number;
+}
+/** Options for {@link beginDrag}. */
+interface BeginDragOptions {
+    target: XenoHitTarget;
+    tool: XenoTimelineTool;
+    x: number;
+    y: number;
+    tick: XenoTick;
+    trackIndex: number;
+    /** Clips that will move — the selection, or just the pressed clip. */
+    clips: readonly XenoClip[];
+    modifiers?: XenoDragModifiers;
+    startHeightPx?: number;
+}
+/**
+ * Start a gesture, choosing its kind **once**.
+ *
+ * @param options - What was hit, which tool is active, and where.
+ * @returns Frozen drag state, or `null` when this press starts no gesture.
+ *
+ * @example
+ * ```ts
+ * dragRef.current = beginDrag({ target, tool, x, y, tick, trackIndex, clips: selected })
+ * ```
+ */
+declare function beginDrag(options: BeginDragOptions): XenoDragState | null;
+/**
+ * Has the press travelled far enough to be a drag?
+ *
+ * @param state - The gesture.
+ * @param x - Current pointer x.
+ * @param y - Current pointer y.
+ * @returns Whether the threshold is passed.
+ */
+declare function passedThreshold(state: XenoDragState, x: number, y: number): boolean;
+/** The preview a renderer reads through. The model is untouched. */
+interface XenoDragPreview {
+    /** Clip id → its previewed position. */
+    clips: Record<string, {
+        startTick: XenoTick;
+        endTick: XenoTick;
+        trackId: string;
+    }>;
+    marquee?: XenoDragState['marquee'];
+    /** For a scrub. */
+    playheadTick?: XenoTick;
+}
+/**
+ * Compute the preview for the current pointer position.
+ *
+ * 🔴 Always derived from `state.origin`, **never from the previous preview**. Accumulating deltas
+ * makes a drag that crosses a snap target drift permanently, because the snap correction is applied
+ * to an already-corrected position.
+ *
+ * @param state - The gesture.
+ * @param deltaTicks - The snapped horizontal delta.
+ * @param deltaTracks - The vertical track delta.
+ * @param tracksById - Track ids in display order, for cross-track moves.
+ * @returns The preview.
+ */
+declare function previewDrag(state: XenoDragState, deltaTicks: number, deltaTracks: number, trackIds: readonly string[]): XenoDragPreview;
+/**
+ * Turn a finished gesture into an op — or into nothing.
+ *
+ * 🔴 Returns `null` when the gesture never passed the threshold **or** when its net delta is zero.
+ * A click that selects, and a drag that returns exactly where it started, must both leave the undo
+ * stack untouched. An editor that records those makes undo useless: the user presses it and the
+ * document does not change.
+ *
+ * @param state - The finished gesture.
+ * @param trimMode - How a trim ripples. From the active tool.
+ * @returns One op, or `null`.
+ */
+declare function commitDrag(state: XenoDragState, trimMode?: XenoTrimMode): XenoTimelineOp | null;
+/**
+ * Which trim mode a tool implies.
+ *
+ * @param tool - The active tool.
+ * @returns The trim mode.
+ */
+declare function trimModeFor(tool: XenoTimelineTool): XenoTrimMode;
+/**
+ * Clips inside a marquee rectangle.
+ *
+ * @param marquee - The rectangle in content space.
+ * @param rows - Track top offsets, one longer than the track list.
+ * @param tracks - Track ids in display order.
+ * @param clips - Every clip.
+ * @returns Selected clip ids.
+ */
+declare function clipsInMarquee(marquee: NonNullable<XenoDragState['marquee']>, rows: {
+    offsets: Float64Array;
+}, tracks: readonly {
+    id: string;
+    clipIds: string[];
+}[], clips: Readonly<Record<string, XenoClip>>): string[];
+
+/**
+ * The lane-tile cache — **keyed by SOURCE position, never by screen position.**
+ *
+ * ## The rule, and what breaks without it
+ *
+ * A lane tile is a strip of waveform or filmstrip. If its cache key contains a screen x or a slot
+ * index, then **every one-pixel scroll misses**, every zoom step invalidates the whole cache, and
+ * trimming a clip's left edge makes all its thumbnails visibly shuffle. Key on
+ * `(sourceId, source tick range, quantized zoom, height)` and a scroll is free, a re-trim keeps its
+ * pixels, and two clips of the same source share tiles.
+ *
+ * Every implementation surveyed is source-keyed. One goes further and satisfies a request from any
+ * cached tile that **contains** it, which is why it renders wider than the viewport.
+ *
+ * ## Why tile widths are jittered
+ *
+ * With a fixed tile width, every track's tiles fall due on the same scroll pixel and one frame has
+ * to render all of them — a periodic stall exactly when the user is scrubbing. Multiplying the
+ * nominal width by a per-tile random factor in 1.4–1.8× de-synchronizes them, so the work spreads
+ * across frames. This is lifted directly from a shipping DAW, whose source comment says the same.
+ *
+ * @module
+ */
+
+/** A tile held in the cache. */
+interface XenoCachedTile {
+    key: string;
+    sourceId: string;
+    /** SOURCE tick range this tile covers. */
+    startTick: number;
+    endTick: number;
+    /** Quantized zoom the tile was rendered at. */
+    zoomBucket: number;
+    heightPx: number;
+    bitmap: ImageBitmap | ImageData | null;
+    /** Approximate bytes, for the budget. */
+    bytes: number;
+    /** Monotonic counter for LRU. */
+    usedAt: number;
+}
+/** Cache configuration. */
+interface XenoTileCacheOptions {
+    /**
+     * Byte budget.
+     *
+     * A **byte** budget rather than a count: row heights are user-variable, so a fixed tile count can
+     * mean 4 MB or 400 MB depending on how tall the user made their tracks.
+     */
+    maxBytes?: number;
+    /** Injectable RNG, so the jitter is testable. */
+    random?: () => number;
+}
+/**
+ * Quantize zoom to a power-of-two bucket.
+ *
+ * Without this the key changes on **every frame of a zoom gesture** and the cache never hits during
+ * the one interaction that most needs it. A tile rendered at 1.3× the current zoom is visually fine;
+ * one rendered at 8× is not.
+ *
+ * @param pxPerTick - Current zoom.
+ * @returns The bucket, as an integer exponent.
+ */
+declare function zoomBucket(pxPerTick: number): number;
+/**
+ * Build a tile's cache key.
+ *
+ * Everything in it is source-space or style. **No screen coordinate appears.**
+ *
+ * @param parts - Source identity, source range, zoom bucket, height.
+ * @returns The key.
+ *
+ * @example
+ * ```ts
+ * tileKey({ sourceId: 'take-3', startTick: 0, endTick: 4800, zoomBucket: -3, heightPx: 64 })
+ * // → 'take-3|0|4800|-3|64'
+ * ```
+ */
+declare function tileKey(parts: {
+    sourceId: string;
+    startTick: number;
+    endTick: number;
+    zoomBucket: number;
+    heightPx: number;
+}): string;
+/**
+ * The source tick range a clip's visible portion reads from.
+ *
+ * A clip trimmed at the head reads from further into its source, so the tile grid must be anchored
+ * to the **source**, not to the clip's timeline position — otherwise dragging the left handle makes
+ * every thumbnail slide.
+ *
+ * @param clip - The clip.
+ * @param fromTick - Visible timeline start.
+ * @param toTick - Visible timeline end.
+ * @returns The source range, or `null` when the clip has no source window.
+ */
+declare function sourceRangeFor(clip: XenoClip, fromTick: number, toTick: number): {
+    startTick: number;
+    endTick: number;
+} | null;
+/**
+ * Quantize a source range onto a tile grid anchored at the source origin.
+ *
+ * @param range - A source range.
+ * @param tileTicks - Grid spacing.
+ * @returns The aligned tiles covering it.
+ */
+declare function alignToTileGrid(range: {
+    startTick: number;
+    endTick: number;
+}, tileTicks: number): {
+    startTick: number;
+    endTick: number;
+}[];
+/**
+ * The nominal tile width in ticks at the current zoom, jittered.
+ *
+ * @param scale - The scale.
+ * @param random - Injectable RNG.
+ * @returns Tile width in ticks.
+ */
+declare function tileWidthTicks(scale: XenoTimeScale, random?: () => number): number;
+/** A source-keyed, byte-budgeted, LRU tile cache. */
+declare class XenoTileCache {
+    private readonly tiles;
+    private readonly maxBytes;
+    private readonly random;
+    private clock;
+    private bytes;
+    /** Keys already asked for, so a request is never sent twice while one is in flight. */
+    private readonly pending;
+    constructor(options?: XenoTileCacheOptions);
+    /** Bytes currently held. */
+    get sizeBytes(): number;
+    /** Tiles currently held. */
+    get size(): number;
+    /**
+     * Find a usable tile for a request.
+     *
+     * 🔴 Satisfied by **containment**, not equality: a cached tile whose source range *covers* the
+     * request, at the same zoom bucket and height, is a hit. That is what makes scrolling produce hits
+     * instead of thrash, and it is why tiles are rendered wider than the viewport.
+     *
+     * @param request - Source identity, range, zoom bucket, height.
+     * @returns A tile that covers it, or `null`.
+     */
+    find(request: {
+        sourceId: string;
+        startTick: number;
+        endTick: number;
+        zoomBucket: number;
+        heightPx: number;
+    }): XenoCachedTile | null;
+    /**
+     * Record a tile the host returned.
+     *
+     * @param tile - Everything but the LRU stamp.
+     * @returns The stored tile.
+     */
+    put(tile: Omit<XenoCachedTile, 'usedAt' | 'bytes'> & {
+        bytes?: number;
+    }): XenoCachedTile;
+    /** Has a request for this key already gone out? */
+    isPending(key: string): boolean;
+    /**
+     * Mark a key as requested.
+     *
+     * Coalescing matters: without it, every frame of a scroll re-asks the host for the same tile, and
+     * a decode queue that is already behind falls further behind.
+     *
+     * @param key - The tile key.
+     * @returns `false` when a request was already outstanding.
+     */
+    markPending(key: string): boolean;
+    /** Abandon an outstanding request — the tile scrolled out of view. */
+    cancelPending(key: string): void;
+    /** A tile width in ticks for the current zoom, jittered. */
+    widthTicks(scale: XenoTimeScale): number;
+    /** Drop everything for one source — it was edited, or its media changed. */
+    invalidateSource(sourceId: string): number;
+    /** Release everything, closing bitmaps. */
+    clear(): void;
+    /** Evict least-recently-used tiles until inside the budget. */
+    private trim;
+    /** Remove one tile and release its bitmap. */
+    private evictOne;
+}
+/**
+ * Blit a tile, defensively.
+ *
+ * 🔴 **Every blit is wrapped.** A closed `ImageBitmap` throws on `drawImage`, and inside a React
+ * render that exception unmounts the subtree — the whole timeline disappears because one tile was
+ * evicted a frame early. A failed tile must degrade to a blank strip, not to a blank panel.
+ *
+ * @param ctx - The 2D context.
+ * @param tile - The tile.
+ * @param x - Destination x.
+ * @param y - Destination y.
+ * @param width - Destination width.
+ * @param height - Destination height.
+ * @returns Whether it drew.
+ */
+declare function blitTile(ctx: CanvasRenderingContext2D, tile: XenoCachedTile | null, x: number, y: number, width: number, height: number): boolean;
+
+/**
+ * The Timeline controller — framework-free, testable in Node.
+ *
+ * Owns the view state (scale, tool, selection, gesture) and **nothing else**. The arrangement is the
+ * host's; the clock is the host's; the pixels in a lane are the host's. What this produces is
+ * intents.
+ *
+ * 🔴 **One scroll source of truth.** Scroll and zoom live here, in `scale`, and are *emitted* on
+ * `viewport`. The panel never reads a scroll position back from a store it does not own — the
+ * reference implementation keeps a `scrollX` in its store that is written and never applied, and the
+ * resulting drift class is the single most confusing thing about that timeline.
+ *
+ * @module
+ */
+
+/** The host seam. */
+interface TimelineHostBridge {
+    emit(portId: string, value: unknown): void;
+    now?: () => number;
+    makeId?: () => string;
+}
+/** Construction options. */
+interface TimelineControllerOptions {
+    host: TimelineHostBridge;
+    tool?: XenoTimelineTool;
+    snapMode?: XenoSnapMode;
+    zoom?: XenoZoomBounds;
+    /** Throttle for `opPreview` and `viewport`, ms. */
+    throttleMs?: number;
+    crossTrackDrag?: boolean;
+    multiSelect?: boolean;
+    marquee?: boolean;
+    virtualize?: boolean;
+    rulerPx?: number;
+    gutterPx?: number;
+    tileCache?: XenoTileCache;
+}
+/** What the view renders. */
+interface TimelineViewState {
+    scale: XenoTimeScale;
+    arrangement: XenoArrangement | null;
+    timebase: XenoTimebase;
+    tool: XenoTimelineTool;
+    snap: XenoSnapConfig;
+    selection: XenoTimelineSelection;
+    /** Live gesture preview. The arrangement is untouched until the host answers. */
+    preview: XenoDragPreview | null;
+    /** Culled, virtualized rows. */
+    visible: XenoVisibleTrack[];
+    rows: XenoRowLayout;
+    playheadTick: XenoTick;
+    playing: boolean;
+    durationTicks: number;
+}
+/** Persisted preferences. **Never content.** */
+interface TimelinePanelState {
+    tool?: XenoTimelineTool;
+    snapMode?: XenoSnapMode;
+    pxPerTick?: number;
+    scrollTick?: number;
+    scrollTopPx?: number;
+}
+/** The Timeline panel controller. */
+declare class TimelineController {
+    private readonly host;
+    private readonly listeners;
+    private readonly now;
+    private readonly zoomBounds;
+    private readonly crossTrackDrag;
+    private readonly multiSelect;
+    private readonly marqueeEnabled;
+    private readonly virtualize;
+    private readonly rulerPx;
+    private scale;
+    private arrangement;
+    private clock;
+    private tool;
+    private snapMode;
+    private selection;
+    /**
+     * The live gesture.
+     *
+     * 🔴 A field on the controller, **not a closure local in an event handler**. The reference
+     * implementation keeps drag bookkeeping in variables the move handler closes over, and loses the
+     * commit whenever a re-render swaps the closure.
+     */
+    private drag;
+    private preview;
+    private readonly tiles;
+    private readonly emitPreview;
+    private readonly emitViewport;
+    private snapshot;
+    private cachedVisible;
+    constructor(options: TimelineControllerOptions);
+    subscribe: (listener: () => void) => (() => void);
+    getState: () => TimelineViewState;
+    private notify;
+    /**
+     * Install a new arrangement.
+     *
+     * The re-walk is gated on `rev`: an identical revision is a no-op, so a host that re-pushes on
+     * every animation frame costs nothing.
+     *
+     * @param arrangement - The host's arrangement.
+     * @returns Whether anything changed.
+     */
+    setArrangement(arrangement: XenoArrangement): boolean;
+    /**
+     * Install a playhead clock push.
+     *
+     * A malformed push is **ignored**, not installed: the last good clock keeps extrapolating, which
+     * is far better than a playhead that jumps to zero because one message was wrong.
+     */
+    setClock(clock: XenoPlayheadClock): void;
+    /** Install an externally-driven selection. */
+    setSelection(selection: XenoTimelineSelection, emit?: boolean): void;
+    /** Record a tile the host returned. */
+    setLaneTile(tile: XenoLaneTile): void;
+    /** The tile cache, for the renderer. */
+    get tileCache(): XenoTileCache;
+    /** Tell the controller how big it is. */
+    resize(widthPx: number, heightPx: number, gutterPx?: number): void;
+    /** The current scale. */
+    get timeScale(): XenoTimeScale;
+    /**
+     * Zoom about a pointer.
+     *
+     * @param x - Container-relative pointer x.
+     * @param factor - Zoom multiplier.
+     */
+    zoomAt(x: number, factor: number): void;
+    /**
+     * Handle a wheel event.
+     *
+     * @param event - Deltas, modifiers, and the container-relative x.
+     */
+    wheel(event: {
+        deltaX?: number;
+        deltaY?: number;
+        x: number;
+        zoom: boolean;
+    }): void;
+    /** Scroll by a tick delta and a pixel delta. */
+    scrollBy(deltaTicks: number, deltaTopPx: number): void;
+    /** Scroll to an absolute position. The ONE place scroll is written. */
+    scrollTo(scrollTick: number, scrollTopPx: number): void;
+    /** Fit the whole arrangement, or a range, into the lane. */
+    zoomToFitRange(fromTick?: number, toTick?: number): void;
+    /** Change the active tool. Ignored mid-gesture — the mode is frozen at mousedown. */
+    setTool(tool: XenoTimelineTool): void;
+    /** Change snapping. */
+    setSnapMode(mode: XenoSnapMode): void;
+    /** The snap config for the current zoom, with the visible grid. */
+    private snapConfig;
+    /**
+     * Begin a gesture.
+     *
+     * @param options - What was hit and where.
+     * @returns Whether a gesture started.
+     */
+    pointerDown(options: Omit<BeginDragOptions, 'tool' | 'clips'> & {
+        clips?: readonly XenoClip[];
+    }): boolean;
+    /**
+     * Update the live gesture.
+     *
+     * @param x - Container-relative pointer x.
+     * @param y - Container-relative pointer y.
+     * @param modifiers - Modifiers **as of now** — the snap invert is re-read every move.
+     */
+    pointerMove(x: number, y: number, modifiers?: {
+        snapInvert?: boolean;
+        constrain?: boolean;
+    }): void;
+    /**
+     * Finish the gesture, emitting **at most one** op.
+     *
+     * @returns The op that was emitted, or `null`.
+     */
+    pointerUp(): XenoTimelineOp | null;
+    /** Abandon the gesture. Nothing was mutated, so there is nothing to roll back. */
+    cancelDrag(): void;
+    /** Is a gesture live? */
+    get dragging(): boolean;
+    /** Split the selection, or every clip, at a tick. */
+    split(atTick: XenoTick, all?: boolean): XenoTimelineOp | null;
+    /** Delete the selection. */
+    deleteSelection(ripple?: boolean): XenoTimelineOp | null;
+    /** Emit any op. The single door for the view's buttons. */
+    dispatchOp(op: XenoTimelineOp): void;
+    private applySelection;
+    /** Select a clip, or add it to the selection. */
+    selectClip(clipId: string, additive?: boolean): void;
+    /** Clear the selection. */
+    clearSelection(): void;
+    /**
+     * Move the selection to an adjacent clip.
+     *
+     * Keyboard clip and track navigation, which none of the surveyed products has — and which is what
+     * makes the panel usable without a mouse at all.
+     *
+     * @param direction - Where to go.
+     * @returns The newly selected clip, or `null`.
+     */
+    navigate(direction: 'next' | 'previous' | 'up' | 'down'): XenoClip | null;
+    /** Scroll the minimum distance to bring a clip on screen. */
+    revealClip(clip: XenoClip): void;
+    /**
+     * The playhead right now.
+     *
+     * Dead-reckoned from the last host push, and **clamped against the LIVE duration every read** —
+     * an arrangement that shrinks while playing would otherwise leave the playhead extrapolating past
+     * the end of a document that no longer goes that far.
+     */
+    playheadTick(): XenoTick;
+    private clampToDuration;
+    /** The duration to clamp against; an unset duration must not clamp everything to zero. */
+    private durationOrMax;
+    /**
+     * Ask the host for any lane tiles the visible clips need.
+     *
+     * Requests are coalesced by key, so a scroll does not re-ask for a tile already in flight.
+     *
+     * @returns The requests emitted.
+     */
+    requestTiles(): XenoLaneTileRequest[];
+    private publishViewport;
+    /**
+     * The visible set, recomputed only when something that affects it moved.
+     *
+     * Computing it once per read rather than once per access is what keeps a render from doing the
+     * culling walk several times for the same frame.
+     */
+    private computeVisibleCached;
+    /** The clips a gesture on `clipId` should move. */
+    private gestureClips;
+    /** Every edge a gesture moves, for delta snapping. */
+    private gestureEdges;
+    /** Snap a bare tick, for the scrub. */
+    private snapAbsolute;
+    /** Preferences only — never the arrangement, never the selection, never a tile. */
+    serialize(): TimelinePanelState;
+    /** Restore preferences. */
+    deserialize(state: Partial<TimelinePanelState>): void;
+    /** Release timers, listeners and every cached bitmap. */
+    dispose(): void;
+}
+
+/**
+ * The `PanelModule` — what a host registers and mounts.
+ *
+ * Every line marked 🔴 is a shipped bug's fix. See `packages/panel-template/README.md`.
+ *
+ * @module
+ */
+
+/** Everything a renderer needs. */
+interface TimelineRenderContext {
+    controller: TimelineController;
+    config: TimelineRenderConfig;
+}
+/** Resolved, observed config. */
+interface TimelineRenderConfig {
+    trackHeightPx: number;
+    virtualize: boolean;
+}
+/** Options for {@link createTimelinePanel}. */
+interface CreateTimelinePanelOptions {
+    /** Override the renderer. Rarely needed. */
+    render?: (root: HTMLElement, context: TimelineRenderContext) => () => void;
+}
+/**
+ * Build the Timeline panel module.
+ *
+ * @param options - Optional renderer override.
+ * @returns The module.
+ */
+declare function createTimelinePanel(options?: CreateTimelinePanelOptions): PanelModule;
+/** The default Timeline panel module — view already wired. Register THIS. */
+declare const timelinePanel: PanelModule;
+
+/**
+ * The `xeno.core.timeline` manifest.
+ *
+ * **`storage.local` and nothing else.** A timeline is the panel most likely to be handed a
+ * capability it does not need — it draws waveforms and filmstrips, so `fs.read`, `gpu` and
+ * `lib.process` all look reasonable. None of them is. Lane pixels arrive through the tile
+ * round-trip, which is the Layers thumbnail round-trip generalized: *pixel access stays host-side.*
+ *
+ * @module
+ */
+
+/** The canonical manifest id. */
+declare const TIMELINE_PANEL_ID = "xeno.core.timeline";
+/** The `xeno.core.timeline` manifest. */
+declare const timelineManifest: PanelManifest;
+
+/**
+ * The ruler — a mixed-radix tick ladder, not a computed "nice numbers" step.
+ *
+ * ## Why not 1-2-5
+ *
+ * The classic nice-numbers algorithm (Heckbert, and d3's `ticks` after it) picks steps from
+ * 1·2·5 × 10ⁿ. That is right for a linear quantity and **wrong for time**, which is mixed-radix:
+ * 1000 ms/s, 60 s/min, 60 min/h, 24 h/day, plus 24/25/30/50/60 frames per second and 3/4/5/7 beats
+ * per bar. A 1-2-5 ladder produces a ruler marked every 20 seconds and every 50 minutes.
+ *
+ * Every shipping timeline surveyed uses a **hard-coded ladder** instead. So does this.
+ *
+ * ## Two details that are easy to get wrong
+ *
+ * - **Classify ticks by index, not by time modulo.** Deciding "is this a major tick?" with
+ *   `tick % majorStep === 0` drifts and drops ticks as soon as the step is not an exact divisor of
+ *   the origin. Counting position within a repeating pattern cannot drift.
+ * - **Start from a quantized floor**, so the first tick is on the ladder rather than wherever the
+ *   viewport happens to begin.
+ *
+ * Bars and beats are handled here as **formatting**: tick geometry stays linear wall-clock, so zoom
+ * remains a single scalar and hit-testing never inverts a tempo curve.
+ *
+ * @module
+ */
+
+/** How prominent a tick is. */
+type XenoTickWeight = 'major' | 'medium' | 'minor';
+/** One ruler tick. */
+interface XenoRulerTick {
+    tick: XenoTick;
+    x: number;
+    weight: XenoTickWeight;
+    /** Present on majors only — labelling every tick is unreadable and costs a shaping pass each. */
+    label?: string;
+}
+/**
+ * Minimum pixels between **labelled** ticks.
+ *
+ * The surveyed products land between 70 and 120 px, all of them describing it as an approximation of
+ * how wide the label text is. Timecode (`00:00:00:00`) is the widest thing this ruler draws, so this
+ * sits at the top of that band.
+ */
+declare const MIN_MAJOR_PX = 120;
+/** Minimum pixels between unlabelled minors. */
+declare const MIN_MINOR_PX = 8;
+/**
+ * Choose the ladder rung for the current zoom.
+ *
+ * @param scale - The scale.
+ * @param timebase - For frame and tempo awareness.
+ * @returns Major step in ticks, its subdivision count, and which subdivision is medium.
+ */
+declare function chooseRung(scale: XenoTimeScale, timebase: XenoTimebase): {
+    majorTicks: number;
+    subdivisions: number;
+    medium: number;
+};
+/**
+ * Generate the visible ruler ticks.
+ *
+ * @param scale - The scale.
+ * @param timebase - For the ladder and the labels.
+ * @param options - Label override.
+ * @returns Ticks, left to right.
+ *
+ * @example
+ * ```ts
+ * for (const t of rulerTicks(scale, timebase)) {
+ *   ctx.fillRect(Math.floor(t.x), 0, 1, t.weight === 'major' ? 10 : 5)
+ * }
+ * ```
+ */
+declare function rulerTicks(scale: XenoTimeScale, timebase: XenoTimebase, options?: {
+    label?: (tick: XenoTick) => string;
+}): XenoRulerTick[];
+/**
+ * The grid spacing snapping should use at this zoom.
+ *
+ * Derived from the same ladder the ruler draws, so the grid a user snaps to is **the grid they can
+ * see**. A 1/128 grid at a zoom showing whole bars is a grid nobody can aim at, and snapping to it
+ * feels random.
+ *
+ * @param scale - The scale.
+ * @param timebase - The timebase.
+ * @returns Grid spacing in ticks.
+ */
+declare function gridTicksFor(scale: XenoTimeScale, timebase: XenoTimebase): number;
+
+/**
+ * The Timeline view.
+ *
+ * Composes `@xenosystem/workbench/primitives`. **The host must import
+ * `@xenosystem/workbench/primitives.css`** or this renders unstyled with no error — the most common
+ * integration mistake, and the hardest to diagnose because nothing fails.
+ *
+ * Monochromatic per `DESIGN_SYSTEM.md`: rectangles with a corner radius, no circles, compact
+ * chrome, no colour except what the host declares on a clip.
+ *
+ * @module
+ */
+
+/** Props for {@link TimelinePanelView}. */
+interface TimelinePanelViewProps {
+    controller: TimelineController;
+    trackHeightPx?: number;
+    virtualize?: boolean;
+}
+/** The Timeline panel view. */
+declare function TimelinePanelView({ controller }: TimelinePanelViewProps): ReactNode;
+
+/**
+ * The `xeno.core.calendar` contract.
+ *
+ * ## Why this is a panel and not a table view mode
+ *
+ * **The visible window is an OUTPUT that drives the query.** For table, board and gallery the
+ * visible set is a *projection of an already-fetched result*; for calendar the window **is an input
+ * to the fetch** — month navigation derives `from`/`to` and those become the fetch key. That single
+ * port is the whole reason this is a sibling panel rather than a mode.
+ *
+ * ## 🔴 Landmine §6.7 — two wrong answers in shipped code
+ *
+ * - notes matches a day with `value === 'YYYY-MM-DD'`, so **any datetime, or any value with an
+ *   offset suffix, silently never renders at all**.
+ * - post derives a day with `toISOString().slice(0, 10)`, which is the day **in UTC** — so a
+ *   23:00-local event lands on the wrong day, invisibly, for everyone not at `UTC+0`.
+ *
+ * Both are structurally impossible here: `date` and `datetime` are different types, bucketing goes
+ * through `@xenosystem/data-core`'s zone-aware `bucketKey`, and `timeZone` is **mandatory** on the window.
+ *
+ * @module
+ */
+
+/** How the time axis is laid out. */
+type XenoCalendarViewMode = 'month' | 'week' | 'day' | 'agenda' | 'timeline';
+/** Every mode v1 implements. */
+declare const ALL_CALENDAR_MODES: readonly XenoCalendarViewMode[];
+/**
+ * The visible window — **the output that makes this a panel**.
+ *
+ * `timeZone` is mandatory, exactly as on `XenoWindow`. It is not defaulted anywhere, because a
+ * default is how both shipped bugs got in.
+ */
+interface XenoCalendarWindow {
+    /** Inclusive start, ISO 8601. */
+    from: string;
+    /** Exclusive end, ISO 8601. */
+    to: string;
+    /** The time column the window applies to. */
+    columnId: string;
+    /** IANA zone. **Mandatory.** */
+    timeZone: string;
+}
+/** One event, derived from a row. */
+interface XenoCalendarEvent {
+    /** The row id — identity comes from the result, never from a position. */
+    id: string;
+    /** Display title. */
+    title: string;
+    /** Start bucket key (`'2026-08-15'` for a day-grained view). */
+    startKey: string;
+    /** End bucket key. Equal to `startKey` for a single-day event. */
+    endKey: string;
+    /** Minutes from midnight, for timed events in week/day/timeline modes. `null` for all-day. */
+    startMinutes: number | null;
+    /** Minutes from midnight for the end. */
+    endMinutes: number | null;
+    /** The event spans more than one day. */
+    multiDay: boolean;
+    /** All-day (the source column is a `date`, or no time is present). */
+    allDay: boolean;
+    /** Pre-formatted extra fields for the chip. */
+    fields?: Record<string, string>;
+    /** Status value, for tone. */
+    status?: XenoValue;
+    /** The source row, for `rowActivate` and drag intents. */
+    row: XenoRow;
+}
+/** A day cell in month/week view. */
+interface XenoCalendarCell {
+    /** The day key. */
+    key: string;
+    /** Day of month. */
+    day: number;
+    /** The cell belongs to the displayed period (not a leading/trailing filler day). */
+    inPeriod: boolean;
+    /** Today, in the declared zone. */
+    today: boolean;
+    /** Events starting or spanning this day, after overlap packing. */
+    events: XenoCalendarEvent[];
+    /** How many events were hidden by `maxChipsPerCell`. */
+    overflow: number;
+}
+/** A drag-to-reschedule intent. The host writes. */
+interface XenoCalendarEdit {
+    rowId: string;
+    columnId: string;
+    /** The new start, ISO 8601 in the declared zone. */
+    value: string;
+    /** The previous value, so a host can build an undo entry without re-reading. */
+    previousValue: XenoValue;
+    /** Set when the event has an end column that moved with it. */
+    endColumnId?: string;
+    endValue?: string;
+    /** One gesture, one undo entry. */
+    gestureId: string;
+}
+/** Clicking an empty slot — the create affordance. */
+interface XenoCalendarSlotActivate {
+    /** The day key. */
+    date: string;
+    /** Minutes from midnight, in a timed view. */
+    time?: number;
+}
+/** The panel's serialized state. */
+interface CalendarPanelState {
+    viewMode: XenoCalendarViewMode;
+    /** The anchor date the view is centred on, as a day key. */
+    anchor?: string;
+    selection: string[];
+}
+/** What the controller exposes to its view. */
+interface CalendarViewState {
+    viewMode: XenoCalendarViewMode;
+    /** The current window — also what was last emitted. */
+    window: XenoCalendarWindow | null;
+    /** Day cells, for month/week/day. */
+    cells: XenoCalendarCell[];
+    /** Every event in the window, in start order — the agenda and timeline source. */
+    events: XenoCalendarEvent[];
+    /** Selected row ids. */
+    selection: string[];
+    /** No result, or no events in the window. */
+    empty: boolean;
+    /** The result was `partial`. */
+    partial: boolean;
+    /** A typed error from the result. */
+    errorMessage: string | null;
+    /** Set when the configured date column is missing or untyped. */
+    configProblem: string | null;
+}
+/** Days in a month, 1-indexed month. */
+declare function daysInMonth(year: number, month: number): number;
+/** A day key from calendar parts. */
+declare function dayKey(year: number, month: number, day: number): string;
+/** Parse a day key back into parts. Returns `null` for anything malformed. */
+declare function parseDayKey(key: string): {
+    year: number;
+    month: number;
+    day: number;
+} | null;
+/**
+ * ISO day-of-week for a day key, `1` = Monday … `7` = Sunday.
+ *
+ * Computed from the key's own calendar parts, never from a local `Date` — reading a day key through
+ * the runtime's zone is how a grid shifts by one column for half the world.
+ */
+declare function isoWeekday(key: string): number;
+/** Add days to a day key, staying in pure calendar arithmetic. */
+declare function addDays(key: string, days: number): string;
+/** Add months to a day key, CLAMPING the day (31 Mar − 1 month is 28 Feb, not 3 Mar). */
+declare function addMonths(key: string, months: number): string;
+/**
+ * The first cell of a month grid, honouring `firstDayOfWeek`.
+ *
+ * **Config, not a constant**: post is Monday-first, notes is Sunday-first. A calendar that assumes
+ * either is wrong for half its users.
+ */
+declare function gridStart(monthKey: string, firstDayOfWeek: number): string;
+/** The tone a status value maps to. Presentation only. */
+declare function statusTone(value: XenoValue): 'neutral' | 'success' | 'warning' | 'error';
+
+/**
+ * The Calendar controller.
+ *
+ * **The window is an OUTPUT.** Navigating a month derives `from`/`to` and emits both `window` and a
+ * `queryRequest` — the visible range *is* the fetch key. That is what makes this a panel rather than
+ * a table view mode.
+ *
+ * @module
+ */
+
+/** The host seam. */
+interface CalendarHostBridge {
+    emit(portId: string, value: unknown): void;
+    makeId?: () => string;
+    now?: () => number;
+}
+/** Construction options. */
+interface CalendarControllerOptions {
+    host: CalendarHostBridge;
+    initial?: Partial<CalendarPanelState>;
+    /** The start column. Without it the panel reports a config problem rather than rendering blank. */
+    dateColumnId?: string;
+    endDateColumnId?: string;
+    /**
+     * IANA zone, or `'local'` to resolve the runtime's.
+     *
+     * Explicit by design: the two shipped calendar bugs are both a zone nobody declared.
+     */
+    timeZone?: string;
+    viewMode?: XenoCalendarViewMode;
+    /** `1` = Monday (post), `7` = Sunday (notes). CONFIG — a calendar that assumes either is wrong. */
+    firstDayOfWeek?: number;
+    maxChipsPerCell?: number;
+    chipFields?: string[];
+    titleColumnId?: string;
+    statusColumnId?: string;
+    slotMinutes?: number;
+    allowDrag?: boolean;
+}
+/** The Calendar panel controller. */
+declare class CalendarController {
+    private readonly host;
+    private readonly makeId;
+    private readonly now;
+    private readonly listeners;
+    private readonly firstDayOfWeek;
+    private readonly maxChipsPerCell;
+    private readonly allowDrag;
+    private readonly derive;
+    private result;
+    private viewMode;
+    private anchor;
+    private selection;
+    private window;
+    private snapshot;
+    constructor(options: CalendarControllerOptions);
+    subscribe: (listener: () => void) => (() => void);
+    getState: () => CalendarViewState;
+    private notify;
+    /** Why the panel cannot render, as a sentence. A blank grid explains nothing. */
+    private configProblem;
+    /** Receive a result. */
+    setResult(result: XenoResultSet): void;
+    /** Receive an externally set window (a host driving navigation). Does not re-emit. */
+    setWindow(window: XenoCalendarWindow): void;
+    /** Receive a host-driven selection. */
+    setSelection(rowIds: readonly string[]): void;
+    /** Events derived from the current result. */
+    events(): XenoCalendarEvent[];
+    /** The visible day cells for the current mode. */
+    cells(events?: XenoCalendarEvent[]): XenoCalendarCell[];
+    /** Grid geometry for the current mode. `null` for agenda/timeline, which are not grids. */
+    private geometry;
+    /**
+     * The window the current view covers.
+     *
+     * Agenda and timeline follow the month, so navigation stays meaningful in every mode.
+     */
+    computeWindow(): XenoCalendarWindow | null;
+    /**
+     * Emit the window and the matching query.
+     *
+     * **This is the port that makes calendar a panel**: the visible range is the fetch key, so moving
+     * a month is a re-fetch, not a re-projection.
+     */
+    emitWindow(force?: boolean): XenoCalendarWindow | null;
+    /** Switch view mode and re-emit the window. */
+    setViewMode(mode: XenoCalendarViewMode): boolean;
+    /** Step forward or back by one period. */
+    navigate(direction: 1 | -1): void;
+    /** Jump to today, in the DECLARED zone — never the runtime's, unless that is what was declared. */
+    goToToday(): void;
+    /** Jump to a specific day. */
+    goToDate(key: string): boolean;
+    /** The anchor day key. */
+    anchorKey(): string;
+    /** Select events. */
+    select(rowIds: readonly string[], additive?: boolean): void;
+    /** Open an event. */
+    activateRow(rowId: string): boolean;
+    /** Click an empty slot — the create affordance. */
+    activateSlot(date: string, time?: number): boolean;
+    /**
+     * Drag-to-reschedule — an INTENT. The host writes and republishes.
+     *
+     * The new value carries the target day and, for a timed event, the original clock time: dropping
+     * an event on a day should move the day, not silently reset it to midnight.
+     *
+     * @returns `true` when an intent was emitted.
+     */
+    rescheduleTo(rowId: string, targetDate: string, targetMinutes?: number): boolean;
+    /** Ask the host to open a context menu. */
+    requestContextMenu(rowIds: readonly string[], x: number, y: number): void;
+    /** Serialize. View mode, anchor and selection — never a result, never events. */
+    serialize(): CalendarPanelState;
+    /** Restore. Does not emit. */
+    deserialize(state: Partial<CalendarPanelState>): void;
+    /** The resolved zone — exposed so a host can render it. */
+    timeZone(): string;
+    /** Drop listeners. */
+    dispose(): void;
+}
+
+/**
+ * The `PanelModule` — view wired inside the package (one React copy).
+ *
+ * @module
+ */
+
+/** Everything a renderer needs: the controller plus the resolved config. */
+interface CalendarRenderContext {
+    controller: CalendarController;
+    config: {
+        firstDayOfWeek: number;
+        emptyHint?: string;
+    };
+}
+/** Options for {@link createCalendarPanel}. */
+interface CreateCalendarPanelOptions {
+    /** Override the view. Rarely needed — mounting inside the package keeps React singular. */
+    render?: (root: HTMLElement, context: CalendarRenderContext) => () => void;
+}
+/**
+ * Build the Calendar panel module.
+ *
+ * @param options - Optional renderer override.
+ * @returns The module.
+ */
+declare function createCalendarPanel(options?: CreateCalendarPanelOptions): PanelModule;
+/** The default Calendar panel module — view already wired. Register THIS. */
+declare const calendarPanel: PanelModule;
+
+/**
+ * The `xeno.core.calendar` manifest.
+ *
+ * **`window` is an OUTPUT.** That port is why this is a panel and not a table view mode: the visible
+ * range drives the query rather than projecting an already-fetched result.
+ *
+ * @module
+ */
+
+/** The canonical manifest id. */
+declare const CALENDAR_PANEL_ID = "xeno.core.calendar";
+/** The `xeno.core.calendar` manifest. */
+declare const calendarManifest: PanelManifest;
+
+/**
+ * Event derivation and calendar layout — the calendar-only work.
+ *
+ * ## 🔴 The two shipped wrong answers this module refuses
+ *
+ * **notes** matches a day with `value === 'YYYY-MM-DD'`, so any datetime — or any value carrying an
+ * offset — silently never renders. **post** derives a day with `toISOString().slice(0, 10)`, which
+ * is the day in UTC, so a 23:00-local event lands on the wrong day for everyone not at `UTC+0`.
+ *
+ * Both are impossible here because bucketing goes through `@xenosystem/data-core`'s `parseTime` +
+ * `bucketKey`, which parse every ISO form and apply the zone **only to instants** — a `date` column
+ * is a calendar day everywhere and is never shifted.
+ *
+ * The rest — multi-day spans and overlap packing — is genuinely calendar-only.
+ *
+ * @module
+ */
+
+/** Options for {@link deriveEvents}. */
+interface DeriveOptions {
+    /** The start column. Required. */
+    dateColumnId: string;
+    /** The end column, for spans. */
+    endDateColumnId?: string;
+    /** IANA zone. **Mandatory** — a default is how both shipped bugs got in. */
+    timeZone: string;
+    /** Column supplying the chip title. Defaults to the first `identifier`/`string` column. */
+    titleColumnId?: string;
+    /** Extra columns to render on the chip. */
+    chipFields?: string[];
+    /** Column supplying status tone. */
+    statusColumnId?: string;
+}
+/**
+ * Derive events from a result.
+ *
+ * @param result - The result set.
+ * @param options - Column mapping + the mandatory zone.
+ * @returns Events in start order. A row whose date cannot be parsed is SKIPPED, not defaulted —
+ *   placing an unparseable row on today is worse than omitting it, because it looks correct.
+ */
+declare function deriveEvents(result: XenoResultSet, options: DeriveOptions): XenoCalendarEvent[];
+/** Options for {@link buildCells}. */
+interface BuildCellsOptions {
+    /** First day key of the grid. */
+    start: string;
+    /** How many days the grid covers. */
+    days: number;
+    /** The month the grid is "about", for the in-period flag. `null` in week/day views. */
+    periodMonth?: string | null;
+    /** Today's key, in the declared zone. */
+    today?: string;
+    /** Chips rendered before an overflow indicator appears. */
+    maxChipsPerCell?: number;
+}
+/**
+ * Lay events into day cells.
+ *
+ * A **multi-day event appears in every day it covers** — that is the whole point of a span, and it
+ * is why a naive `group by startKey` is wrong. Each cell then caps its chips and reports the
+ * remainder rather than silently truncating.
+ *
+ * @param events - Derived events.
+ * @param options - Grid geometry.
+ * @returns The cells, in grid order.
+ */
+declare function buildCells(events: readonly XenoCalendarEvent[], options: BuildCellsOptions): XenoCalendarCell[];
+/**
+ * Pack overlapping timed events into columns, for week/day views.
+ *
+ * Two events that overlap in time share a row's width; the packer assigns each the lowest column
+ * index not already taken by something it overlaps. Without it, overlapping events draw on top of
+ * each other and the lower one is invisible.
+ *
+ * @param events - Events for ONE day, in start order.
+ * @returns Each event with its column index and the total column count for that cluster.
+ */
+declare function packOverlaps(events: readonly XenoCalendarEvent[]): {
+    event: XenoCalendarEvent;
+    column: number;
+    columns: number;
+}[];
+/** Today's day key in a zone — never `new Date().toISOString().slice(0,10)`, which is UTC. */
+declare function todayKey(timeZone: string, now?: number): string;
+/** The week key range a day belongs to, honouring `firstDayOfWeek`. */
+declare function weekStart(key: string, firstDayOfWeek: number): string;
+/** Whether a row would be visible in a window — exported so a host can pre-filter. */
+declare function rowInWindow(row: XenoRow, columnId: string, column: XenoColumn | undefined, from: string, to: string): boolean;
+
+/**
+ * The Calendar panel view.
+ *
+ * Composes `@xenosystem/workbench/primitives`; the host must ensure `@xenosystem/workbench/primitives.css` is
+ * present.
+ *
+ * @module
+ */
+
+/** Props for {@link CalendarPanelView}. */
+interface CalendarPanelViewProps {
+    controller: CalendarController;
+    firstDayOfWeek?: number;
+    emptyHint?: string;
+}
+/** The Calendar panel view. */
+declare function CalendarPanelView({ controller, firstDayOfWeek, emptyHint, }: CalendarPanelViewProps): ReactNode;
+
+export { ALL_CALENDAR_MODES, type BeginDragOptions, type BuildCellsOptions, CALENDAR_PANEL_ID, CalendarController, type CalendarControllerOptions, type CalendarHostBridge, type CalendarPanelState, CalendarPanelView, type CalendarPanelViewProps, type CalendarRenderContext, type CalendarViewState, type CreateCalendarPanelOptions, type CreateTimelinePanelOptions, type CreateTransportPanelOptions, DEFAULT_SNAP, DEFAULT_ZOOM, DRAG_THRESHOLD_PX, type DeriveOptions, EDGE_ZONE_MIN_CLIP_PX, EDGE_ZONE_PX, MIN_MAJOR_PX, MIN_MINOR_PX, TIMELINE_PANEL_ID, TRIM_SNAP_PX, TimelineController, type TimelineControllerOptions, type TimelineHostBridge, type TimelinePanelState, TimelinePanelView, type TimelinePanelViewProps, type TimelineRenderConfig, type TimelineRenderContext, type TimelineViewState, type TransportKeyEvent, TransportPanelController, type TransportPanelControllerOptions, type TransportPanelSerialized, TransportPanelView, type TransportPanelViewProps, type XenoArrangement, type XenoCachedTile, type XenoCalendarCell, type XenoCalendarEdit, type XenoCalendarEvent, type XenoCalendarSlotActivate, type XenoCalendarViewMode, type XenoCalendarWindow, type XenoClip, type XenoClipFade, type XenoDragKind, type XenoDragModifiers, type XenoDragPreview, type XenoDragState, type XenoHitTarget, type XenoLaneTile, type XenoLaneTileRequest, type XenoMarker, type XenoOverlaySpan, type XenoRenderTier, type XenoRowLayout, type XenoRulerTick, type XenoSnapCandidate, type XenoSnapConfig, type XenoSnapMode, type XenoSnapResult, type XenoTickWeight, XenoTileCache, type XenoTileCacheOptions, XenoTimeScale, type XenoTimeScaleGeometry, type XenoTimeScaleState, type XenoTimelineOp, type XenoTimelineSelection, type XenoTimelineTool, type XenoTimelineViewport, type XenoTrack, type XenoTrackKind, type XenoTrimMode, type XenoVisibleTrack, type XenoZoomBounds, addDays, addMonths, alignToTileGrid, beginDrag, blitTile, buildCells, buildRowLayout, calendarManifest, calendarPanel, chooseRung, clampScroll, clipDuration, clipsInMarquee, clipsOverlap, collectSnapTargets, commitDrag, computeVisible, createCalendarPanel, createTimelinePanel, createTransportPanel, dayKey, daysInMonth, dedupeByColumn, deriveEvents, edgeZone, gridStart, gridTicksFor, hasSourceWindow, isZoomGesture, isoWeekday, packOverlaps, parseDayKey, passedThreshold, previewDrag, renderTier, rowAtY, rowInWindow, rulerTicks, scrollToReveal, snapDelta, snapTick, snapWouldFight, sourceRangeFor, statusTone, ticksPerStep, tileKey, tileWidthTicks, timelineManifest, timelinePanel, todayKey, transportManifest, transportPanel, trimModeFor, visibleClips, visibleRows, weekStart, wheelZoomFactor, withSnapModifier, zoomAboutCursor, zoomBucket, zoomToFit };