@bluepic/embed 0.4.0-next.138 → 0.4.0-next.142

package/dist/util/fieldHints/geometry.d.ts

@@ -0,0 +1,52 @@
+import type { BluepicField } from '@bluepic/types';
+import type { HintPoint, HintQuad } from './probe';
+/**
+ * Geometry helpers over probe output. Everything here works in SERIAL
+ * coordinates — the overlay maps to screen space via zoompinch's
+ * `composePoint`, so nothing in this file needs to know about pan, zoom or
+ * viewport size.
+ */
+/** Shoelace area. Quads may be rotated or sheared, so no width×height shortcut. */
+export declare function quadArea(quad: HintQuad): number;
+export declare function quadCentroid(quad: HintQuad): HintPoint;
+export declare function quadAABB(quad: HintQuad): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * Which frame a quad belongs to, in the 1-based numbering `field.frameIndex`
+ * already uses (`BxTemplateEditor` reads it as `field.frameIndex || 1` and
+ * derives `frameX = (frameIndex - 1) % frames.x`).
+ *
+ * Decided by the centroid, so an element straddling a frame boundary lands in
+ * the frame it mostly occupies rather than being duplicated or dropped.
+ */
+export declare function frameIndexOfPoint(point: HintPoint, serialWidth: number, serialHeight: number, frames: {
+    x: number;
+    y: number;
+} | undefined): number;
+/**
+ * Stacking class for overlap resolution — lower sits ON TOP.
+ *
+ * Hitboxes overlap constantly (a logo inside a full-bleed background image), so
+ * the pointer has to go somewhere defensible. Content-bearing fields win over
+ * pickers, which win over the tweak-a-value controls.
+ */
+export declare function hintPriorityClass(fieldType: BluepicField['type']): number;
+export type OrderableHitbox = {
+    fieldType: BluepicField['type'];
+    area: number;
+    /** Position of the element in the serial's depth-first order; later paints later. */
+    elementOrder: number;
+};
+/**
+ * Sorts hitboxes back-to-front, so the caller can render in array order and let
+ * DOM order do the stacking. The LAST entry is the topmost / most reachable.
+ *
+ * Smaller area on top is what keeps a logo sitting inside a full-bleed image
+ * clickable — without it the background would swallow every pointer event
+ * inside its own bounds.
+ */
+export declare function orderHitboxes<T extends OrderableHitbox>(hitboxes: T[]): T[];

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

@@ -0,0 +1,8 @@
+export { fieldHitboxProbe } from './probe';
+export type { HintPoint, HintQuad, ElementQuad, HitboxProbeResult } from './probe';
+export { collectSerialElements, expandBindingClosure, fieldBindings, referencesIdentifier, resolveFieldElements, scoreElement, CANDIDATE_SCORE_RATIO, } from './resolve';
+export type { FieldElementMatch } from './resolve';
+export { frameIndexOfPoint, hintPriorityClass, orderHitboxes, quadAABB, quadArea, quadCentroid } from './geometry';
+export type { OrderableHitbox } from './geometry';
+export { useFieldHitboxes } from './useFieldHitboxes';
+export type { FieldHitbox } from './useFieldHitboxes';

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

@@ -0,0 +1,73 @@
+/**
+ * The sandbox-side geometry probe.
+ *
+ * Field hints need to know where each element ACTUALLY landed on the canvas —
+ * after every ancestor transform, layout-group flow shift, mask clip and text
+ * auto-fit. That composition already happened once, inside the sandbox iframe,
+ * and the browser is holding the result. So rather than re-deriving it in the
+ * parent (which would mean linking `@bluepic/core` into this package and
+ * pinning ONE engine version against sandboxes that deliberately freeze one
+ * engine per template), we ask the frame that drew the pixels.
+ *
+ * `getBBox()` gives an element's local geometry; `getScreenCTM()` gives its
+ * full transform chain — CSS `transform` included, which is how core applies
+ * per-element matrices. Composing the element's screen CTM with the INVERSE of
+ * the root SVG's screen CTM cancels out viewport sizing and `preserveAspectRatio`
+ * letterboxing, leaving a matrix straight into viewBox units — i.e. serial
+ * coordinates. Verified against a live sandbox (0.2.65) to 0.0000px for an
+ * identity rect, a 23°-rotated text element, a rotate+scale group, and a rect
+ * nested inside that group.
+ *
+ * Nothing here needs a core release or a sandbox redeploy: it travels as source
+ * text through the existing `EmbeddedController.evaluate()` channel.
+ */
+export type HintPoint = {
+    x: number;
+    y: number;
+};
+/** Element corners in serial coordinates, clockwise from the local top-left. */
+export type HintQuad = [HintPoint, HintPoint, HintPoint, HintPoint];
+export type ElementQuad = {
+    /**
+     * The rendered instance's unique id (`data-id`). An element with an
+     * `iteration` renders once per item, so one serial element can yield several
+     * of these — `id__0`, `id__1`, … — all sharing one `data-orginal-id`.
+     */
+    dataId: string;
+    quad: HintQuad;
+};
+export type HitboxProbeResult = {
+    supported: false;
+    /**
+     * `no-root` — no `.serial-wrapper > svg` yet (not mounted, or a sandbox
+     * that structures its DOM differently).
+     * `no-element-identity` — rendered, but the engine predates per-element
+     * `data-id` attributes (roughly < core 0.1.400). Nothing to anchor to;
+     * hints stay off for this template forever, by design.
+     * `no-ctm` — the root SVG has no screen CTM (whole subtree hidden).
+     */
+    reason: 'no-root' | 'no-element-identity' | 'no-ctm';
+} | {
+    supported: true;
+    quads: {
+        [originalId: string]: ElementQuad[];
+    };
+};
+/**
+ * ⚠️ THIS FUNCTION IS SHIPPED AS SOURCE TEXT, NOT AS A CLOSURE.
+ *
+ * `EmbeddedController.evaluate()` does `func.toString()` here and `new Function(...)`
+ * inside the iframe, so the body executes in a scope where NOTHING from this
+ * bundle exists. Any reference to an import, a module-scope const, or a helper
+ * defined outside these braces typechecks, builds green, and then throws
+ * `ReferenceError` in the sandbox under a minified name that won't resemble the
+ * original.
+ *
+ * Rules, all enforced by `probe.test.ts`:
+ *   - one self-contained function; no free variables beyond `document`
+ *   - plain ES (`var`, `function`, no optional chaining) so no transpiler
+ *     helper can be hoisted out of the body
+ *   - arguments in as a JSON string, return value JSON-serialisable — flatten
+ *     every `DOMMatrix`/`DOMRect` before returning
+ */
+export declare function fieldHitboxProbe(originalIdsJson: string): HitboxProbeResult;

package/dist/util/fieldHints/resolve.d.ts

@@ -0,0 +1,55 @@
+import type { BluepicField, Template } from '@bluepic/types';
+/**
+ * Candidates scoring below this share of the winner are dropped. Keeps the
+ * legitimate multi-element cases — a headline plus the background bar bound to
+ * it, or one binding echoed across two frames — while cutting the long tail of
+ * weak style/visibility couplings that would otherwise blanket the canvas.
+ */
+export declare const CANDIDATE_SCORE_RATIO = 0.6;
+export type FieldElementMatch = {
+    /** Serial element id — matches the rendered `data-orginal-id`. */
+    elementId: string;
+    element: Template.Element;
+    score: number;
+    /** Property keys that produced the match, for debugging a surprising hitbox. */
+    matchedProperties: string[];
+};
+/** Depth-first walk over the serial tree, descending into group/mask slots. */
+export declare function collectSerialElements(elements: Template.Element[]): Generator<Template.Element>;
+/**
+ * Does `expression` reference `name` as a standalone identifier?
+ *
+ * Hand-rolled rather than a regex with a lookbehind: `(?<!…)` still throws at
+ * compile time on Safari below 16.4, and a template that renders fine
+ * everywhere else must not blank its hints on an older iPad. A preceding `.`
+ * is excluded so `other.headline` doesn't match `headline`.
+ */
+export declare function referencesIdentifier(expression: string, name: string): boolean;
+/**
+ * Every binding that carries this field's value, mapped to how many
+ * `computedBindings` hops away it is. A field may write `headline`, while the
+ * element actually reads `headlineUpper = UPPER(headline)`.
+ *
+ * Iterated to a fixpoint and guarded on improvement only, so a cyclic
+ * computed-binding definition terminates instead of spinning.
+ */
+export declare function expandBindingClosure(computedBindings: {
+    [k: string]: string;
+} | undefined, roots: string[]): Map<string, number>;
+/** The bindings a field writes. Group/Instruction fields have none. */
+export declare function fieldBindings(field: BluepicField): string[];
+/**
+ * Score one element against one field. Returns `null` when nothing matched.
+ * The score is the STRONGEST single property match, not a sum — an element
+ * whose text is bound to the field shouldn't outrank a sibling merely by also
+ * borrowing the same value for its opacity.
+ */
+export declare function scoreElement(field: BluepicField, element: Template.Element, hopsByBinding: Map<string, number>): {
+    score: number;
+    matchedProperties: string[];
+} | null;
+/**
+ * The elements a field drives, best first, already cut to the candidates worth
+ * drawing a hitbox for.
+ */
+export declare function resolveFieldElements(serial: Template.Serial, field: BluepicField): FieldElementMatch[];