PCB Interfaces

PcbSvgCanvasConfig

Rationale

PCB SVGs need a compact visual canvas while preserving Altium coordinate metadata.

Purpose

Defines the A0 SVG viewBox bounds mode and margin for rendered layer outputs and composed views.

Test Requirements

Tests must verify default board-outline bounds, config validation, and real SVG output metadata.

Working Definition

Working when board views open tightly around the board profile and metadata records the canvas transform.

PcbSvgAssemblyConfig

Rationale

Assembly SVG virtual layers need component-level projection policy without forcing all components through HLR.

Purpose

Stores default and DNP projection modes plus normal and DNP designator colors.

Test Requirements

Config tests must validate projection-mode aliases and optional root serialization.

Working Definition

Working when configs can select detail, simple, bounding_box, or none before rendering consumes those options.

PcbSvgDnpConfig

Rationale

DNP components need explicit visual policy that does not depend on STEP HLR.

Purpose

Stores DNP color and hatch styling for future pad-bounding-box projection output.

Test Requirements

Config tests must verify DNP hatching fields parse and serialize.

Working Definition

Working when DNP visual defaults are available to renderer code and remain absent from default JSON when unused.

PcbSvgDiodeConfig

Rationale

Two-pin diode marking needs a shared detection and cathode convention.

Purpose

Stores diode detection prefixes, text terms, cathode pad names, numeric cathode fallback, marker color, and line-art default.

Test Requirements

Config and inventory tests must exercise diode detection and cathode mapping fields.

Working Definition

Working when generated config comments identify diode candidates and users can override cathode behavior.

PcbSvgPin1Config

Rationale

Pin-1 overlays need global defaults so passive families can stay quiet while explicit component overrides remain possible.

Purpose

Stores designator prefixes excluded from automatic pin-1 marking in PCB SVG virtual views.

Test Requirements

Config tests must verify default and configured prefix lists parse and serialize with the PCB SVG config root.

Working Definition

Working when pin-1 views can suppress default passive markers and component overrides can re-enable specific parts.

PcbSvgComponentOverride

Rationale

Users need per-designator control over projection, pin, cathode, diode, and designator behavior.

Purpose

Represents one optional component override keyed by designator in pcb.svg.config.

Test Requirements

Config tests must validate side and projection parsing plus optional-field serialization.

Working Definition

Working when hand-edited component overrides round-trip without adding no-op defaults.

PcbSvgGlobalConfig

Rationale

PCB SVG defaults need a shared A0 root.

Purpose

Stores global PCB SVG options and style defaults inherited by layer outputs and composed views.

Test Requirements

PCB SVG tests must preserve default style inheritance and CLI output selection behavior.

Working Definition

Working when global options merge predictably with per-view style overrides.

PcbSvgViewConfig

Rationale

Each PCB SVG view needs an explicit draw stack and durable update boundary.

Purpose

Defines one configured PCB SVG view, including output pattern, group id, layer tokens, mirror policy, HLR mode, and style overrides.

Test Requirements

View-selection and config tests must exercise explicit view names and layer-output filters.

Working Definition

Working when selected views render the configured layer token stack and can be updated by durable group id.

PcbSvgConfig

Rationale

PCB SVG command config needs a versionable root object.

Purpose

Aggregates the pcb.svg.config user config, A0 schema, global options, layer-output policy, and composed view list.

Test Requirements

Tests must cover created defaults, schema rejection, CLI overrides, JSONC input, and style merging.

Working Definition

Working when command config loads and selects the intended layer outputs and composed views.

CruncherPcbRenderInput

Rationale

PCB commands need one resolved board input shape.

Purpose

Carries resolved PcbDoc, board key, path, and project parameters.

Test Requirements

L3 PCB SVG tests must load public PcbDoc inputs without private context.

Working Definition

Working when all PCB render commands receive consistent resolved input metadata.

PcbSvgComponentInventoryEntry

Rationale

Generated PCB SVG configs need concise component facts without running rendering or HLR.

Purpose

Stores one component's side, footprint, pads, rotation, diode detection, and cathode candidate.

Test Requirements

Inventory tests must cover side extraction, pad names, diode detection, and cathode mapping.

Working Definition

Working when config templates can list useful per-component hints from PcbDoc data alone.

PcbSvgComponentInventory

Rationale

PCB SVG config generation needs a board-level component inventory that remains independent from SVG rendering.

Purpose

Groups component inventory entries for one board and exposes diode candidates for template comments.

Test Requirements

Fixture-backed tests must verify cricket-node component and diode comments are emitted from inventory data.

Working Definition

Working when config generation can annotate all discovered designators without invoking Geometer.

AssemblyProjectionOptions

Rationale

Assembly HLR projection needs explicit side and curve policy.

Purpose

Configures projected side and curve conversion behavior.

Test Requirements

Projection cache tests must exercise geometer HLR requests.

Working Definition

Working when projection options produce stable cached projected geometry.

AssemblyProjectedArc

Rationale

Projected assembly geometry may contain arcs that need structured metadata.

Purpose

Represents one projected arc segment.

Test Requirements

Projection tests must preserve projected curve handling.

Working Definition

Working when arcs survive HLR projection with usable coordinates.

AssemblyProjectedGeometry

Rationale

Assembly SVG rendering needs a stable projected geometry bundle.

Purpose

Stores projected lines, arcs, and bounds.

Test Requirements

Projection tests must verify cached geometer-backed geometry.

Working Definition

Working when assembly rendering can consume projected data without re-running HLR.

CruncherPcbAssemblySvgRenderOptions

Rationale

Assembly SVG rendering extends normal PCB SVG options.

Purpose

Controls assembly SVG render behavior.

Test Requirements

PCB SVG workflow tests must keep render options compatible with public fixtures.

Working Definition

Working when assembly and layer renders share compatible option handling.

CruncherPcbCutoutStyle

Rationale

Standalone cutout artifacts and composed board views need one resolved cutout styling contract.

Purpose

Stores resolved board-cutout overlay, hatching, label, dashed-outline, and stroke-width settings for the cutout-aware PCB SVG renderer.

Test Requirements

Unit tests must verify the style drives hash spacing, hash direction, stroke width, dashed outlines, and composed-view overlay output.

Working Definition

Working when top and bottom SVG views inherit global cutout style settings and standalone cutout layers can share the same style values.

CruncherPcbCutoutLayerRenderer

Rationale

Board-profile cutouts need an independently toggleable SVG layer artifact.

Purpose

Renders pcbdoc.board.outline.cutouts as a synthetic BOARD_CUTOUTS layer with optional hatching, configurable stroke widths, dashed outlines, and labels.

Test Requirements

Unit tests must exercise cutout paths, metadata, hatching spacing, angle, and line width, dashed outline options, outline line width, labels, and empty-board behavior. L3 must exercise a real fixture with arc and line cutouts.

Working Definition

Working when cutout-enabled layer views can emit a red cutout-only SVG without changing normal PCB layer rendering.

PcbLayerStepOptions

Rationale

Layer STEP generation needs immutable effective options.

Purpose

Represents resolved layer, color, thickness, outline, cutout, drill, plating, filter, and fusion options.

Test Requirements

Unit tests must cover config and CLI override merging.

Working Definition

Working when generated STEP requests match resolved options.

PcbLayerStepResult

Rationale

STEP export callers need generated file and count metadata.

Purpose

Reports output path, manifest path, layer, and geometry counts.

Test Requirements

STEP export tests must verify manifest and result fields.

Working Definition

Working when callers can inspect outputs without reparsing the STEP file.

PcbLayerStepConfig

Rationale

The command needs a JSON root config for repeatable layer exports.

Purpose

Stores persisted layer STEP options.

Test Requirements

Config tests must verify template creation and schema.

Working Definition

Working when config templates load into valid effective options.

IllustrationComponent

Rationale

The illustration adapter must place Altium STEP and extruded bodies together within each component without inventing geometry for model-less parts.

Purpose

Stores placed meshes relative to a board anchor, source-body material and height metadata, and mesh bounds in millimeters. Separate bodies enter Geometer's demo rendering flow, which resolves depth and combines matching painted surfaces.

Test Requirements

Native tests cover RT_SUPER_C1 body colors, top/bottom body selection and STEP offsets, stacked bottom extrusion depth, nullable free-body ownership, preserved STEP root placement, and omission of the pad-only connector.

Working Definition

Working for experimental top/bottom previews when STEP and extruded meshes render in their authored poses and native visibility resolves bodies within each component. Repeated component illustrations are reused through SVG definitions and references; separate components paint in visible-side height order. Native camera coordinates remain registered with board artwork; the outer SVG scene mirrors the complete bottom view. Public CLI illustration selection remains a subsequent integration slice.

IllustrationSymbol

Rationale

Geometer returns completed SVG in its own integer coordinate frame, which must be placed correctly in the existing PCB SVG.

Purpose

Carries native SVG, statistics and warnings with its board-space origin and scale. Embedding resolves native CSS to element attributes while retaining Geometer's polygons, shading and Fast HLR linework.

Test Requirements

Native tests verify stacked-body paint order, surface fusion, source colors, SVG coordinate mapping, isolated styles, and reuse across instances without mixing material variants.

Working Definition

Working when the native illustration can be embedded at its actual millimeter placement without geometry reconstruction, recoloring adjacent symbols or adding custom rendering behavior.

IllustrationProjection

Rationale

Board-surface fragments and aperture-visible overhangs need the same explicit SVG placement contract.

Purpose

Carries one native SVG projection with its component-local board origin and millimeters-per-unit scale.

Test Requirements

Native tests verify that clipped surface projections and uncut aperture projections remain registered on top and bottom views.

Working Definition

Working when either projection can be embedded without recomputing geometry or changing its affine placement.

SoldermaskFilmRenderer

Rationale

Preview views need a filled solder-mask surface derived from existing Altium aperture geometry.

Purpose

Renders top or bottom film within the board profile, subtracting cutouts, saved expanded apertures and NPTH holes/slots. Reads the saved 3D mask color with configurable color and opacity overrides.

Test Requirements

Focused tests cover overlapping apertures/cutouts, signed saved expansion, tenting, via span and hole-edge expansion, NPTH slots, source colors, overrides and the public config schema.

Working Definition

Working when the existing pcb-svg compositor emits film virtual layers and the RT_SUPER_C1 preview preserves approved component registration above the film.

Component SVG Layers

PcbSvgCompositeRenderer.render_view_svg accepts ILLUSTRATION_TOP/BOTTOM and ASSEMBLY_DESIGNATORS_TOP/BOTTOM in its normal layer list. A renderer owns a ComponentLayerSession for one job over immutable PCB records. Native clients are closed after materialization; geometry, symbols and fitted layers remain available to subsequent views. Create a new renderer when the source document changes.

Designator fitting and cutout-clearance use the pcb-autodoc algorithm. The geometry adapter reuses Fast outline segments from the native illustration request, preserving Altium STEP/extrusion poses. Ordinary designator-only views can fit model-less labels to normalized electrical-pad silhouettes, including the copper renderer's flagged-testpoint exception, with mechanical holes as a fallback. Views co-composed with the matching component illustration layer, including Toon, omit projected labels without renderable model geometry. Config and output semantics, presets, draw order and coordinate transforms are documented in PCB SVG illustration layers. The enrichment metadata extension is specified by pcb.svg.component-layers.a0.

BoardSubstrateRenderer

Rationale

Mask openings over bare board need a substrate color independent of the page background.

Purpose

Renders the composable BOARD_SUBSTRATE layer (9014), with global/per-view color and enabled settings. Native board contours, scoped cutouts, pad holes and slots define the surface; via openings follow the selected outer side.

Test Requirements

Focused tests cover intrinsic clipping, overlapping voids, native arcs and slots, bottom mirroring, mask composition, metadata and config/preset round-tripping.

Working Definition

Working when mask artwork reveals opaque substrate and physical voids remain open in the substrate layer. See Board Substrate for placement and configuration.

CachedComponentPlacement

Rationale

Reuse validated artwork placements without rebuilding model geometry.

Purpose

Carries the component anchor, body recipe, source index, 3D bounds, and diagnostic model label needed to reproduce cold-render warnings.

Test Requirements

Warm cache preserves body order, model warning identity, and retries incomplete model results.

Working Definition

Working when cold and warm SVG and warning reports are byte-identical and consuming views preserve documented geometry and metadata.

CcaComponentGeometryFact

Rationale

Share model and pad silhouettes with the autodoc-derived fit algorithm.

Purpose

Carries bounds and separate visible and annotation line segments in millimeters.

Test Requirements

Disconnected regions remain distinct and do not center labels in empty gaps.

Working Definition

Working when the linked regression passes and consuming SVG views preserve the documented geometry and metadata.

CcaDesignatorFit

Rationale

Carry a fitted label without coupling layout to SVG markup.

Purpose

Returns the center, font size and rotation selected for the component silhouette.

Test Requirements

Capped font sizes and long-axis rotation match the fitting rules.

Working Definition

Working when the linked regression passes and consuming SVG views preserve the documented geometry and metadata.

CcaDesignatorFitTelemetry

Rationale

Measure fit reuse during repeated component placement.

Purpose

Counts requests, hits and misses and reports elapsed fit time.

Test Requirements

Translated equivalent silhouettes reuse cached fits.

Working Definition

Working when the linked regression passes and consuming SVG views preserve the documented geometry and metadata.

CcaPadFact

Rationale

Provide annotation bounds for parts without a 3D model.

Purpose

Captures electrical-pad geometry after component pose normalization.

Test Requirements

RT J1 labels center on the electrical pads in both mirrored and unmirrored views.

Working Definition

Working when the linked regression passes and consuming SVG views preserve the documented geometry and metadata.

ComponentLayer

Rationale

Compose illustrations and labels through the existing virtual-layer pipeline.

Purpose

Carries SVG, component metadata and optional millimeter bounds.

Test Requirements

Layer groups link to their components and preserve top/bottom placement.

Working Definition

Working when the linked regression passes and consuming SVG views preserve the documented geometry and metadata.

IllustrationVariant

Rationale

Render variant views without mutating the saved board.

Purpose

Carries exclusions, project parameters and per-component parameter overrides.

Test Requirements

Variant selection changes composed output while leaving source state unchanged.

Working Definition

Working when the linked regression passes and consuming SVG views preserve the documented geometry and metadata.

DirectIllustrationSource

Rationale

STEP bytes and analytic bodies should cross the native boundary once without materializing an intermediate mesh in Python.

Purpose

Carries the governed Geometer model source, optional STEP attachment, stable cache identity and diagnostic label until rendering.

Test Requirements

Fixture-backed tests must exercise embedded STEP and Altium analytic bodies through the direct illustration boundary while omitting model-less parts.

Working Definition

Working when ACR sends compact source data to Geometer, receives renderer-neutral illustration geometry, preserves cache identity and renders the same authored component placement.

BoardMaterialDomain

Rationale

Substrate painting and silkscreen clipping must use one physical board-footprint definition.

Purpose

Carries the board path and physical hole/cutout openings and serializes them as a deterministic SVG mask.

Test Requirements

Tests cover outlines, cutouts, plated and non-plated holes, slots, and overlapping openings.

Working Definition

Working when substrate and board-mode silkscreen clipping remove the same physical voids.

BoardRegionEnvelope

Rationale

Rigid-flex rendering needs a source-aware local slab instead of one board-wide thickness.

Purpose

Carries one valid region polygon, holes, substack identity, rigid/flex classification, and normalized physical envelope.

Test Requirements

Fixture tests verify exact Bluetooth Sentinel rigid and flex envelopes and normalized surfaces.

Working Definition

Working when a board-space query can recover the correct local top and bottom surfaces without raw row summation.

BoardRegionEnvelopeQuery

Rationale

Callers must distinguish a safe single-slab result from edges, holes, and conflicting regions.

Purpose

Reports typed query status, canonical region, full XY coverage, matching regions, and diagnostic detail.

Test Requirements

Tests cover contained bounds, outer-edge overhang, cutouts, equal envelopes, and conflicting envelopes.

Working Definition

Working when only fully covered equivalent-envelope bounds qualify for half-space clipping.

InvalidBoardRegion

Rationale

Malformed region geometry or stack references must fail safely without becoming guessed board thickness.

Purpose

Preserves source identity, available bounds, and a deterministic rejection reason.

Test Requirements

Tests require malformed outlines and unresolved stack references to produce typed invalid results.

Working Definition

Working when invalid source regions remain diagnosable and cannot qualify component clipping.

BoardSurfaceAppearance

Rationale

Solder mask, coverlay, exposed copper, and exposed substrate require different rendering semantics.

Purpose

Carries the resolved side, surface class, physical row identity, material, and authored color.

Test Requirements

Tests distinguish typed coverlay from ordinary overlay and reject zero-thickness rows as visible film.

Working Definition

Working when visible surface classification follows typed stack data rather than material-name guesses.

BoardRegionAppearance

Rationale

Each rigid-flex region may expose a different substrate and coating on each side.

Purpose

Groups substrate provenance with independent top and bottom surface facts for one valid region.

Test Requirements

Bluetooth Sentinel tests require rigid solder mask and uncoated flex without borrowing a global mask.

Working Definition

Working when regional substrate and film paths are painted only from their owning substack.

SurfaceFilmDomain

Rationale

Visible film and film-clipped silkscreen must consume identical region and aperture geometry.

Purpose

Carries the side-aware film path, openings, and per-region appearance paths and emits a reusable SVG mask.

Test Requirements

Raster tests compare none, board, and film clipping over pads, cutouts, and normal coated areas.

Working Definition

Working when film paint and silkscreen clipping cannot disagree about coated material.

BoardSpaceBendLine

Rationale

Region-local bend records need an explicit flat board-space representation before SVG rendering.

Purpose

Carries source identity, fold metadata, and lifted endpoints in board mils without folding geometry.

Test Requirements

Tests verify six Bluetooth flex lines, region translation, deduplication, and invalid-record handling.

Working Definition

Working when bend annotations align with their flat owning region and preserve authored metadata.

HalfSpacePlane

Rationale

Cruncher needs a deterministic board-surface policy ready for Geometer's released clipping contract.

Purpose

Represents a normalized world-space plane, tolerance, no-cap policy, and stable cache identity.

Test Requirements

Tests assert top and bottom plane direction and distance against exact RT_SUPER bounds and thickness.

Working Definition

Working when a fully covered body receives the correct local top or bottom half-space without inventing wire types.

ComponentVisibilityResolution

Rationale

Opposite-side rendering must distinguish visible, clipped, empty, and unsafe overhang cases.

Purpose

Carries the selected action, reason, sides, optional plane, region, and query status for one body group.

Test Requirements

Tests cover through-board bodies, shallow penetration, fully visible bodies, board edges, cutouts, and unlike envelopes.

Working Definition

Working when unsafe XY cases retain mounting-side compatibility and never guess an opposite-side fragment.

RotationResolution

Rationale

Altium STEP Z rotation can require either instance-space or footprint-local interpretation.

Purpose

Records the selected candidate, reason, and normalized bounds-fit scores.

Test Requirements

Tests cover the rectangular IC case, ambiguous square/180-degree cases, invalid bounds, and full affine transforms.

Working Definition

Working when the alternative pose is selected only when native bounds uniquely support it.

IllustrationDiagnostic

Rationale

Recoverable model and Geometer conditions must be queued instead of streamed from parallel work.

Purpose

Carries structured producer, category, code, component/body/model context, message, and detail from illustration preparation.

Test Requirements

Tests verify queued Geometer diagnostics do not log during work and retain structured producer identity.

Working Definition

Working when cache and worker paths can replay equivalent structured diagnostics for end-of-run aggregation.

ToonDiagnostic

Rationale

Toon needs deterministic, groupable, machine-readable nonfatal warnings.

Purpose

Represents one normalized warning identity with scope, occurrence count, source context, and optional structured detail.

Test Requirements

Tests validate schema, sort order, grouping, occurrence deduplication, empty reports, and variant-scoped omissions.

Working Definition

Working when console summaries and JSON reports derive from the same stable diagnostic set.