@contrail/documents 1.20.0-alpha.23f6f22 → 1.20.0-alpha.25ac790

package/CHANGELOG.md

@@ -11,6 +11,7 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 - `MaskDefinition` and `MaskShapeKey` on `DocumentElement` — `maskDefinition` records that an image is masked into one of nine preset shapes, with an optional clockwise `rotation`. Its presence changes how `cropDefinition`'s percents are read: element-space (the mask window within the element) instead of the source-image crop they otherwise mean. Anything deriving image geometry must check `hasShapeMask` before treating a crop as a source crop — reading one as the other samples the wrong region of the bitmap.
 - `@contrail/documents/util/mask` — the shared mask model, exported from the package root: the nine shapes as renderer-agnostic cubic path segments (`getMaskShapeSegments`), `rotatedRectAABB` for the bounds a tilted shape actually occupies, `rotatePoint`, the mask-rect/percent conversions, and `MASK_SHAPE_PRESET_GEOMETRY` mapping each shape to its OOXML preset so exporters and the canvas cannot drift apart. Segments are cubic-only because cubics survive affine maps exactly, letting each consumer render them however it draws — `Path2D` in a browser, preset geometry in pptx.
+- `getMaskBakeGeometry`, `getMaskBakeLayout` and `maskShapeSegmentsToSvgPath` — the bake inputs a consumer needs to flatten a mask into a bitmap, and an SVG serializer for renderers that go through SVG rather than a canvas path. The layout scales to the source bitmap's own resolution rather than the element's on-board size, so a shrunk image does not bake at reduced detail, and re-bases a rotated mask onto its own bounding box. Only the rasterizer stays per-consumer: `Path2D` in a browser, an SVG composite in a service.
 
 ## [1.18.0] - 2026-09-10
 

package/lib/util/mask/index.d.ts

@@ -2,3 +2,4 @@ export * from './mask-shape-geometry';
 export * from './rotation-math';
 export * from './shape-mask-element';
 export * from './mask-preset-geometry';
+export * from './mask-bake-layout';

package/lib/util/mask/index.js

@@ -18,3 +18,4 @@ __exportStar(require("./mask-shape-geometry"), exports);
 __exportStar(require("./rotation-math"), exports);
 __exportStar(require("./shape-mask-element"), exports);
 __exportStar(require("./mask-preset-geometry"), exports);
+__exportStar(require("./mask-bake-layout"), exports);

package/lib/util/mask/mask-bake-layout.d.ts

@@ -0,0 +1,17 @@
+import { DocumentElement, SizeDefinition } from '../../types';
+import { MaskRect, MaskShapeKey } from './mask-shape-geometry';
+export declare const MASK_BAKE_MAX_SIDE = 4096;
+export interface MaskBakeGeometry {
+    shape: MaskShapeKey;
+    rotation: number;
+    maskRect: MaskRect;
+    imageRect: MaskRect;
+}
+export interface MaskBakeLayout {
+    size: SizeDefinition;
+    scale: number;
+    maskRect: MaskRect;
+    imageRect: MaskRect;
+}
+export declare function getMaskBakeGeometry(element: DocumentElement): MaskBakeGeometry | null;
+export declare function getMaskBakeLayout(geometry: MaskBakeGeometry, sourceImageSize: SizeDefinition): MaskBakeLayout | null;

package/lib/util/mask/mask-bake-layout.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MASK_BAKE_MAX_SIDE = void 0;
+exports.getMaskBakeGeometry = getMaskBakeGeometry;
+exports.getMaskBakeLayout = getMaskBakeLayout;
+const mask_shape_geometry_1 = require("./mask-shape-geometry");
+const shape_mask_element_1 = require("./shape-mask-element");
+exports.MASK_BAKE_MAX_SIDE = 4096;
+function getMaskBakeGeometry(element) {
+    var _a, _b;
+    const shape = (0, shape_mask_element_1.getShapeMaskKey)(element);
+    if (!shape || !(0, shape_mask_element_1.hasShapeMask)(element) || !((_a = element.size) === null || _a === void 0 ? void 0 : _a.width) || !((_b = element.size) === null || _b === void 0 ? void 0 : _b.height)) {
+        return null;
+    }
+    const imageRect = element.imageSize && element.imagePosition
+        ? {
+            x: element.imagePosition.x,
+            y: element.imagePosition.y,
+            width: element.imageSize.width,
+            height: element.imageSize.height,
+        }
+        : { x: 0, y: 0, width: element.size.width, height: element.size.height };
+    return {
+        shape,
+        rotation: (0, shape_mask_element_1.getShapeMaskRotation)(element),
+        maskRect: (0, shape_mask_element_1.cropDefinitionToMaskRect)(element.cropDefinition, element.size),
+        imageRect,
+    };
+}
+function scaleRect(rect, scale, originX, originY) {
+    return {
+        x: (rect.x - originX) * scale,
+        y: (rect.y - originY) * scale,
+        width: rect.width * scale,
+        height: rect.height * scale,
+    };
+}
+function getMaskBakeLayout(geometry, sourceImageSize) {
+    const { maskRect, imageRect, rotation } = geometry;
+    if (!imageRect.width || !imageRect.height || !(sourceImageSize === null || sourceImageSize === void 0 ? void 0 : sourceImageSize.width) || !maskRect.width || !maskRect.height) {
+        return null;
+    }
+    const extent = rotation ? (0, mask_shape_geometry_1.rotatedRectAABB)(maskRect, rotation) : Object.assign({}, maskRect);
+    const nativeScale = sourceImageSize.width / imageRect.width;
+    const longestSide = Math.max(extent.width, extent.height) * nativeScale;
+    const scale = longestSide > exports.MASK_BAKE_MAX_SIDE ? (exports.MASK_BAKE_MAX_SIDE / longestSide) * nativeScale : nativeScale;
+    return {
+        size: {
+            width: Math.ceil(extent.width * scale),
+            height: Math.ceil(extent.height * scale),
+        },
+        scale,
+        maskRect: scaleRect(maskRect, scale, extent.x, extent.y),
+        imageRect: scaleRect(imageRect, scale, extent.x, extent.y),
+    };
+}

package/lib/util/mask/mask-shape-geometry.d.ts

@@ -24,3 +24,4 @@ export type PathSegment = {
 };
 export declare function getMaskShapeSegments(shape: MaskShapeKey, rect: MaskRect, rotationDeg?: number): PathSegment[];
 export declare function rotatedRectAABB(rect: MaskRect, rotationDeg: number): MaskRect;
+export declare function maskShapeSegmentsToSvgPath(segments: PathSegment[]): string;

package/lib/util/mask/mask-shape-geometry.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MASK_SHAPE_KEYS = void 0;
 exports.getMaskShapeSegments = getMaskShapeSegments;
 exports.rotatedRectAABB = rotatedRectAABB;
+exports.maskShapeSegmentsToSvgPath = maskShapeSegmentsToSvgPath;
 const rotation_math_1 = require("./rotation-math");
 exports.MASK_SHAPE_KEYS = [
     'circle',
@@ -143,12 +144,28 @@ function rotatedRectAABB(rect, rotationDeg) {
         { x: rect.x + rect.width, y: rect.y },
         { x: rect.x + rect.width, y: rect.y + rect.height },
         { x: rect.x, y: rect.y + rect.height },
-    ].map(p => (0, rotation_math_1.rotatePoint)(p, rotationDeg, { x: cx, y: cy }));
-    const xs = corners.map(p => p.x);
-    const ys = corners.map(p => p.y);
+    ].map((p) => (0, rotation_math_1.rotatePoint)(p, rotationDeg, { x: cx, y: cy }));
+    const xs = corners.map((p) => p.x);
+    const ys = corners.map((p) => p.y);
     const minX = Math.min(...xs);
     const maxX = Math.max(...xs);
     const minY = Math.min(...ys);
     const maxY = Math.max(...ys);
     return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
 }
+function maskShapeSegmentsToSvgPath(segments) {
+    return segments
+        .map((segment) => {
+        if (segment.op === 'move') {
+            return `M ${segment.x} ${segment.y}`;
+        }
+        if (segment.op === 'line') {
+            return `L ${segment.x} ${segment.y}`;
+        }
+        if (segment.op === 'cubic') {
+            return `C ${segment.c1x} ${segment.c1y} ${segment.c2x} ${segment.c2y} ${segment.x} ${segment.y}`;
+        }
+        return 'Z';
+    })
+        .join(' ');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrail/documents",
-  "version": "1.20.0-alpha.23f6f22",
+  "version": "1.20.0-alpha.25ac790",
   "description": "Documents library for contrail platform",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",