entangle-ui 0.8.2 → 0.10.0

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

@@ -0,0 +1,241 @@
+import { AssetBrowserLabels } from './assetBrowserLabels.js';
+import { TreeNodeData } from '../../controls/TreeView/TreeView.types.js';
+import React from 'react';
+import { DataTableDensity, DataTableColumn } from '../../data/DataTable/DataTable.types.js';
+import { BaseComponent } from '../../../types/common.js';
+import { Prettify, LiteralUnion } from '../../../types/utilities.js';
+
+/** Whether an entry is a file/asset or a navigable folder. */
+type AssetKind = 'file' | 'folder';
+/** Well-known asset types. Extensible — consumers may pass any string. */
+type AssetType = LiteralUnion<'image' | 'model' | 'material' | 'audio' | 'video' | 'text' | 'scene' | 'unknown'>;
+/** A single entry shown in the current folder (file OR sub-folder). */
+interface AssetItem {
+    /** Stable unique id within the browser. */
+    id: string;
+    /** Display name. */
+    name: string;
+    /** Drives navigation vs. open behaviour. */
+    kind: AssetKind;
+    /** Consumer-defined category; drives the fallback icon and the type filter. */
+    assetType?: AssetType;
+    /** Image thumbnail URL for grid view. */
+    thumbnailUrl?: string;
+    /** Explicit icon override (files without a thumbnail, and folders). */
+    icon?: React.ReactNode;
+    /** Size in bytes — feeds the list "Size" column and size sort. */
+    size?: number;
+    /** Last-modified timestamp — feeds the list "Modified" column and date sort. */
+    modifiedAt?: number | Date;
+    /** Arbitrary consumer payload (dimensions, tags, GUID, …). */
+    meta?: Record<string, unknown>;
+    /** Default `true`. When `false`, the item cannot be selected. */
+    selectable?: boolean;
+    /** Default `true`. When `false`, the item cannot be dragged. */
+    draggable?: boolean;
+    /** Default: `true` for folders, `false` for files. Can items be dropped onto it? */
+    droppable?: boolean;
+    /** Dim + non-interactive. */
+    disabled?: boolean;
+}
+/** One hop in the current location, oldest → newest. Drives the breadcrumb bar. */
+interface AssetPathSegment {
+    id: string;
+    name: string;
+}
+type AssetView = 'grid' | 'list';
+type AssetSortField = LiteralUnion<'name' | 'type' | 'size' | 'modified'>;
+interface AssetSortState {
+    field: AssetSortField;
+    direction: 'asc' | 'desc';
+}
+/** Active filters. `types: []` or `undefined` means "no type filter". */
+interface AssetFilterState {
+    types?: AssetType[];
+}
+type AssetThumbnailSize = 'sm' | 'md' | 'lg' | number;
+/** Why a selection change fired — useful for analytics & undo. */
+type AssetSelectionReason = 'click' | 'keyboard' | 'marquee' | 'selectAll' | 'clear' | 'contextMenu';
+type AssetNavigationSource = 'breadcrumb' | 'sidebar' | 'open' | 'back' | 'forward';
+/** Per-item state handed to render props. */
+interface AssetItemState {
+    selected: boolean;
+    focused: boolean;
+    /** Index within the displayed (filtered + sorted) list. */
+    index: number;
+    view: AssetView;
+    /** A drag is currently hovering this item as a drop target. */
+    dropTarget: boolean;
+}
+/** Imperative handle exposed via `ref`. */
+interface AssetBrowserHandle {
+    focus: () => void;
+    getElement: () => HTMLDivElement | null;
+    selectAll: () => void;
+    clearSelection: () => void;
+    scrollToItem: (id: string) => void;
+    getSelectedItems: () => AssetItem[];
+    /**
+     * Put the item into inline-rename mode (scrolls it into view + focuses the
+     * field). No-op when `onItemRename` isn't set. Use after inserting a new
+     * folder/file to immediately let the user name it.
+     */
+    beginRename: (id: string) => void;
+}
+/**
+ * Return value of `onItemRename`. Return / resolve `false` to reject the new
+ * name and keep the inline editor open; anything else — including returning
+ * nothing — accepts it. `void` is a member so the common "just apply it"
+ * handler needs no `return`; TS's void-assignability special case does not
+ * fire when a union also contains a `Promise`, so it must be explicit here.
+ */
+type AssetRenameResult = boolean | void | Promise<boolean | undefined>;
+/**
+ * Mutation actions handed to `renderItemContextMenu`, so a custom menu can wire
+ * the built-in flows without juggling a ref. Each is a no-op when its backing
+ * callback (`onItemRename` / `onItemsDelete` / `onItemsDuplicate`) is absent.
+ */
+interface AssetItemActions {
+    /** The items the action applies to (the right-clicked selection). */
+    items: AssetItem[];
+    /** Enter inline-rename on the first item. */
+    rename: () => void;
+    /** Delete `items` via `onItemsDelete`. */
+    delete: () => void;
+    /** Duplicate `items` via `onItemsDuplicate`. */
+    duplicate: () => void;
+}
+interface AssetBrowserBaseProps extends Omit<BaseComponent, 'ref' | 'onChange'> {
+    ref?: React.Ref<AssetBrowserHandle>;
+    /** Direct children of the current folder (files + sub-folders). */
+    items: readonly AssetItem[];
+    /** Current location, oldest → newest. Drives the breadcrumb bar. */
+    path?: readonly AssetPathSegment[];
+    /** Folder hierarchy for the sidebar. Reuses TreeView's node shape. Omit to hide the sidebar. */
+    folderTree?: readonly TreeNodeData[];
+    /** Id of the folder currently shown. Highlights the sidebar node. */
+    currentFolderId?: string;
+    view?: AssetView;
+    defaultView?: AssetView;
+    onViewChange?: (view: AssetView) => void;
+    thumbnailSize?: AssetThumbnailSize;
+    defaultThumbnailSize?: AssetThumbnailSize;
+    onThumbnailSizeChange?: (size: AssetThumbnailSize) => void;
+    /** List-view row density (passthrough to DataTable). @default "comfortable" */
+    density?: DataTableDensity;
+    /** Show the "N items · M selected" footer + thumbnail-size control. @default false */
+    showStatusBar?: boolean;
+    selectionMode?: 'single' | 'multiple' | false;
+    selection?: readonly string[];
+    defaultSelection?: readonly string[];
+    onSelectionChange?: (ids: string[], meta: {
+        reason: AssetSelectionReason;
+    }) => void;
+    /** Rubber-band marquee selection in grid empty space. @default true for 'multiple' */
+    marquee?: boolean;
+    search?: string;
+    defaultSearch?: string;
+    onSearchChange?: (query: string) => void;
+    /** When true, the consumer pre-filters `items` by name. @default false */
+    manualSearch?: boolean;
+    filters?: AssetFilterState;
+    defaultFilters?: AssetFilterState;
+    onFiltersChange?: (filters: AssetFilterState) => void;
+    manualFilter?: boolean;
+    /** Type values offered in the filter menu. Defaults to distinct `assetType`s in `items`. */
+    filterableTypes?: AssetType[];
+    sort?: AssetSortState;
+    defaultSort?: AssetSortState;
+    manualSort?: boolean;
+    onSortChange?: (sort: AssetSortState) => void;
+    /** Fires when the user enters a folder (open / breadcrumb / sidebar / history). */
+    onNavigate?: (folderId: string, source: AssetNavigationSource) => void;
+    /** Fires when a FILE is activated (double-click / Enter). Folders go through onNavigate. */
+    onItemOpen?: (item: AssetItem) => void;
+    /** Enable Back/Forward + Backspace-to-parent. @default false */
+    history?: boolean;
+    /** Override the default list columns. When omitted, a name/type/size/modified set is used. */
+    columns?: readonly DataTableColumn<AssetItem>[];
+    /** Internal move: items dropped onto a folder. Presence enables internal DnD. */
+    onItemsMove?: (payload: {
+        itemIds: string[];
+        targetFolderId: string;
+    }) => void;
+    /** External import: OS files dropped onto the surface (or a folder). Presence enables external drop. */
+    onFilesImport?: (payload: {
+        files: File[];
+        targetFolderId: string | null;
+    }) => void;
+    /** MIME type used when dragging items out. @default 'application/x-entangle-asset' */
+    dragOutMimeType?: string;
+    /** Override the drag-out dataTransfer payload. */
+    getDragData?: (items: AssetItem[]) => Record<string, string>;
+    onItemDragStart?: (items: AssetItem[], event: React.DragEvent) => void;
+    onItemDragEnd?: (items: AssetItem[], event: React.DragEvent) => void;
+    /**
+     * Inline-rename commit. Fires when the user confirms a new name (Enter / blur
+     * with a changed, non-empty value). Presence enables the rename affordance
+     * (F2, double-click-to-rename, the `Rename` default action, and
+     * `handle.beginRename`). Return / resolve `false` to reject the name and keep
+     * the editor open (e.g. failed validation); `void` / `true` accepts it. Apply
+     * the rename to your data source — AssetBrowser only reports intent.
+     */
+    onItemRename?: (item: AssetItem, newName: string) => AssetRenameResult;
+    /** Delete intent for the acted-on items (the selection). Enables Delete key + default action. */
+    onItemsDelete?: (items: AssetItem[]) => void;
+    /** Create-folder intent in the current folder. Enables the empty-area `New folder` default action. */
+    onCreateFolder?: (parentFolderId: string | null) => void;
+    /** Duplicate intent for the acted-on items. Enables Ctrl/Cmd+D + default action. */
+    onItemsDuplicate?: (items: AssetItem[]) => void;
+    /**
+     * Auto-populate the item / empty-area context menus with Rename / Duplicate /
+     * Delete / New folder entries for whichever mutation callbacks are present.
+     * Ignored for a menu you supply yourself via `renderItemContextMenu` /
+     * `renderEmptyContextMenu`. @default false
+     */
+    defaultItemActions?: boolean;
+    loading?: boolean;
+    /** Number of skeleton cells shown in grid view while `loading`. @default 12 */
+    loadingItemCount?: number;
+    emptyState?: React.ReactNode;
+    /**
+     * Error state. `true` renders the built-in error message (with a Retry button
+     * when `onErrorRetry` is set); any other `ReactNode` fully replaces it;
+     * `false` / `undefined` means no error. Takes precedence over `loading` and
+     * the empty state. (Typed as `ReactNode`, which subsumes `boolean`.)
+     */
+    error?: React.ReactNode;
+    /** Retry handler shown as a button in the built-in error state (`error={true}`). */
+    onErrorRetry?: () => void;
+    /** Custom thumbnail (e.g. canvas 3D preview). Falls back to thumbnailUrl → icon → type icon. */
+    renderThumbnail?: (item: AssetItem, ctx: {
+        size: number;
+        selected: boolean;
+    }) => React.ReactNode;
+    /** Fully replace a grid cell's inner content (advanced). */
+    renderItem?: (item: AssetItem, state: AssetItemState) => React.ReactNode;
+    /**
+     * Returns the body of the item context menu (`Menu.*` children). Receives the
+     * acted-on items (the whole selection when right-clicking a selected item,
+     * else just that item) plus an `actions` object wiring the built-in
+     * rename / delete / duplicate flows.
+     */
+    renderItemContextMenu?: (items: AssetItem[], actions: AssetItemActions) => React.ReactNode;
+    /** Returns the body of the empty-area context menu. */
+    renderEmptyContextMenu?: () => React.ReactNode;
+    virtualized?: boolean | 'auto';
+    virtualizationThreshold?: number;
+    overscanRows?: number;
+    'aria-label'?: string;
+    /**
+     * Override any of the built-in English UI strings (search placeholder, sort /
+     * filter menus, empty / loading / error messages, column headers, the live
+     * announcement, …). Merged onto the defaults, so you can translate a subset.
+     */
+    labels?: Partial<AssetBrowserLabels>;
+    /** Compound slots only (`AssetBrowser.Toolbar`, `AssetBrowser.Sidebar`). */
+    children?: React.ReactNode;
+}
+type AssetBrowserProps = Prettify<AssetBrowserBaseProps>;
+
+export type { AssetBrowserBaseProps, AssetBrowserHandle, AssetBrowserProps, AssetFilterState, AssetItem, AssetItemActions, AssetItemState, AssetKind, AssetNavigationSource, AssetPathSegment, AssetRenameResult, AssetSelectionReason, AssetSortField, AssetSortState, AssetThumbnailSize, AssetType, AssetView };

package/dist/types/components/editor/AssetBrowser/assetBrowserLabels.d.ts

@@ -0,0 +1,70 @@
+import { AssetSortField } from './AssetBrowser.types.js';
+
+/**
+ * Every user-facing string in the AssetBrowser chrome. Pass a partial
+ * `labels` prop to translate or reword any subset; unspecified keys fall back
+ * to {@link DEFAULT_ASSET_BROWSER_LABELS} (English).
+ *
+ * The `*Aria` keys are accessible names (screen-reader only); the rest are
+ * visible text. `sortFields` maps each sortable field id to its menu/column
+ * label. `itemCount` / `selectedCount` build the live-region announcement and
+ * receive the relevant counts.
+ */
+interface AssetBrowserLabels {
+    /** Search input placeholder. @default "Search assets…" */
+    searchPlaceholder: string;
+    /** Accessible name of the view-mode toggle. @default "View mode" */
+    viewModeAria: string;
+    /** Grid-view tooltip. @default "Grid view" */
+    gridViewTooltip: string;
+    /** List-view tooltip. @default "List view" */
+    listViewTooltip: string;
+    /** Accessible name of the grid region. @default "Assets" */
+    gridAria: string;
+    /** Sort menu trigger. @default "Sort" */
+    sort: string;
+    /** Ascending radio item. @default "Ascending" */
+    sortAscending: string;
+    /** Descending radio item. @default "Descending" */
+    sortDescending: string;
+    /** Filter menu trigger. @default "Filter" */
+    filter: string;
+    /** Back button accessible name. @default "Back" */
+    back: string;
+    /** Forward button accessible name. @default "Forward" */
+    forward: string;
+    /** Thumbnail-size control accessible name. @default "Thumbnail size" */
+    thumbnailSizeAria: string;
+    /** Default empty-folder message. @default "This folder is empty." */
+    empty: string;
+    /** Loading message (list view) / skeleton aria. @default "Loading assets…" */
+    loading: string;
+    /** Built-in error title. @default "Couldn’t load assets" */
+    errorTitle: string;
+    /** Built-in error description. */
+    errorDescription: string;
+    /** Retry button. @default "Retry" */
+    retry: string;
+    /** File-import drop overlay. @default "Drop files to import" */
+    importOverlay: string;
+    /** List "Type" value for folders. @default "Folder" */
+    folder: string;
+    /** Rename default-action label + rename-field accessible name. @default "Rename" */
+    rename: string;
+    /** Delete default-action label. @default "Delete" */
+    delete: string;
+    /** Duplicate default-action label. @default "Duplicate" */
+    duplicate: string;
+    /** New-folder default-action label. @default "New folder" */
+    newFolder: string;
+    /** Per-sort-field labels (also the list column headers). */
+    sortFields: Record<AssetSortField, string>;
+    /** Live-region item count, e.g. `n => \`${n} items\``. */
+    itemCount: (count: number) => string;
+    /** Live-region selected count suffix, e.g. `n => \`, ${n} selected\``. */
+    selectedCount: (count: number) => string;
+}
+declare const DEFAULT_ASSET_BROWSER_LABELS: AssetBrowserLabels;
+
+export { DEFAULT_ASSET_BROWSER_LABELS };
+export type { AssetBrowserLabels };

package/dist/types/components/editor/ChatPanel/ChatMarkdownRenderer.types.d.ts

@@ -1,6 +1,6 @@
-import React from 'react';
 import { BaseComponent } from '../../../types/common.js';
 import { Prettify } from '../../../types/utilities.js';
+import React from 'react';
 
 interface ChatMarkdownRendererBaseProps extends BaseComponent {
     /** Raw markdown content. */

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

@@ -1,6 +1,6 @@
-import React from 'react';
-import { Prettify } from '../../../types/utilities.js';
 import { BaseComponent } from '../../../types/common.js';
+import { Prettify } from '../../../types/utilities.js';
+import React from 'react';
 
 /**
  * Standard message roles in an LLM conversation.

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

@@ -0,0 +1,26 @@
+import React from 'react';
+import { MinimapProps } from './Minimap.types.js';
+
+/**
+ * Compact navigation widget for editor viewports. Renders a miniature of
+ * the world content alongside a draggable rectangle that mirrors the main
+ * viewport's visible region. Intended to be shared by NodeGraph, Timeline,
+ * and any custom 2D editor surface.
+ *
+ * Designed as a controlled primitive — pass the current `transform` /
+ * `viewportSize` from your `<Viewport>` and translate `onNavigate.worldPoint`
+ * into a `viewport.centerOn(...)` call.
+ *
+ * Children may include `<Minimap.Title>`, `<Minimap.Footer>`,
+ * `<Minimap.Corner>` slot subcomponents — any other nodes render as a
+ * free-form overlay layer above the canvas body. Children can read live
+ * state (hover position, hovered item id, transform) via
+ * `useMinimapContext()` / `useMinimapHover()` / `useMinimapGeometry()` /
+ * `useMinimapDragState()`.
+ */
+declare const Minimap: {
+    ({ items, worldBounds, transform, viewportSize, onNavigate, width, minHeight, maxHeight, interactions, keyboardPanStep, backgroundColor, defaultItemColor, viewportRectStroke, outsideOverlay, renderOverlay, disabled, ariaLabel, className, style, testId, id, children, ref, ...rest }: MinimapProps): React.ReactElement;
+    displayName: string;
+};
+
+export { Minimap };

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

@@ -0,0 +1,249 @@
+import { Point2D } from '../../primitives/canvas/canvas.types.js';
+import React from 'react';
+import { WorldRect, ViewportSize, ViewportTransform } from '../../primitives/viewport/Viewport.types.js';
+import { BaseComponent } from '../../../types/common.js';
+import { Prettify } from '../../../types/utilities.js';
+
+/**
+ * Helpers and current state passed to `renderOverlay` and to custom item
+ * `draw` callbacks. Exposes the same world ↔ minimap math the built-in
+ * shapes use, so consumer drawing stays aligned with everything else.
+ */
+interface MinimapDrawInfo {
+    /** Minimap size in CSS pixels (canvas already DPR-scaled). */
+    minimapSize: ViewportSize;
+    /** World rectangle this minimap maps from. */
+    worldBounds: WorldRect;
+    /** Current main-viewport transform (mirrored). */
+    transform: ViewportTransform;
+    /** Current main-viewport size in CSS pixels (mirrored). */
+    viewportSize: ViewportSize;
+    /** Uniform world → minimap scale (px per world unit). */
+    scale: number;
+    /** Letterbox offset applied when minimap aspect ≠ worldBounds aspect. */
+    offset: Point2D;
+    /** Map a world point to a minimap CSS-pixel point. */
+    worldToMinimap: (point: Point2D) => Point2D;
+    /** Inverse of `worldToMinimap`. */
+    minimapToWorld: (point: Point2D) => Point2D;
+}
+interface MinimapItemBase {
+    /** Stable identity. Used for hover hit-testing and future selection support. */
+    id: string;
+    /** Override draw color for this item. Falls back to `defaultItemColor`. */
+    color?: string;
+}
+interface MinimapRectItem extends MinimapItemBase {
+    type: 'rect';
+    /** Top-left X in world units. */
+    x: number;
+    /** Top-left Y in world units. */
+    y: number;
+    /** Width in world units. */
+    width: number;
+    /** Height in world units. */
+    height: number;
+}
+interface MinimapCircleItem extends MinimapItemBase {
+    type: 'circle';
+    /** Center X in world units. */
+    cx: number;
+    /** Center Y in world units. */
+    cy: number;
+    /** Radius in world units. */
+    r: number;
+}
+interface MinimapLineItem extends MinimapItemBase {
+    type: 'line';
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    /** Stroke width in minimap CSS pixels (does not scale with content). @default 1 */
+    lineWidth?: number;
+}
+/**
+ * Caller-defined item. `draw` is invoked with the minimap canvas context
+ * and a `MinimapDrawInfo` object containing world ↔ minimap helpers.
+ * `bounds` (world coords) is used for hover hit-testing.
+ */
+interface MinimapCustomItem extends MinimapItemBase {
+    type: 'custom';
+    bounds: WorldRect;
+    draw: (ctx: CanvasRenderingContext2D, info: MinimapDrawInfo) => void;
+}
+/** Discriminated union of all minimap item shapes. */
+type MinimapItem = MinimapRectItem | MinimapCircleItem | MinimapLineItem | MinimapCustomItem;
+type MinimapNavigatePhase = 'click' | 'drag-start' | 'drag' | 'drag-end';
+/**
+ * Info passed to `onNavigate` for every navigation event.
+ *
+ * `worldPoint` is the world-space point the user wants at the center
+ * of the main viewport — call `viewport.centerOn(info.worldPoint)`
+ * (or update your transform accordingly) to satisfy the request.
+ */
+interface MinimapNavigateInfo {
+    worldPoint: Point2D;
+    phase: MinimapNavigatePhase;
+}
+/** Fine-grained gesture toggles. Pass `false` to `interactions` to disable everything. */
+interface MinimapInteractionConfig {
+    /** Tap outside the viewport rect → `phase: 'click'`. @default true */
+    click?: boolean;
+    /** Drag the viewport rect itself → `phase: 'drag-*'`. @default true */
+    dragViewportRect?: boolean;
+    /** Drag starting outside the rect → immediately jumps + pans. @default true */
+    dragFromEmpty?: boolean;
+}
+/**
+ * Symbol attached to `Minimap.Title` / `.Footer` / `.Corner` so the parent
+ * `<Minimap>` can identify slot children without relying on `displayName`
+ * (which gets clobbered by wrappers like `React.memo`, `React.forwardRef`,
+ * or Vanilla Extract recipes).
+ */
+declare const MINIMAP_SLOT: unique symbol;
+type MinimapSlotKind = 'title' | 'footer' | 'corner';
+interface MinimapSlotMarker {
+    [MINIMAP_SLOT]: MinimapSlotKind;
+}
+type MinimapTitlePlacement = 'top-outside' | 'top-inside';
+type MinimapFooterPlacement = 'bottom-outside' | 'bottom-inside';
+type MinimapCornerSide = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+/**
+ * Imperative handle exposed via `ref` on `<Minimap>` and `<ViewportMinimap>`.
+ * Stable for the lifetime of the component.
+ */
+interface MinimapHandle {
+    /** Focus the minimap body so arrow keys start working. */
+    focus(): void;
+    /** Access the underlying body DOM element (the `role="region"` div). */
+    getElement(): HTMLDivElement | null;
+    /** Convert a world-space point to minimap CSS-pixel coordinates. */
+    worldToMinimap(point: Point2D): Point2D;
+    /** Inverse of `worldToMinimap`. */
+    minimapToWorld(point: Point2D): Point2D;
+}
+interface MinimapBaseProps extends Omit<BaseComponent, 'onChange' | 'ref'> {
+    /** Items rendered as the content miniature. */
+    items: ReadonlyArray<MinimapItem>;
+    /**
+     * World-space rectangle the minimap maps to. Use the exported
+     * `computeBoundsFromItems(items, padding?)` helper if you don't already
+     * track one yourself.
+     */
+    worldBounds: WorldRect;
+    /** Current main-viewport transform — drives the viewport rect overlay. */
+    transform: ViewportTransform;
+    /** Current main-viewport size in CSS pixels — drives the viewport rect overlay. */
+    viewportSize: ViewportSize;
+    /**
+     * Called when the user navigates via click, drag, or arrow keys.
+     * `info.worldPoint` is the world-space point that should sit at the
+     * center of the main viewport — pass it to `viewport.centerOn(...)`.
+     */
+    onNavigate?: (info: MinimapNavigateInfo) => void;
+    /**
+     * Minimap width in CSS pixels. Height is derived from `worldBounds`
+     * aspect ratio and clamped to `[minHeight, maxHeight]`.
+     * @default 200
+     */
+    width?: number;
+    /** @default 60 */
+    minHeight?: number;
+    /** @default 200 */
+    maxHeight?: number;
+    /**
+     * Gesture configuration. Pass `false` to disable all interactions.
+     * @default { click: true, dragViewportRect: true, dragFromEmpty: true }
+     */
+    interactions?: MinimapInteractionConfig | false;
+    /**
+     * Keyboard pan step, as a fraction of the current main-viewport's
+     * world-space extent per arrow-key press. Shift × 5.
+     * @default 0.1
+     */
+    keyboardPanStep?: number;
+    /** Override background color. Defaults to theme `--etui-color-bg-secondary`. */
+    backgroundColor?: string;
+    /** Default item color. Defaults to theme accent. */
+    defaultItemColor?: string;
+    /** Viewport-rect outline color. Defaults to theme accent. */
+    viewportRectStroke?: string;
+    /**
+     * Dimmed overlay color covering the area outside the viewport rect.
+     * @default 'rgba(0, 0, 0, 0.4)'
+     */
+    outsideOverlay?: string;
+    /**
+     * Custom canvas drawing pass executed after items and before the
+     * viewport-rect shroud + outline. Use for backdrops, playheads, grid
+     * overlays, selection regions — anything that should sit between items
+     * and the viewport-rect chrome.
+     */
+    renderOverlay?: (ctx: CanvasRenderingContext2D, info: MinimapDrawInfo) => void;
+    /** Disable interactions and dim the minimap. @default false */
+    disabled?: boolean;
+    /** @default 'Minimap' */
+    ariaLabel?: string;
+    /**
+     * Slot children. Pass `<Minimap.Title>`, `<Minimap.Footer>`,
+     * `<Minimap.Corner>` subcomponents for chrome, or arbitrary nodes for
+     * absolute overlays inside the canvas body. Children that aren't
+     * recognised slot markers render as a free-form overlay layer.
+     */
+    children?: React.ReactNode;
+    /** Imperative handle. */
+    ref?: React.Ref<MinimapHandle>;
+}
+type MinimapProps = Prettify<MinimapBaseProps>;
+interface MinimapTitleProps {
+    children?: React.ReactNode;
+    /** @default 'top-outside' */
+    placement?: MinimapTitlePlacement;
+    className?: string;
+    style?: React.CSSProperties;
+}
+interface MinimapFooterProps {
+    children?: React.ReactNode;
+    /** @default 'bottom-outside' */
+    placement?: MinimapFooterPlacement;
+    className?: string;
+    style?: React.CSSProperties;
+}
+interface MinimapCornerProps {
+    children?: React.ReactNode;
+    /** Which corner of the canvas body to anchor in. @default 'top-right' */
+    side?: MinimapCornerSide;
+    className?: string;
+    style?: React.CSSProperties;
+}
+/**
+ * Live state available to children of a `<Minimap>` via `useMinimapContext()`.
+ *
+ * For perf-conscious consumers, prefer the per-slice hooks
+ * (`useMinimapHover`, `useMinimapGeometry`, `useMinimapDragState`) — each
+ * subscribes to a single slice and re-renders only when that slice
+ * changes. `useMinimapContext()` re-renders on every store mutation.
+ */
+interface MinimapContextValue {
+    worldBounds: WorldRect;
+    minimapSize: ViewportSize;
+    transform: ViewportTransform;
+    viewportSize: ViewportSize;
+    /** Current pointer position in world coordinates, or null when not hovering. */
+    hoverWorldPoint: Point2D | null;
+    /** Id of the item currently under the pointer (hit-test), or null. */
+    hoveredItemId: string | null;
+    /** True during an active drag (rect or pan). */
+    isDragging: boolean;
+    /** Uniform world → minimap scale. */
+    scale: number;
+    /** Letterbox offset. */
+    offset: Point2D;
+    /** Same helpers exposed in `MinimapDrawInfo`, for symmetry. */
+    worldToMinimap: (point: Point2D) => Point2D;
+    minimapToWorld: (point: Point2D) => Point2D;
+}
+
+export { MINIMAP_SLOT };
+export type { MinimapBaseProps, MinimapCircleItem, MinimapContextValue, MinimapCornerProps, MinimapCornerSide, MinimapCustomItem, MinimapDrawInfo, MinimapFooterPlacement, MinimapFooterProps, MinimapHandle, MinimapInteractionConfig, MinimapItem, MinimapLineItem, MinimapNavigateInfo, MinimapNavigatePhase, MinimapProps, MinimapRectItem, MinimapSlotKind, MinimapSlotMarker, MinimapTitlePlacement, MinimapTitleProps };

package/dist/types/components/editor/Minimap/MinimapContext.d.ts

@@ -0,0 +1,27 @@
+import { MinimapContextValue } from './Minimap.types.js';
+import { MinimapGeometryState, MinimapHoverState } from './MinimapStore.js';
+
+/**
+ * Subscribe to **all** Minimap state. Convenient catch-all but re-renders
+ * on every store mutation. For perf-sensitive consumers, prefer the
+ * slice-specific hooks (`useMinimapHover`, `useMinimapGeometry`,
+ * `useMinimapDragState`).
+ */
+declare function useMinimapContext(): MinimapContextValue;
+/**
+ * Subscribe to the hover slice. Re-renders only when the pointer position
+ * or hovered item id changes.
+ */
+declare function useMinimapHover(): MinimapHoverState;
+/**
+ * Subscribe to the geometry slice (transform / sizes / bounds). Re-renders
+ * only on geometry mutations.
+ */
+declare function useMinimapGeometry(): MinimapGeometryState;
+/**
+ * Subscribe to the drag slice — `true` while a pan/rect-drag gesture is
+ * in flight. Re-renders only on drag-state transitions.
+ */
+declare function useMinimapDragState(): boolean;
+
+export { useMinimapContext, useMinimapDragState, useMinimapGeometry, useMinimapHover };

package/dist/types/components/editor/Minimap/MinimapCorner.d.ts

@@ -0,0 +1,8 @@
+import { MinimapCornerProps, MINIMAP_SLOT } from './Minimap.types.js';
+
+declare const MinimapCorner: ((props: MinimapCornerProps) => null) & {
+    displayName: string;
+    [MINIMAP_SLOT]: "corner";
+};
+
+export { MinimapCorner };

package/dist/types/components/editor/Minimap/MinimapFooter.d.ts

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

package/dist/types/components/editor/Minimap/MinimapStore.d.ts

@@ -0,0 +1,17 @@
+import { Point2D } from '../../primitives/canvas/canvas.types.js';
+import { ViewportTransform, ViewportSize, WorldRect } from '../../primitives/viewport/Viewport.types.js';
+
+/** Snapshot of the geometry slice — the data needed to position anything. */
+interface MinimapGeometryState {
+    transform: ViewportTransform;
+    viewportSize: ViewportSize;
+    worldBounds: WorldRect;
+    minimapSize: ViewportSize;
+}
+/** Snapshot of the hover slice. */
+interface MinimapHoverState {
+    hoverWorldPoint: Point2D | null;
+    hoveredItemId: string | null;
+}
+
+export type { MinimapGeometryState, MinimapHoverState };