kritzel-stencil 0.1.92 → 0.1.94

package/dist/cjs/index.cjs.js

@@ -1,6 +1,6 @@
 'use strict';
 
-var workspace_migrations = require('./workspace.migrations-PaftqSjk.js');
+var workspace_migrations = require('./workspace.migrations-BENHTbRC.js');
 var Y = require('yjs');
 var yWebsocket = require('y-websocket');
 require('y-indexeddb');

package/dist/cjs/kritzel-active-users_42.cjs.entry.js

@@ -1,7 +1,7 @@
 'use strict';
 
 var index = require('./index-CFnj_FXt.js');
-var workspace_migrations = require('./workspace.migrations-PaftqSjk.js');
+var workspace_migrations = require('./workspace.migrations-BENHTbRC.js');
 var Y = require('yjs');
 require('y-indexeddb');
 require('y-websocket');
@@ -21767,6 +21767,10 @@ class KritzelObjectMap {
         objectsToUpdate.forEach(object => {
             const existed = this._idMap.has(object.id);
             if (existed) {
+                const previous = this._idMap.get(object.id);
+                if (previous && typeof object.adoptTransientStateFrom === 'function') {
+                    object.adoptTransientStateFrom(previous);
+                }
                 this.quadtree.update(object);
                 this._idMap.set(object.id, object);
                 updatedObjects.push(object);
@@ -21782,6 +21786,10 @@ class KritzelObjectMap {
         selectionGroupsToUpdate.forEach(object => {
             const existed = this._idMap.has(object.id);
             if (existed) {
+                const previous = this._idMap.get(object.id);
+                if (previous && typeof object.adoptTransientStateFrom === 'function') {
+                    object.adoptTransientStateFrom(previous);
+                }
                 this.quadtree.update(object);
                 this._idMap.set(object.id, object);
             }
@@ -23324,12 +23332,24 @@ class KritzelCore {
     }
     /**
      * Initializes the Yjs document for collaborative editing.
-     * Sets up the app state map with the current sync configuration and
-     * initializes the asset storage layer.
+     * Sets up the app state map with the current sync configuration.
+     *
+     * Asset storage is initialized separately via {@link initializeAssetStorage}
+     * so that it can be deferred until the `assetStorageConfig` prop arrives,
+     * mirroring the lazy-init pattern used for sync config.
      */
     async initializeYjs() {
-        await this._assetResolver.init(this._assetStorageConfig);
         await this._appStateMap.initialize(this, this._syncConfig);
+    }
+    /**
+     * Initializes the asset storage layer with the current asset storage
+     * configuration. Safe to call multiple times: subsequent calls are
+     * no-ops because {@link KritzelAssetResolver.init} is idempotent.
+     * To apply a new configuration after initialization, destroy the
+     * resolver first or use {@link KritzelEngine.reinitSync}.
+     */
+    async initializeAssetStorage() {
+        await this._assetResolver.init(this._assetStorageConfig);
         this.warnIfAssetStorageMismatched();
     }
     /**
@@ -25731,11 +25751,18 @@ const KritzelEngine = class {
      * such as `HttpAssetProvider` or `PresignedAssetProvider`.
      */
     assetStorageConfig;
-    onAssetStorageConfigChange(newValue) {
-        // Forward to core so initializeYjs picks up the latest value. The
-        // resolver itself is only initialized once per engine; swapping
-        // providers at runtime requires reinitSync().
+    async onAssetStorageConfigChange(newValue) {
+        this._assetStorageConfigRevision++;
+        // Keep core config in sync immediately so late prop updates are not lost.
         this.core.setAssetStorageConfig(newValue);
+        // If assetStorageConfig arrives after componentDidLoad, initialize the
+        // asset storage layer now. Mirrors the syncConfig watcher: the resolver
+        // is only initialized once, when a non-undefined config first becomes
+        // available. Subsequent changes after initialization require
+        // `reinitSync()`, identical to syncConfig semantics.
+        if (newValue && !this._isAssetStorageInitialized && this._isViewportReady) {
+            await this.initializeAssetStorage();
+        }
     }
     /** The current user for awareness broadcasting (name, id, cursor position). */
     user;
@@ -26849,7 +26876,9 @@ const KritzelEngine = class {
         this.core.store.objects?.clearCursorPosition();
         this.core.store.objects?.destroy();
         this.core.appStateMap.destroy();
+        this.core.assetResolver.destroy();
         this._isYjsInitialized = false;
+        this._isAssetStorageInitialized = false;
         await this.initializeSyncAndWorkspace();
     }
     core;
@@ -26860,12 +26889,14 @@ const KritzelEngine = class {
     _lastHadSelectionGroup = false;
     _isViewportReady = false;
     _isYjsInitialized = false;
+    _isAssetStorageInitialized = false;
     _isResolvingActiveWorkspaceId = false;
     _stateChangeListenersRegistered = false;
     _workspaceInitializationPromise = null;
     _workspaceInitializationTargetKey = null;
     _syncInitPromise = null;
     _syncConfigRevision = 0;
+    _assetStorageConfigRevision = 0;
     _isWorkspaceLoading = false;
     _defaultUndoState = {
         canUndo: false,
@@ -26963,6 +26994,27 @@ const KritzelEngine = class {
             this._syncInitPromise = null;
         }
     }
+    /**
+     * Initializes the asset storage layer with the latest config. Mirrors
+     * the in-flight replay logic of {@link doInitializeSyncAndWorkspace} for
+     * `assetStorageConfig` prop updates that arrive while init is running.
+     */
+    async initializeAssetStorage() {
+        if (this._isAssetStorageInitialized) {
+            return;
+        }
+        const revisionAtStart = this._assetStorageConfigRevision;
+        this.core.setAssetStorageConfig(this.assetStorageConfig);
+        await this.core.initializeAssetStorage();
+        // If assetStorageConfig changed mid-flight, replay once with the latest
+        // value so late prop updates are not lost.
+        if (revisionAtStart !== this._assetStorageConfigRevision) {
+            this.core.assetResolver.destroy();
+            this.core.setAssetStorageConfig(this.assetStorageConfig);
+            await this.core.initializeAssetStorage();
+        }
+        this._isAssetStorageInitialized = true;
+    }
     async doInitializeSyncAndWorkspace() {
         // Capture sync config revision to detect prop updates that happen while
         // initialization is in-flight.
@@ -26983,6 +27035,12 @@ const KritzelEngine = class {
             }
             this._isYjsInitialized = true;
         }
+        // Initialize the asset storage layer if a config has been provided.
+        // When the prop arrives later, the @Watch('assetStorageConfig') handler
+        // will trigger initializeAssetStorage() instead.
+        if (!this._isAssetStorageInitialized && this.assetStorageConfig) {
+            await this.initializeAssetStorage();
+        }
         if (this.activeWorkspaceId) {
             const startupWorkspace = this.core.getWorkspaces().find(ws => ws.id === this.activeWorkspaceId);
             if (startupWorkspace) {
@@ -27187,7 +27245,7 @@ const KritzelEngine = class {
                     opacity: object.markedForRemoval ? '0.5' : object.opacity.toString(),
                     pointerEvents: object.markedForRemoval ? 'none' : 'auto',
                     overflow: 'visible',
-                }, viewBox: object?.viewBox }, (object.hasStartArrow || object.hasEndArrow) && (index.h("defs", null, object.hasStartArrow && (index.h("marker", { id: object.startMarkerId, markerWidth: object.getArrowSize('start'), markerHeight: object.getArrowSize('start'), refX: 0, refY: object.getArrowSize('start') / 2, orient: "auto-start-reverse", markerUnits: "userSpaceOnUse" }, index.h("path", { d: object.getArrowPath(object.arrows?.start?.style), fill: object.getArrowFill('start'), transform: `scale(${object.getArrowSize('start') / 10})` }))), object.hasEndArrow && (index.h("marker", { id: object.endMarkerId, markerWidth: object.getArrowSize('end'), markerHeight: object.getArrowSize('end'), refX: 0, refY: object.getArrowSize('end') / 2, orient: "auto", markerUnits: "userSpaceOnUse" }, index.h("path", { d: object.getArrowPath(object.arrows?.end?.style), fill: object.getArrowFill('end'), transform: `scale(${object.getArrowSize('end') / 10})` }))))), index.h("path", { d: this.core.anchorManager.computeClippedLinePath(object), fill: "none", stroke: "transparent", "stroke-width": Math.max(object?.strokeWidth || 0, 10), "stroke-linecap": "round" }), index.h("path", { d: this.core.anchorManager.computeClippedLinePath(object), fill: "none", stroke: workspace_migrations.KritzelColorHelper.resolveThemeColor(object?.stroke, currentTheme), "stroke-width": object?.strokeWidth, "stroke-linecap": "round", "marker-start": object.hasStartArrow ? `url(#${object.startMarkerId})` : undefined, "marker-end": object.hasEndArrow ? `url(#${object.endMarkerId})` : undefined }))), workspace_migrations.KritzelClassHelper.isInstanceOf(object, 'KritzelImage') && (index.h("img", { ref: el => el && object.mount(el), src: object.resolvedSrc || object.src, style: {
+                }, viewBox: object?.viewBox }, (object.hasStartArrow || object.hasEndArrow) && (index.h("defs", null, object.hasStartArrow && (index.h("marker", { id: object.startMarkerId, markerWidth: object.getArrowSize('start'), markerHeight: object.getArrowSize('start'), refX: 0, refY: object.getArrowSize('start') / 2, orient: "auto-start-reverse", markerUnits: "userSpaceOnUse" }, index.h("path", { d: object.getArrowPath(object.arrows?.start?.style), fill: object.getArrowFill('start'), transform: `scale(${object.getArrowSize('start') / 10})` }))), object.hasEndArrow && (index.h("marker", { id: object.endMarkerId, markerWidth: object.getArrowSize('end'), markerHeight: object.getArrowSize('end'), refX: 0, refY: object.getArrowSize('end') / 2, orient: "auto", markerUnits: "userSpaceOnUse" }, index.h("path", { d: object.getArrowPath(object.arrows?.end?.style), fill: object.getArrowFill('end'), transform: `scale(${object.getArrowSize('end') / 10})` }))))), index.h("path", { d: this.core.anchorManager.computeClippedLinePath(object), fill: "none", stroke: "transparent", "stroke-width": Math.max(object?.strokeWidth || 0, 10), "stroke-linecap": "round" }), index.h("path", { d: this.core.anchorManager.computeClippedLinePath(object), fill: "none", stroke: workspace_migrations.KritzelColorHelper.resolveThemeColor(object?.stroke, currentTheme), "stroke-width": object?.strokeWidth, "stroke-linecap": "round", "marker-start": object.hasStartArrow ? `url(#${object.startMarkerId})` : undefined, "marker-end": object.hasEndArrow ? `url(#${object.endMarkerId})` : undefined }))), workspace_migrations.KritzelClassHelper.isInstanceOf(object, 'KritzelImage') && object.loadState === 'ready' && (index.h("img", { ref: el => el && object.mount(el), src: object.resolvedSrc || object.src, style: {
                     position: 'absolute',
                     left: '0',
                     top: '0',
@@ -27205,7 +27263,31 @@ const KritzelEngine = class {
                     overflow: 'visible',
                     userSelect: 'none',
                     imageRendering: this.core.store.state.isScaling || this.core.store.state.isPanning ? 'pixelated' : 'auto',
-                }, draggable: false, onDragStart: e => e.preventDefault() })), workspace_migrations.KritzelClassHelper.isInstanceOf(object, 'KritzelCustomElement') && (index.h("div", { ref: el => el && object.mount(el), style: {
+                }, draggable: false, onDragStart: e => e.preventDefault() })), workspace_migrations.KritzelClassHelper.isInstanceOf(object, 'KritzelImage') && object.loadState !== 'ready' && (index.h("div", { ref: () => object.ensureLoaded(), style: {
+                    position: 'absolute',
+                    left: '0',
+                    top: '0',
+                    width: object.totalWidth + 'px',
+                    height: object.totalHeight + 'px',
+                    transform: object.rotationDegrees !== 0 ? `rotate(${object.rotationDegrees}deg)` : undefined,
+                    transformOrigin: object.rotationDegrees !== 0 ? `${object.totalWidth / 2}px ${object.totalHeight / 2}px` : undefined,
+                    opacity: object.markedForRemoval ? '0.5' : object.opacity.toString(),
+                    pointerEvents: object.markedForRemoval ? 'none' : 'auto',
+                    backgroundColor: workspace_migrations.KritzelColorHelper.resolveThemeColor({ light: '#e5e7eb', dark: '#2a2a2a' }, currentTheme),
+                    borderColor: object.loadState === 'error'
+                        ? workspace_migrations.KritzelColorHelper.resolveThemeColor({ light: '#9ca3af', dark: '#6b7280' }, currentTheme)
+                        : workspace_migrations.KritzelColorHelper.resolveThemeColor(object.borderColor, currentTheme),
+                    borderWidth: object.loadState === 'error' ? '1px' : object.borderWidth + 'px',
+                    borderStyle: 'solid',
+                    padding: object.padding + 'px',
+                    overflow: 'hidden',
+                    userSelect: 'none',
+                    display: 'flex',
+                    alignItems: 'center',
+                    justifyContent: 'center',
+                } }, index.h("kritzel-icon", { name: object.loadState === 'error' ? 'image-off' : 'image', size: Math.max(16, Math.min(object.totalWidth, object.totalHeight) * 0.3), style: {
+                    color: workspace_migrations.KritzelColorHelper.resolveThemeColor({ light: '#9ca3af', dark: '#6b7280' }, currentTheme),
+                } }))), workspace_migrations.KritzelClassHelper.isInstanceOf(object, 'KritzelCustomElement') && (index.h("div", { ref: el => el && object.mount(el), style: {
                     position: 'absolute',
                     left: '0',
                     top: '0',
@@ -28829,7 +28911,7 @@ const KritzelPortal = class {
  * This file is auto-generated by the version bump scripts.
  * Do not modify manually.
  */
-const KRITZEL_VERSION = '0.1.92';
+const KRITZEL_VERSION = '0.1.94';
 
 const kritzelSettingsCss = () => `:host{display:contents}kritzel-dialog{--kritzel-dialog-body-padding:0;--kritzel-dialog-width-large:800px;--kritzel-dialog-height-large:500px}.footer-button{padding:8px 16px;border-radius:6px;cursor:pointer;font-size:14px}.cancel-button{border:1px solid #ebebeb;background:#fff;color:inherit}.cancel-button:hover{background:#f5f5f5}.settings-content{padding:0}.settings-content h3{margin:0 0 16px 0;font-size:18px;font-weight:600;color:var(--kritzel-settings-content-heading-color, #333333)}.settings-content p{margin:0;font-size:14px;color:var(--kritzel-settings-content-text-color, #666666);line-height:1.5}.settings-group{display:flex;flex-direction:column;gap:24px}.settings-item{display:flex;flex-direction:column;gap:8px}.settings-row{display:flex;align-items:center;justify-content:space-between;gap:16px}.settings-label{font-size:14px;font-weight:600;color:var(--kritzel-settings-label-color, #333333);margin:0 0 4px 0}.settings-description{font-size:12px;color:var(--kritzel-settings-description-color, #888888);margin:0;line-height:1.4}.shortcuts-list{display:flex;flex-direction:column;gap:24px}.shortcuts-category{display:flex;flex-direction:column;gap:8px}.shortcuts-category-title{font-size:14px;font-weight:600;color:var(--kritzel-settings-label-color, #333333);margin:0 0 4px 0}.shortcuts-group{display:flex;flex-direction:column;gap:4px}.shortcut-item{display:flex;justify-content:space-between;align-items:center;padding:6px 8px;border-radius:4px;background:var(--kritzel-settings-shortcut-item-bg, rgba(0, 0, 0, 0.02))}.shortcut-label{font-size:14px;color:var(--kritzel-settings-content-text-color, #666666)}.shortcut-key{font-family:monospace;font-size:12px;padding:2px 8px;border-radius:4px;background:var(--kritzel-settings-shortcut-key-bg, #f0f0f0);color:var(--kritzel-settings-shortcut-key-color, #333333);border:1px solid var(--kritzel-settings-shortcut-key-border, #ddd)}`;
 

package/dist/cjs/{workspace.migrations-PaftqSjk.js → workspace.migrations-BENHTbRC.js}

@@ -608,6 +608,20 @@ class KritzelBaseObject {
         Object.assign(this, object);
         return this;
     }
+    /**
+     * Copies transient (non-persisted) state from a previous local instance
+     * onto this freshly-revived instance. Called when a remote Yjs update
+     * replaces an existing object so that local-only fields (e.g. asset
+     * load state, resolved blob URLs) survive across remote position
+     * updates and don't visually flicker.
+     *
+     * Default implementation is a no-op; subclasses with transient fields
+     * should override.
+     * @param previous - The previous local instance being replaced.
+     */
+    adoptTransientStateFrom(_previous) {
+        // no-op by default
+    }
     /**
      * Type guard to check if this object is of a specific class type.
      * Compares against the __class__ property.
@@ -16241,6 +16255,20 @@ class KritzelImage extends KritzelBaseObject {
      * Not serialized into the Yjs document.
      */
     loadState = 'idle';
+    /**
+     * Maximum number of resolution attempts per page load before the
+     * image is considered permanently failed. Defaults to 3.
+     *
+     * The counter is transient (not persisted to Yjs) and resets every
+     * time a fresh `KritzelImage` instance is constructed, so a full page
+     * reload always grants a fresh budget.
+     */
+    maxLoadAttempts = 3;
+    /**
+     * Number of resolution attempts that have been issued so far for the
+     * current page load. Not serialized into the Yjs document.
+     */
+    loadAttempts = 0;
     /**
      * Creates a new KritzelImage instance.
      * @param config - Optional partial configuration object to initialize image properties
@@ -16260,6 +16288,7 @@ class KritzelImage extends KritzelBaseObject {
         this.height = config?.height || 0;
         this.maxWidth = config?.maxWidth ?? 300;
         this.maxHeight = config?.maxHeight ?? 300;
+        this.maxLoadAttempts = config?.maxLoadAttempts ?? 3;
     }
     /**
      * Factory method to create a new KritzelImage instance with core integration.
@@ -16311,21 +16340,56 @@ class KritzelImage extends KritzelBaseObject {
         // Strip transient, non-persistent rendering state.
         delete plain.resolvedSrc;
         delete plain.loadState;
+        delete plain.loadAttempts;
         return plain;
     }
+    /**
+     * Carries transient asset-loading state (resolved URL, load lifecycle,
+     * retry counters) over from the previous local instance when a remote
+     * Yjs update produces a freshly-revived replacement. Without this,
+     * frequent remote updates (e.g. another user dragging the image)
+     * would reset `loadState` to `'idle'` on every tick and cause the
+     * skeleton to flicker between renders.
+     */
+    adoptTransientStateFrom(previous) {
+        if (!(previous instanceof KritzelImage))
+            return;
+        // Only carry over the resolved URL when the asset reference itself
+        // hasn't changed; otherwise the new asset must be re-resolved.
+        if (previous.assetId === this.assetId) {
+            this.resolvedSrc = previous.resolvedSrc;
+            this.loadState = previous.loadState;
+            this.loadAttempts = previous.loadAttempts;
+        }
+    }
     /**
      * Triggers (idempotent) resolution of the referenced asset. Updates
      * `resolvedSrc` and `loadState` as the resolution progresses and
      * schedules a re-render when the URL is available.
+     *
+     * On failure, retries automatically up to {@link maxLoadAttempts}
+     * times per page load with a short exponential backoff. Once the
+     * budget is exhausted, the image is marked permanently `'error'` for
+     * the remainder of the page load to avoid hammering an unavailable
+     * backend; a full reload (which constructs a fresh instance) grants
+     * a new budget.
      */
     ensureResolved() {
         if (this.loadState === 'loading' || this.loadState === 'ready')
             return;
+        if (this.loadState === 'error')
+            return;
         if (!this.assetId)
             return;
         if (!this._core?.assetResolver)
             return;
+        if (this.loadAttempts >= this.maxLoadAttempts) {
+            this.loadState = 'error';
+            return;
+        }
         this.loadState = 'loading';
+        this.loadAttempts += 1;
+        const attempt = this.loadAttempts;
         this._core.assetResolver
             .resolve(this.assetId)
             .then(url => {
@@ -16334,9 +16398,24 @@ class KritzelImage extends KritzelBaseObject {
             this._core?.rerender();
         })
             .catch(err => {
-            this.loadState = 'error';
-            console.warn(`[KritzelImage] Failed to resolve asset ${this.assetId}:`, err);
-            this._core?.rerender();
+            const attemptsExhausted = this.loadAttempts >= this.maxLoadAttempts;
+            console.warn(`[KritzelImage] Failed to resolve asset ${this.assetId} ` +
+                `(attempt ${attempt}/${this.maxLoadAttempts}):`, err);
+            if (attemptsExhausted) {
+                this.loadState = 'error';
+                this._core?.rerender();
+                return;
+            }
+            // Schedule a retry with a small exponential backoff. Reset to
+            // 'idle' so the next call (or scheduled tick) is allowed to
+            // proceed past the early-return guard.
+            this.loadState = 'idle';
+            const backoffMs = Math.min(2000, 250 * Math.pow(2, attempt - 1));
+            setTimeout(() => {
+                if (this.loadState === 'idle') {
+                    this.ensureResolved();
+                }
+            }, backoffMs);
         });
     }
     /**
@@ -16370,13 +16449,15 @@ class KritzelImage extends KritzelBaseObject {
         });
     }
     /**
-     * Overrides base mount to kick off asset resolution the first time
-     * the image is attached to the DOM. Legacy images persisted with an
-     * inline `src` data URL are opportunistically migrated to the asset
-     * storage layer on first mount.
+     * Kicks off asset resolution (or legacy data-URL migration) without
+     * requiring the `<img>` element to be mounted. Safe to call multiple
+     * times; both underlying paths are idempotent.
+     *
+     * Useful for the renderer's loading-skeleton path, where the actual
+     * `<img>` is not in the DOM yet but the asset bytes still need to
+     * start loading.
      */
-    mount(element) {
-        super.mount(element);
+    ensureLoaded() {
         if (this.assetId && !this.resolvedSrc) {
             this.ensureResolved();
         }
@@ -16384,6 +16465,16 @@ class KritzelImage extends KritzelBaseObject {
             this.migrateLegacyDataUrlIfNeeded();
         }
     }
+    /**
+     * Overrides base mount to kick off asset resolution the first time
+     * the image is attached to the DOM. Legacy images persisted with an
+     * inline `src` data URL are opportunistically migrated to the asset
+     * storage layer on first mount.
+     */
+    mount(element) {
+        super.mount(element);
+        this.ensureLoaded();
+    }
     /**
      * Creates a KritzelImage from a URL, handling image loading and dimension calculation.
      * Loads the image, calculates scaled dimensions respecting maxWidth/maxHeight constraints,
@@ -20260,6 +20351,7 @@ KritzelIconRegistry.registerIcons({
     'shape-ellipse': '<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><ellipse cx="12" cy="12" rx="10" ry="8"/></svg>',
     'shape-triangle': '<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M12 3L22 21H2L12 3Z"/></svg>',
     'image': '<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><rect width="18" height="18" x="3" y="3" rx="2" ry="2"/><circle cx="9" cy="9" r="2"/><path d="m21 15-3.086-3.086a2 2 0 0 0-2.828 0L6 21"/></svg>',
+    'image-off': '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-image-off-icon lucide-image-off"><line x1="2" x2="22" y1="2" y2="22"/><path d="M10.41 10.41a2 2 0 1 1-2.83-2.83"/><line x1="13.5" x2="6" y1="13.5" y2="21"/><line x1="18" x2="21" y1="12" y2="15"/><path d="M3.59 3.59A1.99 1.99 0 0 0 3 5v14a2 2 0 0 0 2 2h14c.55 0 1.052-.22 1.41-.59"/><path d="M21 15V5a2 2 0 0 0-2-2H9"/></svg>',
     'chevron-down': '<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="m6 9 6 6 6-6"/></svg>',
     'chevron-up': '<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="m18 15-6-6-6 6"/></svg>',
     'chevron-left': '<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-chevron-left-icon lucide-chevron-left"><path d="m15 18-6-6 6-6"/></svg>',

package/dist/collection/classes/core/core.class.js

@@ -168,12 +168,24 @@ export class KritzelCore {
     }
     /**
      * Initializes the Yjs document for collaborative editing.
-     * Sets up the app state map with the current sync configuration and
-     * initializes the asset storage layer.
+     * Sets up the app state map with the current sync configuration.
+     *
+     * Asset storage is initialized separately via {@link initializeAssetStorage}
+     * so that it can be deferred until the `assetStorageConfig` prop arrives,
+     * mirroring the lazy-init pattern used for sync config.
      */
     async initializeYjs() {
-        await this._assetResolver.init(this._assetStorageConfig);
         await this._appStateMap.initialize(this, this._syncConfig);
+    }
+    /**
+     * Initializes the asset storage layer with the current asset storage
+     * configuration. Safe to call multiple times: subsequent calls are
+     * no-ops because {@link KritzelAssetResolver.init} is idempotent.
+     * To apply a new configuration after initialization, destroy the
+     * resolver first or use {@link KritzelEngine.reinitSync}.
+     */
+    async initializeAssetStorage() {
+        await this._assetResolver.init(this._assetStorageConfig);
         this.warnIfAssetStorageMismatched();
     }
     /**

package/dist/collection/classes/objects/base-object.class.js

@@ -371,6 +371,20 @@ export class KritzelBaseObject {
         Object.assign(this, object);
         return this;
     }
+    /**
+     * Copies transient (non-persisted) state from a previous local instance
+     * onto this freshly-revived instance. Called when a remote Yjs update
+     * replaces an existing object so that local-only fields (e.g. asset
+     * load state, resolved blob URLs) survive across remote position
+     * updates and don't visually flicker.
+     *
+     * Default implementation is a no-op; subclasses with transient fields
+     * should override.
+     * @param previous - The previous local instance being replaced.
+     */
+    adoptTransientStateFrom(_previous) {
+        // no-op by default
+    }
     /**
      * Type guard to check if this object is of a specific class type.
      * Compares against the __class__ property.

package/dist/collection/classes/objects/image.class.js

@@ -49,6 +49,20 @@ export class KritzelImage extends KritzelBaseObject {
      * Not serialized into the Yjs document.
      */
     loadState = 'idle';
+    /**
+     * Maximum number of resolution attempts per page load before the
+     * image is considered permanently failed. Defaults to 3.
+     *
+     * The counter is transient (not persisted to Yjs) and resets every
+     * time a fresh `KritzelImage` instance is constructed, so a full page
+     * reload always grants a fresh budget.
+     */
+    maxLoadAttempts = 3;
+    /**
+     * Number of resolution attempts that have been issued so far for the
+     * current page load. Not serialized into the Yjs document.
+     */
+    loadAttempts = 0;
     /**
      * Creates a new KritzelImage instance.
      * @param config - Optional partial configuration object to initialize image properties
@@ -68,6 +82,7 @@ export class KritzelImage extends KritzelBaseObject {
         this.height = config?.height || 0;
         this.maxWidth = config?.maxWidth ?? 300;
         this.maxHeight = config?.maxHeight ?? 300;
+        this.maxLoadAttempts = config?.maxLoadAttempts ?? 3;
     }
     /**
      * Factory method to create a new KritzelImage instance with core integration.
@@ -119,21 +134,56 @@ export class KritzelImage extends KritzelBaseObject {
         // Strip transient, non-persistent rendering state.
         delete plain.resolvedSrc;
         delete plain.loadState;
+        delete plain.loadAttempts;
         return plain;
     }
+    /**
+     * Carries transient asset-loading state (resolved URL, load lifecycle,
+     * retry counters) over from the previous local instance when a remote
+     * Yjs update produces a freshly-revived replacement. Without this,
+     * frequent remote updates (e.g. another user dragging the image)
+     * would reset `loadState` to `'idle'` on every tick and cause the
+     * skeleton to flicker between renders.
+     */
+    adoptTransientStateFrom(previous) {
+        if (!(previous instanceof KritzelImage))
+            return;
+        // Only carry over the resolved URL when the asset reference itself
+        // hasn't changed; otherwise the new asset must be re-resolved.
+        if (previous.assetId === this.assetId) {
+            this.resolvedSrc = previous.resolvedSrc;
+            this.loadState = previous.loadState;
+            this.loadAttempts = previous.loadAttempts;
+        }
+    }
     /**
      * Triggers (idempotent) resolution of the referenced asset. Updates
      * `resolvedSrc` and `loadState` as the resolution progresses and
      * schedules a re-render when the URL is available.
+     *
+     * On failure, retries automatically up to {@link maxLoadAttempts}
+     * times per page load with a short exponential backoff. Once the
+     * budget is exhausted, the image is marked permanently `'error'` for
+     * the remainder of the page load to avoid hammering an unavailable
+     * backend; a full reload (which constructs a fresh instance) grants
+     * a new budget.
      */
     ensureResolved() {
         if (this.loadState === 'loading' || this.loadState === 'ready')
             return;
+        if (this.loadState === 'error')
+            return;
         if (!this.assetId)
             return;
         if (!this._core?.assetResolver)
             return;
+        if (this.loadAttempts >= this.maxLoadAttempts) {
+            this.loadState = 'error';
+            return;
+        }
         this.loadState = 'loading';
+        this.loadAttempts += 1;
+        const attempt = this.loadAttempts;
         this._core.assetResolver
             .resolve(this.assetId)
             .then(url => {
@@ -142,9 +192,24 @@ export class KritzelImage extends KritzelBaseObject {
             this._core?.rerender();
         })
             .catch(err => {
-            this.loadState = 'error';
-            console.warn(`[KritzelImage] Failed to resolve asset ${this.assetId}:`, err);
-            this._core?.rerender();
+            const attemptsExhausted = this.loadAttempts >= this.maxLoadAttempts;
+            console.warn(`[KritzelImage] Failed to resolve asset ${this.assetId} ` +
+                `(attempt ${attempt}/${this.maxLoadAttempts}):`, err);
+            if (attemptsExhausted) {
+                this.loadState = 'error';
+                this._core?.rerender();
+                return;
+            }
+            // Schedule a retry with a small exponential backoff. Reset to
+            // 'idle' so the next call (or scheduled tick) is allowed to
+            // proceed past the early-return guard.
+            this.loadState = 'idle';
+            const backoffMs = Math.min(2000, 250 * Math.pow(2, attempt - 1));
+            setTimeout(() => {
+                if (this.loadState === 'idle') {
+                    this.ensureResolved();
+                }
+            }, backoffMs);
         });
     }
     /**
@@ -178,13 +243,15 @@ export class KritzelImage extends KritzelBaseObject {
         });
     }
     /**
-     * Overrides base mount to kick off asset resolution the first time
-     * the image is attached to the DOM. Legacy images persisted with an
-     * inline `src` data URL are opportunistically migrated to the asset
-     * storage layer on first mount.
+     * Kicks off asset resolution (or legacy data-URL migration) without
+     * requiring the `<img>` element to be mounted. Safe to call multiple
+     * times; both underlying paths are idempotent.
+     *
+     * Useful for the renderer's loading-skeleton path, where the actual
+     * `<img>` is not in the DOM yet but the asset bytes still need to
+     * start loading.
      */
-    mount(element) {
-        super.mount(element);
+    ensureLoaded() {
         if (this.assetId && !this.resolvedSrc) {
             this.ensureResolved();
         }
@@ -192,6 +259,16 @@ export class KritzelImage extends KritzelBaseObject {
             this.migrateLegacyDataUrlIfNeeded();
         }
     }
+    /**
+     * Overrides base mount to kick off asset resolution the first time
+     * the image is attached to the DOM. Legacy images persisted with an
+     * inline `src` data URL are opportunistically migrated to the asset
+     * storage layer on first mount.
+     */
+    mount(element) {
+        super.mount(element);
+        this.ensureLoaded();
+    }
     /**
      * Creates a KritzelImage from a URL, handling image loading and dimension calculation.
      * Loads the image, calculates scaled dimensions respecting maxWidth/maxHeight constraints,

package/dist/collection/classes/registries/icon-registry.class.js

@@ -64,6 +64,7 @@ KritzelIconRegistry.registerIcons({
     'shape-ellipse': '<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><ellipse cx="12" cy="12" rx="10" ry="8"/></svg>',
     'shape-triangle': '<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M12 3L22 21H2L12 3Z"/></svg>',
     'image': '<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><rect width="18" height="18" x="3" y="3" rx="2" ry="2"/><circle cx="9" cy="9" r="2"/><path d="m21 15-3.086-3.086a2 2 0 0 0-2.828 0L6 21"/></svg>',
+    'image-off': '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-image-off-icon lucide-image-off"><line x1="2" x2="22" y1="2" y2="22"/><path d="M10.41 10.41a2 2 0 1 1-2.83-2.83"/><line x1="13.5" x2="6" y1="13.5" y2="21"/><line x1="18" x2="21" y1="12" y2="15"/><path d="M3.59 3.59A1.99 1.99 0 0 0 3 5v14a2 2 0 0 0 2 2h14c.55 0 1.052-.22 1.41-.59"/><path d="M21 15V5a2 2 0 0 0-2-2H9"/></svg>',
     'chevron-down': '<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="m6 9 6 6 6-6"/></svg>',
     'chevron-up': '<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="m18 15-6-6-6 6"/></svg>',
     'chevron-left': '<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-chevron-left-icon lucide-chevron-left"><path d="m15 18-6-6 6-6"/></svg>',

package/dist/collection/classes/structures/object-map.structure.js

@@ -438,6 +438,10 @@ export class KritzelObjectMap {
         objectsToUpdate.forEach(object => {
             const existed = this._idMap.has(object.id);
             if (existed) {
+                const previous = this._idMap.get(object.id);
+                if (previous && typeof object.adoptTransientStateFrom === 'function') {
+                    object.adoptTransientStateFrom(previous);
+                }
                 this.quadtree.update(object);
                 this._idMap.set(object.id, object);
                 updatedObjects.push(object);
@@ -453,6 +457,10 @@ export class KritzelObjectMap {
         selectionGroupsToUpdate.forEach(object => {
             const existed = this._idMap.has(object.id);
             if (existed) {
+                const previous = this._idMap.get(object.id);
+                if (previous && typeof object.adoptTransientStateFrom === 'function') {
+                    object.adoptTransientStateFrom(previous);
+                }
                 this.quadtree.update(object);
                 this._idMap.set(object.id, object);
             }