@kritzel/engine 0.4.31

package/dist/collection/classes/providers/assets/indexeddb-asset-provider.class.js

@@ -0,0 +1,241 @@
+/** Default database name used by IndexedDBAssetProvider. */
+const DEFAULT_DB_NAME = 'kritzel-assets';
+/** Object store holding the binary payloads. */
+const BLOB_STORE = 'blobs';
+/** Object store holding the asset metadata. */
+const META_STORE = 'metadata';
+/** Database schema version. Increment when changing store layout. */
+const DB_VERSION = 1;
+/**
+ * Local-only asset storage provider backed by IndexedDB.
+ *
+ * Stores asset blobs and metadata in a dedicated database (separate from
+ * the Yjs IndexedDB sync provider). Resolved URLs are `blob:` object URLs
+ * created on demand and cached to avoid redundant allocations.
+ *
+ * This provider is always-safe to include in an asset storage config; it
+ * doubles as an offline cache when combined with a remote provider.
+ */
+export class IndexedDBAssetProvider {
+    type = 'local';
+    name = 'IndexedDBAssetProvider';
+    _dbName;
+    _db = null;
+    /** In-memory cache of id -> object URL to avoid re-creating blob URLs. */
+    _urlCache = new Map();
+    /** In-memory known-present ids to let `canResolve` answer synchronously. */
+    _knownIds = new Set();
+    constructor(options) {
+        this._dbName = options?.dbName ?? DEFAULT_DB_NAME;
+    }
+    /**
+     * Factory helper enabling use as `IndexedDBAssetProvider.with({ dbName: '...' })`
+     * inside a `KritzelAssetStorageConfig.providers` array.
+     */
+    static with(options) {
+        return { create: () => new IndexedDBAssetProvider(options) };
+    }
+    async init() {
+        if (this._db)
+            return;
+        this._db = await this.openDatabase();
+        // Warm up the known-ids cache so canResolve can answer synchronously.
+        await this.loadKnownIds();
+    }
+    destroy() {
+        for (const url of this._urlCache.values()) {
+            try {
+                URL.revokeObjectURL(url);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        this._urlCache.clear();
+        this._knownIds.clear();
+        if (this._db) {
+            this._db.close();
+            this._db = null;
+        }
+    }
+    canResolve(id) {
+        return this._knownIds.has(id);
+    }
+    async put(blob, metadata) {
+        const db = await this.ensureDb();
+        const id = metadata.id ?? this.generateUuid();
+        const asset = {
+            id,
+            kind: metadata.kind ?? 'file',
+            mimeType: metadata.mimeType,
+            size: blob.size,
+            createdAt: Date.now(),
+            width: metadata.width,
+            height: metadata.height,
+            durationMs: metadata.durationMs,
+            originalFilename: metadata.originalFilename,
+        };
+        await new Promise((resolve, reject) => {
+            const tx = db.transaction([BLOB_STORE, META_STORE], 'readwrite');
+            tx.oncomplete = () => resolve();
+            tx.onerror = () => reject(tx.error);
+            tx.onabort = () => reject(tx.error);
+            tx.objectStore(BLOB_STORE).put(blob, id);
+            tx.objectStore(META_STORE).put(asset, id);
+        });
+        this._knownIds.add(id);
+        return asset;
+    }
+    async resolve(id) {
+        const cached = this._urlCache.get(id);
+        if (cached)
+            return cached;
+        const blob = await this.fetch(id);
+        const url = URL.createObjectURL(blob);
+        this._urlCache.set(id, url);
+        return url;
+    }
+    async fetch(id) {
+        const db = await this.ensureDb();
+        const blob = await new Promise((resolve, reject) => {
+            const tx = db.transaction(BLOB_STORE, 'readonly');
+            const req = tx.objectStore(BLOB_STORE).get(id);
+            req.onsuccess = () => resolve(req.result);
+            req.onerror = () => reject(req.error);
+        });
+        if (!blob) {
+            throw new Error(`[IndexedDBAssetProvider] Asset ${id} not found`);
+        }
+        this._knownIds.add(id);
+        return blob;
+    }
+    async delete(id) {
+        const db = await this.ensureDb();
+        await new Promise((resolve, reject) => {
+            const tx = db.transaction([BLOB_STORE, META_STORE], 'readwrite');
+            tx.oncomplete = () => resolve();
+            tx.onerror = () => reject(tx.error);
+            tx.objectStore(BLOB_STORE).delete(id);
+            tx.objectStore(META_STORE).delete(id);
+        });
+        const url = this._urlCache.get(id);
+        if (url) {
+            try {
+                URL.revokeObjectURL(url);
+            }
+            catch {
+                /* ignore */
+            }
+            this._urlCache.delete(id);
+        }
+        this._knownIds.delete(id);
+    }
+    /**
+     * Returns the metadata record for a stored asset, or `undefined` when
+     * the asset is not present locally.
+     */
+    async getMetadata(id) {
+        const db = await this.ensureDb();
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(META_STORE, 'readonly');
+            const req = tx.objectStore(META_STORE).get(id);
+            req.onsuccess = () => resolve(req.result);
+            req.onerror = () => reject(req.error);
+        });
+    }
+    /**
+     * Returns every stored asset that still has one or more remote
+     * providers marked as pending. Used by the resolver on init to
+     * re-enqueue uploads that were interrupted (e.g. the user reloaded
+     * the tab while a background upload was retrying).
+     */
+    async listAssetsWithPendingRemotes() {
+        const db = await this.ensureDb();
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(META_STORE, 'readonly');
+            const req = tx.objectStore(META_STORE).getAll();
+            req.onsuccess = () => {
+                const all = req.result ?? [];
+                resolve(all.filter(a => Array.isArray(a.pendingRemotes) && a.pendingRemotes.length > 0));
+            };
+            req.onerror = () => reject(req.error);
+        });
+    }
+    /**
+     * Replaces the `pendingRemotes` list on an asset's metadata record.
+     * Passing an empty array clears the pending flag entirely.
+     */
+    async setPendingRemotes(id, providerNames) {
+        const db = await this.ensureDb();
+        await new Promise((resolve, reject) => {
+            const tx = db.transaction(META_STORE, 'readwrite');
+            tx.oncomplete = () => resolve();
+            tx.onerror = () => reject(tx.error);
+            const store = tx.objectStore(META_STORE);
+            const req = store.get(id);
+            req.onsuccess = () => {
+                const existing = req.result;
+                if (!existing)
+                    return; // Asset gone; nothing to update.
+                const updated = { ...existing };
+                if (providerNames.length > 0) {
+                    updated.pendingRemotes = providerNames;
+                }
+                else {
+                    delete updated.pendingRemotes;
+                }
+                store.put(updated, id);
+            };
+        });
+    }
+    async ensureDb() {
+        if (!this._db) {
+            await this.init();
+        }
+        return this._db;
+    }
+    openDatabase() {
+        return new Promise((resolve, reject) => {
+            const req = indexedDB.open(this._dbName, DB_VERSION);
+            req.onupgradeneeded = () => {
+                const db = req.result;
+                if (!db.objectStoreNames.contains(BLOB_STORE)) {
+                    db.createObjectStore(BLOB_STORE);
+                }
+                if (!db.objectStoreNames.contains(META_STORE)) {
+                    db.createObjectStore(META_STORE);
+                }
+            };
+            req.onsuccess = () => resolve(req.result);
+            req.onerror = () => reject(req.error);
+        });
+    }
+    async loadKnownIds() {
+        const db = this._db;
+        if (!db)
+            return;
+        await new Promise((resolve, reject) => {
+            const tx = db.transaction(META_STORE, 'readonly');
+            const req = tx.objectStore(META_STORE).getAllKeys();
+            req.onsuccess = () => {
+                for (const key of req.result) {
+                    if (typeof key === 'string')
+                        this._knownIds.add(key);
+                }
+                resolve();
+            };
+            req.onerror = () => reject(req.error);
+        });
+    }
+    generateUuid() {
+        if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+            return crypto.randomUUID();
+        }
+        // Fallback for environments without crypto.randomUUID (e.g. older jsdom).
+        const bytes = crypto.getRandomValues(new Uint8Array(16));
+        bytes[6] = (bytes[6] & 0x0f) | 0x40;
+        bytes[8] = (bytes[8] & 0x3f) | 0x80;
+        const hex = Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
+        return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+    }
+}

package/dist/collection/classes/providers/assets/presigned-asset-provider.class.js

@@ -0,0 +1,86 @@
+/**
+ * Remote asset storage provider for pre-signed URL uploads (S3, GCS, ...).
+ *
+ * All auth and URL signing is performed by the host application via the
+ * callbacks in {@link PresignedAssetProviderOptions}. The library simply
+ * PUTs/POSTs bytes to the provided URL.
+ */
+export class PresignedAssetProvider {
+    type = 'remote';
+    name = 'PresignedAssetProvider';
+    _options;
+    constructor(options) {
+        this._options = options;
+    }
+    static with(options) {
+        return { create: () => new PresignedAssetProvider(options) };
+    }
+    async init() {
+        if (!this._options.quiet) {
+            console.info('PresignedAssetProvider initialized');
+        }
+    }
+    destroy() {
+        // No-op.
+    }
+    canResolve(_id) {
+        return true;
+    }
+    async put(blob, metadata) {
+        const descriptor = await this._options.getUploadDescriptor(metadata);
+        const method = descriptor.method ?? 'PUT';
+        const headers = { ...(descriptor.headers ?? {}) };
+        if (!headers['Content-Type'] && !headers['content-type']) {
+            headers['Content-Type'] = metadata.mimeType;
+        }
+        let body;
+        if (method === 'POST' && descriptor.fields) {
+            const form = new FormData();
+            for (const [key, value] of Object.entries(descriptor.fields)) {
+                form.append(key, value);
+            }
+            form.append('file', blob);
+            body = form;
+            // Browser sets multipart boundary; avoid forcing content-type.
+            delete headers['Content-Type'];
+            delete headers['content-type'];
+        }
+        else {
+            body = blob;
+        }
+        const res = await fetch(descriptor.url, { method, headers, body });
+        if (!res.ok) {
+            throw new Error(`[PresignedAssetProvider] Upload failed: ${res.status} ${res.statusText}`);
+        }
+        return {
+            id: descriptor.id,
+            kind: metadata.kind ?? 'file',
+            mimeType: metadata.mimeType,
+            size: blob.size,
+            createdAt: Date.now(),
+            width: metadata.width,
+            height: metadata.height,
+            durationMs: metadata.durationMs,
+            originalFilename: metadata.originalFilename,
+        };
+    }
+    async resolve(id) {
+        return this._options.getDownloadUrl(id);
+    }
+    async fetch(id) {
+        const url = await this._options.getDownloadUrl(id);
+        const res = await fetch(url);
+        if (!res.ok) {
+            throw new Error(`[PresignedAssetProvider] Failed to fetch asset ${id}: ${res.status} ${res.statusText}`);
+        }
+        return res.blob();
+    }
+    async delete(id) {
+        if (!this._options.deleteAsset)
+            return;
+        await this._options.deleteAsset(id);
+        if (!this._options.quiet) {
+            console.info(`PresignedAssetProvider: deleted asset ${id}`);
+        }
+    }
+}

package/dist/collection/classes/providers/paste-intent/event-paste-intent.provider.js

@@ -0,0 +1,48 @@
+import { CLIPBOARD_PAYLOAD_PREFIX } from "../../managers/clipboard.types";
+export class KritzelEventPasteIntentProvider {
+    canHandle(context) {
+        return !!context.event?.clipboardData;
+    }
+    async getPasteIntent(context) {
+        const data = context.event?.clipboardData;
+        if (!data) {
+            return { type: 'unknown' };
+        }
+        const imageFiles = Array.from(data.files ?? []).filter(file => file.type.startsWith('image/'));
+        if (imageFiles.length > 0) {
+            return { type: 'image_files', files: imageFiles };
+        }
+        if (data.types.includes('text/plain')) {
+            const textIntent = this.determineTextPasteIntent(data.getData('text/plain'));
+            if (textIntent) {
+                return textIntent;
+            }
+        }
+        return { type: 'unknown' };
+    }
+    parseClipboardPayload(text) {
+        if (!text || !text.startsWith(CLIPBOARD_PAYLOAD_PREFIX)) {
+            return null;
+        }
+        try {
+            const parsed = JSON.parse(text.slice(CLIPBOARD_PAYLOAD_PREFIX.length));
+            if (parsed?.version !== 1 || !Array.isArray(parsed.objects)) {
+                return null;
+            }
+            return parsed;
+        }
+        catch {
+            return null;
+        }
+    }
+    determineTextPasteIntent(text) {
+        const payload = this.parseClipboardPayload(text);
+        if (payload) {
+            return { type: 'kritzel_objects', payload };
+        }
+        if (text && text.trim().length > 0) {
+            return { type: 'plain_text', text };
+        }
+        return null;
+    }
+}

package/dist/collection/classes/providers/paste-intent/ios-paste-intent.provider.js

@@ -0,0 +1,16 @@
+import { KritzelDevicesHelper } from "../../../helpers/devices.helper";
+export class KritzelIosPasteIntentProvider {
+    canHandle(context) {
+        return !context.event?.clipboardData && KritzelDevicesHelper.isIOS();
+    }
+    async getPasteIntent(context) {
+        // On iOS Safari, eventless programmatic clipboard reads are commonly unavailable
+        // (e.g. the context-menu paste calls engine.paste() without a native ClipboardEvent).
+        // Fall back to the in-memory session buffer so internal object copy/paste still works.
+        const payload = context.core.clipboardManager.sessionClipboardPayload;
+        if (payload) {
+            return { type: 'kritzel_objects', payload };
+        }
+        return { type: 'unknown' };
+    }
+}

package/dist/collection/classes/providers/paste-intent/navigator-paste-intent.provider.js

@@ -0,0 +1,86 @@
+import { CLIPBOARD_PAYLOAD_PREFIX } from "../../managers/clipboard.types";
+export class KritzelNavigatorPasteIntentProvider {
+    canHandle(context) {
+        return !context.event?.clipboardData && typeof navigator !== 'undefined' && !!navigator.clipboard;
+    }
+    async getPasteIntent(context) {
+        if (typeof navigator === 'undefined' || !navigator.clipboard) {
+            return { type: 'unknown' };
+        }
+        const { clipboard } = navigator;
+        const permissionState = await context.core.permissionManager.checkPermission('clipboard-read');
+        if (permissionState !== 'granted') {
+            const requestedState = await context.core.permissionManager.requestPermission('clipboard-read');
+            if (requestedState !== 'granted') {
+                return { type: 'unknown' };
+            }
+        }
+        if (clipboard.read) {
+            try {
+                const items = await clipboard.read();
+                const { imageFiles, text } = await this.processClipboardItems(items);
+                if (imageFiles.length > 0) {
+                    return { type: 'image_files', files: imageFiles };
+                }
+                if (text !== null) {
+                    const textIntent = this.determineTextPasteIntent(text);
+                    if (textIntent) {
+                        return textIntent;
+                    }
+                }
+            }
+            catch {
+                // Fall back to readText below when read() is denied or unavailable at runtime.
+            }
+        }
+        if (clipboard.readText) {
+            const textIntent = this.determineTextPasteIntent(await clipboard.readText());
+            if (textIntent) {
+                return textIntent;
+            }
+        }
+        return { type: 'unknown' };
+    }
+    async processClipboardItems(items) {
+        const imageFiles = [];
+        let text = null;
+        await Promise.all(items.map(async (item) => {
+            const imageType = item.types.find(type => type.startsWith('image/'));
+            if (imageType) {
+                const blob = await item.getType(imageType);
+                imageFiles.push(new File([blob], 'pasted-image', { type: imageType }));
+                return;
+            }
+            if (text === null && item.types.includes('text/plain')) {
+                const blob = await item.getType('text/plain');
+                text = await blob.text();
+            }
+        }));
+        return { imageFiles, text };
+    }
+    parseClipboardPayload(text) {
+        if (!text || !text.startsWith(CLIPBOARD_PAYLOAD_PREFIX)) {
+            return null;
+        }
+        try {
+            const parsed = JSON.parse(text.slice(CLIPBOARD_PAYLOAD_PREFIX.length));
+            if (parsed?.version !== 1 || !Array.isArray(parsed.objects)) {
+                return null;
+            }
+            return parsed;
+        }
+        catch {
+            return null;
+        }
+    }
+    determineTextPasteIntent(text) {
+        const payload = this.parseClipboardPayload(text);
+        if (payload) {
+            return { type: 'kritzel_objects', payload };
+        }
+        if (text && text.trim().length > 0) {
+            return { type: 'plain_text', text };
+        }
+        return null;
+    }
+}

package/dist/collection/classes/providers/sync/broadcast-sync-provider.class.js

@@ -0,0 +1,100 @@
+import * as Y from "yjs";
+import * as encoding from "lib0/encoding";
+import * as decoding from "lib0/decoding";
+/**
+ * BroadcastChannel sync provider for cross-tab synchronization
+ * This is a lightweight alternative to y-webrtc for browser-tab-only sync
+ */
+export class BroadcastSyncProvider {
+    static type = 'local';
+    type = 'local';
+    doc;
+    channel;
+    _synced = false;
+    constructor(docName, doc, _options) {
+        this.doc = doc;
+        this.channel = new BroadcastChannel(docName);
+        // Handle incoming messages from other tabs
+        this.channel.onmessage = (event) => {
+            this.handleMessage(event.data);
+        };
+        // Listen to document updates and broadcast them
+        this.doc.on('update', this.handleDocUpdate);
+        // Send initial sync request
+        this.broadcastSync();
+        // Mark as synced after a short delay (to receive any pending updates)
+        setTimeout(() => {
+            this._synced = true;
+        }, 100);
+        if (!_options?.quiet) {
+            console.info(`BroadcastChannel Provider initialized: ${docName}`);
+        }
+    }
+    handleDocUpdate = (update, origin) => {
+        // Don't broadcast updates that came from other tabs (to prevent loops)
+        if (origin !== this) {
+            const encoder = encoding.createEncoder();
+            encoding.writeVarUint(encoder, 0); // Message type: sync update
+            encoding.writeVarUint8Array(encoder, update);
+            this.channel.postMessage(encoding.toUint8Array(encoder));
+        }
+    };
+    handleMessage(message) {
+        const decoder = decoding.createDecoder(new Uint8Array(message));
+        const messageType = decoding.readVarUint(decoder);
+        switch (messageType) {
+            case 0: // Sync update
+                const update = decoding.readVarUint8Array(decoder);
+                Y.applyUpdate(this.doc, update, this);
+                break;
+            case 1: // Sync request
+                this.broadcastSync();
+                break;
+            case 2: // Sync response
+                const stateVector = decoding.readVarUint8Array(decoder);
+                const updateResponse = Y.encodeStateAsUpdate(this.doc, stateVector);
+                if (updateResponse.length > 0) {
+                    const encoder = encoding.createEncoder();
+                    encoding.writeVarUint(encoder, 0); // Send as regular update
+                    encoding.writeVarUint8Array(encoder, updateResponse);
+                    this.channel.postMessage(encoding.toUint8Array(encoder));
+                }
+                break;
+        }
+    }
+    broadcastSync() {
+        // Broadcast our current state vector to request missing updates
+        const encoder = encoding.createEncoder();
+        encoding.writeVarUint(encoder, 2); // Message type: sync response
+        encoding.writeVarUint8Array(encoder, Y.encodeStateVector(this.doc));
+        this.channel.postMessage(encoding.toUint8Array(encoder));
+    }
+    async connect() {
+        // Wait for initial sync to complete
+        if (this._synced) {
+            return;
+        }
+        return new Promise((resolve) => {
+            const checkSync = () => {
+                if (this._synced) {
+                    resolve();
+                }
+                else {
+                    setTimeout(checkSync, 50);
+                }
+            };
+            checkSync();
+        });
+    }
+    disconnect() {
+        // BroadcastChannel doesn't have explicit disconnect
+    }
+    async reconnect() {
+        this.disconnect();
+        return this.connect();
+    }
+    destroy() {
+        this.doc.off('update', this.handleDocUpdate);
+        this.channel.close();
+    }
+}