entangle-ui 0.9.0 → 0.11.0

package/dist/types/components/editor/NodeGraph/useNodeGraph.d.ts

@@ -0,0 +1,103 @@
+import { NodeGraphNode, NodeGraphEdge, NodeGraphGroup, NodeGraphSelection, NodeGraphPortRef } from './NodeGraph.types.js';
+import { DuplicateNodesOptions } from './nodeGraphActions.js';
+import { Dispatch, SetStateAction } from 'react';
+import { WorldRect } from '../../primitives/viewport/Viewport.types.js';
+
+/** A node accepted by `addNode` — the `id` is generated when omitted. */
+type NodeGraphNodeInput = Omit<NodeGraphNode, 'id'> & {
+    id?: string;
+};
+interface UseNodeGraphOptions {
+    /** Initial nodes. @default [] */
+    nodes?: NodeGraphNode[];
+    /** Initial edges. @default [] */
+    edges?: NodeGraphEdge[];
+    /** Initial groups. @default [] */
+    groups?: NodeGraphGroup[];
+    /** Initial selection. @default { nodes: [], edges: [], groups: [] } */
+    selection?: NodeGraphSelection;
+}
+interface AddGroupOptions {
+    /** Group id. Generated when omitted. */
+    id?: string;
+    label?: string;
+    color?: string;
+}
+/** The four controlled props + change handlers, ready to spread. */
+interface NodeGraphBind {
+    nodes: NodeGraphNode[];
+    edges: NodeGraphEdge[];
+    groups: NodeGraphGroup[];
+    selection: NodeGraphSelection;
+    onNodesChange: (nodes: NodeGraphNode[]) => void;
+    onEdgesChange: (edges: NodeGraphEdge[]) => void;
+    onGroupsChange: (groups: NodeGraphGroup[]) => void;
+    onSelectionChange: (selection: NodeGraphSelection) => void;
+}
+interface UseNodeGraphReturn {
+    nodes: NodeGraphNode[];
+    edges: NodeGraphEdge[];
+    groups: NodeGraphGroup[];
+    selection: NodeGraphSelection;
+    setNodes: Dispatch<SetStateAction<NodeGraphNode[]>>;
+    setEdges: Dispatch<SetStateAction<NodeGraphEdge[]>>;
+    setGroups: Dispatch<SetStateAction<NodeGraphGroup[]>>;
+    setSelection: Dispatch<SetStateAction<NodeGraphSelection>>;
+    /** Append a node (generating an id when omitted). Returns the node id. */
+    addNode: (node: NodeGraphNodeInput) => string;
+    /**
+     * Cascade-delete the given nodes — removes them, drops any edge touching
+     * them, and prunes them from the selection.
+     */
+    removeNodes: (ids: ReadonlyArray<string>) => void;
+    /** Remove the given edges and prune them from the selection. */
+    removeEdges: (ids: ReadonlyArray<string>) => void;
+    /** Remove every edge connected to a port — "detach all" for one socket. */
+    disconnectPort: (node: string, port: string) => void;
+    /**
+     * Cascade-delete the current selection (nodes + edges + groups) and clear
+     * it — the programmatic equivalent of pressing Delete.
+     */
+    removeSelection: () => void;
+    /**
+     * Clone nodes (defaults to the current selection), append the copies, and
+     * select them. Returns the new node ids.
+     */
+    duplicateNodes: (ids?: ReadonlyArray<string>, options?: DuplicateNodesOptions) => string[];
+    /**
+     * Add an edge between two ports, de-duplicating identical endpoints.
+     * Returns the new (or existing) edge id.
+     */
+    connect: (source: NodeGraphPortRef, target: NodeGraphPortRef, data?: unknown) => string;
+    /** Append a group. Returns the group id. */
+    addGroup: (bounds: WorldRect, options?: AddGroupOptions) => string;
+    /** Remove the given groups and prune them from the selection. */
+    removeGroups: (ids: ReadonlyArray<string>) => void;
+    /** Clear the selection. */
+    clearSelection: () => void;
+    /** Spread onto `<NodeGraph {...bind} />` to wire all four controlled props. */
+    bind: NodeGraphBind;
+}
+/**
+ * Own a node graph's state (nodes / edges / groups / selection) plus the
+ * mutations every editor re-implements — add / remove (with edge cascade) /
+ * duplicate / connect / group. Spread `bind` onto `<NodeGraph>` and call the
+ * actions from your toolbar / context menu:
+ *
+ * ```tsx
+ * const graph = useNodeGraph({ nodes: initialNodes, edges: initialEdges });
+ * return (
+ *   <NodeGraph {...graph.bind} renderNode={renderNode}>
+ *     <NodeGraph.Background />
+ *   </NodeGraph>
+ * );
+ * // graph.addNode(...), graph.removeSelection(), graph.duplicateNodes(), ...
+ * ```
+ *
+ * Uncontrolled by design — the hook owns the state. For controlled state
+ * (Redux / Zustand / external store) wire the four `onChange` props yourself.
+ */
+declare function useNodeGraph(options?: UseNodeGraphOptions): UseNodeGraphReturn;
+
+export { useNodeGraph };
+export type { AddGroupOptions, NodeGraphBind, NodeGraphNodeInput, UseNodeGraphOptions, UseNodeGraphReturn };

package/dist/types/components/editor/PropertyInspector/PropertyInspector.types.d.ts

@@ -1,8 +1,15 @@
-import React from 'react';
-import { Prettify } from '../../../types/utilities.js';
 import { BaseComponent, Size } from '../../../types/common.js';
+import { Prettify } from '../../../types/utilities.js';
+import React from 'react';
 
 type PropertyInspectorSize = Size;
+/**
+ * Vertical spacing density applied to property rows.
+ * - `compact`: tighter rows for dense inspectors
+ * - `normal`: default spacing
+ * - `spacious`: roomier rows
+ */
+type PropertyDensity = 'compact' | 'normal' | 'spacious';
 interface PropertyPanelBaseProps extends BaseComponent {
     /**
      * Panel content — PropertySection, PropertyGroup, or any elements
@@ -27,6 +34,19 @@ interface PropertyPanelBaseProps extends BaseComponent {
      * @default "100%"
      */
     maxHeight?: number | string;
+    /**
+     * Fill the available height of the parent and scroll the content when it
+     * overflows, without needing a fixed `maxHeight`. A scrollbar gutter is
+     * reserved so controls never sit under the scrollbar. Ignored when
+     * `maxHeight` is set.
+     * @default false
+     */
+    fillHeight?: boolean;
+    /**
+     * Vertical spacing density applied to all nested rows.
+     * @default "normal"
+     */
+    density?: PropertyDensity;
     /**
      * Whether to show a search/filter input in the header
      * @default false
@@ -102,6 +122,32 @@ interface PropertySectionBaseProps extends Omit<BaseComponent, 'onChange'> {
      * @default false
      */
     disabled?: boolean;
+    /**
+     * Whether this section renders a managed enable/disable toggle in its header.
+     * When the toggle is off, the section body is dimmed and made
+     * non-interactive (but stays mounted). The toggle is independent of the
+     * collapse state.
+     * @default false
+     */
+    checkable?: boolean;
+    /**
+     * Whether the section is enabled (controlled). Requires `checkable`.
+     */
+    checked?: boolean;
+    /**
+     * Whether the section starts enabled (uncontrolled). Requires `checkable`.
+     * @default true
+     */
+    defaultChecked?: boolean;
+    /**
+     * Callback when the enable toggle changes. Requires `checkable`.
+     */
+    onCheckedChange?: (checked: boolean) => void;
+    /**
+     * Accessible label for the enable toggle.
+     * @default the section `title`
+     */
+    checkLabel?: string;
     /**
      * Size override for this section and its rows
      */
@@ -123,9 +169,9 @@ interface PropertySectionBaseProps extends Omit<BaseComponent, 'onChange'> {
 type PropertySectionProps = Prettify<PropertySectionBaseProps>;
 interface PropertyRowBaseProps extends BaseComponent {
     /**
-     * Property label text
+     * Property label. Accepts any renderable node (text, an icon + text, etc.).
      */
-    label: string;
+    label: React.ReactNode;
     /**
      * Tooltip text for the label (shown on hover)
      */
@@ -235,4 +281,4 @@ interface UsePropertyUndoReturn<T = unknown> {
     clear: () => void;
 }
 
-export type { PropertyGroupBaseProps, PropertyGroupProps, PropertyInspectorSize, PropertyPanelBaseProps, PropertyPanelProps, PropertyRowBaseProps, PropertyRowProps, PropertySectionBaseProps, PropertySectionProps, PropertyUndoEntry, UsePropertyUndoOptions, UsePropertyUndoReturn };
+export type { PropertyDensity, PropertyGroupBaseProps, PropertyGroupProps, PropertyInspectorSize, PropertyPanelBaseProps, PropertyPanelProps, PropertyRowBaseProps, PropertyRowProps, PropertySectionBaseProps, PropertySectionProps, PropertyUndoEntry, UsePropertyUndoOptions, UsePropertyUndoReturn };

package/dist/types/components/editor/Timeline/Timeline.d.ts

@@ -0,0 +1,18 @@
+import React from 'react';
+import { TimelineProps } from './Timeline.types.js';
+
+/**
+ * Horizontal multi-track animation timeline / dope sheet. Tracks hold
+ * keyframes (the shared `CurveKeyframe` model) along a frame-based time axis;
+ * a playhead scrubs across all tracks. Canvas-rendered keyframes with DOM
+ * chrome, store-driven via `useSyncExternalStore`.
+ *
+ * Children read live state via `useTimelineContext()` / `useTimelineGeometry()`
+ * / `useTimelinePlayhead()` / `useTimelineSelection()`.
+ */
+declare const Timeline: {
+    (props: TimelineProps): React.ReactElement;
+    displayName: string;
+};
+
+export { Timeline };

package/dist/types/components/editor/Timeline/Timeline.types.d.ts

@@ -0,0 +1,348 @@
+import React from 'react';
+import { ViewportSize } from '../../primitives/viewport/Viewport.types.js';
+import { BaseComponent } from '../../../types/common.js';
+import { Prettify } from '../../../types/utilities.js';
+import { CurveKeyframe, CurveData } from '../../../types/keyframe.js';
+
+/** Dope sheet (keyframe timing) or graph editor (value curves). */
+type TimelineMode = 'dope-sheet' | 'graph';
+/** Pre/post-infinity behaviour, reused from the shared curve model. */
+type TimelineInfinity = {
+    pre?: CurveData['preInfinity'];
+    post?: CurveData['postInfinity'];
+};
+/**
+ * One animated property. Keyframes use the shared `CurveKeyframe` model
+ * (`x` = frame, `y` = value); graph mode assembles a `CurveData` per track
+ * from `{ keyframes, domainX: [startFrame, endFrame], domainY: valueRange }`.
+ */
+interface TimelineTrack {
+    id: string;
+    /** Display label in the header column. */
+    label?: string;
+    /** Keyframe / lane accent color (theme accent fallback). */
+    color?: string;
+    /** Keyframes — `x` is a frame, `y` is the value at that frame. */
+    keyframes: CurveKeyframe[];
+    /** Value range (graph-mode domainY). Auto-fit from keyframes when omitted. */
+    valueRange?: [number, number];
+    /** Pre/post-infinity behaviour for graph mode. */
+    infinity?: TimelineInfinity;
+    /** Visible but not editable. */
+    locked?: boolean;
+    /** Collapsed / not drawn. */
+    hidden?: boolean;
+    /** Expand this track into a graph (curve) lane regardless of the global mode. */
+    expanded?: boolean;
+    /** Group this track belongs to (matches a `TimelineGroup.id`). */
+    groupId?: string;
+    /** Row-height override (CSS px). */
+    height?: number;
+}
+/** A collapsible group of tracks (matched by `TimelineTrack.groupId`). */
+interface TimelineGroup {
+    id: string;
+    label?: string;
+    color?: string;
+    collapsed?: boolean;
+}
+/** A reference to one keyframe on one track. */
+interface TimelineKeyframeRef {
+    trackId: string;
+    keyframeId: string;
+}
+/** Current keyframe selection, flat across tracks. */
+type TimelineSelection = ReadonlyArray<TimelineKeyframeRef>;
+/** The visible frame window (zoom/pan over time). */
+interface TimelineView {
+    startFrame: number;
+    endFrame: number;
+}
+/** A loop sub-range, or `true` for the whole timeline range. */
+type TimelineLoop = boolean | {
+    startFrame: number;
+    endFrame: number;
+};
+/**
+ * Helpers + current state passed to `renderOverlay`. Exposes the same
+ * frame ↔ pixel math the built-in drawing uses, so consumer drawing stays
+ * aligned with everything else.
+ */
+interface TimelineDrawInfo {
+    /** Track-area size in CSS pixels (canvas already DPR-scaled). */
+    size: ViewportSize;
+    /** Visible frame window. */
+    view: TimelineView;
+    /** Global frame range. */
+    startFrame: number;
+    endFrame: number;
+    /** Frames per second. */
+    fps: number;
+    /** Current playhead frame. */
+    frame: number;
+    /** Map a frame to a track-area CSS-pixel X. */
+    frameToX: (frame: number) => number;
+    /** Inverse of `frameToX`. */
+    xToFrame: (x: number) => number;
+}
+/** State passed to the `renderTrackHeader` render prop. */
+interface TimelineTrackHeaderInfo {
+    /** Row index of the track. */
+    index: number;
+    /** Whether any of this track's keyframes are currently selected. */
+    hasSelection: boolean;
+}
+/**
+ * Symbol attached to `Timeline.Toolbar` / `.Footer` so the parent
+ * `<Timeline>` can identify slot children without relying on `displayName`
+ * (clobbered by `React.memo` / Vanilla Extract recipes).
+ */
+declare const TIMELINE_SLOT: unique symbol;
+type TimelineSlotKind = 'toolbar' | 'footer' | 'minimap' | 'track-scale';
+interface TimelineSlotMarker {
+    [TIMELINE_SLOT]: TimelineSlotKind;
+}
+/**
+ * Imperative handle exposed via `ref` on `<Timeline>`. Stable for the
+ * lifetime of the component.
+ */
+interface TimelineHandle {
+    /** Focus the timeline body so keyboard navigation starts working. */
+    focus(): void;
+    /** Access the underlying body DOM element. */
+    getElement(): HTMLDivElement | null;
+    /** Move the playhead to a frame (snapped + clamped). */
+    seek(frame: number): void;
+    /** Start playback. */
+    play(): void;
+    /** Pause playback. */
+    pause(): void;
+    /** Toggle playback. */
+    toggle(): void;
+    /** Current playhead frame. */
+    getFrame(): number;
+    /** Fit the view to the whole frame range, with optional padding (frames). */
+    zoomToFit(paddingFrames?: number): void;
+    /** Fit the view to the current selection. No-op when nothing is selected. */
+    zoomToSelection(): void;
+    /** Current visible frame window. */
+    getView(): TimelineView;
+    /** Set the visible frame window (clamped to bounds + minFramesVisible). */
+    setView(view: TimelineView): void;
+    /** Map a frame to a track-area CSS-pixel X. */
+    frameToX(frame: number): number;
+    /** Inverse of `frameToX`. */
+    xToFrame(x: number): number;
+}
+interface TimelineBaseProps extends Omit<BaseComponent, 'onChange' | 'ref'> {
+    /** Tracks rendered top-to-bottom. */
+    tracks: ReadonlyArray<TimelineTrack>;
+    /** Fires continuously during keyframe drag. */
+    onTracksChange?: (tracks: TimelineTrack[]) => void;
+    /** Fires once on commit (drag end, add, delete) — use for undo integration. */
+    onTracksChangeComplete?: (tracks: TimelineTrack[]) => void;
+    /** First frame of the global range. @default 0 */
+    startFrame?: number;
+    /** Last frame of the global range (the duration). */
+    endFrame: number;
+    /** Frames per second — drives timecode display + the snap grid. @default 30 */
+    fps?: number;
+    /** Playhead frame (controlled). */
+    frame?: number;
+    /** Initial playhead frame (uncontrolled). @default startFrame */
+    defaultFrame?: number;
+    /** Fires continuously while scrubbing. */
+    onFrameChange?: (frame: number) => void;
+    /** Fires once on scrub end. */
+    onFrameChangeComplete?: (frame: number) => void;
+    /** Visible frame window (controlled). */
+    view?: TimelineView;
+    /** Initial visible frame window (uncontrolled). @default whole range */
+    defaultView?: TimelineView;
+    /** Fires when the view zooms/pans. */
+    onViewChange?: (view: TimelineView) => void;
+    /** Minimum frames visible (max zoom-in). @default 1 */
+    minFramesVisible?: number;
+    /** Maximum frames visible (max zoom-out). @default range span */
+    maxFramesVisible?: number;
+    /** Keyframe selection (controlled). */
+    selection?: TimelineSelection;
+    /** Initial selection (uncontrolled). @default [] */
+    defaultSelection?: TimelineSelection;
+    /** Fires when the selection changes. */
+    onSelectionChange?: (selection: TimelineSelection) => void;
+    /** Master editing switch. @default true */
+    editable?: boolean;
+    /** Allow double-click to add keyframes. @default true */
+    allowAddKeyframe?: boolean;
+    /** Allow Delete/Backspace to remove keyframes. @default true */
+    allowDeleteKeyframe?: boolean;
+    /** Snap-to-frame: `true` = 1 frame, number = N-frame grid, `false` = off. @default true */
+    snap?: boolean | number;
+    /** Editor mode (controlled). */
+    mode?: TimelineMode;
+    /** Initial mode (uncontrolled). @default 'dope-sheet' */
+    defaultMode?: TimelineMode;
+    /** Fires when the mode toggles. */
+    onModeChange?: (mode: TimelineMode) => void;
+    /** Playback running (controlled). */
+    playing?: boolean;
+    /** Initial playback state (uncontrolled). @default false */
+    defaultPlaying?: boolean;
+    /** Fires when playback starts/stops. */
+    onPlayingChange?: (playing: boolean) => void;
+    /** Loop the whole range (`true`) or a sub-range (controlled). @default false */
+    loop?: TimelineLoop;
+    /** Initial loop (uncontrolled). */
+    defaultLoop?: TimelineLoop;
+    /** Fires when the loop region is dragged on the ruler. */
+    onLoopChange?: (loop: TimelineLoop) => void;
+    /**
+     * How the view tracks the playhead during playback.
+     * - `'smooth'` — keep the playhead centred in the view; the view slides
+     *   continuously once the playhead reaches the centre.
+     * - `'paged'` — leave the view still until the playhead leaves it, then
+     *   jump forward by one full view span.
+     * - `'off'` — never auto-scroll; user manages the view.
+     * @default 'smooth'
+     */
+    followMode?: 'smooth' | 'paged' | 'off';
+    /**
+     * Adds a thin dedicated **loop strip** directly under the time ruler. A
+     * plain drag on the strip creates / re-draws the loop region (no Alt
+     * needed); the strip also makes loop edges easier to grab. The main ruler
+     * keeps its scrub behaviour. @default false
+     */
+    loopStrip?: boolean;
+    /**
+     * Visual style for the loop region's edge markers.
+     * - `'edges'` — full-height vertical bars on each loop edge (default).
+     * - `'brackets'` — `[ ]` bracket markers in the chrome (ruler / loop
+     *   strip) with serifs at the top and bottom, no full-height bars. Bigger
+     *   pick targets, less visual noise across the track area.
+     * @default 'edges'
+     */
+    loopHandles?: 'edges' | 'brackets';
+    /** Track groups (collapsible). Tracks join a group via `groupId`. */
+    groups?: ReadonlyArray<TimelineGroup>;
+    /** Fires when a group is collapsed / expanded via its header. */
+    onGroupsChange?: (groups: TimelineGroup[]) => void;
+    /** Default row height in CSS px. @default 28 */
+    trackHeight?: number;
+    /** Row height for a graph-expanded track in CSS px. @default 96 */
+    expandedTrackHeight?: number;
+    /** Group header row height in CSS px. @default 22 */
+    groupHeaderHeight?: number;
+    /** Show the time ruler. @default true */
+    showRuler?: boolean;
+    /** Show the playhead. @default true */
+    showPlayhead?: boolean;
+    /** Width of the left track-header column in CSS px. @default 160 */
+    trackHeaderWidth?: number;
+    /** Fill the parent container (ResizeObserver). @default true */
+    responsive?: boolean;
+    /** Fixed height in CSS px (ignored when `responsive`). */
+    height?: number;
+    /** Playhead line color. Defaults to theme accent. */
+    playheadColor?: string;
+    /** Background color. Defaults to theme `--etui-color-bg-secondary`. */
+    backgroundColor?: string;
+    /**
+     * Per-track value scale on graph / expanded-track lanes (axis line + min/max
+     * labels, optional midpoint + gridlines). Omit to hide the scale entirely.
+     */
+    trackScale?: TimelineTrackScaleProps;
+    /** Custom canvas pass, drawn after built-in content, before the playhead. */
+    renderOverlay?: (ctx: CanvasRenderingContext2D, info: TimelineDrawInfo) => void;
+    /** Custom track-header renderer. Falls back to a built-in header. */
+    renderTrackHeader?: (track: TimelineTrack, info: TimelineTrackHeaderInfo) => React.ReactNode;
+    /** Ruler label formatter. Defaults to `HH:MM:SS:FF` timecode. */
+    formatTime?: (frame: number, fps: number) => string;
+    /** @default 'Timeline' */
+    ariaLabel?: string;
+    /**
+     * Slot children: `<Timeline.Toolbar>`, `<Timeline.Footer>`. Unrecognised
+     * children render as a free-form overlay layer.
+     */
+    children?: React.ReactNode;
+    /** Imperative handle. */
+    ref?: React.Ref<TimelineHandle>;
+}
+type TimelineProps = Prettify<TimelineBaseProps>;
+interface TimelineToolbarProps {
+    children?: React.ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+}
+interface TimelineFooterProps {
+    children?: React.ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+}
+interface TimelineTrackScaleProps {
+    /**
+     * Which side of the lane the scale axis is drawn on.
+     * @default 'start'
+     */
+    position?: 'start' | 'end';
+    /**
+     * Custom value formatter. Receives the raw value and returns the label.
+     * @default `(v) => Number(v.toFixed(2)).toString()`
+     */
+    format?: (value: number) => string;
+    /**
+     * Draw a tick + label at the midpoint of the range too. @default false
+     */
+    showMidpoint?: boolean;
+    /**
+     * Draw thin horizontal gridlines across the whole lane width at each tick
+     * (`min` / `max`, plus midpoint when `showMidpoint` is on). @default false
+     */
+    gridlines?: boolean;
+    /**
+     * Lanes shorter than this (CSS px) skip the scale, so the labels never
+     * overlap into an unreadable blob on a short / collapsed graph lane.
+     * @default 48
+     */
+    minLaneHeight?: number;
+    /**
+     * Override the axis / label color. Defaults to the muted text colour.
+     */
+    color?: string;
+}
+interface TimelineMinimapProps {
+    /**
+     * Tracks to summarize as keyframe markers in the minimap.
+     * Pass the same array you pass to `<Timeline tracks={...} />`.
+     */
+    tracks: ReadonlyArray<TimelineTrack>;
+    /** Strip height in CSS px. @default 40 */
+    height?: number;
+    /** Override the keyframe marker color. */
+    markerColor?: string;
+    /** Override the viewport rectangle color. */
+    viewportColor?: string;
+    className?: string;
+    style?: React.CSSProperties;
+}
+/**
+ * Live state available to children of a `<Timeline>` via
+ * `useTimelineContext()`. Prefer the per-slice hooks for perf-conscious
+ * consumers — each subscribes to a single slice.
+ */
+interface TimelineContextValue {
+    view: TimelineView;
+    size: ViewportSize;
+    startFrame: number;
+    endFrame: number;
+    fps: number;
+    frame: number;
+    playing: boolean;
+    mode: TimelineMode;
+    selection: TimelineSelection;
+    frameToX: (frame: number) => number;
+    xToFrame: (x: number) => number;
+}
+
+export { TIMELINE_SLOT };
+export type { TimelineBaseProps, TimelineContextValue, TimelineDrawInfo, TimelineFooterProps, TimelineGroup, TimelineHandle, TimelineInfinity, TimelineKeyframeRef, TimelineLoop, TimelineMinimapProps, TimelineMode, TimelineProps, TimelineSelection, TimelineSlotKind, TimelineSlotMarker, TimelineToolbarProps, TimelineTrack, TimelineTrackHeaderInfo, TimelineTrackScaleProps, TimelineView };

package/dist/types/components/editor/Timeline/TimelineContext.d.ts

@@ -0,0 +1,51 @@
+import { TimelineContextValue, TimelineTrack, TimelineSelection } from './Timeline.types.js';
+import { TimelineGeometryState, TimelinePlayheadState } from './TimelineStore.js';
+import { TangentMode } from '../../../types/keyframe.js';
+
+/**
+ * Subscribe to **all** Timeline state. Convenient catch-all but re-renders on
+ * every store mutation. For perf-sensitive consumers, prefer the slice hooks
+ * (`useTimelineGeometry`, `useTimelinePlayhead`, `useTimelineSelection`).
+ */
+declare function useTimelineContext(): TimelineContextValue;
+/** Subscribe to the geometry slice (view / sizes / range / mode). */
+declare function useTimelineGeometry(): TimelineGeometryState;
+/** Subscribe to the playhead slice (frame / playing). */
+declare function useTimelinePlayhead(): TimelinePlayheadState;
+/** Subscribe to the selection slice. */
+declare function useTimelineSelection(): TimelineSelection;
+interface TimelineSelectedTangentMode {
+    /**
+     * The tangent mode shared by all selected keyframes; `'mixed'` if they
+     * disagree; `null` when nothing applicable is selected.
+     */
+    current: TangentMode | 'mixed' | null;
+    /** Apply a tangent mode to every selected keyframe. */
+    set: (mode: TangentMode) => void;
+}
+/**
+ * Convenience hook for building a tangent-mode toggle UI (the six modes:
+ * `auto` / `linear` / `step` / `aligned` / `mirrored` / `free`). Reads the
+ * current selection from the Timeline store, exposes the unified mode (or
+ * `'mixed'`), and applies a chosen mode to every selected keyframe via the
+ * caller's `onTracksChange`.
+ *
+ * @example
+ * ```tsx
+ * function TangentBar({ tracks, onTracksChange }) {
+ *   const t = useTimelineSelectedTangentMode(tracks, onTracksChange);
+ *   if (t.current === null) return null;
+ *   return (
+ *     <>
+ *       <button onClick={() => t.set('auto')} aria-pressed={t.current === 'auto'}>auto</button>
+ *       <button onClick={() => t.set('aligned')} aria-pressed={t.current === 'aligned'}>aligned</button>
+ *       …
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+declare function useTimelineSelectedTangentMode(tracks: ReadonlyArray<TimelineTrack>, onTracksChange: (next: TimelineTrack[]) => void): TimelineSelectedTangentMode;
+
+export { useTimelineContext, useTimelineGeometry, useTimelinePlayhead, useTimelineSelectedTangentMode, useTimelineSelection };
+export type { TimelineSelectedTangentMode };

package/dist/types/components/editor/Timeline/TimelineFooter.d.ts

@@ -0,0 +1,8 @@
+import { TimelineFooterProps, TIMELINE_SLOT } from './Timeline.types.js';
+
+declare const TimelineFooter: ((props: TimelineFooterProps) => null) & {
+    displayName: string;
+    [TIMELINE_SLOT]: "footer";
+};
+
+export { TimelineFooter };

package/dist/types/components/editor/Timeline/TimelineMinimap.d.ts

@@ -0,0 +1,21 @@
+import React from 'react';
+import { TimelineMinimapProps, TimelineView, TIMELINE_SLOT } from './Timeline.types.js';
+
+interface InternalProps extends TimelineMinimapProps {
+    /** Wired by the Timeline parent via the slot mechanism. */
+    setView?: (view: TimelineView) => void;
+}
+/**
+ * Compact overview strip showing the full frame range, the current viewport
+ * rectangle (draggable), the playhead, and small dots for every keyframe.
+ * Picked out of `<Timeline>` children by the `TIMELINE_SLOT` symbol — its
+ * position in the child tree does not affect placement (always rendered below
+ * the track area).
+ */
+declare function TimelineMinimapImpl(props: InternalProps): React.ReactElement;
+declare const TimelineMinimap: typeof TimelineMinimapImpl & {
+    displayName: string;
+    [TIMELINE_SLOT]: "minimap";
+};
+
+export { TimelineMinimap };

package/dist/types/components/editor/Timeline/TimelineStore.d.ts

@@ -0,0 +1,41 @@
+import { TimelineView, TimelineMode } from './Timeline.types.js';
+import { ViewportSize } from '../../primitives/viewport/Viewport.types.js';
+
+/** Snapshot of the geometry slice — everything needed to position content. */
+interface TimelineGeometryState {
+    /** Visible frame window. */
+    view: TimelineView;
+    /** Track-area size in CSS px (excludes the header column). */
+    size: ViewportSize;
+    /** Uniform row height in CSS px. */
+    trackHeight: number;
+    /** Vertical scroll offset of the track stack. */
+    scrollTop: number;
+    /** Global frame range. */
+    startFrame: number;
+    endFrame: number;
+    /** Frames per second. */
+    fps: number;
+    /** Editor mode. */
+    mode: TimelineMode;
+}
+/** Snapshot of the playhead slice. */
+interface TimelinePlayheadState {
+    frame: number;
+    playing: boolean;
+}
+/** The active pointer gesture. */
+type TimelineDragKind = 'none' | 'scrub' | 'move' | 'marquee' | 'pan';
+/** Snapshot of the drag slice — active gesture + optional marquee rectangle. */
+interface TimelineDragState {
+    kind: TimelineDragKind;
+    /** Marquee rectangle in track-area CSS px (box-select), or null. */
+    marquee: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+}
+
+export type { TimelineDragKind, TimelineDragState, TimelineGeometryState, TimelinePlayheadState };