@endge/nova 0.13.6 → 0.13.11

package/dist/model/runtime/components/NovaSchemaRegistry.d.ts

@@ -0,0 +1,71 @@
+import { EventList } from '@endge/utils';
+import { NovaComponentDescriptor, NovaComponentSchema, NovaElementConstructor, NovaElementSchema, NovaSchemaRenderMode } from '../../../domain/types/component.types';
+import { NovaNodeContextOptions } from '../../../domain/types/context.types';
+import { NovaRenderer } from '../../../domain/types/renderer.types';
+import { NovaDefinedComponentInput } from './nova-defined-component';
+import { NovaNode } from '../tree/NovaNode';
+import { NovaSurface } from '../tree/NovaSurface';
+/**
+ * Хранит schema components и отвечает за их expansion и bounds resolution.
+ */
+export declare class NovaSchemaRegistry {
+    private readonly _descriptors;
+    private readonly _tagDescriptors;
+    private readonly _reservedTags;
+    /**
+     * Создает instance и подготавливает внутреннее состояние.
+     */
+    constructor(options?: {
+        defaults?: boolean;
+    });
+    /**
+     * Выполняет внутреннюю операцию register.
+     */
+    register<TProps extends Record<string, any>, TApi, TEvents extends Record<string, unknown>, TSchema>(descriptor: NovaComponentDescriptor<TProps, TApi, TEvents, TSchema>, options?: {
+        override?: boolean;
+    }): void;
+    /**
+     * Регистрирует class-компонент с optional global tag.
+     */
+    registerDefinedComponent<E extends EventList = Record<string, any>>(input: NovaElementConstructor<E> | NovaDefinedComponentInput<E>, options?: {
+        override?: boolean;
+    }): void;
+    /**
+     * Регистрирует decorated class-component напрямую без ручного descriptor/registry glue.
+     */
+    registerDecorated<E extends EventList = Record<string, any>>(input: NovaElementConstructor<E> | NovaDefinedComponentInput<E>, options?: {
+        override?: boolean;
+    }): void;
+    /**
+     * Помечает tag как занятый builtin-слоем или compiler semantics.
+     */
+    reserveTag(tag: string): void;
+    /**
+     * Выполняет внутреннюю операцию has.
+     */
+    has(type: string): boolean;
+    /**
+     * Выполняет внутреннюю операцию resolve.
+     */
+    resolve<T extends NovaComponentDescriptor<any, any, any, any> = NovaComponentDescriptor<any, any, any, any>>(type: string): T | undefined;
+    /**
+     * Выполняет render-операцию schema component.
+     */
+    renderSchemaComponent(renderer: NovaRenderer, item: NovaComponentSchema<any>, _mode: NovaSchemaRenderMode, depth?: number): boolean;
+    /**
+     * Создает node.
+     */
+    createNode<E extends EventList>(surface: NovaSurface<E>, schema: NovaElementSchema<any>, options?: NovaNodeContextOptions): NovaNode<E>;
+    /**
+     * Создает child.
+     */
+    createChild<E extends EventList>(parent: NovaNode<E>, schema: NovaElementSchema<any>, options?: NovaNodeContextOptions): NovaNode<E>;
+    /**
+     * Создает detached node.
+     */
+    private createDetachedNode;
+    /**
+     * Регистрирует defaults.
+     */
+    private registerDefaults;
+}

package/dist/model/runtime/components/nova-component-metadata.d.ts

@@ -0,0 +1,90 @@
+import { NovaComponentApiDefinition, NovaComponentCommandDefinition, NovaComponentDescriptor, NovaComponentDirtyPolicy, NovaComponentPropDefinition, NovaComponentPropKind, NovaComponentSchema, NovaComponentWatchDefinition, NovaElementConstructor } from '../../../domain/types/component.types';
+/**
+ * Описывает class-level metadata декорированного компонента.
+ */
+export interface NovaDecoratedComponentMetadata {
+    type?: string;
+    tag?: string;
+    name?: string;
+    version?: string;
+    dirtyPolicy?: NovaComponentDirtyPolicy<Record<string, any>>;
+    bounds?: 'size' | 'custom';
+    props: Array<NovaComponentPropDefinition>;
+    watchers: Array<NovaComponentWatchDefinition>;
+    commands: Array<NovaComponentCommandDefinition>;
+    apis: Array<NovaComponentApiDefinition>;
+}
+/**
+ * Описывает options декоратора NovaComponent.
+ */
+export interface NovaDecoratedComponentOptions {
+    type?: string;
+    tag?: string;
+    name?: string;
+    version?: string;
+    dirtyPolicy?: NovaComponentDirtyPolicy<Record<string, any>>;
+    bounds?: 'size' | 'custom';
+}
+/**
+ * Описывает options декоратора Prop.
+ */
+export interface NovaPropDecoratorOptions<T = unknown> {
+    key?: string;
+    required?: boolean;
+    default?: T | (() => T);
+    defaultValue?: T | (() => T);
+    mode?: 'plain' | 'versioned';
+}
+/**
+ * Описывает options декоратора Watch.
+ */
+export interface NovaWatchDecoratorOptions {
+    phase?: 'update' | 'render' | 'matrix';
+    immediate?: boolean;
+}
+/**
+ * Возвращает metadata конструктора.
+ */
+export declare function readNovaDecoratedComponent(component: NovaElementConstructor<any>): NovaDecoratedComponentMetadata | undefined;
+/**
+ * Обновляет metadata конструктора.
+ */
+export declare function updateNovaDecoratedComponent(component: Function, patch: Partial<NovaDecoratedComponentMetadata>): NovaDecoratedComponentMetadata;
+/**
+ * Добавляет prop metadata.
+ */
+export declare function addNovaPropMetadata(target: object, propertyKey: string | symbol, kind: NovaComponentPropKind, options?: NovaPropDecoratorOptions, event?: boolean): void;
+/**
+ * Добавляет watcher metadata.
+ */
+export declare function addNovaWatchMetadata(target: object, propertyKey: string | symbol, path: string, options?: NovaWatchDecoratorOptions): void;
+/**
+ * Добавляет command metadata.
+ */
+export declare function addNovaCommandMetadata(target: object, propertyKey: string | symbol, id: string, options?: {
+    scope?: string;
+}): void;
+/**
+ * Добавляет API metadata.
+ */
+export declare function addNovaApiMetadata(target: object, propertyKey: string | symbol): void;
+/**
+ * Создает descriptor из class decorator metadata.
+ */
+export declare function createNovaDecoratedComponentDescriptor<TProps extends Record<string, any> = Record<string, any>, TApi = unknown, TEvents extends Record<string, unknown> = Record<string, unknown>, TSchema = TProps>(component: NovaElementConstructor<any>): NovaComponentDescriptor<TProps, TApi, TEvents, TSchema>;
+/**
+ * Устанавливает accessors для prop-полей на prototype.
+ */
+export declare function installNovaPropAccessors(component: Function): void;
+/**
+ * Возвращает normalized props декорированного компонента.
+ */
+export declare function normalizeDecoratedProps(schema: NovaComponentSchema<Record<string, any>>, metadata: NovaDecoratedComponentMetadata): Record<string, any>;
+/**
+ * Считывает значение path из object.
+ */
+export declare function readNovaComponentPath(source: Record<string, any> | undefined, path: string): unknown;
+/**
+ * Собирает metadata с учетом prototype chain.
+ */
+export declare function collectMetadata(component: Function): NovaDecoratedComponentMetadata;

package/dist/model/runtime/components/nova-component.decorator.d.ts

@@ -0,0 +1,38 @@
+import { EventList } from '@endge/utils';
+import { NovaDecoratedComponentOptions, NovaPropDecoratorOptions, NovaWatchDecoratorOptions } from './nova-component-metadata';
+import { NovaDefinedComponentOptions } from './nova-defined-component';
+/**
+ * Помечает class-компонент metadata для DSL и явной registry-регистрации.
+ */
+export declare function NovaComponent<E extends EventList = Record<string, any>>(options?: (NovaDefinedComponentOptions<E> & NovaDecoratedComponentOptions)): <T extends new (...args: Array<any>) => any>(target: T) => T;
+/**
+ * Описывает набор prop-декораторов Nova.
+ */
+export declare const Prop: {
+    model: <T = unknown>(options?: NovaPropDecoratorOptions<T>) => (target: object, propertyKey: string | symbol, _descriptor?: PropertyDescriptor) => void;
+    object: <T = unknown>(options?: NovaPropDecoratorOptions<T>) => (target: object, propertyKey: string | symbol, _descriptor?: PropertyDescriptor) => void;
+    options: <T = unknown>(options?: NovaPropDecoratorOptions<T>) => (target: object, propertyKey: string | symbol, _descriptor?: PropertyDescriptor) => void;
+    array: <T = unknown>(options?: NovaPropDecoratorOptions<T>) => (target: object, propertyKey: string | symbol, _descriptor?: PropertyDescriptor) => void;
+    string: <T = unknown>(options?: NovaPropDecoratorOptions<T>) => (target: object, propertyKey: string | symbol, _descriptor?: PropertyDescriptor) => void;
+    number: <T = unknown>(options?: NovaPropDecoratorOptions<T>) => (target: object, propertyKey: string | symbol, _descriptor?: PropertyDescriptor) => void;
+    boolean: <T = unknown>(options?: NovaPropDecoratorOptions<T>) => (target: object, propertyKey: string | symbol, _descriptor?: PropertyDescriptor) => void;
+    function: <T = unknown>(options?: NovaPropDecoratorOptions<T>) => (target: object, propertyKey: string | symbol, _descriptor?: PropertyDescriptor) => void;
+};
+/**
+ * Помечает callback prop как event.
+ */
+export declare function Event(options?: NovaPropDecoratorOptions): (target: object, propertyKey: string | symbol, _descriptor?: PropertyDescriptor) => void;
+/**
+ * Регистрирует watcher prop/path.
+ */
+export declare function Watch(path: string, options?: NovaWatchDecoratorOptions): (target: object, propertyKey: string | symbol, _descriptor?: PropertyDescriptor) => void;
+/**
+ * Регистрирует command handler.
+ */
+export declare function Command(id: string, options?: {
+    scope?: string;
+}): (target: object, propertyKey: string | symbol, _descriptor?: PropertyDescriptor) => void;
+/**
+ * Помечает метод как часть public API.
+ */
+export declare function Api(): (target: object, propertyKey: string | symbol, _descriptor?: PropertyDescriptor) => void;

package/dist/model/runtime/components/nova-defined-component.d.ts

@@ -0,0 +1,58 @@
+import { EventList, OneOrMany } from '@endge/utils';
+import { NovaComponentCreateContext, NovaComponentDescriptor, NovaComponentSchema, NovaElementConstructor, NovaElementSlots } from '../../../domain/types/component.types';
+import { NovaSchemaRegistry } from './NovaSchemaRegistry';
+import { NovaNode } from '../tree/NovaNode';
+export interface NovaComponentListeners {
+    [key: string]: (...args: Array<any>) => void;
+}
+export interface NovaDefinedComponentOptions<E extends EventList = Record<string, any>> {
+    tag?: string;
+    name?: string;
+    version?: string;
+    createNode?: (context: NovaComponentCreateContext<E>, schema: NovaComponentSchema<Record<string, any>>) => NovaNode<E>;
+}
+export interface NovaDefinedComponentInput<E extends EventList = Record<string, any>> extends NovaDefinedComponentOptions<E> {
+    component: NovaElementConstructor<E>;
+}
+export interface NovaNormalizedDefinedComponent<E extends EventList = Record<string, any>> {
+    component: NovaElementConstructor<E>;
+    tag?: string;
+    name: string;
+    version: string;
+    descriptor?: NovaComponentDescriptor<any, any, any, any>;
+    createNode?: (context: NovaComponentCreateContext<E>, schema: NovaComponentSchema<Record<string, any>>) => NovaNode<E>;
+}
+/**
+ * Декоратор и статический Nova.defineComponent хранят metadata на constructor.
+ */
+export declare function defineNovaComponent<E extends EventList, T extends NovaElementConstructor<E>>(component: T, options?: NovaDefinedComponentOptions<E>): T;
+/**
+ * Возвращает metadata class-компонента, если он был помечен define/decorator.
+ */
+export declare function readDefinedComponent<E extends EventList = Record<string, any>>(component: NovaElementConstructor<E>): NovaDefinedComponentOptions<E> | undefined;
+/**
+ * Нормализует class-компонент или explicit definition в единый формат регистрации.
+ */
+export declare function normalizeDefinedComponent<E extends EventList = Record<string, any>>(input: NovaElementConstructor<E> | NovaDefinedComponentInput<E>): NovaNormalizedDefinedComponent<E>;
+/**
+ * Регистрирует один или несколько class-компонентов в schema registry.
+ */
+export declare function registerDefinedComponents<E extends EventList = Record<string, any>>(registry: NovaSchemaRegistry, inputs: OneOrMany<NovaElementConstructor<E> | NovaDefinedComponentInput<E>>): void;
+/**
+ * Инстанцирует direct constructor component с учетом metadata и generic runtime state.
+ */
+export declare function createDefinedComponentNode<E extends EventList = Record<string, any>>(component: NovaElementConstructor<E>, context: NovaComponentCreateContext<E>, options?: {
+    schema?: NovaComponentSchema<Record<string, any>>;
+    componentId?: string;
+    listeners?: NovaComponentListeners;
+    slots?: NovaElementSlots;
+}): NovaNode<E>;
+/**
+ * Добавляет plain NovaNode минимальный component runtime layer: props, listeners и component id.
+ */
+export declare function attachRuntimeComponentState(node: NovaNode<any>, options?: {
+    componentId?: string;
+    props?: Record<string, any>;
+    listeners?: NovaComponentListeners;
+    slots?: NovaElementSlots;
+}): void;

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

@@ -0,0 +1,5 @@
+import { NovaContextToken } from '../../../domain/types/context.types';
+/**
+ * Создает типизированный token для scoped dependency в Nova tree.
+ */
+export declare function createNovaContextToken<T>(name: string): NovaContextToken<T>;

package/dist/model/runtime/cursor/NovaCursorManager.d.ts

@@ -0,0 +1,148 @@
+import { EventList } from '@endge/utils';
+import { NovaCursorDeclaration, NovaCursorRuntimeState, NovaCursorValue } from '../../../domain/types/cursor.types';
+import { NovaApp } from '../app/NovaApp';
+import { NovaNode } from '../tree/NovaNode';
+/**
+ * Описывает входные данные для синхронизации cursor с pointer.
+ */
+export interface NovaCursorPointerSync<E extends EventList> {
+    x: number;
+    y: number;
+    target: NovaNode<E> | null;
+    pressed?: boolean;
+    dragging?: boolean;
+}
+/**
+ * Централизованно выбирает cursor, обновляет DOM cursor и управляет component cursor overlay.
+ */
+export declare class NovaCursorManager<E extends EventList = Record<string, any>> {
+    private readonly app;
+    readonly cursorNodes: Set<NovaNode<E>>;
+    lastHitTestCandidates: number;
+    private readonly _spatialIndex;
+    private readonly _spatialDirtyNodes;
+    private readonly _componentNodes;
+    private _spatialFullDirty;
+    private _overlaySurface;
+    private _activeComponentKey;
+    private _lastCursorKey;
+    private _lastDomCursor;
+    private _lastSource;
+    private _lastState;
+    /**
+     * Создает cursor manager для приложения.
+     */
+    constructor(app: NovaApp<E>);
+    /**
+     * Регистрирует node как носителя cursor declaration.
+     */
+    register(node: NovaNode<E>): void;
+    /**
+     * Удаляет node из cursor index и active references.
+     */
+    unregister(node: NovaNode<E>): void;
+    /**
+     * Помечает spatial index грязным.
+     */
+    markSpatialDirty(node?: NovaNode<E>, includeChildren?: boolean): void;
+    /**
+     * Синхронизирует cursor с текущим pointer state.
+     */
+    syncPointer(input: NovaCursorPointerSync<E>): void;
+    /**
+     * Сбрасывает cursor в default.
+     */
+    reset(): void;
+    /**
+     * Обновляет native cursor напрямую для legacy API.
+     */
+    setNativeCursor(value: string): void;
+    /**
+     * Освобождает component cursor overlay.
+     */
+    destroy(): void;
+    /**
+     * Возвращает последнюю примененную строку DOM cursor.
+     */
+    get lastDomCursor(): string;
+    /**
+     * Возвращает последнюю source node.
+     */
+    get lastSource(): NovaNode<E> | null;
+    /**
+     * Возвращает ключ последнего примененного cursor declaration.
+     */
+    get lastCursorKey(): string;
+    /**
+     * Возвращает последний runtime state cursor.
+     */
+    get lastState(): NovaCursorRuntimeState<E> | null;
+    /**
+     * Восстанавливает DOM cursor после render/backend writers, если они перезаписали canvas style.
+     */
+    reapplyNativeCursor(): void;
+    /**
+     * Возвращает фактическую policy cursor hit-test индекса.
+     */
+    get hitTestIndexPolicy(): 'rbush';
+    /**
+     * Возвращает количество node в cursor hit-test индексе.
+     */
+    get hitTestIndexedNodeCount(): number;
+    /**
+     * Нормализует и возвращает итоговое значение NovaCursorManager.
+     */
+    private resolveCursorSource;
+    /**
+     * Находит сущность по runtime-критериям NovaCursorManager.
+     */
+    private findCursorAncestor;
+    /**
+     * Выполняет внутренний шаг cursorHitTest для NovaCursorManager.
+     */
+    private cursorHitTest;
+    /**
+     * Возвращает значение состояния NovaCursorManager.
+     */
+    private getCursorCandidates;
+    /**
+     * Синхронизирует dirty nodes с cursor spatial index.
+     */
+    private syncSpatialIndex;
+    /**
+     * Создает runtime-сущность NovaCursorManager.
+     */
+    private createRuntimeState;
+    /**
+     * Применяет подготовленное состояние NovaCursorManager.
+     */
+    private applyCursorValue;
+    /**
+     * Применяет подготовленное состояние NovaCursorManager.
+     */
+    private applyComponentCursor;
+    /**
+     * Нормализует и возвращает итоговое значение NovaCursorManager.
+     */
+    private resolveComponentNode;
+    /**
+     * Нормализует и возвращает итоговое значение NovaCursorManager.
+     */
+    private resolveOverlaySurface;
+    /**
+     * Выполняет внутренний шаг hideActiveComponent для NovaCursorManager.
+     */
+    private hideActiveComponent;
+    /**
+     * Выполняет внутренний шаг hideComponentNode для NovaCursorManager.
+     */
+    private hideComponentNode;
+    /**
+     * Применяет подготовленное состояние NovaCursorManager.
+     */
+    private applyNativeCursor;
+}
+/**
+ * Вычисляет cursor value по declaration и runtime state.
+ */
+export declare function resolveNovaCursorValue<E extends EventList>(declaration: NovaCursorDeclaration | null | undefined, state: NovaCursorRuntimeState<E>): NovaCursorValue | null;

package/dist/model/runtime/debug/NovaDebug.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Собирает debug-информацию по кадрам и фазам runtime.
+ */
+export declare class NovaDebug {
+    private _enabled;
+    private _lastLogFrameTimes;
+    private readonly _logThrottleTime;
+    private _shouldLogFrame;
+    private _frameStartTime;
+    private _phaseStart;
+    private _phaseName;
+    private _phaseStack;
+    private _lastFrameTime;
+    private _lastFps;
+    private _displayFps;
+    private _displayTick;
+    private _lastRenderedTick;
+    private _lastRenderedAt;
+    private _displayFrameTimes;
+    private _displayRafId;
+    private _framePhases;
+    private _frameLogs;
+    private _phaseLogs;
+    private _timers;
+    /**
+     * Обновляет enabled.
+     */
+    set enabled(v: boolean);
+    /**
+     * Возвращает enabled.
+     */
+    get enabled(): boolean;
+    /**
+     * Возвращает last frame time.
+     */
+    get lastFrameTime(): number;
+    /**
+     * Возвращает last fps.
+     */
+    get lastFps(): number;
+    /**
+     * Возвращает display fps.
+     */
+    get displayFps(): number;
+    /**
+     * Запускает связанную runtime-операцию.
+     */
+    startDisplayMonitor(): void;
+    /**
+     * Останавливает связанную runtime-операцию.
+     */
+    stopDisplayMonitor(): void;
+    /**
+     * Помечает rendered frame.
+     */
+    markRenderedFrame(): void;
+    /**
+     * Выполняет внутреннюю операцию frame start.
+     */
+    frameStart(group?: string | null): void;
+    /**
+     * Выполняет внутреннюю операцию frame end.
+     */
+    frameEnd(title?: string): void;
+    /**
+     * Выполняет внутреннюю операцию phase start.
+     */
+    phaseStart(name: string): void;
+    /**
+     * Выполняет внутреннюю операцию phase end.
+     */
+    phaseEnd(): void;
+    /**
+     * Выполняет внутреннюю операцию face log.
+     */
+    faceLog(message: string): void;
+    /**
+     * Запускает связанную runtime-операцию.
+     */
+    startTimer(label: string): void;
+    /**
+     * Выполняет внутреннюю операцию info.
+     */
+    info(message: string, timerLabel?: string): void;
+    /**
+     * Выполняет внутреннюю операцию warn.
+     */
+    warn(message: string, timerLabel?: string): void;
+    /**
+     * Выполняет внутреннюю операцию error.
+     */
+    error(message: string, timerLabel?: string): void;
+    /**
+     * Выполняет внутреннюю операцию success.
+     */
+    success(message: string, timerLabel?: string): void;
+    /**
+     * Выполняет внутреннюю операцию log to phase.
+     */
+    private logToPhase;
+    /**
+     * Выполняет внутреннюю операцию print colored.
+     */
+    private printColored;
+}

package/dist/model/runtime/debug/NovaMetrics.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Описывает контракт NovaMetricsSnapshot.
+ */
+export interface NovaMetricsSnapshot {
+    rFps: number;
+    fps: number;
+    ups: number;
+    last: number;
+    idle: number;
+}
+/**
+ * Считает runtime-метрики кадров, draw events и update frequency.
+ */
+export declare class NovaMetrics {
+    private readonly readUps;
+    private _rafId;
+    private _rafLastAt;
+    private _rafFrames;
+    private _rFps;
+    private _drawLastAt;
+    private _drawWindowAt;
+    private _drawFrames;
+    private _fps;
+    private _frameStartedAt;
+    private _last;
+    /**
+     * Создает instance и подготавливает внутреннее состояние.
+     */
+    constructor(readUps: () => number);
+    /**
+     * Запускает связанную runtime-операцию.
+     */
+    start(): void;
+    /**
+     * Останавливает связанную runtime-операцию.
+     */
+    stop(): void;
+    /**
+     * Помечает frame start.
+     */
+    markFrameStart(now?: number): void;
+    /**
+     * Помечает frame end.
+     */
+    markFrameEnd(now?: number): void;
+    /**
+     * Помечает draw.
+     */
+    markDraw(now?: number): void;
+    /**
+     * Выполняет внутреннюю операцию snapshot.
+     */
+    snapshot(now?: number): NovaMetricsSnapshot;
+    private tickRaf;
+}