@sealpixel/core 1.0.0-rc.0

package/dist/session.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Headless editor session. Owns the edit log (as `History`), the derived
+ * document, and a renderer. Every state change schedules a debounced preview
+ * render on the proxy; stale results are discarded by version.
+ */
+import type { RgbaBuffer } from '@sealpixel/wasm';
+import { type AssetResolver } from './assets.js';
+import { SealpixelError } from './errors.js';
+import type { Geometry } from './plan.js';
+import type { AnyPlugin, AssetDeclaration, Document } from './plugin.js';
+import { type Registry } from './registry.js';
+import type { Renderer } from './renderer.js';
+import type { ExportResult } from './renderer-core.js';
+import type { EditLog, History, Operation, OutputOptions, SourceDescriptor } from './types.js';
+export type LoadSource = Uint8Array | ArrayBuffer | Blob | string;
+export interface LoadOptions {
+    /** Saved state to resume from (an `EditLog` or `{ log, index }`), validated through the registry. */
+    editLog?: unknown;
+    /** History position to resume at. Defaults to the end of the log. */
+    index?: number;
+    /** Source id. Defaults to the File name without extension, or `image`. */
+    id?: string;
+}
+export interface SessionOptions {
+    plugins: readonly AnyPlugin[];
+    /** Defaults to an `InlineRenderer` built from `plugins`. Pass a `WorkerRenderer` in browsers. */
+    renderer?: Renderer;
+    limits?: {
+        maxClientMegapixels?: number;
+        maxClientBytes?: number;
+    };
+    preview?: {
+        debounceMs?: number;
+        enabled?: boolean;
+    };
+    /**
+     * Server rendering: `endpoint` accepts the `@sealpixel/server` contract. Used
+     * by `requestServerRender`, by `download({ via: 'server' })`, and by the
+     * `server` proxy strategy for images above the client limits.
+     */
+    server?: {
+        endpoint: string;
+        fetch?: typeof fetch;
+        headers?: Record<string, string>;
+    };
+    /** How to obtain the preview for images above the client limits. Default `auto`. */
+    proxy?: {
+        maxSide?: number;
+        strategy?: 'auto' | 'wasm' | 'server';
+    };
+    /** Fonts and images referenced by the log. Defaults to the plugins' declarations with relative urls. */
+    assets?: AssetResolver;
+    /**
+     * How `download` hands bytes to the user. Defaults to an `<a download>`
+     * click in browsers; required elsewhere.
+     */
+    saveFile?: (bytes: Uint8Array, filename: string, mimeType: string) => void | Promise<void>;
+}
+export interface PreviewState {
+    image: RgbaBuffer;
+    /** Geometry of the real output, whatever the stage shows. */
+    geometry: Geometry;
+    /**
+     * Geometry of the log the preview image was rendered from. Equals
+     * `geometry` without a preview transform; with one (a tool showing the
+     * uncropped image) it describes the pixels on the stage, so the UI can map
+     * preview pixels back to the source and keep the view steady.
+     */
+    viewGeometry: Geometry;
+    /** Version of the history the preview reflects. */
+    version: number;
+}
+export interface SessionState {
+    status: 'empty' | 'loading' | 'ready' | 'error';
+    source: SourceDescriptor | null;
+    /** Whether full-resolution pixels are held client-side (local export possible). */
+    resident: boolean;
+    history: History;
+    document: Document;
+    /** Increments on every history change. */
+    version: number;
+    preview: PreviewState | null;
+    previewPending: boolean;
+    error: SealpixelError | null;
+}
+export interface ExportOptions {
+    output: OutputOptions;
+    embedEditLog?: boolean;
+    upTo?: number;
+}
+export interface DownloadOptions extends Partial<ExportOptions> {
+    filename?: string;
+    /** `auto` renders locally when the image is resident, otherwise on the server. */
+    via?: 'auto' | 'local' | 'server';
+}
+export interface EditorSession {
+    readonly registry: Registry;
+    load(source: LoadSource, options?: LoadOptions): Promise<SourceDescriptor>;
+    dispatch(op: Operation): void;
+    undo(): void;
+    redo(): void;
+    timeTravel(index: number): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    getState(): SessionState;
+    getEditLog(): {
+        log: EditLog;
+        index: number;
+    };
+    getDocument(): Document;
+    subscribe(listener: (state: SessionState) => void): () => void;
+    /** Forces a preview render now and resolves when it is applied. */
+    renderPreview(): Promise<PreviewState>;
+    /** Resolves when no preview render is pending. */
+    whenIdle(): Promise<void>;
+    /**
+     * Replaces the history with a saved state for the loaded image (controlled
+     * mode). Validates through the registry and checks the source.
+     */
+    setEditLog(saved: unknown, index?: number): void;
+    /**
+     * Transforms the log before preview rendering only. Tools use it to show,
+     * for example, the un-cropped image while the crop gizmo is active.
+     */
+    setPreviewTransform(transform: ((log: EditLog) => EditLog) | null): void;
+    /**
+     * Renders a proxy-sized image from the current log, transformed, and returns
+     * it without touching the stage, the state or the history. Tools use it to
+     * show what an edit the user has not made yet would look like: the filter
+     * tool renders its thumbnails from the log with the filter removed, so a
+     * chosen preset does not end up baked into the alternatives beside it.
+     */
+    renderDetached(transform: (log: EditLog) => EditLog, options?: {
+        signal?: AbortSignal;
+    }): Promise<RgbaBuffer>;
+    /**
+     * Registers an asset the user supplied (for example an uploaded sticker):
+     * stores the bytes in the renderer and records the declaration in the log
+     * so the log stays self-describing. Returns the declaration with its hash.
+     */
+    addAsset(bytes: Uint8Array, options?: {
+        id?: string;
+        url?: string;
+    }): Promise<AssetDeclaration>;
+    export(options: ExportOptions): Promise<ExportResult>;
+    download(options?: DownloadOptions): Promise<{
+        filename: string;
+        result: ExportResult | ServerRenderResult;
+    }>;
+    /**
+     * Renders on the server from the original bytes (inline) or a host-provided
+     * source reference. With `destination: 's3'` the server stores the object and
+     * returns its key and presigned url; otherwise the bytes come back.
+     */
+    requestServerRender(options: ServerRenderOptions): Promise<ServerRenderResult>;
+    dispose(): void;
+}
+export interface ServerRenderOptions extends ExportOptions {
+    /** Defaults to the loaded bytes sent inline. Hosts that uploaded the original pass its reference. */
+    source?: {
+        kind: 's3';
+        bucket?: string;
+        key: string;
+    } | {
+        kind: 'url';
+        url: string;
+    };
+    destination?: 's3' | 'response';
+    endpoint?: string;
+}
+export interface ServerRenderResult {
+    /** Present for `destination: 'response'`. */
+    bytes?: Uint8Array;
+    /** Present for `destination: 's3'`. */
+    url?: string | null;
+    objectKey?: string;
+    bucket?: string;
+    hash: string;
+    width: number;
+    height: number;
+    mimeType: OutputOptions['format'];
+    cached: boolean;
+    jobKey: string;
+}
+export declare function createEditorSession(options: SessionOptions): EditorSession;
+/** Default `saveFile`: an `<a download>` click, with the share sheet as a fallback on iOS Safari. */
+export declare function browserSaveFile(bytes: Uint8Array, filename: string, mimeType: string): Promise<void>;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}