@contrail/documents 1.20.0-alpha.5ed9686 → 1.20.0-alpha.6beca3a

package/CHANGELOG.md

@@ -5,20 +5,25 @@ 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-20
+## [1.20.0] - 2026-09-25
+
+A maintenance release on the 1.x line, published under the `v1-maintenance` tag. Carries the
+same container work as 2.4.0, for consumers still on `@contrail/types@^3.4` and Node 20.
 
 ### 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.
+  belongs to the container whose box covers its anchor point 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.
+- `DocumentContainerUtil` — the container geometry as statics, with `anchorFor` for a caller
+  holding an element rather than a measured box.
 - `positionKeepingAnchor` — where an element has to sit for its drawn corner to land where it did
   before a resize. Rotation turns about the centre and the centre moves with the size, so a rotated
   element resized about its stored position drags its corner along with it. The board already makes
@@ -63,6 +68,17 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   `getBoundingClientRectScaled` above. A scaled element previously measured at its unscaled size
   and could resolve to the wrong container.
 
+## [2.3.0] - 2026-09-21
+
+### 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.
+
 ## [2.2.1] - 2026-09-15
 
 ### Changed

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

@@ -35,8 +35,8 @@ class DocumentContainerIndex {
         return members;
     }
     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);
+        const covering = this.containersOfType(elementType).filter((container) => document_container_1.DocumentContainerUtil.containsPoint(container.box, point));
+        return document_container_1.DocumentContainerUtil.topmostPerDepth(covering).map((container) => container.id);
     }
     maxDepth(elementType) {
         return this.containersOfType(elementType).reduce((max, container) => Math.max(max, container.depth + 1), 0);

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

@@ -14,11 +14,14 @@ export interface MeasuredDocumentElement {
     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 anchorOf(documentElement: DocumentElement, box: CoordinateBox): PositionDefinition;
-export declare function positionKeepingAnchor(documentElement: DocumentElement, newSize: SizeDefinition): 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[];
+export declare class DocumentContainerUtil {
+    static toCoordinateBox(x: number, y: number, width: number, height: number): CoordinateBox;
+    static centerOf(box: CoordinateBox): PositionDefinition;
+    static anchorOf(documentElement: DocumentElement, box: CoordinateBox): PositionDefinition;
+    static positionKeepingAnchor(documentElement: DocumentElement, newSize: SizeDefinition): PositionDefinition;
+    static anchorFor(documentElement: DocumentElement, position?: PositionDefinition): PositionDefinition;
+    static containsPoint(box: CoordinateBox, point: PositionDefinition): boolean;
+    static encloses(outer: CoordinateBox, inner: CoordinateBox): boolean;
+    static isWiderAndTallerThan(box: CoordinateBox, other: CoordinateBox): boolean;
+    static topmostPerDepth(containers: DocumentContainer[]): DocumentContainer[];
+}

package/lib/containers/document-container.js

@@ -1,69 +1,75 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toCoordinateBox = toCoordinateBox;
-exports.centerOf = centerOf;
-exports.anchorOf = anchorOf;
-exports.positionKeepingAnchor = positionKeepingAnchor;
-exports.containsPoint = containsPoint;
-exports.encloses = encloses;
-exports.isWiderAndTallerThan = isWiderAndTallerThan;
-exports.topmostPerDepth = topmostPerDepth;
+exports.DocumentContainerUtil = void 0;
 const rotation_math_1 = require("../util/mask/rotation-math");
 const dynamic_text_util_1 = require("../util/dynamic-text/dynamic-text-util");
-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 anchorOf(documentElement, box) {
-    var _a;
-    if (!dynamic_text_util_1.DynamicTextUtil.isDynamicText(documentElement)) {
-        return centerOf(box);
+class DocumentContainerUtil {
+    static toCoordinateBox(x, y, width, height) {
+        return { x, y, width, height, left: x, right: x + width, top: y, bottom: y + height };
     }
-    const angle = (_a = documentElement.rotate) === null || _a === void 0 ? void 0 : _a.angle;
-    const corner = { x: box.left, y: box.top };
-    return angle ? (0, rotation_math_1.rotatePoint)(corner, angle, centerOf(box)) : corner;
-}
-function positionKeepingAnchor(documentElement, newSize) {
-    var _a, _b, _c, _d, _e;
-    const position = documentElement === null || documentElement === void 0 ? void 0 : documentElement.position;
-    const angle = (_a = documentElement === null || documentElement === void 0 ? void 0 : documentElement.rotate) === null || _a === void 0 ? void 0 : _a.angle;
-    if (!position || !angle || !newSize || !documentElement.size) {
-        return position;
+    static centerOf(box) {
+        return { x: box.left + box.width / 2, y: box.top + box.height / 2 };
     }
-    const scaleX = (_c = (_b = documentElement.scale) === null || _b === void 0 ? void 0 : _b.x) !== null && _c !== void 0 ? _c : 1;
-    const scaleY = (_e = (_d = documentElement.scale) === null || _d === void 0 ? void 0 : _d.y) !== null && _e !== void 0 ? _e : 1;
-    const cornerOffset = (size) => {
-        const half = { x: (size.width * scaleX) / 2, y: (size.height * scaleY) / 2 };
-        const turned = (0, rotation_math_1.rotatePoint)(half, angle);
-        return { x: half.x - turned.x, y: half.y - turned.y };
-    };
-    const before = cornerOffset(documentElement.size);
-    const after = cornerOffset(newSize);
-    return { x: position.x + before.x - after.x, y: position.y + before.y - after.y };
-}
-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;
+    static anchorOf(documentElement, box) {
+        var _a;
+        if (!dynamic_text_util_1.DynamicTextUtil.isDynamicText(documentElement)) {
+            return DocumentContainerUtil.centerOf(box);
+        }
+        const angle = (_a = documentElement.rotate) === null || _a === void 0 ? void 0 : _a.angle;
+        const corner = { x: box.left, y: box.top };
+        return angle ? (0, rotation_math_1.rotatePoint)(corner, angle, DocumentContainerUtil.centerOf(box)) : corner;
+    }
+    static positionKeepingAnchor(documentElement, newSize) {
+        var _a, _b, _c, _d, _e;
+        const position = documentElement === null || documentElement === void 0 ? void 0 : documentElement.position;
+        const angle = (_a = documentElement === null || documentElement === void 0 ? void 0 : documentElement.rotate) === null || _a === void 0 ? void 0 : _a.angle;
+        if (!position || !angle || !newSize || !documentElement.size) {
+            return position;
+        }
+        const scaleX = (_c = (_b = documentElement.scale) === null || _b === void 0 ? void 0 : _b.x) !== null && _c !== void 0 ? _c : 1;
+        const scaleY = (_e = (_d = documentElement.scale) === null || _d === void 0 ? void 0 : _d.y) !== null && _e !== void 0 ? _e : 1;
+        const cornerOffset = (size) => {
+            const half = { x: (size.width * scaleX) / 2, y: (size.height * scaleY) / 2 };
+            const turned = (0, rotation_math_1.rotatePoint)(half, angle);
+            return { x: half.x - turned.x, y: half.y - turned.y };
+        };
+        const before = cornerOffset(documentElement.size);
+        const after = cornerOffset(newSize);
+        return { x: position.x + before.x - after.x, y: position.y + before.y - after.y };
+    }
+    static anchorFor(documentElement, position) {
+        var _a, _b, _c, _d, _e;
+        const at = position !== null && position !== void 0 ? position : documentElement === null || documentElement === void 0 ? void 0 : documentElement.position;
+        if (!at) {
+            return null;
+        }
+        const size = (_a = documentElement === null || documentElement === void 0 ? void 0 : documentElement.size) !== null && _a !== void 0 ? _a : { width: 0, height: 0 };
+        const box = DocumentContainerUtil.toCoordinateBox(at.x, at.y, size.width * ((_c = (_b = documentElement === null || documentElement === void 0 ? void 0 : documentElement.scale) === null || _b === void 0 ? void 0 : _b.x) !== null && _c !== void 0 ? _c : 1), size.height * ((_e = (_d = documentElement === null || documentElement === void 0 ? void 0 : documentElement.scale) === null || _d === void 0 ? void 0 : _d.y) !== null && _e !== void 0 ? _e : 1));
+        return DocumentContainerUtil.anchorOf(documentElement, box);
+    }
+    static containsPoint(box, point) {
+        return point.x >= box.left && point.x <= box.right && point.y >= box.top && point.y <= box.bottom;
+    }
+    static 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;
+    }
+    static isWiderAndTallerThan(box, other) {
+        return box.width > other.width && box.height > other.height;
+    }
+    static 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);
     }
-    return byDepth.filter(Boolean);
 }
+exports.DocumentContainerUtil = DocumentContainerUtil;

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

@@ -65,7 +65,7 @@ class DocumentContainerService {
             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.getBoundingClientRectScaled(documentElement, start, end);
-            return (0, document_container_1.toCoordinateBox)(x, y, width, height);
+            return document_container_1.DocumentContainerUtil.toCoordinateBox(x, y, width, height);
         }
         catch (_c) {
             return null;
@@ -86,7 +86,7 @@ class DocumentContainerService {
         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))
+                ? containers.filter((other) => other !== container && document_container_1.DocumentContainerUtil.encloses(other.box, container.box))
                 : [];
             ancestorsById.set(container.id, ancestors);
             container.depth = ancestors.length;
@@ -123,10 +123,10 @@ class DocumentContainerService {
             .reduce((topmost, container) => (container.drawOrder > topmost.drawOrder ? container : topmost));
     }
     static toContainerPath(containers) {
-        return (0, document_container_1.topmostPerDepth)(containers).map((container) => container.id);
+        return document_container_1.DocumentContainerUtil.topmostPerDepth(containers).map((container) => container.id);
     }
     static candidateContainers(measured, containers) {
-        const anchor = (0, document_container_1.anchorOf)(measured.documentElement, measured.box);
+        const anchor = document_container_1.DocumentContainerUtil.anchorOf(measured.documentElement, measured.box);
         const isShape = document_element_constants_1.SHAPE_ELEMENT_TYPES.includes(measured.documentElement.type) &&
             !dynamic_text_util_1.DynamicTextUtil.isDynamicText(measured.documentElement);
         return containers.filter((container) => {
@@ -134,10 +134,10 @@ class DocumentContainerService {
             if (container.id === measured.documentElement.id || measured.drawOrder <= container.drawOrder) {
                 return false;
             }
-            if (!(0, document_container_1.containsPoint)(container.box, anchor)) {
+            if (!document_container_1.DocumentContainerUtil.containsPoint(container.box, anchor)) {
                 return false;
             }
-            if (isShape && (0, document_container_1.isWiderAndTallerThan)(measured.box, container.box)) {
+            if (isShape && document_container_1.DocumentContainerUtil.isWiderAndTallerThan(measured.box, container.box)) {
                 return false;
             }
             return !((_a = measured.documentElement.elementIds) === null || _a === void 0 ? void 0 : _a.includes(container.id));

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/package.json

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