@contrail/documents 2.1.0-alpha.c922865 → 2.1.0

package/CHANGELOG.md

@@ -5,31 +5,21 @@ All notable changes to `@contrail/documents` are documented here.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [2.1.0] - 2026-09-09
+## [1.19.0] - 2026-09-11
 
 ### Added
 
-- `DocumentContainerService.buildIndex` and `DocumentContainerIndex` — which containers hold which
-  elements, for one document, resolved once and read back by lookup. A container is a frame or a
-  section, described by a `ContainerKind` carrying `elementType`, `nests` and `layer`. An element
-  belongs to the container whose box covers its measured centre and which is drawn below it.
-  Nesting gives a path with one container per depth, the later-drawn one winning where two cross.
-  A container is only ever content of a kind layered behind it, so a frame belongs to a section and
-  a section never to a frame. Shapes wider and taller than the container, and groups holding it,
-  are excluded.
-- `SECTION_ELEMENT_TYPE`, `FRAME_ELEMENT_TYPE` and `SHAPE_ELEMENT_TYPES` in
-  `document-element-constants`, so the rule above has one definition rather than one per app.
+- `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`, and the mask-rect/percent conversions, 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, an SVG composite in a service.
+- `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.
+- `hasShapeMask` is a type guard and the complete discriminator: it requires a shape key the renderer knows and all four crop percents, so an origin of `0` passes while a missing origin (previously multiplied into `NaN` by `cropDefinitionToMaskRect`) and an unknown shape (previously thrown on by `getMaskShapeSegments`) are rejected up front. The true branch narrows the percents to numbers.
 
-### Fixed
-
-- `DynamicTextUtil.calculateSize` threw on an element that reached it without a `size`, which on
-  the server failed the read for the whole document. It now measures from a zero size instead.
+## [1.18.0] - 2026-09-10
 
-### Changed
+### Added
 
-- `DocumentElementFactory.getBoundingClientRect` multiplies the measured size by the element's
-  `scale`. Scale grows an element from its top-left, so it widens the box and moves the centre; a
-  scaled element previously measured at its unscaled size and could resolve to the wrong container.
+- `DocumentChange.gestureId?: string` — optional marker a producer sets to correlate the
+  actions of one user gesture across a batch.
 
 ## [1.17.0] - 2026-09-09
 

package/lib/document-element-constants.d.ts

@@ -3,6 +3,3 @@ export declare const ANNOTATION_PADDING_Y = 8;
 export declare const COLOR_PADDING = 5;
 export declare const COLOR_FONT_SIZE = 8;
 export declare const COLOR_WIDTH = 140;
-export declare const SECTION_ELEMENT_TYPE = "section";
-export declare const FRAME_ELEMENT_TYPE = "frame";
-export declare const SHAPE_ELEMENT_TYPES: string[];

package/lib/document-element-constants.js

@@ -1,29 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SHAPE_ELEMENT_TYPES = exports.FRAME_ELEMENT_TYPE = exports.SECTION_ELEMENT_TYPE = exports.COLOR_WIDTH = exports.COLOR_FONT_SIZE = exports.COLOR_PADDING = exports.ANNOTATION_PADDING_Y = exports.ANNOTATION_IMG_SIZE = void 0;
+exports.COLOR_WIDTH = exports.COLOR_FONT_SIZE = exports.COLOR_PADDING = exports.ANNOTATION_PADDING_Y = exports.ANNOTATION_IMG_SIZE = void 0;
 exports.ANNOTATION_IMG_SIZE = 15;
 exports.ANNOTATION_PADDING_Y = 8;
 exports.COLOR_PADDING = 5;
 exports.COLOR_FONT_SIZE = 8;
 exports.COLOR_WIDTH = 140;
-exports.SECTION_ELEMENT_TYPE = 'section';
-exports.FRAME_ELEMENT_TYPE = 'frame';
-exports.SHAPE_ELEMENT_TYPES = [
-    'text',
-    'line',
-    'arrow',
-    'circle',
-    'rectangle',
-    'round_rectangle',
-    'triangle',
-    'diamond',
-    'star',
-    'heart',
-    'double_arrow',
-    'right_arrow',
-    'rhombus',
-    'cloud',
-    'callout',
-    'draw_frame',
-    'draw_section',
-];

package/lib/document-element-factory.js

@@ -207,14 +207,13 @@ class DocumentElementFactory {
         return ['rectangle', 'circle'].indexOf(element === null || element === void 0 ? void 0 : element.type) !== -1 && ((_a = element === null || element === void 0 ? void 0 : element.elementIds) === null || _a === void 0 ? void 0 : _a.length) > 0;
     }
     static getBoundingClientRect(documentElement, startElement, endElement) {
-        var _a, _b, _c, _d;
         const { x, y } = this.getPosition(documentElement, startElement, endElement);
         const { width, height } = this.getSize(documentElement, startElement, endElement);
         return {
             x,
             y,
-            width: width * ((_b = (_a = documentElement.scale) === null || _a === void 0 ? void 0 : _a.x) !== null && _b !== void 0 ? _b : 1),
-            height: height * ((_d = (_c = documentElement.scale) === null || _c === void 0 ? void 0 : _c.y) !== null && _d !== void 0 ? _d : 1),
+            width,
+            height,
         };
     }
     static getPosition(documentElement, startElement, endElement) {

package/lib/index.d.ts

@@ -12,8 +12,5 @@ export * from './document-element-constants';
 export * from './util/curved-line/point';
 export * from './util/curved-line/curved-line';
 export * from './util/callout/callout';
+export * from './util/mask';
 export * from './document-frame.service';
-export * from './containers/container-kind';
-export * from './containers/document-container';
-export * from './containers/document-container-index';
-export * from './containers/document-container.service';

package/lib/index.js

@@ -28,8 +28,5 @@ __exportStar(require("./document-element-constants"), exports);
 __exportStar(require("./util/curved-line/point"), exports);
 __exportStar(require("./util/curved-line/curved-line"), exports);
 __exportStar(require("./util/callout/callout"), exports);
+__exportStar(require("./util/mask"), exports);
 __exportStar(require("./document-frame.service"), exports);
-__exportStar(require("./containers/container-kind"), exports);
-__exportStar(require("./containers/document-container"), exports);
-__exportStar(require("./containers/document-container-index"), exports);
-__exportStar(require("./containers/document-container.service"), exports);

package/lib/types/common.d.ts

@@ -74,6 +74,11 @@ export interface LineDefinition {
     markerEnd?: string;
     lineType?: LineType;
 }
+export type MaskShapeKey = 'circle' | 'square' | 'rounded' | 'triangle' | 'diamond' | 'parallelogram' | 'star' | 'heart' | 'cloud';
+export interface MaskDefinition {
+    shape: MaskShapeKey;
+    rotation?: number;
+}
 export interface CropDefinition {
     x1?: number;
     x2?: number;

package/lib/types/document-change.d.ts

@@ -18,4 +18,5 @@ export interface DocumentChange {
     backingAssortmentItemData?: any;
     targetSortIndex?: number;
     skipUndo?: boolean;
+    gestureId?: string;
 }

package/lib/types/document-element.d.ts

@@ -1,5 +1,5 @@
 import { PropertyLevel } from '@contrail/types';
-import { CropDefinition, LineDefinition, PositionDefinition, RotationDefinition, SizeDefinition } from './common';
+import { CropDefinition, LineDefinition, MaskDefinition, PositionDefinition, RotationDefinition, SizeDefinition } from './common';
 import { Document } from './document';
 import { ScaleTransformation } from './element-transformation';
 export interface AlternateUrls {
@@ -32,6 +32,7 @@ export interface DocumentElement extends Document {
     annotations?: any;
     isLocked?: boolean;
     cropDefinition?: CropDefinition;
+    maskDefinition?: MaskDefinition;
     embedInfo?: any;
     isHidden?: boolean;
     elementIds?: Array<string>;

package/lib/util/dynamic-text/dynamic-text-util.js

@@ -150,12 +150,12 @@ class DynamicTextUtil {
         return text;
     }
     static calculateSize(dynamicTextElement, entityType, text) {
-        var _a, _b, _c, _d, _e;
-        let size = (_a = dynamicTextElement.size) !== null && _a !== void 0 ? _a : { width: 0, height: 0 };
-        const fontFamily = (_b = document_util_1.DocumentStyleUtil.getFirstFontFamily(dynamicTextElement === null || dynamicTextElement === void 0 ? void 0 : dynamicTextElement.text)) !== null && _b !== void 0 ? _b : document_util_1.DEFAULT_TEXT_FONT_FAMILY;
-        const fontSize = (_e = (dynamicTextElement.isTextTool
-            ? (_d = (_c = dynamicTextElement.style) === null || _c === void 0 ? void 0 : _c.font) === null || _d === void 0 ? void 0 : _d.size
-            : document_util_1.DocumentStyleUtil.getFirstFontSize(dynamicTextElement === null || dynamicTextElement === void 0 ? void 0 : dynamicTextElement.text, true))) !== null && _e !== void 0 ? _e : document_util_1.DEFAULT_TEXT_FONT_SIZE;
+        var _a, _b, _c, _d;
+        let size = dynamicTextElement.size;
+        const fontFamily = (_a = document_util_1.DocumentStyleUtil.getFirstFontFamily(dynamicTextElement === null || dynamicTextElement === void 0 ? void 0 : dynamicTextElement.text)) !== null && _a !== void 0 ? _a : document_util_1.DEFAULT_TEXT_FONT_FAMILY;
+        const fontSize = (_d = (dynamicTextElement.isTextTool
+            ? (_c = (_b = dynamicTextElement.style) === null || _b === void 0 ? void 0 : _b.font) === null || _c === void 0 ? void 0 : _c.size
+            : document_util_1.DocumentStyleUtil.getFirstFontSize(dynamicTextElement === null || dynamicTextElement === void 0 ? void 0 : dynamicTextElement.text, true))) !== null && _d !== void 0 ? _d : document_util_1.DEFAULT_TEXT_FONT_SIZE;
         const fontSizePx = document_util_1.DocumentStyleUtil.toPx(fontSize, 4);
         const padding = dynamicTextElement.isTextTool ? document_util_1.TEXT_TOOL_PADDING : document_util_1.TEXT_BOX_PADDING;
         const bold = document_util_1.DocumentStyleUtil.isBold(dynamicTextElement === null || dynamicTextElement === void 0 ? void 0 : dynamicTextElement.text, fontFamily);
@@ -169,7 +169,7 @@ class DynamicTextUtil {
             italic,
         };
         if (!dynamicTextElement.isTextTool) {
-            measureTextSettings.width = size.width - padding * 2;
+            measureTextSettings.width = dynamicTextElement.size.width - padding * 2;
         }
         try {
             const dimensions = document_util_1.DocumentTextUtil.measureText(text, measureTextSettings);

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

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

package/lib/util/mask/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./mask-shape-geometry"), exports);
+__exportStar(require("./rotation-math"), exports);
+__exportStar(require("./shape-mask-element"), 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

@@ -0,0 +1,27 @@
+import { MaskShapeKey } from '../../types';
+export { MaskShapeKey };
+export declare const MASK_SHAPE_KEYS: readonly MaskShapeKey[];
+export interface MaskRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export type PathSegment = {
+    op: 'move' | 'line';
+    x: number;
+    y: number;
+} | {
+    op: 'cubic';
+    c1x: number;
+    c1y: number;
+    c2x: number;
+    c2y: number;
+    x: number;
+    y: number;
+} | {
+    op: 'close';
+};
+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

@@ -0,0 +1,171 @@
+"use strict";
+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',
+    'square',
+    'rounded',
+    'triangle',
+    'diamond',
+    'parallelogram',
+    'star',
+    'heart',
+    'cloud',
+];
+const K = 0.5522847498;
+function polygon(points) {
+    const [first, ...rest] = points;
+    return [
+        { op: 'move', x: first[0], y: first[1] },
+        ...rest.map(([x, y]) => ({ op: 'line', x, y })),
+        { op: 'close' },
+    ];
+}
+function ellipse(cx, cy, rx, ry) {
+    return [
+        { op: 'move', x: cx + rx, y: cy },
+        { op: 'cubic', c1x: cx + rx, c1y: cy + K * ry, c2x: cx + K * rx, c2y: cy + ry, x: cx, y: cy + ry },
+        { op: 'cubic', c1x: cx - K * rx, c1y: cy + ry, c2x: cx - rx, c2y: cy + K * ry, x: cx - rx, y: cy },
+        { op: 'cubic', c1x: cx - rx, c1y: cy - K * ry, c2x: cx - K * rx, c2y: cy - ry, x: cx, y: cy - ry },
+        { op: 'cubic', c1x: cx + K * rx, c1y: cy - ry, c2x: cx + rx, c2y: cy - K * ry, x: cx + rx, y: cy },
+        { op: 'close' },
+    ];
+}
+function roundedRect(x, y, w, h, r) {
+    const x2 = x + w;
+    const y2 = y + h;
+    return [
+        { op: 'move', x: x + r, y },
+        { op: 'line', x: x2 - r, y },
+        { op: 'cubic', c1x: x2 - r + K * r, c1y: y, c2x: x2, c2y: y + r - K * r, x: x2, y: y + r },
+        { op: 'line', x: x2, y: y2 - r },
+        { op: 'cubic', c1x: x2, c1y: y2 - r + K * r, c2x: x2 - r + K * r, c2y: y2, x: x2 - r, y: y2 },
+        { op: 'line', x: x + r, y: y2 },
+        { op: 'cubic', c1x: x + r - K * r, c1y: y2, c2x: x, c2y: y2 - r + K * r, x, y: y2 - r },
+        { op: 'line', x, y: y + r },
+        { op: 'cubic', c1x: x, c1y: y + r - K * r, c2x: x + r - K * r, c2y: y, x: x + r, y },
+        { op: 'close' },
+    ];
+}
+const UNIT_SEGMENTS = {
+    circle: ellipse(50, 50, 49, 49),
+    square: polygon([
+        [1, 1],
+        [99, 1],
+        [99, 99],
+        [1, 99],
+    ]),
+    rounded: roundedRect(1, 1, 98, 98, 16),
+    triangle: polygon([
+        [50, 3],
+        [97, 96],
+        [3, 96],
+    ]),
+    diamond: polygon([
+        [50, 2],
+        [98, 50],
+        [50, 98],
+        [2, 50],
+    ]),
+    parallelogram: polygon([
+        [27, 12],
+        [98, 12],
+        [73, 88],
+        [2, 88],
+    ]),
+    star: polygon([
+        [50, 3],
+        [61, 37],
+        [97, 37],
+        [68, 59],
+        [79, 95],
+        [50, 73],
+        [21, 95],
+        [32, 59],
+        [3, 37],
+        [39, 37],
+    ]),
+    heart: [
+        { op: 'move', x: 50, y: 90 },
+        { op: 'cubic', c1x: 6, c1y: 58, c2x: 10, c2y: 20, x: 32, y: 18 },
+        { op: 'cubic', c1x: 44, c1y: 17, c2x: 50, c2y: 27, x: 50, y: 34 },
+        { op: 'cubic', c1x: 50, c1y: 27, c2x: 56, c2y: 17, x: 68, y: 18 },
+        { op: 'cubic', c1x: 90, c1y: 20, c2x: 94, c2y: 58, x: 50, y: 90 },
+        { op: 'close' },
+    ],
+    cloud: [
+        { op: 'move', x: 30, y: 80 },
+        { op: 'cubic', c1x: 13, c1y: 80, c2x: 6, c2y: 66, x: 16, y: 56 },
+        { op: 'cubic', c1x: 11, c1y: 42, c2x: 27, c2y: 34, x: 37, y: 42 },
+        { op: 'cubic', c1x: 41, c1y: 24, c2x: 66, c2y: 24, x: 70, y: 42 },
+        { op: 'cubic', c1x: 86, c1y: 38, c2x: 96, c2y: 56, x: 84, y: 68 },
+        { op: 'cubic', c1x: 92, c1y: 78, c2x: 82, c2y: 88, x: 70, y: 84 },
+        { op: 'close' },
+    ],
+};
+function getMaskShapeSegments(shape, rect, rotationDeg = 0) {
+    const unit = UNIT_SEGMENTS[shape];
+    if (!unit) {
+        throw new Error(`Unknown mask shape: ${shape}`);
+    }
+    const sx = rect.width / 100;
+    const sy = rect.height / 100;
+    const tx = (x) => rect.x + x * sx;
+    const ty = (y) => rect.y + y * sy;
+    const cx = rect.x + rect.width * 0.5;
+    const cy = rect.y + rect.height * 0.5;
+    const rotate = (x, y) => rotationDeg ? (0, rotation_math_1.rotatePoint)({ x, y }, rotationDeg, { x: cx, y: cy }) : { x, y };
+    return unit.map((s) => {
+        if (s.op === 'close') {
+            return { op: 'close' };
+        }
+        if (s.op === 'cubic') {
+            const c1 = rotate(tx(s.c1x), ty(s.c1y));
+            const c2 = rotate(tx(s.c2x), ty(s.c2y));
+            const p = rotate(tx(s.x), ty(s.y));
+            return { op: 'cubic', c1x: c1.x, c1y: c1.y, c2x: c2.x, c2y: c2.y, x: p.x, y: p.y };
+        }
+        const p = rotate(tx(s.x), ty(s.y));
+        return { op: s.op, x: p.x, y: p.y };
+    });
+}
+function rotatedRectAABB(rect, rotationDeg) {
+    if (!rotationDeg) {
+        return Object.assign({}, rect);
+    }
+    const cx = rect.x + rect.width * 0.5;
+    const cy = rect.y + rect.height * 0.5;
+    const corners = [
+        { x: rect.x, y: rect.y },
+        { 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);
+    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/lib/util/mask/rotation-math.d.ts

@@ -0,0 +1,2 @@
+import { PositionDefinition } from '../../types';
+export declare function rotatePoint(point: PositionDefinition, angleDeg: number, pivot?: PositionDefinition): PositionDefinition;

package/lib/util/mask/rotation-math.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rotatePoint = rotatePoint;
+function rotatePoint(point, angleDeg, pivot = { x: 0, y: 0 }) {
+    const theta = (angleDeg * Math.PI) / 180;
+    const cos = Math.cos(theta);
+    const sin = Math.sin(theta);
+    const dx = point.x - pivot.x;
+    const dy = point.y - pivot.y;
+    return {
+        x: dx * cos - dy * sin + pivot.x,
+        y: dx * sin + dy * cos + pivot.y,
+    };
+}

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

@@ -0,0 +1,23 @@
+import { CropDefinition, DocumentElement, MaskDefinition, SizeDefinition } from '../../types';
+import { MaskRect, MaskShapeKey } from './mask-shape-geometry';
+export type MaskCropDefinition = CropDefinition & Required<Pick<CropDefinition, 'x1Percent' | 'y1Percent' | 'widthPercent' | 'heightPercent'>>;
+export type ShapeMaskedElement = DocumentElement & {
+    maskDefinition: MaskDefinition & {
+        shape: MaskShapeKey;
+    };
+    cropDefinition: MaskCropDefinition;
+};
+export declare function hasShapeMask(element: DocumentElement): element is ShapeMaskedElement;
+export declare function getShapeMaskKey(element: DocumentElement): MaskShapeKey | null;
+export declare function getShapeMaskRotation(element: DocumentElement): number;
+export declare function normalizeMaskRotation(rotation: number): number;
+export declare function isShapeMaskable(element: DocumentElement): boolean;
+export declare function getDefaultShapeMaskCrop(size: SizeDefinition): CropDefinition;
+export declare function cropDefinitionToMaskRect(crop: CropDefinition, size: SizeDefinition): MaskRect;
+export declare function maskRectToCropDefinition(rect: MaskRect, size: SizeDefinition): CropDefinition;
+export declare const SHAPE_MASK_CLEAR_FIELDS: {
+    readonly maskDefinition: any;
+    readonly cropDefinition: any;
+    readonly imageSize: any;
+    readonly imagePosition: any;
+};

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

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SHAPE_MASK_CLEAR_FIELDS = void 0;
+exports.hasShapeMask = hasShapeMask;
+exports.getShapeMaskKey = getShapeMaskKey;
+exports.getShapeMaskRotation = getShapeMaskRotation;
+exports.normalizeMaskRotation = normalizeMaskRotation;
+exports.isShapeMaskable = isShapeMaskable;
+exports.getDefaultShapeMaskCrop = getDefaultShapeMaskCrop;
+exports.cropDefinitionToMaskRect = cropDefinitionToMaskRect;
+exports.maskRectToCropDefinition = maskRectToCropDefinition;
+const mask_shape_geometry_1 = require("./mask-shape-geometry");
+const DEFAULT_MASK_FRACTION = 0.72;
+function hasShapeMask(element) {
+    var _a;
+    const shape = (_a = element === null || element === void 0 ? void 0 : element.maskDefinition) === null || _a === void 0 ? void 0 : _a.shape;
+    if (!shape || !mask_shape_geometry_1.MASK_SHAPE_KEYS.includes(shape)) {
+        return false;
+    }
+    const crop = element === null || element === void 0 ? void 0 : element.cropDefinition;
+    return (Number.isFinite(crop === null || crop === void 0 ? void 0 : crop.x1Percent) &&
+        Number.isFinite(crop === null || crop === void 0 ? void 0 : crop.y1Percent) &&
+        crop.widthPercent > 0 &&
+        crop.heightPercent > 0);
+}
+function getShapeMaskKey(element) {
+    var _a, _b;
+    return (_b = (_a = element === null || element === void 0 ? void 0 : element.maskDefinition) === null || _a === void 0 ? void 0 : _a.shape) !== null && _b !== void 0 ? _b : null;
+}
+function getShapeMaskRotation(element) {
+    var _a, _b;
+    return (_b = (_a = element === null || element === void 0 ? void 0 : element.maskDefinition) === null || _a === void 0 ? void 0 : _a.rotation) !== null && _b !== void 0 ? _b : 0;
+}
+function normalizeMaskRotation(rotation) {
+    return ((rotation % 360) + 360) % 360;
+}
+function isShapeMaskable(element) {
+    return (element === null || element === void 0 ? void 0 : element.type) === 'image';
+}
+function getDefaultShapeMaskCrop(size) {
+    const side = Math.min(size.width, size.height) * DEFAULT_MASK_FRACTION;
+    return {
+        x1Percent: ((size.width - side) * 0.5) / size.width,
+        y1Percent: ((size.height - side) * 0.5) / size.height,
+        widthPercent: side / size.width,
+        heightPercent: side / size.height,
+    };
+}
+function cropDefinitionToMaskRect(crop, size) {
+    return {
+        x: crop.x1Percent * size.width,
+        y: crop.y1Percent * size.height,
+        width: crop.widthPercent * size.width,
+        height: crop.heightPercent * size.height,
+    };
+}
+function maskRectToCropDefinition(rect, size) {
+    return {
+        x1Percent: rect.x / size.width,
+        y1Percent: rect.y / size.height,
+        widthPercent: rect.width / size.width,
+        heightPercent: rect.height / size.height,
+    };
+}
+exports.SHAPE_MASK_CLEAR_FIELDS = {
+    maskDefinition: null,
+    cropDefinition: null,
+    imageSize: null,
+    imagePosition: null,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrail/documents",
-  "version": "2.1.0-alpha.c922865",
+  "version": "2.1.0",
   "description": "Documents library for contrail platform",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -22,7 +22,7 @@
     "tslint": "^5.11.0",
     "tslint-config-prettier": "^1.18.0",
     "typescript": "^5.8.3",
-    "@contrail/telemetry": "^2.0.0"
+    "@contrail/telemetry": "^3.0.0"
   },
   "jest": {
     "moduleFileExtensions": [
@@ -39,14 +39,17 @@
     "testEnvironment": "node"
   },
   "dependencies": {
-    "@contrail/actions": "^1.0.18",
-    "@contrail/document-table": "^1.2.3",
-    "@contrail/document-util": "^1.2.0",
-    "@contrail/types": "^3.4.0",
+    "@contrail/actions": "^2.0.0",
+    "@contrail/document-table": "^2.0.0",
+    "@contrail/document-util": "^2.0.0",
+    "@contrail/types": "^4.0.0",
     "fractional-indexing": "^2.1.0",
     "reflect-metadata": "^0.1.13"
   },
   "peerDependencies": {
-    "@contrail/telemetry": "^2.0.0"
+    "@contrail/telemetry": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=24"
   }
 }

package/lib/containers/container-kind.d.ts

@@ -1,10 +0,0 @@
-import { FRAME_ELEMENT_TYPE, SECTION_ELEMENT_TYPE } from '../document-element-constants';
-export type ContainerElementType = typeof FRAME_ELEMENT_TYPE | typeof SECTION_ELEMENT_TYPE;
-export interface ContainerKind {
-    elementType: ContainerElementType;
-    nests: boolean;
-    layer: number;
-}
-export declare const SECTION_KIND: ContainerKind;
-export declare const FRAME_KIND: ContainerKind;
-export declare const CONTAINER_KINDS: ContainerKind[];

package/lib/containers/container-kind.js

@@ -1,7 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CONTAINER_KINDS = exports.FRAME_KIND = exports.SECTION_KIND = void 0;
-const document_element_constants_1 = require("../document-element-constants");
-exports.SECTION_KIND = { elementType: document_element_constants_1.SECTION_ELEMENT_TYPE, nests: true, layer: 0 };
-exports.FRAME_KIND = { elementType: document_element_constants_1.FRAME_ELEMENT_TYPE, nests: false, layer: 1 };
-exports.CONTAINER_KINDS = [exports.SECTION_KIND, exports.FRAME_KIND];

package/lib/containers/document-container-index.d.ts

@@ -1,23 +0,0 @@
-import { DocumentElement, PositionDefinition } from '../types';
-import { ContainerElementType } from './container-kind';
-import { DocumentContainer } from './document-container';
-export declare class DocumentContainerIndex {
-    private readonly data;
-    constructor(data: {
-        documentElementsById: Map<string, DocumentElement>;
-        containersById: Map<string, DocumentContainer>;
-        containerPathsByDocumentElementId: Map<string, Map<string, string[]>>;
-        memberIdsByContainerId: Map<string, string[]>;
-        containerIdsByElementType: Map<string, string[]>;
-    });
-    getContainer(containerId: string): DocumentContainer | null;
-    containersOf(documentElementId: string, elementType: ContainerElementType): DocumentContainer[];
-    containerIdsOf(documentElementId: string, elementType: ContainerElementType): string[];
-    innermostContainerIdOf(documentElementId: string, elementType: ContainerElementType): string | null;
-    memberIdsOf(containerId: string): string[];
-    memberDocumentElementsOf(containerId: string): DocumentElement[];
-    containerPathAtPoint(point: PositionDefinition, elementType: ContainerElementType): string[];
-    maxDepth(elementType: ContainerElementType): number;
-    private containersOfType;
-    private containerPath;
-}

package/lib/containers/document-container-index.js

@@ -1,52 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DocumentContainerIndex = void 0;
-const document_container_1 = require("./document-container");
-class DocumentContainerIndex {
-    constructor(data) {
-        this.data = data;
-    }
-    getContainer(containerId) {
-        var _a;
-        return (_a = this.data.containersById.get(containerId)) !== null && _a !== void 0 ? _a : null;
-    }
-    containersOf(documentElementId, elementType) {
-        return this.containerIdsOf(documentElementId, elementType)
-            .map((containerId) => this.data.containersById.get(containerId))
-            .filter(Boolean);
-    }
-    containerIdsOf(documentElementId, elementType) {
-        return this.containerPath(documentElementId, elementType);
-    }
-    innermostContainerIdOf(documentElementId, elementType) {
-        const path = this.containerPath(documentElementId, elementType);
-        return path.length ? path[path.length - 1] : null;
-    }
-    memberIdsOf(containerId) {
-        var _a;
-        return (_a = this.data.memberIdsByContainerId.get(containerId)) !== null && _a !== void 0 ? _a : [];
-    }
-    memberDocumentElementsOf(containerId) {
-        return this.memberIdsOf(containerId)
-            .map((memberId) => this.data.documentElementsById.get(memberId))
-            .filter(Boolean);
-    }
-    containerPathAtPoint(point, elementType) {
-        const covering = this.containersOfType(elementType).filter((container) => (0, document_container_1.containsPoint)(container.box, point));
-        return (0, document_container_1.topmostPerDepth)(covering).map((container) => container.id);
-    }
-    maxDepth(elementType) {
-        return this.containersOfType(elementType).reduce((max, container) => Math.max(max, container.depth + 1), 0);
-    }
-    containersOfType(elementType) {
-        var _a;
-        return ((_a = this.data.containerIdsByElementType.get(elementType)) !== null && _a !== void 0 ? _a : [])
-            .map((containerId) => this.data.containersById.get(containerId))
-            .filter(Boolean);
-    }
-    containerPath(documentElementId, elementType) {
-        var _a, _b;
-        return (_b = (_a = this.data.containerPathsByDocumentElementId.get(documentElementId)) === null || _a === void 0 ? void 0 : _a.get(elementType)) !== null && _b !== void 0 ? _b : [];
-    }
-}
-exports.DocumentContainerIndex = DocumentContainerIndex;

package/lib/containers/document-container.d.ts

@@ -1,22 +0,0 @@
-import { CoordinateBox, DocumentElement, PositionDefinition } from '../types';
-import { ContainerKind } from './container-kind';
-export interface DocumentContainer {
-    id: string;
-    kind: ContainerKind;
-    name: string;
-    documentElement: DocumentElement;
-    box: CoordinateBox;
-    depth: number;
-    drawOrder: number;
-}
-export interface MeasuredDocumentElement {
-    documentElement: DocumentElement;
-    box: CoordinateBox | null;
-    drawOrder: number;
-}
-export declare function toCoordinateBox(x: number, y: number, width: number, height: number): CoordinateBox;
-export declare function centerOf(box: CoordinateBox): PositionDefinition;
-export declare function containsPoint(box: CoordinateBox, point: PositionDefinition): boolean;
-export declare function encloses(outer: CoordinateBox, inner: CoordinateBox): boolean;
-export declare function isWiderAndTallerThan(box: CoordinateBox, other: CoordinateBox): boolean;
-export declare function topmostPerDepth(containers: DocumentContainer[]): DocumentContainer[];

package/lib/containers/document-container.js

@@ -1,38 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.toCoordinateBox = toCoordinateBox;
-exports.centerOf = centerOf;
-exports.containsPoint = containsPoint;
-exports.encloses = encloses;
-exports.isWiderAndTallerThan = isWiderAndTallerThan;
-exports.topmostPerDepth = topmostPerDepth;
-function toCoordinateBox(x, y, width, height) {
-    return { x, y, width, height, left: x, right: x + width, top: y, bottom: y + height };
-}
-function centerOf(box) {
-    return { x: box.left + box.width / 2, y: box.top + box.height / 2 };
-}
-function containsPoint(box, point) {
-    return point.x >= box.left && point.x <= box.right && point.y >= box.top && point.y <= box.bottom;
-}
-function encloses(outer, inner) {
-    const covers = outer.left <= inner.left && outer.right >= inner.right && outer.top <= inner.top && outer.bottom >= inner.bottom;
-    const identical = outer.left === inner.left &&
-        outer.right === inner.right &&
-        outer.top === inner.top &&
-        outer.bottom === inner.bottom;
-    return covers && !identical;
-}
-function isWiderAndTallerThan(box, other) {
-    return box.width > other.width && box.height > other.height;
-}
-function topmostPerDepth(containers) {
-    const byDepth = [];
-    for (const container of containers) {
-        const existing = byDepth[container.depth];
-        if (!existing || container.drawOrder > existing.drawOrder) {
-            byDepth[container.depth] = container;
-        }
-    }
-    return byDepth.filter(Boolean);
-}

package/lib/containers/document-container.service.d.ts

@@ -1,14 +0,0 @@
-import { DocumentElement } from '../types';
-import { ContainerKind } from './container-kind';
-import { DocumentContainerIndex } from './document-container-index';
-export declare class DocumentContainerService {
-    static buildIndex(documentElements: readonly DocumentElement[], kinds?: ContainerKind[]): DocumentContainerIndex;
-    static isContainer(documentElement: DocumentElement, kinds?: ContainerKind[]): boolean;
-    private static measureDocumentElements;
-    private static measure;
-    private static buildNesting;
-    private static resolveContainerPath;
-    private static resolveInnermostOnTop;
-    private static toContainerPath;
-    private static candidateContainers;
-}

package/lib/containers/document-container.service.js

@@ -1,145 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DocumentContainerService = void 0;
-const document_element_factory_1 = require("../document-element-factory");
-const document_element_constants_1 = require("../document-element-constants");
-const container_kind_1 = require("./container-kind");
-const document_container_index_1 = require("./document-container-index");
-const document_container_1 = require("./document-container");
-class DocumentContainerService {
-    static buildIndex(documentElements, kinds = container_kind_1.CONTAINER_KINDS) {
-        const measuredDocumentElements = this.measureDocumentElements(documentElements !== null && documentElements !== void 0 ? documentElements : []);
-        const nestingByElementType = new Map(kinds.map((kind) => [kind.elementType, this.buildNesting(measuredDocumentElements, kind)]));
-        const containersById = new Map();
-        const containerIdsByElementType = new Map();
-        nestingByElementType.forEach((nesting, elementType) => {
-            containerIdsByElementType.set(elementType, nesting.containers.map((container) => container.id));
-            nesting.containers.forEach((container) => containersById.set(container.id, container));
-        });
-        const containerPathsByDocumentElementId = new Map();
-        const memberIdsByContainerId = new Map();
-        for (const measured of measuredDocumentElements) {
-            const documentElementId = measured.documentElement.id;
-            const pathsByElementType = new Map();
-            for (const kind of kinds) {
-                const path = this.resolveContainerPath(measured, kind, kinds, nestingByElementType.get(kind.elementType));
-                pathsByElementType.set(kind.elementType, path);
-                for (const containerId of path) {
-                    const members = memberIdsByContainerId.get(containerId);
-                    if (members) {
-                        members.push(documentElementId);
-                    }
-                    else {
-                        memberIdsByContainerId.set(containerId, [documentElementId]);
-                    }
-                }
-            }
-            containerPathsByDocumentElementId.set(documentElementId, pathsByElementType);
-        }
-        return new document_container_index_1.DocumentContainerIndex({
-            documentElementsById: new Map(measuredDocumentElements.map((measured) => [measured.documentElement.id, measured.documentElement])),
-            containersById,
-            containerPathsByDocumentElementId,
-            memberIdsByContainerId,
-            containerIdsByElementType,
-        });
-    }
-    static isContainer(documentElement, kinds = container_kind_1.CONTAINER_KINDS) {
-        return kinds.some((kind) => kind.elementType === (documentElement === null || documentElement === void 0 ? void 0 : documentElement.type));
-    }
-    static measureDocumentElements(documentElements) {
-        const documentElementsById = new Map(documentElements.map((documentElement) => [documentElement.id, documentElement]));
-        return documentElements.map((documentElement, drawOrder) => ({
-            documentElement,
-            drawOrder,
-            box: this.measure(documentElement, documentElementsById),
-        }));
-    }
-    static measure(documentElement, documentElementsById) {
-        var _a, _b;
-        if (!(documentElement === null || documentElement === void 0 ? void 0 : documentElement.position)) {
-            return null;
-        }
-        try {
-            const start = ((_a = documentElement.start) === null || _a === void 0 ? void 0 : _a.id) ? documentElementsById.get(documentElement.start.id) : undefined;
-            const end = ((_b = documentElement.end) === null || _b === void 0 ? void 0 : _b.id) ? documentElementsById.get(documentElement.end.id) : undefined;
-            const { x, y, width, height } = document_element_factory_1.DocumentElementFactory.getBoundingClientRect(documentElement, start, end);
-            return (0, document_container_1.toCoordinateBox)(x, y, width, height);
-        }
-        catch (_c) {
-            return null;
-        }
-    }
-    static buildNesting(measuredDocumentElements, kind) {
-        const containers = measuredDocumentElements
-            .filter((measured) => measured.documentElement.type === kind.elementType && measured.box)
-            .map((measured) => ({
-            id: measured.documentElement.id,
-            kind,
-            name: measured.documentElement.name,
-            documentElement: measured.documentElement,
-            box: measured.box,
-            depth: 0,
-            drawOrder: measured.drawOrder,
-        }));
-        const ancestorsById = new Map();
-        for (const container of containers) {
-            const ancestors = kind.nests
-                ? containers.filter((other) => other !== container && (0, document_container_1.encloses)(other.box, container.box))
-                : [];
-            ancestorsById.set(container.id, ancestors);
-            container.depth = ancestors.length;
-        }
-        return { containers, ancestorsById };
-    }
-    static resolveContainerPath(measured, kind, kinds, nesting) {
-        var _a, _b;
-        if (!(nesting === null || nesting === void 0 ? void 0 : nesting.containers.length) || !measured.box) {
-            return [];
-        }
-        const ownKind = kinds.find((candidate) => candidate.elementType === measured.documentElement.type);
-        if (ownKind) {
-            if (ownKind.elementType === kind.elementType) {
-                return kind.nests ? this.toContainerPath((_a = nesting.ancestorsById.get(measured.documentElement.id)) !== null && _a !== void 0 ? _a : []) : [];
-            }
-            if (kind.layer > ownKind.layer) {
-                return [];
-            }
-        }
-        const candidates = this.candidateContainers(measured, nesting.containers);
-        if (!candidates.length) {
-            return [];
-        }
-        const innermostOnTop = this.resolveInnermostOnTop(candidates, nesting);
-        const candidateIds = new Set(candidates.map((container) => container.id));
-        const ancestors = ((_b = nesting.ancestorsById.get(innermostOnTop.id)) !== null && _b !== void 0 ? _b : []).filter((container) => candidateIds.has(container.id));
-        return this.toContainerPath([...ancestors, innermostOnTop]);
-    }
-    static resolveInnermostOnTop(candidates, nesting) {
-        const enclosingIds = new Set(candidates.flatMap((container) => { var _a; return (_a = nesting.ancestorsById.get(container.id)) !== null && _a !== void 0 ? _a : []; }).map((ancestor) => ancestor.id));
-        return candidates
-            .filter((container) => !enclosingIds.has(container.id))
-            .reduce((topmost, container) => (container.drawOrder > topmost.drawOrder ? container : topmost));
-    }
-    static toContainerPath(containers) {
-        return (0, document_container_1.topmostPerDepth)(containers).map((container) => container.id);
-    }
-    static candidateContainers(measured, containers) {
-        const center = (0, document_container_1.centerOf)(measured.box);
-        const isShape = document_element_constants_1.SHAPE_ELEMENT_TYPES.includes(measured.documentElement.type);
-        return containers.filter((container) => {
-            var _a;
-            if (container.id === measured.documentElement.id || measured.drawOrder <= container.drawOrder) {
-                return false;
-            }
-            if (!(0, document_container_1.containsPoint)(container.box, center)) {
-                return false;
-            }
-            if (isShape && (0, document_container_1.isWiderAndTallerThan)(measured.box, container.box)) {
-                return false;
-            }
-            return !((_a = measured.documentElement.elementIds) === null || _a === void 0 ? void 0 : _a.includes(container.id));
-        });
-    }
-}
-exports.DocumentContainerService = DocumentContainerService;