@endge/nova 0.13.5 → 0.13.11

package/dist/model/runtime/tree/NovaSurface.d.ts

@@ -0,0 +1,95 @@
+import { ConstructorOrFactory, EventList } from '@endge/utils';
+import { NovaNodeProperties } from '../../../domain/types/base.types';
+import { NovaRenderCompileStats, NovaRenderCullingMode, NovaRenderCullingStats, NovaRenderer } from '../../../domain/types/renderer.types';
+import { NovaRenderFrame, NovaRenderMetrics } from '../../../domain/types/rendering/index';
+import { NovaCanvas } from '../../platform/NovaCanvas';
+import { NovaApp } from '../app/NovaApp';
+import { NovaRenderGraph } from '../../render/graph/NovaRenderGraph';
+import { NovaNode } from './NovaNode';
+/**
+ * Логическая render boundary внутри app-level render pass Nova.
+ */
+export declare class NovaSurface<E extends EventList> extends NovaNode<E> {
+    readonly name: string;
+    private _activeRenderContext;
+    private readonly _renderCompiler;
+    private readonly _renderGraph;
+    private _renderMetrics;
+    protected _dirty: boolean;
+    private _renderCullingMode;
+    private _renderCompileStats;
+    private _renderCullingStats;
+    private readonly _novaApp;
+    /**
+     * Создает logical surface. Canvas и backend принадлежат NovaApp.
+     */
+    constructor(name: string, app: NovaApp<E>);
+    /**
+     * Обновляет logical dimensions. Physical canvas принадлежит приложению.
+     */
+    options(opts: Partial<NovaNodeProperties>): this;
+    /**
+     * Компилирует surface в retained frame.
+     */
+    compileRenderFrame(): NovaRenderFrame;
+    /**
+     * Выполняет render hooks нод через recorder context.
+     */
+    renderWithContext(renderer: NovaRenderer): void;
+    /**
+     * Обновляет последние renderer metrics после backend replay.
+     */
+    setRenderMetrics(metrics: NovaRenderMetrics): void;
+    /**
+     * Помечает node как rebuilt во время compile.
+     */
+    markRenderNodeRebuilt(): void;
+    /**
+     * Помечает node как проверенную для culling.
+     */
+    markRenderNodeTestedForCulling(): void;
+    /**
+     * Помечает node как culled.
+     */
+    markRenderNodeCulled(): void;
+    /**
+     * Освобождает resources логического surface.
+     */
+    destroy(): void;
+    /**
+     * Создает node внутри этого surface.
+     */
+    createNode<T extends NovaNode<E>>(NodeClassOrFactory?: ConstructorOrFactory<T, [NovaApp<E>, NovaSurface<E>, ...Array<any>]>, ...args: Array<any>): T;
+    /**
+     * Возвращает app-owned canvas.
+     */
+    get canvas(): NovaCanvas;
+    /**
+     * Возвращает текущий render context. Доступен только во время compile.
+     */
+    get renderer(): NovaRenderer;
+    /**
+     * Возвращает render graph.
+     */
+    get renderGraph(): NovaRenderGraph;
+    /**
+     * Возвращает render culling mode.
+     */
+    get renderCullingMode(): NovaRenderCullingMode;
+    /**
+     * Обновляет render culling mode.
+     */
+    set renderCullingMode(value: NovaRenderCullingMode);
+    /**
+     * Возвращает compile stats последнего retained frame compile.
+     */
+    get renderCompileStats(): NovaRenderCompileStats;
+    /**
+     * Возвращает render culling stats.
+     */
+    get renderCullingStats(): NovaRenderCullingStats;
+    /**
+     * Возвращает последние retained renderer metrics.
+     */
+    get renderMetrics(): NovaRenderMetrics | null;
+}

package/dist/model/semantic/NovaSemanticService.d.ts

@@ -0,0 +1,30 @@
+import { NovaSemanticQueryOptions, NovaSemanticRegion, NovaSemanticRegisterOptions, NovaSemanticSnapshot, NovaSemanticSnapshotOptions } from '../../domain/types/semantic.types';
+/**
+ * Хранит bounded semantic regions без DOM-оверлея и без участия в render hot path.
+ */
+export declare class NovaSemanticService {
+    private readonly regions;
+    private readonly sourceIndex;
+    private insertionCounter;
+    private autoIdCounter;
+    private focusedByScope;
+    register(options: NovaSemanticRegisterOptions): NovaSemanticRegion;
+    update(id: string, patch: Partial<Omit<NovaSemanticRegisterOptions, 'id'>>): NovaSemanticRegion | undefined;
+    remove(id: string): boolean;
+    clearScope(scope?: string): void;
+    clearSource(sourceKey: string): void;
+    syncSource(sourceKey: string, regions: Array<NovaSemanticRegisterOptions>): Array<NovaSemanticRegion>;
+    query(options?: NovaSemanticQueryOptions): Array<NovaSemanticRegion>;
+    snapshot(options?: NovaSemanticSnapshotOptions): NovaSemanticSnapshot;
+    focusNext(options?: NovaSemanticQueryOptions): NovaSemanticRegion | undefined;
+    focusPrevious(options?: NovaSemanticQueryOptions): NovaSemanticRegion | undefined;
+    getFocused(scope?: string): NovaSemanticRegion | undefined;
+    setFocused(id: string | null, scope?: string): NovaSemanticRegion | undefined;
+    clear(): void;
+    reset(): void;
+    private moveFocus;
+    private addToSourceIndex;
+    private removeFromSourceIndex;
+    private findAnyFocusedId;
+    private clearRegionFocused;
+}

package/dist/model/sound/NovaSoundEngine.d.ts

@@ -0,0 +1,134 @@
+import { NovaSoundCueInput, NovaSoundDescriptor, NovaSoundHandle, NovaSoundOptions, NovaSoundPlayOptions, NovaSoundStats } from '../../domain/types/sound.types';
+import { NovaApp } from '../runtime/app/NovaApp';
+/**
+ * Управляет загрузкой, кэшированием и воспроизведением звуков Nova runtime.
+ */
+export declare class NovaSoundEngine {
+    private readonly descriptors;
+    private readonly assets;
+    private readonly activeHandles;
+    private readonly lastPlayedAt;
+    private readonly categoryVolumes;
+    private readonly formats;
+    private readonly backend;
+    private readonly maxVoices;
+    private readonly unlockMode;
+    private enabled;
+    private muted;
+    private volume;
+    private played;
+    private skipped;
+    private unlocked;
+    /**
+     * Создает instance и выбирает audio backend.
+     */
+    constructor(_app: NovaApp<any>, options?: NovaSoundOptions);
+    /**
+     * Загружает один или несколько sound descriptors.
+     */
+    load(input: NovaSoundDescriptor | Array<NovaSoundDescriptor>): Promise<void>;
+    /**
+     * Алиас для фоновой предзагрузки sound descriptors.
+     */
+    preload(input: NovaSoundDescriptor | Array<NovaSoundDescriptor>): Promise<void>;
+    /**
+     * Запускает воспроизведение sound asset.
+     */
+    play(id: string, options?: NovaSoundPlayOptions): NovaSoundHandle;
+    /**
+     * Останавливает конкретный handle, asset id или все активные звуки.
+     */
+    stop(target?: NovaSoundHandle | string): void;
+    /**
+     * Обновляет master mute.
+     */
+    setMuted(muted: boolean): void;
+    /**
+     * Обновляет master volume.
+     */
+    setVolume(volume: number): void;
+    /**
+     * Обновляет громкость категории.
+     */
+    setCategoryVolume(category: string, volume: number): void;
+    /**
+     * Разблокирует browser audio context после пользовательского жеста.
+     */
+    unlock(): Promise<void>;
+    /**
+     * Разблокирует audio context только для режима first-input.
+     */
+    unlockFromInput(): void;
+    /**
+     * Создает scene/component scope для привязанных playback.
+     */
+    scope(name: string): NovaSoundScope;
+    /**
+     * Возвращает runtime stats.
+     */
+    stats(): NovaSoundStats;
+    /**
+     * Освобождает active handles, cache и backend resources.
+     */
+    destroy(): void;
+    /**
+     * Проигрывает sound cue input.
+     */
+    playCue(input: NovaSoundCueInput | undefined): NovaSoundHandle | null;
+    /**
+     * Загружает один descriptor.
+     */
+    private loadOne;
+    /**
+     * Проверяет cooldown и instance limits.
+     */
+    private canPlay;
+    /**
+     * Останавливает предыдущее воспроизведение с тем же dedupe key.
+     */
+    private stopDedupeHandle;
+    /**
+     * Освобождает место в voice pool при необходимости.
+     */
+    private enforceVoicePool;
+    /**
+     * Удаляет завершенный handle из active pool.
+     */
+    private finishHandle;
+    /**
+     * Фиксирует skipped playback.
+     */
+    private skip;
+    /**
+     * Создает лучший доступный backend.
+     */
+    private createBackend;
+}
+/**
+ * Управляет playback handles в рамках scene/component scope.
+ */
+export declare class NovaSoundScope {
+    private readonly engine;
+    readonly name: string;
+    private readonly handles;
+    /**
+     * Создает scope.
+     */
+    constructor(engine: NovaSoundEngine, name: string);
+    /**
+     * Запускает scoped sound.
+     */
+    play(id: string, options?: NovaSoundPlayOptions): NovaSoundHandle;
+    /**
+     * Запускает scoped sound cue.
+     */
+    playCue(input: NovaSoundCueInput | undefined): NovaSoundHandle | null;
+    /**
+     * Останавливает и освобождает scope.
+     */
+    destroy(): void;
+    /**
+     * Отслеживает handle до завершения.
+     */
+    private track;
+}

package/dist/model/telemetry.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Описывает тип EventKind.
+ */
+export type EventKind = 'ctx:create' | 'ctx:destroy' | 'ctx:lost' | 'ctx:restored' | 'gl:error' | 'canvas:resize' | 'res:create' | 'res:delete' | 'raf:drop' | 'page' | 'visibility';
+/**
+ * Описывает тип Evt.
+ */
+export interface Evt {
+    t: number;
+    k: EventKind;
+    s?: string;
+    g?: string;
+    d: any;
+}
+/**
+ * Описывает тип FrameStat.
+ */
+export interface FrameStat {
+    t: number;
+    s?: string;
+    g?: string;
+    bytes: number;
+    draws: number;
+    rects?: number;
+    batches?: number;
+    backbufferBytes?: number;
+}
+/**
+ * Описывает тип Snapshot.
+ */
+interface Snapshot {
+    label: string;
+    at: number;
+    stats: Array<FrameStat>;
+    events: Array<Evt>;
+}
+/**
+ * Описывает тип SnapshotHandler.
+ */
+type SnapshotHandler = (snap: Snapshot) => void;
+/**
+ * Собирает graphics telemetry events и статистику кадров.
+ */
+export declare class GfxTelemetry {
+    private readonly eventsLimit;
+    private readonly statsLimit;
+    private _enabled;
+    private _events;
+    private _stats;
+    private _snapListeners;
+    lastSnap?: Snapshot;
+    private _accBytes;
+    /**
+     * Возвращает enabled.
+     */
+    get enabled(): boolean;
+    /**
+     * Обновляет enabled.
+     */
+    set enabled(value: boolean);
+    /**
+     * Обрабатывает событие snapshot.
+     */
+    onSnapshot(cb: SnapshotHandler): () => void;
+    /**
+     * Выполняет внутреннюю операцию emit snapshot.
+     */
+    private _emitSnapshot;
+    /**
+     * Добавляет upload bytes.
+     */
+    addUploadBytes(n: number): void;
+    /**
+     * Выполняет внутреннюю операцию consume acc bytes.
+     */
+    consumeAccBytes(): number;
+    /**
+     * Создает instance и подготавливает внутреннее состояние.
+     */
+    constructor(opts?: {
+        eventsLimit?: number;
+        statsLimit?: number;
+    });
+    /**
+     * Выполняет внутреннюю операцию event.
+     */
+    event(k: EventKind, d?: any, s?: string, g?: string): void;
+    /**
+     * Выполняет внутреннюю операцию stat.
+     */
+    stat(partial: Omit<FrameStat, 't'>): void;
+    /**
+     * Выполняет внутреннюю операцию snapshot.
+     */
+    snapshot(label: string): Snapshot;
+}
+export declare const Telemetry: GfxTelemetry;
+/**
+ * Выполняет публичную операцию analyze snapshot.
+ */
+export declare function analyzeSnapshot(snap: {
+    stats: Array<FrameStat>;
+    events: Array<Evt>;
+}): {
+    flags: string[];
+    notes: any;
+};
+export {};

package/dist/model/text-selection/NovaTextSelectionService.d.ts

@@ -0,0 +1,85 @@
+import { NovaClipboardResult } from '../input/NovaClipboardService';
+import { NovaTextSelectionHit, NovaTextSelectionOptions, NovaTextSelectionRange, NovaTextSelectionState, NovaTextSelectionTarget } from './nova-text-selection.types';
+/**
+ * Инкапсулирует сервисную логику NovaTextSelectionService.
+ */
+export declare class NovaTextSelectionService<TContext = unknown> {
+    private options;
+    private readonly clipboard;
+    private readonly targets;
+    private readonly buckets;
+    private readonly orderedTargets;
+    private anchor;
+    private focus;
+    private dragging;
+    private orderCursor;
+    /**
+     * Создает экземпляр NovaTextSelectionService и подготавливает базовое состояние.
+     */
+    constructor(options?: Required<NovaTextSelectionOptions>);
+    /**
+     * Выполняет действие configure в рамках ответственности NovaTextSelectionService.
+     */
+    configure(options: NovaTextSelectionOptions | false | undefined): void;
+    /**
+     * Выполняет действие beginFrame в рамках ответственности NovaTextSelectionService.
+     */
+    beginFrame(): void;
+    /**
+     * Регистрирует сущность в runtime-слое NovaTextSelectionService.
+     */
+    register(target: NovaTextSelectionTarget<TContext>): void;
+    /**
+     * Выполняет hit-test для runtime-геометрии NovaTextSelectionService.
+     */
+    hitTest(x: number, y: number): NovaTextSelectionHit<TContext> | null;
+    /**
+     * Запускает runtime-процесс NovaTextSelectionService.
+     */
+    start(x: number, y: number): boolean;
+    /**
+     * Обновляет runtime-состояние NovaTextSelectionService.
+     */
+    update(x: number, y: number): boolean;
+    /**
+     * Выполняет действие end в рамках ответственности NovaTextSelectionService.
+     */
+    end(): void;
+    /**
+     * Очищает накопленное состояние NovaTextSelectionService.
+     */
+    clear(): void;
+    /**
+     * Выполняет действие hasSelection в рамках ответственности NovaTextSelectionService.
+     */
+    hasSelection(): boolean;
+    /**
+     * Возвращает значение состояния NovaTextSelectionService.
+     */
+    getSelectionColor(): string;
+    /**
+     * Возвращает значение состояния NovaTextSelectionService.
+     */
+    getRanges(): Array<NovaTextSelectionRange<TContext>>;
+    /**
+     * Возвращает значение состояния NovaTextSelectionService.
+     */
+    getSelectedText(formatter?: (ranges: Array<NovaTextSelectionRange<TContext>>) => string): string;
+    /**
+     * Выполняет действие copy в рамках ответственности NovaTextSelectionService.
+     */
+    copy(formatter?: (ranges: Array<NovaTextSelectionRange<TContext>>) => string): Promise<NovaClipboardResult>;
+    /**
+     * Возвращает значение состояния NovaTextSelectionService.
+     */
+    getState(formatter?: (ranges: Array<NovaTextSelectionRange<TContext>>) => string): NovaTextSelectionState<TContext>;
+    /**
+     * Выполняет внутренний шаг addToBuckets для NovaTextSelectionService.
+     */
+    private addToBuckets;
+    /**
+     * Выполняет внутренний шаг bucketKey для NovaTextSelectionService.
+     */
+    private bucketKey;
+}
+export declare function resolveNovaTextSelectionOptions(options?: NovaTextSelectionOptions | false): Required<NovaTextSelectionOptions>;

package/dist/model/text-selection/index.d.ts

@@ -0,0 +1,2 @@
+export * from './nova-text-selection.types';
+export * from './NovaTextSelectionService';

package/dist/model/text-selection/nova-text-selection.types.d.ts

@@ -0,0 +1,54 @@
+import { NovaRectLike, NovaTextRange } from '../input/nova-input.types';
+export type NovaTextSelectionMode = 'explicit' | 'all-text';
+export type NovaTextSelectionGranularity = 'text' | 'word' | 'line' | 'block';
+export type NovaTextSelectionClipboardMode = 'plain' | 'rich' | 'contextual';
+export interface NovaTextSelectionOptions {
+    enabled?: boolean;
+    mode?: NovaTextSelectionMode;
+    copy?: boolean;
+    drag?: boolean;
+    doubleClick?: 'word' | 'block';
+    tripleClick?: 'line' | 'paragraph';
+    granularity?: NovaTextSelectionGranularity;
+    clipboard?: NovaTextSelectionClipboardMode;
+    selectionColor?: string;
+}
+export interface NovaTextSelectionTarget<TContext = unknown> {
+    id: string;
+    text: string;
+    rect: NovaRectLike;
+    selectable?: boolean;
+    copyable?: boolean;
+    scope?: string;
+    ownerId?: string;
+    zIndex?: number;
+    order?: number;
+    context?: TContext;
+    copyText?: string;
+}
+export interface NovaTextSelectionResolvedTarget<TContext = unknown> extends NovaTextSelectionTarget<TContext> {
+    selectable: boolean;
+    copyable: boolean;
+    zIndex: number;
+    order: number;
+}
+export interface NovaTextSelectionAnchor {
+    targetId: string;
+    offset: number;
+}
+export interface NovaTextSelectionRange<TContext = unknown> {
+    target: NovaTextSelectionResolvedTarget<TContext>;
+    range: NovaTextRange;
+}
+export interface NovaTextSelectionState<TContext = unknown> {
+    active: boolean;
+    dragging: boolean;
+    anchor: NovaTextSelectionAnchor | null;
+    focus: NovaTextSelectionAnchor | null;
+    ranges: Array<NovaTextSelectionRange<TContext>>;
+    text: string;
+}
+export interface NovaTextSelectionHit<TContext = unknown> {
+    target: NovaTextSelectionResolvedTarget<TContext>;
+    offset: number;
+}

package/dist/model/theme/NovaGlobalThemeRegistry.d.ts

@@ -0,0 +1,57 @@
+import { EventList } from '@endge/utils';
+import { NovaThemeId, NovaThemeTokens } from '../../domain/types/theme.types';
+import { NovaApp } from '../runtime/app/NovaApp';
+export interface NovaGlobalThemeRule {
+    selector?: {
+        parts?: Array<{
+            type?: string;
+            id?: string;
+            classes?: Array<string>;
+        }>;
+        specificity?: number;
+    };
+    declarations?: {
+        customProperties?: Record<string, unknown>;
+    };
+    order?: number;
+}
+export interface NovaGlobalThemeStyleSheet {
+    rules?: Array<NovaGlobalThemeRule>;
+}
+export interface NovaGlobalThemeAsset {
+    themes?: Array<{
+        id: NovaThemeId;
+        title?: string;
+        tokens?: NovaThemeTokens;
+        styleSheet?: NovaGlobalThemeStyleSheet | null;
+    }>;
+}
+export interface NovaThemeSelectorTarget {
+    type: string;
+    id?: string | null;
+    className?: unknown;
+    theme?: NovaThemeId | null;
+}
+/**
+ * Global registry for imported NovaCSS assets and app-wide theme switching.
+ */
+export declare class NovaGlobalThemeRegistry {
+    private readonly assets;
+    private readonly listeners;
+    private readonly apps;
+    private activeTheme;
+    import(asset: NovaGlobalThemeAsset): void;
+    theme(): NovaThemeId | null;
+    theme(id: NovaThemeId): NovaThemeId;
+    attach<E extends EventList>(app: NovaApp<E>, options?: {
+        inheritActive?: boolean;
+    }): () => void;
+    subscribe(listener: () => void): () => void;
+    resolveTokens(target: NovaThemeSelectorTarget): NovaThemeTokens;
+    resetForTests(): void;
+    private registerThemes;
+    private collectThemeDefinitions;
+    private tryUseTheme;
+    private notify;
+}
+export declare const NovaGlobalThemes: NovaGlobalThemeRegistry;

package/dist/model/theme/NovaThemeService.d.ts

@@ -0,0 +1,83 @@
+import { EventList } from '@endge/utils';
+import { NovaThemeCreateOptions, NovaThemeDefinition, NovaThemeId, NovaThemeObserveOptions, NovaThemeSnapshot, NovaThemeTokenName, NovaThemeTokenResolver, NovaThemeTokenValue } from '../../domain/types/theme.types';
+import { NovaApp } from '../runtime/app/NovaApp';
+import { NovaNode } from '../runtime/tree/NovaNode';
+/**
+ * Путь активной темы в shared RaphKernel data-store.
+ */
+export declare const NOVA_THEME_ACTIVE_PATH = "nova.theme.active";
+/**
+ * Путь версии темы в shared RaphKernel data-store.
+ */
+export declare const NOVA_THEME_VERSION_PATH = "nova.theme.version";
+/**
+ * Управляет Nova theme definitions, а активную тему хранит в shared RaphKernel.
+ */
+export declare class NovaThemeService<E extends EventList = Record<string, any>> {
+    private readonly app;
+    private readonly themes;
+    /**
+     * Создает service и регистрирует начальные темы.
+     */
+    constructor(app: NovaApp<E>, options?: NovaThemeCreateOptions);
+    /**
+     * Регистрирует тему в локальном Nova registry.
+     */
+    register(theme: NovaThemeDefinition, options?: {
+        activate?: boolean;
+    }): void;
+    /**
+     * Регистрирует несколько тем.
+     */
+    registerMany(themes: Array<NovaThemeDefinition>, options?: {
+        active?: NovaThemeId;
+    }): void;
+    /**
+     * Делает тему активной и пишет состояние в RaphKernel.
+     */
+    use(id: NovaThemeId): void;
+    /**
+     * Возвращает активный theme id из RaphKernel.
+     */
+    active(): NovaThemeId | null;
+    /**
+     * Возвращает текущую версию темы из RaphKernel.
+     */
+    version(): number;
+    /**
+     * Возвращает активную theme definition.
+     */
+    activeDefinition(): NovaThemeDefinition | null;
+    /**
+     * Возвращает raw token активной темы.
+     */
+    token(name: NovaThemeTokenName): NovaThemeTokenValue | undefined;
+    /**
+     * Резолвит token в строку для renderer и NovaCSS.
+     */
+    resolve(name: string, fallback?: string): string | undefined;
+    /**
+     * Возвращает snapshot активной темы.
+     */
+    snapshot(): NovaThemeSnapshot;
+    /**
+     * Создает resolver, совместимый с Nova UI Kit style engine.
+     */
+    createTokenResolver(): NovaThemeTokenResolver;
+    /**
+     * Подписывает Nova node на смену темы через Raph data observer.
+     */
+    observe(node: NovaNode<E>, options?: NovaThemeObserveOptions): () => void;
+    /**
+     * Возвращает путь версии темы для прямых подписок.
+     */
+    get versionPath(): string;
+    /**
+     * Возвращает путь активной темы для диагностики и интеграций.
+     */
+    get activePath(): string;
+    /**
+     * Поднимает версию темы без смены active id.
+     */
+    private bumpVersion;
+}