@bluepic/embed 0.5.9 → 0.5.11

package/dist/util/imageStates/index.d.ts

@@ -0,0 +1,4 @@
+export { imageStateProbe, imageStateProbeStop, IMAGE_STATE_MESSAGE } from './probe';
+export type { ImageLoadState, ImageStateEntry, ImageStatePoint, ImageStateQuad, ImageStateSnapshot } from './probe';
+export { useImageStates, createImageStateStore } from './useImageStates';
+export type { ImageOverlay } from './useImageStates';

package/dist/util/imageStates/probe.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The sandbox-side image-state watcher.
+ *
+ * Everything else in the editor updates instantly: a binding changes, the
+ * engine recomposes, the pixels are already right. A picture is the exception —
+ * it has to travel the network first — and because an expression can drive
+ * `image.image` off something that *looks* instantaneous (a dropdown), there is
+ * no way to know from the outside whether a data change will land in one frame
+ * or in two seconds.
+ *
+ * `@bluepic/core` answers that on the element itself (`Image.vue`), publishing
+ * `data-bx-image-state` on each rendered image's `<g>`. The DOM is the channel
+ * because a sandboxed frame is all DOM to us: we cannot import from it, and its
+ * engine version is not ours to choose.
+ *
+ * ⚠️ SHIPPED AS SOURCE TEXT, NOT AS A CLOSURE — same rules as
+ * `fieldHints/probe.ts`: `EmbeddedController.evaluate()` does `func.toString()`
+ * and `new Function(...)` inside the frame, so the body runs in a scope where
+ * nothing from this bundle exists. No free variables beyond `document`/`window`,
+ * plain ES, JSON in and JSON out.
+ *
+ * AND NO NAMED INNER FUNCTION OF ANY KIND — a constraint that comes from the
+ * TEST pipeline, not from the shipped one. Vite's production build leaves probe
+ * bodies alone (verified against the built `dist/bluepic-embed.umd.js`), but
+ * `tsx`/esbuild runs with `keepNames`, which rewrites every function with an
+ * inferable name — `function read()`, `var read = function()`, `var read = () =>`,
+ * object methods alike — into `__name(fn, 'read')`, a helper that does not exist
+ * in the frame. A probe written with inner functions therefore cannot be
+ * EXERCISED by the `new Function` round trip that proves self-containment; the
+ * fieldHints probes only pass theirs because the stub returns before reaching
+ * any of their code. Two forms survive `keepNames`, and this probe uses both:
+ * an anonymous callback passed inline (`new MutationObserver(function () {…})`)
+ * and a function assigned to a MEMBER (`w.__bxImageStateRead = function () {…}`).
+ * The cost is a slightly odd shape; the gain is a test that runs the real body.
+ *
+ * Unlike the geometry probe this one INSTALLS: it returns the current snapshot
+ * and then keeps posting to the parent as things change. Polling at the latency
+ * a spinner needs would be a round trip every few frames.
+ */
+export type ImageLoadState = 'loading' | 'ready' | 'error';
+export type ImageStatePoint = {
+    x: number;
+    y: number;
+};
+export type ImageStateQuad = [ImageStatePoint, ImageStatePoint, ImageStatePoint, ImageStatePoint];
+export type ImageStateEntry = {
+    /** Rendered instance id — an iterated element reports `id__0`, `id__1`, … */
+    id: string;
+    state: ImageLoadState;
+    /**
+     * Whether the ENGINE is currently painting its in-flight treatment (the blur)
+     * on this instance — its own timed decision, not the raw `state`.
+     *
+     * The spinner follows this rather than timing the wait itself. While the two
+     * decided independently they disagreed by construction: the blur stopped the
+     * instant `load` fired, the spinner served out its own minimum, and it was
+     * left turning over an unblurred picture for up to 420ms. One clock, one
+     * follower.
+     */
+    busy: boolean;
+    /**
+     * The element's AUTHORED frame in serial coordinates, not the painted
+     * picture: a contain-mode image paints smaller than its frame, and a busy
+     * overlay that shrank to the old picture's letterbox would jump the moment
+     * the new one landed. Absent when the frame has not painted yet — the host
+     * keeps whatever it measured last.
+     */
+    quad?: ImageStateQuad;
+};
+export type ImageStateSnapshot = {
+    /**
+     * `false` means this engine predates `data-bx-image-state`: it renders images
+     * but publishes no state for them. The host then treats every picture as
+     * loaded, which is exactly how the editor behaved before this feature.
+     */
+    supported: boolean;
+    entries: ImageStateEntry[];
+};
+/** What the installed watcher posts to the parent window. */
+export declare const IMAGE_STATE_MESSAGE = "bx:image-states";
+export declare function imageStateProbe(configJson: string): ImageStateSnapshot;
+/** Tears the watcher down. Separate function because probes ship as source. */
+export declare function imageStateProbeStop(): boolean;

package/dist/util/imageStates/useImageStates.d.ts

@@ -0,0 +1,63 @@
+import { type Ref } from 'vue';
+import { type ImageLoadState, type ImageStateEntry, type ImageStateQuad } from './probe';
+export type ImageOverlay = {
+    /** Rendered instance id: `id__0`, `id__1`, … for an iterated element. */
+    id: string;
+    state: ImageLoadState;
+    /** Element frame in SERIAL coordinates. */
+    quad: ImageStateQuad;
+    aabb: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    centroid: {
+        x: number;
+        y: number;
+    };
+};
+type EvaluateFn = (func: Function, ...args: string[]) => Promise<unknown>;
+/**
+ * Snapshots in, "what is covered right now" out, keyed by RENDERED INSTANCE id —
+ * an iterated element contributes one entry per instance, so `logo__2` can be
+ * covered while `logo__0` and `logo__1` stay untouched.
+ *
+ * NO TIMERS LIVE HERE. Deciding when a wait is worth announcing used to be this
+ * file's job, and it was the right place while the host also drew the blur. Once
+ * the blur moved into the engine (only the engine knows an image's clip, radius
+ * and mask) two clocks were deciding one thing: the blur stopped the instant
+ * `load` fired while the spinner served out its own 420ms minimum, so on
+ * medium-speed loads the spinner was left turning over an unblurred picture.
+ * The engine now makes that call once and publishes it; this mirrors it. See
+ * `useInFlightTreatment` in @bluepic/core.
+ */
+export declare function createImageStateStore(): {
+    apply: (list: ImageStateEntry[]) => void;
+    states: import("vue").ComputedRef<Record<string, ImageLoadState>>;
+    busy: import("vue").ComputedRef<boolean>;
+    overlays: import("vue").ComputedRef<ImageOverlay[]>;
+    coveredIds: import("vue").ComputedRef<Set<string>>;
+};
+/**
+ * Live load state for every rendered image in the sandbox.
+ *
+ * The store above is the level; the sandbox pushes the edges. See `probe.ts`
+ * for why this is a DOM watcher installed over `evaluate()` rather than a core
+ * event or a poll.
+ */
+export declare function useImageStates(options: {
+    /** Resolved lazily — the sandbox controller only exists once the iframe mounts. */
+    evaluate: () => EvaluateFn | undefined;
+    /** The frame's own window, so a message from anywhere else can be ignored. */
+    frameWindow: () => Window | null | undefined;
+    ready: Ref<boolean>;
+}): {
+    states: import("vue").ComputedRef<Record<string, ImageLoadState>>;
+    busy: import("vue").ComputedRef<boolean>;
+    overlays: import("vue").ComputedRef<ImageOverlay[]>;
+    coveredIds: import("vue").ComputedRef<Set<string>>;
+    supported: Ref<boolean | undefined, boolean | undefined>;
+    dispose: () => void;
+};
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluepic/embed",
-  "version": "0.5.9",
+  "version": "0.5.11",
   "description": "Bluepic embed sdk",
   "type": "module",
   "sideEffects": false,
@@ -42,7 +42,8 @@
     "test:autocrop": "tsx src/util/autoCrop/solveAutoCrop.test.ts",
     "test:gallery": "tsx src/util/gallery.test.ts",
     "test:fieldhints": "tsx src/util/fieldHints/fieldHints.test.ts",
-    "test:clone": "tsx src/util/cloneDeep.test.ts"
+    "test:clone": "tsx src/util/cloneDeep.test.ts",
+    "test:imagestates": "tsx src/util/imageStates/imageStates.test.ts"
   },
   "peerDependencies": {
     "vue": "^3.5.23"