@realnation/builder-shared-sdk 2.4.1 → 2.5.0

package/dist/souvenir/index.d.ts

@@ -11,7 +11,7 @@
 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';
+export { renderSouvenir, drawOrder, outputSize, regionOf, pageHasOpaqueBackground, souvenirSignature, loadSouvenirImage, } from './render.js';
 import { type SouvenirOptions, type SouvenirPage, type SouvenirResult, type SouvenirValues } from './types.js';
 export { parseSouvenirOutputId } from './outputId.js';
 /**
@@ -37,5 +37,5 @@ export declare function composeSouvenir(page: SouvenirPage, values?: SouvenirVal
  * 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;
+export declare function souvenirTag(page: SouvenirPage, values?: SouvenirValues, options?: SouvenirOptions): string;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +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;AAGpB,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAEtD;;;;;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"}
+{"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,UAAU,EACV,QAAQ,EACR,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;AAGpB,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAEtD;;;;;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,EAAE,OAAO,GAAE,eAAoB,GAAG,MAAM,CAElH"}

package/dist/souvenir/index.js

@@ -11,7 +11,7 @@
 export * from './types.js';
 export * from './imageFit.js';
 export { wrapText, tokenize, layoutLines, } from './text.js';
-export { renderSouvenir, drawOrder, pageHasOpaqueBackground, souvenirSignature, loadSouvenirImage, } from './render.js';
+export { renderSouvenir, drawOrder, outputSize, regionOf, pageHasOpaqueBackground, souvenirSignature, loadSouvenirImage, } from './render.js';
 import { pageHasOpaqueBackground, renderSouvenir, souvenirSignature } from './render.js';
 import { SouvenirError, } from './types.js';
 import { parseSouvenirOutputId } from './outputId.js';
@@ -52,7 +52,7 @@ 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)
+        : pageHasOpaqueBackground(page, options.region)
             ? 'jpeg'
             : 'png';
     const quality = typeof options.quality === 'number' ? options.quality : 0.9;
@@ -63,7 +63,7 @@ export async function composeSouvenir(page, values = {}, options = {}) {
     return {
         file,
         canvas,
-        tag: souvenirTag(page, values),
+        tag: souvenirTag(page, values, options),
         width: canvas.width,
         height: canvas.height,
         format,
@@ -77,6 +77,6 @@ export async function composeSouvenir(page, values = {}, options = {}) {
  * 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)}`;
+export function souvenirTag(page, values = {}, options = {}) {
+    return `souvenir-${souvenirSignature(page, values, options)}`;
 }

package/dist/souvenir/render.d.ts

@@ -9,7 +9,7 @@
  * mirrors the runner's `elementStyle`, which is what the operator sees in the
  * editor and the preview.
  */
-import { type SouvenirOptions, type SouvenirPage, type SouvenirProperty, type SouvenirValues } from './types.js';
+import { type SouvenirOptions, type SouvenirPage, type SouvenirProperty, type SouvenirRegion, type SouvenirValues } from './types.js';
 /**
  * An element bound to a Data field whose field has no value is left out, the
  * way the runner hides it on a live page. Falling back to what the Builder
@@ -30,15 +30,25 @@ export declare function loadSouvenirImage(url: string, crossOrigin: string | nul
     width: number;
     height: number;
 }>;
+/**
+ * 整页时用它，给了区域时按区域算。区域外的元件照常留在页面上，由 runner 画。
+ */
+export declare function regionOf(page: SouvenirPage, region?: SouvenirRegion): SouvenirRegion;
+/** 出图尺寸：形状跟着区域，长边取 longEdge；不给 longEdge 就按区域原尺寸。 */
+export declare function outputSize(region: SouvenirRegion, longEdge?: number): {
+    width: number;
+    height: number;
+    scale: number;
+};
 /** Element ids in draw order: z-index ascending, insertion order for ties. */
-export declare function drawOrder(page: SouvenirPage): string[];
+export declare function drawOrder(page: SouvenirPage, region?: SouvenirRegion): 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;
+export declare function pageHasOpaqueBackground(page: SouvenirPage, region?: SouvenirRegion): boolean;
+/** A stable signature for (page, values, region, size): same inputs, same tag, same upload. */
+export declare function souvenirSignature(page: SouvenirPage, values: SouvenirValues, options?: SouvenirOptions): string;
 /**
  * Draws the page and returns the canvas.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/souvenir/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EAEpB,MAAM,YAAY,CAAC;AA6CpB;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAI7E;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAO5F;AA6ND,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,CAsE5B"}
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/souvenir/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,EAKL,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,cAAc,EAEpB,MAAM,YAAY,CAAC;AA6CpB;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAI7E;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAO5F;AAyPD,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;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,cAAc,CAEpF;AAED,oDAAoD;AACpD,wBAAgB,UAAU,CAAC,MAAM,EAAE,cAAc,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAStH;AAED,8EAA8E;AAC9E,wBAAgB,SAAS,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,MAAM,EAAE,CAY/E;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,OAAO,CAc5F;AAED,+FAA+F;AAC/F,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,GAAE,eAAoB,GAAG,MAAM,CAQnH;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,YAAY,EAClB,MAAM,GAAE,cAAmB,EAC3B,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,iBAAiB,CAAC,CA2E5B"}

package/dist/souvenir/render.js

@@ -12,7 +12,7 @@
 import { computeImageFitDrawRect, hashSignature, normalizeImageFit } from './imageFit.js';
 import { parseSouvenirOutputId } from './outputId.js';
 import { layoutLines, wrapText } from './text.js';
-import { isSouvenirSizeAllowed, SouvenirError, SOUVENIR_ELEMENT_TYPES, } from './types.js';
+import { isInsideRegion, isSouvenirInteractive, isSouvenirSizeAllowed, SouvenirError, SOUVENIR_ELEMENT_TYPES, } from './types.js';
 const DEFAULT_LINE_HEIGHT = 1.2;
 const TRANSPARENT = 'TRANSPARENT';
 const num = (value, fallback = 0) => {
@@ -144,39 +144,55 @@ function fontOf(property, fontSize) {
     const quoted = /[",]/.test(family) || !/\s/.test(family) ? family : `"${family}"`;
     return `${style}${weight}${fontSize}px ${quoted}`;
 }
-function drawText(ctx, property, geo, content) {
+/**
+ * Lays the text out inside the box already in element space. `padX` is the side
+ * padding the runner leaves on shape text.
+ */
+function drawTextInBox(c, property, radius, width, height, content, padX = 0) {
     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');
+    const boxWidth = Math.max(0, width - padX * 2);
+    if (boxWidth <= 0)
+        return;
+    c.save();
+    roundedRectPath(c, 0, 0, width, height, 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, boxWidth, measure);
+    const placed = layoutLines(lines, { x: padX, y: 0, width: boxWidth, 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));
+    }
+    c.restore();
+}
+function drawText(ctx, property, geo, content) {
+    if (!content)
+        return;
     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));
-        }
+        drawTextInBox(c, property, geo.radius, width, height, content);
     });
     inElementSpace(ctx, geo, (c, width, height) => strokeBorder(c, property, width, height, geo.radius, false));
 }
+/** The runner pads shape text by 4px on each side; match it so the wrap is the same. */
+const SHAPE_TEXT_PADDING = 4;
 function drawImage(ctx, property, geo, image) {
     inElementSpace(ctx, geo, (c, width, height) => {
         fillBackground(c, property, width, height, geo.radius, false);
@@ -233,6 +249,11 @@ function drawShape(ctx, type, property, geo) {
         // Rectangles and ellipses take their outline from the border settings, like
         // on a live page; a new shape stores a 1px grey border with style None.
         strokeBorder(c, property, width, height, geo.radius, ellipse);
+        // Text typed into a shape (a Button preset is a shape with text) is part of
+        // the picture, the same as it is on a live page.
+        const content = typeof property['content'] === 'string' ? property['content'] : '';
+        if (content)
+            drawTextInBox(c, property, geo.radius, width, height, content, SHAPE_TEXT_PADDING);
     });
 }
 /** Loads one image with EXIF orientation applied, or throws a SouvenirError. */
@@ -260,11 +281,33 @@ export async function loadSouvenirImage(url, crossOrigin) {
         image.src = url;
     });
 }
+/**
+ * 整页时用它，给了区域时按区域算。区域外的元件照常留在页面上，由 runner 画。
+ */
+export function regionOf(page, region) {
+    return region ?? { x: 0, y: 0, width: num(page.width), height: num(page.height) };
+}
+/** 出图尺寸：形状跟着区域，长边取 longEdge；不给 longEdge 就按区域原尺寸。 */
+export function outputSize(region, longEdge) {
+    const edge = Number.isFinite(longEdge) && longEdge > 0 ? longEdge : 0;
+    const longest = Math.max(region.width, region.height);
+    const scale = edge > 0 && longest > 0 ? edge / longest : 1;
+    return {
+        width: Math.max(1, Math.round(region.width * scale)),
+        height: Math.max(1, Math.round(region.height * scale)),
+        scale,
+    };
+}
 /** Element ids in draw order: z-index ascending, insertion order for ties. */
-export function drawOrder(page) {
+export function drawOrder(page, region) {
+    const box = region;
     return Object.keys(page.elements ?? {})
         .filter((eid) => SOUVENIR_ELEMENT_TYPES.includes(page.elements[eid]?.type))
         .filter((eid) => !isHidden(page.properties?.[eid] ?? {}))
+        // Controls stay on screen over the picture, so they are not in it
+        .filter((eid) => !isSouvenirInteractive(page.elements[eid]?.type, page.properties?.[eid] ?? {}))
+        // 框外的元件是页面的一部分，不进图
+        .filter((eid) => !box || isInsideRegion(page.properties?.[eid] ?? {}, box))
         .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);
@@ -273,7 +316,8 @@ export function drawOrder(page) {
  * 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) {
+export function pageHasOpaqueBackground(page, region) {
+    const box = regionOf(page, region);
     for (const eid of Object.keys(page.elements ?? {})) {
         if (page.elements[eid]?.type !== 'bg')
             continue;
@@ -281,7 +325,7 @@ export function pageHasOpaqueBackground(page) {
         if (isHidden(property))
             continue;
         const geo = geometryOf(property);
-        const covers = geo.x <= 0 && geo.y <= 0 && geo.width >= page.width && geo.height >= page.height;
+        const covers = geo.x <= box.x && geo.y <= box.y && geo.x + geo.width >= box.x + box.width && geo.y + geo.height >= box.y + box.height;
         if (!covers)
             continue;
         if (geo.opacity < 100 || geo.radius > 0 || geo.rotation)
@@ -291,10 +335,12 @@ export function pageHasOpaqueBackground(page) {
     }
     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)) {
+/** A stable signature for (page, values, region, size): same inputs, same tag, same upload. */
+export function souvenirSignature(page, values, options = {}) {
+    const box = regionOf(page, options.region);
+    const size = outputSize(box, options.longEdge);
+    const parts = [`${box.x},${box.y},${box.width}x${box.height}`, `${size.width}x${size.height}`];
+    for (const eid of drawOrder(page, options.region)) {
         parts.push(eid, page.elements[eid]?.type ?? '', JSON.stringify(page.properties?.[eid] ?? {}), String(values[eid] ?? ''));
     }
     return hashSignature(parts.join('|'));
@@ -310,12 +356,14 @@ 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));
+    const box = regionOf(page, options.region);
+    const size = outputSize(box, options.longEdge);
+    const width = size.width;
+    const height = size.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.`);
+        throw new SouvenirError(width < 1 || height < 1 ? 'bad_size' : 'too_large', `Souvenir image size ${width}x${height} is out of range.`);
     }
-    const order = drawOrder(page);
+    const order = drawOrder(page, options.region);
     // 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) {
@@ -345,6 +393,9 @@ export async function renderSouvenir(page, values = {}, options = {}) {
     const ctx = canvas.getContext('2d');
     if (!ctx)
         throw new SouvenirError('canvas_unavailable', 'Could not get a 2d context.');
+    // 元件坐标是页面坐标：先按出图倍数放大，再把框的左上角移到画布原点。描边宽度与字号
+    // 跟着这一层变换等比放大，所以各元件照页面坐标画就行。
+    ctx.setTransform(size.scale, 0, 0, size.scale, -box.x * size.scale, -box.y * size.scale);
     for (const eid of order) {
         const type = page.elements[eid]?.type ?? '';
         const property = page.properties?.[eid] ?? {};

package/dist/souvenir/types.d.ts

@@ -14,6 +14,19 @@
 /** 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];
+/**
+ * Element types that do something when the participant taps them, or that count
+ * down. On a page the module composes and displays itself, the runner keeps
+ * these on screen over the picture, so the composer must leave them out or the
+ * same thing would appear twice (`qik-sense-runner/src/services/pageRender.ts`
+ * keeps the same list).
+ */
+export declare const SOUVENIR_INTERACTIVE_TYPES: readonly ["timeout", "button", "qr", "link"];
+/**
+ * True when this element is a control rather than part of the picture: an
+ * interactive type, or any element the operator gave a target to.
+ */
+export declare function isSouvenirInteractive(type: string | undefined | null, property?: SouvenirProperty): boolean;
 /** 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. */
@@ -42,12 +55,34 @@ export interface SouvenirPage {
  */
 export type SouvenirValues = Record<string, string | null | undefined>;
 export type SouvenirFormat = 'auto' | 'jpeg' | 'png';
+/**
+ * The part of the page that becomes the image, in the page's own coordinates.
+ *
+ * A module that lays the souvenir out on a page participants see marks a frame
+ * on it: what is inside becomes the picture, what is outside stays a normal
+ * page (PF 2026-09-18). Left out, the whole page is composed.
+ */
+export interface SouvenirRegion {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** 一个元件算不算在框里：按中心点判定（PF 2026-09-18），画的时候再按框裁切。 */
+export declare function isInsideRegion(property: SouvenirProperty, region: SouvenirRegion): boolean;
 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;
+    /** 只合成页面上的这一块。不给就是整页（Live Input 的离屏页走这一条）。 */
+    region?: SouvenirRegion;
+    /**
+     * 出图的长边像素。短边按区域比例算，所以运营改框的形状不必再改这个数。
+     * 不给就按区域的原始尺寸出图。
+     */
+    longEdge?: number;
     /** JPEG quality, 0 to 1. Default 0.9. */
     quality?: number;
     /** File name handed to the upload endpoint. Extension is set from the format. */

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

@@ -1 +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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/souvenir/types.ts"],"names":[],"mappings":"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"}

package/dist/souvenir/types.js

@@ -21,6 +21,38 @@ export const SOUVENIR_ELEMENT_TYPES = [
     'shape-ellipse',
     'shape-line',
 ];
+/**
+ * Element types that do something when the participant taps them, or that count
+ * down. On a page the module composes and displays itself, the runner keeps
+ * these on screen over the picture, so the composer must leave them out or the
+ * same thing would appear twice (`qik-sense-runner/src/services/pageRender.ts`
+ * keeps the same list).
+ */
+export const SOUVENIR_INTERACTIVE_TYPES = ['timeout', 'button', 'qr', 'link'];
+/** Property keys that turn any element into something tappable. */
+const INTERACTIVE_PROPERTIES = ['connection-key', 'url', 'key-code'];
+/**
+ * True when this element is a control rather than part of the picture: an
+ * interactive type, or any element the operator gave a target to.
+ */
+export function isSouvenirInteractive(type, property = {}) {
+    if (SOUVENIR_INTERACTIVE_TYPES.includes(String(type ?? '')))
+        return true;
+    return INTERACTIVE_PROPERTIES.some((key) => String(property?.[key] ?? '').trim() !== '');
+}
+/** 一个元件算不算在框里：按中心点判定（PF 2026-09-18），画的时候再按框裁切。 */
+export function isInsideRegion(property, region) {
+    const num = (value) => {
+        const parsed = typeof value === 'number' ? value : parseFloat(String(value ?? ''));
+        return Number.isFinite(parsed) ? parsed : 0;
+    };
+    const centerX = num(property['x-position']) + num(property['width']) / 2;
+    const centerY = num(property['y-position']) + num(property['height']) / 2;
+    return (centerX >= region.x &&
+        centerX <= region.x + region.width &&
+        centerY >= region.y &&
+        centerY <= region.y + region.height);
+}
 /** Thrown for every refusal the caller is expected to handle and show. */
 export class SouvenirError extends Error {
     code;

package/package.json

@@ -1,64 +1,64 @@
-{
-  "name": "@realnation/builder-shared-sdk",
-  "version": "2.4.1",
-  "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"
-  }
-}
+{
+  "name": "@realnation/builder-shared-sdk",
+  "version": "2.5.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"
+  }
+}