circuitjson-toolkit 1.0.16 → 1.1.0

package/src/core/contracts/ToolkitProgress.mjs

@@ -0,0 +1,89 @@
+import { ToolkitError } from './ToolkitError.mjs'
+
+const STAGES = ['detect', 'decode', 'project', 'validate', 'complete']
+
+/**
+ * Creates ordered shared progress records.
+ */
+export class ToolkitProgress {
+    /**
+     * Normalizes one progress update and validates it against the previous row.
+     * @param {Record<string, any>} fields Progress fields.
+     * @param {Record<string, any> | null} [previous] Previous progress row.
+     * @returns {Record<string, any>} Clone-safe progress row.
+     */
+    static create(fields = {}, previous = null) {
+        const stage = String(fields.stage || '')
+        const stageIndex = STAGES.indexOf(stage)
+        if (stageIndex < 0) {
+            throw ToolkitProgress.#error(
+                'ERR_PROGRESS_STAGE',
+                `Unknown progress stage: ${stage || '(empty)'}`
+            )
+        }
+        if (previous?.stage === 'complete') {
+            throw ToolkitProgress.#error(
+                'ERR_PROGRESS_TERMINAL',
+                'Progress cannot continue after complete.'
+            )
+        }
+        const previousIndex = previous ? STAGES.indexOf(previous.stage) : -1
+        if (previous && (previousIndex < 0 || stageIndex < previousIndex)) {
+            throw ToolkitProgress.#error(
+                'ERR_PROGRESS_ORDER',
+                `Progress cannot move from ${previous.stage} to ${stage}.`
+            )
+        }
+
+        const completed = ToolkitProgress.#count(fields.completed, null)
+        const total = ToolkitProgress.#count(fields.total, null)
+        if (completed !== null && total !== null && completed > total) {
+            throw ToolkitProgress.#error(
+                'ERR_PROGRESS_COUNT',
+                'Progress completed count exceeds total.'
+            )
+        }
+
+        const result = { stage }
+        if (fields.detail != null && String(fields.detail)) {
+            result.detail = String(fields.detail)
+        }
+        if (fields.completed !== undefined) result.completed = completed
+        if (fields.total !== undefined) result.total = total
+        if (fields.message != null && String(fields.message)) {
+            result.message = String(fields.message)
+        }
+        return result
+    }
+
+    /**
+     * Normalizes a nullable non-negative count.
+     * @param {unknown} value Count candidate.
+     * @param {number | null} fallback Fallback value.
+     * @returns {number | null} Normalized count.
+     */
+    static #count(value, fallback) {
+        if (value == null) return fallback
+        const count = Number(value)
+        if (!Number.isFinite(count) || count < 0) {
+            throw ToolkitProgress.#error(
+                'ERR_PROGRESS_COUNT',
+                'Progress counts must be finite and non-negative.'
+            )
+        }
+        return count
+    }
+
+    /**
+     * Creates a progress validation error.
+     * @param {string} code Error code.
+     * @param {string} message Error message.
+     * @returns {ToolkitError} Typed error.
+     */
+    static #error(code, message) {
+        return new ToolkitError(message, {
+            code,
+            category: 'runtime'
+        })
+    }
+}

package/src/core/interaction/CanonicalInteractionOptions.mjs

@@ -0,0 +1,246 @@
+import { ToolkitError } from '../contracts/ToolkitError.mjs'
+
+const SIDES = new Set(['top', 'bottom'])
+
+/**
+ * Normalizes safe reusable PCB interaction options.
+ */
+export class CanonicalInteractionOptions {
+    /**
+     * Normalizes a safe finite CircuitJSON millimeter point.
+     * @param {unknown} point Point candidate.
+     * @returns {{ x: number, y: number }} Normalized point.
+     */
+    static point(point) {
+        if (!point || typeof point !== 'object') {
+            throw CanonicalInteractionOptions.error(
+                'Interaction point must be a plain finite x/y object.'
+            )
+        }
+        let prototype
+        let descriptors
+        try {
+            if (Array.isArray(point)) throw new TypeError('array')
+            prototype = Object.getPrototypeOf(point)
+            descriptors = Object.getOwnPropertyDescriptors(point)
+        } catch {
+            throw CanonicalInteractionOptions.error(
+                'Interaction point could not be inspected safely.'
+            )
+        }
+        const x = CanonicalInteractionOptions.#dataValue(descriptors.x)
+        const y = CanonicalInteractionOptions.#dataValue(descriptors.y)
+        if (
+            (prototype !== Object.prototype && prototype !== null) ||
+            typeof x !== 'number' ||
+            typeof y !== 'number' ||
+            !Number.isFinite(x) ||
+            !Number.isFinite(y)
+        ) {
+            throw CanonicalInteractionOptions.error(
+                'Interaction point must be a plain finite x/y object.'
+            )
+        }
+        return { x, y }
+    }
+
+    /**
+     * Normalizes one option record over existing defaults.
+     * @param {unknown} options Option candidate.
+     * @param {Record<string, any>} [defaults] Existing normalized defaults.
+     * @returns {{ side: 'top' | 'bottom' | null, tolerance: number, hiddenLayers: string[], hiddenObjects: string[] }} Normalized options.
+     */
+    static normalize(options = {}, defaults = {}) {
+        const record = CanonicalInteractionOptions.#record(options)
+        return {
+            side: CanonicalInteractionOptions.#side(
+                record.side,
+                defaults.side ?? null
+            ),
+            tolerance: CanonicalInteractionOptions.#tolerance(
+                record.tolerance,
+                defaults.tolerance ?? 0.2
+            ),
+            hiddenLayers: CanonicalInteractionOptions.#strings(
+                record.hiddenLayers,
+                defaults.hiddenLayers || [],
+                'hiddenLayers'
+            ),
+            hiddenObjects: CanonicalInteractionOptions.#strings(
+                record.hiddenObjects,
+                defaults.hiddenObjects || [],
+                'hiddenObjects'
+            )
+        }
+    }
+
+    /**
+     * Reads supported own data fields without invoking accessors.
+     * @param {unknown} value Option candidate.
+     * @returns {Record<string, any>} Safe option record.
+     */
+    static #record(value) {
+        if (!value || typeof value !== 'object') {
+            throw CanonicalInteractionOptions.error(
+                'Interaction options must be a plain object.'
+            )
+        }
+        let prototype
+        let descriptors
+        try {
+            if (Array.isArray(value)) throw new TypeError('array')
+            prototype = Object.getPrototypeOf(value)
+            descriptors = Object.getOwnPropertyDescriptors(value)
+        } catch {
+            throw CanonicalInteractionOptions.error(
+                'Interaction options could not be inspected safely.'
+            )
+        }
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw CanonicalInteractionOptions.error(
+                'Interaction options must be a plain object.'
+            )
+        }
+        const allowed = new Set([
+            'hiddenLayers',
+            'hiddenObjects',
+            'side',
+            'tolerance'
+        ])
+        const result = {}
+        for (const key of Reflect.ownKeys(descriptors)) {
+            const descriptor = descriptors[key]
+            if (
+                typeof key !== 'string' ||
+                !allowed.has(key) ||
+                descriptor.enumerable !== true ||
+                descriptor.get ||
+                descriptor.set
+            ) {
+                throw CanonicalInteractionOptions.error(
+                    'Interaction options contain an unsupported field.'
+                )
+            }
+            result[key] = descriptor.value
+        }
+        return result
+    }
+
+    /**
+     * Normalizes one optional board side.
+     * @param {unknown} value Side candidate.
+     * @param {'top' | 'bottom' | null} fallback Fallback side.
+     * @returns {'top' | 'bottom' | null} Normalized side.
+     */
+    static #side(value, fallback) {
+        const side = value === undefined ? fallback : value
+        if (side !== null && !SIDES.has(side)) {
+            throw CanonicalInteractionOptions.error(
+                'Interaction side must be top or bottom.'
+            )
+        }
+        return side
+    }
+
+    /**
+     * Normalizes one nonnegative interaction tolerance.
+     * @param {unknown} value Tolerance candidate.
+     * @param {number} fallback Fallback tolerance.
+     * @returns {number} Normalized tolerance.
+     */
+    static #tolerance(value, fallback) {
+        const tolerance = value === undefined ? fallback : value
+        if (
+            typeof tolerance !== 'number' ||
+            !Number.isFinite(tolerance) ||
+            tolerance < 0 ||
+            tolerance > 1000000
+        ) {
+            throw CanonicalInteractionOptions.error(
+                'Interaction tolerance must be a bounded nonnegative number.'
+            )
+        }
+        return tolerance
+    }
+
+    /**
+     * Normalizes one unique string-list option through data descriptors.
+     * @param {unknown} value Array candidate.
+     * @param {string[]} fallback Fallback values.
+     * @param {string} name Option name.
+     * @returns {string[]} Normalized strings.
+     */
+    static #strings(value, fallback, name) {
+        if (value === undefined) return [...fallback]
+        let descriptors
+        try {
+            if (
+                !Array.isArray(value) ||
+                Object.getPrototypeOf(value) !== Array.prototype
+            ) {
+                throw new TypeError('array')
+            }
+            descriptors = Object.getOwnPropertyDescriptors(value)
+        } catch {
+            throw CanonicalInteractionOptions.error(
+                `Interaction ${name} must be a plain string array.`
+            )
+        }
+        const length = descriptors.length?.value
+        if (!Number.isSafeInteger(length) || length < 0 || length > 4096) {
+            throw CanonicalInteractionOptions.error(
+                `Interaction ${name} must be a bounded string array.`
+            )
+        }
+        const result = []
+        for (let index = 0; index < length; index += 1) {
+            const descriptor = descriptors[String(index)]
+            if (
+                !descriptor ||
+                descriptor.get ||
+                descriptor.set ||
+                typeof descriptor.value !== 'string' ||
+                !descriptor.value.trim()
+            ) {
+                throw CanonicalInteractionOptions.error(
+                    `Interaction ${name} must contain non-empty strings.`
+                )
+            }
+            result.push(descriptor.value.trim())
+        }
+        const allowed = new Set([
+            'length',
+            ...Array.from({ length }, (_entry, index) => String(index))
+        ])
+        if (Reflect.ownKeys(descriptors).some((key) => !allowed.has(key))) {
+            throw CanonicalInteractionOptions.error(
+                `Interaction ${name} must be a plain string array.`
+            )
+        }
+        return [...new Set(result)]
+    }
+
+    /**
+     * Returns a descriptor's own data value without invoking accessors.
+     * @param {PropertyDescriptor | undefined} descriptor Field descriptor.
+     * @returns {unknown} Data value or undefined.
+     */
+    static #dataValue(descriptor) {
+        return descriptor && !descriptor.get && !descriptor.set
+            ? descriptor.value
+            : undefined
+    }
+
+    /**
+     * Creates one typed interaction-option error.
+     * @param {string} message Failure message.
+     * @returns {ToolkitError} Typed error.
+     */
+    static error(message) {
+        return new ToolkitError(message, {
+            code: 'ERR_INTERACTION_OPTIONS',
+            category: 'validation',
+            format: 'circuitjson'
+        })
+    }
+}

package/src/core/interaction/PcbInteractionBounds.mjs

@@ -0,0 +1,167 @@
+/**
+ * Resolves conservative broad-phase bounds from every exact geometry signal.
+ */
+export class PcbInteractionBounds {
+    /**
+     * Unions stored, point-list, segment-stroke, and rotated shape bounds.
+     * @param {object} primitive Prepared PCB primitive.
+     * @returns {{ minX: number, minY: number, maxX: number, maxY: number } | null} Conservative bounds.
+     */
+    static resolve(primitive) {
+        const stored = PcbInteractionBounds.#bounds(primitive?.bounds)
+        const points = (
+            Array.isArray(primitive?.points) ? primitive.points : []
+        )
+            .map(PcbInteractionBounds.#point)
+            .filter(Boolean)
+        const pointBounds = points.length
+            ? PcbInteractionBounds.#pointBounds(points)
+            : null
+        const segment = PcbInteractionBounds.#segmentBounds(primitive)
+        const shape = PcbInteractionBounds.#rotatedShapeBounds(primitive)
+        const signals = [stored, pointBounds, segment, shape].filter(Boolean)
+        return signals.length ? PcbInteractionBounds.#merge(signals) : null
+    }
+
+    /**
+     * Resolves stroke-expanded explicit segment bounds.
+     * @param {object} primitive Primitive candidate.
+     * @returns {object | null} Segment bounds.
+     */
+    static #segmentBounds(primitive) {
+        const start = PcbInteractionBounds.#point({
+            x: primitive?.x1,
+            y: primitive?.y1
+        })
+        const end = PcbInteractionBounds.#point({
+            x: primitive?.x2,
+            y: primitive?.y2
+        })
+        if (!start || !end) return null
+        const halfWidth = Math.max(
+            PcbInteractionBounds.#number(primitive?.width, 0) / 2,
+            0
+        )
+        return {
+            minX: Math.min(start.x, end.x) - halfWidth,
+            minY: Math.min(start.y, end.y) - halfWidth,
+            maxX: Math.max(start.x, end.x) + halfWidth,
+            maxY: Math.max(start.y, end.y) + halfWidth
+        }
+    }
+
+    /**
+     * Resolves an axis-aligned envelope for one rotated center-size shape.
+     * @param {object} primitive Primitive candidate.
+     * @returns {object | null} Rotated shape bounds.
+     */
+    static #rotatedShapeBounds(primitive) {
+        const center = PcbInteractionBounds.#point(primitive)
+        const width = PcbInteractionBounds.#finite(
+            primitive?.width ?? primitive?.diameter
+        )
+        const height = PcbInteractionBounds.#finite(
+            primitive?.height ?? primitive?.diameter ?? primitive?.width
+        )
+        if (!center || width === null || height === null) return null
+        const radians =
+            (PcbInteractionBounds.#number(primitive?.rotation, 0) * Math.PI) /
+            180
+        const cos = Math.abs(Math.cos(radians))
+        const sin = Math.abs(Math.sin(radians))
+        const halfWidth = (Math.abs(width) * cos + Math.abs(height) * sin) / 2
+        const halfHeight = (Math.abs(width) * sin + Math.abs(height) * cos) / 2
+        return {
+            minX: center.x - halfWidth,
+            minY: center.y - halfHeight,
+            maxX: center.x + halfWidth,
+            maxY: center.y + halfHeight
+        }
+    }
+
+    /**
+     * Resolves minimal bounds for normalized points.
+     * @param {{ x: number, y: number }[]} points Normalized points.
+     * @returns {object} Point bounds.
+     */
+    static #pointBounds(points) {
+        return points.reduce(
+            (bounds, point) => ({
+                minX: Math.min(bounds.minX, point.x),
+                minY: Math.min(bounds.minY, point.y),
+                maxX: Math.max(bounds.maxX, point.x),
+                maxY: Math.max(bounds.maxY, point.y)
+            }),
+            { minX: Infinity, minY: Infinity, maxX: -Infinity, maxY: -Infinity }
+        )
+    }
+
+    /**
+     * Unions normalized bounds rows.
+     * @param {object[]} rows Bounds rows.
+     * @returns {object} Merged bounds.
+     */
+    static #merge(rows) {
+        return rows.reduce(
+            (bounds, row) => ({
+                minX: Math.min(bounds.minX, row.minX),
+                minY: Math.min(bounds.minY, row.minY),
+                maxX: Math.max(bounds.maxX, row.maxX),
+                maxY: Math.max(bounds.maxY, row.maxY)
+            }),
+            { minX: Infinity, minY: Infinity, maxX: -Infinity, maxY: -Infinity }
+        )
+    }
+
+    /**
+     * Normalizes a point candidate.
+     * @param {unknown} value Point candidate.
+     * @returns {{ x: number, y: number } | null} Point or null.
+     */
+    static #point(value) {
+        const x = PcbInteractionBounds.#finite(value?.x)
+        const y = PcbInteractionBounds.#finite(value?.y)
+        return x === null || y === null ? null : { x, y }
+    }
+
+    /**
+     * Normalizes ordered rectangle bounds.
+     * @param {unknown} value Bounds candidate.
+     * @returns {object | null} Bounds or null.
+     */
+    static #bounds(value) {
+        const minX = PcbInteractionBounds.#finite(value?.minX)
+        const minY = PcbInteractionBounds.#finite(value?.minY)
+        const maxX = PcbInteractionBounds.#finite(value?.maxX)
+        const maxY = PcbInteractionBounds.#finite(value?.maxY)
+        return minX !== null &&
+            minY !== null &&
+            maxX !== null &&
+            maxY !== null &&
+            minX <= maxX &&
+            minY <= maxY
+            ? { minX, minY, maxX, maxY }
+            : null
+    }
+
+    /**
+     * Converts one value to a finite number or null.
+     * @param {unknown} value Number candidate.
+     * @returns {number | null} Finite number or null.
+     */
+    static #finite(value) {
+        if (value === undefined || value === null || value === '') return null
+        const number = Number(value)
+        return Number.isFinite(number) ? number : null
+    }
+
+    /**
+     * Converts one value to a finite number with fallback.
+     * @param {unknown} value Number candidate.
+     * @param {number} fallback Fallback number.
+     * @returns {number} Finite number.
+     */
+    static #number(value, fallback) {
+        return PcbInteractionBounds.#finite(value) ?? fallback
+    }
+}