@deltarobotics/uhd-viewer 0.0.0-stage → 0.2.1

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;
+}>;

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

@@ -0,0 +1,55 @@
+/**
+ * Grid router (PB-803, design D12): orthogonal routes on the 16 px grid.
+ *
+ * A* over grid cells with a direction in the state. It avoids module cards,
+ * penalises bends and crossings, and keeps parallel runs one grid step apart
+ * by charging for cells another route already runs along. Pinned waypoints
+ * (dragged by the user, saved in the display file) are visited in order; the
+ * bends it chooses itself are the automatic waypoints.
+ */
+import type { Pt, Side } from "../canvas/routing";
+export declare const GRID = 16;
+export interface Rect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export declare const snap: (v: number) => number;
+export declare class GridRouter {
+    private x0;
+    private y0;
+    private W;
+    private H;
+    private blocked;
+    /** Cells used by earlier routes: bit 1 horizontal run, bit 2 vertical run. */
+    private used;
+    /** Search state, allocated once and reused: a state is valid when its stamp is the current search's. */
+    private g;
+    private prev;
+    private stamp;
+    private gen;
+    private thorough;
+    /**
+     * `thorough`: a search that runs out of its budget is retried over the whole grid (off while
+     * dragging, where a frame cannot wait for it).
+     */
+    constructor(obstacles: Rect[], extra?: Pt[], margin?: number, thorough?: boolean);
+    private idx;
+    /**
+     * Route from a port (on `fromSide` of its card) to another port, through
+     * `pins` in order. Returns the polyline in canvas coordinates. With
+     * `within`, the route stays inside that rectangle (a link between two
+     * modules of a container expanded in place never leaves the container);
+     * where no such route exists it is routed without the limit.
+     */
+    route(from: Pt, fromSide: Side, to: Pt, toSide: Side, pins?: Pt[], within?: Rect): Pt[];
+    /** The cells a search may use, in grid coordinates (a container's inside), when a route is kept within one. */
+    private region;
+    /** One routing attempt; `strict` gives up (undefined, nothing marked) where a leg finds no way instead of jogging straight. */
+    private routeOnce;
+    private search;
+    /** Treat an existing route (canvas coordinates, axis-aligned) as occupied, as if it had just been routed. */
+    occupy(points: Pt[]): void;
+    private mark;
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Rail taps (PB-873): a supply rail drawn the way a schematic draws it.
+ *
+ * A rail joins most of a board (a 3V3 rail reaches 15–20 parts). Drawn as one
+ * junction it pulls a line from every corner of the sheet. Drawn as a net
+ * label at each place it is used, it reads at a glance: here the rail is
+ * split into taps, one per cluster of parts (a part and the passives that
+ * serve it, board-layout.ts), each joined only to the members of its cluster.
+ * The taps carry the net's name and colour; the one with the most members
+ * keeps the net's id, the others are `<net>~<cluster>` with `tapOf` set.
+ *
+ * Only the drawing changes: the inspector, the hierarchy and the findings
+ * read the level's view model, where the net is one node.
+ */
+import type { ViewModel, ViewNode } from "../model/types";
+/** A power net with at least this many members is drawn as taps. */
+export declare const RAIL_TAP_MIN = 5;
+export declare function tapRails(vm: ViewModel): ViewModel;
+/** The node a selection names for a drawn node: a tap's net. */
+export declare const selectionId: (node: ViewNode | undefined, id: string) => string;

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

@@ -0,0 +1,129 @@
+/**
+ * A definition's artifacts as cards: every artifact is one card with a kind
+ * (image, 3D model, schematic, PCB, datasheet, document, …), a title, where
+ * it comes from (a file, or the host of its URL) and, where it has one, a
+ * picture to show. No React here: the inspector draws the cards
+ * (chrome/ArtifactCards.tsx), a host may read the same list.
+ */
+import type { ArtifactDef, ModuleDef } from "@deltarobotics/uhd";
+import type { ArtifactResolver } from "../api";
+export type ArtifactKind = "image" | "model" | "schematic" | "pcb" | "drawing" | "datasheet" | "document" | "source" | "firmware" | "data" | "evidence";
+/** The sections cards are shown in, in this order. */
+export type ArtifactGroup = "images" | "models" | "board" | "datasheets" | "documents" | "evidence" | "design" | "data";
+export declare const ARTIFACT_GROUPS: {
+    id: ArtifactGroup;
+    title: string;
+}[];
+/** What a card shows above its title: a picture, or a model a host may draw small. */
+export type ArtifactPreview = {
+    kind: "image";
+    src: string;
+} | {
+    kind: "model";
+    src: string;
+};
+export interface ArtifactCardModel {
+    /** Unique among a definition's cards. */
+    key: string;
+    defId: string;
+    /** The artifact's id (absent for a card that is not an artifact of the definition: an evidence source). */
+    artifactId?: string;
+    title: string;
+    kind: ArtifactKind;
+    group: ArtifactGroup;
+    /** The kind in words: "Datasheet", "STEP model", "PCB top". */
+    kindLabel: string;
+    /** The file format, upper case: "PDF", "STEP", "GLB". */
+    format?: string;
+    /** Where it comes from, short: a URL's host, a file's name. */
+    source?: string;
+    /** More about the source: its authority and when it was fetched ("manufacturer · fetched 2026-10-03"). */
+    sourceNote?: string;
+    /** The whole URL or path, for the tooltip. */
+    location?: string;
+    /** What a click opens when no host takes artifacts. */
+    href?: string;
+    /** Lucide icon name, drawn when there is no picture. */
+    icon: string;
+    preview?: ArtifactPreview;
+    /** The artifact is a web address, not a file of the project. */
+    remote: boolean;
+    description?: string;
+    /** The same model in other formats (a STEP and the GLB exported with it): one card, each format a way to open it. */
+    also?: {
+        artifactId: string;
+        format?: string;
+        href?: string;
+    }[];
+}
+/** An evidence source row (sources.json), as far as cards need it. */
+export interface ArtifactSourceRow {
+    id: string;
+    title: string;
+    url: string;
+    type?: string;
+    authority?: string;
+    fetched_at?: string;
+}
+export interface ArtifactCardOptions {
+    /**
+     * A picture for an artifact that is not an image itself (a model's exported
+     * preview, or the model for the host to draw small). Not given: such cards
+     * show their icon.
+     */
+    previewFor?: (def: ModuleDef, artifact: ArtifactDef) => ArtifactPreview | undefined;
+    /** Load pictures from web addresses (default true). A host that loads only its own files turns it off: those cards show their icon. */
+    remoteImages?: boolean;
+    /** The definition's evidence sources: an artifact with the same URL says its authority and when it was fetched; `evidence: true` lists the others as cards of their own. */
+    sources?: ArtifactSourceRow[];
+    evidence?: boolean;
+    /** Artifacts to leave out (already shown another way). */
+    skip?: (artifact: ArtifactDef) => boolean;
+    /**
+     * Keep a part's internal geometry: the per-interface models its mates are computed from (role `interface`),
+     * which a module's cards leave out (QA B2: 17 "interface geometry" GLBs on a flight controller). An
+     * interface's own card asks for them.
+     */
+    internal?: boolean;
+    /** One card per model, its formats together (`mergeFormats`; default true). */
+    mergeFormats?: boolean;
+}
+/** An artifact that is a part's internal geometry, not something to open: one interface's mating model. */
+export declare const isInternalArtifact: (a: Pick<ArtifactDef, "role">) => boolean;
+/** A file's or URL's last path segment. */
+export declare const artifactFileName: (a: Pick<ArtifactDef, "filePath" | "url">) => string;
+/** The extension of an artifact's file or URL, lower case (only a short alphanumeric one counts). */
+export declare function artifactExtension(a: Pick<ArtifactDef, "filePath" | "url">): string;
+/** A URL's host without `www.`, or undefined when it is not a URL. */
+export declare function hostOf(url: string | undefined): string | undefined;
+interface Classified {
+    kind: ArtifactKind;
+    group: ArtifactGroup;
+    kindLabel: string;
+    icon: string;
+}
+/** What an artifact is, from its type, role, format and file name. */
+export declare function classifyArtifact(a: ArtifactDef): Classified;
+/** One artifact as a card. */
+export declare function artifactCard(def: ModuleDef, a: ArtifactDef, resolve: ArtifactResolver, options?: ArtifactCardOptions): ArtifactCardModel;
+/** A definition's evidence sources (sources.json), each as a card: its title, what kind of source, its host, its authority and when it was fetched. */
+export declare const evidenceSourceCards: (defId: string, sources: ArtifactSourceRow[]) => ArtifactCardModel[];
+/**
+ * Every artifact of a definition as a card, in the order of the groups; with
+ * `evidence`, the definition's evidence sources that no artifact names follow
+ * as cards too.
+ */
+export declare function artifactCards(def: ModuleDef | undefined, resolve: ArtifactResolver, options?: ArtifactCardOptions): ArtifactCardModel[];
+/**
+ * One card per model (QA B2): models that are one file in several formats (`body.step` and `body.glb`, beside
+ * each other) are one card, the first's (a STEP before its GLB), with every format named and the others in
+ * `also`. Its title loses a "(STEP)" that named the format.
+ */
+export declare function mergeFormats(cards: ArtifactCardModel[]): ArtifactCardModel[];
+/** Cards by group, in the groups' order; empty groups are left out. */
+export declare function groupArtifactCards(cards: ArtifactCardModel[]): {
+    id: ArtifactGroup;
+    title: string;
+    cards: ArtifactCardModel[];
+}[];
+export {};

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

@@ -0,0 +1,41 @@
+import type { LinkState } from "./types";
+/**
+ * Interface/harness classification (design decision D7): the rule that
+ * colours ports and links. Domain is the default.
+ */
+export type Classification = "domain" | "drc" | "signal";
+export declare const CLASSIFICATIONS: {
+    id: Classification;
+    label: string;
+}[];
+export interface Colorable {
+    domain: string;
+    protocol: string;
+    state?: LinkState;
+}
+export declare function colorFor(item: Colorable, mode: Classification): string;
+/** Items outside the classification's focus are faded (signal mode shows electrical only). */
+export declare function isFaded(item: Colorable, mode: Classification): boolean;
+/** One entry of a classification's legend. `key` is what `classKey` gives the items it stands for. */
+export interface LegendEntry {
+    key: string;
+    /** Its name, as the legend shows it. */
+    label: string;
+    /** What it stands for, in a few words (the legend's second line). */
+    meaning: string;
+    color: string;
+}
+/** The legend entry an item belongs to in a classification (the key of its colour). */
+export declare function classKey(item: Colorable, mode: Classification): string;
+/**
+ * What the colours of a classification mean. With `present` (the keys drawn
+ * on the level, `presentKeys`), the entries the fixed list leaves out (SPI,
+ * CAN, a domain of its own…) are added where the level has them, so every
+ * colour on screen has an entry to read and to isolate.
+ */
+export declare function legendFor(mode: Classification, present?: ReadonlySet<string>): LegendEntry[];
+/** Signal-type colour: one table for links, lanes and conductors ("uart_tx" is a UART). */
+declare function signalColor(protocol: string): string;
+/** Colour of one conductor in signal mode (the same table as links and lanes). */
+export declare const conductorColor: typeof signalColor;
+export {};

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

@@ -0,0 +1,27 @@
+/**
+ * The system checks the viewer runs itself (PB-823).
+ *
+ * UHD derives links per module: a parent does not see through a child
+ * board's nets (docs/boards-and-nets.md, "Limits"). So the root is checked,
+ * and so is every module below it that declares nets (a board), on its own.
+ * A board's findings are re-based onto the root: refs and ids carry the
+ * board's instance path (`board/u2:pin_14`, `link:board/<id>`, `board:sda`),
+ * and `scope` names the board, so the checks panel can say where a finding
+ * is and the diagram can overlay it when that board is drilled into.
+ */
+import type { ModuleDef } from "@deltarobotics/uhd";
+import type { ModuleLookup } from "@deltarobotics/uhd";
+import { type SystemDiagnostic } from "@deltarobotics/uhd";
+export interface ScopedDiagnostic extends SystemDiagnostic {
+    /** Instance path of the module that was checked ("" for the root). */
+    scope: string;
+}
+/** A canonical path below `scope`, re-based onto the root. */
+export declare function rebase(ref: string, scope: string): string;
+/** Instance paths of every module below `root` that declares nets, depth first. */
+export declare function boardsBelow(root: ModuleDef, lookup: ModuleLookup): {
+    path: string;
+    def: ModuleDef;
+}[];
+/** The root's findings, then each board's, re-based onto the root. */
+export declare function systemDiagnostics(root: ModuleDef, lookup: ModuleLookup): ScopedDiagnostic[];

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

@@ -0,0 +1,63 @@
+/**
+ * Evidence for a part: its sources.json and verification.json, when they are
+ * registered (registerEvidenceFiles; nothing does yet), plus the evidence
+ * traits on its definition.
+ *
+ * The traits come with the bundle. The two files do not (yet): UHD has no
+ * part library to read them from, so without a host that supplies them the
+ * viewer shows the traits only.
+ */
+import type { ModuleDef } from "@deltarobotics/uhd";
+export interface SourceRow {
+    id: string;
+    title: string;
+    url: string;
+    type: string;
+    authority: string;
+    supports?: string[];
+    fetched_at?: string;
+}
+export interface Verification {
+    audit: {
+        checked: number;
+        confirmed: number;
+        wrong: number;
+        unsupported: number;
+    } | null;
+    repairs: string | null;
+    assumptions: unknown[];
+    data_gaps: unknown[];
+    vocabulary_gaps: unknown[];
+    recorded_at: string;
+}
+/** Evidence files by part id (definition id). */
+export declare function registerEvidenceFiles(files: {
+    sources: Record<string, SourceRow[]>;
+    verification: Record<string, Verification>;
+}): void;
+export interface Evidence {
+    /** Whether sources.json / verification.json were available at all (false: the audit state is unknown). */
+    filesKnown: boolean;
+    sources: SourceRow[];
+    verification?: Verification;
+    performance: {
+        kind: string;
+        facts: [string, string][];
+    }[];
+    assumptions: {
+        field: string;
+        value?: string;
+        reason?: string;
+    }[];
+    discrepancies: {
+        field: string;
+        resolution?: string;
+    }[];
+    gaps: string[];
+}
+/** A definition's evidence files as a host gives them (`files`), else as registered. */
+export interface EvidenceFiles {
+    sources?: SourceRow[];
+    verification?: Verification;
+}
+export declare function evidenceFor(def: ModuleDef | undefined, files?: EvidenceFiles): Evidence | undefined;

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

@@ -0,0 +1,58 @@
+/**
+ * Adapter: UHD system ModuleDef → neutral view model.
+ *
+ * A level shows the children of one module. Children that have children of
+ * their own are drawn expanded in place when listed in `expanded` (their
+ * boundary ports are exports, joined to the inner ports by pass-through
+ * lines); otherwise they are drawn as a single card with boundary ports.
+ * Harness children (kind "harness") become harness nodes, and every link
+ * they carry is drawn in two segments through them. System diagnostics
+ * (checkSystem) are overlaid onto link state for DRC colouring.
+ */
+import type { ChildLink, InterfaceDef, ModuleDef } from "@deltarobotics/uhd";
+import { type LinkResult, type ModuleLookup } from "@deltarobotics/uhd";
+import type { SystemDiagnostic } from "@deltarobotics/uhd";
+import type { ViewLink, ViewModel, ViewPort } from "./types";
+export declare function toPort(iface: InterfaceDef, owner: ModuleDef, exported?: ViewPort["exported"]): ViewPort;
+/** Link ids whose child links are stored overrides. */
+type Overrides = Record<string, ChildLink[]>;
+export interface LevelLinks {
+    links: ViewLink[];
+    /** Harness children drawn as regions on links, not as nodes. */
+    regionHarnesses: Set<string>;
+    /** Stored or derived link id → the view link that draws it (for diagnostics). */
+    owners: Map<string, string>;
+    /** Every link UHD derives at this level (through cables and over nets). */
+    derived: LinkResult[];
+}
+/**
+ * The links of one level (PB-803/805). A harness with exactly two connector
+ * ends becomes one link from part to part with the harness as a region along
+ * it; its lanes are the links derived through its conductors and its
+ * conductors are the mated positions. Logical links that name a harness get
+ * the same region. Anything else keeps its own line.
+ */
+export declare function levelLinks(def: ModuleDef, results: LinkResult[], lookup: ModuleLookup, prefix: string, overrides: Overrides | undefined): LevelLinks;
+export interface BuildOptions {
+    /** Child ids (at this level) drawn expanded in place. */
+    expanded: Set<string>;
+    /** Stored child-link overrides keyed by link id (top level). */
+    overrides?: Overrides;
+    /**
+     * System diagnostics to overlay on link state. Refs are relative to the
+     * root; findings of a board checked on its own (see App) carry its path
+     * (`link:board/<id>`), so they overlay when that board is drilled into.
+     */
+    diagnostics?: SystemDiagnostic[];
+    /** Draw ground nets as junctions with wires (GND wires on) rather than as ground symbols. */
+    grounds?: boolean;
+}
+/** Apply child-link overrides to a module's stored links. */
+export declare function withOverrides(def: ModuleDef, overrides: Overrides | undefined): ModuleDef;
+/** Descend `drill` child ids from the root to find the module shown at this level. */
+export declare function levelModule(root: ModuleDef, drill: string[], lookup: ModuleLookup): {
+    def: ModuleDef;
+    path: ViewModel["path"];
+};
+export declare function buildView(root: ModuleDef, lookup: ModuleLookup, drill: string[], opts: BuildOptions): ViewModel;
+export {};