@agrhub/engine-pixi 0.0.0-stage → 1.3.3

package/dist/studio/history-manager.d.ts

@@ -0,0 +1,46 @@
+import { Difference } from 'microdiff';
+import { ClipJSON, ProjectJSON, StudioTrackJSON } from '../json-serialization';
+export interface HistoryOptions {
+    maxSize?: number;
+}
+export interface HistoryState {
+    clips: Record<string, ClipJSON>;
+    tracks: StudioTrackJSON[];
+    settings: any;
+}
+export declare class HistoryManager {
+    private past;
+    private future;
+    private lastState;
+    private maxSize;
+    constructor(options?: HistoryOptions);
+    private projectToHistoryState;
+    /**
+     * Initialize history with the starting state
+     */
+    init(state: ProjectJSON): void;
+    /**
+     * Push a new state to history. Calculates the diff from the last state.
+     */
+    push(newState: ProjectJSON): void;
+    /**
+     * Undo the last action. Returns the patches and the new target state.
+     */
+    undo(currentState: ProjectJSON): {
+        patches: Difference[];
+        state: HistoryState;
+    } | null;
+    /**
+     * Redo the next action. Returns the patches and the new target state.
+     */
+    redo(currentState: ProjectJSON): {
+        patches: Difference[];
+        state: HistoryState;
+    } | null;
+    /**
+     * Apply patches to an object.
+     */
+    private applyPatches;
+    canUndo(): boolean;
+    canRedo(): boolean;
+}

package/dist/studio/resource-manager.d.ts

@@ -0,0 +1,53 @@
+import { file } from 'opfs-tools';
+export declare enum ResourceStatus {
+    PENDING = "pending",
+    LOADING = "loading",
+    COMPLETED = "completed",
+    FAILED = "failed"
+}
+export interface ResourceItem {
+    url: string;
+    status: ResourceStatus;
+    localFile?: ReturnType<typeof file>;
+    error?: Error;
+}
+/**
+ * ResourceManager handles asset preloading and caching in OPFS.
+ * It ensures that resources are downloaded only once and reused across sessions.
+ */
+export declare class ResourceManager {
+    private resources;
+    private loadingPromises;
+    /**
+     * Preload a batch of URLs in parallel.
+     * @param urls Array of URLs to preload
+     */
+    preload(urls: string[]): Promise<void>;
+    /**
+     * Get a ReadableStream for the given URL. Backed by the shared media cache: concurrent and repeated
+     * requests for a URL share one download (memory LRU + OPFS).
+     */
+    static getReadableStream(url: string): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Get an ImageBitmap for the given URL (a new bitmap per call; the bytes are shared and cached).
+     */
+    static getImageBitmap(url: string): Promise<ImageBitmap>;
+    /**
+     * Load a single resource, using cache if available.
+     * @param url URL to load
+     */
+    loadResource(url: string): Promise<ResourceItem>;
+    /**
+     * Resolve a URL to its local OPFS file if available.
+     * @param url URL to resolve
+     */
+    resolve(url: string): Promise<ReturnType<typeof file> | string>;
+    /**
+     * Get the status of a specific resource.
+     */
+    getStatus(url: string): ResourceItem | undefined;
+    /**
+     * Clear instance state (not OPFS cache).
+     */
+    clear(): void;
+}

package/dist/studio/selection-manager.d.ts

@@ -0,0 +1,66 @@
+import { Application, Container, Graphics } from 'pixi.js';
+import { IClip } from '../clips/iclip';
+import { Transformer } from '../transformer/transformer';
+import { Studio } from '../studio';
+export declare class SelectionManager {
+    private studio;
+    selectedClips: Set<IClip>;
+    activeTransformer: Transformer | null;
+    interactiveClips: Set<IClip>;
+    getSelection(): IClip[];
+    selectionGraphics: Graphics | null;
+    isDragSelecting: boolean;
+    private dragSelectionStart;
+    private isUpdatingTextRealtime;
+    private textClipResizedWidth;
+    private textClipResizeHandle;
+    private textClipResizedSx;
+    private textClipResizedSy;
+    private lastPointerDownTime;
+    private lastPointerDownClip;
+    constructor(studio: Studio);
+    init(app: Application, artboard: Container): void;
+    private onStagePointerDown;
+    private onStagePointerMove;
+    private onStagePointerUp;
+    /**
+     * Find clips that intersect with the given selection rectangle
+     */
+    private getIntersectingClips;
+    /**
+     * Update the transformer to show a preview of what will be selected
+     */
+    private updatePreviewSelection;
+    /**
+     * Update root.hitArea to match logical clip dimensions.
+     * Must be called after clip.width/height change (e.g. after text reflow or resize).
+     */
+    refreshClipHitArea(clip: IClip): void;
+    /**
+     * Setup sprite interactivity for click selection
+     */
+    setupSpriteInteractivity(clip: IClip): void;
+    /**
+     * Find the topmost clip (highest zIndex) at a given point
+     */
+    getTopmostClipAtPoint(globalPoint: {
+        x: number;
+        y: number;
+    }): IClip | null;
+    /**
+     * Select a clip and show transform controls
+     */
+    selectClip(clip: IClip, addToSelection?: boolean): void;
+    selectClipsByIds(ids: string[]): void;
+    setSelection(clips: IClip[]): void;
+    deselectClip(): void;
+    move(dx: number, dy: number): Promise<void>;
+    clear(): void;
+    recreateTransformer(): void;
+    private destroyTransformer;
+    private createTransformer;
+    private syncSelectedClipsTransformsRealtime;
+    private syncSelectedClipsTransforms;
+    private syncSpriteToClipProperties;
+    deleteSelected(): Promise<void>;
+}

package/dist/studio/timeline-model.d.ts

@@ -0,0 +1,117 @@
+import { Studio, StudioTrack } from '../studio';
+import { IClip } from '../clips/iclip';
+import { ProjectJSON } from '../json-serialization';
+export declare class TimelineModel {
+    private studio;
+    tracks: StudioTrack[];
+    clips: IClip[];
+    constructor(studio: Studio);
+    getTrackById(trackId: string): StudioTrack | undefined;
+    getClipById(clipId: string): IClip | undefined;
+    findTrackIdByClipId(clipId: string): string | undefined;
+    getTrackIndex(trackId: string): number;
+    /**
+     * Add a new track to the studio
+     */
+    addTrack(track: {
+        name: string;
+        type: string;
+        id?: string;
+    }, index?: number): StudioTrack;
+    /**
+     * Remove a track and all its clips
+     */
+    removeTrack(trackId: string): Promise<void>;
+    /**
+     * Move a track to a new index
+     */
+    moveTrack(trackId: string, newIndex: number): Promise<void>;
+    /**
+     * Set the order of tracks by ID
+     */
+    setTrackOrder(trackIds: string[]): Promise<void>;
+    /**
+     * Add a Transition clip at the join where the selected clip starts.
+     */
+    addTransition(transitionKey: string, duration?: number, fromClipId?: string | null, toClipId?: string | null, id?: string): Promise<void>;
+    /**
+     * Add a clip (or clips) to the studio
+     */
+    addClip(clipOrClips: IClip | IClip[], options?: {
+        trackId?: string;
+        audioSource?: string | File | Blob;
+    } | string | File | Blob): Promise<void>;
+    private normalizeAddClipOptions;
+    private prepareClipForTimeline;
+    private addClipToTrack;
+    private setupClipVisuals;
+    private emitAddClipEvents;
+    removeClip(clip: IClip, options?: {
+        permanent: boolean;
+    }): Promise<void>;
+    /**
+     * Remove multiple clips in a batch
+     */
+    removeClips(clips: IClip[], options?: {
+        permanent: boolean;
+    }): Promise<void>;
+    removeClipById(clipId: string): Promise<void>;
+    updateClip(clipId: string, updates: Partial<IClip>): Promise<void>;
+    updateClips(updates: {
+        id: string;
+        updates: Partial<IClip>;
+    }[]): Promise<void>;
+    /**
+     * Replace all clips with the same source with new clips generated by a factory.
+     * Useful for replacing placeholders with actual assets.
+     */
+    replaceClipsBySource(src: string, newClipFactory: (oldClip: IClip) => Promise<IClip>): Promise<void>;
+    private applyClipUpdate;
+    private updateTransformer;
+    /**
+     * Export current project state to JSON
+     */
+    exportToJSON(): ProjectJSON;
+    /**
+     * Load clips from JSON
+     */
+    loadFromJSON(json: ProjectJSON): Promise<void>;
+    /**
+     * Delete all currently selected clips
+     */
+    deleteSelected(): Promise<void>;
+    /**
+     * Duplicate all currently selected clips
+     */
+    duplicateSelected(): Promise<void>;
+    /**
+     * Split the selected clip at the given time or current time
+     */
+    splitSelected(splitTime?: number): Promise<void>;
+    /**
+     * Trim the selected clip from a specified time
+     * @param trimFromSeconds - Number of seconds to trim from the start of the clip
+     */
+    trimSelected(trimFromSeconds: number): Promise<void>;
+    updateSelected(updates: Partial<IClip>): Promise<void>;
+    setTracks(tracks: StudioTrack[]): Promise<void>;
+    /**
+     * Reconciles the tracks list with the available clips.
+     * 1. Filters each track's clipIds to only include IDs present in this.clips.
+     * 2. Removes any tracks that are then empty.
+     * This is used as a safety net to ensure no orphaned empty tracks or dangling references remain.
+     */
+    reconcileTracks(): void;
+    private ensureFontsForClips;
+    recalculateMaxDuration(): Promise<void>;
+    private setupPlaybackForClip;
+    private isPlaybackCapable;
+    clear(): Promise<void>;
+    /**
+     * Remove a time range from the entire timeline and shift subsequent content left.
+     * This is a ripple delete operation.
+     * @param fromUs Start time in microseconds
+     * @param toUs End time in microseconds
+     */
+    rippleDelete(fromUs: number, toUs: number): Promise<void>;
+}

package/dist/studio/transport.d.ts

@@ -0,0 +1,44 @@
+import { Studio } from '../studio';
+import { IClip, IPlaybackCapable } from '../clips/iclip';
+export interface PlaybackElementInfo {
+    element: HTMLVideoElement | HTMLAudioElement;
+    objectUrl?: string;
+}
+export declare class Transport {
+    private studio;
+    isPlaying: boolean;
+    currentTime: number;
+    maxDuration: number;
+    private playStartTime;
+    private playStartTimestamp;
+    private rafId;
+    playbackElements: Map<IClip<import('../sprite/base-sprite').BaseSpriteEvents>, PlaybackElementInfo>;
+    constructor(studio: Studio);
+    setMaxDuration(duration: number): void;
+    /**
+     * Start playback
+     */
+    play(): Promise<void>;
+    /**
+     * Pause playback
+     */
+    pause(): void;
+    /**
+     * Stop playback and reset to start
+     */
+    stop(): Promise<void>;
+    /**
+     * Seek to a specific time (in microseconds)
+     */
+    seek(time: number): Promise<void>;
+    /**
+     * Move to the next frame
+     */
+    frameNext(): Promise<void>;
+    /**
+     * Move to the previous frame
+     */
+    framePrev(): Promise<void>;
+    private renderLoop;
+    isPlaybackCapable(clip: any): clip is IPlaybackCapable;
+}

package/dist/studio-bridge.d.ts

@@ -0,0 +1,50 @@
+import { Core } from '@agrhub/core';
+import { Studio } from './studio';
+/**
+ * StudioBridge - The "Reconciler" between Core and Studio.
+ * Driven by Core patches, applied strictly in order (see enqueue) so async clip creation from an
+ * older patch can never land after a newer rebuild.
+ */
+export declare class StudioBridge {
+    private core;
+    private studio;
+    constructor(core: Core, studio: Studio);
+    /** Set while applying Core -> Studio changes, so Studio events they cause aren't echoed back */
+    private isSyncing;
+    private disposed;
+    /** Serialises all patch work (each step awaits the previous) */
+    private queue;
+    /** Bumped on full rebuilds: queued granular work from before a rebuild is skipped */
+    private generation;
+    /** A full rebuild is queued but hasn't started (further requests coalesce into it) */
+    private resyncQueued;
+    /** Latest requested seek while one is running (scrubbing: latest wins, nothing is dropped) */
+    private pendingSeek;
+    private seekRunning;
+    private unsubscribers;
+    private init;
+    /** Runs fn unless a sync is already in progress (prevents Core <-> Studio echo loops) */
+    private guarded;
+    private enqueue;
+    /** Full rebuild from Core state; requests made before it starts share that one rebuild */
+    private requestResync;
+    private requestSeek;
+    private syncSelectionToStudio;
+    private onCoreChange;
+    private handlePatches;
+    private getTrackCaptionConfig;
+    private buildClipContext;
+    private handleAddClip;
+    private handleRemoveClip;
+    private handleUpdateClip;
+    private syncInitialState;
+    private findTrackIdForClip;
+    /**
+     * Pre-load a font referenced by a clip's style.fontUrl (or top-level fontUrl).
+     * Must be called before jsonToClip() so document.fonts is populated when
+     * the Text constructor calls refreshText().
+     */
+    private ensureFontForClip;
+    private syncClipProperties;
+    dispose(): void;
+}