@endge/nova 0.13.6 → 0.13.11

package/dist/domain/constants/nova-phase.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Описывает стандартные фазы Nova runtime pipeline.
+ */
+export declare const NovaPhase: {
+    readonly Before: "before";
+    readonly PreUpdate: "preupdate";
+    readonly Update: "update";
+    readonly Matrix: "matrix";
+    readonly Render: "render";
+    readonly Flush: "flush";
+    readonly After: "after";
+};
+/**
+ * Описывает имя стандартной фазы Nova runtime pipeline.
+ */
+export type NovaPhaseName = typeof NovaPhase[keyof typeof NovaPhase];

package/dist/domain/types/base.types.d.ts

@@ -0,0 +1,177 @@
+import { RaphKernel, RaphProperties, RaphSchedulerType } from '@endge/raph';
+import { EventList } from '@endge/utils';
+import { mat3 } from 'gl-matrix';
+import { NovaCursorContext, NovaCursorDeclaration } from './cursor.types';
+import { NovaDiagnosticsOptions } from './diagnostics.types';
+import { NovaHitTestHandler } from './hit-test.types';
+import { RendererType } from './renderer.types';
+import { NovaRendererConfigInput } from './rendering/index';
+import { NovaSoundOptions } from './sound.types';
+import { NovaThemeCreateOptions } from './theme.types';
+import { NovaSchemaRegistry } from '../../model/runtime/components/NovaSchemaRegistry';
+import { NovaSyncScope } from '../../model/runtime/sync/NovaSyncScope';
+/**
+ * Описывает контракт NovaNodeProperties.
+ */
+export interface NovaNodeProperties extends RaphProperties {
+    localActive: boolean;
+    localVisible: boolean;
+    interactive: boolean;
+    propagateUpdate: boolean;
+    cursor: NovaCursorDeclaration | null;
+    cursorContext: NovaCursorContext | null;
+    hitTest: NovaHitTestHandler | null;
+    active: boolean;
+    x: number;
+    y: number;
+    scaleX: number;
+    scaleY: number;
+    rotation: number;
+    matrix: mat3;
+    visible: boolean;
+    opacity: number;
+    width: number;
+    height: number;
+}
+/**
+ * Описывает контракт NovaAppOptions.
+ */
+export interface NovaAppOptions {
+    debug: boolean | string | Array<string>;
+    diagnostics: NovaDiagnosticsOptions;
+    loop: boolean;
+    width: number;
+    height: number;
+    dpr: number;
+    maxDpr: number;
+}
+/**
+ * Описывает тип NovaCanvasTarget.
+ */
+export type NovaCanvasTarget = HTMLCanvasElement;
+/**
+ * Описывает контракт NovaSizeOptions.
+ */
+export interface NovaSizeOptions {
+    width: number;
+    height: number;
+    dpr?: number;
+    maxDpr?: number;
+}
+/**
+ * Описывает тип NovaPointerScope.
+ */
+export type NovaPointerScope = 'target';
+/**
+ * Описывает тип NovaKeyboardScope.
+ */
+export type NovaKeyboardScope = 'focused' | 'active' | 'hovered' | 'global' | 'manual';
+/**
+ * Описывает тип NovaInputPreventDefault.
+ */
+export type NovaInputPreventDefault = 'never' | 'handled' | 'always';
+/**
+ * Описывает контракт NovaPointerInputOptions.
+ */
+export interface NovaPointerInputOptions {
+    enabled?: boolean;
+    scope?: NovaPointerScope;
+    capture?: boolean;
+}
+/**
+ * Описывает контракт NovaKeyboardInputOptions.
+ */
+export interface NovaKeyboardInputOptions {
+    enabled?: boolean;
+    scope?: NovaKeyboardScope;
+    preventDefault?: NovaInputPreventDefault;
+    ignoreEditableTargets?: boolean;
+}
+/**
+ * Описывает контракт NovaInputOptions.
+ */
+export interface NovaInputOptions {
+    pointer?: NovaPointerInputOptions;
+    keyboard?: NovaKeyboardInputOptions;
+}
+/**
+ * Описывает контракт ResolvedNovaInputOptions.
+ */
+export interface ResolvedNovaInputOptions {
+    pointer: {
+        enabled: boolean;
+        capture: boolean;
+    };
+    keyboard: {
+        enabled: boolean;
+        scope: NovaKeyboardScope;
+        preventDefault: NovaInputPreventDefault;
+        ignoreEditableTargets: boolean;
+    };
+}
+/**
+ * Описывает контракт NovaRendererOptions.
+ */
+export interface NovaRendererOptions {
+    main?: RendererType;
+    webgl?: WebGLContextAttributes;
+    config?: NovaRendererConfigInput;
+}
+/**
+ * Описывает контракт NovaSchedulerOptions.
+ */
+export interface NovaSchedulerOptions {
+    type?: RaphSchedulerType;
+    loop?: boolean;
+}
+/**
+ * Описывает контракт NovaDebugOptions.
+ */
+export interface NovaDebugOptions {
+    enabled?: boolean | string | Array<string>;
+    telemetry?: boolean;
+    overlay?: boolean;
+}
+/**
+ * Описывает настройки подключения NovaApp к Raph runtime/kernel.
+ */
+export interface NovaRaphOptions {
+    kernel?: RaphKernel;
+    runtimeId?: string;
+}
+/**
+ * Описывает наследование глобальной темы Nova.
+ */
+export interface NovaGlobalThemeCreateOptions {
+    inherit?: boolean;
+}
+/**
+ * Описывает контракт NovaAppCreateOptions.
+ */
+export interface NovaAppCreateOptions<E extends EventList = Record<string, any>> {
+    target: NovaCanvasTarget;
+    size: NovaSizeOptions;
+    input?: NovaInputOptions;
+    renderer?: NovaRendererOptions;
+    scheduler?: NovaSchedulerOptions;
+    sound?: NovaSoundOptions;
+    theme?: NovaThemeCreateOptions;
+    globalTheme?: NovaGlobalThemeCreateOptions;
+    debug?: NovaDebugOptions;
+    diagnostics?: NovaDiagnosticsOptions;
+    raph?: NovaRaphOptions;
+    syncScope?: NovaSyncScope;
+    predefinedEvents?: Array<keyof E>;
+    schemaRegistry?: NovaSchemaRegistry;
+}
+/**
+ * Описывает тип NovaCanvasOwnership.
+ */
+export type NovaCanvasOwnership = 'external' | 'internal';
+/**
+ * Описывает контракт NovaCanvasCreateOptions.
+ */
+export interface NovaCanvasCreateOptions extends Partial<NovaSizeOptions> {
+    webgl?: WebGLContextAttributes;
+    contextType?: RendererType;
+}

package/dist/domain/types/component.types.d.ts

@@ -0,0 +1,156 @@
+import { EventList } from '@endge/utils';
+import { NovaBounds, NovaRenderer, NovaSchema } from './renderer.types';
+import { NovaApp } from '../../model/runtime/app/NovaApp';
+import { NovaSchemaRegistry } from '../../model/runtime/components/NovaSchemaRegistry';
+import { NovaNode } from '../../model/runtime/tree/NovaNode';
+import { NovaSurface } from '../../model/runtime/tree/NovaSurface';
+/**
+ * Описывает тип NovaSchemaDescriptorKind.
+ */
+export type NovaSchemaDescriptorKind = 'primitive' | 'schema-component' | 'node-component';
+/**
+ * Описывает тип NovaSchemaRenderMode.
+ */
+export type NovaSchemaRenderMode = 'schema' | 'batched' | 'ordered';
+/**
+ * Описывает тип NovaComponentDirtyPhase.
+ */
+export type NovaComponentDirtyPhase = 'update' | 'render' | 'matrix';
+/**
+ * Constructor runtime-компонента, который может быть создан напрямую без string registry key.
+ */
+export type NovaElementConstructor<E extends EventList = Record<string, any>> = new (app: NovaApp<E>, surface: NovaSurface<E>, props?: Record<string, any>, listeners?: Record<string, (...args: Array<any>) => void>, slots?: NovaElementSlots) => NovaNode<E>;
+/**
+ * Фабрика named slot, которая строит schema snapshot по публичному scope.
+ */
+export type NovaElementSlotFactory<TScope = Record<string, any>> = (scope?: TScope) => Array<NovaElementSchema<any>>;
+/**
+ * Набор named slots для runtime component schema.
+ */
+export type NovaElementSlots = Record<string, NovaElementSlotFactory<any>>;
+/**
+ * Тип компонента в runtime trees: string schema type или прямой constructor.
+ */
+export type NovaElementType<E extends EventList = Record<string, any>> = string | NovaElementConstructor<E>;
+/**
+ * Описывает контракт NovaComponentDirtyPolicy.
+ */
+export type NovaComponentDirtyPath<TProps extends Record<string, any> = Record<string, any>> = keyof TProps | string;
+/**
+ * Описывает контракт NovaComponentDirtyPolicy.
+ */
+export interface NovaComponentDirtyPolicy<TProps extends Record<string, any> = Record<string, any>> {
+    update?: ReadonlyArray<NovaComponentDirtyPath<TProps>>;
+    render?: ReadonlyArray<NovaComponentDirtyPath<TProps>>;
+    matrix?: ReadonlyArray<NovaComponentDirtyPath<TProps>>;
+}
+/**
+ * Описывает kind prop-декоратора.
+ */
+export type NovaComponentPropKind = 'model' | 'object' | 'options' | 'array' | 'string' | 'number' | 'boolean' | 'function';
+/**
+ * Описывает prop metadata class-компонента.
+ */
+export interface NovaComponentPropDefinition {
+    key: string;
+    propertyKey?: string;
+    kind: NovaComponentPropKind;
+    required?: boolean;
+    defaultValue?: unknown | (() => unknown);
+    mode?: 'plain' | 'versioned';
+    event?: boolean;
+}
+/**
+ * Описывает watcher metadata class-компонента.
+ */
+export interface NovaComponentWatchDefinition {
+    path: string;
+    methodName: string;
+    phase: 'update' | 'render' | 'matrix';
+    immediate?: boolean;
+}
+/**
+ * Описывает command metadata class-компонента.
+ */
+export interface NovaComponentCommandDefinition {
+    id: string;
+    methodName: string;
+    scope?: string;
+}
+/**
+ * Описывает API metadata class-компонента.
+ */
+export interface NovaComponentApiDefinition {
+    methodName: string;
+}
+/**
+ * Описывает контракт NovaComponentSchema.
+ */
+export interface NovaComponentSchema<TSchema = Record<string, any>> {
+    type: string;
+    id?: string;
+    props?: Partial<TSchema> & Record<string, any>;
+    slots?: NovaElementSlots;
+    [key: string]: any;
+}
+/**
+ * Описывает runtime tree schema item, который может ссылаться на string type или constructor.
+ */
+export interface NovaElementSchema<TSchema = Record<string, any>, TType extends NovaElementType = NovaElementType> extends Omit<NovaComponentSchema<TSchema>, 'type'> {
+    type: TType;
+}
+/**
+ * Описывает runtime component node, доступный через app.components.
+ */
+export interface NovaRuntimeComponentNode {
+    componentId: string;
+    getApi: () => unknown;
+}
+/**
+ * Описывает контракт NovaSchemaRenderContext.
+ */
+export interface NovaSchemaRenderContext {
+    renderer: NovaRenderer;
+    registry: NovaSchemaRegistry;
+    depth: number;
+}
+/**
+ * Описывает контракт NovaSchemaBoundsContext.
+ */
+export interface NovaSchemaBoundsContext {
+    registry: NovaSchemaRegistry;
+    depth: number;
+}
+/**
+ * Описывает контракт NovaComponentCreateContext.
+ */
+export interface NovaComponentCreateContext<E extends EventList = Record<string, any>> {
+    app: NovaApp<E>;
+    surface: NovaSurface<E>;
+    registry: NovaSchemaRegistry;
+    parent?: NovaNode<E>;
+    context?: unknown;
+}
+/**
+ * Описывает контракт NovaComponentDescriptor.
+ */
+export interface NovaComponentDescriptor<TProps extends Record<string, any> = Record<string, any>, TApi = unknown, TEvents extends Record<string, unknown> = Record<string, unknown>, TSchema = TProps> {
+    type: string;
+    name: string;
+    title?: string;
+    version: string;
+    kind: NovaSchemaDescriptorKind;
+    dirtyPolicy?: NovaComponentDirtyPolicy<TProps>;
+    propDefinitions?: ReadonlyArray<NovaComponentPropDefinition>;
+    watchDefinitions?: ReadonlyArray<NovaComponentWatchDefinition>;
+    commandDefinitions?: ReadonlyArray<NovaComponentCommandDefinition>;
+    apiDefinitions?: ReadonlyArray<NovaComponentApiDefinition>;
+    bounds?: 'size' | 'custom';
+    fields?: unknown;
+    api?: unknown | TApi;
+    events?: unknown | TEvents;
+    normalize?: (schema: NovaComponentSchema<TSchema>) => TProps;
+    renderSchema?: (ctx: NovaSchemaRenderContext, schema: NovaComponentSchema<TSchema>) => NovaSchema<any> | void;
+    measureBounds?: (ctx: NovaSchemaBoundsContext, schema: NovaComponentSchema<TSchema>) => NovaBounds | null;
+    createNode?: <E extends EventList>(ctx: NovaComponentCreateContext<E>, schema: NovaComponentSchema<TSchema>) => NovaNode<E>;
+}

package/dist/domain/types/context.types.d.ts

@@ -0,0 +1,31 @@
+import { DataPathDef, RaphObserveDataOptions, Traversal } from '@endge/raph';
+import { NovaPhaseName } from '../constants/nova-phase';
+/**
+ * Описывает типизированный token scoped dependency в Nova tree.
+ */
+export type NovaContextToken<T> = symbol & {
+    readonly __novaContextType?: T;
+};
+/**
+ * Описывает параметры явного контекста child-ноды.
+ */
+export interface NovaNodeContextOptions {
+    context?: unknown;
+}
+/**
+ * Описывает параметры добавления child-ноды.
+ */
+export interface NovaAddChildOptions extends NovaNodeContextOptions {
+    invalidate?: boolean;
+}
+/**
+ * Описывает параметры подписки Nova-ноды на business data path.
+ */
+export interface NovaObserveDataOptions extends Omit<RaphObserveDataOptions, 'phase' | 'traversal'> {
+    phase?: NovaPhaseName | string;
+    traversal?: Traversal;
+}
+/**
+ * Описывает публичную сигнатуру подписки Nova-ноды на business data path.
+ */
+export type NovaObserveData = (path: DataPathDef, options?: NovaObserveDataOptions) => () => void;

package/dist/domain/types/cursor.types.d.ts

@@ -0,0 +1,89 @@
+import { EventList } from '@endge/utils';
+import { NovaNode } from '../../model/runtime/tree/NovaNode';
+/**
+ * Описывает имя состояния pointer для выбора cursor.
+ */
+export type NovaCursorStateName = 'default' | 'hover' | 'pressed' | 'dragging' | 'disabled';
+/**
+ * Описывает встроенный CSS cursor.
+ */
+export type NovaNativeCursor = 'auto' | 'default' | 'none' | 'pointer' | 'text' | 'move' | 'grab' | 'grabbing' | 'not-allowed' | 'crosshair' | 'ew-resize' | 'ns-resize' | 'col-resize' | 'row-resize' | 'e-resize' | 'w-resize' | 'n-resize' | 's-resize' | 'ne-resize' | 'nw-resize' | 'se-resize' | 'sw-resize' | 'nesw-resize' | 'nwse-resize';
+/**
+ * Описывает hotspot cursor относительно левого верхнего угла.
+ */
+export interface NovaCursorHotspot {
+    x: number;
+    y: number;
+}
+/**
+ * Описывает cursor из внешнего image/svg URL.
+ */
+export interface NovaUrlCursorValue {
+    type: 'url';
+    src: string;
+    hotspot?: NovaCursorHotspot;
+    fallback?: NovaNativeCursor | string;
+}
+/**
+ * Описывает cursor как зарегистрированный Nova schema component.
+ */
+export interface NovaComponentCursorValue {
+    type: 'component';
+    component: string;
+    props?: Record<string, unknown>;
+    hotspot?: NovaCursorHotspot;
+    fallback?: NovaNativeCursor | string;
+}
+/**
+ * Описывает конкретное значение cursor.
+ */
+export type NovaCursorValue = NovaNativeCursor | (string & {}) | NovaUrlCursorValue | NovaComponentCursorValue;
+/**
+ * Описывает state-map форму cursor declaration.
+ */
+export interface NovaCursorStateMap {
+    default?: NovaCursorValue;
+    hover?: NovaCursorValue;
+    pressed?: NovaCursorValue;
+    dragging?: NovaCursorValue;
+    disabled?: NovaCursorValue;
+}
+/**
+ * Описывает значение контекста cursor rule.
+ */
+export type NovaCursorContextValue = string | number | boolean;
+/**
+ * Описывает условие cursor rule.
+ */
+export interface NovaCursorRuleCondition extends Record<string, NovaCursorContextValue | NovaCursorStateName | Array<NovaCursorStateName> | undefined> {
+    state?: NovaCursorStateName | Array<NovaCursorStateName>;
+}
+/**
+ * Описывает rule-форму cursor declaration.
+ */
+export interface NovaCursorRule {
+    when?: NovaCursorRuleCondition;
+    use: NovaCursorValue;
+}
+/**
+ * Описывает декларативный cursor для Nova node.
+ */
+export type NovaCursorDeclaration = NovaCursorValue | NovaCursorStateMap | Array<NovaCursorRule>;
+/**
+ * Описывает контекст cursor rule на node.
+ */
+export type NovaCursorContext = Record<string, NovaCursorContextValue>;
+/**
+ * Описывает runtime state pointer для выбора cursor.
+ */
+export interface NovaCursorRuntimeState<E extends EventList = Record<string, any>> {
+    x: number;
+    y: number;
+    hover: boolean;
+    pressed: boolean;
+    dragging: boolean;
+    disabled: boolean;
+    target: NovaNode<E> | null;
+    source: NovaNode<E> | null;
+    context: NovaCursorContext;
+}

package/dist/domain/types/diagnostics.types.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Описывает источник и точность диагностической метрики.
+ */
+export type NovaDiagnosticsMetricSource = 'exact' | 'estimated' | 'observed' | 'unavailable';
+/**
+ * Описывает категорию runtime diagnostics.
+ */
+export type NovaDiagnosticsCategory = 'runtime' | 'frame' | 'render' | 'resources' | 'browser' | 'input' | 'history';
+/**
+ * Описывает доступность группы диагностических данных.
+ */
+export interface NovaDiagnosticsAvailability {
+    runtime: NovaDiagnosticsMetricSource;
+    frame: NovaDiagnosticsMetricSource;
+    render: NovaDiagnosticsMetricSource;
+    resources: NovaDiagnosticsMetricSource;
+    browserHeap: NovaDiagnosticsMetricSource;
+    browserMemory: NovaDiagnosticsMetricSource;
+    browserDom: NovaDiagnosticsMetricSource;
+    browserLongTasks: NovaDiagnosticsMetricSource;
+    gpuProcessMemory: NovaDiagnosticsMetricSource;
+}
+/**
+ * Описывает настройки diagnostics runtime.
+ */
+export interface NovaDiagnosticsOptions {
+    enabled?: boolean;
+    browser?: boolean;
+    sampleIntervalMs?: number;
+    historyLimit?: number;
+    categories?: Array<NovaDiagnosticsCategory>;
+}
+/**
+ * Описывает runtime-счетчики NovaApp.
+ */
+export interface NovaDiagnosticsRuntimeSnapshot {
+    enabled: boolean;
+    fps: number;
+    renderFps: number;
+    ups: number;
+    idleMs: number;
+    surfaces: number;
+    dirtySurfaces: number;
+    nodes: number;
+    width: number;
+    height: number;
+    dpr: number;
+    loop: boolean;
+}
+/**
+ * Описывает timings последнего frame.
+ */
+export interface NovaDiagnosticsFrameSnapshot {
+    index: number;
+    lastMs: number;
+    phases: Record<string, number>;
+    dirtyNodes: number;
+    dirtyRenderNodes: number;
+    renderedAt: number;
+}
+/**
+ * Описывает renderer counters последнего replay.
+ */
+export interface NovaDiagnosticsRenderSnapshot {
+    compilerMs: number;
+    backendMs: number;
+    uploadMs: number;
+    drawMs: number;
+    drawCalls: number;
+    batches: number;
+    commands: number;
+    items: number;
+    groups: number;
+    uploadBytes: number;
+    bufferDataCalls: number;
+    bufferSubDataCalls: number;
+    fullUploads: number;
+    dirtyRangeCount: number;
+    nodeRenderCalls: number;
+    updatedHandles: number;
+    dirtyStreamRanges: number;
+    rebuiltNodes: number;
+    cachedNodes: number;
+    culledNodes: number;
+    cullingTests: number;
+    textRasterCount: number;
+    textRasterPixels: number;
+    textRasterBytes: number;
+    textRasterBoxPixels: number;
+    textRasterSavedPixels: number;
+    textRasterMs: number;
+}
+/**
+ * Описывает расчетные ресурсы, которыми владеет Nova runtime.
+ */
+export interface NovaDiagnosticsResourceSnapshot {
+    estimatedGpuMemoryMB: number;
+    estimatedTextureMemoryMB: number;
+    estimatedTextAtlasMemoryMB: number;
+    estimatedCachedTextureMemoryMB: number;
+    estimatedBufferMemoryMB: number;
+    estimatedCanvasMemoryMB: number;
+    textAtlasPages: number;
+    glyphAtlasPages: number;
+    textAtlasEvictions: number;
+    glyphAtlasEvictions: number;
+    textureBatchFallbacks: number;
+    atlasUploads: number;
+}
+/**
+ * Описывает наблюдаемые браузерные метрики.
+ */
+export interface NovaDiagnosticsBrowserSnapshot {
+    jsHeapUsedMB?: number;
+    jsHeapTotalMB?: number;
+    jsHeapLimitMB?: number;
+    userAgentMemoryMB?: number;
+    domNodes?: number;
+    documents?: number;
+    frames?: number;
+    longTasks?: number;
+    longTaskMs?: number;
+    resources?: number;
+    lastSampledAt?: number;
+}
+/**
+ * Описывает input diagnostics.
+ */
+export interface NovaDiagnosticsInputSnapshot {
+    hitTestMode: string;
+    hitTestIndexPolicy?: string;
+    lastHitTestCandidates: number;
+    cursorLastHitTestCandidates?: number;
+    hitTestIndexedNodes?: number;
+    cursorIndexedNodes?: number;
+}
+/**
+ * Описывает полный diagnostics snapshot.
+ */
+export interface NovaDiagnosticsSnapshot {
+    runtime: NovaDiagnosticsRuntimeSnapshot;
+    frame: NovaDiagnosticsFrameSnapshot;
+    render: NovaDiagnosticsRenderSnapshot;
+    resources: NovaDiagnosticsResourceSnapshot;
+    browser: NovaDiagnosticsBrowserSnapshot;
+    input: NovaDiagnosticsInputSnapshot;
+    availability: NovaDiagnosticsAvailability;
+}