docs(api): mark seven unread option fields @deprecated (#2731) (#2975)

Each of these is declared in a public type, settable by a caller, and read
by nothing at runtime — no error, no warning, no effect. The JSDoc now says
so plainly, and names the substitute where one exists.

- SVGExportOptions.units (drawing-2d): export() never destructures it; the
  exporter emits no dimension annotations and always sizes the sheet in mm.
- OpeningFilterOptions.keepBoundarySegments (drawing-2d): merged into the
  filter's options object, never consulted; tolerance alone governs how
  segments near an opening edge are treated.
- DoorSymbolConfig.showThreshold (drawing-2d): no threshold-rendering code
  exists, so true and false produce identical geometry.
- SnapOptions.snapRadius (renderer): documented as world units, but every
  proximity check reads screenSnapRadius (pixels). Set that instead.
- SectionPlaneRenderOptions.flipped (renderer): the gizmo renderer never
  reads it. The GPU clip plane flips through separate state, so cutting
  behaviour is unaffected; only the gizmo option is inert.
- RenderOptions.enableDepthTest (renderer): dead on both ends — the sole
  occurrence of the name is its own declaration. Depth comparison is fixed
  per pipeline at construction time.
- StreamingOptions.onMetadataBootstrap (geometry): an unfinished stub. Its
  siblings onBatch, onColorUpdate, onComplete and onError are all dispatched
  by the bridge; this one never is.

Deprecated rather than deleted, following the maintainer's lean on the
issue: removing an optional field an embedder already passes turns a silent
no-op into a TS compile error, which is a worse first contact with the
problem than a warning that explains it. Removal stays a separate versioned
decision, so no removal timeline is implied here.

Two docs/guide/rendering.md snippets that advertised snapRadius as "10cm
world units" and listed enableDepthTest under "Performance" are annotated
to match.

No export added, removed or renamed: check-api-surface.mjs is green against
the unchanged snapshot, since it records exported names rather than members.

Out of scope by the maintainer's split — each needs a behaviour decision,
not a mechanical fix: the streaming batch ramp-up, GeometryQuality, and the
scale-bar / north-arrow renderer divergence.

Author: BIMvoice

.changeset/deprecate-unread-optional-fields.md

@@ -0,0 +1,41 @@
+---
+'@ifc-lite/drawing-2d': patch
+'@ifc-lite/renderer': patch
+'@ifc-lite/geometry': patch
+---
+
+Seven public option fields that nothing reads are now marked `@deprecated`,
+with JSDoc that says what actually happens instead of what the old comment
+promised. No behaviour changes and no export is removed or renamed — the
+values were already ignored at runtime; only the type-level documentation
+changes, so editors now warn at the point a caller sets one.
+
+- `SVGExportOptions.units` (`drawing-2d`) — `export()` never destructures it;
+  the exporter emits no dimension annotations and always sizes the sheet in
+  millimetres.
+- `OpeningFilterOptions.keepBoundarySegments` (`drawing-2d`) — merged into the
+  filter's options object but never consulted; `tolerance` is the only field
+  that governs how segments near an opening edge are treated.
+- `DoorSymbolConfig.showThreshold` (`drawing-2d`) — no threshold-rendering code
+  exists, so `true` and `false` produce identical geometry.
+- `SnapOptions.snapRadius` (`renderer`) — documented as a world-units snap
+  distance, but every proximity check reads `screenSnapRadius` (pixels).
+  Snapping is screen-space and zoom-dependent; set `screenSnapRadius` instead.
+- `SectionPlaneRenderOptions.flipped` (`renderer`) — the gizmo renderer never
+  reads it. The GPU clip plane flips correctly through separate state, so
+  cutting behaviour is unaffected; only the gizmo option is inert.
+- `RenderOptions.enableDepthTest` (`renderer`) — dead on both ends: nothing
+  sets it and nothing reads it. Depth comparison is fixed per pipeline at
+  construction time and is not configurable through `RenderOptions`.
+- `StreamingOptions.onMetadataBootstrap` (`geometry`) — an unfinished stub. Its
+  siblings `onBatch`, `onColorUpdate`, `onComplete` and `onError` are all
+  dispatched by the bridge; this one never is, so a callback passed here is
+  never called.
+
+Deprecating rather than deleting is deliberate: removing an optional field an
+embedder already passes converts a silent no-op into a TypeScript compile
+error, which is a worse first contact with the problem than a deprecation
+warning that explains it. Removal is left as a separate, explicitly versioned
+decision. See issue #2731 for the full audit; the findings that carry a
+behaviour decision (the streaming batch ramp-up, `GeometryQuality`, and the
+scale-bar / north-arrow renderer divergence) are deliberately untouched here.

docs/guide/rendering.md

@@ -266,7 +266,7 @@ canvas.addEventListener('mousemove', (e) => {
       snapToVertices: true,
       snapToEdges: true,
       snapToFaces: true,
-      snapRadius: 0.1,           // 10cm world units
+      snapRadius: 0.1,           // deprecated: ignored, screenSnapRadius is what is read
       screenSnapRadius: 20       // 20 pixels
     }
   });
@@ -300,7 +300,7 @@ canvas.addEventListener('mousemove', (e) => {
     snapOptions: {
       snapToVertices: true,
       snapToEdges: true,
-      snapRadius: 0.1,
+      snapRadius: 0.1,          // deprecated: ignored
       screenSnapRadius: 20
     }
   });
@@ -522,7 +522,7 @@ interface RenderOptions {
   clearColor?: [number, number, number, number];
 
   // Performance
-  enableDepthTest?: boolean;
+  enableDepthTest?: boolean;        // deprecated: declared but never read
   enableFrustumCulling?: boolean;
   spatialIndex?: SpatialIndex;
 

packages/drawing-2d/src/openings/opening-filter.ts

@@ -24,7 +24,16 @@ import { projectTo2D, getProjectionAxes } from '../math.js';
 export interface OpeningFilterOptions {
   /** Tolerance for point-in-bounds testing (world units) */
   tolerance: number;
-  /** Whether to keep segments at opening boundaries */
+  /**
+   * Declared but never read. The constructor merges it into `this.options`,
+   * but no method consults it: boundary handling is governed entirely by
+   * {@link tolerance}, which inflates the opening bounds in `pointInBounds`
+   * so a larger tolerance drops slightly more of the segment near the edge.
+   * Setting this to `false` does not make boundary segments disappear.
+   * Slated for removal; see issue #2731.
+   *
+   * @deprecated Ignored by the filter — `tolerance` is what governs boundaries.
+   */
   keepBoundarySegments: boolean;
 }
 

packages/drawing-2d/src/svg-exporter.ts

@@ -59,7 +59,15 @@ export interface SVGExportOptions {
   projectName?: string;
   /** Background color (default: white) */
   backgroundColor?: string;
-  /** Units for dimension display */
+  /**
+   * Declared but never read. `export()` does not destructure `units` and no
+   * other code path consults it, so setting it has no effect on the emitted
+   * SVG. The exporter emits no dimension annotations at all, and the sheet
+   * itself is always sized in millimetres (`width="…mm"`), so there is no
+   * substitute option to reach for. Slated for removal; see issue #2731.
+   *
+   * @deprecated Ignored by the exporter — see above.
+   */
   units?: 'mm' | 'm';
   /** DXF reference underlays rendered beneath the drawing (issue #1782) */
   underlays?: SVGUnderlayOptions[];

packages/drawing-2d/src/symbols/door-symbol.ts

@@ -44,7 +44,15 @@ export interface DoorSymbolConfig {
   swingAngle: number;
   /** Show door leaf line */
   showLeaf: boolean;
-  /** Show threshold line */
+  /**
+   * Declared but never read. No threshold-rendering code exists anywhere in
+   * the package, so this field cannot switch anything on: setting it to
+   * `true` produces exactly the same geometry as leaving it at the default
+   * `false`. There is no substitute option — a threshold line would have to
+   * be drawn by the caller. Slated for removal; see issue #2731.
+   *
+   * @deprecated Ignored by the generator — no threshold is ever drawn.
+   */
   showThreshold: boolean;
 }
 

packages/geometry/src/platform-bridge.ts

@@ -113,7 +113,17 @@ export interface GeometryProcessingResult {
 export interface StreamingOptions {
   /** Callback for each batch of meshes */
   onBatch?: (batch: GeometryBatch) => void;
-  /** Callback for early metadata bootstrap when available */
+  /**
+   * Declared but never read. This is the only occurrence of the name in the
+   * repository — no bridge implementation ever invokes it, so a callback
+   * passed here is never called and no "early metadata bootstrap" is
+   * delivered. Unlike its siblings ({@link onBatch}, {@link onColorUpdate},
+   * {@link onComplete}, {@link onError}), which are all dispatched, this one
+   * is an unfinished stub. There is no substitute callback; metadata must be
+   * read from the completed result. Slated for removal; see issue #2731.
+   *
+   * @deprecated Never invoked — see above.
+   */
   onMetadataBootstrap?: (bootstrap: MetadataBootstrapPayload) => void;
   /** Callback for deferred color updates */
   onColorUpdate?: (updates: Map<number, [number, number, number, number]>) => void;

packages/renderer/src/section-plane.ts

@@ -17,7 +17,18 @@ export interface SectionPlaneRenderOptions {
     max: { x: number; y: number; z: number };
   };
   viewProj: Float32Array;
-  flipped?: boolean; // If true, show the opposite side indicator
+  /**
+   * Declared but never read. `SectionPlaneRenderer.render()` never consults
+   * it, so the gizmo quad looks identical either way — this field cannot
+   * "show the opposite side indicator". Note that the actual GPU clip plane
+   * is flipped correctly elsewhere (`scene-raycaster.ts` and `point-picker.ts`
+   * read a `flipped` off their own section-plane state), so cutting behaviour
+   * is unaffected; only this gizmo option is inert. Slated for removal; see
+   * issue #2731.
+   *
+   * @deprecated Ignored by the gizmo renderer — see above.
+   */
+  flipped?: boolean;
   isPreview?: boolean; // If true, render as preview (less opacity)
   min?: number;      // Optional override for min range value
   max?: number;      // Optional override for max range value

packages/renderer/src/snap-detector.ts

@@ -33,6 +33,16 @@ export interface SnapOptions {
   snapToVertices: boolean;
   snapToEdges: boolean;
   snapToFaces: boolean;
+  /**
+   * Declared but never read. Documented as a world-units snap distance, but
+   * every proximity check in `SnapDetector` uses {@link screenSnapRadius}
+   * (pixels) instead — see the two call sites that pass `opts.screenSnapRadius`
+   * into the candidate search. Snapping is therefore purely screen-space and
+   * zoom-dependent; changing this value has no effect. Set
+   * {@link screenSnapRadius} instead. Slated for removal; see issue #2731.
+   *
+   * @deprecated Ignored — `screenSnapRadius` is the value that is read.
+   */
   snapRadius: number; // In world units
   screenSnapRadius: number; // In pixels
   /**

packages/renderer/src/types.ts

@@ -204,6 +204,15 @@ export interface RenderOptions {
    * look exactly. See {@link import('./environment.js').LightingEnvironment}.
    */
   environment?: import('./environment.js').LightingEnvironment;
+  /**
+   * Declared but never read. This is the only occurrence of the name in the
+   * package: nothing sets it and nothing consults it, so it is dead on both
+   * ends. Depth testing is decided per pipeline at construction time and is
+   * not configurable through `RenderOptions`; there is no substitute field.
+   * Slated for removal; see issue #2731.
+   *
+   * @deprecated Ignored by the renderer — see above.
+   */
   enableDepthTest?: boolean;
   enableFrustumCulling?: boolean;
   spatialIndex?: import('@ifc-lite/spatial').SpatialIndex;