circuitjson-toolkit 1.1.2 → 1.2.0

package/README.md

@@ -49,6 +49,12 @@ theme fallback, and generic component and symbol bodies explicitly use the
 ECAD Forge schematic palette. See the
 [1.1.2 release notes](docs/release-notes-v1.1.2.md).
 
+Version 1.2.0 extends the canonical PCB contract with validated source text
+fidelity, rotated drilled-pad bounds, and rounded-pad corner radii. Worker and
+metadata ownership traversals now support deeply nested, valid ECAD documents
+up to 256 levels. See the
+[1.2.0 release notes](docs/release-notes-v1.2.0.md).
+
 Before 1.1.0:
 
 ```js
@@ -82,6 +88,8 @@ const model = document.model
   defaults
 - Asset-backed `schematic_image` rows and hierarchical
   `schematic_sheet_symbol` rows with shared bounds and SVG behavior
+- Validated PCB text source-fidelity fields for independent font dimensions,
+  exact nine-position anchors, visibility, layer provenance, and native type
 - Reusable exact PCB interaction and spatial indexes
 - Query, manufacturing, and injected simulation services
 - Data-only, millimeter-based, right-handed Z-up PCB 3D scenes
@@ -310,6 +318,7 @@ copy while keeping sync, direct async, and worker results mutation-isolated.
 - [1.1.0 release notes](docs/release-notes-v1.1.0.md)
 - [1.1.1 release notes](docs/release-notes-v1.1.1.md)
 - [1.1.2 release notes](docs/release-notes-v1.1.2.md)
+- [1.2.0 release notes](docs/release-notes-v1.2.0.md)
 - [Library scope](spec/library-scope.md)
 
 ## Package scope

package/docs/api.md

@@ -144,6 +144,15 @@ The canonical union is the pinned upstream schema plus the source-neutral
 snapshot, `canonicalElementTypes()` for all accepted types, and
 `extensionElementTypes()` for the toolkit-owned additions.
 
+Pinned PCB text rows may also retain the validated source-fidelity fields
+`font_width`, `font_height`, `stroke_width`, `source_anchor_alignment`,
+`is_hidden`, `source_layer`, `source_type`, and `source_text_kind`. Board note
+rotation uses `ccw_rotation`; fabrication note mirroring uses `is_mirrored`.
+Canonical upstream properties remain authoritative when they exist. In
+particular, `pcb_note_text.anchor_alignment` keeps the narrower upstream enum,
+while `source_anchor_alignment` can preserve the exact nine-position source
+anchor for lossless rendering.
+
 The projection covers legacy schematic table row/column/span geometry, PCB
 artwork `points`/`width` paths, pad-clearance diagnostic relations, courtyard
 line/path/polygon forms, outer-layer aliases, and retained stroke dash fields.
@@ -157,7 +166,12 @@ rendering and interaction consumers. Polygon `pad_outline` points determine
 rotation-local outer width and height; pill drill width, height, diameter, and
 board-space rotation remain distinct from outer-pad rotation. Legal
 `outer_width`, `outer_height`, `rect_ccw_rotation`, and `hole_ccw_rotation`
-variants are preserved. Import this retained source-neutral helper from
+variants are preserved. The returned geometry includes the parsed rectangular
+`cornerRadius`. Rotated rectangular bounds use the exact visible
+rounded-rectangle support dimensions, with the effective radius clamped from
+zero through half the smaller outer dimension. A zero radius therefore retains
+sharp-rectangle bounds, while a half-minor-dimension radius has the same support
+extent as a pill. Import this retained source-neutral helper from
 `circuitjson-toolkit/extensions`.
 
 Packed release checks reject any missing or additional root export.

package/docs/model-format.md

@@ -119,6 +119,40 @@ validation/proof boundary. Table cell geometry, PCB artwork routes,
 pad-clearance relations, courtyards, layer aliases, and stroke dashes are
 derived structurally and never from a source filename or fixture identity.
 
+### PCB text source fidelity
+
+`pcb_note_text`, `pcb_fabrication_note_text`, and `pcb_silkscreen_text` retain
+canonical upstream fields first. Source formats with independent width and
+height, edge-center anchors, native layer names, or hidden-text state may add:
+
+```js
+{
+    type: 'pcb_note_text',
+    pcb_note_text_id: 'board_text_1',
+    text: 'BOARD MARK',
+    anchor_position: { x: 12.5, y: 4.25 },
+    layer: 'bottom',
+    ccw_rotation: 28,
+    font_size: 1.2,
+    font_width: 0.8,
+    font_height: 1.2,
+    stroke_width: 0.12,
+    anchor_alignment: 'center',
+    source_anchor_alignment: 'center_left',
+    is_mirrored_from_top_view: true,
+    is_hidden: false,
+    source_layer: 'B.SilkS',
+    source_type: 'gr_text'
+}
+```
+
+The extension fields are validated and preserved through immutable document
+preparation. Lengths accept the same numeric millimeter or unit-suffixed style
+as canonical dimensions. `source_anchor_alignment` accepts all nine standard
+anchor positions. The narrower upstream anchor on board and fabrication notes
+must remain `center` or a corner; renderers use the source anchor when they
+need the exact edge-center placement.
+
 ## Assets and diagnostics
 
 Assets have exact `id`, `kind`, `name`, `mediaType`, `byteLength`, `data`, and

package/docs/release-notes-v1.2.0.md

@@ -0,0 +1,33 @@
+# circuitjson-toolkit 1.2.0
+
+## Canonical PCB fidelity
+
+This minor release expands the shared CircuitJSON contract used by the Gerber,
+Altium, KiCad, and 3D viewer packages. Existing canonical fields remain
+authoritative, while source formats can retain exact rendering information in
+validated, source-neutral extension fields.
+
+### API additions
+
+- `pcb_note_text`, `pcb_fabrication_note_text`, and `pcb_silkscreen_text` may
+  retain independent `font_width` and `font_height`, `stroke_width`, the exact
+  nine-position `source_anchor_alignment`, `is_hidden`, `source_layer`,
+  `source_type`, and `source_text_kind`.
+- Board-note `ccw_rotation` and fabrication-note `is_mirrored` are validated
+  when present, so downstream renderers can consume the original orientation
+  without source-format adapters.
+- `CircuitJsonPcbHolePrimitiveModel.build()` now returns `cornerRadius` and
+  computes board-space bounds for rotated rectangles and pills instead of
+  treating their local width and height as axis-aligned.
+
+### Behavior and performance
+
+- Structured metadata snapshots and worker request graphs accept valid nesting
+  up to 256 levels, matching the deeper native data graphs emitted by ECAD
+  parsers while retaining the existing item and byte limits.
+- The new fields pass through the existing immutable document ownership and
+  validation boundaries; no viewer or host-app workaround is required.
+
+No existing public class, method, package subpath, parameter, or document
+envelope is removed in this release. Consumers that exhaustively validate PCB
+text or primitive return objects should accept the additive fields above.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "circuitjson-toolkit",
-    "version": "1.1.2",
+    "version": "1.2.0",
     "description": "Canonical CircuitJSON parsing, project, rendering, query, manufacturing, simulation, and scene contracts",
     "keywords": [
         "circuitjson",
@@ -53,6 +53,7 @@
         "docs/release-notes-v1.1.0.md",
         "docs/release-notes-v1.1.1.md",
         "docs/release-notes-v1.1.2.md",
+        "docs/release-notes-v1.2.0.md",
         "docs/testing.md",
         "spec",
         "LICENSE",

package/src/core/CircuitJsonPcbHolePrimitiveModel.mjs

@@ -29,19 +29,25 @@ export class CircuitJsonPcbHolePrimitiveModel {
             shape,
             size
         )
-        const bounds = points.length
-            ? CircuitJsonPcbPrimitiveGeometry.pointsBounds(points)
-            : CircuitJsonPcbPrimitiveGeometry.centerBounds(
-                  center,
-                  size.width,
-                  size.height
-              )
+        const cornerRadius = CircuitJsonUnits.length(
+            element.rect_border_radius ?? element.corner_radius,
+            0
+        )
+        const bounds = CircuitJsonPcbHolePrimitiveModel.#outerBounds(
+            center,
+            size,
+            shape,
+            rotation,
+            cornerRadius,
+            points
+        )
 
         return {
             shape,
             width: size.width,
             height: size.height,
             diameter: Math.max(size.width, size.height),
+            cornerRadius,
             holeShape: hole.shape,
             holeDiameter: hole.diameter,
             holeWidth: hole.width,
@@ -123,6 +129,64 @@ export class CircuitJsonPcbHolePrimitiveModel {
         }
     }
 
+    /**
+     * Resolves the board-space axis-aligned bounds of the visible outer shape.
+     * @param {{ x: number, y: number }} center Shape center.
+     * @param {{ width: number, height: number }} size Local shape size.
+     * @param {'circle' | 'pill' | 'polygon' | 'rect'} shape Shape kind.
+     * @param {number} rotation Counter-clockwise rotation in degrees.
+     * @param {number} cornerRadius Parsed rectangular corner radius.
+     * @param {{ x: number, y: number }[]} points Polygon points.
+     * @returns {object} Board-space axis-aligned bounds.
+     */
+    static #outerBounds(center, size, shape, rotation, cornerRadius, points) {
+        if (points.length) {
+            return CircuitJsonPcbPrimitiveGeometry.pointsBounds(points)
+        }
+        if (shape === 'circle' || rotation === 0) {
+            return CircuitJsonPcbPrimitiveGeometry.centerBounds(
+                center,
+                size.width,
+                size.height
+            )
+        }
+
+        const radians = (rotation * Math.PI) / 180
+        if (shape === 'pill') {
+            const minor = Math.min(size.width, size.height)
+            const lineLength = Math.max(size.width, size.height) - minor
+            const axisRadians =
+                radians + (size.height > size.width ? Math.PI / 2 : 0)
+            const width = Math.abs(Math.cos(axisRadians)) * lineLength + minor
+            const height = Math.abs(Math.sin(axisRadians)) * lineLength + minor
+            return CircuitJsonPcbPrimitiveGeometry.centerBounds(
+                center,
+                width,
+                height
+            )
+        }
+
+        const radius = Math.max(
+            0,
+            Math.min(cornerRadius, Math.min(size.width, size.height) / 2)
+        )
+        const innerWidth = size.width - radius * 2
+        const innerHeight = size.height - radius * 2
+        const width =
+            Math.abs(Math.cos(radians)) * innerWidth +
+            Math.abs(Math.sin(radians)) * innerHeight +
+            radius * 2
+        const height =
+            Math.abs(Math.sin(radians)) * innerWidth +
+            Math.abs(Math.cos(radians)) * innerHeight +
+            radius * 2
+        return CircuitJsonPcbPrimitiveGeometry.centerBounds(
+            center,
+            width,
+            height
+        )
+    }
+
     /**
      * Resolves polygonal outer pad points.
      * @param {object} element Drilled PCB element.

package/src/core/CircuitJsonToolkitElementSchema.mjs

@@ -1,7 +1,25 @@
+import { optionalAngle, optionalLength } from './CircuitJsonUnitParsers.mjs'
+
 const TOOLKIT_ELEMENT_TYPES = new Set([
     'schematic_image',
     'schematic_sheet_symbol'
 ])
+const PCB_TEXT_EXTENSION_TYPES = new Set([
+    'pcb_note_text',
+    'pcb_fabrication_note_text',
+    'pcb_silkscreen_text'
+])
+const PCB_TEXT_ANCHOR_ALIGNMENTS = new Set([
+    'top_left',
+    'top_center',
+    'top_right',
+    'center_left',
+    'center',
+    'center_right',
+    'bottom_left',
+    'bottom_center',
+    'bottom_right'
+])
 
 /**
  * Validates canonical toolkit element types that are newer than the pinned
@@ -45,6 +63,22 @@ export class CircuitJsonToolkitElementSchema {
               ]
     }
 
+    /**
+     * Validates source-fidelity fields retained on pinned upstream elements.
+     * @param {Record<string, any>} value Element value.
+     * @param {string} type Element type.
+     * @param {string} [location] Human-readable location suffix.
+     * @returns {string[]} Empty on success or one validation error.
+     */
+    static validateExtensions(value, type, location = '') {
+        if (!PCB_TEXT_EXTENSION_TYPES.has(type)) return []
+        return CircuitJsonToolkitElementSchema.#pcbTextExtensions(value, type)
+            ? []
+            : [
+                  `CircuitJSON element ${type}${location} does not match the canonical toolkit extension schema.`
+              ]
+    }
+
     /**
      * Validates an asset-backed schematic image.
      * @param {Record<string, any>} value Image element.
@@ -156,6 +190,68 @@ export class CircuitJsonToolkitElementSchema {
         )
     }
 
+    /**
+     * Validates exact PCB text dimensions, alignment, visibility, and source provenance.
+     * @param {Record<string, any>} value Text element.
+     * @param {string} type Text element type.
+     * @returns {boolean} Whether the extension fields match their contract.
+     */
+    static #pcbTextExtensions(value, type) {
+        for (const field of ['font_width', 'font_height']) {
+            if (
+                value[field] !== undefined &&
+                !CircuitJsonToolkitElementSchema.#positiveLength(value[field])
+            ) {
+                return false
+            }
+        }
+        if (
+            value.stroke_width !== undefined &&
+            !CircuitJsonToolkitElementSchema.#nonNegativeLength(
+                value.stroke_width
+            )
+        ) {
+            return false
+        }
+        for (const field of [
+            'source_layer',
+            'source_type',
+            'source_text_kind'
+        ]) {
+            if (
+                value[field] !== undefined &&
+                !CircuitJsonToolkitElementSchema.#requiredString(value[field])
+            ) {
+                return false
+            }
+        }
+        if (
+            value.source_anchor_alignment !== undefined &&
+            !PCB_TEXT_ANCHOR_ALIGNMENTS.has(value.source_anchor_alignment)
+        ) {
+            return false
+        }
+        if (
+            value.is_hidden !== undefined &&
+            typeof value.is_hidden !== 'boolean'
+        ) {
+            return false
+        }
+        if (
+            type === 'pcb_note_text' &&
+            value.ccw_rotation !== undefined &&
+            (!CircuitJsonToolkitElementSchema.#unitScalar(value.ccw_rotation) ||
+                optionalAngle(value.ccw_rotation) === null)
+        ) {
+            return false
+        }
+        return !(
+            type === 'pcb_fabrication_note_text' &&
+            value.is_mirrored !== undefined &&
+            typeof value.is_mirrored !== 'boolean'
+        )
+    }
+
     /**
      * Validates a required non-empty string.
      * @param {unknown} value Candidate.
@@ -183,6 +279,37 @@ export class CircuitJsonToolkitElementSchema {
         return CircuitJsonToolkitElementSchema.#number(value) && value > 0
     }
 
+    /**
+     * Validates a positive CircuitJSON length with optional unit suffix.
+     * @param {unknown} value Candidate.
+     * @returns {boolean} Whether the length is positive.
+     */
+    static #positiveLength(value) {
+        if (!CircuitJsonToolkitElementSchema.#unitScalar(value)) return false
+        const length = optionalLength(value)
+        return length !== null && length > 0
+    }
+
+    /**
+     * Validates a non-negative CircuitJSON length with optional unit suffix.
+     * @param {unknown} value Candidate.
+     * @returns {boolean} Whether the length is non-negative.
+     */
+    static #nonNegativeLength(value) {
+        if (!CircuitJsonToolkitElementSchema.#unitScalar(value)) return false
+        const length = optionalLength(value)
+        return length !== null && length >= 0
+    }
+
+    /**
+     * Returns whether a unit field is a primitive parser input.
+     * @param {unknown} value Candidate.
+     * @returns {boolean} Whether the value can be parsed without coercion.
+     */
+    static #unitScalar(value) {
+        return typeof value === 'number' || typeof value === 'string'
+    }
+
     /**
      * Validates one finite point.
      * @param {unknown} value Candidate.

package/src/core/CircuitJsonUpstreamValidator.mjs

@@ -31,11 +31,16 @@ export class CircuitJsonUpstreamValidator {
             type === 'source_net'
                 ? CircuitJsonUpstreamValidator.#sourceNet(value)
                 : CircuitJsonUpstreamValidator.#matches(schema, value)
-        return matches
-            ? []
-            : [
-                  `CircuitJSON element ${type}${location} does not match the pinned upstream schema.`
-              ]
+        if (!matches) {
+            return [
+                `CircuitJSON element ${type}${location} does not match the pinned upstream schema.`
+            ]
+        }
+        return CircuitJsonToolkitElementSchema.validateExtensions(
+            value,
+            type,
+            location
+        )
     }
 
     /**

package/src/core/context/StructuredDataSnapshot.mjs

@@ -1,6 +1,6 @@
 import { BinaryDataSnapshot } from './BinaryDataSnapshot.mjs'
 
-const METADATA_MAX_DEPTH = 64
+const METADATA_MAX_DEPTH = 256
 const METADATA_MAX_ITEMS = 100_000
 const UNBOUNDED_METADATA_BYTES = Number.MAX_SAFE_INTEGER
 const DATE_GET_TIME = Date.prototype.getTime

package/src/core/worker/WorkerRequestData.mjs

@@ -52,7 +52,7 @@ const UINT8_ARRAY_CONSTRUCTOR = Uint8Array
 const UINT8_ARRAY_SET = Uint8Array.prototype.set
 const STRUCTURED_CLONE = globalThis.structuredClone
 const MAX_REQUEST_BYTES = 100_000_000
-const MAX_REQUEST_DEPTH = 64
+const MAX_REQUEST_DEPTH = 256
 const MAX_REQUEST_VALUES = 100_000
 const MAX_RESULT_BYTES = 250_000_000
 const MAX_RESULT_VALUES = 2_000_000