circuitjson-toolkit 1.0.16 → 1.1.0

package/src/core/PcbInteractionPrimitiveModel.mjs

@@ -1,5 +1,8 @@
 import { CircuitJsonDocument } from './CircuitJsonDocument.mjs'
 import { CircuitJsonPcbPrimitiveBuilder } from './CircuitJsonPcbPrimitiveBuilder.mjs'
+import { CircuitJsonDocumentContext } from './context/CircuitJsonDocumentContext.mjs'
+import { PcbPrimitivePreparation } from './context/PcbPrimitivePreparation.mjs'
+import { PcbInteractionBounds } from './interaction/PcbInteractionBounds.mjs'
 
 /**
  * Builds renderer-neutral PCB primitives for element-array board documents.
@@ -11,13 +14,17 @@ export class PcbInteractionPrimitiveModel {
      * @returns {{ bounds: object, layers: object[], virtualLayers: object[], components: object[], nets: object[], primitives: object[], anchors: object[], diagnostics: object[], airwires: object[], traceLengths: object[], groups: object[], anchorOffsets: object[] }}
      */
     static build(documentModel) {
-        if (
-            !PcbInteractionPrimitiveModel.#isElementArrayDocument(documentModel)
-        ) {
+        const context = PcbInteractionPrimitiveModel.#context(documentModel)
+        if (context) return PcbPrimitivePreparation.prepareComplete(context)
+
+        const elements = CircuitJsonDocument.normalizeModel(
+            CircuitJsonPcbPrimitiveBuilder.elements(documentModel)
+        )
+        try {
+            return CircuitJsonPcbPrimitiveBuilder.build(elements)
+        } catch {
             return PcbInteractionPrimitiveModel.#emptyModel()
         }
-
-        return CircuitJsonPcbPrimitiveBuilder.build(documentModel)
     }
 
     /**
@@ -26,13 +33,7 @@ export class PcbInteractionPrimitiveModel {
      * @returns {{ physicalLayers: object[], virtualLayers: object[] }}
      */
     static resolveLayerGroups(documentModel) {
-        if (
-            !PcbInteractionPrimitiveModel.#isElementArrayDocument(documentModel)
-        ) {
-            return { physicalLayers: [], virtualLayers: [] }
-        }
-
-        const model = CircuitJsonPcbPrimitiveBuilder.build(documentModel)
+        const model = PcbInteractionPrimitiveModel.build(documentModel)
         return {
             physicalLayers: model.layers,
             virtualLayers: model.virtualLayers || []
@@ -47,6 +48,21 @@ export class PcbInteractionPrimitiveModel {
      * @returns {{ snapped: boolean, point: { x: number, y: number } }}
      */
     static resolveSnapPoint(documentModel, point, options = {}) {
+        return PcbInteractionPrimitiveModel.resolveSnapPointFromModel(
+            PcbInteractionPrimitiveModel.build(documentModel),
+            point,
+            options
+        )
+    }
+
+    /**
+     * Snaps against anchors from one already prepared primitive model.
+     * @param {{ anchors?: object[] }} model Prepared primitive model.
+     * @param {{ x?: unknown, y?: unknown }} point Board-space point.
+     * @param {{ tolerance?: number }} [options] Snap options.
+     * @returns {{ snapped: boolean, point: { x: number, y: number } }}
+     */
+    static resolveSnapPointFromModel(model, point, options = {}) {
         const normalizedPoint = PcbInteractionPrimitiveModel.#point(point)
         if (!normalizedPoint) return { snapped: false, point: { x: 0, y: 0 } }
 
@@ -57,8 +73,7 @@ export class PcbInteractionPrimitiveModel {
         let bestPoint = null
         let bestDistanceSq = Infinity
 
-        for (const anchor of PcbInteractionPrimitiveModel.build(documentModel)
-            .anchors) {
+        for (const anchor of model?.anchors || []) {
             const distanceSq = PcbInteractionPrimitiveModel.#distanceSquared(
                 normalizedPoint,
                 anchor.point
@@ -84,21 +99,66 @@ export class PcbInteractionPrimitiveModel {
      * @returns {object[]}
      */
     static hitTest(documentModel, point, options = {}) {
+        const model = PcbInteractionPrimitiveModel.build(documentModel)
+        return PcbInteractionPrimitiveModel.hitTestPrimitives(
+            model.primitives,
+            point,
+            options,
+            model.groups
+        )
+    }
+
+    /**
+     * Applies the legacy exact narrow phase to prepared primitive candidates.
+     * @param {object[]} primitives Prepared primitive candidates.
+     * @param {{ x?: unknown, y?: unknown }} point Board-space point.
+     * @param {{ side?: 'top' | 'bottom', hiddenLayers?: string[], hiddenObjects?: string[], tolerance?: number }} [options] Hit-test options.
+     * @param {object[]} [groups] Prepared group rows.
+     * @returns {object[]} Prioritized hit candidates.
+     */
+    static hitTestPrimitives(primitives, point, options = {}, groups = []) {
+        return PcbInteractionPrimitiveModel.hitTestRecords(
+            (primitives || []).map((primitive, index) => ({
+                recordId: String(index),
+                primitive
+            })),
+            point,
+            options,
+            groups
+        ).map(({ recordId: _recordId, ...hit }) => hit)
+    }
+
+    /**
+     * Applies the exact narrow phase while preserving a caller-owned stable
+     * record identity independently from non-unique primitive ids.
+     * @param {{ recordId: string, primitive: object }[]} records Prepared primitive records.
+     * @param {{ x?: unknown, y?: unknown }} point Board-space point.
+     * @param {{ side?: 'top' | 'bottom', hiddenLayers?: string[], hiddenObjects?: string[], tolerance?: number }} [options] Hit-test options.
+     * @param {object[]} [groups] Prepared group rows.
+     * @returns {object[]} Prioritized hits carrying their stable record ids.
+     */
+    static hitTestRecords(records, point, options = {}, groups = []) {
         const normalizedPoint = PcbInteractionPrimitiveModel.#point(point)
         if (!normalizedPoint) return []
-
+        const preparedOptions =
+            PcbInteractionPrimitiveModel.#visibilityOptions(options)
         const tolerance = PcbInteractionPrimitiveModel.#number(
             options.tolerance,
             0.2
         )
-        const model = PcbInteractionPrimitiveModel.build(documentModel)
         const groupsById = new Map(
-            (model.groups || []).map((group) => [String(group.id || ''), group])
+            (groups || []).map((group) => [String(group.id || ''), group])
         )
         const hits = []
 
-        for (const primitive of model.primitives) {
-            if (!PcbInteractionPrimitiveModel.#isVisible(primitive, options)) {
+        for (const record of records || []) {
+            const primitive = record.primitive
+            if (
+                !PcbInteractionPrimitiveModel.#isVisible(
+                    primitive,
+                    preparedOptions
+                )
+            ) {
                 continue
             }
             const distance = PcbInteractionPrimitiveModel.#hitDistance(
@@ -109,6 +169,7 @@ export class PcbInteractionPrimitiveModel {
             if (distance === null) continue
 
             hits.push({
+                recordId: String(record.recordId),
                 ...PcbInteractionPrimitiveModel.#candidate(
                     primitive,
                     groupsById
@@ -126,14 +187,53 @@ export class PcbInteractionPrimitiveModel {
     }
 
     /**
-     * Returns true when the document uses the element-array source format.
-     * @param {object | object[]} documentModel Parsed document model.
-     * @returns {boolean}
+     * Resolves conservative exact-geometry bounds for spatial indexing.
+     * @param {object} primitive Prepared PCB primitive.
+     * @returns {{ minX: number, minY: number, maxX: number, maxY: number } | null} Interaction bounds.
      */
-    static #isElementArrayDocument(documentModel) {
-        return CircuitJsonDocument.isModel(
-            CircuitJsonPcbPrimitiveBuilder.elements(documentModel)
-        )
+    static interactionBounds(primitive) {
+        return PcbInteractionBounds.resolve(primitive)
+    }
+
+    /**
+     * Resolves one canonical context without exposing validation failures from
+     * this legacy tolerant facade.
+     * @param {unknown} documentModel Document result, model, or context.
+     * @returns {CircuitJsonDocumentContext | null} Prepared context.
+     */
+    static #context(documentModel) {
+        try {
+            if (documentModel instanceof CircuitJsonDocumentContext) {
+                return documentModel
+            }
+            if (
+                documentModel &&
+                typeof documentModel === 'object' &&
+                !Array.isArray(documentModel)
+            ) {
+                const schema = Object.getOwnPropertyDescriptor(
+                    documentModel,
+                    'schema'
+                )
+                const model = Object.getOwnPropertyDescriptor(
+                    documentModel,
+                    'model'
+                )
+                if (
+                    schema &&
+                    Object.hasOwn(schema, 'value') &&
+                    schema.value === 'ecad-toolkit.document.v1' &&
+                    model &&
+                    Object.hasOwn(model, 'value') &&
+                    Array.isArray(model.value)
+                ) {
+                    return CircuitJsonDocumentContext.prepare(documentModel)
+                }
+            }
+            return null
+        } catch {
+            return null
+        }
     }
 
     /**
@@ -164,39 +264,59 @@ export class PcbInteractionPrimitiveModel {
      * @returns {boolean}
      */
     static #isVisible(primitive, options) {
-        const hiddenLayers = new Set(
-            (Array.isArray(options.hiddenLayers) ? options.hiddenLayers : [])
-                .map(String)
-                .filter(Boolean)
-        )
-        if (primitive.layer && hiddenLayers.has(String(primitive.layer))) {
+        if (
+            primitive.layer &&
+            options.hiddenLayers.has(String(primitive.layer))
+        ) {
             return false
         }
 
-        const hiddenObjects = new Set(
-            (Array.isArray(options.hiddenObjects) ? options.hiddenObjects : [])
-                .map(String)
-                .filter(Boolean)
-        )
         if (
-            hiddenObjects.has(
+            options.hiddenObjects.has(
                 PcbInteractionPrimitiveModel.#componentSideObjectKey(primitive)
             )
         ) {
             return false
         }
         if (
-            hiddenObjects.has(
+            options.hiddenObjects.has(
                 PcbInteractionPrimitiveModel.#objectKey(primitive)
             )
         ) {
             return false
         }
 
-        const side = String(options.side || '')
+        const side = options.side
         return !side || !primitive.side || primitive.side === side
     }
 
+    /**
+     * Builds visibility lookup sets once per hit-test call.
+     * @param {object} options Raw legacy hit options.
+     * @returns {{ side: string, hiddenLayers: Set<string>, hiddenObjects: Set<string> }} Prepared options.
+     */
+    static #visibilityOptions(options) {
+        return {
+            side: String(options.side || ''),
+            hiddenLayers: new Set(
+                (Array.isArray(options.hiddenLayers)
+                    ? options.hiddenLayers
+                    : []
+                )
+                    .map(String)
+                    .filter(Boolean)
+            ),
+            hiddenObjects: new Set(
+                (Array.isArray(options.hiddenObjects)
+                    ? options.hiddenObjects
+                    : []
+                )
+                    .map(String)
+                    .filter(Boolean)
+            )
+        }
+    }
+
     /**
      * Resolves component-side object keys for component-backed primitives.
      * @param {object} primitive Primitive row.
@@ -268,27 +388,40 @@ export class PcbInteractionPrimitiveModel {
             return distance <= width / 2 + tolerance ? distance : null
         }
         if (primitive.kind === 'via') {
-            if (String(primitive.shape || 'circle') !== 'circle') {
-                return PcbInteractionPrimitiveModel.#inside(
-                    point,
-                    primitive.bounds,
-                    tolerance
-                )
-                    ? 0
-                    : null
-            }
-            const distance = Math.sqrt(
-                PcbInteractionPrimitiveModel.#distanceSquared(point, primitive)
+            const hit = PcbInteractionPrimitiveModel.#shapeHit(
+                primitive,
+                point,
+                tolerance
             )
-            return distance <= primitive.diameter / 2 + tolerance
-                ? distance
-                : null
+            if (hit === null) return null
+            return String(primitive.shape || 'circle') === 'circle'
+                ? Math.sqrt(
+                      PcbInteractionPrimitiveModel.#distanceSquared(
+                          point,
+                          primitive
+                      )
+                  )
+                : hit
         }
-        if (
-            ['pad', 'zone', 'keepout', 'cutout', 'courtyard'].includes(
-                primitive.kind
+        if (primitive.kind === 'pad') {
+            return PcbInteractionPrimitiveModel.#shapeHit(
+                primitive,
+                point,
+                tolerance
             )
+        }
+        if (
+            ['zone', 'keepout', 'cutout', 'courtyard'].includes(primitive.kind)
         ) {
+            const points =
+                PcbInteractionPrimitiveModel.#primitivePoints(primitive)
+            if (points.length >= 3) {
+                return PcbInteractionPrimitiveModel.#polygonHit(
+                    points,
+                    point,
+                    tolerance
+                )
+            }
             return PcbInteractionPrimitiveModel.#inside(
                 point,
                 primitive.bounds,
@@ -298,15 +431,213 @@ export class PcbInteractionPrimitiveModel {
                 : null
         }
         if (primitive.kind === 'board') {
-            return PcbInteractionPrimitiveModel.#inside(
+            const points =
+                PcbInteractionPrimitiveModel.#primitivePoints(primitive)
+            const inside =
+                points.length >= 3
+                    ? PcbInteractionPrimitiveModel.#polygonHit(
+                          points,
+                          point,
+                          0
+                      ) !== null
+                    : PcbInteractionPrimitiveModel.#inside(
+                          point,
+                          primitive.bounds,
+                          0
+                      )
+            return inside ? Number.MAX_SAFE_INTEGER : null
+        }
+        return null
+    }
+
+    /**
+     * Applies exact common pad and via shape predicates.
+     * @param {object} primitive Shape primitive.
+     * @param {{ x: number, y: number }} point Board point.
+     * @param {number} tolerance Hit tolerance.
+     * @returns {number | null} Hit distance or null.
+     */
+    static #shapeHit(primitive, point, tolerance) {
+        const points = PcbInteractionPrimitiveModel.#primitivePoints(primitive)
+        if (points.length >= 3) {
+            return PcbInteractionPrimitiveModel.#polygonHit(
+                points,
                 point,
-                primitive.bounds,
+                tolerance
+            )
+        }
+        const center = PcbInteractionPrimitiveModel.#point(primitive)
+        if (!center) return null
+        const width = Math.max(
+            PcbInteractionPrimitiveModel.#number(
+                primitive.width ?? primitive.diameter,
                 0
+            ),
+            0
+        )
+        const height = Math.max(
+            PcbInteractionPrimitiveModel.#number(
+                primitive.height ?? primitive.diameter ?? primitive.width,
+                width
+            ),
+            0
+        )
+        if (!width || !height) return null
+        const local = PcbInteractionPrimitiveModel.#rotatePoint(
+            point,
+            center,
+            -PcbInteractionPrimitiveModel.#number(primitive.rotation, 0)
+        )
+        const shape = String(primitive.shape || 'circle').toLowerCase()
+        if (['circle', 'oval_circle'].includes(shape)) {
+            const x = (local.x - center.x) / (width / 2 + tolerance)
+            const y = (local.y - center.y) / (height / 2 + tolerance)
+            return x * x + y * y <= 1 ? 0 : null
+        }
+        if (['pill', 'oval', 'rotated_pill', 'capsule'].includes(shape)) {
+            return PcbInteractionPrimitiveModel.#capsuleHit(
+                local,
+                center,
+                width,
+                height,
+                tolerance
             )
-                ? Number.MAX_SAFE_INTEGER
-                : null
         }
-        return null
+        if (['rounded_rect', 'roundrect'].includes(shape)) {
+            return PcbInteractionPrimitiveModel.#roundedRectHit(
+                local,
+                center,
+                width,
+                height,
+                PcbInteractionPrimitiveModel.#number(primitive.radius, 0),
+                tolerance
+            )
+        }
+        return Math.abs(local.x - center.x) <= width / 2 + tolerance &&
+            Math.abs(local.y - center.y) <= height / 2 + tolerance
+            ? 0
+            : null
+    }
+
+    /**
+     * Tests a point against a horizontal or vertical capsule.
+     * @param {{ x: number, y: number }} point Local point.
+     * @param {{ x: number, y: number }} center Shape center.
+     * @param {number} width Shape width.
+     * @param {number} height Shape height.
+     * @param {number} tolerance Hit tolerance.
+     * @returns {number | null} Hit distance or null.
+     */
+    static #capsuleHit(point, center, width, height, tolerance) {
+        const radius = Math.min(width, height) / 2
+        const horizontal = width >= height
+        const halfSegment = Math.abs(width - height) / 2
+        const start = horizontal
+            ? { x: center.x - halfSegment, y: center.y }
+            : { x: center.x, y: center.y - halfSegment }
+        const end = horizontal
+            ? { x: center.x + halfSegment, y: center.y }
+            : { x: center.x, y: center.y + halfSegment }
+        return PcbInteractionPrimitiveModel.#distanceToSegment(
+            point,
+            start,
+            end
+        ) <=
+            radius + tolerance
+            ? 0
+            : null
+    }
+
+    /**
+     * Tests one rounded rectangle in local coordinates.
+     * @param {{ x: number, y: number }} point Local point.
+     * @param {{ x: number, y: number }} center Shape center.
+     * @param {number} width Shape width.
+     * @param {number} height Shape height.
+     * @param {number} radius Requested corner radius.
+     * @param {number} tolerance Hit tolerance.
+     * @returns {number | null} Hit distance or null.
+     */
+    static #roundedRectHit(point, center, width, height, radius, tolerance) {
+        const corner = Math.max(0, Math.min(radius, width / 2, height / 2))
+        const x = Math.max(
+            Math.abs(point.x - center.x) - (width / 2 - corner),
+            0
+        )
+        const y = Math.max(
+            Math.abs(point.y - center.y) - (height / 2 - corner),
+            0
+        )
+        return Math.hypot(x, y) <= corner + tolerance ? 0 : null
+    }
+
+    /**
+     * Tests a point against a polygon with edge tolerance.
+     * @param {{ x: number, y: number }[]} points Polygon points.
+     * @param {{ x: number, y: number }} point Board point.
+     * @param {number} tolerance Hit tolerance.
+     * @returns {number | null} Hit distance or null.
+     */
+    static #polygonHit(points, point, tolerance) {
+        let inside = false
+        let distance = Infinity
+        for (
+            let index = 0, previous = points.length - 1;
+            index < points.length;
+            previous = index, index += 1
+        ) {
+            const start = points[previous]
+            const end = points[index]
+            distance = Math.min(
+                distance,
+                PcbInteractionPrimitiveModel.#distanceToSegment(
+                    point,
+                    start,
+                    end
+                )
+            )
+            if (
+                start.y > point.y !== end.y > point.y &&
+                point.x <
+                    ((end.x - start.x) * (point.y - start.y)) /
+                        (end.y - start.y) +
+                        start.x
+            ) {
+                inside = !inside
+            }
+        }
+        return inside || distance <= tolerance ? 0 : null
+    }
+
+    /**
+     * Resolves valid polygon points from one primitive.
+     * @param {object} primitive PCB primitive.
+     * @returns {{ x: number, y: number }[]} Points.
+     */
+    static #primitivePoints(primitive) {
+        return (Array.isArray(primitive?.points) ? primitive.points : [])
+            .map(PcbInteractionPrimitiveModel.#point)
+            .filter(Boolean)
+    }
+
+    /**
+     * Rotates a point around one center.
+     * @param {{ x: number, y: number }} point Point.
+     * @param {{ x: number, y: number }} center Center.
+     * @param {number} degrees Counter-clockwise degrees.
+     * @returns {{ x: number, y: number }} Rotated point.
+     */
+    static #rotatePoint(point, center, degrees) {
+        if (!degrees) return point
+        const radians = (degrees * Math.PI) / 180
+        const cos = Math.cos(radians)
+        const sin = Math.sin(radians)
+        const x = point.x - center.x
+        const y = point.y - center.y
+        return {
+            x: center.x + x * cos - y * sin,
+            y: center.y + x * sin + y * cos
+        }
     }
 
     /**

package/src/core/ProjectAsyncInputOwner.mjs

@@ -0,0 +1,70 @@
+import { BinaryDataSnapshot } from './context/BinaryDataSnapshot.mjs'
+import { ToolkitAsset } from './contracts/ToolkitAsset.mjs'
+
+/**
+ * Owns direct asynchronous project payloads before host callbacks run.
+ */
+export class ProjectAsyncInputOwner {
+    /**
+     * Owns candidate bytes and prepares companion assets once.
+     * @param {{ entries: object[] }} classified Classified entries.
+     * @param {'none' | 'metadata' | 'full'} assetMode Asset decode mode.
+     * @returns {void}
+     */
+    static own(classified, assetMode) {
+        const snapshots = new WeakMap()
+        for (const entry of classified.entries) {
+            if (entry.name.toLowerCase().endsWith('.json')) {
+                entry.input.data = ProjectAsyncInputOwner.#binary(
+                    entry.input.data,
+                    snapshots
+                )
+                continue
+            }
+            if (assetMode === 'none') continue
+            entry.companionAsset = ProjectAsyncInputOwner.#companionAsset(
+                entry,
+                assetMode
+            )
+        }
+    }
+
+    /**
+     * Copies one binary value once while leaving immutable text unchanged.
+     * @param {unknown} value Entry data.
+     * @param {WeakMap<object, unknown>} snapshots Request-local binary copies.
+     * @returns {unknown} Owned data.
+     */
+    static #binary(value, snapshots) {
+        if (typeof value === 'string') return value
+        if (value && typeof value === 'object' && snapshots.has(value)) {
+            return snapshots.get(value)
+        }
+        const owned = BinaryDataSnapshot.clone(value)
+        if (value && typeof value === 'object') snapshots.set(value, owned)
+        return owned
+    }
+
+    /**
+     * Prepares one companion asset as the final canonical payload snapshot.
+     * @param {object} entry Classified companion entry.
+     * @param {'metadata' | 'full'} mode Asset decode mode.
+     * @returns {Record<string, any>} Prepared companion asset.
+     */
+    static #companionAsset(entry, mode) {
+        return ToolkitAsset.prepare(
+            {
+                kind: 'companion',
+                name: entry.name,
+                mediaType: 'application/octet-stream',
+                byteLength: entry.byteLength,
+                data: entry.input.data,
+                source: { entryName: entry.name }
+            },
+            { mode }
+        )
+    }
+}
+
+Object.freeze(ProjectAsyncInputOwner.prototype)
+Object.freeze(ProjectAsyncInputOwner)