@deltarobotics/uhd-viewer 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,218 @@
+import { Component, type ErrorInfo, type ReactNode } from "react";
+import type { ChildLink } from "@deltarobotics/uhd";
+import type { UhdBundleDiagnostic } from "@deltarobotics/uhd";
+import type { Classification } from "../model/classification";
+import type { ViewLink } from "../model/types";
+import { type ComputedLayout, type LevelLayout, type LinkLayout } from "../layout/layout";
+import type { Pt } from "../canvas/routing";
+import { type LoadedSource } from "../source/source";
+import type { ViewerEvent, ViewerOptions, ViewerSelection } from "../api";
+import type { Selection, ViewCommand } from "../canvas/Canvas";
+import { type CanvasTool, type Viewport } from "../canvas/interaction";
+import type { Goto, NodeMenuItem, Panel } from "../chrome/Chrome";
+import type { CadSelection } from "../cad/CadView";
+import type { LegendStage } from "../ui/legendFit";
+import type { CommandBus } from "../host/channel";
+import { type HostActions } from "../host/context";
+type Overrides = Record<string, ChildLink[]>;
+/** What is being dragged right now (see LiveLayout). */
+export interface Live {
+    nodes?: Set<string>;
+    links?: Set<string>;
+}
+export interface AppProps extends ViewerOptions {
+    /** Development only: absolute artifact bases are served through Vite's /@fs route. */
+    fsRoute?: boolean;
+    /** The host channel (mount.tsx): its messages, where events go, and which open actions the host takes. */
+    host?: HostLink;
+}
+export interface HostLink {
+    bus: CommandBus;
+    emit: (event: ViewerEvent) => void;
+    /** The host opens sources (the viewer offers OPEN SOURCE). */
+    source: boolean;
+    /** The host opens artifact files (instead of a new tab). */
+    artifact: boolean;
+    /** The host opens modules on their own (double-click), `onOpenModule`. */
+    module?: boolean;
+    /** The host shows the pair view (instead of the viewer's own over the diagram). */
+    pair?: boolean;
+    /** The host has an inspector of its own and shows a module there when asked (`onInspect`). */
+    inspect?: boolean;
+}
+/** Loads the UHD bundle (the viewer's only input): the source once loaded, or why not. */
+export declare function useViewerSource(props: Pick<AppProps, "bundle" | "bundleUrl" | "resolveArtifact" | "fsRoute">): {
+    source: LoadedSource | null;
+    error: string | null;
+    empty: boolean;
+};
+/**
+ * The viewer's state and behaviour for one loaded bundle: what is drawn, what
+ * is selected, the drill level, the classification, layout edits, the host
+ * channel. Shells read it through `useViewer()` inside `UhdViewer`; the
+ * canvases, inspector panels, toolbar and legend are views of it.
+ */
+export declare function useViewerController(source: LoadedSource, options: ViewerOptions, host?: HostLink): {
+    source: LoadedSource;
+    options: ViewerOptions;
+    scenario: import("../source/source").ViewerScenario;
+    scenarios: {
+        id: string;
+        label: string;
+    }[];
+    onScenario: (id: string) => void;
+    system: import("@deltarobotics/uhd").ModuleDef;
+    vm: import("../components").ViewModel;
+    drawn: import("../components").ViewModel;
+    layout: ComputedLayout;
+    hand: LevelLayout;
+    levelKey: string;
+    levelDef: import("@deltarobotics/uhd").ModuleDef;
+    drill: string[];
+    topLevel: boolean;
+    diagnostics: import("../model/diagnostics").ScopedDiagnostic[];
+    hostDiagnostics: UhdBundleDiagnostic[];
+    errors: number;
+    defFor: (id?: string) => import("@deltarobotics/uhd").ModuleDef | undefined;
+    bSlotsFor: (link: ViewLink) => string[];
+    view: "3d" | "diagram";
+    setView: import("react").Dispatch<import("react").SetStateAction<"3d" | "diagram">>;
+    mode: Classification;
+    setMode: (m: Classification) => void;
+    conductors: boolean;
+    setConductors: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    showGrounds: boolean;
+    setShowGrounds: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    isolated: ReadonlySet<string>;
+    isolation: import("../components").Isolation | null;
+    present: Set<string>;
+    onIsolate: (key: string, add?: boolean) => void;
+    clearIsolated: () => void;
+    legendStage: LegendStage;
+    setLegendStage: import("react").Dispatch<import("react").SetStateAction<LegendStage>>;
+    panel: Panel | null;
+    setPanel: import("react").Dispatch<import("react").SetStateAction<Panel | null>>;
+    selection: Selection;
+    setSelection: (s: Selection) => void;
+    group: readonly string[];
+    onSelectChanges: (changes: readonly {
+        id: string;
+        selected: boolean;
+    }[]) => void;
+    onSelectAll: () => void;
+    onEscape: () => void;
+    interaction: import("../components").InteractionState;
+    onInteraction: import("react").ActionDispatch<[action: import("../components").InteractionAction]>;
+    tool: CanvasTool;
+    setTool: (tool: CanvasTool) => void;
+    viewCommand: ViewCommand | undefined;
+    fitView: () => void;
+    zoomIn: () => void;
+    zoomOut: () => void;
+    viewport: Viewport | undefined;
+    /** Counts the times a host replaced the viewports: the canvas opens again on them. */
+    viewportsSeq: number;
+    onViewport: (v: Viewport | null) => void;
+    openLinks: Set<string>;
+    overrides: Overrides;
+    pair: ViewLink | undefined;
+    setPairLink: import("react").Dispatch<import("react").SetStateAction<string | null>>;
+    onNavigate: (depth: number) => void;
+    onDrill: (id: string) => void;
+    onGoto: (g: Goto) => void;
+    onPair: (l: ViewLink) => void;
+    onReset: () => void;
+    onToggleLink: (id: string) => void;
+    onToggleExpand: (id: string) => void;
+    onMove: (id: string, x: number, y: number) => void;
+    onOverride: (linkId: string, childLinks: ChildLink[] | null) => void;
+    editLink: (linkId: string, patch: LinkLayout) => void;
+    onPins: (linkId: string, pins: Pt[]) => void;
+    setLive: import("react").Dispatch<import("react").SetStateAction<Live | null>>;
+    centre: {
+        id: string;
+        seq: number;
+    } | undefined;
+    reveal: {
+        selection: NonNullable<Selection>;
+        seq: number;
+    } | undefined;
+    cadFocus: {
+        path: string;
+        seq: number;
+        kind?: "node" | "link" | "none";
+        look?: boolean;
+    } | undefined;
+    onCadSelect: (s: CadSelection) => void;
+    cadSelection: ViewerSelection | null;
+    focusPath: (path: string) => void;
+    hostActions: HostActions;
+    onOpenNode: (id: string) => void;
+    onNodeContext: (id: string, x: number, y: number) => void;
+    onPaneContext: (x: number, y: number) => void;
+    menu: {
+        id?: string;
+        x: number;
+        y: number;
+    } | null;
+    menuItems: NodeMenuItem[];
+    closeMenu: () => void;
+};
+/**
+ * What a double-click on a node does: `open` it on its own (the host's new
+ * tab), `expand` it in place, or `none`. Only a module that holds modules
+ * has a level to open or to expand; a part with nothing inside, a net's
+ * junction, a rail's tap and a boundary port have none.
+ */
+export declare function openAction(node: {
+    defId?: string;
+    childCount?: number;
+    net?: unknown;
+    tapOf?: string;
+    sheetPort?: unknown;
+} | undefined, hostOpens: boolean): "open" | "expand" | "none";
+/** Everything a view of the loaded model reads (see useViewerController). */
+export type ViewerController = ReturnType<typeof useViewerController>;
+/** The viewer's state, inside `UhdViewer` (or `ViewerProvider`). */
+export declare function useViewer(): ViewerController;
+/** The viewer's state for a loaded source, for the components inside. */
+export declare function ViewerProvider({ source, options, host, children }: {
+    source: LoadedSource;
+    options: ViewerOptions;
+    host?: HostLink;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+export interface UhdViewerProps extends AppProps {
+    /** The views of the model: canvases, panels, the shell's own chrome. */
+    children?: ReactNode;
+}
+/**
+ * Loads the bundle, then provides the viewer's state to `children`. While
+ * loading, or when the bundle cannot be read, it says so in place.
+ */
+export declare function UhdViewer({ children, ...props }: UhdViewerProps): import("react").JSX.Element;
+/**
+ * A bundle the viewer cannot draw says so in place, instead of leaving an
+ * empty page: what failed, and that the next bundle is tried again (a
+ * producer that rebuilds on a source edit sends one).
+ */
+export declare class ViewerBoundary extends Component<{
+    source: LoadedSource;
+    children?: ReactNode;
+}, {
+    failed?: {
+        source: LoadedSource;
+        message: string;
+    };
+}> {
+    state: {
+        failed?: {
+            source: LoadedSource;
+            message: string;
+        };
+    };
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    static getDerivedStateFromError(): null;
+    render(): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | Iterable<ReactNode> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined> | null | undefined;
+}
+export {};

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

@@ -0,0 +1,81 @@
+/**
+ * The inspector's details for one thing of a bundle, without a viewer around
+ * it: what `ViewerInspector` shows for a selected module, link or net, for a
+ * host that has an inspector of its own (a native side view) and selects by
+ * path. The same components draw both, so a host's inspector and the
+ * viewer's show a module the same way.
+ *
+ *   <ThemeProvider adapter={vscodeThemeAdapter()}>
+ *     <SelectionDetails bundle={bundle} target={{ kind: "module", path: "stack/esc" }} host={{ openArtifact }} />
+ *   </ThemeProvider>
+ *
+ * The level that holds the target is modelled as the viewer models it (its
+ * links, nets and checks), but nothing is laid out or drawn.
+ */
+import { type ReactNode } from "react";
+import type { ModuleDef } from "@deltarobotics/uhd";
+import type { UhdBundle } from "@deltarobotics/uhd";
+import type { ArtifactResolver } from "../api";
+import { type HostActions } from "../host/context";
+import type { Classification } from "../model/classification";
+import { type HostFinding } from "../model/slots";
+/** An interface card's request to its host: the module's path, the interface, and the links that end on it as their module declares them. */
+export interface InterfaceRequest {
+    /** The module's instance path from the root. */
+    path: string;
+    interfaceId: string;
+    /** The module that declares the links (the level's), from the root. */
+    owner: string;
+    /** Its stored links by their local ids ("rx_fc_pads"). */
+    links: string[];
+}
+/** What to show: a module instance by its path from the root (`""`: the root), a link on the level of its owner, or a definition on its own. */
+export type DetailsTarget = {
+    kind: "module";
+    path: string;
+} | {
+    kind: "link";
+    owner: string;
+    ids: string[];
+} | {
+    kind: "definition";
+    id: string;
+};
+export interface SelectionDetailsProps {
+    /** The bundle the target is in. Not given: only `definition` targets among `definitions` can be shown. */
+    bundle?: UhdBundle;
+    /** Definitions outside the bundle (a library part shown on its own), by their ids. */
+    definitions?: ModuleDef[];
+    target: DetailsTarget;
+    /** URL of a definition's artifact file; not given, files do not resolve (their cards show icons). */
+    resolveArtifact?: ArtifactResolver;
+    /** What the host takes over, and how artifacts are shown (host/context.ts). */
+    host?: HostActions;
+    /** How interface swatches are coloured (default: by domain). */
+    mode?: Classification;
+    /** A board's drawings with pan and zoom, as in the viewer (default false: the drawings are cards, nothing is fetched). */
+    boardDrawings?: boolean;
+    /** The user picked something else in the details (an end of a link, a net's member, a functional link): canonical ids from the root. */
+    onSelect?: (selection: {
+        kind: "node" | "link";
+        id: string;
+    }) => void;
+    /** The user asked for the pair view of the link shown. */
+    onPair?: (request: {
+        linkId: string;
+        a: string;
+        b: string;
+    }) => void;
+    /** Shown when the target is not in the bundle. */
+    missing?: ReactNode;
+    /** The host's findings for the interface cards (with the keys its Locate takes); not given, the viewer's own checks. */
+    findings?: HostFinding[];
+    /** A finding's Locate on an interface card. */
+    onFinding?: (key: string) => void;
+    /** An interface card's Open in source: the line of its link, else of the interface. */
+    onInterfaceSource?: (request: InterfaceRequest) => void;
+    /** An open slot's Connect…. */
+    onConnect?: (request: InterfaceRequest) => void;
+    className?: string;
+}
+export declare function SelectionDetails({ bundle, definitions, target, resolveArtifact, host, mode, boardDrawings, onSelect, onPair, missing, className, findings, onFinding, onInterfaceSource, onConnect }: SelectionDetailsProps): import("react").JSX.Element;

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

@@ -0,0 +1,60 @@
+import { type HierarchyNode, type HierarchyPanelState } from "../model/hierarchy";
+/** What a host asks of the panel: show a module's row, put the keyboard in the filter, open or fold it. */
+export interface HierarchyCommand {
+    type: "reveal" | "filter" | "open" | "close" | "toggle";
+    /** For `reveal`: the module's instance path. */
+    path?: string;
+    /** A new number for every command (the same command twice is two). */
+    seq: number;
+}
+export interface ViewerHierarchyProps {
+    /** What the host kept for this tab (`onStateChange` gave it); anything malformed is ignored. */
+    state?: unknown;
+    /** The panel's state changed (open, width, open rows): a host keeps it per tab. */
+    onStateChange?: (state: HierarchyPanelState) => void;
+    /** The panel opened or folded (at once; a host's toggle button shows it). */
+    onOpenChange?: (open: boolean) => void;
+    command?: HierarchyCommand;
+    /** Attributes a host puts on every row (`data-*`), e.g. for its own context menu. */
+    rowAttributes?: (node: HierarchyNode) => Record<`data-${string}`, string>;
+    /** Show the panel's own context menu (default). A host with a menu of its own passes false: a right-click then only selects the row. */
+    ownMenu?: boolean;
+    /** Below this width of the window the panel starts folded when nothing was kept (default 640). */
+    narrow?: number;
+    className?: string;
+}
+/** The folded panel's width. */
+export declare const RAIL_WIDTH = 36;
+/**
+ * The panel's look, in one place (PB-1042; the Pencil iterations, 2026-10-21):
+ * docked flush at the left of the canvas, below the floating header, with a
+ * border at its edge; rows highlighted in the theme's selection colour. Only
+ * the viewer's tokens, so a host's theme decides the colours (orange only
+ * under the Protoboard theme). Swap these to restyle it.
+ */
+export declare const HIERARCHY_LOOK: {
+    readonly dock: "uhd-hierarchy-dock absolute inset-y-0 left-0 z-30 flex flex-col pt-[var(--uhd-inset-top,0px)]";
+    readonly panel: "relative flex min-h-0 flex-1 flex-col overflow-hidden border-t border-r border-line bg-surface font-ui text-fg";
+    readonly rail: "flex min-h-0 flex-1 flex-col items-center gap-1 border-t border-r border-line bg-surface py-1";
+    readonly header: "flex h-8 shrink-0 items-center gap-0.5 pr-1 pl-3";
+    readonly title: "min-w-0 flex-1 truncate font-label text-[11px] tracking-[0.08em] text-fg-muted uppercase";
+    readonly filterBox: "mx-2 mb-1.5 flex h-7 shrink-0 items-center gap-1.5 rounded-md border border-line bg-sunken px-2 focus-within:outline focus-within:outline-1 focus-within:-outline-offset-1 focus-within:outline-focus";
+    readonly row: "uhd-tree-row group relative flex h-[26px] cursor-pointer items-center gap-1.5 pr-3 text-[12.5px] leading-none outline-none select-none";
+    readonly rowSelected: "bg-selection text-selection-fg outline outline-1 -outline-offset-1 outline-focus";
+    readonly rowIdle: "text-fg hover:bg-hover";
+    /** Filtering: a row that only leads to what matches. */
+    readonly rowDim: "text-fg-faint hover:bg-hover hover:text-fg";
+    readonly rowFocus: "focus-visible:outline focus-visible:outline-1 focus-visible:-outline-offset-1 focus-visible:outline-focus";
+    readonly groupRow: "mt-1 border-t border-line-subtle text-fg-muted";
+    readonly badge: "shrink-0 rounded border border-line px-1.5 font-code text-[10px] leading-[16px] text-fg-muted";
+    readonly legend: "flex shrink-0 flex-wrap items-center gap-x-3 gap-y-1 border-t border-line-subtle px-3 py-1.5 text-[10.5px] text-fg-muted";
+};
+/** The panel, docked at the left of the view: render it beside the shell's `.workspace` (its sibling, before it), which then starts after it. */
+export declare function ViewerHierarchy({ state: given, onStateChange, onOpenChange, command, rowAttributes, ownMenu, narrow, className }: ViewerHierarchyProps): import("react").JSX.Element;
+/** The toolbar's Hierarchy button (left of a shell's view tabs): it opens and folds the panel. */
+export declare function HierarchyToggle({ open, onClick, disabled, className }: {
+    open: boolean;
+    onClick: () => void;
+    disabled?: boolean;
+    className?: string;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,12 @@
+/**
+ * Renders a viewer shell into an element: the standalone app (app/main.tsx,
+ * lib.tsx's mountViewer) or a host's own shell built from the library's views
+ * (`renderViewer(el, options, Shell)`). The handle carries the host channel:
+ * its methods send host messages, events go to the options' callbacks and,
+ * with `parentWindow`, to the parent window. The shell receives the options
+ * and the channel (`host`) as props and passes them to `UhdViewer`.
+ */
+import { type ComponentType } from "react";
+import type { AppProps } from "./controller";
+import type { ViewerHandle } from "../api";
+export declare function renderViewer<P extends AppProps>(element: HTMLElement, props: P, Shell: ComponentType<P>): ViewerHandle;

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

@@ -0,0 +1,156 @@
+/**
+ * The library's views of a loaded model, each reading the viewer's state
+ * (`useViewer`): the diagram canvas with its toolbar and legend, the 3D
+ * scene, the inspector panels and a module's context menu. Shells place them;
+ * none of them is app chrome.
+ */
+import { type ReactNode } from "react";
+export interface DiagramCanvasProps {
+    /** Draw the floating toolbar (fit, zoom, reset layout). Default true. */
+    toolbar?: boolean;
+    /** Draw the classification's legend. Default true. */
+    legend?: boolean;
+    /** A panel floats over the canvas's right side: fitting leaves room for it. Default: the inspector panel is open. */
+    coveredRight?: boolean;
+    /** What the shell adds to the notice about definitions the bundle does not hold (how its producer gets them). */
+    missingHint?: ReactNode;
+    className?: string;
+}
+/** The diagram of the current level: modules, interfaces, links and harnesses. */
+export declare function DiagramCanvas({ toolbar, legend, coveredRight, missingHint, className }: DiagramCanvasProps): import("react").JSX.Element;
+/** The scenario being shown, when it is not the nominal build. */
+export declare function ScenarioBanner(): import("react").JSX.Element | null;
+/**
+ * Definitions the bundle names and does not hold (source/tolerant.ts): they are
+ * drawn as placeholders, and this says which. It can be put away; a bundle
+ * that lacks something else brings it back.
+ */
+export declare function MissingNotice({ hint, className }: {
+    hint?: ReactNode;
+    className?: string;
+}): import("react").JSX.Element | null;
+/** The diagram's view controls as icon toggles (each with a tooltip). */
+export declare const CLASSIFICATION_OPTIONS: readonly [{
+    readonly id: "domain";
+    readonly icon: "layers";
+    readonly label: "Colour by domain";
+}, {
+    readonly id: "drc";
+    readonly icon: "shield-check";
+    readonly label: "Colour by DRC health";
+}, {
+    readonly id: "signal";
+    readonly icon: "activity";
+    readonly label: "Colour by signal type";
+}];
+export declare const DETAIL_OPTIONS: readonly [{
+    readonly id: "bundled";
+    readonly icon: "minus";
+    readonly label: "Basic: one line per link";
+}, {
+    readonly id: "conductors";
+    readonly icon: "rows-3";
+    readonly label: "Ribbon: every conductor";
+}];
+/**
+ * The pointer's tool: select (a drag on the empty canvas draws a selection
+ * box) or pan (a drag moves the view). For a shell's own toolbar.
+ */
+export declare function ToolToggle({ tooltipSide, size }: {
+    tooltipSide?: "top" | "bottom" | "left" | "right";
+    size?: "sm" | "md";
+}): import("react").JSX.Element;
+/** Fit and zoom, as the canvas does them (a fit asked for here is also what the level opens on next time). */
+export declare function ViewButtons({ tooltipSide }: {
+    tooltipSide?: "top" | "bottom" | "left" | "right";
+}): import("react").JSX.Element;
+/**
+ * The diagram's controls (classification, detail, grounds; `controls={false}` leaves them out), then fit, zoom and reset.
+ * When the legend has no room beside it, it starts with the legend's button (`legend`: what that opens; default the
+ * viewer's legend).
+ */
+export declare function DiagramToolbar({ coveredRight, className, controls, legend }: {
+    coveredRight?: boolean;
+    className?: string;
+    controls?: boolean;
+    legend?: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * The entries of the current classification's legend, as buttons: a click
+ * isolates one (its links stay, with the interfaces and modules they touch;
+ * the rest of the level fades), a click on it again shows everything, a
+ * click on another switches, and Shift, Ctrl or Cmd holds several. For a
+ * shell that draws its own legend card.
+ */
+export declare function DiagramLegendItems({ compact, columns }?: {
+    compact?: boolean;
+    columns?: number;
+}): import("react").JSX.Element;
+/** The way back from an isolated legend entry to everything (shown only while something is isolated). */
+export declare function IsolationClear({ className }: {
+    className?: string;
+}): import("react").JSX.Element | null;
+/**
+ * What the legend shows in a form: `full` the title and the entries with their
+ * labels; `compact` the classification's icon and the swatches alone (each
+ * named by its label).
+ */
+export declare function DiagramLegendBody({ form }: {
+    form: "full" | "compact";
+}): import("react").JSX.Element;
+/** What the link colours mean in the current classification; a click on an entry isolates it. It gives way to the toolbar as the canvas narrows (`FittedLegend`). */
+export declare function DiagramLegend({ className }: {
+    className?: string;
+}): import("react").JSX.Element;
+/**
+ * A legend card at the canvas's bottom left that stays there and gives way
+ * to the bottom toolbar (ui/legendFit.ts): the full form while it fits beside
+ * the toolbar, then the compact one, and at its smallest none, the toolbar
+ * then offering it behind a button (`LegendToolbarButton`). It measures the
+ * room it has (a `ResizeObserver` on the canvas, the toolbar and both forms)
+ * from hidden copies of the two forms, so it never overlaps the toolbar.
+ * `render` draws a form; the card is a sibling of the toolbar (`.toolbar`).
+ */
+export declare function FittedLegend({ label, render, className }: {
+    label: string;
+    render: (form: "full" | "compact") => ReactNode;
+    className?: string;
+}): import("react").JSX.Element;
+/**
+ * The legend's button in the toolbar, shown only when the legend has no room
+ * beside it (`FittedLegend`): it opens the legend (`children`) as a popover
+ * above the toolbar. Escape, a click elsewhere or the button closes it, and
+ * the keyboard goes back to the button.
+ */
+export declare function LegendToolbarButton({ children, label }: {
+    children: ReactNode;
+    label?: string;
+}): import("react").JSX.Element | null;
+export interface Scene3DProps {
+    /** Show the 3D view's own inspector card. Default: the inspector panel is open. */
+    inspector?: boolean;
+    /**
+     * The module to show, by instance path from the root. Default: the level
+     * the viewer is on (`drill`), so the root shows the whole assembly and a
+     * module shows that module alone. A shell whose tab is on a module with no
+     * level of its own (a part) passes that module's path.
+     */
+    scope?: string[];
+    /** What the shell adds where a module has nothing to draw (how its 3D model is made). */
+    emptyHint?: ReactNode;
+}
+/**
+ * The 3D model of what is being viewed: the whole assembly at the root, one
+ * module alone (in its own coordinates) on that module's level. With its own
+ * toolbar and (optionally) its inspector.
+ */
+export declare function Scene3D({ inspector, scope, emptyHint }: Scene3DProps): import("react").JSX.Element;
+/**
+ * The inspector of the current level: the selected module or link, else the
+ * hierarchy or the system checks (`panel`). Hidden while no panel is open.
+ */
+export declare function ViewerInspector({ className }: {
+    className?: string;
+}): import("react").JSX.Element | null;
+/** A module's context menu, where the pointer opened it. */
+export declare function ViewerNodeMenu(): import("react").JSX.Element | null;

package/dist/headless/index.d.ts

@@ -0,0 +1,71 @@
+import type { UhdBundle } from "@deltarobotics/uhd";
+import type { LinkLayout } from "../lib/api.js";
+
+export interface Box { x: number; y: number; w: number; h: number }
+/** One level of `diagram.layouts` in the display file. */
+export interface LevelLayout {
+  nodes: Record<string, { x?: number; y?: number; w?: number; h?: number }>;
+  ports?: Record<string, "left" | "right" | "top" | "bottom">;
+  links?: Record<string, LinkLayout>;
+}
+/** A level layout with the nodes the layout step must not move (the viewer ignores the list). */
+export type PinnedLevelLayout = LevelLayout & { pinned?: string[] };
+export interface LayoutMetrics {
+  cards: number;
+  boundary: number;
+  links: number;
+  crossings: number;
+  overlaps: number;
+  aspect: number;
+  width: number;
+  height: number;
+  strip: number;
+  stripAxis: "row" | "column";
+  stripCards: string[];
+  underCards: number;
+  length: number;
+  detail: { overlaps: [string, string][]; underCards: { link: string; card: string }[] };
+}
+export interface LayoutFinding {
+  severity: "warning" | "info";
+  code: "strip" | "crossings" | "overlaps" | "under-cards" | "aspect";
+  message: string;
+}
+export interface LayoutLimits {
+  strip: (cards: number) => number;
+  crossings: (links: number) => number;
+  aspect: [number, number];
+}
+export declare const LAYOUT_LIMITS: LayoutLimits;
+export declare function layoutFindings(m: LayoutMetrics, limits?: LayoutLimits): LayoutFinding[];
+export interface DiagramLevel { level: string; label: string; board: boolean }
+export declare function diagramLevels(bundle: UhdBundle, maxDepth?: number): DiagramLevel[];
+export interface LevelOptions {
+  layout?: LevelLayout | null;
+  expanded?: string[];
+  legacy?: boolean;
+}
+export interface MeasuredLevel {
+  level: string;
+  saved: boolean;
+  metrics: LayoutMetrics;
+  findings: LayoutFinding[];
+  /** What the viewer draws (internal shapes: read `layout.boxes` and `layout.routes` only). */
+  view: { nodes: { id: string; label: string; parent?: string; kind: string }[] };
+  layout: { boxes: Record<string, Box>; routes: Record<string, [number, number][]> };
+}
+export declare function measureLevel(bundle: UhdBundle, level: string, opts?: LevelOptions): MeasuredLevel;
+export interface ProposeOptions extends LevelOptions {
+  mode?: "default" | "tidy";
+  pinned?: string[];
+}
+export interface Proposal {
+  level: string;
+  before: MeasuredLevel;
+  after: MeasuredLevel;
+  layout: PinnedLevelLayout;
+  better: boolean;
+}
+export declare function proposeLevel(bundle: UhdBundle, level: string, opts?: ProposeOptions): Proposal;
+export declare function reads(m: LayoutMetrics): number;
+export declare function readsBetter(a: LayoutMetrics, b: LayoutMetrics): boolean;