@endge/nova 0.13.6 → 0.13.14

package/dist/model/runtime/diagnostics/NovaDiagnostics_Module.d.ts

@@ -0,0 +1,143 @@
+import { EventList } from '@endge/utils';
+import { NovaDiagnosticsCategory, NovaDiagnosticsOptions, NovaDiagnosticsSnapshot } from '../../../domain/types/diagnostics.types';
+import { NovaApp } from '../app/NovaApp';
+import { NovaDiagnosticsBrowser_Adapter } from './adapters/NovaDiagnosticsBrowser_Adapter';
+/**
+ * Описывает callbacks, которыми diagnostics управляет внешними runtime-сервисами.
+ */
+export interface NovaDiagnosticsRuntimeHooks {
+    setRendererDiagnosticsEnabled: (enabled: boolean) => void;
+}
+/**
+ * Собирает diagnostics NovaApp только при включенном runtime-флаге.
+ */
+export declare class NovaDiagnostics_Module<E extends EventList = EventList> {
+    private readonly _app;
+    private readonly _hooks;
+    private readonly _browserAdapter;
+    private _options;
+    private readonly _categories;
+    private _frameIndex;
+    private _frameStartedAt;
+    private _phaseStartedAt;
+    private _phaseName;
+    private _dirtyNodes;
+    private _dirtyRenderNodes;
+    private _lastFrame;
+    private _browser;
+    private _history;
+    private _browserTimerId;
+    private _longTaskObserver;
+    private _longTasks;
+    private _longTaskMs;
+    private _samplingBrowser;
+    private readonly _phaseDurations;
+    /**
+     * Создает diagnostics module для конкретного NovaApp.
+     */
+    constructor(_app: NovaApp<E>, _hooks: NovaDiagnosticsRuntimeHooks, _browserAdapter?: NovaDiagnosticsBrowser_Adapter);
+    /**
+     * Возвращает активность diagnostics.
+     */
+    get enabled(): boolean;
+    /**
+     * Возвращает текущие настройки diagnostics.
+     */
+    get options(): Required<NovaDiagnosticsOptions>;
+    /**
+     * Возвращает накопленную history последних snapshots.
+     */
+    get history(): Array<NovaDiagnosticsSnapshot>;
+    /**
+     * Применяет новые настройки diagnostics.
+     */
+    configure(options: NovaDiagnosticsOptions | undefined): void;
+    /**
+     * Проверяет активность категории.
+     */
+    hasCategory(category: NovaDiagnosticsCategory): boolean;
+    /**
+     * Помечает начало frame diagnostics.
+     */
+    frameStart(now?: number): void;
+    /**
+     * Помечает конец frame diagnostics и сохраняет snapshot.
+     */
+    frameEnd(now?: number): void;
+    /**
+     * Помечает начало runtime phase.
+     */
+    phaseStart(name: string, now?: number): void;
+    /**
+     * Помечает конец runtime phase.
+     */
+    phaseEnd(now?: number): void;
+    /**
+     * Сохраняет размер dirty workload для текущей Raph phase.
+     */
+    recordDirtyNodes(count: number): void;
+    /**
+     * Сохраняет размер render dirty workload для текущего frame.
+     */
+    recordDirtyRenderNodes(count: number): void;
+    /**
+     * Возвращает текущий diagnostics snapshot.
+     */
+    snapshot(now?: number): NovaDiagnosticsSnapshot;
+    /**
+     * Освобождает diagnostics timers и observers.
+     */
+    destroy(): void;
+    /**
+     * Запускает runtime collectors.
+     */
+    private _startCollectors;
+    /**
+     * Останавливает runtime collectors.
+     */
+    private _stopCollectors;
+    /**
+     * Перезапускает browser collectors после изменения настроек.
+     */
+    private _restartBrowserCollectors;
+    /**
+     * Останавливает browser collectors.
+     */
+    private _stopBrowserCollectors;
+    /**
+     * Сбрасывает mutable state, который не должен жить при выключенной диагностике.
+     */
+    private _resetRuntimeState;
+    /**
+     * Читает browser-level метрики, если runtime API доступны.
+     */
+    private _sampleBrowser;
+    /**
+     * Запускает observer long task API, если браузер его поддерживает.
+     */
+    private _startLongTaskObserver;
+    /**
+     * Собирает runtime snapshot.
+     */
+    private _collectRuntime;
+    /**
+     * Собирает render snapshot по последним surface metrics.
+     */
+    private _collectRender;
+    /**
+     * Собирает resource snapshot по расчетным ресурсам Nova.
+     */
+    private _collectResources;
+    /**
+     * Собирает input snapshot.
+     */
+    private _collectInput;
+    /**
+     * Возвращает карту доступности diagnostics данных.
+     */
+    private _collectAvailability;
+    /**
+     * Нормализует options diagnostics.
+     */
+    private _resolveOptions;
+}

package/dist/model/runtime/diagnostics/adapters/NovaDiagnosticsBrowser_Adapter.d.ts

@@ -0,0 +1,32 @@
+/** Описывает browser memory API Chromium. */
+export interface BrowserPerformanceMemory {
+    usedJSHeapSize: number;
+    totalJSHeapSize?: number;
+    jsHeapSizeLimit?: number;
+}
+/** Описывает расширенный Performance API для browser diagnostics. */
+export interface DiagnosticsPerformance extends Performance {
+    memory?: BrowserPerformanceMemory;
+    measureUserAgentSpecificMemory?: () => Promise<{
+        bytes: number;
+    }>;
+}
+/** Изолирует browser observability APIs Nova diagnostics. */
+export declare class NovaDiagnosticsBrowser_Adapter {
+    /** Возвращает monotonic browser timestamp с безопасным fallback. */
+    now(): number;
+    /** Возвращает доступный Performance API. */
+    performance(): DiagnosticsPerformance | undefined;
+    /** Снимает DOM snapshot без передачи Document в модуль. */
+    sampleDom(): {
+        domNodes: number;
+        documents: number;
+        frames: number;
+    } | null;
+    /** Подключает long-task observer, если platform API доступен. */
+    observeLongTasks(onEntry: (duration: number) => void): PerformanceObserver | null;
+    /** Показывает доступность DOM observability. */
+    hasDom(): boolean;
+    /** Показывает доступность long-task observability. */
+    hasLongTaskObserver(): boolean;
+}

package/dist/model/runtime/interaction/NovaEvents.d.ts

@@ -0,0 +1,229 @@
+import { EventList } from '@endge/utils';
+import { NovaNodeEventHandlers } from '../../../domain/types/events.types';
+import { NovaHitTestMode } from '../../../domain/types/renderer.types';
+import { NovaApp } from '../app/NovaApp';
+import { NovaNode } from '../tree/NovaNode';
+/**
+ * Управляет DOM-событиями, hit-test и маршрутизацией событий к Nova nodes.
+ */
+export declare class NovaEvents<E extends EventList> {
+    readonly app: NovaApp<E>;
+    interactiveNodes: Set<NovaNode<E>>;
+    canvasLifecycleNodes: Set<NovaNode<E>>;
+    hoveredNodes: Set<NovaNode<E>>;
+    draggedNodes: Set<NovaNode<E>>;
+    selectedNodes: Set<NovaNode<E>>;
+    focusedNode: NovaNode<E> | null;
+    pointerCaptureNode: NovaNode<E> | null;
+    readonly selectedNodesByScope: Map<string, Set<NovaNode<E>>>;
+    readonly focusedNodesByScope: Map<string, NovaNode<E> | null>;
+    hitTestMode: NovaHitTestMode;
+    lastHitTestCandidates: number;
+    lastHitTestMode: NovaHitTestMode;
+    isDragging: boolean;
+    isDraggingEmitted: boolean;
+    lastClickTime: number;
+    clickTimeout: number | null;
+    startMouseX: number;
+    startMouseY: number;
+    lastMouseX: number;
+    lastMouseY: number;
+    mouseX: number;
+    mouseY: number;
+    clickTimeoutMs: number;
+    private _mouseMoveQueued;
+    private _lastMouseMoveEvent;
+    private readonly _spatialIndex;
+    private readonly _spatialDirtyNodes;
+    private readonly _pointerCaptureNodes;
+    private readonly _pointerStates;
+    private _spatialFullDirty;
+    private _activePointerId;
+    /**
+     * Создает instance и подготавливает внутреннее состояние.
+     */
+    constructor(app: NovaApp<E>);
+    /**
+     * Сбрасывает внутреннее состояние к начальному виду.
+     */
+    reset(): void;
+    /**
+     * Помечает spatial dirty.
+     */
+    markSpatialDirty(node?: NovaNode<E>, includeChildren?: boolean): void;
+    /**
+     * Удаляет node references.
+     */
+    removeNodeReferences(node: NovaNode<E>): void;
+    /**
+     * Регистрирует interactive node и синхронизирует производные event indexes.
+     */
+    registerInteractiveNode(node: NovaNode<E>): void;
+    /**
+     * Возвращает фактическую policy spatial hit-test индекса.
+     */
+    get hitTestIndexPolicy(): 'rbush';
+    /**
+     * Возвращает количество node в spatial hit-test индексе.
+     */
+    get hitTestIndexedNodeCount(): number;
+    /**
+     * Выполняет внутреннюю операцию handle.
+     */
+    handle(type: keyof NovaNodeEventHandlers, event: Event): boolean;
+    /**
+     * Возвращает canvas mouse position.
+     */
+    getCanvasMousePosition(event: MouseEvent): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Выполняет внутреннюю операцию hit test.
+     */
+    hitTest(x: number, y: number): NovaNode<E> | null;
+    /**
+     * Обновляет pointer capture.
+     */
+    setPointerCapture(node: NovaNode<E>, event?: MouseEvent): void;
+    /**
+     * Выполняет внутреннюю операцию release pointer capture.
+     */
+    releasePointerCapture(node?: NovaNode<E>, event?: MouseEvent): void;
+    /**
+     * Проверяет наличие pointer capture.
+     */
+    hasPointerCapture(node: NovaNode<E>, event?: MouseEvent): boolean;
+    /**
+     * Выполняет внутреннюю операцию focus.
+     */
+    focus(node: NovaNode<E> | null, event?: Event, scope?: string): void;
+    /**
+     * Выполняет внутреннюю операцию blur.
+     */
+    blur(node?: NovaNode<E>, event?: Event, scope?: string): void;
+    /**
+     * Проверяет focused.
+     */
+    isFocused(node: NovaNode<E>, scope?: string): boolean;
+    /**
+     * Выполняет внутреннюю операцию select.
+     */
+    select(node: NovaNode<E>, options?: {
+        append?: boolean;
+        toggle?: boolean;
+        scope?: string;
+    }, event?: Event): void;
+    /**
+     * Выполняет внутреннюю операцию deselect.
+     */
+    deselect(node: NovaNode<E>, event?: Event, scope?: string): void;
+    /**
+     * Очищает selection.
+     */
+    clearSelection(event?: Event, scope?: string): void;
+    /**
+     * Проверяет selected.
+     */
+    isSelected(node: NovaNode<E>, scope?: string): boolean;
+    /**
+     * Возвращает selection scope.
+     */
+    private _getSelectionScope;
+    /**
+     * Возвращает focused scope.
+     */
+    private _getFocusedScope;
+    /**
+     * Возвращает hit candidates.
+     */
+    private _getHitCandidates;
+    /**
+     * Синхронизирует dirty nodes с spatial hit-test индексом.
+     */
+    private _syncSpatialIndex;
+    /**
+     * Возвращает pointer id.
+     */
+    private _getPointerId;
+    /**
+     * Возвращает pointer state.
+     */
+    private _getPointerState;
+    /**
+     * Выполняет внутреннюю операцию sync pointer state.
+     */
+    private _syncPointerState;
+    /**
+     * Возвращает captured node.
+     */
+    private _getCapturedNode;
+    /**
+     * Выполняет внутреннюю операцию first captured node.
+     */
+    private _firstCapturedNode;
+    /**
+     * Выполняет внутреннюю операцию dispatch pointer.
+     */
+    private _dispatchPointer;
+    /**
+     * Выполняет внутреннюю операцию build event path.
+     */
+    private _buildEventPath;
+    /**
+     * Выполняет внутреннюю операцию call handler.
+     */
+    private _callHandler;
+    /**
+     * Выполняет внутреннюю операцию call drag handler.
+     */
+    private _callDragHandler;
+    /**
+     * Создает drag meta.
+     */
+    private _createDragMeta;
+    /**
+     * Обрабатывает событие mouse down.
+     */
+    private _onMouseDown;
+    /**
+     * Обрабатывает событие mouse move.
+     */
+    private _onMouseMove;
+    /**
+     * Выполняет внутреннюю операцию handle mouse move.
+     */
+    private _handleMouseMove;
+    /**
+     * Обрабатывает событие mouse up.
+     */
+    private _onMouseUp;
+    /**
+     * Обрабатывает событие wheel.
+     */
+    private _onWheel;
+    /**
+     * Обрабатывает событие context menu.
+     */
+    private _onContextMenu;
+    /**
+     * Обрабатывает событие key down.
+     */
+    private _onKeyDown;
+    /**
+     * Обрабатывает событие key up.
+     */
+    private _onKeyUp;
+    /**
+     * Обрабатывает событие canvas enter.
+     */
+    private _onCanvasEnter;
+    /**
+     * Обрабатывает событие canvas leave.
+     */
+    private _onCanvasLeave;
+    /**
+     * Выполняет внутреннюю операцию dispatch keyboard.
+     */
+    private _dispatchKeyboard;
+}

package/dist/model/runtime/interaction/NovaHitIndex.d.ts

@@ -0,0 +1,57 @@
+import { NovaBounds } from '../../../domain/types/renderer.types';
+/**
+ * Описывает options общего hit-test индекса.
+ */
+export interface NovaHitIndexOptions<T> {
+    getBounds: (item: T) => NovaBounds;
+    isIndexable?: (item: T) => boolean;
+}
+/**
+ * Хранит RBush-backed индекс для point и bounds queries.
+ */
+export declare class NovaHitIndex<T extends object> {
+    private readonly _options;
+    private readonly _tree;
+    private readonly _records;
+    private _lastQueryCandidateCount;
+    /**
+     * Создает instance и подготавливает внутреннее состояние.
+     */
+    constructor(_options: NovaHitIndexOptions<T>);
+    /**
+     * Полностью пересобирает индекс.
+     */
+    rebuild(items: Iterable<T>): void;
+    /**
+     * Выполняет point query.
+     */
+    queryPoint(x: number, y: number): Array<T>;
+    /**
+     * Выполняет bounds query.
+     */
+    queryBounds(bounds: NovaBounds): Array<T>;
+    /**
+     * Обновляет один item в индексе.
+     */
+    update(item: T): void;
+    /**
+     * Удаляет item из индекса.
+     */
+    remove(item: T): void;
+    /**
+     * Очищает индекс.
+     */
+    clear(): void;
+    /**
+     * Возвращает количество проиндексированных items.
+     */
+    get indexedNodeCount(): number;
+    /**
+     * Возвращает количество RBush candidates в последнем query.
+     */
+    get lastQueryCandidateCount(): number;
+    /**
+     * Создает RBush record для item.
+     */
+    private _createRecord;
+}

package/dist/model/runtime/interaction/NovaSpatialIndex.d.ts

@@ -0,0 +1,49 @@
+import { EventList } from '@endge/utils';
+import { NovaBounds } from '../../../domain/types/renderer.types';
+import { NovaNode } from '../tree/NovaNode';
+/**
+ * Совместимый facade над RBush-backed hit-test индексом.
+ */
+export declare class NovaSpatialIndex<E extends EventList> {
+    private readonly _index;
+    /**
+     * Создает instance. cellSize сохранен только для обратной совместимости.
+     */
+    constructor(_cellSize?: number);
+    /**
+     * Выполняет внутреннюю операцию rebuild.
+     */
+    rebuild(nodes: Iterable<NovaNode<E>>): void;
+    /**
+     * Выполняет query point.
+     */
+    queryPoint(x: number, y: number): Array<NovaNode<E>>;
+    /**
+     * Выполняет query bounds.
+     */
+    queryBounds(bounds: NovaBounds): Array<NovaNode<E>>;
+    /**
+     * Очищает внутреннее состояние.
+     */
+    clear(): void;
+    /**
+     * Выполняет внутреннюю операцию update.
+     */
+    update(node: NovaNode<E>): void;
+    /**
+     * Выполняет внутреннюю операцию remove.
+     */
+    remove(node: NovaNode<E>): void;
+    /**
+     * Возвращает условный cell count для старого diagnostics API.
+     */
+    get cellCount(): number;
+    /**
+     * Возвращает indexed node count.
+     */
+    get indexedNodeCount(): number;
+    /**
+     * Возвращает количество candidates в последнем query.
+     */
+    get lastQueryCandidateCount(): number;
+}

package/dist/model/runtime/reactivity/nova-reactivity.d.ts

@@ -0,0 +1,24 @@
+import { NovaNode } from '../tree/NovaNode';
+export interface NovaTrackNodeOptions {
+    mode?: 'replace' | 'append';
+}
+export interface NovaReadableSignal<T> {
+    readonly value: T;
+}
+export interface NovaSignal<T> extends NovaReadableSignal<T> {
+    value: T;
+}
+export interface NovaComputed<T> extends NovaReadableSignal<T> {
+}
+/**
+ * Creates a mutable Nova signal.
+ */
+export declare function createNovaSignal<T>(initialValue: T): NovaSignal<T>;
+/**
+ * Creates a lazy Nova computed signal.
+ */
+export declare function createNovaComputed<T>(compute: () => T): NovaComputed<T>;
+/**
+ * Tracks signal reads performed by a NovaNode update/template pass.
+ */
+export declare function trackNovaNode<T>(node: NovaNode<any>, callback: () => T, options?: NovaTrackNodeOptions): T;

package/dist/model/runtime/refs/nova-ref.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Proxy-ref на публичный API Nova component без `.current`.
+ */
+export type NovaRef<T extends object> = T & {
+    readonly $mounted: boolean;
+    $ready: () => Promise<T>;
+};
+/**
+ * Коллекция refs для компонентов, созданных внутри repeat/list.
+ */
+export interface NovaRefMap<T extends object> {
+    get: (key: string | number) => NovaRef<T>;
+    has: (key: string | number) => boolean;
+    delete: (key: string | number) => boolean;
+    keys: () => IterableIterator<string>;
+    values: () => IterableIterator<NovaRef<T>>;
+    entries: () => IterableIterator<[string, NovaRef<T>]>;
+    readonly size: number;
+}
+/**
+ * Scope refs, который передается template runtime.
+ */
+export interface NovaScope {
+    refs: Record<string, NovaRef<any> | NovaRefMap<any>>;
+}
+/**
+ * Создает пустой scope refs.
+ */
+export declare function createNovaScope(input?: Partial<NovaScope>): NovaScope;
+/**
+ * Создает proxy-ref для component API.
+ */
+export declare function createNovaRef<T extends object>(name?: string): NovaRef<T>;
+/**
+ * Создает map refs для keyed template nodes.
+ */
+export declare function createNovaRefMap<T extends object>(): NovaRefMap<T>;
+/**
+ * Проверяет, является ли value обычным NovaRef.
+ */
+export declare function isNovaRef(value: unknown): value is NovaRef<any>;
+/**
+ * Проверяет, является ли value NovaRefMap.
+ */
+export declare function isNovaRefMap(value: unknown): value is NovaRefMap<any>;
+/**
+ * Привязывает API к ref.
+ */
+export declare function bindNovaRef<T extends object>(ref: NovaRef<T>, api: T): void;
+/**
+ * Отвязывает API от ref.
+ */
+export declare function unbindNovaRef<T extends object>(ref: NovaRef<T>, api?: T): void;
+/**
+ * Привязывает API к ref map entry.
+ */
+export declare function bindNovaRefMap<T extends object>(refMap: NovaRefMap<T>, key: string | number, api: T): void;
+/**
+ * Отвязывает API от ref map entry.
+ */
+export declare function unbindNovaRefMap<T extends object>(refMap: NovaRefMap<T>, key: string | number, api?: T): void;

package/dist/model/runtime/scene/NovaScene.d.ts

@@ -0,0 +1,80 @@
+import { EventList } from '@endge/utils';
+import { NovaLifecycleState } from '../../../domain/types/renderer.types';
+import { NovaApp } from '../app/NovaApp';
+import { NovaNode } from '../tree/NovaNode';
+/**
+ * Описывает монтируемую сцену Nova и управляет ее жизненным циклом.
+ */
+export declare class NovaScene<E extends EventList> {
+    protected readonly app: NovaApp<E>;
+    private readonly _roots;
+    private _state;
+    /**
+     * Создает instance и подготавливает внутреннее состояние.
+     */
+    constructor(app: NovaApp<E>);
+    /**
+     * Выполняет внутреннюю операцию mount.
+     */
+    mount(): void;
+    /**
+     * Выполняет внутреннюю операцию pause.
+     */
+    pause(): void;
+    /**
+     * Выполняет внутреннюю операцию resume.
+     */
+    resume(): void;
+    /**
+     * Выполняет внутреннюю операцию unmount.
+     */
+    unmount(): void;
+    /**
+     * Освобождает runtime resources и снимает связанные ссылки.
+     */
+    destroy(): void;
+    /**
+     * Добавляет root.
+     */
+    protected addRoot<T extends NovaNode<E>>(root: T): T;
+    /**
+     * Удаляет root.
+     */
+    protected removeRoot(root: NovaNode<E>): void;
+    /**
+     * Синхронизирует tracked roots после внешнего reconcile-прохода.
+     */
+    protected setRoots(roots: ReadonlyArray<NovaNode<E>>): void;
+    /**
+     * Возвращает текущие tracked roots для scene-specific lifecycle hooks.
+     */
+    protected get roots(): ReadonlyArray<NovaNode<E>>;
+    /**
+     * Обрабатывает событие mount.
+     */
+    protected onMount(): void;
+    /**
+     * Обрабатывает событие pause.
+     */
+    protected onPause(): void;
+    /**
+     * Обрабатывает событие resume.
+     */
+    protected onResume(): void;
+    /**
+     * Обрабатывает событие unmount.
+     */
+    protected onUnmount(): void;
+    /**
+     * Обрабатывает событие destroy.
+     */
+    protected onDestroy(): void;
+    /**
+     * Возвращает state.
+     */
+    get state(): NovaLifecycleState;
+    /**
+     * Возвращает root count.
+     */
+    get rootCount(): number;
+}