@contrail/documents 1.20.0-alpha.5014a52 → 1.20.0-alpha.79987a9

package/CHANGELOG.md

@@ -5,13 +5,27 @@ 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).
 
-## [1.20.0] - 2026-09-10
+## [1.20.0] - 2026-09-21
+
+Maintenance release on the 1.x line; the same change ships on 2.x as 2.3.0.
+
+### Added
+
+- `isValidSortIndex(sortIndex)` — whether a value is a key `fractional-indexing` could have produced, so every client writing a sort index is held to one definition of valid rather than each caller inventing its own. `fractional-indexing` keeps its `validateOrderKey` private, so the check asks the generator to mint a key after the candidate: that path validates its bound first and cannot fail for any other reason. The generator's own grammar check ignores the digit alphabet, and accepts `a0!` or `a0 `, so the candidate is screened against the exported `BASE_62_DIGITS` first. Costs ~130ns for a short key and ~350ns for a 387-character one.
+
+### Changed
+
+- `allElementsHaveSortIndex` now requires each element's key to be valid, not merely a non-empty string. Callers that treat an unkeyed collection as needing fresh keys — board snapshot restore is the one today — now also re-key a collection whose keys are present but malformed, instead of restoring ordering that cannot sort.
+- `SortOrderErrorMessage.SORT_INDEX_NOT_USABLE` describes the real rule ("sortIndex must be a valid fractional index") rather than "must be a non-empty string". The `SORT_INDEX_NOT_USABLE` code is unchanged.
+
+## [1.19.0] - 2026-09-11
 
 ### Added
 
 - `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/sort-index.d.ts

@@ -1,4 +1,5 @@
 import { DocumentElement } from './types';
+export declare function isValidSortIndex(sortIndex: unknown): sortIndex is string;
 export declare function allElementsHaveSortIndex(elements: unknown[]): boolean;
 export declare function buildKeyBetween(a: string | null, b: string | null): string;
 export declare function buildNKeysBetween(a: string | null, b: string | null, n: number): string[];

package/lib/sort-index.js

@@ -1,13 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidSortIndex = isValidSortIndex;
 exports.allElementsHaveSortIndex = allElementsHaveSortIndex;
 exports.buildKeyBetween = buildKeyBetween;
 exports.buildNKeysBetween = buildNKeysBetween;
 exports.compareSortIndex = compareSortIndex;
 const fractional_indexing_1 = require("fractional-indexing");
+const SORT_INDEX_DIGITS = new RegExp(`^[${fractional_indexing_1.BASE_62_DIGITS.replace(/[\\\]^-]/g, (digit) => `\\${digit}`)}]+$`);
+function isValidSortIndex(sortIndex) {
+    if (typeof sortIndex !== 'string' || !SORT_INDEX_DIGITS.test(sortIndex)) {
+        return false;
+    }
+    try {
+        (0, fractional_indexing_1.generateKeyBetween)(sortIndex, null);
+    }
+    catch (_a) {
+        return false;
+    }
+    return true;
+}
 function allElementsHaveSortIndex(elements) {
-    return elements.every((element) => typeof element.sortIndex === 'string' &&
-        element.sortIndex.length > 0);
+    return elements.every((element) => isValidSortIndex(element.sortIndex));
 }
 function buildKeyBetween(a, b) {
     return (0, fractional_indexing_1.generateKeyBetween)(a, b);

package/lib/sort-order-errors.d.ts

@@ -6,5 +6,5 @@ export declare enum SortOrderErrorCode {
 export declare enum SortOrderErrorMessage {
     SORT_MIGRATION_IN_PROGRESS = "Sort order is being migrated for this document; editing is briefly locked",
     SORT_MODE_MISMATCH = "Ordering write does not match the document's sort mode",
-    SORT_INDEX_NOT_USABLE = "sortIndex must be a non-empty string"
+    SORT_INDEX_NOT_USABLE = "sortIndex must be a valid fractional index"
 }

package/lib/sort-order-errors.js

@@ -11,5 +11,5 @@ var SortOrderErrorMessage;
 (function (SortOrderErrorMessage) {
     SortOrderErrorMessage["SORT_MIGRATION_IN_PROGRESS"] = "Sort order is being migrated for this document; editing is briefly locked";
     SortOrderErrorMessage["SORT_MODE_MISMATCH"] = "Ordering write does not match the document's sort mode";
-    SortOrderErrorMessage["SORT_INDEX_NOT_USABLE"] = "sortIndex must be a non-empty string";
+    SortOrderErrorMessage["SORT_INDEX_NOT_USABLE"] = "sortIndex must be a valid fractional index";
 })(SortOrderErrorMessage || (exports.SortOrderErrorMessage = SortOrderErrorMessage = {}));

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.79987a9",
   "description": "Documents library for contrail platform",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",