circuitjson-toolkit 1.0.16 → 1.1.0

package/src/core/scene3d/Scene3dDocumentMetadata.mjs

@@ -0,0 +1,167 @@
+/**
+ * Reads owned scene document metadata without accessors or object coercion.
+ */
+export class Scene3dDocumentMetadata {
+    /**
+     * Returns a primitive source format.
+     * @param {object} context Prepared document context.
+     * @returns {string} Source format.
+     */
+    static sourceFormat(context) {
+        const value = context.source?.format
+        if (value === undefined || value === null || value === '') {
+            return 'circuitjson'
+        }
+        if (typeof value !== 'string') {
+            throw new TypeError('CircuitJSON source format must be a string.')
+        }
+        return value
+    }
+
+    /**
+     * Returns a primitive source file name.
+     * @param {object} context Prepared document context.
+     * @returns {string} Source file name.
+     */
+    static sourceFileName(context) {
+        const value = context.source?.fileName
+        if (value === undefined || value === null) return ''
+        if (typeof value !== 'string') {
+            throw new TypeError('CircuitJSON source fileName must be a string.')
+        }
+        return value
+    }
+
+    /**
+     * Returns true when a source extension declares usable native scene data.
+     * @param {string} format Source format.
+     * @param {unknown} extension Source extension.
+     * @returns {boolean} Whether native scene data is declared.
+     */
+    static hasNativeExtension(format, extension) {
+        if (
+            format === 'circuitjson' ||
+            !extension ||
+            typeof extension !== 'object' ||
+            Array.isArray(extension)
+        ) {
+            return false
+        }
+        const metadata = extension.$meta
+        Scene3dDocumentMetadata.#validateExtensionMetadata(metadata)
+        const completeness = metadata?.completeness || 'none'
+        if (!['canonical', 'full'].includes(completeness)) return false
+        const included = metadata?.included || []
+        return (
+            included.some(
+                (feature) =>
+                    feature === 'scene3d' || feature.startsWith('scene3d.')
+            ) || Boolean(extension.scene3d)
+        )
+    }
+
+    /**
+     * Validates extension metadata as primitive owned data.
+     * @param {unknown} metadata Extension metadata candidate.
+     * @returns {void}
+     */
+    static #validateExtensionMetadata(metadata) {
+        if (metadata === undefined || metadata === null) return
+        if (typeof metadata !== 'object' || Array.isArray(metadata)) {
+            throw new TypeError(
+                'Scene extension metadata must be a plain data object.'
+            )
+        }
+        const prototype = Object.getPrototypeOf(metadata)
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError(
+                'Scene extension metadata must be a plain data object.'
+            )
+        }
+        for (const key of Reflect.ownKeys(metadata)) {
+            if (typeof key !== 'string') {
+                throw new TypeError(
+                    'Scene extension metadata keys must be strings.'
+                )
+            }
+            const descriptor = Object.getOwnPropertyDescriptor(metadata, key)
+            if (!descriptor || !Object.hasOwn(descriptor, 'value')) {
+                throw new TypeError(
+                    'Scene extension metadata must contain only data properties.'
+                )
+            }
+            Scene3dDocumentMetadata.#validateMetadataValue(
+                key,
+                descriptor.value
+            )
+        }
+    }
+
+    /**
+     * Validates one primitive metadata field or primitive array.
+     * @param {string} key Metadata field name.
+     * @param {unknown} value Metadata value.
+     * @returns {void}
+     */
+    static #validateMetadataValue(key, value) {
+        if (key === 'schema' || key === 'completeness') {
+            if (typeof value === 'string') return
+            throw new TypeError(`Scene extension ${key} must be a string.`)
+        }
+        if (key === 'included' || key === 'omitted') {
+            if (
+                Array.isArray(value) &&
+                Scene3dDocumentMetadata.#primitiveArray(value, true)
+            ) {
+                return
+            }
+            throw new TypeError(
+                `Scene extension ${key} must contain only strings.`
+            )
+        }
+        if (Array.isArray(value)) {
+            if (Scene3dDocumentMetadata.#primitiveArray(value, false)) return
+        } else if (Scene3dDocumentMetadata.#isPrimitive(value)) {
+            return
+        }
+        throw new TypeError(
+            `Scene extension ${key} must contain only primitive data.`
+        )
+    }
+
+    /**
+     * Tests a dense array of primitive extension entries.
+     * @param {unknown[]} values Metadata entries.
+     * @param {boolean} stringsOnly Whether every entry must be a string.
+     * @returns {boolean} Whether all entries are accepted primitives.
+     */
+    static #primitiveArray(values, stringsOnly) {
+        for (let index = 0; index < values.length; index += 1) {
+            const value = values[index]
+            if (
+                stringsOnly
+                    ? typeof value !== 'string'
+                    : !Scene3dDocumentMetadata.#isPrimitive(value)
+            ) {
+                return false
+            }
+        }
+        return true
+    }
+
+    /**
+     * Tests one clone-safe primitive without coercion.
+     * @param {unknown} value Metadata value.
+     * @returns {boolean} Whether the value is a supported primitive.
+     */
+    static #isPrimitive(value) {
+        return (
+            value === null ||
+            value === undefined ||
+            ['string', 'number', 'boolean', 'bigint'].includes(typeof value)
+        )
+    }
+}
+
+Object.freeze(Scene3dDocumentMetadata.prototype)
+Object.freeze(Scene3dDocumentMetadata)

package/src/core/scene3d/Scene3dFreeze.mjs

@@ -0,0 +1,37 @@
+/**
+ * Freezes data-only scene graphs iteratively without recursing into binary data.
+ * @param {unknown} value Scene value.
+ * @returns {any} The same value.
+ */
+export function freezeScene(value) {
+    if (!value || typeof value !== 'object') return value
+    const seen = new WeakSet()
+    const pending = [value]
+    const ordered = []
+
+    while (pending.length) {
+        const current = pending.pop()
+        if (
+            !current ||
+            typeof current !== 'object' ||
+            seen.has(current) ||
+            current instanceof ArrayBuffer ||
+            ArrayBuffer.isView(current)
+        ) {
+            continue
+        }
+        seen.add(current)
+        ordered.push(current)
+        for (const key of Reflect.ownKeys(current)) {
+            const descriptor = Object.getOwnPropertyDescriptor(current, key)
+            if (descriptor && Object.hasOwn(descriptor, 'value')) {
+                pending.push(descriptor.value)
+            }
+        }
+    }
+
+    for (let index = ordered.length - 1; index >= 0; index -= 1) {
+        if (!Object.isFrozen(ordered[index])) Object.freeze(ordered[index])
+    }
+    return value
+}

package/src/core/scene3d/Scene3dIdRegistry.mjs

@@ -0,0 +1,34 @@
+import { ToolkitError } from '../contracts/ToolkitError.mjs'
+
+/**
+ * Enforces unambiguous identifiers within canonical scene collections.
+ */
+export class Scene3dIdRegistry {
+    /**
+     * Rejects duplicate non-empty identifiers in one output collection.
+     * @param {string} collection Canonical collection name.
+     * @param {object[]} rows Canonical rows.
+     * @returns {void}
+     */
+    static assertUnique(collection, rows) {
+        const ids = new Set()
+        for (const row of rows) {
+            const id = row.id
+            if (!id || !ids.has(id)) {
+                if (id) ids.add(id)
+                continue
+            }
+            throw new ToolkitError(
+                `Scene ${collection} id is ambiguous: ${id}.`,
+                {
+                    code: 'ERR_SCENE_ID_AMBIGUOUS',
+                    category: 'unsupported',
+                    details: { collection, id }
+                }
+            )
+        }
+    }
+}
+
+Object.freeze(Scene3dIdRegistry.prototype)
+Object.freeze(Scene3dIdRegistry)

package/src/core/scene3d/Scene3dInputPreflight.mjs

@@ -0,0 +1,193 @@
+import { ToolkitError } from '../contracts/ToolkitError.mjs'
+import { CircuitJsonReadOnlyDocument } from '../context/CircuitJsonReadOnlyDocument.mjs'
+import { Scene3dOptions } from './Scene3dOptions.mjs'
+
+const DOCUMENT_SCHEMA = 'ecad-toolkit.document.v1'
+const ENVELOPE_FIELDS = ['schema', 'model', 'source', 'extensions', 'assets']
+
+/**
+ * Rejects unsafe envelopes and resident asset limits before context copying.
+ */
+export class Scene3dInputPreflight {
+    /**
+     * Preflights one document envelope without invoking caller accessors.
+     * @param {unknown} input Scene input.
+     * @param {ReturnType<Scene3dOptions['normalize']>} options Scene options.
+     * @returns {boolean} Whether envelope assets were preflighted.
+     */
+    static check(input, options) {
+        if (Array.isArray(input) || !input || typeof input !== 'object') {
+            return false
+        }
+        const schema = Scene3dInputPreflight.#descriptor(input, 'schema')
+        if (!schema) return false
+        if (!Object.hasOwn(schema, 'value')) {
+            throw new TypeError(
+                'Canonical document schema must be an own data property.'
+            )
+        }
+        if (schema.value !== DOCUMENT_SCHEMA) return false
+
+        const values = Object.create(null)
+        for (const field of ENVELOPE_FIELDS) {
+            const descriptor = Scene3dInputPreflight.#descriptor(input, field)
+            if (!descriptor) {
+                if (field === 'schema' || field === 'model') {
+                    throw new TypeError(
+                        `Canonical document ${field} must be an own data property.`
+                    )
+                }
+                values[field] = undefined
+                continue
+            }
+            if (!Object.hasOwn(descriptor, 'value')) {
+                throw new TypeError(
+                    `Canonical document ${field} must be an own data property.`
+                )
+            }
+            values[field] = descriptor.value
+        }
+        Scene3dInputPreflight.checkAssets(values.assets, options)
+        return true
+    }
+
+    /**
+     * Applies one global metadata and resident-byte budget to document assets.
+     * @param {unknown} values Canonical document assets.
+     * @param {ReturnType<Scene3dOptions['normalize']>} options Scene options.
+     * @returns {object[]} Captured assets in authored order.
+     */
+    static checkAssets(values, options) {
+        const owner = values === undefined ? [] : values
+        const assets = Scene3dOptions.dataArray(
+            owner,
+            'Scene assets',
+            Scene3dOptions.maxAssetCount
+        )
+        const metadataBudget =
+            CircuitJsonReadOnlyDocument.createMetadataBudget()
+        let total = 0
+        for (let index = 0; index < assets.length; index += 1) {
+            const asset = assets[index]
+            const captured = CircuitJsonReadOnlyDocument.captureAsset(
+                asset,
+                metadataBudget,
+                true,
+                (bytes, identity) => {
+                    const assetId =
+                        typeof identity.id === 'string' ? identity.id : ''
+                    if (bytes > options.maxAssetBytes) {
+                        throw Scene3dInputPreflight.#limit(
+                            bytes,
+                            options.maxAssetBytes,
+                            'asset',
+                            assetId
+                        )
+                    }
+                    if (total + bytes > options.maxTotalAssetBytes) {
+                        throw Scene3dInputPreflight.#limit(
+                            total + bytes,
+                            options.maxTotalAssetBytes,
+                            'total',
+                            assetId
+                        )
+                    }
+                }
+            )
+            assets[index] = captured
+            Scene3dInputPreflight.#replaceAsset(owner, index, asset, captured)
+            const bytes = CircuitJsonReadOnlyDocument.assetPayloadByteLength(
+                captured,
+                metadataBudget
+            )
+            const assetId = Scene3dInputPreflight.#assetId(captured)
+            if (bytes > options.maxAssetBytes) {
+                throw Scene3dInputPreflight.#limit(
+                    bytes,
+                    options.maxAssetBytes,
+                    'asset',
+                    assetId
+                )
+            }
+            total += bytes
+            if (total > options.maxTotalAssetBytes) {
+                throw Scene3dInputPreflight.#limit(
+                    total,
+                    options.maxTotalAssetBytes,
+                    'total',
+                    assetId
+                )
+            }
+        }
+        return assets
+    }
+
+    /**
+     * Replaces one caller array item with the exact preflight snapshot.
+     * @param {object[]} owner Original dense asset array.
+     * @param {number} index Asset index.
+     * @param {object} asset Original asset.
+     * @param {object} captured Owned asset snapshot.
+     * @returns {void}
+     */
+    static #replaceAsset(owner, index, asset, captured) {
+        if (asset === captured) return
+        let descriptor
+        try {
+            descriptor = Object.getOwnPropertyDescriptor(owner, String(index))
+            Object.defineProperty(owner, String(index), {
+                ...descriptor,
+                value: captured
+            })
+        } catch {
+            throw new TypeError(
+                'Canonical document assets could not be captured safely.'
+            )
+        }
+    }
+
+    /**
+     * Reads one own descriptor and normalizes proxy failures.
+     * @param {object} owner Envelope candidate.
+     * @param {string} key Field name.
+     * @returns {PropertyDescriptor | undefined} Own descriptor.
+     */
+    static #descriptor(owner, key) {
+        try {
+            return Object.getOwnPropertyDescriptor(owner, key)
+        } catch {
+            throw new TypeError(
+                'Canonical document could not be inspected safely.'
+            )
+        }
+    }
+
+    /**
+     * Reads one validated asset identifier without coercion.
+     * @param {object} asset Canonical asset.
+     * @returns {string} Asset id when present.
+     */
+    static #assetId(asset) {
+        const descriptor = Scene3dInputPreflight.#descriptor(asset, 'id')
+        return typeof descriptor?.value === 'string' ? descriptor.value : ''
+    }
+
+    /**
+     * Creates a typed preflight byte-limit error.
+     * @param {number} actual Actual resident bytes.
+     * @param {number} maximum Configured maximum.
+     * @param {'asset' | 'total'} scope Limit scope.
+     * @param {string} assetId Current asset id.
+     * @returns {ToolkitError} Typed limit error.
+     */
+    static #limit(actual, maximum, scope, assetId) {
+        return new ToolkitError('Scene asset bytes exceed the safe limit.', {
+            code: 'ERR_ASSET_LIMIT',
+            category: 'unsupported',
+            details: { assetId, scope, actual, maximum }
+        })
+    }
+}
+
+Object.freeze(Scene3dInputPreflight.prototype)
+Object.freeze(Scene3dInputPreflight)

package/src/core/scene3d/Scene3dMaterials.mjs

@@ -0,0 +1,58 @@
+import { freezeScene } from './Scene3dFreeze.mjs'
+
+/**
+ * Builds canonical scene materials while preserving CircuitJSON appearance.
+ */
+export class Scene3dMaterials {
+    /**
+     * Builds one frozen material list from the primary board appearance.
+     * @param {object[]} boards PCB board elements.
+     * @returns {object[]} Canonical materials.
+     */
+    static build(boards) {
+        const board = boards[0] || {}
+        return freezeScene([
+            {
+                id: 'board-core',
+                kind: String(board.material || 'board'),
+                color: Scene3dMaterials.#color(
+                    board.solder_mask_color,
+                    '#2f7d32'
+                ),
+                opacity: 1
+            },
+            {
+                id: 'component-body',
+                kind: 'component',
+                color: '#252525',
+                opacity: 1
+            },
+            {
+                id: 'copper',
+                kind: 'copper',
+                color: '#b87333',
+                opacity: 1
+            },
+            {
+                id: 'silkscreen',
+                kind: 'silkscreen',
+                color: Scene3dMaterials.#color(
+                    board.silkscreen_color,
+                    '#f3f3e7'
+                ),
+                opacity: 1
+            }
+        ])
+    }
+
+    /**
+     * Preserves one bounded color token or returns the canonical fallback.
+     * @param {unknown} value Color candidate.
+     * @param {string} fallback Fallback color.
+     * @returns {string} Color token.
+     */
+    static #color(value, fallback) {
+        const color = String(value || '').trim()
+        return color && color.length <= 64 ? color : fallback
+    }
+}

package/src/core/scene3d/Scene3dModelReference.mjs

@@ -0,0 +1,134 @@
+import { ToolkitError } from '../contracts/ToolkitError.mjs'
+
+const MODEL_FIELDS = [
+    ['model_obj_url', 'obj'],
+    ['model_stl_url', 'stl'],
+    ['model_3mf_url', '3mf'],
+    ['model_gltf_url', 'gltf'],
+    ['model_glb_url', 'glb'],
+    ['model_step_url', 'step'],
+    ['model_wrl_url', 'wrl']
+]
+
+/**
+ * Normalizes canonical CAD component model references.
+ */
+export class Scene3dModelReference {
+    /**
+     * Resolves the first canonical CAD model reference by field precedence.
+     * @param {object} cadComponent CAD component element.
+     * @returns {{ name: string, format: string, mediaType: string, requiresAsset: boolean, inlineModel?: unknown, generator?: string } | null} Model reference.
+     */
+    static fromCadComponent(cadComponent) {
+        for (const [field, format] of MODEL_FIELDS) {
+            const name = String(cadComponent[field] || '').trim()
+            if (name) {
+                return {
+                    name: Scene3dModelReference.#boundedName(name),
+                    format,
+                    mediaType: Scene3dModelReference.#mediaType(format),
+                    requiresAsset: true
+                }
+            }
+        }
+        const embedded = cadComponent.model_asset
+        if (embedded && typeof embedded === 'object') {
+            const name = String(
+                embedded.project_relative_path || embedded.url || ''
+            ).trim()
+            if (name) {
+                const format = Scene3dModelReference.#formatFromName(name)
+                return {
+                    name: Scene3dModelReference.#boundedName(name),
+                    format,
+                    mediaType: String(
+                        embedded.mimetype ||
+                            Scene3dModelReference.#mediaType(format)
+                    ),
+                    requiresAsset: true
+                }
+            }
+        }
+        if (
+            Object.hasOwn(cadComponent, 'model_jscad') &&
+            cadComponent.model_jscad !== undefined
+        ) {
+            return {
+                name: '',
+                format: 'jscad',
+                mediaType: 'application/vnd.jscad+json',
+                requiresAsset: false,
+                inlineModel: cadComponent.model_jscad
+            }
+        }
+        const footprinter = String(cadComponent.footprinter_string || '').trim()
+        if (footprinter) {
+            return {
+                name: '',
+                format: 'footprinter',
+                mediaType: 'application/x-footprinter',
+                requiresAsset: false,
+                generator: Scene3dModelReference.#boundedName(footprinter)
+            }
+        }
+        if (cadComponent.size || cadComponent.show_as_bounding_box === true) {
+            return {
+                name: '',
+                format: 'bounding-box',
+                mediaType: 'application/x-ecad-bounding-box',
+                requiresAsset: false
+            }
+        }
+        return null
+    }
+
+    /**
+     * Normalizes a comparison-only asset path.
+     * @param {unknown} value Path value.
+     * @returns {string} Normalized path.
+     */
+    static normalizedPath(value) {
+        return String(value || '')
+            .replaceAll('\\', '/')
+            .replace(/^\.\//u, '')
+    }
+
+    /**
+     * Bounds one asset reference string.
+     * @param {string} name Asset name.
+     * @returns {string} Bounded name.
+     */
+    static #boundedName(name) {
+        if (name.length > 4096) {
+            throw new ToolkitError('Scene asset name exceeds the safe limit.', {
+                code: 'ERR_ASSET_LIMIT',
+                category: 'unsupported',
+                details: { maximumCharacters: 4096 }
+            })
+        }
+        return name
+    }
+
+    /**
+     * Resolves a model format from a file suffix.
+     * @param {string} name Asset name.
+     * @returns {string} Lowercase model format.
+     */
+    static #formatFromName(name) {
+        const suffix = name.split(/[?#]/u)[0].split('.').pop()
+        return String(suffix || 'model').toLowerCase()
+    }
+
+    /**
+     * Resolves a common model media type.
+     * @param {string} format Model format.
+     * @returns {string} Media type.
+     */
+    static #mediaType(format) {
+        return format === 'gltf'
+            ? 'model/gltf+json'
+            : format === 'glb'
+              ? 'model/gltf-binary'
+              : `model/${format}`
+    }
+}