circuitjson-toolkit 1.1.2 → 1.2.1

package/README.md

@@ -49,6 +49,18 @@ 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).
+
+Version 1.2.1 keeps large canonical documents and multi-document projects
+inside explicit worker budgets. Selected extensions may contain up to four
+million structured items, while exact project envelopes receive independent
+per-document, project-metadata, aggregate-byte, and repeated-work limits. See
+the [1.2.1 release notes](docs/release-notes-v1.2.1.md).
+
 Before 1.1.0:
 
 ```js
@@ -82,6 +94,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
@@ -92,7 +106,7 @@ const model = document.model
 - Strict `ecad-toolkit.worker.v1` parsing/project protocol with progress,
   cancellation, and controlled buffer transfer
 - One-pass ownership for selected source extensions, with a separate 128 MiB /
-  2,000,000-item bound and exact direct/worker result parity
+  4,000,000-item bound and exact direct/worker result parity
 - Machine-readable capability inventory and packed downstream conformance
   harness
 - Explicit `/extensions` surface retaining every previous specialized API
@@ -193,11 +207,14 @@ falls back to direct execution only when worker construction is unavailable;
 explicit worker and runtime failures remain visible.
 
 Selected source-native extensions are captured once into an immutable owned
-snapshot. Their separate 128 MiB payload and 2,000,000-item ceilings permit
-realistic renderer/model graphs without weakening the worker protocol's 250 MB
-total-result ceiling; an over-limit extension fails visibly instead of being
-silently truncated. Binary extension values remain byte-backed and return
-defensive copies instead of expanding into JavaScript number arrays.
+snapshot. Their separate 128 MiB payload and 4,000,000-item ceilings permit
+realistic renderer/model graphs. Canonical standalone documents remain within
+a 250 MB result ceiling, while exact multi-document project envelopes use a
+256 MiB aggregate ceiling plus independent 250 MB per-document and metadata
+ceilings. Item and repeated-alias work budgets remain separately bounded; an
+over-limit extension or result fails visibly instead of being silently
+truncated. Binary extension values remain byte-backed and return defensive
+copies instead of expanding into JavaScript number arrays.
 When extensions are disabled, native documents and projects return the exact
 empty map `{}`. Bounded ZIP consumers can preflight local/central filenames and
 CRC32/size metadata with
@@ -310,6 +327,8 @@ 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)
+- [1.2.1 release notes](docs/release-notes-v1.2.1.md)
 - [Library scope](spec/library-scope.md)
 
 ## Package scope

package/docs/api.md

@@ -53,12 +53,13 @@ make the common shape smaller.
 
 Validated source documents own selected extension values as one deeply
 immutable, descriptor-safe snapshot. This uses a distinct 128 MiB payload and
-2,000,000-item ceiling so large native renderer graphs do not inherit the
+4,000,000-item ceiling so large native renderer graphs do not inherit the
 compact metadata limit. The shared worker protocol applies the same ownership
-boundary after structured cloning and retains its 250 MB whole-result ceiling.
-Binary values preserve their `ArrayBuffer`/typed-view shape behind defensive
-copy access, so payload bytes do not inflate into one JavaScript number per
-byte.
+boundary after structured cloning. Canonical standalone documents retain a
+250 MB byte ceiling; exact multi-document projects use a 256 MiB aggregate
+ceiling with independent 250 MB document and project-metadata limits. Binary
+values preserve their `ArrayBuffer`/typed-view shape behind defensive copy
+access, so payload bytes do not inflate into one JavaScript number per byte.
 
 ### Errors
 
@@ -144,6 +145,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 +167,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

@@ -102,15 +102,19 @@ must not duplicate the CircuitJSON model or keep a renamed renderer model.
 Default parsing excludes raw/base64/full-payload graphs.
 
 When a caller explicitly selects a native extension, the toolkit captures and
-freezes that graph once under a distinct ceiling of 2,000,000 structured items
+freezes that graph once under a distinct ceiling of 4,000,000 structured items
 and 128 MiB of string or binary content. The ceiling is shared across the
-selected namespace, applies equally after worker transfer, and remains below
-the worker's 250 MB whole-result limit. General document metadata keeps its
-smaller budget, so a large native projection cannot consume the canonical
-metadata allowance. Oversized graphs are rejected; they are never truncated or
-partially retained. Binary extension values remain byte-backed with their
-common buffer/view type and are exposed as defensive copies, preserving
-mutation isolation without expanding bytes into plain numeric arrays.
+selected namespace and applies equally after worker transfer. Canonical
+standalone documents allow the extension plus envelope overhead within five
+million result values and 250 MB. Exact project envelopes allow eight million
+aggregate values and 256 MiB, while each document stays within five million
+values and 250 MB and non-document project metadata stays within two million
+values and 250 MB. Reused graphs are charged independently to each local scope,
+and repeated accounting work is itself bounded by the aggregate project
+budget. Oversized graphs are rejected; they are never truncated or partially
+retained. Binary extension values remain byte-backed with their common
+buffer/view type and are exposed as defensive copies, preserving mutation
+isolation without expanding bytes into plain numeric arrays.
 
 Supported pre-union CircuitJSON aliases may be projected through
 `CircuitJsonDocument.normalizeModel()`. The copy-on-write form preserves exact
@@ -119,6 +123,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/docs/release-notes-v1.2.1.md

@@ -0,0 +1,26 @@
+# circuitjson-toolkit 1.2.1
+
+## Large canonical worker results
+
+This patch release keeps valid high-fidelity documents and multi-document
+projects inside explicit, format-neutral worker limits:
+
+- Selected native extensions may contain up to 4,000,000 structured items and
+  128 MiB of string or binary content.
+- A canonical standalone document may contain up to 5,000,000 result values
+  within the existing 250 MB byte ceiling.
+- An exact canonical project may contain up to 8,000,000 aggregate values and
+  256 MiB, while every document retains its own 5,000,000-value and 250 MB
+  limits.
+- Non-document project metadata retains the generic 2,000,000-value and 250 MB
+  limits.
+
+Elevated budgets require the complete canonical document or project envelope;
+a schema string alone does not change generic result limits. Reused object
+graphs are charged independently to document and project-metadata scopes in a
+property-order-independent way. Repeated alias-accounting work is also capped
+by the project aggregate budget, keeping transport time bounded.
+
+No public class, method, package subpath, parameter, or result field is removed
+or renamed. Oversized results continue to fail visibly rather than being
+truncated.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "circuitjson-toolkit",
-    "version": "1.1.2",
+    "version": "1.2.1",
     "description": "Canonical CircuitJSON parsing, project, rendering, query, manufacturing, simulation, and scene contracts",
     "keywords": [
         "circuitjson",
@@ -53,6 +53,8 @@
         "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/release-notes-v1.2.1.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/CircuitJsonReadOnlyDocument.mjs

@@ -13,7 +13,7 @@ const METADATA_BUDGETS = new WeakMap()
 const EXTENSION_METADATA_LIMITS = Object.freeze({
     label: 'Canonical extension data',
     maxBytes: 128 * 1024 * 1024,
-    maxItems: 2_000_000,
+    maxItems: 4_000_000,
     preserveBinary: true
 })
 const ASSET_SCALAR_FIELDS = new Set([

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