@realnation/builder-shared-sdk 2.2.0 → 2.4.0

package/dist/interaction/vue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vue.d.ts","sourceRoot":"","sources":["../../src/interaction/vue.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEtF,wFAAwF;AACxF,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,mBAAmB,GAAG,IAAI,GAAG,SAAS,CAAC;CAClD;AAED,MAAM,WAAW,0BAA0B;IACzC,gFAAgF;IAChF,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IACnD,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACvC,8EAA8E;IAC9E,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;IACrC;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,YAAY,CAAC;CACrB;AAED,MAAM,WAAW,sBAAsB;IACrC;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,KAAK,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAC;IACzG,oFAAoF;IACpF,IAAI,CACF,QAAQ,EAAE,mBAAmB,GAAG,IAAI,GAAG,SAAS,EAChD,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,sBAAsB,GAC/B,MAAM,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC,CAAC;IAC9B;;;;;;OAMG;IACH,IAAI,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,IAAI,CAAC;IACxC,oEAAoE;IACpE,IAAI,IAAI,IAAI,CAAC;IACb,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;CAC3C;AAUD,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,0BAA+B,GAAG,mBAAmB,CAqGjG"}
+{"version":3,"file":"vue.d.ts","sourceRoot":"","sources":["../../src/interaction/vue.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEtF,wFAAwF;AACxF,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,mBAAmB,GAAG,IAAI,GAAG,SAAS,CAAC;CAClD;AAED,MAAM,WAAW,0BAA0B;IACzC,gFAAgF;IAChF,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IACnD,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACvC,8EAA8E;IAC9E,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;IACrC;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,YAAY,CAAC;CACrB;AAED,MAAM,WAAW,sBAAsB;IACrC;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,KAAK,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAC;IACzG,oFAAoF;IACpF,IAAI,CACF,QAAQ,EAAE,mBAAmB,GAAG,IAAI,GAAG,SAAS,EAChD,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,sBAAsB,GAC/B,MAAM,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC,CAAC;IAC9B;;;;;;OAMG;IACH,IAAI,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,IAAI,CAAC;IACxC,oEAAoE;IACpE,IAAI,IAAI,IAAI,CAAC;IACb,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;CAC3C;AAUD,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,0BAA+B,GAAG,mBAAmB,CAyGjG"}

package/dist/interaction/vue.js

@@ -115,7 +115,11 @@ export function useInteractionState(options = {}) {
                     active[key] = false;
                     timers.set(key, setTimer(() => { active[key] = !active[key]; }, interactionPeriodOf(property)));
                 }
-                else {
+                else if (trigger !== 'click') {
+                    // Click is a state the player put the element into on purpose (which
+                    // answer they picked). Navigating to another page and back re-syncs
+                    // the timed triggers, and clearing their choice on the way would be
+                    // a bug. Hover has no such meaning: the pointer really has left.
                     active[key] = false;
                 }
             }

package/dist/souvenir/imageFit.d.ts

@@ -0,0 +1,43 @@
+/**
+ * How an image sits inside its element box, and the content hash that makes a
+ * recompose idempotent.
+ *
+ * Canonical home for both. The runner's output media engine carries the same
+ * three modes (`qik-sense-runner/src/views/components/imageFit.ts`); it should
+ * import from here once it takes the souvenir path, so `fill`/`crop`/`contain`
+ * can never drift between the page the operator sees and the image we produce.
+ */
+export declare const ImageFitMode: {
+    readonly FILL: "fill";
+    readonly CROP: "crop";
+    readonly CONTAIN: "contain";
+};
+export type ImageFitModeValue = (typeof ImageFitMode)[keyof typeof ImageFitMode];
+export interface ImageFitDrawRect {
+    sx: number;
+    sy: number;
+    sw: number;
+    sh: number;
+    dx: number;
+    dy: number;
+    dw: number;
+    dh: number;
+}
+/** Unknown values fall back to `fill`, matching the Builder's default. */
+export declare function normalizeImageFit(value: unknown): ImageFitModeValue;
+/** The same mode expressed as CSS, for anyone rendering the element live. */
+export declare function imageFitObjectFit(value: unknown): 'fill' | 'cover' | 'contain';
+/**
+ * Source and destination rectangles for one `drawImage` call.
+ *
+ * `fill` stretches, `crop` centre-crops the source, `contain` letterboxes
+ * inside the box. Returns null when either side has no area to draw into.
+ */
+export declare function computeImageFitDrawRect(sourceWidth: number, sourceHeight: number, targetX: number, targetY: number, targetWidth: number, targetHeight: number, value: unknown): ImageFitDrawRect | null;
+/**
+ * 128-bit-ish digest of an arbitrary string. Same construction the runner uses
+ * for its composition cache tag, so the two agree on what "the same image"
+ * means.
+ */
+export declare function hashSignature(input: string): string;
+//# sourceMappingURL=imageFit.d.ts.map

package/dist/souvenir/imageFit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"imageFit.d.ts","sourceRoot":"","sources":["../../src/souvenir/imageFit.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,YAAY;;;;CAIf,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAEjF,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,CAGnE;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAI9E;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,OAAO,GACb,gBAAgB,GAAG,IAAI,CAkCzB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAanD"}

package/dist/souvenir/imageFit.js

@@ -0,0 +1,85 @@
+/**
+ * How an image sits inside its element box, and the content hash that makes a
+ * recompose idempotent.
+ *
+ * Canonical home for both. The runner's output media engine carries the same
+ * three modes (`qik-sense-runner/src/views/components/imageFit.ts`); it should
+ * import from here once it takes the souvenir path, so `fill`/`crop`/`contain`
+ * can never drift between the page the operator sees and the image we produce.
+ */
+export const ImageFitMode = {
+    FILL: 'fill',
+    CROP: 'crop',
+    CONTAIN: 'contain',
+};
+/** Unknown values fall back to `fill`, matching the Builder's default. */
+export function normalizeImageFit(value) {
+    if (value === ImageFitMode.CROP || value === ImageFitMode.CONTAIN)
+        return value;
+    return ImageFitMode.FILL;
+}
+/** The same mode expressed as CSS, for anyone rendering the element live. */
+export function imageFitObjectFit(value) {
+    const mode = normalizeImageFit(value);
+    if (mode === ImageFitMode.CROP)
+        return 'cover';
+    return mode;
+}
+/**
+ * Source and destination rectangles for one `drawImage` call.
+ *
+ * `fill` stretches, `crop` centre-crops the source, `contain` letterboxes
+ * inside the box. Returns null when either side has no area to draw into.
+ */
+export function computeImageFitDrawRect(sourceWidth, sourceHeight, targetX, targetY, targetWidth, targetHeight, value) {
+    if (sourceWidth <= 0 || sourceHeight <= 0 || targetWidth <= 0 || targetHeight <= 0)
+        return null;
+    const rect = {
+        sx: 0,
+        sy: 0,
+        sw: sourceWidth,
+        sh: sourceHeight,
+        dx: targetX,
+        dy: targetY,
+        dw: targetWidth,
+        dh: targetHeight,
+    };
+    const mode = normalizeImageFit(value);
+    if (mode === ImageFitMode.CROP) {
+        const targetAspect = targetWidth / targetHeight;
+        const sourceAspect = sourceWidth / sourceHeight;
+        if (targetAspect > sourceAspect) {
+            rect.sh = sourceWidth / targetAspect;
+            rect.sy = (sourceHeight - rect.sh) / 2;
+        }
+        else {
+            rect.sw = sourceHeight * targetAspect;
+            rect.sx = (sourceWidth - rect.sw) / 2;
+        }
+    }
+    else if (mode === ImageFitMode.CONTAIN) {
+        const scale = Math.min(targetWidth / sourceWidth, targetHeight / sourceHeight);
+        rect.dw = sourceWidth * scale;
+        rect.dh = sourceHeight * scale;
+        rect.dx = targetX + (targetWidth - rect.dw) / 2;
+        rect.dy = targetY + (targetHeight - rect.dh) / 2;
+    }
+    return rect;
+}
+/**
+ * 128-bit-ish digest of an arbitrary string. Same construction the runner uses
+ * for its composition cache tag, so the two agree on what "the same image"
+ * means.
+ */
+export function hashSignature(input) {
+    let first = 0xdeadbeef ^ input.length;
+    let second = 0x41c6ce57 ^ input.length;
+    for (let index = 0; index < input.length; index++) {
+        const code = input.charCodeAt(index);
+        first = Math.imul(first ^ code, 2654435761);
+        second = Math.imul(second ^ code, 1597334677);
+    }
+    first = Math.imul(first ^ (first >>> 16), 2246822507) ^ Math.imul(second ^ (second >>> 13), 3266489909);
+    second = Math.imul(second ^ (second >>> 16), 2246822507) ^ Math.imul(first ^ (first >>> 13), 3266489909);
+    return `${(first >>> 0).toString(16).padStart(8, '0')}${(second >>> 0).toString(16).padStart(8, '0')}`;
+}

package/dist/souvenir/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Souvenir composer — one image out of a Builder page.
+ *
+ * `composeSouvenir` is the whole public surface most callers need: hand it the
+ * souvenir page's saved editor config plus the values for its bound elements,
+ * get back a File ready to upload and a tag that makes re-composing the same
+ * content a no-op on the server.
+ *
+ * See `README.md` in this folder for the contract and the platform wiring.
+ */
+export * from './types.js';
+export * from './imageFit.js';
+export { wrapText, tokenize, layoutLines, type MeasureText, type TextAlign, type TextVAlign, type PlacedLine, } from './text.js';
+export { renderSouvenir, drawOrder, pageHasOpaqueBackground, souvenirSignature, loadSouvenirImage, } from './render.js';
+import { type SouvenirOptions, type SouvenirPage, type SouvenirResult, type SouvenirValues } from './types.js';
+/**
+ * Element ids for output-bound elements are `outputs@@nodeId@@key[@@tab@@rand]`.
+ * Modules know field keys; the page knows element ids. This bridges the two.
+ */
+export declare function parseSouvenirOutputId(eid: string): {
+    nodeId: string;
+    key: string;
+} | null;
+/**
+ * Spreads `{ fieldKey: value }` over every element on the page bound to that
+ * field, so a module never has to know how element ids are built.
+ *
+ * Pass `nodeId` to ignore elements bound to some other node's output.
+ */
+export declare function resolveSouvenirValues(page: SouvenirPage, fieldValues: Record<string, string | null | undefined>, nodeId?: string): SouvenirValues;
+/**
+ * Renders the page and packages it as a File.
+ *
+ * `auto` keeps JPEG for the usual case (a designed card with a full background,
+ * where JPEG is three to five times smaller on a phone's connection) and only
+ * falls back to PNG when the page has no opaque background to flatten onto.
+ */
+export declare function composeSouvenir(page: SouvenirPage, values?: SouvenirValues, options?: SouvenirOptions): Promise<SouvenirResult>;
+/**
+ * The upload tag for this exact souvenir.
+ *
+ * The media endpoint is idempotent per (project, session, tag): re-composing
+ * unchanged content returns the URL already stored instead of a second file.
+ * Anything else uploaded in the same submission must use a different tag, or
+ * it will be handed back the first file.
+ */
+export declare function souvenirTag(page: SouvenirPage, values?: SouvenirValues): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/souvenir/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/souvenir/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,WAAW,EACX,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,UAAU,GAChB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,cAAc,EACd,SAAS,EACT,uBAAuB,EACvB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,cAAc,EACpB,MAAM,YAAY,CAAC;AAKpB;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAKzF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,YAAY,EAClB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EACtD,MAAM,CAAC,EAAE,MAAM,GACd,cAAc,CAUhB;AAYD;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,YAAY,EAClB,MAAM,GAAE,cAAmB,EAC3B,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,cAAc,CAAC,CAqBzB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,GAAE,cAAmB,GAAG,MAAM,CAEnF"}

package/dist/souvenir/index.js

@@ -0,0 +1,94 @@
+/**
+ * Souvenir composer — one image out of a Builder page.
+ *
+ * `composeSouvenir` is the whole public surface most callers need: hand it the
+ * souvenir page's saved editor config plus the values for its bound elements,
+ * get back a File ready to upload and a tag that makes re-composing the same
+ * content a no-op on the server.
+ *
+ * See `README.md` in this folder for the contract and the platform wiring.
+ */
+export * from './types.js';
+export * from './imageFit.js';
+export { wrapText, tokenize, layoutLines, } from './text.js';
+export { renderSouvenir, drawOrder, pageHasOpaqueBackground, souvenirSignature, loadSouvenirImage, } from './render.js';
+import { pageHasOpaqueBackground, renderSouvenir, souvenirSignature } from './render.js';
+import { SouvenirError, } from './types.js';
+const OUTPUT_SEPARATOR = '@@';
+const OUTPUT_PREFIX = 'outputs';
+/**
+ * Element ids for output-bound elements are `outputs@@nodeId@@key[@@tab@@rand]`.
+ * Modules know field keys; the page knows element ids. This bridges the two.
+ */
+export function parseSouvenirOutputId(eid) {
+    if (!eid.startsWith(OUTPUT_PREFIX + OUTPUT_SEPARATOR))
+        return null;
+    const parts = eid.split(OUTPUT_SEPARATOR);
+    if (parts.length < 3)
+        return null;
+    return { nodeId: parts[1], key: parts[2] };
+}
+/**
+ * Spreads `{ fieldKey: value }` over every element on the page bound to that
+ * field, so a module never has to know how element ids are built.
+ *
+ * Pass `nodeId` to ignore elements bound to some other node's output.
+ */
+export function resolveSouvenirValues(page, fieldValues, nodeId) {
+    const values = {};
+    for (const eid of Object.keys(page.elements ?? {})) {
+        const parsed = parseSouvenirOutputId(eid);
+        if (!parsed)
+            continue;
+        if (nodeId && parsed.nodeId !== nodeId)
+            continue;
+        if (!(parsed.key in fieldValues))
+            continue;
+        values[eid] = fieldValues[parsed.key];
+    }
+    return values;
+}
+function encode(canvas, type, quality) {
+    return new Promise((resolve, reject) => {
+        canvas.toBlob((blob) => (blob ? resolve(blob) : reject(new SouvenirError('encode_failed', 'Could not encode the souvenir.'))), type, quality);
+    });
+}
+/**
+ * Renders the page and packages it as a File.
+ *
+ * `auto` keeps JPEG for the usual case (a designed card with a full background,
+ * where JPEG is three to five times smaller on a phone's connection) and only
+ * falls back to PNG when the page has no opaque background to flatten onto.
+ */
+export async function composeSouvenir(page, values = {}, options = {}) {
+    const canvas = await renderSouvenir(page, values, options);
+    const format = options.format && options.format !== 'auto'
+        ? options.format
+        : pageHasOpaqueBackground(page)
+            ? 'jpeg'
+            : 'png';
+    const quality = typeof options.quality === 'number' ? options.quality : 0.9;
+    const mime = format === 'png' ? 'image/png' : 'image/jpeg';
+    const blob = await encode(canvas, mime, quality);
+    const name = (options.fileName || 'souvenir').replace(/\.(jpe?g|png)$/i, '');
+    const file = new File([blob], `${name}.${format === 'png' ? 'png' : 'jpg'}`, { type: mime });
+    return {
+        file,
+        canvas,
+        tag: souvenirTag(page, values),
+        width: canvas.width,
+        height: canvas.height,
+        format,
+    };
+}
+/**
+ * The upload tag for this exact souvenir.
+ *
+ * The media endpoint is idempotent per (project, session, tag): re-composing
+ * unchanged content returns the URL already stored instead of a second file.
+ * Anything else uploaded in the same submission must use a different tag, or
+ * it will be handed back the first file.
+ */
+export function souvenirTag(page, values = {}) {
+    return `souvenir-${souvenirSignature(page, values)}`;
+}

package/dist/souvenir/render.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The composer itself: a souvenir page's saved properties, redrawn onto a
+ * canvas at the page's own pixel size.
+ *
+ * It redraws from the property bag rather than screenshotting the DOM. The
+ * souvenir page is never mounted in the runner, so there is no DOM to shoot;
+ * and reading properties keeps the result independent of screen size, scroll
+ * position, font fallback and half-finished animations. Every mapping below
+ * mirrors the runner's `elementStyle`, which is what the operator sees in the
+ * editor and the preview.
+ */
+import { type SouvenirOptions, type SouvenirPage, type SouvenirValues } from './types.js';
+/** Loads one image with EXIF orientation applied, or throws a SouvenirError. */
+export declare function loadSouvenirImage(url: string, crossOrigin: string | null | undefined): Promise<CanvasImageSource & {
+    width: number;
+    height: number;
+}>;
+/** Element ids in draw order: z-index ascending, insertion order for ties. */
+export declare function drawOrder(page: SouvenirPage): string[];
+/**
+ * True when every pixel is guaranteed opaque, i.e. a `bg` element covers the
+ * page with a colour or an image. Decides JPEG versus PNG in `auto`.
+ */
+export declare function pageHasOpaqueBackground(page: SouvenirPage): boolean;
+/** A stable signature for (page, values): same inputs, same tag, same upload. */
+export declare function souvenirSignature(page: SouvenirPage, values: SouvenirValues): string;
+/**
+ * Draws the page and returns the canvas.
+ *
+ * Every image is loaded before anything is drawn, so a slow CDN cannot leave a
+ * half-composed image behind; a failed load throws rather than quietly
+ * producing a souvenir with a hole in it.
+ */
+export declare function renderSouvenir(page: SouvenirPage, values?: SouvenirValues, options?: SouvenirOptions): Promise<HTMLCanvasElement>;
+//# sourceMappingURL=render.d.ts.map

package/dist/souvenir/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/souvenir/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,YAAY,EAEjB,KAAK,cAAc,EAEpB,MAAM,YAAY,CAAC;AAkRpB,gFAAgF;AAChF,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACrC,OAAO,CAAC,iBAAiB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAoBhE;AAED,8EAA8E;AAC9E,wBAAgB,SAAS,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,EAAE,CAOtD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAYnE;AAED,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,cAAc,GAAG,MAAM,CAMpF;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,YAAY,EAClB,MAAM,GAAE,cAAmB,EAC3B,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,iBAAiB,CAAC,CAoE5B"}

package/dist/souvenir/render.js

@@ -0,0 +1,357 @@
+/**
+ * The composer itself: a souvenir page's saved properties, redrawn onto a
+ * canvas at the page's own pixel size.
+ *
+ * It redraws from the property bag rather than screenshotting the DOM. The
+ * souvenir page is never mounted in the runner, so there is no DOM to shoot;
+ * and reading properties keeps the result independent of screen size, scroll
+ * position, font fallback and half-finished animations. Every mapping below
+ * mirrors the runner's `elementStyle`, which is what the operator sees in the
+ * editor and the preview.
+ */
+import { computeImageFitDrawRect, hashSignature, normalizeImageFit } from './imageFit.js';
+import { layoutLines, wrapText } from './text.js';
+import { isSouvenirSizeAllowed, SouvenirError, SOUVENIR_ELEMENT_TYPES, } from './types.js';
+const DEFAULT_LINE_HEIGHT = 1.2;
+const TRANSPARENT = 'TRANSPARENT';
+const num = (value, fallback = 0) => {
+    const parsed = typeof value === 'number' ? value : parseFloat(String(value ?? ''));
+    return Number.isFinite(parsed) ? parsed : fallback;
+};
+const colorOf = (value) => {
+    const text = typeof value === 'string' ? value.trim() : '';
+    if (!text || text === TRANSPARENT)
+        return '';
+    return text;
+};
+function geometryOf(property) {
+    return {
+        x: num(property['x-position']),
+        y: num(property['y-position']),
+        width: num(property['width']),
+        height: num(property['height']),
+        zIndex: num(property['zIndex']),
+        rotation: num(property['rotation']),
+        opacity: 'opacity' in property ? num(property['opacity'], 100) : 100,
+        radius: num(property['radius']),
+    };
+}
+/** `display: 'off'` is the layer eye in the Builder. A hidden layer is not in the image. */
+function isHidden(property) {
+    return property['display'] === 'off';
+}
+function roundedRectPath(ctx, x, y, width, height, radius) {
+    const r = Math.max(0, Math.min(radius, Math.min(width, height) / 2));
+    ctx.beginPath();
+    if (r <= 0) {
+        ctx.rect(x, y, width, height);
+        return;
+    }
+    ctx.moveTo(x + r, y);
+    ctx.lineTo(x + width - r, y);
+    ctx.quadraticCurveTo(x + width, y, x + width, y + r);
+    ctx.lineTo(x + width, y + height - r);
+    ctx.quadraticCurveTo(x + width, y + height, x + width - r, y + height);
+    ctx.lineTo(x + r, y + height);
+    ctx.quadraticCurveTo(x, y + height, x, y + height - r);
+    ctx.lineTo(x, y + r);
+    ctx.quadraticCurveTo(x, y, x + r, y);
+    ctx.closePath();
+}
+function ellipsePath(ctx, x, y, width, height) {
+    ctx.beginPath();
+    ctx.ellipse(x + width / 2, y + height / 2, width / 2, height / 2, 0, 0, Math.PI * 2);
+    ctx.closePath();
+}
+/**
+ * Runs `draw` in the element's own space: origin at the box's top left, the
+ * box rotated about its centre and faded like CSS `opacity`.
+ */
+function inElementSpace(ctx, geo, draw) {
+    ctx.save();
+    ctx.globalAlpha = Math.max(0, Math.min(1, geo.opacity / 100));
+    ctx.translate(geo.x + geo.width / 2, geo.y + geo.height / 2);
+    if (geo.rotation)
+        ctx.rotate((geo.rotation * Math.PI) / 180);
+    ctx.translate(-geo.width / 2, -geo.height / 2);
+    draw(ctx, geo.width, geo.height);
+    ctx.restore();
+}
+function fillBackground(ctx, property, width, height, radius, ellipse) {
+    const background = colorOf(property['bg-color']) || colorOf(property['fill-color']);
+    if (!background)
+        return;
+    if (ellipse)
+        ellipsePath(ctx, 0, 0, width, height);
+    else
+        roundedRectPath(ctx, 0, 0, width, height, radius);
+    ctx.fillStyle = background;
+    ctx.fill();
+}
+/**
+ * Strokes the element's border inside its box.
+ *
+ * CSS would grow the box outward; drawing inside keeps the element exactly the
+ * size the operator gave it, at the cost of half a border width along the edge.
+ */
+function strokeBorder(ctx, property, width, height, radius, ellipse) {
+    if (property['border-style'] === 'none')
+        return;
+    const borderWidth = num(property['border-width']);
+    if (borderWidth <= 0)
+        return;
+    const color = colorOf(property['border-color']) || '#94a3b8';
+    if (!color)
+        return;
+    const inset = borderWidth / 2;
+    if (ellipse)
+        ellipsePath(ctx, inset, inset, width - borderWidth, height - borderWidth);
+    else
+        roundedRectPath(ctx, inset, inset, width - borderWidth, height - borderWidth, Math.max(0, radius - inset));
+    ctx.lineWidth = borderWidth;
+    ctx.strokeStyle = color;
+    ctx.stroke();
+}
+function fontOf(property, fontSize) {
+    const formatting = Array.isArray(property['formatting']) ? property['formatting'] : [];
+    const style = formatting.includes('Italic') ? 'italic ' : '';
+    const weight = formatting.includes('Bold') ? 'bold ' : '';
+    const rawFamily = typeof property['family'] === 'string' ? property['family'].trim() : '';
+    const family = !rawFamily || rawFamily === 'inherit' ? 'sans-serif' : rawFamily;
+    const quoted = /[",]/.test(family) || !/\s/.test(family) ? family : `"${family}"`;
+    return `${style}${weight}${fontSize}px ${quoted}`;
+}
+function drawText(ctx, property, geo, content) {
+    const fontSize = num(property['font-size'], 14);
+    if (fontSize <= 0 || !content)
+        return;
+    const lineHeight = num(property['line-height'], DEFAULT_LINE_HEIGHT) || DEFAULT_LINE_HEIGHT;
+    const align = (property['alignment'] || 'center');
+    const vAlign = (property['v-alignment'] || 'middle');
+    inElementSpace(ctx, geo, (c, width, height) => {
+        fillBackground(c, property, width, height, geo.radius, false);
+        roundedRectPath(c, 0, 0, width, height, geo.radius);
+        c.clip();
+        c.font = fontOf(property, fontSize);
+        c.textBaseline = 'alphabetic';
+        c.textAlign = 'left';
+        c.fillStyle = colorOf(property['color']) || '#000000';
+        const measure = (text) => c.measureText(text).width;
+        const lines = wrapText(content, width, measure);
+        const placed = layoutLines(lines, { x: 0, y: 0, width, height }, fontSize, lineHeight, align, vAlign, measure);
+        const formatting = Array.isArray(property['formatting']) ? property['formatting'] : [];
+        const underline = formatting.includes('Underline');
+        const strike = formatting.includes('Strikethrough');
+        for (const line of placed) {
+            if (!line.text)
+                continue;
+            c.fillText(line.text, line.x, line.y);
+            if (underline)
+                c.fillRect(line.x, line.y + fontSize * 0.12, line.width, Math.max(1, fontSize / 16));
+            if (strike)
+                c.fillRect(line.x, line.y - fontSize * 0.28, line.width, Math.max(1, fontSize / 16));
+        }
+    });
+    inElementSpace(ctx, geo, (c, width, height) => strokeBorder(c, property, width, height, geo.radius, false));
+}
+function drawImage(ctx, property, geo, image) {
+    inElementSpace(ctx, geo, (c, width, height) => {
+        fillBackground(c, property, width, height, geo.radius, false);
+        roundedRectPath(c, 0, 0, width, height, geo.radius);
+        c.clip();
+        const rect = computeImageFitDrawRect(image.width, image.height, 0, 0, width, height, normalizeImageFit(property['image-fit']));
+        if (rect)
+            c.drawImage(image, rect.sx, rect.sy, rect.sw, rect.sh, rect.dx, rect.dy, rect.dw, rect.dh);
+    });
+    inElementSpace(ctx, geo, (c, width, height) => strokeBorder(c, property, width, height, geo.radius, false));
+}
+function drawShape(ctx, type, property, geo) {
+    inElementSpace(ctx, geo, (c, width, height) => {
+        if (type === 'shape-line') {
+            const strokeWidth = num(property['stroke-width'], 1);
+            const color = colorOf(property['stroke-color']) || '#000000';
+            if (strokeWidth <= 0 || !color)
+                return;
+            if (property['line-style'] === 'dashed')
+                c.setLineDash([strokeWidth * 3, strokeWidth * 2]);
+            else if (property['line-style'] === 'dotted')
+                c.setLineDash([strokeWidth, strokeWidth * 2]);
+            c.lineCap = 'round';
+            c.strokeStyle = color;
+            c.lineWidth = strokeWidth;
+            const y = height / 2;
+            c.beginPath();
+            c.moveTo(0, y);
+            c.lineTo(width, y);
+            c.stroke();
+            c.setLineDash([]);
+            if (property['arrow'] && property['arrow'] !== 'none') {
+                const head = Math.max(strokeWidth * 3, 6);
+                c.beginPath();
+                c.moveTo(width, y);
+                c.lineTo(width - head, y - head / 2);
+                c.lineTo(width - head, y + head / 2);
+                c.closePath();
+                c.fillStyle = color;
+                c.fill();
+            }
+            return;
+        }
+        const ellipse = type === 'shape-ellipse';
+        const fill = colorOf(property['fill-color']);
+        if (fill) {
+            if (ellipse)
+                ellipsePath(c, 0, 0, width, height);
+            else
+                roundedRectPath(c, 0, 0, width, height, geo.radius);
+            c.fillStyle = fill;
+            c.fill();
+        }
+        const strokeWidth = num(property['stroke-width'], 0) || num(property['border-width'], 0);
+        const strokeColor = colorOf(property['stroke-color']) || colorOf(property['border-color']);
+        if (strokeWidth > 0 && strokeColor) {
+            const inset = strokeWidth / 2;
+            if (ellipse)
+                ellipsePath(c, inset, inset, width - strokeWidth, height - strokeWidth);
+            else
+                roundedRectPath(c, inset, inset, width - strokeWidth, height - strokeWidth, Math.max(0, geo.radius - inset));
+            c.lineWidth = strokeWidth;
+            c.strokeStyle = strokeColor;
+            c.stroke();
+        }
+    });
+}
+/** Loads one image with EXIF orientation applied, or throws a SouvenirError. */
+export async function loadSouvenirImage(url, crossOrigin) {
+    if (typeof createImageBitmap === 'function' && typeof fetch === 'function') {
+        try {
+            const response = await fetch(url, { mode: crossOrigin === null ? 'same-origin' : 'cors' });
+            if (!response.ok)
+                throw new Error(`HTTP ${response.status}`);
+            const blob = await response.blob();
+            // A phone's portrait photo carries its rotation in EXIF. Without this the
+            // person in the souvenir is lying on their side.
+            return await createImageBitmap(blob, { imageOrientation: 'from-image' });
+        }
+        catch {
+            // Fall through: some CDNs refuse the fetch but serve <img> fine.
+        }
+    }
+    return await new Promise((resolve, reject) => {
+        const image = new Image();
+        if (crossOrigin !== null)
+            image.crossOrigin = crossOrigin ?? 'anonymous';
+        image.onload = () => resolve(image);
+        image.onerror = () => reject(new SouvenirError('image_failed', `Could not load image: ${url}`));
+        image.src = url;
+    });
+}
+/** Element ids in draw order: z-index ascending, insertion order for ties. */
+export function drawOrder(page) {
+    return Object.keys(page.elements ?? {})
+        .filter((eid) => SOUVENIR_ELEMENT_TYPES.includes(page.elements[eid]?.type))
+        .filter((eid) => !isHidden(page.properties?.[eid] ?? {}))
+        .map((eid, index) => ({ eid, index, z: num((page.properties?.[eid] ?? {})['zIndex']) }))
+        .sort((a, b) => (a.z === b.z ? a.index - b.index : a.z - b.z))
+        .map((entry) => entry.eid);
+}
+/**
+ * True when every pixel is guaranteed opaque, i.e. a `bg` element covers the
+ * page with a colour or an image. Decides JPEG versus PNG in `auto`.
+ */
+export function pageHasOpaqueBackground(page) {
+    for (const eid of Object.keys(page.elements ?? {})) {
+        if (page.elements[eid]?.type !== 'bg')
+            continue;
+        const property = page.properties?.[eid] ?? {};
+        if (isHidden(property))
+            continue;
+        const geo = geometryOf(property);
+        const covers = geo.x <= 0 && geo.y <= 0 && geo.width >= page.width && geo.height >= page.height;
+        if (!covers)
+            continue;
+        if (geo.opacity < 100 || geo.radius > 0 || geo.rotation)
+            continue;
+        if (colorOf(property['bg-color']) || typeof property['source'] === 'string' && property['source'])
+            return true;
+    }
+    return false;
+}
+/** A stable signature for (page, values): same inputs, same tag, same upload. */
+export function souvenirSignature(page, values) {
+    const parts = [`${page.width}x${page.height}`];
+    for (const eid of drawOrder(page)) {
+        parts.push(eid, page.elements[eid]?.type ?? '', JSON.stringify(page.properties?.[eid] ?? {}), String(values[eid] ?? ''));
+    }
+    return hashSignature(parts.join('|'));
+}
+/**
+ * Draws the page and returns the canvas.
+ *
+ * Every image is loaded before anything is drawn, so a slow CDN cannot leave a
+ * half-composed image behind; a failed load throws rather than quietly
+ * producing a souvenir with a hole in it.
+ */
+export async function renderSouvenir(page, values = {}, options = {}) {
+    if (typeof document === 'undefined') {
+        throw new SouvenirError('no_dom', 'The souvenir composer needs a browser document.');
+    }
+    const width = Math.round(num(page.width));
+    const height = Math.round(num(page.height));
+    if (!isSouvenirSizeAllowed(width, height)) {
+        throw new SouvenirError(width < 1 || height < 1 ? 'bad_size' : 'too_large', `Souvenir page size ${width}x${height} is out of range.`);
+    }
+    const order = drawOrder(page);
+    // Webfonts first: measuring before they land silently lays the text out in
+    // the fallback font and the first souvenir of an event comes out wrong.
+    if (!options.skipFontWait && typeof document !== 'undefined' && document.fonts?.ready) {
+        try {
+            await document.fonts.ready;
+        }
+        catch {
+            /* a font that never resolves must not block the souvenir */
+        }
+    }
+    const sources = new Map();
+    await Promise.all(order.map(async (eid) => {
+        const type = page.elements[eid]?.type;
+        if (type !== 'image' && type !== 'image-frame' && type !== 'bg')
+            return;
+        const property = page.properties?.[eid] ?? {};
+        const url = (values[eid] ?? property['source'] ?? '').toString().trim();
+        if (!url)
+            return;
+        sources.set(eid, await loadSouvenirImage(url, options.crossOrigin));
+    }));
+    const canvas = document.createElement('canvas');
+    canvas.width = width;
+    canvas.height = height;
+    const ctx = canvas.getContext('2d');
+    if (!ctx)
+        throw new SouvenirError('canvas_unavailable', 'Could not get a 2d context.');
+    for (const eid of order) {
+        const type = page.elements[eid]?.type ?? '';
+        const property = page.properties?.[eid] ?? {};
+        const geo = geometryOf(property);
+        if (geo.width <= 0 || geo.height <= 0)
+            continue;
+        if (type === 'text') {
+            const content = (values[eid] ?? property['content'] ?? '').toString();
+            drawText(ctx, property, geo, content);
+            continue;
+        }
+        if (type === 'image' || type === 'image-frame' || type === 'bg') {
+            const image = sources.get(eid);
+            if (image)
+                drawImage(ctx, property, geo, image);
+            else
+                inElementSpace(ctx, geo, (c, w, h) => {
+                    fillBackground(c, property, w, h, geo.radius, false);
+                    strokeBorder(c, property, w, h, geo.radius, false);
+                });
+            continue;
+        }
+        drawShape(ctx, type, property, geo);
+    }
+    return canvas;
+}

package/dist/souvenir/text.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Text layout for the souvenir composer.
+ *
+ * Canvas has no line box: every wrap decision has to be made here. The rule
+ * that matters is PF's 2026-09-12 ruling for the live wall, carried over to
+ * every composed image: **a word is never broken across lines**. A word only
+ * splits when it alone is wider than the box, which is the one case where
+ * keeping it whole would push it out of frame entirely.
+ *
+ * CJK has no spaces, so a run of CJK characters breaks per character. Mixed
+ * text therefore behaves the way a reader expects on both sides.
+ */
+/** Measures one string in the current canvas font. Injected so layout is testable. */
+export type MeasureText = (text: string) => number;
+export type TextAlign = 'left' | 'center' | 'right';
+export type TextVAlign = 'top' | 'middle' | 'bottom';
+/**
+ * Splits a line into the smallest pieces a break is allowed to fall between:
+ * a whole latin word, a single CJK character, or a run of spaces.
+ */
+export declare function tokenize(line: string): string[];
+/**
+ * Wraps text to `maxWidth`, honouring existing newlines.
+ *
+ * Trailing spaces are dropped at a wrap point, the way a browser does, so a
+ * line never ends with the space that pushed it over.
+ */
+export declare function wrapText(text: string, maxWidth: number, measure: MeasureText): string[];
+export interface PlacedLine {
+    text: string;
+    /** Left edge to draw from; the caller keeps `textAlign` at `left`. */
+    x: number;
+    /** Baseline y. */
+    y: number;
+    width: number;
+}
+/**
+ * Places wrapped lines inside the element box.
+ *
+ * Vertical centring is the default because the runner sets `align-items: safe
+ * center` on any element that has an alignment, and the composed image has to
+ * match the page the operator laid out.
+ */
+export declare function layoutLines(lines: string[], box: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, fontSize: number, lineHeight: number, align: TextAlign, vAlign: TextVAlign, measure: MeasureText): PlacedLine[];
+//# sourceMappingURL=text.d.ts.map

package/dist/souvenir/text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../src/souvenir/text.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,sFAAsF;AACtF,MAAM,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;AAEnD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AACpD,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAKrD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAwB/C;AAmBD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,MAAM,EAAE,CAmCvF;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,CAAC,EAAE,MAAM,CAAC;IACV,kBAAkB;IAClB,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,EAAE,EACf,GAAG,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAC5D,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,SAAS,EAChB,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,WAAW,GACnB,UAAU,EAAE,CAkBd"}

package/dist/souvenir/text.js

@@ -0,0 +1,137 @@
+/**
+ * Text layout for the souvenir composer.
+ *
+ * Canvas has no line box: every wrap decision has to be made here. The rule
+ * that matters is PF's 2026-09-12 ruling for the live wall, carried over to
+ * every composed image: **a word is never broken across lines**. A word only
+ * splits when it alone is wider than the box, which is the one case where
+ * keeping it whole would push it out of frame entirely.
+ *
+ * CJK has no spaces, so a run of CJK characters breaks per character. Mixed
+ * text therefore behaves the way a reader expects on both sides.
+ */
+const CJK = /[ᄀ-ᇿ⺀-〿぀-ヿ㄰-㆏㐀-䶿一-鿿ꀀ-꓏가-힯豈-﫿︰-﹏＀-｠￠-￦]/;
+/**
+ * Splits a line into the smallest pieces a break is allowed to fall between:
+ * a whole latin word, a single CJK character, or a run of spaces.
+ */
+export function tokenize(line) {
+    const tokens = [];
+    let word = '';
+    const flush = () => {
+        if (word)
+            tokens.push(word);
+        word = '';
+    };
+    for (const char of Array.from(line)) {
+        if (char === ' ' || char === '\t') {
+            flush();
+            const last = tokens[tokens.length - 1];
+            if (last && (last === ' ' || last.endsWith(' ')))
+                tokens[tokens.length - 1] = last + char;
+            else
+                tokens.push(char);
+            continue;
+        }
+        if (CJK.test(char)) {
+            flush();
+            tokens.push(char);
+            continue;
+        }
+        word += char;
+    }
+    flush();
+    return tokens;
+}
+/** Breaks one over-wide token by characters. Only reached when a single token cannot fit. */
+function splitOversized(token, maxWidth, measure) {
+    const out = [];
+    let current = '';
+    for (const char of Array.from(token)) {
+        const next = current + char;
+        if (current && measure(next) > maxWidth) {
+            out.push(current);
+            current = char;
+        }
+        else {
+            current = next;
+        }
+    }
+    if (current)
+        out.push(current);
+    return out;
+}
+/**
+ * Wraps text to `maxWidth`, honouring existing newlines.
+ *
+ * Trailing spaces are dropped at a wrap point, the way a browser does, so a
+ * line never ends with the space that pushed it over.
+ */
+export function wrapText(text, maxWidth, measure) {
+    if (!text)
+        return [''];
+    if (!(maxWidth > 0))
+        return text.split('\n');
+    const lines = [];
+    for (const rawLine of text.split('\n')) {
+        if (rawLine === '') {
+            lines.push('');
+            continue;
+        }
+        let current = '';
+        for (const token of tokenize(rawLine)) {
+            if (measure(current + token) <= maxWidth) {
+                current += token;
+                continue;
+            }
+            // Does not fit after what we already have: close the line first.
+            if (current) {
+                lines.push(current.replace(/[ \t]+$/, ''));
+                current = '';
+            }
+            // A space that caused the wrap is swallowed, as a browser does.
+            if (token.trim() === '')
+                continue;
+            if (measure(token) > maxWidth) {
+                // The one case where a word has to break: it does not fit on a line of its own.
+                const pieces = splitOversized(token, maxWidth, measure);
+                for (let i = 0; i < pieces.length - 1; i++)
+                    lines.push(pieces[i]);
+                current = pieces[pieces.length - 1] ?? '';
+            }
+            else {
+                current = token;
+            }
+        }
+        lines.push(current.replace(/[ \t]+$/, ''));
+    }
+    return lines;
+}
+/**
+ * Places wrapped lines inside the element box.
+ *
+ * Vertical centring is the default because the runner sets `align-items: safe
+ * center` on any element that has an alignment, and the composed image has to
+ * match the page the operator laid out.
+ */
+export function layoutLines(lines, box, fontSize, lineHeight, align, vAlign, measure) {
+    const step = fontSize * lineHeight;
+    const blockHeight = step * lines.length;
+    let top = box.y;
+    if (vAlign === 'middle')
+        top = box.y + (box.height - blockHeight) / 2;
+    else if (vAlign === 'bottom')
+        top = box.y + box.height - blockHeight;
+    return lines.map((text, index) => {
+        const width = measure(text);
+        let x = box.x;
+        if (align === 'center')
+            x = box.x + (box.width - width) / 2;
+        else if (align === 'right')
+            x = box.x + box.width - width;
+        // Baseline sits on the alphabetic line of a box `step` tall; 0.8 of the
+        // font size is the ratio browsers land on for the fonts we ship.
+        const y = top + index * step + fontSize * 0.8;
+        return { text, x, y, width };
+    });
+}

package/dist/souvenir/types.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Souvenir — the shared definition of "one page of Builder elements, rendered
+ * into a single image".
+ *
+ * A node with `souvenir_setting.on` gets an extra editor page that the runner
+ * never renders: it exists only to be composed. The composer reads the very
+ * same property bag the Builder saves for any other page, so an operator lays
+ * the souvenir out with the tools they already know and what they see is what
+ * gets composed.
+ *
+ * Framework-free by construction: the renderer takes plain data and returns a
+ * canvas. Nothing here knows about Vue, the runner, or any single module.
+ */
+/** Element types the composer draws. Anything else on the page is skipped. */
+export declare const SOUVENIR_ELEMENT_TYPES: readonly ["bg", "image", "image-frame", "text", "shape-rect", "shape-ellipse", "shape-line"];
+export type SouvenirElementType = (typeof SOUVENIR_ELEMENT_TYPES)[number];
+/** Anything the Builder stores for one element. Values arrive untyped from the API. */
+export type SouvenirProperty = Record<string, unknown>;
+/** One element as the Builder's `detail.elements` records it. */
+export interface SouvenirElement {
+    type: string;
+    name?: string;
+}
+/**
+ * One souvenir page, shaped exactly like the editor config the API returns:
+ * `detail.elements` keyed by element id, `detail.properties[tab]` for the bag.
+ * The caller picks the tab; the composer only ever sees one page.
+ */
+export interface SouvenirPage {
+    /** Canvas pixels. This is the output size too: souvenir pages are never folded. */
+    width: number;
+    height: number;
+    elements: Record<string, SouvenirElement>;
+    properties: Record<string, SouvenirProperty>;
+}
+/**
+ * Runtime values for the elements bound to node outputs, keyed by element id.
+ * Text elements take the string; image elements take a URL.
+ *
+ * Use `resolveSouvenirValues` to go from field keys (what a module knows) to
+ * element ids (what the page knows).
+ */
+export type SouvenirValues = Record<string, string | null | undefined>;
+export type SouvenirFormat = 'auto' | 'jpeg' | 'png';
+export interface SouvenirOptions {
+    /**
+     * `auto` (default) picks JPEG unless the page has no opaque background, in
+     * which case the transparency has to survive and PNG wins.
+     */
+    format?: SouvenirFormat;
+    /** JPEG quality, 0 to 1. Default 0.9. */
+    quality?: number;
+    /** File name handed to the upload endpoint. Extension is set from the format. */
+    fileName?: string;
+    /**
+     * `crossOrigin` for every image the page loads. Defaults to `anonymous`,
+     * which is what keeps the canvas untainted; pass `null` for same-origin-only
+     * pages that must not send the header.
+     */
+    crossOrigin?: string | null;
+    /** Skip `document.fonts.ready`. Only for tests: a missing wait costs the first compose its webfonts. */
+    skipFontWait?: boolean;
+}
+export interface SouvenirResult {
+    file: File;
+    canvas: HTMLCanvasElement;
+    /** Stable per (page, values) — the upload tag that makes recomposing idempotent. */
+    tag: string;
+    width: number;
+    height: number;
+    format: Exclude<SouvenirFormat, 'auto'>;
+}
+/** Thrown for every refusal the caller is expected to handle and show. */
+export declare class SouvenirError extends Error {
+    readonly code: 'no_dom' | 'bad_size' | 'too_large' | 'canvas_unavailable' | 'image_failed' | 'encode_failed';
+    constructor(code: 'no_dom' | 'bad_size' | 'too_large' | 'canvas_unavailable' | 'image_failed' | 'encode_failed', message: string);
+}
+/**
+ * Canvas ceilings. iOS Safari refuses to rasterise past these and hands back a
+ * blank bitmap instead of an error, so the page is rejected at save time in the
+ * Builder rather than silently producing white images at an event.
+ */
+export declare const SOUVENIR_MAX_EDGE = 4096;
+export declare const SOUVENIR_MAX_AREA = 16777216;
+/** `true` when the page is within what a mobile browser will actually rasterise. */
+export declare function isSouvenirSizeAllowed(width: number, height: number): boolean;
+/** The message the Builder shows when a size is refused. */
+export declare function souvenirSizeError(width: number, height: number): string | '';
+//# sourceMappingURL=types.d.ts.map

package/dist/souvenir/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/souvenir/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,8EAA8E;AAC9E,eAAO,MAAM,sBAAsB,8FAQzB,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1E,uFAAuF;AACvF,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEvD,iEAAiE;AACjE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,mFAAmF;IACnF,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC1C,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAC9C;AAED;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;AAEvE,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;AAErD,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,wGAAwG;IACxG,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,IAAI,CAAC;IACX,MAAM,EAAE,iBAAiB,CAAC;IAC1B,oFAAoF;IACpF,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;CACzC;AAED,0EAA0E;AAC1E,qBAAa,aAAc,SAAQ,KAAK;aAEpB,IAAI,EAChB,QAAQ,GACR,UAAU,GACV,WAAW,GACX,oBAAoB,GACpB,cAAc,GACd,eAAe;gBANH,IAAI,EAChB,QAAQ,GACR,UAAU,GACV,WAAW,GACX,oBAAoB,GACpB,cAAc,GACd,eAAe,EACnB,OAAO,EAAE,MAAM;CAKlB;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,OAAO,CAAC;AACtC,eAAO,MAAM,iBAAiB,WAAa,CAAC;AAE5C,oFAAoF;AACpF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAK5E;AAED,4DAA4D;AAC5D,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,EAAE,CAW5E"}

package/dist/souvenir/types.js

@@ -0,0 +1,62 @@
+/**
+ * Souvenir — the shared definition of "one page of Builder elements, rendered
+ * into a single image".
+ *
+ * A node with `souvenir_setting.on` gets an extra editor page that the runner
+ * never renders: it exists only to be composed. The composer reads the very
+ * same property bag the Builder saves for any other page, so an operator lays
+ * the souvenir out with the tools they already know and what they see is what
+ * gets composed.
+ *
+ * Framework-free by construction: the renderer takes plain data and returns a
+ * canvas. Nothing here knows about Vue, the runner, or any single module.
+ */
+/** Element types the composer draws. Anything else on the page is skipped. */
+export const SOUVENIR_ELEMENT_TYPES = [
+    'bg',
+    'image',
+    'image-frame',
+    'text',
+    'shape-rect',
+    'shape-ellipse',
+    'shape-line',
+];
+/** Thrown for every refusal the caller is expected to handle and show. */
+export class SouvenirError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'SouvenirError';
+    }
+}
+/**
+ * Canvas ceilings. iOS Safari refuses to rasterise past these and hands back a
+ * blank bitmap instead of an error, so the page is rejected at save time in the
+ * Builder rather than silently producing white images at an event.
+ */
+export const SOUVENIR_MAX_EDGE = 4096;
+export const SOUVENIR_MAX_AREA = 16_777_216;
+/** `true` when the page is within what a mobile browser will actually rasterise. */
+export function isSouvenirSizeAllowed(width, height) {
+    if (!Number.isFinite(width) || !Number.isFinite(height))
+        return false;
+    if (width < 1 || height < 1)
+        return false;
+    if (Math.max(width, height) > SOUVENIR_MAX_EDGE)
+        return false;
+    return width * height <= SOUVENIR_MAX_AREA;
+}
+/** The message the Builder shows when a size is refused. */
+export function souvenirSizeError(width, height) {
+    if (!Number.isFinite(width) || !Number.isFinite(height) || width < 1 || height < 1) {
+        return 'Enter a width and a height in pixels.';
+    }
+    if (Math.max(width, height) > SOUVENIR_MAX_EDGE) {
+        return `The longest side must be ${SOUVENIR_MAX_EDGE}px or less.`;
+    }
+    if (width * height > SOUVENIR_MAX_AREA) {
+        return `Width times height must be ${SOUVENIR_MAX_AREA.toLocaleString('en-US')}px or less.`;
+    }
+    return '';
+}

package/package.json

@@ -1,60 +1,64 @@
-{
-  "name": "@realnation/builder-shared-sdk",
-  "version": "2.2.0",
-  "type": "module",
-  "private": false,
-  "exports": {
-    "./package.json": "./package.json",
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./runtime": {
-      "types": "./dist/runtime/index.d.ts",
-      "import": "./dist/runtime/index.js"
-    },
-    "./runtime/vue": {
-      "types": "./dist/runtime/vue/index.d.ts",
-      "import": "./dist/runtime/vue/index.js"
-    },
-    "./interaction": {
-      "types": "./dist/interaction/index.d.ts",
-      "import": "./dist/interaction/index.js"
-    },
-    "./interaction/vue": {
-      "types": "./dist/interaction/vue.d.ts",
-      "import": "./dist/interaction/vue.js"
-    }
-  },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "clean": "rimraf dist",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "prepublishOnly": "npm run clean && npm run test && npm run build",
-    "prepare": "npm run clean && npm run build"
-  },
-  "dependencies": {
-    "ali-oss": "^6.23.0",
-    "axios": "^1.7.7"
-  },
-  "peerDependencies": {
-    "vue": "^3.4.0"
-  },
-  "peerDependenciesMeta": {
-    "vue": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@types/ali-oss": "^6.16.11",
-    "@types/node": "^26.1.2",
-    "rimraf": "^5.0.5",
-    "typescript": "^5.4.5",
-    "vitest": "^2.1.0",
-    "vue": "^3.4.0"
-  }
-}
+{
+  "name": "@realnation/builder-shared-sdk",
+  "version": "2.4.0",
+  "type": "module",
+  "private": false,
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/index.js"
+    },
+    "./runtime/vue": {
+      "types": "./dist/runtime/vue/index.d.ts",
+      "import": "./dist/runtime/vue/index.js"
+    },
+    "./interaction": {
+      "types": "./dist/interaction/index.d.ts",
+      "import": "./dist/interaction/index.js"
+    },
+    "./interaction/vue": {
+      "types": "./dist/interaction/vue.d.ts",
+      "import": "./dist/interaction/vue.js"
+    },
+    "./souvenir": {
+      "types": "./dist/souvenir/index.d.ts",
+      "import": "./dist/souvenir/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rimraf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run clean && npm run test && npm run build",
+    "prepare": "npm run clean && npm run build"
+  },
+  "dependencies": {
+    "ali-oss": "^6.23.0",
+    "axios": "^1.7.7"
+  },
+  "peerDependencies": {
+    "vue": "^3.4.0"
+  },
+  "peerDependenciesMeta": {
+    "vue": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/ali-oss": "^6.16.11",
+    "@types/node": "^26.1.2",
+    "rimraf": "^5.0.5",
+    "typescript": "^5.4.5",
+    "vitest": "^2.1.0",
+    "vue": "^3.4.0"
+  }
+}