@deltarobotics/uhd-viewer 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,37 @@
+import type { ViewLink, ViewModel } from "../model/types";
+import { type Classification } from "../model/classification";
+/**
+ * Pair view (design board 08): every stored link between two modules, left
+ * to right, with each link's child links as conductors. Crossovers (TX→RX)
+ * draw as crossing lines. Unlinked interfaces are listed below.
+ */
+interface Endpoints {
+    a: {
+        node: string;
+        port: string;
+    };
+    b: {
+        node: string;
+        port: string;
+    };
+}
+/** True endpoints of a link, joining harness segments back together. */
+export declare function pairEnds(vm: ViewModel, link: ViewLink): Endpoints;
+export declare function PairView({ vm, link, mode, onClose }: {
+    vm: ViewModel;
+    link: ViewLink;
+    mode: Classification;
+    onClose: () => void;
+}): import("react").JSX.Element | null;
+/**
+ * The pair a link joins, small, for the inspector: the two modules and the
+ * link's conductors from one to the other (a crossover crosses). `onOpen`
+ * opens the full pair view.
+ */
+export declare function PairPreview({ vm, link, mode, onOpen }: {
+    vm: ViewModel;
+    link: ViewLink;
+    mode: Classification;
+    onOpen: () => void;
+}): import("react").JSX.Element | null;
+export {};

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

@@ -0,0 +1,107 @@
+/**
+ * The inspector's sections (PB-1042, design A "Linear-tight", 2026-10-21):
+ * one column, no boxes. Each section is a 28 px header row (chevron, title,
+ * count, and a summary on the right) over its body, separated from the next
+ * by a 1 px divider. Secondary sections start collapsed and say what they
+ * hold in the header. The look is in one place (`SECTION_LOOK`), from the
+ * viewer's tokens only, so a host's theme decides the colours.
+ *
+ * Keyboard: a section header and an interface card are stops of one list
+ * (`data-nav`); Arrow Up and Down move between them, Home and End go to the
+ * first and the last, Enter and Space open and close (they are buttons).
+ */
+import { type KeyboardEvent, type ReactNode } from "react";
+/** The sections' look, in one place: swap these to restyle them. */
+export declare const SECTION_LOOK: {
+    readonly root: "uhd-sections font-ui text-fg";
+    readonly section: "uhd-section border-b border-line-subtle";
+    readonly header: "flex h-7 min-w-0 items-center gap-1.5 pr-3 pl-2.5";
+    readonly toggle: "group/sec -my-px flex h-7 min-w-0 flex-1 cursor-pointer items-center gap-1.5 rounded-[3px] text-left outline-none focus-visible:outline focus-visible:outline-1 focus-visible:-outline-offset-1 focus-visible:outline-focus";
+    readonly chevron: "shrink-0 text-fg-muted transition-transform duration-100";
+    readonly title: "shrink-0 text-[11px] leading-none font-bold text-fg";
+    readonly count: "shrink-0 text-[11px] leading-none text-fg-faint tabular-nums";
+    readonly summary: "ml-auto min-w-0 shrink truncate text-right text-[11px] leading-none text-fg-muted";
+    readonly body: "px-3 pt-0.5 pb-2.5";
+    /** A key and its value, as the Parameters rows. */
+    readonly kv: "flex min-h-[22px] items-baseline gap-2 py-[3px] text-[11px] leading-[1.35]";
+    readonly key: "w-[92px] shrink-0 truncate text-fg-faint";
+    readonly value: "min-w-0 flex-1 text-fg [overflow-wrap:anywhere]";
+    /** A small heading inside a section (an expanded card's groups). */
+    readonly label: "text-[10px] leading-none text-fg-faint";
+    /** A quiet text action at the right of a header ("Show all 21"). */
+    readonly aside: "ml-auto shrink-0 cursor-pointer text-[11px] leading-none text-fg-muted hover:text-fg focus-visible:outline focus-visible:outline-1 focus-visible:outline-focus";
+};
+type Listener = () => void;
+/**
+ * Which sections are open and which interface cards are expanded, kept for
+ * as long as the page lives (a tab's webview, the viewer's page): sections by
+ * their id, cards per selection, so going back to a module shows it as it was.
+ */
+declare class KeptState {
+    private sections;
+    private cards;
+    private listeners;
+    private version;
+    subscribe: (l: Listener) => () => undefined;
+    snapshot: () => number;
+    private changed;
+    section(id: string, fallback: boolean): boolean;
+    setSection(id: string, open: boolean): void;
+    expanded(selection: string): ReadonlySet<string>;
+    setExpanded(selection: string, ids: ReadonlySet<string>): void;
+    /** For tests and a host that resets its page. */
+    clear(): void;
+}
+/** The page's kept state (one per page). */
+export declare const keptInspectorState: KeptState;
+/** The selection the cards below belong to: their expanded set is kept under it. */
+export declare const SelectionKey: import("react").Context<string>;
+/** Whether a section is open (kept while the page lives), and its setter. */
+export declare function useSectionOpen(id: string, defaultOpen: boolean): [boolean, (open: boolean) => void];
+/** The interface cards expanded for the current selection, and a toggle. Several may be open at once. */
+export declare function useExpandedCards(): [ReadonlySet<string>, (id: string) => void];
+/** Where a key moves focus in a list of `count` stops from `index`; undefined: the key is not a move. */
+export declare function navTarget(key: string, index: number, count: number): number | undefined;
+/** Arrow keys on a stop (`data-nav`) move to the next one within the sections (`data-nav-root`). */
+export declare function onNavKey(e: KeyboardEvent<HTMLElement>): void;
+/**
+ * The column the sections are in: its stops are one keyboard list. Inside
+ * another (a host's inspector around the viewer's details) it is part of the
+ * outer one, so the arrows go through both.
+ */
+export declare function Sections({ children, className, label }: {
+    children?: ReactNode;
+    className?: string;
+    label?: string;
+}): import("react").JSX.Element;
+export interface DetailsSectionProps {
+    /** Kept open or closed by this id while the page lives. */
+    id: string;
+    title: string;
+    count?: number;
+    /** What it holds, said in the header (shown open or closed): "6 linked · 1 open", "DolphinRC · $69.99". */
+    summary?: ReactNode;
+    /** A text action at the header's right instead of the summary ("Show all 21"). */
+    aside?: ReactNode;
+    /** Open at first (secondary sections start closed). */
+    defaultOpen?: boolean;
+    children?: ReactNode;
+    className?: string;
+}
+/** A section: its header row (a disclosure button) and its body. */
+export declare function DetailsSection({ id, title, count, summary, aside, defaultOpen, children, className }: DetailsSectionProps): import("react").JSX.Element;
+/** Rows of keys and values; past `limit` the rest wait behind "Show all N" (the header's aside, `ShowAll`). */
+export declare function KeyValues({ rows, limit }: {
+    rows: {
+        key: string;
+        value: ReactNode;
+        title?: string;
+    }[];
+    limit?: number;
+}): import("react").JSX.Element;
+/** A section's rows shown in part, and the header action that shows them all. */
+export declare function useShowAll(total: number, limit: number): {
+    limit: number | undefined;
+    aside: ReactNode;
+};
+export {};

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

@@ -0,0 +1,60 @@
+/**
+ * The component library (`@deltarobotics/uhd-viewer/components`): the
+ * viewer's views of a UHD bundle as React components, for hosts that build
+ * their own shell. No app chrome: the shell places the views, its own header,
+ * tabs and panels.
+ *
+ *   <ThemeProvider adapter={vscodeThemeAdapter()}>
+ *     <UhdViewer bundleUrl="/uhd-bundle.json" host={host}>
+ *       <DiagramCanvas />
+ *       <ViewerInspector />
+ *     </UhdViewer>
+ *   </ThemeProvider>
+ *
+ * React, React DOM, Three, React Flow and Radix are peer dependencies here
+ * (one copy each in the host's bundle). The stylesheet is
+ * `@deltarobotics/uhd-viewer/components.css`; a host's own Tailwind build
+ * gets the token utilities from `@deltarobotics/uhd-viewer/tailwind-theme.css`.
+ * Nothing here names a host product.
+ */
+export type * from "./api";
+export { renderViewer } from "./viewer/mount";
+export { parseHostMessage, isViewerEvent, originAllowed, PREFIX as HOST_MESSAGE_PREFIX } from "./host/protocol";
+export { UhdViewer, ViewerBoundary, ViewerProvider, useViewer, useViewerSource, useViewerController, type AppProps as UhdViewerOptions, type UhdViewerProps, type HostLink, type ViewerController } from "./viewer/controller";
+export type { LoadedSource } from "./source/source";
+export { tolerantSystem, isPlaceholder, type MissingDefinition, type LeftOut, type TolerantSystem } from "./source/tolerant";
+export type { Classification } from "./model/classification";
+export { CLASSIFICATIONS, colorFor, legendFor, classKey, type LegendEntry } from "./model/classification";
+export { isolate, presentKeys, linkKeys, toggleIsolated, type Isolation } from "./model/isolate";
+export type { ViewModel, ViewNode, ViewLink } from "./model/types";
+export type { Selection } from "./canvas/Canvas";
+export type { Panel, Goto } from "./chrome/Chrome";
+export { initialInteraction, interactionReducer, interactionProps, canvasCommand, applySelectChanges, firstView, TOOL_OPTIONS, type CanvasTool, type InteractionState, type InteractionAction, type CanvasCommand, type Viewport } from "./canvas/interaction";
+export { openAction } from "./viewer/controller";
+export { cardWidth, labelIsCut, CARD_W, CARD_W_MAX } from "./layout/card-body";
+export { DiagramCanvas, DiagramToolbar, ToolToggle, ViewButtons, DiagramLegend, DiagramLegendBody, DiagramLegendItems, FittedLegend, LegendToolbarButton, IsolationClear, MissingNotice, ScenarioBanner, Scene3D, ViewerInspector, ViewerNodeMenu, CLASSIFICATION_OPTIONS, DETAIL_OPTIONS, type DiagramCanvasProps, type Scene3DProps } from "./viewer/views";
+export { ModelView, type ModelViewProps, type ModelInfo } from "./cad/ModelView";
+export { ViewerHierarchy, HierarchyToggle, RAIL_WIDTH, HIERARCHY_LOOK, type ViewerHierarchyProps, type HierarchyCommand } from "./viewer/hierarchy";
+export { buildHierarchy, filterHierarchy, visibleRows, treeKey, selectedPath, rowTarget, drillInto, revealPaths, ancestorsOf, hierarchyIndex, walkHierarchy, panelState, groupWiring, markLegend, WIRING_PATH, kindOf, KIND_ICON, KIND_LABEL as HIERARCHY_KIND_LABEL, HIERARCHY_WIDTH, type HierarchyNode, type HierarchyKind, type HierarchyRow, type HierarchyPanelState, type HierarchyOptions, type TreeKeyResult, } from "./model/hierarchy";
+export { SelectionDetails, type SelectionDetailsProps, type DetailsTarget, type InterfaceRequest } from "./viewer/details";
+export { Sections, DetailsSection, KeyValues, useShowAll, useSectionOpen, useExpandedCards, SelectionKey, keptInspectorState, navTarget, onNavKey, SECTION_LOOK, type DetailsSectionProps } from "./chrome/Sections";
+export { InterfaceCards, InterfaceCard, SlotGlyph, CARD_LOOK, SLOT_COLOR, type InterfaceCardActions } from "./chrome/InterfaceCards";
+export { interfaceSlots, slotSummary, groupSlots, checkFindings, levelNames, humanize, sentence, paramValue, type InterfaceSlot, type SlotKind, type SlotState, type SlotPin, type SlotLink, type SlotFinding, type SlotNote, type HostFinding, type SlotOptions } from "./model/slots";
+export { ArtifactCard, ArtifactCards, ArtifactGrid, type ArtifactCardProps } from "./chrome/ArtifactCards";
+export { EvidenceSection } from "./chrome/Evidence";
+export { artifactCard, artifactCards, mergeFormats, isInternalArtifact, classifyArtifact, evidenceSourceCards, groupArtifactCards, ARTIFACT_GROUPS, type ArtifactCardModel, type ArtifactCardOptions, type ArtifactGroup, type ArtifactKind, type ArtifactPreview, type ArtifactSourceRow } from "./model/artifacts";
+export type { EvidenceFiles, SourceRow, Verification } from "./model/evidence";
+export { HostContext, type HostActions } from "./host/context";
+export { ScrollArea, type ScrollAreaProps } from "./ui/ScrollArea";
+export { Toolbar, ToolbarSeparator, IconButton, ToggleGroup, type ToolbarProps, type IconButtonProps, type ToggleGroupProps } from "./ui/Toolbar";
+export { Legend, LegendItem, LegendSwatches, type LegendItemProps, type LegendProps } from "./ui/Legend";
+export { legendStage, legendRoom, type LegendStage } from "./ui/legendFit";
+export { InspectorPanel, Section, PropertyRow, Badge, StatusDot, EmptyState, type InspectorPanelProps, type Tone } from "./ui/Inspector";
+export { Tooltips } from "./ui/Tooltips";
+export { Icon } from "./canvas/Icon";
+export { cx } from "./ui/cx";
+export { TOKEN_NAMES, tokenVar, token, mix, defineTheme, applyTheme, readToken, themeCss, themeDeclarations, DERIVED, type Theme, type ThemeTokens, type ThemeToken, type ThemeScheme, } from "./theme/tokens";
+export { defaultDark, defaultLight, defaultTheme, DRC_TOKENS, DARK_DATA_TOKENS, LIGHT_DATA_TOKENS } from "./theme/themes";
+export { staticTheme, defaultThemeAdapter, vscodeThemeAdapter, vscodeTheme, vscodeScheme, pickTheme, type ThemeAdapter } from "./theme/adapters";
+export { ThemeProvider, useTheme, tokenColor, type ThemeProviderProps, type ThemeState } from "./theme/ThemeProvider";
+export { resolveTheme, completeTheme } from "./theme/resolve";

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

@@ -0,0 +1,49 @@
+/**
+ * The viewer's side of the host channel: commands from the handle or the
+ * parent window reach the mounted viewer (queued until it has a model on
+ * screen), and its events go to the host's callbacks and, in a frame, to the
+ * parent window.
+ */
+import type { ViewerEvent, ViewerHostMessage, ViewerOptions } from "../api";
+/** Host messages on their way to the viewer component (App.tsx subscribes once it shows a model). */
+export interface CommandBus {
+    send(message: ViewerHostMessage): void;
+    /** Receive messages, first the ones that waited; returns the unsubscribe. */
+    subscribe(handler: (message: ViewerHostMessage) => void): () => void;
+}
+export declare function commandBus(): CommandBus;
+/** Calls the option callback that matches an event. */
+export declare function deliver(options: ViewerOptions, event: ViewerEvent): void;
+/** The part of `window` the parent channel uses (a test passes its own). */
+export interface ChannelWindow {
+    /** The frame's parent (the window itself when not in a frame). */
+    parent: {
+        postMessage(message: unknown, targetOrigin: string): void;
+    };
+    location: {
+        origin: string;
+        ancestorOrigins?: ArrayLike<string>;
+    };
+    document?: {
+        referrer?: string;
+    };
+    addEventListener(type: "message", listener: (e: MessageEvent) => void): void;
+    removeEventListener(type: "message", listener: (e: MessageEvent) => void): void;
+}
+export interface ParentChannel {
+    /** Post an event to the parent (held until the parent's origin is known). */
+    post(event: ViewerEvent): void;
+    close(): void;
+}
+/**
+ * The postMessage channel with the parent window. Accepts host messages from
+ * `win.parent` only, from an allowed origin (default: `win`'s own). Events
+ * go to the parent's origin: the frame's ancestor origin or referrer when it
+ * is allowed, the only allowed origin when exactly one is listed, else the
+ * origin of the parent's first accepted message (events wait until then).
+ * Returns undefined when `win` is not in a frame.
+ */
+export declare function connectParent(win: ChannelWindow, options: {
+    origins?: string[];
+    onMessage: (message: ViewerHostMessage) => void;
+}): ParentChannel | undefined;

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

@@ -0,0 +1,29 @@
+import type { ArtifactDef, ModuleDef } from "@deltarobotics/uhd";
+import type { ArtifactPreview } from "../model/artifacts";
+import type { EvidenceFiles } from "../model/evidence";
+export interface HostActions {
+    openSource?: (defId: string, instancePath?: string) => void;
+    openArtifact?: (defId: string, artifactId: string) => void;
+    /** Open a module on its own (the host's new tab); given only when the host takes it. */
+    openModule?: (path: string) => void;
+    /** Show a module in the host's own inspector (a node's INSPECT); given only when the host has one. */
+    inspect?: (path: string, defId?: string) => void;
+    /** Open a web address (an evidence source); not given: a link in a new tab. */
+    openLink?: (url: string) => void;
+    /**
+     * `"live"` (default): a module's body model turns in a small 3D preview
+     * above its cards. `"cards"`: no model is loaded for the inspector; the
+     * model is a card like the others, with the picture `artifactPreview` gives.
+     */
+    artifactModels?: "live" | "cards";
+    /** A picture for an artifact that is not an image itself (a model's exported preview, or the model to draw small). */
+    artifactPreview?: (def: ModuleDef, artifact: ArtifactDef) => ArtifactPreview | undefined;
+    /** Draws a model small, as a picture's URL, for a card whose preview is a model. Not given: such cards show their icon. */
+    drawModel?: (src: string) => Promise<string>;
+    /** Load pictures from web addresses (default true). */
+    remoteImages?: boolean;
+    /** A definition's evidence files (sources.json, verification.json), when the host has them. */
+    evidence?: (defId: string) => EvidenceFiles | undefined;
+}
+export declare const HostContext: import("react").Context<HostActions>;
+export declare const useHost: () => HostActions;

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

@@ -0,0 +1,22 @@
+/**
+ * The host message protocol (README, "Host messages"): checking what arrives
+ * over `postMessage`, and which origins a frame's parent may have. Nothing
+ * here names a host.
+ */
+import type { ViewerEvent, ViewerHostMessage } from "../api";
+/** Every protocol message's type starts with this. */
+export declare const PREFIX = "uhd-viewer:";
+/**
+ * A host → viewer message, checked and normalised (a path given as a list of
+ * child ids is joined); undefined for anything else.
+ */
+export declare function parseHostMessage(data: unknown): ViewerHostMessage | undefined;
+/** A viewer → host event (for a host or a relay telling them from other messages). */
+export declare const isViewerEvent: (data: unknown) => data is ViewerEvent;
+/**
+ * `origin` is one of `allowed`: an exact origin, `scheme://*` (any origin
+ * with that scheme), or `*` (any). An opaque origin ("null") matches only `*`.
+ */
+export declare function originAllowed(origin: string, allowed: readonly string[]): boolean;
+/** Origins from a comma-separated list (`a,b`), blanks dropped. */
+export declare const originList: (value: string | null | undefined) => string[];

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

@@ -0,0 +1,85 @@
+/**
+ * Host messages against the model: what a focus or a select names on which
+ * drill level, and the viewer's selection as the host sees it (canonical
+ * paths from the root). Pure functions, so they test without a page.
+ */
+import type { ModuleDef } from "@deltarobotics/uhd";
+import type { ModuleLookup } from "@deltarobotics/uhd";
+import type { ViewerSelection } from "../api";
+import type { ViewModel } from "../model/types";
+/** A selection on the level being viewed (ids relative to it), as the canvas and inspector hold it. */
+export type LevelSelection = {
+    kind: "node" | "link";
+    id: string;
+} | null;
+/** The longest prefix of `path` that names instances, child by child, from `root`. */
+export declare function instancePrefix(root: ModuleDef, lookup: ModuleLookup, path: string[]): string[];
+/**
+ * Where to show a focused module: the current level when it is drawn there
+ * (a child, or a child of a module expanded in place), else the level of its
+ * parent. A path that stops naming instances is followed as far as it does;
+ * the root (or nothing valid) shows the top level with nothing selected.
+ */
+export declare function focusTarget(root: ModuleDef, lookup: ModuleLookup, path: string, current: {
+    drill: string[];
+    expanded: ReadonlySet<string>;
+}): {
+    drill: string[];
+    selection: LevelSelection;
+};
+/**
+ * The drill path for `path`: as far as it names instances, and only through
+ * modules with children of their own (a level shows a module's children).
+ */
+export declare function drillTarget(root: ModuleDef, lookup: ModuleLookup, path: string): string[];
+/** A selection in the 3D view (by instance path), as the host sees it. */
+export declare function cadHostSelection(sel: {
+    body?: string;
+    component?: string;
+    harness?: string;
+    mate?: string;
+}, defAt: (path: string[]) => ModuleDef | undefined): ViewerSelection | null;
+/**
+ * What a host's select picks in the 3D view, by path from the root: the
+ * selection it made on the diagram's level (a module or a link; nets are not
+ * drawn in 3D), else the first id naming a module instance in full. `none`
+ * for no ids; undefined when nothing applies.
+ */
+export declare function cadSelectTarget(root: ModuleDef, lookup: ModuleLookup, drill: string[], onLevel: LevelSelection | undefined, ids: string[]): {
+    kind: "node" | "link" | "none";
+    path: string;
+} | undefined;
+/** A stored or derived link id as the view selects it: the line that draws it, or the derived link itself. */
+export declare function selectableLink(vm: ViewModel, id: string): LevelSelection;
+/**
+ * The first of `ids` drawn on this level: a node (module instance path, net,
+ * boundary port) or a link. `node:` and `link:` prefixes pick the kind. Ids
+ * are canonical paths from the root (as `selectionChanged` reports them) or
+ * relative to the level. Undefined when none is there; null for no ids.
+ */
+export declare function selectTarget(vm: ViewModel, drill: string[], ids: string[]): LevelSelection | undefined;
+/** A level id as a canonical path from the root. */
+export declare function fullId(drill: string[], id: string): string;
+/**
+ * The selection as the host sees it: canonical ids, and the definition of
+ * the module selected (for a link, the module that declares it).
+ */
+export declare function hostSelection(vm: ViewModel, drill: string[], selection: LevelSelection, levelDefId?: string): ViewerSelection | null;
+/** The definition that declares a level link: the module expanded in place that holds it, or the level's. */
+export declare function linkOwner(vm: ViewModel, linkId: string, levelDefId?: string): string | undefined;
+/** Selections compare by content (the host hears each change once). */
+export declare const selectionKey: (s: ViewerSelection | null) => string;
+/**
+ * Whether the host hears the selection now: when it changed, and when a module or link was picked again while it
+ * was selected (a click on it, a row of the hierarchy, a host's focus). A pick is a new `pick` (the controller's
+ * state object, made anew by each pick, kept when nothing was picked); a rebuild or a view change makes none.
+ * The host then knows the user chose it (D6: the Inspector comes back every time, also for the module already
+ * selected), and two picks that arrive together (nothing, then the same module again) are still said.
+ */
+export declare function saySelection(sent: {
+    key: string;
+    pick: unknown;
+}, now: {
+    selection: ViewerSelection | null;
+    pick: unknown;
+}): boolean;

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

@@ -0,0 +1,69 @@
+export interface BoardNode {
+    id: string;
+    w: number;
+    h: number;
+    /** A net junction (placed after the components). */
+    net?: boolean;
+    /** Taxonomy category ("power.regulator", "component.passive.capacitor"). */
+    category?: string;
+    label?: string;
+    /** A junction that is one tap of a rail drawn in several places: the rail's id (taps.ts). */
+    tapOf?: string;
+    /** A card's height once one side holds this many ports (cards grow to fit their ports). */
+    heightFor?: (perSide: number) => number;
+    /** Ports on lines that do not go to a junction (a sheet port's, a direct link's): either side. */
+    otherPorts?: number;
+}
+export interface Rect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export type FunctionGroup = "io" | "power" | "mcu" | "sensor" | "output" | "other";
+/** A passive or discrete part: placed with the part it serves rather than in a group of its own. */
+export declare function isSatellite(category?: string): boolean;
+/** The function group of a component, from its category. */
+export declare function functionGroup(category?: string): FunctionGroup;
+/** Whether `boxes` overlap once each is grown by its own padding. */
+export declare function hits(a: Rect, b: Rect, padA?: number, padB?: number): boolean;
+/**
+ * The free top-left position nearest `ideal` (a centre) for a box of size w×h,
+ * clear of every obstacle by the paddings. Falls back to below everything.
+ */
+export declare function freeSpot(ideal: [number, number], w: number, h: number, obstacles: Rect[], pad?: {
+    x: number;
+    y: number;
+}): {
+    x: number;
+    y: number;
+};
+/**
+ * Isotonic placement: tops for boxes in a fixed order, each at least `gap`
+ * below the one before, as close to its ideal top as that allows (least
+ * squares, pool-adjacent-violators).
+ */
+export declare function pack(ideal: number[], heights: number[], gap: number): number[];
+/** What the layout and the rail taps share: the clusters of a board level. */
+export interface BoardClusters {
+    /** Cluster (its anchor's id) of each component. */
+    clusterOf: Map<string, string>;
+    /** Members of each cluster: the anchor first, then its satellites in reading order. */
+    clusters: Map<string, string[]>;
+    /** Function group of each cluster. */
+    group: Map<string, FunctionGroup>;
+    /** Component members of each junction. */
+    members: Map<string, string[]>;
+    /** Component ↔ component lines (two-member nets of their own). */
+    direct: [string, string][];
+}
+/** Cluster a board level's components: each passive with the part it serves, a dedicated connector with its part. */
+export declare function boardClusters(nodes: BoardNode[], edges: [string, string][]): BoardClusters;
+/**
+ * Top-left positions by node id for a board level. `edges` are the lines
+ * drawn between nodes (component ↔ junction, or component ↔ component).
+ */
+export declare function boardLayout(nodes: BoardNode[], edges: [string, string][]): Record<string, {
+    x: number;
+    y: number;
+}>;

package/dist/components/types/uhd-viewer/src/layout/card-body.d.ts

@@ -0,0 +1,64 @@
+/**
+ * What a module card's body holds (its icon, its title and the chips that
+ * count its unlinked interfaces by protocol) and how much height that needs.
+ *
+ * The layout grows a card to fit its body between the labels of the ports
+ * on its top and bottom edges; the card then draws only the chips that fit
+ * and folds the rest into "+N". Sizes follow `.module-body`, `.module-title`
+ * and `.port-group` in styles/app.css.
+ */
+import type { PortGroup } from "./layout";
+import type { Side } from "../canvas/routing";
+/** Chips shown before the rest fold into "+N". */
+export declare const MAX_CHIPS = 4;
+/** Chip rows a card grows for; more chips fold into "+N". */
+export declare const MAX_CHIP_ROWS = 3;
+export interface CardInsets {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+}
+/** A port's label as the card draws it: the name without its parenthesised or dashed qualifier. */
+export declare function portLabelText(name: string): string;
+/** How wide a label on a card's left or right edge may run before it is cut with an ellipsis. */
+export declare function sideLabelWidth(cardWidth: number): number;
+/** A card's width with nothing to fit, and the widest it grows to for its labels. */
+export declare const CARD_W = 170;
+export declare const CARD_W_MAX = 272;
+/** The widest a label on a card's top or bottom edge runs (its share of the edge, when that is less). */
+export declare const TOP_LABEL_MAX = 160;
+/** A label's width as drawn (8 px type). */
+export declare const labelWidth: (name: string) => number;
+/**
+ * The width a card takes so the labels of its linked interfaces fit beside
+ * its body: as wide as the longest needs (two may face each other across the
+ * card), from the plain width up to `CARD_W_MAX`. A longer label is cut with
+ * an ellipsis and says its whole name on hover.
+ */
+export declare function cardWidth(labels: readonly string[]): number;
+/** A label is drawn short: it does not fit `width`, or the card leaves out the name's qualifier. */
+export declare function labelIsCut(name: string, width: number): boolean;
+/**
+ * Room the body keeps clear of the port labels: a label row on the top and
+ * bottom edges that have labelled ports, and on the left and right as wide
+ * as that edge's longest label.
+ */
+export declare function cardInsets(labels: {
+    side: Side;
+    name: string;
+}[], cardWidth: number): CardInsets;
+export declare function chipText(g: PortGroup): string;
+/** The height a card needs for its body, with up to MAX_CHIP_ROWS rows of chips. */
+export declare function cardHeight(title: string, width: number, groups: PortGroup[], insets: CardInsets): number;
+/**
+ * The chips a card of this size draws: as many groups as fit its free rows,
+ * the rest counted in "+N". A card with no room for a row draws none.
+ */
+export declare function fitChips(title: string, box: {
+    w: number;
+    h: number;
+}, groups: PortGroup[], insets: CardInsets): {
+    shown: PortGroup[];
+    rest: number;
+};

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

@@ -0,0 +1,94 @@
+import type { ViewLink, ViewModel, ViewPort } from "../model/types";
+import { type Pt, type Side } from "../canvas/routing";
+import type { LinkLayout } from "../api";
+/** Distance kept between a corner and anything placed on a link (handles, toggles). */
+export declare const BEND_CLEAR = 28;
+export interface Box {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** A link's hand layout: part of the host contract (src/api.ts). */
+export type { LinkLayout };
+export interface LevelLayout {
+    /** Top-level nodes: absolute. Nodes inside a container: relative to it. */
+    nodes: Record<string, Partial<Box>>;
+    /** Port side overrides keyed "node|port". */
+    ports?: Record<string, Side>;
+    links?: Record<string, LinkLayout>;
+}
+export interface PlacedPort {
+    node: string;
+    port: ViewPort;
+    side: Side;
+    /** Absolute position on the node outline. */
+    x: number;
+    y: number;
+    /** Colour key: the link that decides this port's classification colour. */
+    links: ViewLink[];
+}
+export interface PortGroup {
+    protocol: string;
+    domain: string;
+    count: number;
+}
+export interface ComputedLayout {
+    boxes: Record<string, Box>;
+    ports: Record<string, PlacedPort>;
+    /** Unlinked ports summarised per node (design D6: "UART ×4"). */
+    groups: Record<string, PortGroup[]>;
+    routes: Record<string, Pt[]>;
+    /** Label anchor per link (absent: route too short to label). */
+    labels: Record<string, Pt>;
+    /** Label + toggle position as an arc length along the route. */
+    labelAt: Record<string, number>;
+    /** Harness region span along the route (arc lengths), for links that run through one. */
+    runs: Record<string, [number, number]>;
+    /** Pinned waypoints per link, and the automatic ones (the router's own bends). */
+    pins: Record<string, Pt[]>;
+    bends: Record<string, Pt[]>;
+    /** Links whose label (and expansion point) the user or the display file placed. */
+    labelFixed: Record<string, boolean>;
+    /** The display file's and the user's label and tab placement per link, merged. */
+    edits: Record<string, LinkLayout>;
+}
+export declare const portKey: (node: string, port: string) => string;
+/** How an automatic layout starts (PB-1007): cards that keep their places, and an earlier arrangement to keep. */
+export interface ArrangeOptions {
+    /** Top-level cards that stay where they are (top-left). */
+    fixed?: Record<string, {
+        x: number;
+        y: number;
+    }>;
+    /** Each top-level card's centre in an earlier layout: the arrangement to start from. */
+    seed?: Record<string, {
+        x: number;
+        y: number;
+    }>;
+    /** The old default (one row), for comparing against. */
+    legacy?: boolean;
+}
+/**
+ * A drag in progress: only the links touching what moves are rerouted, around
+ * the routes the other links already have; everything is rerouted once the
+ * drag ends. Keeps dragging a module or a waypoint at frame rate.
+ */
+export interface LiveLayout {
+    previous: ComputedLayout;
+    /** Nodes being dragged (their children move with them). */
+    nodes?: Set<string>;
+    /** Links whose waypoints are being dragged. */
+    links?: Set<string>;
+}
+/**
+ * The automatic layout of a level as a hand layout (PB-1007, for a host that
+ * writes it to the display file): top-level nodes absolute, nodes inside an
+ * expanded module relative to it. `fixed` cards keep their places; a `seed`
+ * keeps an earlier arrangement where it can.
+ */
+export declare function arrangeLevel(vm: ViewModel, opts?: ArrangeOptions, keepSizes?: LevelLayout): LevelLayout;
+export declare function computeLayout(vm: ViewModel, hand: LevelLayout | undefined, overrides: Record<string, {
+    x: number;
+    y: number;
+}>, showGrounds: boolean, linkOverrides?: Record<string, LinkLayout>, live?: LiveLayout, arrange?: ArrangeOptions): ComputedLayout;

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

@@ -0,0 +1,32 @@
+export interface GridNode {
+    id: string;
+    w: number;
+    h: number;
+    category?: string;
+}
+export interface GridOptions {
+    /** Cards that stay where they are: top-left positions. */
+    fixed?: Record<string, {
+        x: number;
+        y: number;
+    }>;
+    /** Where each card's centre was: the starting arrangement. */
+    seed?: Record<string, {
+        x: number;
+        y: number;
+    }>;
+    /** Width over height to aim for (default 1.6). */
+    aspect?: number;
+}
+/** Room between columns (lines and their labels run there) and between rows. */
+export declare const GRID_GAP_X = 192;
+export declare const GRID_GAP_Y = 128;
+/**
+ * Top-left positions by id for a level of modules. `edges` are the lines
+ * between cards (one entry per line; several between two cards weigh more,
+ * though less than that many).
+ */
+export declare function gridLayout(nodes: GridNode[], edges: [string, string][], opts?: GridOptions): Record<string, {
+    x: number;
+    y: number;
+}>;