@contrail/documents 1.20.0-alpha.5014a52 → 1.20.0-alpha.d5bd4fa

package/CHANGELOG.md

@@ -12,6 +12,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`, 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.
 
 ## [1.18.0] - 2026-09-10
 

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

@@ -1,6 +1,13 @@
-import { CropDefinition, DocumentElement, SizeDefinition } from '../../types';
+import { CropDefinition, DocumentElement, MaskDefinition, SizeDefinition } from '../../types';
 import { MaskRect, MaskShapeKey } from './mask-shape-geometry';
-export declare function hasShapeMask(element: DocumentElement): boolean;
+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;

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

@@ -9,10 +9,19 @@ 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, _b;
-    return (!!getShapeMaskKey(element) && !!((_a = element === null || element === void 0 ? void 0 : element.cropDefinition) === null || _a === void 0 ? void 0 : _a.widthPercent) && !!((_b = element === null || element === void 0 ? void 0 : element.cropDefinition) === null || _b === void 0 ? void 0 : _b.heightPercent));
+    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;

package/package.json

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