three-cad-viewer 4.3.9 → 5.0.1

package/{README.md → Readme.md}

@@ -314,7 +314,7 @@ The keymap serves two purposes:
 - **Modifier keys** (`shift`, `ctrl`, `meta`, `alt`) remap which physical modifier key is used for mouse interactions (e.g. shift-click to isolate, ctrl-rotate). Values are DOM event properties like `"shiftKey"`, `"ctrlKey"`, `"metaKey"`, `"altKey"`.
 - **Action shortcuts** map single keys (with or without Shift) to toolbar buttons, camera presets, tab switches, and animation control. Only plain keys are supported — Ctrl/Alt/Meta combinations are reserved for modifier-based mouse interactions.
 
-Click on the viewer to give it focus, then press shortcut keys to trigger actions. Button tooltips show `[key]` suffixes when shortcuts are configured.
+Click on the viewer to give it focus, then press shortcut keys to trigger actions. Button and tab tooltips show a `› key` suffix when shortcuts are configured.
 
 The default keymap:
 
@@ -323,19 +323,19 @@ keymap: {
   // Modifier keys (remap physical keys for mouse interactions)
   shift: "shiftKey", ctrl: "ctrlKey", meta: "metaKey", alt: "altKey",
   // Toggle buttons
-  axes: "a", axes0: "A", grid: "g", gridxy: "G",
+  axes: "A", axes0: "0", grid: "g", gridxy: "G",
   perspective: "p", transparent: "t", blackedges: "b",
   explode: "x", zscale: "L",
-  distance: "D", properties: "P", select: "S",
+  distance: "D", properties: "P", select: "I",
   // Execute buttons
   reset: "R", resize: "r",
-  iso: "0", front: "1", rear: "2", top: "3", bottom: "4", left: "5", right: "6",
+  iso: "5", front: "1", rear: "3", top: "8", bottom: "2", left: "4", right: "6",
   // Help
   help: "h",
   // Animation
   play: " ", stop: "Escape",
   // Tab selection
-  tree: "T", clip: "C", material: "M", zebra: "Z",
+  tree: "T", clip: "C", material: "M", zebra: "Z", studio: "S",
 }
 ```
 
@@ -347,6 +347,8 @@ const displayOptions = {
 };
 ```
 
+**Topo filter shortcuts.** When the shape filter is visible (B-rep models), the lowercase keys `a` (All), `v` (Vertex), `e` (Edge), `f` (Face), `s` (Solid) set the picking filter. These are fixed (not part of the configurable keymap) — which is why `axes` and `studio` default to the uppercase `A`/`S`.
+
 ## Examples
 
 To understand the data format, a look at the simple 1 unit sized box might be helpful:

package/dist/core/picking-controller.d.ts

@@ -0,0 +1,125 @@
+import * as THREE from "three";
+import { type IdPicker } from "../rendering/id-picking.js";
+import { type PickedComponent } from "../rendering/picked.js";
+import type { Shapes } from "./types.js";
+import type { RenderedState } from "./viewer.js";
+import type { Display } from "../ui/display.js";
+import type { Tools } from "../tools/cad_tools/tools.js";
+/**
+ * The narrow surface {@link PickingController} needs from its host (the Viewer).
+ * Keeps the controller decoupled from the rest of the Viewer god-object and
+ * unit-testable. `rendered` is a lazy getter that throws before render() — the
+ * controller must always read through it (never cache `nestedGroup`/`highlight`,
+ * which are rebuilt every render()).
+ */
+export interface PickHost {
+    readonly idPicker: IdPicker | null;
+    readonly ready: boolean;
+    readonly hasAnimationLoop: boolean;
+    /** True while the Studio (presentation) tab owns the render. */
+    readonly studioActive: boolean;
+    readonly shapes: Shapes | null;
+    readonly renderer: THREE.WebGLRenderer;
+    readonly rendered: RenderedState;
+    readonly display: Display;
+    readonly cadTools: Tools;
+    update(updateMarker: boolean, notify: boolean): void;
+    /** Restore the most recently meta-double-click-hidden leaf (hide-undo stack). */
+    showLastHidden(): void;
+    handlePick(path: string, name: string, meta: boolean, shift: boolean, alt: boolean, point: THREE.Vector3 | null, nodeType?: string | null, tree?: boolean): void;
+}
+/**
+ * Owns all pointer-driven picking on the compact graph: hover preselection
+ * (highlight + status line), left-click selection commit, right-click/key removal,
+ * and double-click pick. Hover proposes the component under the cursor
+ * ({@link lastObject}); a left-click commits it ({@link lastSelection}) — one state
+ * machine, so both fields live here.
+ *
+ * Listener lifecycle: hover (pointermove/leave) is always-on and added at
+ * construction; selection (mousedown/mouseup + document keydown) is tool-scoped via
+ * {@link setSelectionInput}; double-click via {@link setPickHandler}. {@link dispose}
+ * tears them all down.
+ */
+export declare class PickingController {
+    private readonly host;
+    /** Component under the cursor (hover); committed on left-click. */
+    lastObject: PickedComponent | null;
+    /** Last committed selection. */
+    lastSelection: PickedComponent | null;
+    private idHoverClientX;
+    private idHoverClientY;
+    private idHoverInside;
+    private idHoverRenderQueued;
+    /** Per-component hover status text (fixed per mesh; cleared on reload / z-scale). */
+    private hoverStatusCache;
+    private selectionInputActive;
+    private selectDownPosition;
+    private pickHandlerActive;
+    constructor(host: PickHost);
+    /** Remove every listener this controller owns. */
+    dispose(): void;
+    /** Record the cursor position over the canvas. */
+    private onIdHoverMove;
+    /** Cursor left the canvas → clear any hover highlight. */
+    private onIdHoverLeave;
+    /**
+     * Whether hover preselection (highlight + status line) is active. Disabled for GDS:
+     * dense, stacked, instance-unrolled layout data where per-pixel hover flickers
+     * endlessly and the B-rep readout ("area ≈ …") is meaningless, so GDS is
+     * double-click-identify only. Also disabled in Studio (presentation) mode: hover
+     * tint/status is a CAD/analysis affordance, not wanted in Studio, and skipping it
+     * means the id buffer is never re-rendered for a bare mouse-move there.
+     */
+    private hoverPreselectActive;
+    /**
+     * Called once per render: drive hover preselection unless a model is GDS or the
+     * camera is being dragged.
+     */
+    handleHover(): void;
+    /**
+     * Hover via the GPU id picker on the compact graph: resolve the component under the
+     * cursor and drive the shader `HighlightController`. Sets {@link lastObject}
+     * (committed on left-click by {@link commitSelection} when a tool is active).
+     */
+    private handleIdHover;
+    /** Drop the cached hover texts (e.g. on z-scale change — world lengths change). */
+    invalidateHoverCache(): void;
+    /**
+     * Drop any lingering hover highlight + status line (keeping the committed selection).
+     * Called when entering Studio mode: hover preselection is disabled there, so the
+     * per-render {@link handleHover} no longer runs its own release and a stale tint/status
+     * from CAD mode would otherwise persist.
+     */
+    clearHover(): void;
+    /**
+     * Whether the component a pick resolved to is currently visible — used to drop picks
+     * of hidden geometry. Visibility is the owning group's material `visible` flag
+     * (faces for solids/standalone faces; edge/vertex materials for standalone leaves).
+     */
+    private pickVisible;
+    clearSelection: () => void;
+    private releaseLastSelected;
+    removeLastSelected(): void;
+    /** Drop selection state + hover cache + status line (on model reload). */
+    reset(): void;
+    /**
+     * Add/remove the canvas mousedown+mouseup and document keydown listeners
+     * (idempotent, guarded on `selectionInputActive`). Hover maintains
+     * {@link lastObject}; these handlers commit it on left-click and handle the key +
+     * right-click actions.
+     */
+    setSelectionInput(flag: boolean): void;
+    private onSelectMouseDown;
+    private onSelectMouseUp;
+    private onSelectKeyDown;
+    private commitSelection;
+    setPickHandler(flag: boolean): void;
+    /**
+     * Double-click pick via the GPU id picker: `idPicker.pickAt` resolves the component
+     * under the cursor, the registry gives its owning tree-leaf path ({@link leafPath}),
+     * and the readback world-space `point` feeds `handlePick` (the `shift && meta` camera
+     * target, with a bbox-center fallback when `point` is null). No topo filter: a
+     * double-click selects whatever is under the cursor and resolves it to its leaf.
+     */
+    private onDoubleClick;
+}

package/dist/core/types.d.ts

@@ -185,8 +185,12 @@ export interface DisplayOptions {
     zebraTool?: boolean;
     /** Show studio tool (default: true) */
     studioTool?: boolean;
-    /** Enable measurement debug mode (default: false) */
-    measurementDebug?: boolean;
+    /**
+     * Use an external (Python/`ocp_vscode`) measurement backend (default: false).
+     * When false, the built-in TypeScript mesh-based measurement backend answers
+     * measurements locally — so measure works without a backend connection.
+     */
+    externalMeasurementBackend?: boolean;
     /** External canvas element to use for the WebGL renderer, enabling shared WebGL context scenarios (default: undefined — renderer creates its own canvas) */
     canvas?: HTMLCanvasElement;
     /** External WebGL context to use for the renderer. When provided together with `canvas`, the renderer will use this context instead of creating a new one. Useful for sharing a context with other renderers like PixiJS. (default: undefined) */
@@ -338,7 +342,7 @@ export interface ViewerStateShape {
     zscaleTool: boolean;
     zebraTool: boolean;
     studioTool: boolean;
-    measurementDebug: boolean;
+    externalMeasurementBackend: boolean;
     ambientIntensity: number;
     directIntensity: number;
     metalness: number;
@@ -501,9 +505,12 @@ export interface MaterialAppearance {
  *
  * This format is produced by the threejs-materials Python library, which catalogs
  * PBR materials from ambientCG, GPUOpen, PolyHaven, and PhysicallyBased.
- * `values` contains scalar properties (e.g., color as linear RGB array,
- * roughness as float).  `textures` contains texture references (inline data URIs
- * or file paths) keyed by property name.
+ * `values` contains scalar properties (e.g., color as an sRGB RGB array,
+ * roughness as float).  Note the per-key color-space convention: `color` is
+ * sRGB-stored, while `emissive`/`specularColor`/`sheenColor`/`attenuationColor`
+ * are linear-stored (see MaterialFactory.createStudioMaterialFromMaterialX).
+ * `textures` contains texture references (inline data URIs or file paths)
+ * keyed by property name.
  *
  * Detected by the presence of the `values` key.
  * Extra keys from threejs-materials (id, name, source, url, license) pass through

package/dist/core/viewer-state.d.ts

@@ -20,7 +20,7 @@ interface DisplayDefaults {
     zscaleTool: boolean;
     zebraTool: boolean;
     studioTool: boolean;
-    measurementDebug: boolean;
+    externalMeasurementBackend: boolean;
 }
 /**
  * Render configuration defaults

package/dist/core/viewer.d.ts

@@ -19,7 +19,10 @@ import { Controls } from "../camera/controls.js";
 import { Camera, type CameraDirection } from "../camera/camera.js";
 import { BoundingBox, BoxHelper } from "../scene/bbox.js";
 import { Tools } from "../tools/cad_tools/tools.js";
-import { PickedObject, Raycaster } from "../rendering/raycast.js";
+import { MeshMeasureBackend } from "../tools/cad_tools/mesh-measure.js";
+import { IdPicker } from "../rendering/id-picking.js";
+import { type PickedComponent } from "../rendering/picked.js";
+import { PickingController } from "./picking-controller.js";
 import { ViewerState } from "./viewer-state.js";
 import type { Display } from "../ui/display.js";
 import type { Vector3Tuple, QuaternionTuple } from "three";
@@ -70,14 +73,6 @@ interface ImageResult {
     task: string;
     dataUrl: string | ArrayBuffer | null;
 }
-/**
- * Raycast event from keyboard or mouse.
- */
-interface RaycastEvent {
-    key?: string;
-    mouse?: "left" | "right";
-    shift?: boolean;
-}
 /**
  * Backend response structure.
  */
@@ -90,7 +85,7 @@ interface BackendResponse {
  */
 interface DisplayOptionsInternal {
     measureTools?: boolean;
-    measurementDebug?: boolean;
+    externalMeasurementBackend?: boolean;
     selectTool?: boolean;
     explodeTool?: boolean;
     zscaleTool?: boolean;
@@ -106,7 +101,7 @@ interface DisplayOptionsInternal {
  * State that exists only after render() and before clear().
  * Groups all resources that are created together during rendering.
  */
-interface RenderedState {
+export interface RenderedState {
     scene: THREE.Scene;
     ambientLight: THREE.AmbientLight;
     directLight: THREE.DirectionalLight;
@@ -167,6 +162,12 @@ declare class Viewer {
     onAfterRender: (() => void) | null;
     mouse: THREE.Vector2;
     cadTools: Tools;
+    /**
+     * Internal mesh-based measurement backend, used when
+     * `externalMeasurementBackend === false` (the default). Resolves component paths
+     * against the compact group's {@link MeshGeometrySource}.
+     */
+    meshBackend: MeshMeasureBackend;
     animation: Animation;
     clipNormals: [THREE.Vector3, THREE.Vector3, THREE.Vector3];
     private _rendered;
@@ -183,7 +184,6 @@ declare class Viewer {
     private _pendingDisposal;
     shapes: Shapes | null;
     gridSize: number;
-    private _previousGridSize;
     hasAnimationLoop: boolean;
     mixer: THREE.AnimationMixer | null;
     continueAnimation: boolean;
@@ -194,19 +194,24 @@ declare class Viewer {
     renderOptions: RenderOptions | null;
     lastNotification: Record<string, unknown>;
     lastBbox: LastBboxInfo | null;
-    lastObject: PickedObject | null;
-    lastSelection: PickedObject | null;
+    private _hiddenUndo;
     lastPosition: THREE.Vector3 | null;
     bboxNeedsUpdate: boolean;
     keepHighlight: boolean;
-    expandedTree: ShapeTreeData | null;
     compactTree: ShapeTreeData | null;
-    expandedNestedGroup: NestedGroup | null;
     compactNestedGroup: NestedGroup | null;
-    raycaster: Raycaster | null;
+    private _lastPickCam;
+    private _lastPickProj;
+    private _lastClipSig;
+    private _suppressUpdate;
+    private _zebraSettingsApplied;
+    idPicker: IdPicker | null;
+    pickingController: PickingController;
     private _studioManager;
     /** Environment manager — proxied from StudioManager for display.ts access. */
     get envManager(): import("../index.js").EnvironmentManager;
+    /** True while the Studio (presentation) tab owns the render. PickHost member. */
+    get studioActive(): boolean;
     zScale: number;
     clipNormal0: Vector3Tuple | null;
     clipNormal1: Vector3Tuple | null;
@@ -251,11 +256,10 @@ declare class Viewer {
     private getShapeRenderer;
     /**
      * Render the shapes of the CAD object.
-     * @param exploded - Whether to render the compact or exploded version
      * @param shapes - The Shapes object.
      * @returns A nested THREE.Group object and navigation tree.
      */
-    renderTessellatedShapes(exploded: boolean, shapes: Shapes): RenderResult;
+    renderTessellatedShapes(shapes: Shapes): RenderResult;
     /**
      * Add a position animation track (full 3D translation).
      * @param selector - path/id of group to be animated.
@@ -342,7 +346,7 @@ declare class Viewer {
      * - WebGL renderer and context
      * - All Three.js objects (geometries, materials, textures)
      * - Event listeners
-     * - CAD tools and raycaster
+     * - CAD tools and id picker
      *
      * After calling dispose(), the viewer instance should not be used.
      *
@@ -358,15 +362,6 @@ declare class Viewer {
      * @public
      */
     clear(): void;
-    /**
-     * Synchronizes the states of two tree structures recursively.
-     *
-     * @param compactTree - The compact tree structure.
-     * @param expandedTree - The expanded tree structure.
-     * @param exploded - Whether rendering in exploded mode.
-     * @param path - The current path in the tree structure.
-     */
-    syncTreeStates: (compactTree: ShapeTreeData | VisibilityState, expandedTree: ShapeTreeData | VisibilityState, exploded: boolean, path: string) => void;
     /**
      * Get the color of a node from its path
      * @param path - path of the CAD object
@@ -375,16 +370,9 @@ declare class Viewer {
     /**
      * Build nestedGroup and treeview for initial render.
      * @param scene - The scene to add the group to
-     * @param expanded - whether to render the exploded or compact version
      * @returns The nestedGroup and treeview
      */
     private buildInitialGroup;
-    /**
-     * Toggle the two version of the NestedGroup.
-     * Must only be called after render() has completed.
-     * @param expanded - whether to render the exploded or compact version
-     */
-    toggleGroup(expanded: boolean): void;
     /**
      * Set the active sidebar tab.
      * @param tabName - Tab name: "tree", "clip", "material", "zebra", or "studio"
@@ -534,22 +522,30 @@ declare class Viewer {
      * @param tree - whether from tree
      */
     handlePick: (path: string, name: string, meta: boolean, shift: boolean, alt: boolean, point: THREE.Vector3 | null, nodeType?: string | null, tree?: boolean) => void;
-    setPickHandler(flag: boolean): void;
     /**
-     * Find the shape that was double clicked and send notification
-     * @param e - a DOM PointerEvent or MouseEvent
+     * Record a leaf about to be hidden via meta-double-click onto the hide-undo stack,
+     * capturing its current (pre-hide) visibility state for a faithful restore. Dedups:
+     * an existing entry for the same id is dropped so the id moves to the top.
      */
-    pick: (e: PointerEvent | MouseEvent) => void;
-    clearSelection: () => void;
-    _releaseLastSelected: () => void;
-    _removeLastSelected: () => void;
+    private _recordHidden;
     /**
-     * Set raycast mode
-     * @param flag - turn raycast mode on or off
+     * Restore the most recently meta-double-click-hidden leaf (LIFO), skipping entries
+     * that no longer apply — removed objects, or ones already shown again via the tree.
+     * In Studio the restored leaf keeps edges off (presentation); in CAD its pre-hide
+     * edge state is restored. Bound to a meta-double-click on empty space, so a hidden
+     * object can be brought back without the tree (notably in Studio). @public
      */
-    setRaycastMode(flag: boolean): void;
-    handleRaycast: () => void;
-    handleRaycastEvent: (event: RaycastEvent) => void;
+    showLastHidden: () => void;
+    /** Component under the cursor (hover); committed on left-click. */
+    get lastObject(): PickedComponent | null;
+    /** Last committed selection. */
+    get lastSelection(): PickedComponent | null;
+    /** Enable/disable the double-click pick handler (on when no tool is active). */
+    setPickHandler(flag: boolean): void;
+    /** Enable/disable click+key selection input (on while a select/measure tool is active). */
+    setSelectionInput(flag: boolean): void;
+    /** Clear the current selection (and reset the select tool). */
+    clearSelection: () => void;
     /**
      * Handle a backend response sent by the backend
      * The response is a JSON object sent by the Python backend through VSCode

package/dist/rendering/highlight.d.ts

@@ -0,0 +1,209 @@
+import * as THREE from "three";
+import type { ComponentRegistry } from "./id-picking.js";
+/**
+ * Shader-based component highlight (compact graph).
+ *
+ * Design:
+ * - Per-component highlight state lives in ONE `R8UI` data texture indexed by
+ *   `componentId` (the attribute already on the compact geometry). The texture is
+ *   shared by every compact visual material via `onBeforeCompile`, so a state
+ *   write is reflected by all materials with no recompile.
+ * - State is BIT FLAGS ({@link HighlightFlag}); SELECTED wins over HOVER.
+ * - `selectSolid` sets the flag for every registry component sharing a `solidPath`.
+ *
+ * Driven by the live event loop via `IdPicker.pickAt → registry → controller`.
+ */
+/** Highlight color for a selected component (was `ObjectGroup.HIGHLIGHT_COLOR_SELECTED`). */
+export declare const HIGHLIGHT_COLOR_SELECTED = 5480675;
+/** Highlight color for a hovered, not-selected component (was `HIGHLIGHT_COLOR_HOVER`). */
+export declare const HIGHLIGHT_COLOR_HOVER = 9026019;
+/**
+ * Per-topo FOCUS BASE sizes (was `ObjectGroup.vertexFocusSize` / `edgeFocusWidth`).
+ * These are injected PER-MATERIAL by the `patch*Material` methods (a `#define` /
+ * material-local uniform), NOT via the shared {@link HighlightUniforms} — edges
+ * (5) and vertices (8) need different values, and the hover-vs-selected `−2` delta
+ * (`objectgroup.ts:285-298 widen()`) is resolved in-shader from the {@link
+ * HighlightFlag} bits: `HOVER → base`, `SELECTED && !HOVER → base − 2`, else the
+ * material's authored size.
+ */
+export declare const VERTEX_FOCUS_SIZE = 6;
+export declare const EDGE_FOCUS_WIDTH = 5;
+/**
+ * Per-component highlight state, stored as bit flags in one texel of the state
+ * texture. SELECTED takes precedence over HOVER when both are set, so hovering an
+ * already-selected component keeps the selected color (matches the old
+ * `_getHighlightColor` / `unhighlight(true)`).
+ */
+export declare const HighlightFlag: {
+    readonly NONE: 0;
+    readonly SELECTED: number;
+    readonly HOVER: number;
+};
+export type HighlightFlagValue = (typeof HighlightFlag)[keyof typeof HighlightFlag];
+/**
+ * Width of the highlight-state data texture in texels. Height grows with the
+ * component count: `height = ceil((maxId + 1) / WIDTH)`. A component's texel is at
+ * `(id % WIDTH, floor(id / WIDTH))` — the same mapping the shader recomputes.
+ */
+export declare const HIGHLIGHT_STATE_TEXTURE_WIDTH = 2048;
+/** Uniform: the shared `usampler2D` highlight-state texture (R8UI). */
+export declare const U_HIGHLIGHT_STATE = "uHighlightState";
+/** Uniform: texture width, for `id -> ivec2` texel coordinates. */
+export declare const U_HIGHLIGHT_TEX_WIDTH = "uHighlightTexWidth";
+/** Uniform: selected color (linear RGB vec3). */
+export declare const U_HIGHLIGHT_SELECTED_COLOR = "uHighlightSelectedColor";
+/** Uniform: hover color (linear RGB vec3). */
+export declare const U_HIGHLIGHT_HOVER_COLOR = "uHighlightHoverColor";
+/**
+ * The shared `THREE.IUniform` set bound into every patched compact material. One
+ * instance per {@link HighlightController}; the same object is referenced by all
+ * materials so a single write updates them together. Property names MUST match the
+ * `U_HIGHLIGHT_*` GLSL identifier constants above.
+ *
+ * Intentionally TOPO-AGNOSTIC: focus sizes are per-topo and the original (authored)
+ * size is per-material, so those are injected by `patch*Material` per material —
+ * NOT here. See {@link VERTEX_FOCUS_SIZE} / {@link EDGE_FOCUS_WIDTH}.
+ */
+export interface HighlightUniforms {
+    uHighlightState: {
+        value: THREE.DataTexture | null;
+    };
+    uHighlightTexWidth: {
+        value: number;
+    };
+    uHighlightSelectedColor: {
+        value: THREE.Color;
+    };
+    uHighlightHoverColor: {
+        value: THREE.Color;
+    };
+}
+/**
+ * Minimal material surface the patch methods need. Declared structurally because
+ * three's examples-jsm `LineMaterial` has a `vertexColors: string | boolean` field
+ * that is not assignable to the nominal `THREE.Material` type.
+ */
+type PatchableMaterial = Pick<THREE.Material, "onBeforeCompile" | "customProgramCacheKey" | "needsUpdate" | "userData">;
+/**
+ * Owns the per-component highlight state texture and patches compact visual
+ * materials to read it. Created by the compact `NestedGroup` alongside its
+ * `ComponentRegistry`.
+ *
+ * Lifecycle: construct → `patch*Material` on each compact face/edge/vertex visual
+ * material as it is built → `resize(registry.maxId)` once all components are
+ * registered → `setHover` / `setSelected` / `selectSolid` / `clear` to drive
+ * highlight → `dispose`.
+ */
+export declare class HighlightController {
+    /** The registry whose ids index the state texture. */
+    readonly registry: ComponentRegistry;
+    /** Shared uniforms bound into every patched material. */
+    readonly uniforms: HighlightUniforms;
+    /** Backing R8UI state texture (one byte = {@link HighlightFlag} bits per id). */
+    private texture;
+    /** CPU-side mirror of the texture data (length = `capacity`). */
+    private data;
+    /** Number of texels currently allocated (= width * height ≥ maxId + 1). */
+    private capacity;
+    /** Ids currently carrying the HOVER flag (one component, or a whole solid). */
+    private hoverIds;
+    /** Cheap identity of the current hover target so a repeat is a no-op. */
+    private hoverKey;
+    /**
+     * @param registry - the compact group's component registry; sizes the texture
+     *   and resolves `solidPath` for {@link selectSolid}.
+     */
+    constructor(registry: ComponentRegistry);
+    /**
+     * Allocate an R8UI data texture (+ CPU mirror) holding at least `texelCount`
+     * texels. `NearestFilter`, no mips — the shader reads exact integer flags via
+     * `texelFetch`. This is the FROZEN texture format.
+     */
+    private _allocate;
+    /** The shared state texture (re-created by {@link resize}). */
+    get stateTexture(): THREE.DataTexture;
+    /**
+     * Set or clear `bit` on a component's texel and flag the texture for re-upload
+     * on change. The linear data index equals the id (row-major, width-W texels), so
+     * texel `(id % W, floor(id / W))` is `data[id]`. Ignores background (0) and ids
+     * past the current capacity (caller must {@link resize} first).
+     */
+    private _setBit;
+    /**
+     * Move the HOVER flag onto exactly the given `ids` (clearing it from the
+     * previously hovered set). `key` is a cheap identity so a repeat target is a
+     * no-op — without it, re-hovering the same target every mouse-move would toggle
+     * the bits off→on and re-upload the texture each frame. Does not touch SELECTED.
+     */
+    private _applyHover;
+    /**
+     * Move the HOVER flag onto a single component `id` (clearing the previous hover),
+     * or clear hover entirely when `id` is `null`/background.
+     */
+    setHover(id: number | null): void;
+    /**
+     * HOVER a whole solid (its FACES only — see {@link selectSolid}), or clear hover
+     * when `null`. Mirrors {@link selectSolid} for the transient hover state.
+     */
+    setHoverSolid(solidPath: string | null): void;
+    /** Set or clear the SELECTED flag for a single component id. */
+    setSelected(id: number, flag: boolean): void;
+    /** Whether a component currently carries the SELECTED flag. */
+    isSelected(id: number): boolean;
+    /**
+     * Whether a solid is selected — every one of its faces carries SELECTED (false if it
+     * has no faces). Used for solid toggle, so a solid that is only partially selected
+     * (e.g. one face previously single-selected) is treated as not-selected and a click
+     * selects the whole solid rather than clearing it.
+     */
+    isSolidSelected(solidPath: string): boolean;
+    /**
+     * Set or clear SELECTED for a whole solid. Flags only the solid's **faces**
+     * (`topo === "face"`) — the body tints while edges keep their colour and corners
+     * stay hidden. Iterates {@link ComponentRegistry.entries}.
+     */
+    selectSolid(solidPath: string, flag: boolean): void;
+    /** Clear all highlight state (hover + selection) for every component. */
+    clear(): void;
+    /**
+     * Grow the state texture to hold at least `maxId + 1` texels, preserving existing
+     * state, and re-bind the new texture object into {@link uniforms}. No-op when the
+     * current capacity already suffices.
+     */
+    resize(maxId: number): void;
+    /**
+     * Shared `onBeforeCompile` installer: binds the shared uniforms, prepends the
+     * common vertex/fragment headers, forwards the component id, then runs the
+     * topo-specific `customize` (color override / widening). Idempotent per material.
+     */
+    private _install;
+    /**
+     * Install `onBeforeCompile` on a face (`MeshStandardMaterial`) visual material.
+     * Overwrites `diffuseColor.rgb` with the highlight color BEFORE lighting (after
+     * the base color/map is applied) so a highlighted face is lit exactly as the old
+     * `material.color` swap was — selected wins over hover.
+     */
+    patchFaceMaterial(material: PatchableMaterial): void;
+    /**
+     * Install `onBeforeCompile` on an edge (`LineMaterial`) visual material (Option A).
+     * Widens the screen-space half-width for flagged segments by patching the stock
+     * LineMaterial expansion (`offset *= linewidth;`, screen-space branch) and recolors
+     * via the shared fragment override. `vertexColors` axes/trihedron carry no
+     * registry id (state 0) so they stay inert.
+     */
+    patchEdgeMaterial(material: PatchableMaterial): void;
+    /**
+     * Install `onBeforeCompile` on a vertex (`PointsMaterial`) visual material.
+     * Flagged points widen to the focus size and recolor. When `cullUnhighlighted`
+     * (the solid highlight-Points cloud, invisible until selected), non-flagged points
+     * are culled — `gl_PointSize = 0` AND a fragment `discard` (the discard is the
+     * real guard; size-0 rasterization is driver-defined). Standalone visible vertices
+     * (default) keep their authored `size` and color when unflagged.
+     */
+    patchVertexMaterial(material: PatchableMaterial, options?: {
+        cullUnhighlighted?: boolean;
+    }): void;
+    /** Dispose the state texture and release tracking. */
+    dispose(): void;
+}
+export {};