@coderyo/ui-shell 1.0.2 → 1.1.0

package/dist/index.d.ts

@@ -1,9 +1,28 @@
 import * as _coderyo_data from '@coderyo/data';
 import { Interval, SymbolSearchHit } from '@coderyo/data';
+import { Locale, I18nDictionary } from '@coderyo/i18n';
 import { IndicatorConfig } from '@coderyo/indicators';
 import * as _coderyo_drawings from '@coderyo/drawings';
 import { DrawingRecord } from '@coderyo/drawings';
+import { BridgeLayerPane } from '@coderyo/bridge';
 import { StreamLanguage } from '@codemirror/language';
+export { isValidLayerBridgePane as isValidBridgeLayerPane } from '@coderyo/core';
+
+interface I18nProvider {
+    t(key: string, fallback?: string, params?: Record<string, string | number>): string;
+    getLocale(): Locale;
+    setLocale(locale: Locale): void;
+    registerLocale(locale: Locale, dictionary: I18nDictionary): void;
+    subscribe(listener: (locale: Locale) => void): () => void;
+}
+declare function createI18nProvider(defaultLocale?: Locale): I18nProvider;
+
+interface LogoSlotOptions {
+    label?: string;
+    href?: string;
+    imageSrc?: string;
+}
+declare function mountLogoSlot(parent: HTMLElement, opts?: LogoSlotOptions): HTMLElement;
 
 declare const GRID_SETTING_KEY = "tradview:settings:showGrid";
 declare const RETURN_CURSOR_KEY = "tradview:settings:returnToCursorAfterDraw";
@@ -11,7 +30,9 @@ declare function loadShowGridPreference(): boolean;
 declare function saveShowGridPreference(show: boolean): void;
 declare function loadReturnToCursorPreference(): boolean;
 declare function saveReturnToCursorPreference(v: boolean): void;
+/** @deprecated Prefer `@coderyo/core` `loadIndicatorConfig(storage, …)` when not using ui-shell. */
 declare function loadIndicatorConfig(symbol: string, interval: string): IndicatorConfig;
+/** @deprecated Prefer `@coderyo/core` `saveIndicatorConfig(storage, …)` when not using ui-shell. */
 declare function saveIndicatorConfig(symbol: string, interval: string, config: IndicatorConfig): void;
 
 interface SettingsPanelOptions {
@@ -21,10 +42,25 @@ interface SettingsPanelOptions {
     onReturnToCursorChange?: (v: boolean) => void;
     indicatorConfig?: IndicatorConfig;
     onIndicatorConfigChange?: (config: IndicatorConfig) => void;
+    onClearAllIndicators?: () => void;
+    onClearAllDrawings?: () => void;
 }
 declare function mountSettingsPanel(parent: HTMLElement, opts?: SettingsPanelOptions): HTMLElement;
 
-type SymbolInputMode = 'manual' | 'search' | 'none';
+type ThemeId = 'dark' | 'light';
+declare const THEME_STORAGE_KEY = "tradview:theme";
+declare function loadTheme(): ThemeId;
+declare function saveTheme(theme: ThemeId): void;
+declare function applyThemeToDocument(theme: ThemeId, root?: HTMLElement): void;
+interface ThemeProvider {
+    getTheme(): ThemeId;
+    setTheme(theme: ThemeId): void;
+    toggle(): ThemeId;
+    subscribe(listener: (theme: ThemeId) => void): () => void;
+}
+declare function createThemeProvider(initial?: ThemeId): ThemeProvider;
+
+type SymbolInputMode = 'manual' | 'search' | 'dialog' | 'none';
 interface TopBarOptions {
     intervals?: Interval[];
     /** Highlighted interval button (defaults to first in `intervals`). */
@@ -34,6 +70,10 @@ interface TopBarOptions {
     onSymbolSelect?: (symbol: string) => void;
     onIntervalChange?: (interval: Interval) => void;
     onThemeToggle?: () => void;
+    onThemeChange?: (theme: 'dark' | 'light') => void;
+    themeProvider?: ThemeProvider;
+    i18n?: I18nProvider;
+    logo?: LogoSlotOptions | false;
     onFullscreen?: () => void;
     onScreenshot?: () => void;
     settings?: SettingsPanelOptions;
@@ -45,6 +85,142 @@ declare function mountTopBar(parent: HTMLElement, opts?: TopBarOptions): {
     setActiveInterval: (interval: Interval) => void;
 };
 
+interface ThemeToggleOptions {
+    themeProvider: ThemeProvider;
+    i18n?: I18nProvider;
+    onThemeChange?: (theme: ThemeId) => void;
+}
+declare function mountThemeToggle(parent: HTMLElement, opts: ThemeToggleOptions): HTMLButtonElement;
+
+interface SymbolSearchDialogOptions {
+    onSearch: (query: string) => Promise<SymbolSearchHit[]>;
+    onSelect: (symbol: string) => void;
+    initialSymbol?: string;
+    i18n?: I18nProvider;
+}
+interface SymbolSearchDialogHandle {
+    open(): void;
+    close(): void;
+    destroy(): void;
+}
+declare function createSymbolSearchDialog(opts: SymbolSearchDialogOptions): SymbolSearchDialogHandle;
+/** TopBar trigger: shows current symbol and opens the dialog. */
+declare function mountSymbolSearchDialogTrigger(parent: HTMLElement, dialog: SymbolSearchDialogHandle, opts: {
+    initialSymbol?: string;
+    i18n?: I18nProvider;
+}): HTMLElement;
+
+/** LayoutPreset v2 — free-floating layer compositor (replaces layout-schema v1). */
+declare const LAYER_PRESET_VERSION: 2;
+type LayerPresetAuthor = 'integrator' | 'user';
+type LayerType = 'shell.topBar' | 'shell.leftToolbar' | 'shell.bottomToolbar' | 'shell.statusBar' | 'shell.propertiesPanel' | 'chart.host' | 'chart.main' | 'chart.volume' | 'chart.indicator' | 'chart.indicatorHost' | 'overlay.crosshairLegend' | 'overlay.drawing' | 'group';
+/** Normalized frame relative to page root (0..1). */
+interface LayerFrame {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+interface LayoutPage {
+    id: string;
+    title: string;
+}
+interface LayerNode {
+    id: string;
+    pageId: string;
+    type: LayerType;
+    /** Maps to legacy widget id or chart role for mount. */
+    widgetKey: string;
+    frame: LayerFrame;
+    zIndex: number;
+    visible: boolean;
+    locked: boolean;
+    groupId?: string;
+    /**
+     * @public Time-scale sync group for chart panes. Same non-empty id → pan/zoom together;
+     * omit or empty → pane is independent (own TimeScaleBus).
+     */
+    syncTimeScaleGroupId?: string;
+}
+interface BindGroup {
+    id: string;
+    name?: string;
+    layerIds: string[];
+}
+interface LayoutPreset {
+    version: typeof LAYER_PRESET_VERSION;
+    /**
+     * Monotonic revision for remote `host.layer.setPreset` merge/replace (integer ≥ 1).
+     * @public Bridge schema 2 — stale host revision is rejected with `STALE_PRESET_REVISION`.
+     */
+    revision?: number;
+    id: string;
+    name: string;
+    author: LayerPresetAuthor;
+    readonly?: boolean;
+    forkedFrom?: string;
+    pages: LayoutPage[];
+    layers: LayerNode[];
+    groups: BindGroup[];
+}
+type LayerWidgetKey = 'topBar' | 'leftToolbar' | 'bottomToolbar' | 'chartHost' | 'chartMain' | 'chartVolume' | 'chartIndicator' | 'indicatorHost' | 'statusBar' | 'propertiesPanel' | 'crosshairLegend' | 'drawingOverlay';
+
+/** @public Mutable controller for LayoutPreset v2 (layers, groups, pane focus). */
+declare class LayerController {
+    private preset;
+    private readonly listeners;
+    private readonly focusListeners;
+    private interactionDepth;
+    private pageIdSeq;
+    activePageId: string;
+    /** P2: active chart pane layer (click-to-focus). */
+    focusedPaneLayerId: string | null;
+    /** Monotonic preset revision (Bridge `host.layer.setPreset`). */
+    presetRevision: number;
+    constructor(initial: LayoutPreset);
+    getPreset(): LayoutPreset;
+    /** True while pointer drag/resize/marquee is active — blocks setPreset. */
+    isInteracting(): boolean;
+    beginInteraction(): void;
+    endInteraction(): void;
+    setPreset(next: LayoutPreset): boolean;
+    getLayersForActivePage(): LayoutPreset['layers'];
+    getFocusedPaneLayerId(): string | null;
+    getFocusedPaneId(): 'main' | 'volume' | 'indicator' | null;
+    /** Raise z-index among chart panes only; does not rebuild compositor DOM. */
+    focusChartPane(layerId: string): void;
+    subscribeFocus(listener: () => void): () => void;
+    private notifyFocus;
+    private afterChartMainFrameChange;
+    setActivePage(pageId: string): boolean;
+    addPage(title?: string): string;
+    renamePage(pageId: string, title: string): boolean;
+    removePage(pageId: string): boolean;
+    getLayer(layerId: string): LayerNode | undefined;
+    /**
+     * @public Set time-scale sync group for a chart pane layer (`''` clears → independent).
+     */
+    setLayerSyncGroup(layerId: string, groupId: string | null | undefined): boolean;
+    getGroup(groupId: string): BindGroup | undefined;
+    /** Layer ids that move/resize together (group members or singleton). */
+    getTransformLayerIds(layerId: string): string[];
+    getGroupMemberLayers(groupId: string): LayoutPreset['layers'];
+    setLayerFrame(layerId: string, frame: LayerFrame): void;
+    private expandTransformIds;
+    moveLayers(layerIds: string[], dx: number, dy: number): void;
+    resizeLayersFromBbox(layerIds: string[], newBbox: LayerFrame): void;
+    setLayerVisible(layerId: string, visible: boolean): void;
+    setLayerLocked(layerId: string, locked: boolean): void;
+    private syncGroupLayerIds;
+    bumpZIndex(layerId: string, delta: 1 | -1): void;
+    reorderLayers(orderedIds: string[]): void;
+    createBindGroup(layerIds: string[], name?: string): string | null;
+    dissolveGroup(groupId: string): void;
+    removeLayerFromGroup(layerId: string): void;
+    subscribe(listener: () => void): () => void;
+    private emit;
+}
+
 interface ContextMenuAction {
     id: string;
     label: string;
@@ -79,7 +255,7 @@ interface CrosshairLegendOptions {
     symbol?: string;
     interval?: string;
 }
-declare function mountCrosshairLegend(chartHost: HTMLElement, opts?: CrosshairLegendOptions): {
+declare function mountCrosshairLegend(chartHost?: HTMLElement, opts?: CrosshairLegendOptions): {
     el: HTMLElement;
     update: (payload: {
         time?: number;
@@ -112,7 +288,7 @@ interface LayoutFeatures {
     showSettings?: boolean;
     showShortcuts?: boolean;
     /** When TopBar is on and no search API: manual symbol input (default). */
-    symbolInput?: 'manual' | 'search' | 'none';
+    symbolInput?: 'manual' | 'search' | 'dialog' | 'none';
 }
 interface ResolvedLayoutFeatures {
     showTopBar: boolean;
@@ -124,7 +300,7 @@ interface ResolvedLayoutFeatures {
     showContextMenu: boolean;
     showSettings: boolean;
     showShortcuts: boolean;
-    symbolInput: 'manual' | 'search' | 'none';
+    symbolInput: 'manual' | 'search' | 'dialog' | 'none';
 }
 declare const DEFAULT_LAYOUT_FEATURES: ResolvedLayoutFeatures;
 declare function resolveLayoutFeatures(opts?: ChartLayoutOptions): ResolvedLayoutFeatures;
@@ -132,8 +308,52 @@ declare function mergeLayoutFeatures(current: ResolvedLayoutFeatures, patch: Lay
 /** Playground: enable full TV shell. */
 declare function createDemoLayoutOptions(partial?: ChartLayoutOptions): ChartLayoutOptions;
 
+/** Visual layout schema (grid-based composable shell). */
+type LayoutWidgetId = 'topBar' | 'leftToolbar' | 'bottomToolbar' | 'chartHost' | 'indicatorHost' | 'statusBar' | 'propertiesPanel';
+interface LayoutWidgetPlacement {
+    id: LayoutWidgetId;
+    col: number;
+    row: number;
+    colSpan: number;
+    rowSpan: number;
+}
+interface LayoutSchema {
+    version: 1;
+    columns: number;
+    rows: number;
+    widgets: LayoutWidgetPlacement[];
+}
+declare const LAYOUT_SCHEMA_VERSION: 1;
+/** TV-style default when integrator omits `layout` (matches legacy mountChartLayout proportions). */
+declare const DEFAULT_LAYOUT_SCHEMA: LayoutSchema;
+declare function layoutStorageKey(layoutId: string): string;
+declare function resolveLayoutSchema(partial?: LayoutSchema | null): LayoutSchema;
+declare function cloneLayoutSchema(schema: LayoutSchema): LayoutSchema;
+declare function normalizeLayoutSchema(input: LayoutSchema): LayoutSchema;
+declare function loadLayoutSchema(layoutId: string): LayoutSchema | null;
+declare function saveLayoutSchema(layoutId: string, schema: LayoutSchema): void;
+declare function getWidgetPlacement(schema: LayoutSchema, id: LayoutWidgetId): LayoutWidgetPlacement | undefined;
+
 type DrawingToolId = 'cursor' | 'trendline' | 'hline' | 'vline' | 'rectangle' | 'fibonacci' | 'text';
 interface ChartLayoutOptions extends TopBarOptions {
+    themeProvider?: ThemeProvider;
+    i18n?: I18nProvider;
+    /** When false, do not auto-create theme provider / localStorage (default true). */
+    autoThemeProvider?: boolean;
+    /** When false, do not auto-create i18n provider (default true). */
+    autoI18n?: boolean;
+    /** Grid layout schema; omit to use {@link DEFAULT_LAYOUT_SCHEMA}. */
+    layout?: LayoutSchema | null;
+    /** Key for layout persistence (`layoutPersist`). Default `default`. */
+    layoutId?: string;
+    /** Persist layout schema to localStorage on change / saveLayout(). */
+    layoutPersist?: boolean;
+    /**
+     * Enable drag/resize layout editor on mount.
+     * @deprecated Ignored when `layerCompositorManaged` — use `mountLayerCompositor` + `enableLayerEditor`.
+     */
+    layoutEditor?: boolean;
+    onLayoutChange?: (schema: LayoutSchema) => void;
     showTopBar?: boolean;
     showLeftToolbar?: boolean;
     showBottomToolbar?: boolean;
@@ -148,16 +368,28 @@ interface ChartLayoutOptions extends TopBarOptions {
     showContextMenu?: boolean;
     showSettings?: boolean;
     showShortcuts?: boolean;
-    symbolInput?: 'manual' | 'search' | 'none';
+    symbolInput?: 'manual' | 'search' | 'dialog' | 'none';
     onDrawingStyleChange?: (patch: {
         color?: string;
         lineWidth?: number;
         text?: string;
     }) => void;
     onDrawingSelectionBind?: (bind: (drawing: _coderyo_drawings.DrawingRecord | null) => void) => void;
+    /**
+     * When true, crosshair legend is not mounted under chartMain and visibility is driven by
+     * LayerCompositor (not grid CSS / el.style.display here).
+     */
+    layerCompositorManaged?: boolean;
 }
 declare function mountChartLayout(root: HTMLElement, opts?: ChartLayoutOptions): {
+    layoutRoot: HTMLElement;
+    layoutGrid: HTMLElement;
+    /** @deprecated Alias of chartMain — use chartMain for LWC mount. */
     chartHost: HTMLElement;
+    chartMain: HTMLElement;
+    chartVolume: HTMLElement;
+    /** Drawing canvas host (same element as chartMain when compositor-managed). */
+    drawingOverlay: HTMLElement;
     indicatorHost: HTMLElement;
     topBar: HTMLElement;
     setActiveInterval: (interval: _coderyo_data.Interval) => void;
@@ -166,10 +398,236 @@ declare function mountChartLayout(root: HTMLElement, opts?: ChartLayoutOptions):
     detachContextMenu: () => void;
     setActiveDrawingTool: (tool: DrawingToolId) => void;
     propertiesPanel: ReturnType<typeof mountDrawingPropertiesPanel>;
+    /** Bind drawing + apply properties panel visibility (compositor-safe). */
+    handleDrawingSelection: (drawing: _coderyo_drawings.DrawingRecord | null) => void;
+    /** Sync showCrosshairLegend (etc.) to compositor layer.visible when layerCompositorManaged. */
+    syncCompositorShellVisibility?: (controller: LayerController) => void;
+    /**
+     * Bind compositor controller so `setLayoutFeatures` keeps shell/legend layer.visible in sync.
+     * Call once after `mountLayerCompositor` (Playground pattern).
+     */
+    bindLayerCompositorController?: (controller: LayerController) => void;
     setLayoutFeatures: (patch: LayoutFeatures) => void;
     getLayoutFeatures: () => ResolvedLayoutFeatures;
+    getLayoutSchema: () => LayoutSchema;
+    setLayoutSchema: (schema: LayoutSchema) => void;
+    enableLayoutEditor: (enabled: boolean) => void;
+    saveLayout: () => void;
 };
 
+type LayoutWidgetElements = Partial<Record<LayoutWidgetId, HTMLElement>>;
+interface LayoutGridHandle {
+    root: HTMLElement;
+    grid: HTMLElement;
+    cells: Map<LayoutWidgetId, HTMLElement>;
+    applySchema: (schema: LayoutSchema, features: ResolvedLayoutFeatures) => void;
+    enableEditor: (enabled: boolean) => void;
+    getSchema: () => LayoutSchema;
+    setSchema: (schema: LayoutSchema) => void;
+    destroyEditor: () => void;
+}
+interface CreateLayoutGridOptions {
+    schema: LayoutSchema;
+    widgets: LayoutWidgetElements;
+    features: ResolvedLayoutFeatures;
+    editor?: boolean;
+    onSchemaChange?: (schema: LayoutSchema) => void;
+}
+declare function createLayoutGrid(opts: CreateLayoutGridOptions): LayoutGridHandle;
+
+declare function clampFrame(frame: LayerFrame): LayerFrame;
+declare function normalizeLayoutPreset(input: LayoutPreset): LayoutPreset;
+declare function cloneLayoutPreset(preset: LayoutPreset): LayoutPreset;
+
+/** Convert legacy 12×12 grid schema to normalized layer preset (single page). */
+declare function layoutSchemaToPreset(schema?: LayoutSchema, opts?: {
+    id?: string;
+    name?: string;
+}): LayoutPreset;
+
+/** Built-in integrator preset — matches legacy DEFAULT_LAYOUT_SCHEMA proportions. */
+declare const VENDOR_DEFAULT_PRESET: LayoutPreset;
+/** Compact: chart-focused, smaller chrome. */
+declare const VENDOR_COMPACT_PRESET: LayoutPreset;
+/** Demo: main+volume share `prices`; indicator pane uses separate `osc` group. */
+declare const VENDOR_DUAL_SYNC_PRESET: LayoutPreset;
+declare const BUILTIN_PRESETS: LayoutPreset[];
+declare function getBuiltinPreset(id: string): LayoutPreset | undefined;
+
+declare function presetStorageKey(id: string): string;
+interface PresetListEntry {
+    id: string;
+    name: string;
+    author: LayoutPreset['author'];
+    readonly?: boolean;
+    builtin?: boolean;
+}
+declare function listPresets(): PresetListEntry[];
+declare function loadPreset(id: string): LayoutPreset | null;
+declare function savePreset(preset: LayoutPreset): void;
+declare function deleteUserPreset(id: string): boolean;
+declare function forkPreset(sourceId: string, newId: string, newName: string): LayoutPreset | null;
+declare function resolvePreset(id: string | LayoutPreset | null | undefined): LayoutPreset;
+
+/** Union bounding box of layer frames (normalized 0..1). */
+declare function getLayersBoundingBox(layers: Pick<LayerNode, 'frame'>[]): LayerFrame | null;
+/** Move all frames by normalized delta; each frame is clamped independently. */
+declare function moveLayerFrames(frames: LayerFrame[], dx: number, dy: number): LayerFrame[];
+/**
+ * Resize a group by mapping each member's relative position inside oldBbox into newBbox.
+ */
+declare function resizeGroupFrames(members: Pick<LayerNode, 'frame'>[], oldBbox: LayerFrame, newBbox: LayerFrame): LayerFrame[];
+declare function clampBBox(frame: LayerFrame): LayerFrame;
+
+type LayerWidgetElements = Partial<Record<LayerWidgetKey, HTMLElement>>;
+interface LayerCompositorOptions {
+    preset: LayoutPreset;
+    widgets: LayerWidgetElements;
+    /** Hide legacy grid container when compositor positions widgets. */
+    hideLegacyGrid?: HTMLElement;
+    /** Fired after user drag/resize commits a preset change. */
+    onPresetChange?: (preset: LayoutPreset) => void;
+    /** Shift+drag marquee on compositor root (edit mode). */
+    onMarqueeSelect?: (layerIds: string[]) => void;
+    /** P2: chart pane focus changed (main / volume / indicator). */
+    onChartPaneFocus?: (pane: 'main' | 'volume' | 'indicator' | null) => void;
+}
+interface LayerCompositorHandle {
+    root: HTMLElement;
+    controller: LayerController;
+    apply(): void;
+    enableLayerEditor(enabled: boolean): void;
+    isLayerEditorEnabled(): boolean;
+    destroy(): void;
+}
+/** @public Mount floating layer compositor (LayoutPreset v2) over shell widgets. */
+declare function mountLayerCompositor(parent: HTMLElement, opts: LayerCompositorOptions): LayerCompositorHandle;
+
+interface LayerEditorOptions {
+    controller: LayerController;
+    /** Called after drag/resize commits preset changes. */
+    onPresetChange?: () => void;
+    /** Shift+drag marquee selection on compositor root. */
+    onMarqueeSelect?: (layerIds: string[]) => void;
+}
+interface LayerEditorHandle {
+    setEnabled(enabled: boolean): void;
+    isEnabled(): boolean;
+    rebind(): void;
+    destroy(): void;
+}
+declare function attachLayerEditor(compositorRoot: HTMLElement, opts: LayerEditorOptions): LayerEditorHandle;
+
+interface LayerPanelOptions {
+    onSaveAsPreset?: (preset: ReturnType<LayerController['getPreset']>) => void;
+}
+interface LayerPanelHandle {
+    el: HTMLElement;
+    destroy: () => void;
+    toggle: () => boolean;
+    /** Replace panel checkbox selection (e.g. compositor shift+marquee). */
+    selectLayers(layerIds: string[]): void;
+}
+/** @public Layer list UI bound to a LayerController. */
+declare function mountLayerPanel(parent: HTMLElement, controller: LayerController, opts?: LayerPanelOptions): LayerPanelHandle;
+
+declare const CHART_PANE_LAYER_TYPES: readonly LayerType[];
+declare const DEFAULT_SYNC_TIME_SCALE_GROUP = "chart-timescale";
+declare function isChartPaneLayerType(type: string): type is LayerType;
+declare function widgetKeyForChartPaneType(type: LayerType): string | null;
+declare function paneIdFromWidgetKey(widgetKey: string): 'main' | 'volume' | 'indicator' | null;
+interface HostSplitResult {
+    layers: LayerNode[];
+    /** Maps removed `chart.host` layer id → [mainId, volumeId]. */
+    idRemap: Map<string, string[]>;
+}
+/** Split legacy `chart.host` into main + volume layers (vertical tile inside host frame). */
+declare function expandLegacyChartHostLayers(layers: LayerNode[]): LayerNode[];
+declare function splitLegacyChartHost(layers: LayerNode[]): HostSplitResult;
+/** @deprecated Use syncOverlayLayersToMain / syncAllOverlayLayersToMain */
+declare function syncCrosshairLegendToMain(layers: LayerNode[]): void;
+declare function upgradeIndicatorHostType(layers: LayerNode[]): LayerNode[];
+
+declare const OVERLAY_LAYER_TYPES: readonly LayerType[];
+declare function isOverlayLayerType(type: string): type is LayerType;
+/** Anchor crosshair legend + drawing overlay frames to chart.main on one page (P3). */
+declare function syncOverlayLayersToMain(layers: LayerNode[], pageId: string): void;
+/** Sync overlays for every page (normalize / bulk migrate). */
+declare function syncAllOverlayLayersToMain(layers: LayerNode[]): void;
+/** Active-page drawing overlay visibility (wire to `IChart.setFeatures({ drawings: { layer } })`). */
+declare function getDrawingOverlayVisible(controller: {
+    getLayersForActivePage(): LayerNode[];
+}): boolean;
+/** Insert default overlay layers when chart.main exists (normalize). */
+declare function ensureOverlayLayers(layers: LayerNode[], pageId: string): LayerNode[];
+
+type CompositorShellWidgetId = LayoutWidgetId;
+interface CompositorShellHandle {
+    root: HTMLElement;
+    /** Hidden anchor grid (v2 compositor positions widgets; no 12×12 layout). */
+    grid: HTMLElement;
+    cells: Map<CompositorShellWidgetId, HTMLElement>;
+}
+interface CreateCompositorShellOptions {
+    widgets: Partial<Record<CompositorShellWidgetId, HTMLElement>>;
+}
+/** Minimal DOM shell for LayoutPreset v2 — replaces legacy createLayoutGrid when compositor-managed. */
+declare function createCompositorShell(opts: CreateCompositorShellOptions): CompositorShellHandle;
+/** No-op schema apply for compositor shell (features still drive widget mount in chart-layout). */
+declare function applyCompositorShellFeatures(_cells: Map<CompositorShellWidgetId, HTMLElement>, _features: ResolvedLayoutFeatures): void;
+
+/** Map `LayoutFeatures` toggles to compositor layer.visible on the active page. */
+declare function syncCompositorShellVisibilityFromFeatures(controller: LayerController, features: ResolvedLayoutFeatures): void;
+
+interface PageNavigatorOptions {
+    /** Show tab bar even on wide viewports (default: narrow only). */
+    alwaysVisible?: boolean;
+    narrowMq?: string;
+    onPageChange?: (pageId: string) => void;
+}
+interface PageNavigatorHandle {
+    el: HTMLElement;
+    destroy: () => void;
+    refresh: () => void;
+}
+/** @public Mobile-style page tabs for LayoutPreset v2 (P4). */
+declare function mountPageNavigator(parent: HTMLElement, controller: LayerController, opts?: PageNavigatorOptions): PageNavigatorHandle;
+
+/** Minimal chart surface for layer time-scale sync (matches `IChart.applyTimeScaleSyncFromLayers`). */
+interface LayerTimeScaleSyncChart {
+    applyTimeScaleSyncFromLayers(layers: Array<{
+        type: string;
+        pageId?: string;
+        syncTimeScaleGroupId?: string;
+    }>, pageId?: string): unknown;
+}
+interface BindLayerTimeScaleSyncOptions {
+    /** Called after each sync apply (e.g. `requestAnimationFrame(chart.resize)`). */
+    onSync?: () => void;
+}
+/**
+ * @public Wire `IChart.applyTimeScaleSyncFromLayers` to `LayerController` preset mutations.
+ * Applies immediately and on `controller.subscribe` (page switch, sync group, layer edits).
+ * Returns unsubscribe — call after `mountLayerCompositor` + `createChart`.
+ */
+declare function bindLayerTimeScaleSync(chart: LayerTimeScaleSyncChart, controller: LayerController, options?: BindLayerTimeScaleSyncOptions): () => void;
+
+/**
+ * @public Merge partial LayoutPreset v2 into `current` (pages/layers/groups upsert by id).
+ * Unmentioned entries are preserved. Result is normalized.
+ */
+declare function mergeLayoutPreset(current: LayoutPreset, partial: LayoutPreset): LayoutPreset;
+
+declare function layerTypeForBridgePane(pane: BridgeLayerPane): LayerType;
+
+/**
+ * @public Resolve chart pane → layer ids for preset scope (supports `allPages`).
+ */
+declare function resolvePaneLayerIds(preset: Pick<LayoutPreset, 'layers' | 'pages'>, pane: BridgeLayerPane, opts?: {
+    allPages?: boolean;
+    activePageId?: string;
+}): string[];
+
 interface SymbolSearchOptions {
     onSearch: (query: string) => Promise<SymbolSearchHit[]>;
     onSelect: (symbol: string) => void;
@@ -210,4 +668,4 @@ declare function mountPineEditorPanel(parent: HTMLElement, opts?: PineEditorPane
 
 declare const pineLanguage: StreamLanguage<{}>;
 
-export { type ChartLayoutOptions, type ContextMenuAction, type ContextMenuOptions, type CrosshairLegendOptions, DEFAULT_LAYOUT_FEATURES, type DrawingContextMenuHandlers, type DrawingPropertiesPanelOptions, type DrawingToolId, GRID_SETTING_KEY, type LayoutFeatures, type OhlcvSnapshot, PINE_SCRIPT_STORAGE_KEY, type PineEditorPanelOptions, RETURN_CURSOR_KEY, type ResolvedLayoutFeatures, type SettingsPanelOptions as SettingsMenuOptions, type SettingsPanelOptions, type StatusBarOptions, type SymbolInputMode, type SymbolSearchOptions, type TopBarOptions, attachChartContextMenu, bindShortcutsModal, createDemoLayoutOptions, loadIndicatorConfig, loadPineScriptPreference, loadReturnToCursorPreference, loadShowGridPreference, mergeLayoutFeatures, mountChartLayout, mountCodeSnippetPanel, mountCrosshairLegend, mountDrawingPropertiesPanel, mountPineEditorPanel, mountSettingsPanel as mountSettingsMenu, mountSettingsPanel, mountStatusBar, mountSymbolSearch, mountTopBar, openDrawingContextMenu, openShortcutsModal, pineLanguage, resolveLayoutFeatures, saveIndicatorConfig, savePineScriptPreference, saveReturnToCursorPreference, saveShowGridPreference };
+export { BUILTIN_PRESETS, type BindGroup, type BindLayerTimeScaleSyncOptions, CHART_PANE_LAYER_TYPES, type ChartLayoutOptions, type CompositorShellHandle, type CompositorShellWidgetId, type ContextMenuAction, type ContextMenuOptions, type CreateCompositorShellOptions, type CreateLayoutGridOptions, type CrosshairLegendOptions, DEFAULT_LAYOUT_FEATURES, DEFAULT_LAYOUT_SCHEMA, DEFAULT_SYNC_TIME_SCALE_GROUP, type DrawingContextMenuHandlers, type DrawingPropertiesPanelOptions, type DrawingToolId, GRID_SETTING_KEY, type HostSplitResult, type I18nProvider, LAYER_PRESET_VERSION, LAYOUT_SCHEMA_VERSION, type LayerCompositorHandle, type LayerCompositorOptions, LayerController, type LayerEditorHandle, type LayerEditorOptions, type LayerFrame, type LayerNode, type LayerPanelHandle, type LayerPanelOptions, type LayerPresetAuthor, type LayerTimeScaleSyncChart, type LayerType, type LayerWidgetElements, type LayerWidgetKey, type LayoutFeatures, type LayoutGridHandle, type LayoutPage, type LayoutPreset, type LayoutSchema, type LayoutWidgetElements, type LayoutWidgetId, type LayoutWidgetPlacement, type LogoSlotOptions, OVERLAY_LAYER_TYPES, type OhlcvSnapshot, PINE_SCRIPT_STORAGE_KEY, type PageNavigatorHandle, type PageNavigatorOptions, type PineEditorPanelOptions, type PresetListEntry, RETURN_CURSOR_KEY, type ResolvedLayoutFeatures, type SettingsPanelOptions as SettingsMenuOptions, type SettingsPanelOptions, type StatusBarOptions, type SymbolInputMode, type SymbolSearchDialogHandle, type SymbolSearchDialogOptions, type SymbolSearchOptions, THEME_STORAGE_KEY, type ThemeId, type ThemeProvider, type ThemeToggleOptions, type TopBarOptions, VENDOR_COMPACT_PRESET, VENDOR_DEFAULT_PRESET, VENDOR_DUAL_SYNC_PRESET, applyCompositorShellFeatures, applyThemeToDocument, attachChartContextMenu, attachLayerEditor, bindLayerTimeScaleSync, bindShortcutsModal, clampBBox, clampFrame, cloneLayoutPreset, cloneLayoutSchema, createCompositorShell, createDemoLayoutOptions, createI18nProvider, createLayoutGrid, createSymbolSearchDialog, createThemeProvider, deleteUserPreset, ensureOverlayLayers, expandLegacyChartHostLayers, forkPreset, getBuiltinPreset, getDrawingOverlayVisible, getLayersBoundingBox, getWidgetPlacement, isChartPaneLayerType, isOverlayLayerType, layerTypeForBridgePane, layoutSchemaToPreset, layoutStorageKey, listPresets, loadIndicatorConfig, loadLayoutSchema, loadPineScriptPreference, loadPreset, loadReturnToCursorPreference, loadShowGridPreference, loadTheme, mergeLayoutFeatures, mergeLayoutPreset, mountChartLayout, mountCodeSnippetPanel, mountCrosshairLegend, mountDrawingPropertiesPanel, mountLayerCompositor, mountLayerPanel, mountLogoSlot, mountPageNavigator, mountPineEditorPanel, mountSettingsPanel as mountSettingsMenu, mountSettingsPanel, mountStatusBar, mountSymbolSearch, mountSymbolSearchDialogTrigger, mountThemeToggle, mountTopBar, moveLayerFrames, normalizeLayoutPreset, normalizeLayoutSchema, openDrawingContextMenu, openShortcutsModal, paneIdFromWidgetKey, pineLanguage, presetStorageKey, resizeGroupFrames, resolveLayoutFeatures, resolveLayoutSchema, resolvePaneLayerIds, resolvePreset, saveIndicatorConfig, saveLayoutSchema, savePineScriptPreference, savePreset, saveReturnToCursorPreference, saveShowGridPreference, saveTheme, splitLegacyChartHost, syncAllOverlayLayersToMain, syncCompositorShellVisibilityFromFeatures, syncCrosshairLegendToMain, syncOverlayLayersToMain, upgradeIndicatorHostType, widgetKeyForChartPaneType };