pcb-scene3d-viewer 1.1.49 → 1.2.0

package/README.md

@@ -7,12 +7,13 @@ SPDX-License-Identifier: CC-BY-SA-4.0
 # PCB Scene3D Viewer
 
 Reusable browser-side 3D PCB viewer utilities for normalized ECAD scene
-descriptions and direct CircuitJSON element arrays.
+descriptions and canonical CircuitJSON documents.
 
 This package renders scene descriptions produced by packages such as
 `altium-toolkit/scene3d` and `kicad-toolkit/scene3d`. It does not parse ECAD
 source files and does not build format-specific scene data. Hosts that already
-have CircuitJSON can pass the element array directly to the controller or
+have CircuitJSON can pass a common `DocumentResult`, a prepared
+`CircuitJsonDocumentContext`, or an element array directly to the controller or
 runtime.
 
 The package was extracted from [ECAD Forge](https://ecadforge.app/), where it
@@ -21,6 +22,41 @@ factories, model loading, component picking, view presets, archive export,
 GLTF/GLB assembly writing, and optional DOM shell can be reused by other
 browser-based ECAD tools.
 
+## CircuitJSON 1.1 convergence
+
+Version 1.2.0 accepts the common document and prepared-context shapes returned
+by CircuitJSON, Gerber, Altium, and KiCad Toolkit 1.1-compatible APIs. The
+adapter requests the shared `elements` index once and reuses it across repeated
+scene builds. `PcbScene3dCircuitJsonAdapter.prepare()` exposes that proof-aware
+path to hosts. Existing bare arrays are normalized by the shared CircuitJSON
+boundary, while legacy parser-compatible hybrid arrays retain their native
+builder behavior. Canonical `model_asset` paths and matching document or session
+assets are resolved directly by the adapter; hosts do not need an app-side
+document transform or resolver wrapper. Document asset indexes are created only
+for referenced models and cached through a prepared context. Exact
+case-sensitive paths win; case-insensitive fallback is used only when unique.
+Polygon-plated holes use the shared CircuitJSON hole primitive model, including
+rotation-local `pad_outline` extents and pill-slot width, height, and rotation;
+outer-pad and drill rotations remain independent and board-space drill angles
+are applied exactly once. Gerber routed slots therefore retain horizontal,
+diagonal, and vertical canonical geometry in the viewer. Multiple disjoint
+`pcb_board` rows (or multiple `pcb_panel` rows) render as independent substrate,
+outline, mask, and export contours instead of dropping every row after the
+first.
+Legal rectangular and square CircuitJSON drill apertures retain their exact
+width, height, and board-space rotation through substrate, pad, and assembly
+export meshes.
+
+The live runtime loads STEP/STP, WRL/VRML, STL, OBJ, GLTF/GLB, and 3MF from
+canonical text/bytes or browser files. Referenced GLTF buffers, OBJ material
+libraries, and WRL textures are attached from matching document/session assets
+using safe project-relative paths. URL loading is explicit through
+`modelLoaderOptions.fetch` or `allowNetworkModelFetch: true`, with optional
+headers, timeout, cache, and bounded-resource settings. Static `authHeaders`
+stay on the main model origin; `authHeadersForUrl` is the explicit per-URL
+override. The model ZIP exporter uses the same policy and writes each raw model
+under its original source basename with safe GLTF, OBJ, and WRL companions.
+
 ## Install
 
 ```bash
@@ -61,37 +97,26 @@ const controller = new PcbScene3dController(
 controller.setSelectedComponent('U1')
 ```
 
-Direct CircuitJSON input does not require a format-specific `buildScene`
+Canonical document input does not require a format-specific `buildScene`
 callback:
 
 ```js
 import { PcbScene3dController } from 'pcb-scene3d-viewer'
+import { Parser } from 'gerber-toolkit'
 
-const circuitJson = [
-    {
-        type: 'pcb_board',
-        width: 50,
-        height: 30,
-        thickness: 1.6,
-        center: { x: 25, y: 15 }
-    },
-    {
-        type: 'pcb_component',
-        source_component_id: 'source-r1',
-        layer: 1,
-        center: { x: 20, y: 15 },
-        width: 3,
-        height: 1.5
-    }
-]
+const document = await Parser.parseAsync({
+    fileName: file.name,
+    data: await file.arrayBuffer()
+})
 
-const controller = new PcbScene3dController(viewportNode, circuitJson)
+const controller = new PcbScene3dController(viewportNode, document)
 ```
 
 ## Documentation
 
 - [API](docs/api.md)
 - [CircuitJSON usage](docs/circuitjson.md)
+- [1.2.0 release notes](docs/release-notes-v1.2.0.md)
 - [Model format](docs/model-format.md)
 - [Testing](docs/testing.md)
 - [Library scope](spec/library-scope.md)

package/docs/api.md

@@ -8,6 +8,10 @@ The package exports all public APIs from `pcb-scene3d-viewer` and
 ### `PcbScene3dShellRenderer.render(documentModel, translate?)`
 
 Returns HTML markup for the optional interactive 3D scene shell.
+`documentModel` accepts a legacy scene/parser model, a dense CircuitJSON array,
+an `ecad-toolkit.document.v1` result, or a prepared
+`CircuitJsonDocumentContext`. CircuitJSON shapes use the shared context index to
+derive board, component, and BOM summary counts.
 
 The markup includes:
 
@@ -36,10 +40,21 @@ Important options:
 - `createModelRegistry`: optional function passed into `buildScene`.
 - `createRuntime`: optional runtime factory for tests or custom hosts.
 - `sessionAssets`: companion model assets passed to scene preparation.
+- `modelLoaderOptions`: optional runtime model-loading policy. It accepts the
+  same `fetch`, `allowNetworkModelFetch`, `authHeaders`, `authHeadersForUrl`,
+  `fetchTimeoutMs`, `modelCache`, `maxModelBytes`, `maxModelResources`, and
+  `maxModelTotalBytes` fields as `PcbAssemblyModelMeshLoader`. The policy is
+  also forwarded unchanged to model ZIP export.
 - `setLoadingVisible`: callback for shell loading state.
 - `onComponentSelectionChange`: callback for 3D picks.
 - `translate`: optional `(key) => string` translation function.
 
+Preparation precedence is explicit: `sceneDescription`, then
+`scenePrepClient`, then direct canonical CircuitJSON adaptation, and finally
+the legacy `buildScene` callback. If asynchronous scene preparation fails, a
+canonical document still falls back to direct adaptation with the supplied
+adapter and asset options.
+
 Methods:
 
 - `getDocumentModel()`: returns the mounted document model.
@@ -55,15 +70,35 @@ controller only and are forwarded to the runtime through
 
 ### `PcbScene3dCircuitJsonAdapter`
 
-Converts serialized CircuitJSON element arrays into the normalized scene
-description consumed by the runtime.
+Converts a common CircuitJSON `DocumentResult`, prepared
+`CircuitJsonDocumentContext`, or serialized element array into the normalized
+scene description consumed by the runtime.
 
 Methods:
 
-- `isCircuitJsonModel(value)`: returns true for serialized CircuitJSON arrays.
-- `isDirectCircuitJsonModel(value)`: returns true when the array should bypass
-  host `buildScene` callbacks.
-- `build(circuitJson, options?)`: returns a runtime-ready scene description.
+- `isCircuitJsonModel(value)`: returns true for accepted document, context, or
+  structurally valid array inputs without freezing or mutating an unprepared
+  caller value. Shared normalization and schema validation occur in `prepare`.
+- `isDirectCircuitJsonModel(value)`: returns true when the canonical input
+  should bypass host `buildScene` callbacks.
+- `prepare(circuitJson)`: returns a `CircuitJsonDocumentContext`, normalizes
+  supported legacy rows through the shared CircuitJSON boundary, reuses a
+  canonical document validation proof, and prepares the `elements` index once.
+- `build(circuitJson, options?)`: returns a runtime-ready scene description and
+  reuses an existing context `elements` index when supplied. Canonical
+  `cad_component.model_asset` records are consumed directly and matched against
+  canonical document assets or `options.sessionAssets` through a prebuilt
+  descriptor-safe alias index. The index is not built for documents without
+  model references, is cached in a supplied context for repeated builds, and
+  materializes a canonical payload only when its first model reference is used.
+  Plated-hole copper and drill geometry comes from the shared
+  `CircuitJsonPcbHolePrimitiveModel`, so polygon pad outlines and pill slots use
+  the same canonical shape and dimensions as the producing toolkit. Drill
+  rotation is board-space and is never added to pad rotation a second time.
+  Rectangular and square apertures retain width, height, and rotation rather
+  than being approximated as circles or pill slots, including assembly export.
+  Every selected panel contour, or every board contour when no panel exists,
+  is retained in `board.contours` and rendered/exported independently.
   `options.modelUrlResolver` can attach caller-owned URL resolution metadata to
   `cad_component` external models without fetching them. `projectBaseUrl`
   resolves relative model URLs and package-style `node_modules/...` model paths,
@@ -77,6 +112,31 @@ Methods:
 when they receive direct CircuitJSON input. See
 [CircuitJSON usage](circuitjson.md) for supported elements, units, and examples.
 
+### `CircuitJsonCadModelAssetResolver`
+
+`withModelAssetUrls(document)` accepts an element array, common
+`DocumentResult`, or prepared context. It returns the same input shape when no
+derived URL is needed; otherwise it returns a new array, canonical document
+envelope, or prepared context with `model_asset` paths promoted to explicit
+CircuitJSON model URL fields. Source metadata, extensions, assets, diagnostics,
+and statistics are preserved. This utility remains available for consumers
+that need explicit URL fields; the viewer adapter does not require it.
+
+`withSessionAssetResolver(options, documentAssets?)` retains its public session
+asset behavior and also accepts canonical document assets. Alias lookup is
+indexed once and does not invoke asset accessors. Exact case-sensitive project
+paths take precedence. Case-insensitive lookup is a compatibility fallback only
+when one unique asset owns the folded path; ambiguous folded paths do not
+resolve. Resolved metadata is copied through a descriptor-safe boundary.
+
+`withContextAssetResolver(options, context)` uses the same behavior while
+caching the canonical document-asset alias index in the supplied prepared
+context. Session assets remain request-specific and take precedence over
+document assets. Referenced GLTF `buffers[].uri`, OBJ `mtllib`, and WRL
+`ImageTexture` companions are attached as `externalBuffers` or `resources`
+when their safe project-relative path matches an indexed asset. Parent
+traversal, absolute paths, and URL schemes are never attached implicitly.
+
 ## Runtime
 
 ### `new PcbScene3dRuntime(viewportNode, sceneDescription, hooks?)`
@@ -90,6 +150,38 @@ Hooks:
 - `loadRuntimeModules()`: optional async loader returning `{ THREE,
 OrbitControls }`.
 - `translate`: optional translation function for interaction hints.
+- `modelLoaderOptions`: opt-in model URL fetch policy and cache settings.
+
+The live runtime accepts STEP/STP, WRL/VRML, STL, OBJ, GLTF/GLB, and 3MF
+placements. Text-capable formats accept `payloadText`, `text`, and string
+`data`; every format accepts binary `data`, `bytes`, `payloadBytes`, or browser
+`File`/`Blob` content. URL fetching remains opt-in through an injected `fetch`
+function or `allowNetworkModelFetch: true`. Relative GLTF sidecars resolve
+beside absolute or project-relative main model paths. WRL texture references
+are replaced with local or explicitly fetched data URIs before Three.js parses
+the model, preventing implicit texture networking. STL, OBJ, GLTF, and GLB use
+the shared faceted mesh pipeline so runtime and assembly export preserve the
+same units, material color, opacity, and vertex-color behavior.
+
+Static `authHeaders` are sent only to the main model origin. A host that
+intentionally authorizes another origin can return headers from
+`authHeadersForUrl(url, { mainUrl, sameOrigin, label })`. Each fetch scope
+defaults to 128 MiB per resource, 256 resources, and 512 MiB aggregate; override
+these with `maxModelBytes`, `maxModelResources`, and `maxModelTotalBytes`.
+
+### `PcbModelArchiveExporter.buildArchive(options?)`
+
+Exports resolved STEP/STP, WRL/VRML, 3MF, GLB/GLTF, STL, and OBJ sources. Raw
+models accept the same canonical text, byte, file, and explicitly enabled URL
+sources as the runtime. `modelLoaderOptions` is shared with stitched-component
+mesh loading and raw URL export. Exact canonical project paths, source streams,
+or IDs define deduplication; same-basename models in different paths remain
+distinct. A controller derives the archive base name from `summary.title`,
+canonical `source.fileName`, or the legacy `fileName`, in that order.
+Each raw source is written to a unique pattern directory under its original
+source basename. Safe relative GLTF buffers/images, OBJ resources, and WRL
+textures are written beside it so internal references remain valid. Every raw
+`exportedEntries` row includes `bundleDirectory` and `companionPaths`.
 
 Methods:
 
@@ -175,9 +267,15 @@ Options:
 - `fetch`: host-provided fetch function for resolved model URLs.
 - `allowNetworkModelFetch`: use `globalThis.fetch` for `resolvedUrl` or
   `sourceUrl` models when no local payload is present.
-- `authHeaders`: headers forwarded to network model requests.
+- `authHeaders`: headers forwarded only to same-origin model requests.
+- `authHeadersForUrl(url, context)`: explicit per-URL headers. Static
+  `authHeaders` are withheld when `context.sameOrigin` is false.
 - `fetchTimeoutMs`: abort timeout for network model requests.
 - `modelCache`: optional cache map keyed by resolved model URL.
+- `maxModelBytes`: maximum bytes per fetched resource; defaults to 134217728.
+- `maxModelResources`: maximum fetched main/sidecar resources per scope;
+  defaults to 256.
+- `maxModelTotalBytes`: maximum aggregate fetched bytes per scope; defaults to 536870912.
 
 ## Model Archive Export
 
@@ -189,12 +287,15 @@ Options:
 
 - `archiveBaseName`: base name for the downloaded archive.
 - `sceneDescription`: scene description containing resolved external models.
+- `modelLoaderOptions`: the same bounded explicit fetch policy used by runtime
+  model loading.
 
 Returns:
 
 - `archiveName`;
 - `archiveBytes`;
-- `exportedEntries`;
+- `exportedEntries`, including `archivePath`, `bundleDirectory`, and
+  `companionPaths` for each raw source;
 - `skippedEntries`.
 
 ## Geometry Factories

package/docs/circuitjson.md

@@ -1,14 +1,24 @@
 # CircuitJSON Usage
 
-`pcb-scene3d-viewer` can render serialized CircuitJSON element arrays directly.
-Use this path when the host application already has CircuitJSON and does not
-need an Altium, KiCad, or other format-specific scene builder.
+`pcb-scene3d-viewer` can render common CircuitJSON document envelopes, prepared
+document contexts, and serialized element arrays directly. Use this path when
+the host application already has CircuitJSON and does not need an Altium,
+KiCad, Gerber, or other format-specific scene builder.
+
+## Accepted Input Shapes
+
+- `ecad-toolkit.document.v1` results returned by converged toolkit parsers;
+- `CircuitJsonDocumentContext` instances prepared by a host for reuse; or
+- dense serialized CircuitJSON element arrays.
+
+Prepared contexts are the fastest repeated-render path because validation and
+the adapter's `elements` index are built at most once.
 
 ## Direct Controller Input
 
-Pass the CircuitJSON array as the `documentModel`. The controller detects direct
-CircuitJSON input, converts it to the internal render model, and mounts the
-runtime without a `buildScene` callback.
+Pass any accepted CircuitJSON shape as the `documentModel`. The controller
+detects direct CircuitJSON input, converts it to the internal render model, and
+mounts the runtime without a `buildScene` callback.
 
 ```js
 import {
@@ -19,6 +29,7 @@ import {
 const circuitJson = [
     {
         type: 'pcb_board',
+        pcb_board_id: 'board-1',
         width: 50,
         height: 30,
         thickness: 1.6,
@@ -26,14 +37,16 @@ const circuitJson = [
     },
     {
         type: 'source_component',
-        id: 'source-r1',
+        source_component_id: 'source-r1',
         name: 'R1',
-        ftype: 'R_0603'
+        ftype: 'simple_resistor',
+        resistance: '10k'
     },
     {
         type: 'pcb_component',
+        pcb_component_id: 'pcb-r1',
         source_component_id: 'source-r1',
-        layer: 1,
+        layer: 'top',
         center: { x: 20, y: 15 },
         rotation: 90,
         width: 1.6,
@@ -42,7 +55,10 @@ const circuitJson = [
     },
     {
         type: 'pcb_smtpad',
-        layer: 1,
+        pcb_smtpad_id: 'pad-r1-1',
+        pcb_component_id: 'pcb-r1',
+        layer: 'top',
+        shape: 'rect',
         x: 19.2,
         y: 15,
         width: 0.7,
@@ -50,7 +66,10 @@ const circuitJson = [
     },
     {
         type: 'pcb_smtpad',
-        layer: 1,
+        pcb_smtpad_id: 'pad-r1-2',
+        pcb_component_id: 'pcb-r1',
+        layer: 'top',
+        shape: 'rect',
         x: 20.8,
         y: 15,
         width: 0.7,
@@ -58,12 +77,23 @@ const circuitJson = [
     },
     {
         type: 'pcb_trace',
-        layer: 1,
+        pcb_trace_id: 'trace-r1-1',
         route: [
-            { x: 18, y: 15 },
-            { x: 19.2, y: 15 }
-        ],
-        width: 0.25
+            {
+                route_type: 'wire',
+                x: 18,
+                y: 15,
+                width: 0.25,
+                layer: 'top'
+            },
+            {
+                route_type: 'wire',
+                x: 19.2,
+                y: 15,
+                width: 0.25,
+                layer: 'top'
+            }
+        ]
     }
 ]
 
@@ -75,14 +105,14 @@ const controller = new PcbScene3dController(
 )
 ```
 
-The shell renderer does not inspect the CircuitJSON data. It only renders the
-optional DOM controls. The controller performs the CircuitJSON detection and
+The shell renderer uses the shared CircuitJSON context/index to derive its
+board, component, and BOM summary. The controller performs the full render-model
 conversion.
 
 ## Direct Runtime Input
 
-For custom UI shells, pass the same CircuitJSON array directly to
-`PcbScene3dRuntime`.
+For custom UI shells, pass the same document, context, or CircuitJSON array
+directly to `PcbScene3dRuntime`.
 
 ```js
 import { PcbScene3dRuntime } from 'pcb-scene3d-viewer'
@@ -109,9 +139,49 @@ if (PcbScene3dCircuitJsonAdapter.isCircuitJsonModel(circuitJson)) {
 }
 ```
 
+For repeated builds, prepare and retain the shared context:
+
+```js
+import { CircuitJsonDocumentContext } from 'circuitjson-toolkit'
+import { PcbScene3dCircuitJsonAdapter } from 'pcb-scene3d-viewer'
+
+const context = CircuitJsonDocumentContext.prepare(document, {
+    indexes: ['elements']
+})
+const firstScene = PcbScene3dCircuitJsonAdapter.build(context)
+const secondScene = PcbScene3dCircuitJsonAdapter.build(context)
+```
+
+Both builds reuse the same validated model and `elements` index. If the model
+contains CAD model references, its canonical document-asset alias index is also
+built at most once in the same context. Documents without model references do
+not pay that indexing cost.
+
+The viewer exposes the same operation as
+`PcbScene3dCircuitJsonAdapter.prepare(document)`. Controller routing uses this
+proof-aware path before mounting, so a validated toolkit document is not
+validated again. Bare arrays first pass a non-mutating structural predicate and
+are then normalized and validated by the shared CircuitJSON context; supported
+legacy rows are not rejected by an earlier strict viewer precheck.
+
+Canonical CAD rows may retain a `model_asset` path instead of an explicit
+`model_step_url`, `model_glb_url`, or equivalent field. The adapter consumes
+that field directly and resolves matching assets from the canonical document
+or `sessionAssets`; no document pre-transform or resolver wrapper is required.
+Canonical `ToolkitAsset` payloads may expose their immutable `data` through the
+shared accessor-backed contract. The resolver recognizes and lazily
+materializes those trusted assets before its descriptor-safe viewer copy;
+arbitrary accessor-backed session rows remain unread and cannot execute.
+For GLTF, OBJ, and WRL main assets, safe project-relative BIN, MTL, and texture
+references are attached automatically from the same indexed asset sets.
+Session companions take precedence over document companions. Absolute URLs,
+parent traversal, and accessor-backed entries are excluded without executing
+caller accessors.
+`CircuitJsonCadModelAssetResolver.withModelAssetUrls()` remains available when
+a separate consumer specifically needs explicit URL fields.
+
 Hosts that need URL policy control can pass a synchronous `modelUrlResolver`.
-The adapter records the returned metadata on each external model but does not
-fetch the referenced file:
+The adapter records the returned metadata on each external model:
 
 ```js
 const sceneDescription = PcbScene3dCircuitJsonAdapter.build(circuitJson, {
@@ -128,12 +198,20 @@ Hosts can also pass `projectBaseUrl` to resolve relative model URLs without a
 custom resolver. Package-style `node_modules/...` paths resolve to the
 project-origin `/package_files/download` endpoint with package and file-path
 query parameters. Package download file paths are normalized under `dist/` when
-the source path does not already include it. Model fetching remains a separate
-host/export decision.
+the source path does not already include it. Model fetching remains opt-in.
+Pass `modelLoaderOptions` to the controller or runtime hooks with an injected
+`fetch`, or set `allowNetworkModelFetch: true` to use `globalThis.fetch`.
+Canonical document bytes and session `File`/`Blob` assets need no network
+option. Static `authHeaders` remain on the main model origin. Use
+`authHeadersForUrl` for an intentional cross-origin header and
+`maxModelBytes`/`maxModelResources`/`maxModelTotalBytes` to adjust the bounded
+fetch defaults.
 `boardDrillQuality` accepts `low`, `medium`, or `high` and controls generated
 circle sampling for direct CircuitJSON drill/cutout geometry. When a
 CircuitJSON file has components but no board or panel, `drawFauxBoard: true`
 generates a board from component bounds with a 2 mm margin per side.
+The optional shell honors the same flag, so component-only documents show the
+same faux-board scene controls instead of an empty-state message.
 Set `showPcbNotes: true` to render `pcb_note_text`,
 `pcb_fabrication_note_text`, note/fabrication path artwork, and courtyard
 artwork as silkscreen detail. Notes are hidden by default so manufacturing
@@ -145,7 +223,9 @@ does not clutter normal board previews.
 `isDirectCircuitJsonModel(value)` returns `false` for compatibility arrays that
 also carry legacy parser fields such as `pcb`, `schematic`, or `bom`. Those
 arrays continue through the host-provided `buildScene` callback so existing
-parser integrations keep their source-specific conversion behavior.
+parser integrations keep their source-specific conversion behavior. Canonical
+document envelopes and prepared contexts always use the direct CircuitJSON path
+regardless of their original source format.
 
 ## Units And Coordinates
 
@@ -159,6 +239,12 @@ board with a 1.6 mm thickness so incomplete test or preview models still
 render. With `drawFauxBoard: true`, that fallback board is instead sized around
 the PCB component bounds with a minimum 10 mm by 10 mm footprint.
 
+When panels exist, every `pcb_panel` is an independent physical contour and
+child `pcb_board` rows are not duplicated as substrate. Without panels, every
+`pcb_board` is retained. `board.widthMil`, `heightMil`, and center describe the
+aggregate bounds; `board.contours` carries each physical outline, thickness,
+and targeted cutouts for runtime rendering and assembly export.
+
 `cad_component` records with `show_as_bounding_box: true` are exported as
 procedural component bodies. If `size` or `model_size` is present, those
 dimensions drive the generated body; otherwise the paired `pcb_component`
@@ -270,6 +356,34 @@ Drills can use circular, pill, or rotated pill geometry. `hole_offset_x` and
 }
 ```
 
+Polygon-plated slots use the canonical `hole_with_polygon_pad` variant. The
+shared CircuitJSON primitive model derives the copper dimensions in the pad's
+rotation-local coordinate system and preserves the pill drill dimensions:
+
+```js
+{
+    type: 'pcb_plated_hole',
+    shape: 'hole_with_polygon_pad',
+    hole_shape: 'pill',
+    x: 10,
+    y: 8,
+    hole_width: 2.6,
+    hole_height: 0.6,
+    pad_outline: [
+        { x: 8.7, y: 7.7 },
+        { x: 11.3, y: 7.7 },
+        { x: 11.3, y: 8.3 },
+        { x: 8.7, y: 8.3 }
+    ]
+}
+```
+
+This is the same canonical shape emitted for a plated Gerber routed slot; no
+format-specific scene adapter is required. `holeRotation` is board-space, so a
+45-degree or 90-degree routed slot is applied once even when its outer pad uses
+the same rotation. Rectangular outer pads may independently use
+`rect_ccw_rotation`, while rotated pill drills use `hole_ccw_rotation`.
+
 SMT pads can use circular, rectangular, rotated rectangular, or pill geometry.
 Pill pads are normalized as rounded rectangles so their copper keeps the
 expected capsule outline:
@@ -368,7 +482,7 @@ model conversion. Use `PcbScene3dCircuitJsonAdapter.isCircuitJsonModel(value)`
 for a cheap guard when accepting untrusted JSON from users, and catch conversion
 errors around `build(value)` when you need to show a custom diagnostic.
 
-The viewer does not fetch external assets for CircuitJSON input by itself.
-Model URL matching, same-origin checks, proxying, and file loading remain the
-responsibility of source-specific toolkits or host applications that create or
-post-process normalized scene descriptions.
+The viewer never fetches external assets unless the host explicitly enables a
+model loader fetch policy. Model URL matching and same-origin/proxy decisions
+remain host-owned; canonical document bytes and session files are consumed
+directly without an app-side resolver wrapper.

package/docs/model-format.md

@@ -70,7 +70,8 @@ Components describe fallback package bodies and selection metadata:
 
 ## External Placements
 
-External placements describe STEP, WRL, GLB, GLTF, STL, or OBJ model instances:
+External placements describe STEP, WRL, 3MF, GLB, GLTF, STL, or OBJ model
+instances:
 
 ```js
 {
@@ -112,12 +113,47 @@ GLTF/GLB import consumes triangle primitives and ignores unsupported primitive
 modes such as points or lines. Remote `.gltf` files can reference external
 `buffers[].uri` sidecars; when URL-backed model loading is enabled, the loader
 resolves those sidecars relative to the `.gltf` URL and fetches them with the
-same cache, timeout, and auth-header policy.
+same cache, timeout, and auth-header policy. This also works when the main model
+path is project-relative. Resident GLTF JSON uses already attached buffers and
+fetches only missing sidecars when an explicit policy is configured.
+
+Canonical document/session asset resolution attaches safe project-relative
+GLTF BIN, OBJ MTL, and WRL texture companions directly. WRL textures are encoded
+as data URIs before parsing. Unmatched texture URLs become inert unless the host
+supplies an explicit fetch policy, so Three.js cannot perform an implicit
+network request.
 
 Resolved model URLs are not fetched by default. Hosts that want URL-backed model
-loading must provide an explicit fetch policy through `PcbAssemblyModelMeshLoader`
-or a higher-level export service. Use `authHeaders`, `fetchTimeoutMs`, and a
-caller-owned `modelCache` when remote model requests are enabled.
+loading must provide an explicit fetch policy through
+`PcbScene3dController`/`PcbScene3dRuntime` `modelLoaderOptions`,
+`PcbScene3dExternalModels.loadIntoScene({ modelLoaderOptions })`, or
+`PcbAssemblyModelMeshLoader`. Use `authHeaders`, `fetchTimeoutMs`, and a
+caller-owned `modelCache` when remote model requests are enabled. Successful
+STEP/STP, WRL/VRML, and 3MF requests share that cache; rejected requests are
+evicted so callers can retry. Embedded `payloadText`, `text`, `payloadBytes`,
+`bytes`, canonical string/binary `data`, and browser `File`/`Blob` values are
+loaded without enabling network access.
+
+Static `authHeaders` are origin-bound to the main model URL and are not copied
+to cross-origin GLTF buffers or WRL textures. Use
+`authHeadersForUrl(url, { mainUrl, sameOrigin, label })` for an intentional
+per-resource exception. Network scopes default to 128 MiB per resource, 256
+resources, and 512 MiB aggregate across main models and sidecars. Configure
+`maxModelBytes`, `maxModelResources`, and `maxModelTotalBytes` to adjust those
+bounds.
+
+Model caches and ZIP deduplication use exact canonical project paths, retained
+source streams, or asset IDs before falling back to checksums and names. Two
+different directories may therefore contain the same basename without a cache
+collision, while repeated placements of one exact source reuse parsed geometry.
+Canonical/session asset aliases resolve exact case-sensitive paths first. A
+case-insensitive fallback is accepted only when unique, preventing collisions
+between files that differ only by case.
+
+Raw model archives use one unique pattern directory per source. The main file
+keeps its original source basename, and safe relative GLTF buffers/images, OBJ
+resources, and WRL textures are emitted beneath the same directory so their
+references remain usable after extraction.
 
 When `projectBaseUrl` is provided to the CircuitJSON adapter, package-style
 model paths such as `node_modules/package-name/path/to/model.step` are resolved
@@ -167,9 +203,16 @@ model matching, the source toolkit should encode those decisions in the scene
 description.
 
 Through-hole pads can describe offset or slotted drills with `holeOffsetX`,
-`holeOffsetY`, `holeSlotLength`, and `holeRotation`. Board substrate export uses
+`holeOffsetY`, `holeSlotLength`, and board-space `holeRotation`; pad `rotation`
+is not added to the drill angle. Board substrate export uses
 `detail.drillQuality` values of `low`, `medium`, or `high` to choose circular
-drill sampling density.
+drill sampling density. Direct CircuitJSON polygon-plated holes are normalized
+through the shared hole primitive model: polygon extents become the pad's local
+copper size and pill width/height become `holeDiameter` and `holeSlotLength`.
+
+`board.contours` contains every independently extruded board or panel outline.
+The top-level board bounds center all detail, while runtime bodies, outlines,
+solder-mask faces, and exported substrate meshes iterate the contour list.
 
 Rounded SMT pads set `hasRoundedRect`, the side-specific
 `roundedRectShapeTop`/`roundedRectShapeBottom`, and