@deltarobotics/uhd-viewer 0.0.0-stage → 0.2.1

package/dist/components/types/uhd-viewer/src/api.d.ts

@@ -0,0 +1,286 @@
+/**
+ * The viewer's public contract for hosts (docs: protoboard-cli/docs/specs/uhd-boundary.md,
+ * "The viewer contract"). A host gives the viewer a UHD bundle, may replace or
+ * extend how artifact files resolve, may add diagnostics of its own, and may
+ * take over saving the layout the user edits. Nothing here names a host.
+ *
+ * This file holds types only, so the published declarations stay small.
+ */
+import type { UhdBundle, UhdBundleDiagnostic } from "@deltarobotics/uhd";
+/** URL for a definition's artifact file path, or undefined if it cannot be resolved. */
+export type ArtifactResolver = (definitionId: string, filePath: string) => string | undefined;
+/** A link's hand layout on one drill level. */
+export interface LinkLayout {
+    /** Pinned waypoints [x, y] in absolute canvas coordinates (the router passes through them in order). */
+    waypoints?: [number, number][];
+    /** Label + toggle position as a fraction along the route (0..1). */
+    labelT?: number;
+    /** Label on the other side of the line (below a horizontal stretch, left of a vertical one). */
+    labelFlip?: boolean;
+    /** Harness name tab position as a fraction along the route (absent: placed automatically). */
+    tabT?: number;
+    /** Tab on the same side as the label (it defaults to the opposite side). */
+    tabFlip?: boolean;
+}
+/**
+ * Layout edits made in the viewer, on top of the bundle's display hints.
+ * Both maps are keyed by drill level (instance path joined with "/", "" = top).
+ */
+export interface ViewerLayout {
+    /** Dragged node positions: top-level nodes absolute, nodes inside a container relative to it. */
+    positions: Record<string, Record<string, {
+        x: number;
+        y: number;
+    }>>;
+    /** Pinned waypoints and label/tab positions by link id. */
+    links: Record<string, Record<string, LinkLayout>>;
+}
+/** A view of the diagram: the pan offset in pixels and the zoom factor. */
+export interface ViewerViewport {
+    x: number;
+    y: number;
+    zoom: number;
+}
+/** The tones a mark can take; each is a token of the theme (`--uhd-mark-<tone>`). */
+export type NodeMarkTone = "neutral" | "info" | "ok" | "warning" | "error";
+/** A host's mark on a module (`ViewerOptions.nodeMarks`). */
+export interface NodeMark {
+    tone: NodeMarkTone;
+    /** What the mark means, for the tooltip. */
+    label?: string;
+    /** `"ring"`: the tone as a dashed ring instead of a filled dot, for a module that stands for something not chosen yet. Default: a dot. */
+    shape?: "dot" | "ring";
+}
+export interface ViewerOptions {
+    /** The bundle itself. Relative artifact paths resolve against `bundleUrl` when both are given. */
+    bundle?: UhdBundle;
+    /** Where to fetch the bundle from (used when `bundle` is not given). */
+    bundleUrl?: string;
+    /**
+     * Replaces or extends artifact resolution. `fallback` is the default
+     * resolver (the bundle's per-definition artifact bases).
+     */
+    resolveArtifact?: (definitionId: string, filePath: string, fallback: ArtifactResolver) => string | undefined;
+    /**
+     * Findings from the host, listed in the checks panel next to the bundle's
+     * own. Like the bundle's, they describe the nominal build and are shown for
+     * the nominal scenario only.
+     */
+    diagnostics?: UhdBundleDiagnostic[];
+    /**
+     * A mark per definition, by definition id: the dot in the corner of every
+     * module card drawn from that definition takes the mark's tone and says its
+     * label on hover. For what the host knows about a part and the bundle does
+     * not (where it comes from, whether it was reviewed). A module with no mark
+     * keeps the dot of its links' state.
+     */
+    nodeMarks?: Record<string, NodeMark>;
+    /**
+     * The layout edits to show (only used together with `onLayoutChange`). A
+     * different layout passed later through `update` replaces the viewer's
+     * current edits, for example after the host's saved layout changed on disk.
+     * Passing back what `onLayoutChange` sent changes nothing.
+     */
+    layout?: ViewerLayout;
+    /**
+     * Called (debounced) with the whole edited layout after every change. When
+     * given, the host owns the layout and the viewer stops keeping it in local
+     * storage.
+     */
+    onLayoutChange?: (layout: ViewerLayout) => void;
+    /** The viewer has a model on screen and takes host messages from now on. */
+    onReady?: () => void;
+    /** Every change of the selection, in the diagram or the 3D view (null: nothing selected). */
+    onSelectionChanged?: (selection: ViewerSelection | null) => void;
+    /**
+     * The user asked to see where a module is defined (the inspector's OPEN
+     * SOURCE, a node's context menu). Given: the viewer offers these actions.
+     */
+    onOpenSource?: (request: {
+        defId: string;
+        instancePath?: string;
+    }) => void;
+    /**
+     * The user picked an artifact file in the inspector. Given: the host opens
+     * it; otherwise the viewer opens the file's URL in a new tab.
+     */
+    onOpenArtifact?: (request: {
+        defId: string;
+        artifactId: string;
+    }) => void;
+    /**
+     * The user asked to open a module on its own (a double-click on it, OPEN IN
+     * NEW TAB in its context menu): `path` is its instance path from the root.
+     * Given: double-click opens the module there (a host's new tab or window),
+     * and expanding it in place moves to the context menu. Not given:
+     * double-click expands the module in place.
+     */
+    onOpenModule?: (request: {
+        path: string;
+    }) => void;
+    /**
+     * The user asked for the pair view of a link (the inspector's pair
+     * preview). Given: the host shows it (its own tab or window); otherwise
+     * the viewer opens it over the diagram. `linkId` is the link as a
+     * selection names it, `a` and `b` the instance paths of the two modules it
+     * joins.
+     */
+    onOpenPair?: (request: {
+        linkId: string;
+        a: string;
+        b: string;
+    }) => void;
+    /**
+     * The user asked to inspect a module (INSPECT in its context menu): `path`
+     * is its instance path from the root. Given: the host shows it in an
+     * inspector of its own; otherwise the viewer opens its own panel. The
+     * module is selected either way (`onSelectionChanged` says so first).
+     */
+    onInspect?: (request: {
+        path: string;
+        defId?: string;
+    }) => void;
+    /**
+     * Where the user left the view of each drill level (keyed like the layout;
+     * only used together with `onViewportChange`). A level with a viewport
+     * opens on it; a level with none is fitted to the diagram.
+     */
+    viewports?: Record<string, ViewerViewport>;
+    /**
+     * Called with every level's viewport after the user pans or zooms (a fit
+     * the user asks for drops that level's entry). When given, the host keeps
+     * the viewports and the viewer stops keeping them in local storage.
+     */
+    onViewportChange?: (viewports: Record<string, ViewerViewport>) => void;
+    /**
+     * Talk to the parent window over `postMessage` (the viewer in a frame):
+     * host messages are accepted from `window.parent` only, and only from the
+     * listed origins (exact origins, `scheme://*`, or `*`; default: the page's
+     * own origin); events are posted to the parent, at its origin. Open actions
+     * then go to the parent. `true` uses the defaults. Off unless given.
+     */
+    parentWindow?: boolean | {
+        origins?: string[];
+    };
+    /**
+     * How the viewer looks: its own `"dark"` (default) or `"light"` theme,
+     * `"system"` (whichever the system prefers), `"vscode"` (follows the VS Code
+     * colour theme of the webview it runs in, high contrast included), a theme
+     * of the host's (tokens it leaves out come from the default), or an adapter
+     * that tells the viewer when the host's theme changes.
+     */
+    theme?: ViewerThemeOption;
+}
+/** A theme: values for the viewer's semantic tokens (docs: README, "Theming"). */
+export interface ViewerTheme {
+    id: string;
+    label: string;
+    scheme: "dark" | "light" | "high-contrast" | "high-contrast-light";
+    /** Token values by token name (`accent`, `surface`, `textMuted`, …): any CSS value, `var(...)` included. */
+    tokens: Partial<Record<string, string>>;
+}
+/** Where a host's theme comes from, when it can change while the viewer is open. */
+export interface ViewerThemeAdapter {
+    id: string;
+    current(): ViewerTheme;
+    subscribe?(onChange: (theme: ViewerTheme) => void): () => void;
+}
+export type ViewerThemeOption = "dark" | "light" | "system" | "vscode" | ViewerTheme | ViewerThemeAdapter;
+/** What a view shows: the diagram or the assembled 3D model. */
+export type ViewerView = "diagram" | "3d";
+/**
+ * A selection as the host sees it. Ids are canonical paths from the root
+ * system: a module's instance path (`arm_fl/motor`), a link's owner path and
+ * id (`stack/fc_esc`, as UHD's system checks name links).
+ */
+export interface ViewerSelection {
+    kind: "node" | "link";
+    id: string;
+    /** The selected module's definition id (a link's: the module that declares it). */
+    defId?: string;
+    /**
+     * Modules selected together (a selection box, Shift- or Ctrl-click, select all), two or more: every one, by
+     * path from the root. `id` is the first of them.
+     */
+    ids?: string[];
+}
+/** Host → viewer messages (`window.postMessage`, or the handle's methods). */
+export type ViewerHostMessage = 
+/** Drill to the level that holds the module, select it and centre it. */
+{
+    type: "uhd-viewer:focus";
+    path: string;
+}
+/**
+ * Select on the current level (the first id that is there; none: clear the
+ * selection). The diagram pans (zooming out only if it must) to bring the
+ * selection into view when it is not; `reveal: false` leaves the view where it is.
+ */
+ | {
+    type: "uhd-viewer:select";
+    ids: string[];
+    reveal?: boolean;
+}
+/** Show the level of this instance path ("" is the root system). */
+ | {
+    type: "uhd-viewer:drill";
+    path: string;
+} | {
+    type: "uhd-viewer:setView";
+    view: ViewerView;
+};
+/** Viewer → host events (posted to the parent window, or the options' callbacks). */
+export type ViewerEvent = {
+    type: "uhd-viewer:ready";
+} | {
+    type: "uhd-viewer:selectionChanged";
+    selection: ViewerSelection | null;
+} | {
+    type: "uhd-viewer:openSource";
+    defId: string;
+    instancePath?: string;
+} | {
+    type: "uhd-viewer:openArtifact";
+    defId: string;
+    artifactId: string;
+} | {
+    type: "uhd-viewer:openModule";
+    path: string;
+} | {
+    type: "uhd-viewer:openPair";
+    linkId: string;
+    a: string;
+    b: string;
+} | {
+    type: "uhd-viewer:inspect";
+    path: string;
+    defId?: string;
+};
+export interface ViewerHandle {
+    /**
+     * Re-renders with changed options (a rebuilt bundle, new host diagnostics, a
+     * changed layout). The change is merged into the current options; giving
+     * `bundleUrl` without `bundle` drops a bundle given earlier and loads from
+     * the URL.
+     */
+    update(options: Partial<ViewerOptions>): void;
+    unmount(): void;
+    /** Drill to the level that holds the module at `path`, select it and centre it. */
+    focus(path: string): void;
+    /**
+     * Select on the current level: the first of `ids` drawn there (an empty list
+     * clears the selection), brought into view unless `reveal` is false.
+     */
+    select(ids: string[], options?: {
+        reveal?: boolean;
+    }): void;
+    /** Show the level of an instance path ("" is the root system). */
+    drill(path: string): void;
+    setView(view: ViewerView): void;
+    /**
+     * Apply a host message object, as it arrives over `postMessage`. Returns
+     * false when it is not a valid viewer message. Messages sent before the
+     * model is on screen wait for it.
+     */
+    post(message: unknown): boolean;
+}

package/dist/components/types/uhd-viewer/src/cad/CadView.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 3D view (PB-775): the quadcopter assembled from UHD links, with interface
+ * geometry resolved through three binding directions, mounting hardware
+ * placed from the harnesses' fastener stacks, wire harnesses drawn from their
+ * own routed artifacts (placed by the parts they connect), and callout labels.
+ */
+import { type ReactNode } from "react";
+import type { ModuleDef } from "@deltarobotics/uhd";
+import type { ModuleLookup } from "@deltarobotics/uhd";
+import type { UhdBundleDiagnostic } from "@deltarobotics/uhd";
+import type { LoadedSource } from "../source/source";
+import type { ScopedDiagnostic } from "../model/diagnostics";
+export interface CadSelection {
+    body?: string;
+    iface?: string;
+    /** A component drawn inside the selected body (a board's part in board.glb), by instance path. */
+    component?: string;
+    mate?: string;
+    /** A routed wire harness, by instance path. */
+    harness?: string;
+}
+export declare function CadView({ system, lookup, source, diagnostics, hostDiagnostics, focusOn, onSelect, inspector, scope, emptyHint, }: {
+    /** The root system: every path a host gives or hears is from it. */
+    system: ModuleDef;
+    lookup: ModuleLookup;
+    source: LoadedSource;
+    /** The viewer's own checks (root and boards) and the host's findings, pinned to the model where they name something placed. */
+    diagnostics?: ScopedDiagnostic[];
+    hostDiagnostics?: UhdBundleDiagnostic[];
+    /**
+     * A host's focus or select, by instance path; `seq` tells repeats apart. A
+     * node selects the module's body and (with `look`, the default) looks at it;
+     * a link selects the mate of that path (`owner/link`); `none` clears.
+     */
+    focusOn?: {
+        path: string;
+        seq: number;
+        kind?: "node" | "link" | "none";
+        look?: boolean;
+    };
+    /** Show the inspector card (the app's panel toggle; closed by default on a narrow view, PB-861). */
+    inspector?: boolean;
+    /** Every selection change (for the host), by paths from the root. */
+    onSelect?: (sel: CadSelection) => void;
+    /**
+     * The module to show, by instance path from the root (PB-897): that module
+     * alone, in its own coordinates. Absent or empty: the whole assembly.
+     */
+    scope?: string[];
+    /** What a host adds where a module has nothing to draw (how its model is made). */
+    emptyHint?: ReactNode;
+}): import("react").JSX.Element;

package/dist/components/types/uhd-viewer/src/cad/ModelView.d.ts

@@ -0,0 +1,30 @@
+import * as THREE from "three";
+export interface ModelViewProps {
+    /** A GLB or glTF file. */
+    url?: string;
+    /**
+     * A model a host built (a converted STEP), in millimetres with Z up (the
+     * 3D view's CAD coordinates). Used instead of `url`.
+     */
+    object?: THREE.Object3D | null;
+    /** The file's name, for the card. */
+    name?: string;
+    /** A line under the name ("STEP · converted in the viewer"). */
+    detail?: string;
+    /** Why the model could not be shown (the host's conversion failed). */
+    error?: string;
+    /** Called once the model is on screen, with what the card shows. */
+    onReady?: (info: ModelInfo) => void;
+    /** Show the card with the name and size from the start (default: folded into the toolbar's Model info button). */
+    infoOpen?: boolean;
+    /** Extra buttons at the toolbar's end (a host's "open in the system viewer"). */
+    actions?: React.ReactNode;
+    className?: string;
+}
+export interface ModelInfo {
+    /** Size along x, y, z (mm). */
+    size: [number, number, number];
+    meshes: number;
+    triangles: number;
+}
+export declare function ModelView({ url, object, name, detail, error, onReady, actions, infoOpen, className }: ModelViewProps): import("react").JSX.Element;

package/dist/components/types/uhd-viewer/src/cad/explode.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Exploded view by assembly order (PB-899). Parts that go together along the
+ * model's up direction come apart along it in the order they are stacked:
+ * the part at the bottom of a column stays, and each part above it rises
+ * until it clears everything it sits on, plus a gap. Two parts interact only
+ * where one lies over the other (their outlines, seen along the axis,
+ * overlap), so four motors on four arms each lift off their own arm, not
+ * off each other.
+ *
+ * The order is geometric, never the lowest coordinate alone (a cap whose
+ * skirt reaches below the bottle's lip still comes after the bottle):
+ *
+ * - a part held inside another (the other surrounds it on every side across
+ *   the axis: a cell in a case) comes out through the side the holder leaves
+ *   open: up when less of the holder is above it than below, down the other
+ *   way (a seal seated under a cap's ceiling), up when the holder closes
+ *   round it (parts go in before the lid), and clears the holder entirely;
+ * - otherwise the lower part, by its middle, comes first, and the upper one
+ *   only has to clear the surface right under it.
+ *
+ * Pure: the scene samples each part's surfaces into height grids (raycasts in
+ * CadView) and this module orders and spaces them.
+ */
+/**
+ * A part's top and bottom surfaces over its outline, sampled on a grid in the
+ * plane across the axis: `top[i]` is the highest point of the part above
+ * cell i, `bottom[i]` the lowest (NaN where the part has nothing there).
+ */
+export interface HeightGrid {
+    /** Lower corner (u, v) of the grid and the cell size along u and v. */
+    u0: number;
+    v0: number;
+    du: number;
+    dv: number;
+    /** Cells along u and v. */
+    nu: number;
+    nv: number;
+    top: Float64Array;
+    bottom: Float64Array;
+}
+export interface StackPart {
+    key: string;
+    /** Extent along the axis (assembled). */
+    lo: number;
+    hi: number;
+    /** Middle along the axis. */
+    mid: number;
+    /** Outline across the axis: [uMin, uMax, vMin, vMax]. */
+    outline: [number, number, number, number];
+    grid: HeightGrid;
+}
+export interface StackOptions {
+    /** Space left between parts once apart (mm). */
+    gap: number;
+    /** Whether `holder` surrounds `part` across the axis (rays from the part's middle hit it on every side). */
+    surrounds?: (holder: StackPart, part: StackPart) => boolean;
+    /** Which way `part` leaves `holder` (default: `exitOf`, from the height grids). */
+    exit?: (holder: StackPart, part: StackPart) => "up" | "down" | undefined;
+}
+/** The grid cell holding (u, v), or -1 outside. */
+export declare function cellAt(g: HeightGrid, u: number, v: number): number;
+/** Centre of cell k. */
+export declare const cellCentre: (g: HeightGrid, k: number) => [number, number];
+/** A grid for a part made of axis-aligned boxes (tests, and parts without a mesh to sample). */
+export declare function boxGrid(outline: [number, number, number, number], boxes: {
+    u: [number, number];
+    v: [number, number];
+    z: [number, number];
+}[], n?: number): HeightGrid;
+/**
+ * How far `upper` must rise to clear `lower` where they lie over each other:
+ * from the lowest point of `upper` over `lower`'s outline to the highest
+ * point of `lower` under `upper`'s outline (a cap's skirt clears the bottle's
+ * lip it reaches around; a motor clears only the arm's top under it).
+ * Undefined when neither lies over the other.
+ */
+export declare function clearance(lower: StackPart, upper: StackPart): number | undefined;
+/**
+ * Which way a part held by `holder` comes out: `up` when the holder has
+ * material above the part at fewer points than below it, `down` the other
+ * way. When that ties, the side the part sticks out of the holder further (a
+ * probe through a cap's floor hangs below it); undefined when nothing
+ * decides.
+ */
+export declare function exitOf(holder: StackPart, part: StackPart, eps?: number): "up" | "down" | undefined;
+/** What a holder has along one line through a part, parallel to the axis. */
+export interface ExitLine {
+    partTop: number;
+    partBottom: number;
+    /** The holder has material above the part's top, below its bottom. */
+    above: boolean;
+    below: boolean;
+    /** The holder's highest and lowest points on the line. */
+    holderTop: number;
+    holderBottom: number;
+}
+/** The exit decided from lines through the part (see `exitOf`). */
+export declare function exitFrom(lines: readonly ExitLine[], eps?: number): "up" | "down" | undefined;
+/**
+ * Whether `p` is the lower of the two where they lie over each other,
+ * comparing the middles of their material there (a frame's tall centre stack
+ * does not put it above a motor on the arm's tip); undefined when they never
+ * lie over each other.
+ */
+export declare function lowerWhereTheyMeet(p: StackPart, q: StackPart): boolean | undefined;
+/**
+ * Each part's rise along the axis when fully exploded (mm), by key. Parts
+ * that lie over nothing stay where they are.
+ */
+export declare function planStack(parts: readonly StackPart[], options: StackOptions): Map<string, number>;

package/dist/components/types/uhd-viewer/src/cad/explodeSample.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Samples a part's surfaces for the exploded stack (./explode.ts): rays along
+ * the up axis over the part's outline give its top and bottom heights, and
+ * rays across the axis say whether one part surrounds another.
+ */
+import * as THREE from "three";
+import { type StackPart } from "./explode";
+/** A sampled part, with the meshes it was sampled from (for the surround test). */
+export interface SampledPart extends StackPart {
+    meshes: THREE.Mesh[];
+    /** Middle across the axis (u, v). */
+    centre: [number, number];
+}
+/** Two directions across the axis, completing a right-handed frame with it. */
+export declare function acrossAxis(axis: THREE.Vector3): [THREE.Vector3, THREE.Vector3];
+/** The part's top and bottom over a grid on its outline (world space, the assembled pose). */
+export declare function sampleStackPart(key: string, objects: THREE.Object3D[], skip: Set<THREE.Object3D>, axis: THREE.Vector3, n?: number): SampledPart | undefined;
+/** Whether `holder` surrounds `part` across the axis: rays from the part's middle meet it on at least three of four sides. */
+export declare function surrounded(holder: SampledPart, part: SampledPart, axis: THREE.Vector3): boolean;
+/**
+ * Which way `part` leaves `holder`, from rays along the axis through every
+ * sampled point of the part against the holder's own meshes (finer than the
+ * holder's height grid: a probe's few millimetres through a cap's floor).
+ */
+export declare function exitByRays(holder: SampledPart, part: SampledPart, axis: THREE.Vector3, eps?: number): "up" | "down" | undefined;

package/dist/components/types/uhd-viewer/src/cad/findings.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Findings on the 3D model (PB-823): where a diagnostic is, in the body that
+ * holds what it names. Fit and route findings from a host (a cad provider's
+ * check: "swd_window is 0.8 mm off the pads") and the viewer's own system
+ * checks both name canonical paths, so both can be pinned to the model:
+ *
+ *   `enclosure:swd_window`   the interface's frame origin, else the manifest
+ *                            feature of that name on the body
+ *   `board/l1`, `board/u2:pin_14`
+ *                            inside a body that draws its components (a
+ *                            board): the manifest feature named by the
+ *                            component's instance path
+ *   `board`                  the body's centre
+ *   `link:<id>`              a mate's frame on its first end
+ */
+import type { UhdBundleDiagnostic } from "@deltarobotics/uhd";
+import type { Vec3 } from "@deltarobotics/uhd";
+import type { ScopedDiagnostic } from "../model/diagnostics";
+import type { CadModel } from "./model";
+export interface CadTarget {
+    body?: string;
+    iface?: string;
+    /** A component drawn inside the body (its instance path relative to the body). */
+    component?: string;
+}
+export interface FindingAnchor {
+    id: string;
+    severity: "error" | "warning";
+    title: string;
+    message: string;
+    /** Body key the point is in, and the point in the body's own coordinates (undefined: the body's centre). */
+    body: string;
+    local?: Vec3;
+    select: CadTarget;
+    /** From the host (a provider's fit or route check) rather than the viewer's own checks. */
+    host?: boolean;
+}
+/** Where a canonical path is on the model, if any placed body holds it. */
+export declare function anchorOf(model: CadModel, ref: string): Omit<FindingAnchor, "id" | "severity" | "title" | "message"> | undefined;
+/** Errors and warnings that can be pinned to the model, the system's first, then the host's. */
+export declare function findingAnchors(model: CadModel, system: ScopedDiagnostic[], host: UhdBundleDiagnostic[]): FindingAnchor[];

package/dist/components/types/uhd-viewer/src/cad/labels.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Callout labels for the 3D view (PB-775): screen-space cards with leader
+ * lines to 3D anchors, laid out in two columns like a product manual's
+ * exploded-view callouts. HTML stays upright and camera-facing by
+ * construction; positions are recomputed every frame.
+ */
+import * as THREE from "three";
+export type LabelKind = "module" | "harness" | "interface" | "finding";
+export interface LabelItem {
+    id: string;
+    kind: LabelKind;
+    title: string;
+    sub?: string;
+    /** A second class for the card, leader and dot (a finding's severity: "error", "warning"). */
+    tone?: string;
+    /** World-space anchor (read every frame, so it follows explode and animation). */
+    anchor: () => THREE.Vector3 | null;
+    onClick?: () => void;
+}
+/** Vertical gap between cards in a column, and the clearance between the model's anchors and a column. */
+export declare const LABEL_GAP = 6;
+/** The leader's short level run into a card's inner edge. */
+export declare const LEADER_RUN = 16;
+/** Whether segments p1–p2 and q1–q2 cross (touching at an end does not count). */
+export declare function segmentsCross(p1: [number, number], p2: [number, number], q1: [number, number], q2: [number, number]): boolean;
+/** A card to place: its anchor on screen (x, y) and its size. */
+export interface LabelBox {
+    id: string;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** Where a card goes: its top-left corner, the side of the model, and which column on that side (0 nearest). */
+export interface SolvedLabel {
+    x: number;
+    y: number;
+    side: -1 | 1;
+    column: number;
+}
+/**
+ * Callout placement (PB-873): cards in columns either side of the model,
+ * each column ordered by its anchors' screen y (then untangled, where two
+ * anchors at much the same height would still cross) so leader lines do not
+ * cross, and stacked so no two cards overlap. Sides are chosen by anchor x and then
+ * balanced by height; a side taller than the view spills into a second,
+ * outer column. Pure: re-solved every frame as the camera moves.
+ */
+export declare function solveLabels(items: LabelBox[], width: number, height: number, m: {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+}): Map<string, SolvedLabel>;
+export declare class LabelLayer {
+    readonly root: HTMLDivElement;
+    private svg;
+    private cards;
+    /** Place the next frame's cards at their solved positions without easing (stills). */
+    snap: boolean;
+    private items;
+    opacity: number;
+    target: number;
+    /** Screen margins kept clear (floating chrome). */
+    margins: {
+        top: number;
+        bottom: number;
+        left: number;
+        right: number;
+    };
+    constructor(host: HTMLElement);
+    setItems(items: LabelItem[]): void;
+    /** Lay out and draw; call every frame. */
+    update(camera: THREE.Camera, width: number, height: number, dt?: number): void;
+    dispose(): void;
+}