@deltarobotics/uhd-viewer 0.2.0 → 0.2.1

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

@@ -15,6 +15,8 @@ export interface ModelViewProps {
     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;
@@ -25,4 +27,4 @@ export interface ModelInfo {
     meshes: number;
     triangles: number;
 }
-export declare function ModelView({ url, object, name, detail, error, onReady, actions, className }: ModelViewProps): import("react").JSX.Element;
+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/canvas/Canvas.d.ts

@@ -45,10 +45,14 @@ export interface CanvasProps {
     onMove: (id: string, x: number, y: number) => void;
     /** A drag starts (what moves) or ends (null): the layout reroutes only what moves meanwhile. */
     onLive: (live: Live | null) => void;
-    /** A node to bring into view (a host's focus), once it is drawn; `seq` tells repeats apart. */
+    /**
+     * A node to bring into view (a host's focus, a row of the hierarchy), once it is drawn; `seq` tells repeats
+     * apart. With `lines`, a harness drawn along lines (no card of its own): those lines are framed.
+     */
     centre?: {
         id: string;
         seq: number;
+        lines?: readonly string[];
     };
     /** A selection to bring into view if it is not (a host's select): panned to, zoomed out only if it must; `seq` tells repeats apart. */
     reveal?: {

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

@@ -64,12 +64,12 @@ export declare const rightRelease: (press: RightPress) => "menu" | "pan";
 export declare const TOOL_OPTIONS: readonly [{
     readonly id: "select";
     readonly icon: "mouse-pointer-2";
-    readonly label: "Select: drag on the canvas to select several";
+    readonly label: "Select";
     readonly shortcut: "V";
 }, {
     readonly id: "pan";
     readonly icon: "hand";
-    readonly label: "Pan: drag to move the view";
+    readonly label: "Pan";
     readonly shortcut: "H";
 }];
 /** What a key press asks of the canvas. */

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

@@ -18,6 +18,24 @@ export type Rect = {
 };
 /** Where a selection is drawn, in flow coordinates: a node's box, or every line of a link (a derived link: the lines it runs over). */
 export declare function selectionBounds(vm: ViewModel, layout: ComputedLayout, selection: RevealSelection): Rect | undefined;
+/** Where several lines are drawn together (a harness along the lines that carry it), in flow coordinates. */
+export declare function linesBounds(layout: ComputedLayout, lineIds: readonly string[]): Rect | undefined;
+/**
+ * The viewport that frames `rect`, as a module is framed when it is focused:
+ * centred in the view clear of the floating chrome, zoomed to fit it, never
+ * past `maxZoom`.
+ */
+export declare function frameViewport(rect: Rect, pane: {
+    width: number;
+    height: number;
+}, inspector: boolean, { maxZoom, minZoom }?: {
+    maxZoom?: number;
+    minZoom?: number;
+}): {
+    x: number;
+    y: number;
+    zoom: number;
+};
 /**
  * The viewport that shows `rect` clear of the floating chrome (the inspector
  * too, when open), or undefined when it is in view already. It keeps the zoom

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

@@ -9,8 +9,11 @@ import { type HostFinding } from "../model/slots";
 import { type InterfaceCardActions } from "./InterfaceCards";
 import type { Selection } from "../canvas/Canvas";
 export type Panel = "hierarchy" | "checks";
-/** "24 models · 2 docs · 1 evidence": what a definition's artifacts, and its parts', are, by group. */
-export declare function artifactSummary(def: ModuleDef | undefined, lookup: (id?: string) => ModuleDef | undefined): {
+/**
+ * "4 models · 2 docs · 1 evidence": what a definition's own artifacts are, by group. A parent's are its own only
+ * (PB-1088): its children's are theirs, a selection away.
+ */
+export declare function artifactSummary(def: ModuleDef | undefined, _lookup?: (id?: string) => ModuleDef | undefined): {
     count: number;
     text: string;
 };
@@ -101,8 +104,15 @@ declare function InspectorView(props: {
     onNodeContext?: (id: string, x: number, y: number) => void;
 }): import("react").JSX.Element;
 export interface NodeMenuItem {
+    /** Title case, a few words. */
     label: string;
     run: () => void;
+    /** A Lucide icon name, at the item's left. */
+    icon?: string;
+    /** The key that does the same, at the item's right (`F`, `Ctrl+A`). */
+    shortcut?: string;
+    /** A rule above the item: it starts a group. */
+    separator?: boolean;
 }
 /** A small menu at the pointer; any click elsewhere, Escape, or a choice closes it. */
 export declare function NodeMenu({ x, y, items, onClose }: {

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

@@ -10,6 +10,16 @@ export declare const CARD_LOOK: {
     readonly toggle: "min-w-0 truncate text-left text-[12px] leading-[18px] text-fg outline-none after:absolute after:inset-0 after:content-[''] cursor-pointer";
     readonly chip: "inline-flex h-[18px] shrink-0 items-center rounded-[4px] bg-[color-mix(in_oklab,var(--uhd-text)_8%,transparent)] px-1.5 text-[10px] leading-none text-fg-muted";
     readonly pin: "inline-flex h-4 shrink-0 items-center rounded-[4px] border border-line px-1 text-[10px] leading-none text-fg-muted";
+    /**
+     * The pin mapping's columns, shared by its rows: the pin as wide as the widest (at least 44 px, its cell's
+     * minimum; at most 40 % of the card), the leaf (when any pin binds one) at most 30 %, and what it meets in the rest.
+     */
+    readonly pinMap: "grid gap-x-2 gap-y-[3px] text-[11px] leading-none";
+    readonly pinMapPins: "grid-cols-[fit-content(40%)_minmax(0,1fr)]";
+    readonly pinMapLeaves: "grid-cols-[fit-content(40%)_fit-content(30%)_minmax(0,1fr)]";
+    readonly pinRow: "col-span-full grid min-h-5 grid-cols-subgrid items-center";
+    /** A pin in the mapping: a chip that ends in an ellipsis when the column is narrower than its name. */
+    readonly pinName: "inline-block h-4 max-w-full truncate rounded-[4px] border border-line px-1 align-middle text-[10px] leading-[14px] text-fg-muted";
     readonly meta: "mt-[5px] flex min-w-0 items-center gap-1";
     readonly role: "ml-auto shrink-0 text-[10px] leading-none text-fg-faint";
     readonly linked: "mt-[5px] flex min-w-0 items-center gap-1.5 text-[11px] leading-[16px]";
@@ -48,7 +58,7 @@ export declare function InterfaceCard({ slot, open, onToggle, actions }: {
     onToggle: () => void;
     actions: InterfaceCardActions;
 }): import("react").JSX.Element;
-/** The cards, the first few shown; "N more · names" opens the rest. */
+/** The cards, ten at a time (PB-1088): "Show 10 more" adds the next ten, "Show fewer" goes back to the first ten. */
 export declare function InterfaceCards({ slots, actions, first }: {
     slots: InterfaceSlot[];
     actions: InterfaceCardActions;

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

@@ -99,7 +99,28 @@ export declare function KeyValues({ rows, limit }: {
     }[];
     limit?: number;
 }): import("react").JSX.Element;
-/** A section's rows shown in part, and the header action that shows them all. */
+/** How many rows of a long list are shown at first, and how many more each "Show more" adds (PB-1088). */
+export declare const LIST_STEP = 10;
+/**
+ * A long list shown `step` rows at a time (PB-1088): "Show 10 more" under the
+ * rows adds the next ones, "Show fewer" goes back to the first `step`.
+ * `keep`: rows that must stay shown (an expanded card), counted from the top.
+ */
+export declare function useLoadMore(total: number, step?: number, keep?: number): {
+    limit: number;
+    footer: ReactNode;
+};
+/**
+ * A long free text (a module's description) cut to `lines` lines, with "More"
+ * to read it all and "Less" to cut it again (PB-1088). The toggle shows only
+ * when the text is cut.
+ */
+export declare function ClampedText({ text, lines, className }: {
+    text: string;
+    lines?: number;
+    className?: string;
+}): import("react").JSX.Element;
+/** A section's rows shown in part, and the header action that shows them all. Lists use `useLoadMore` (PB-1088). */
 export declare function useShowAll(total: number, limit: number): {
     limit: number | undefined;
     aside: ReactNode;

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

@@ -32,12 +32,12 @@ 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 { DiagramCanvas, DiagramToolbar, ToolToggle, ViewButtons, DiagramLegend, DiagramLegendBody, DiagramLegendItems, FittedLegend, LegendFold, LegendToolbarButton, IsolationClear, MissingNotice, ScenarioBanner, Scene3D, ViewerInspector, ViewerNodeMenu, CLASSIFICATION_OPTIONS, DETAIL_OPTIONS, type DiagramCanvasProps, type FittedLegendProps, 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 { Sections, DetailsSection, KeyValues, useShowAll, useLoadMore, ClampedText, LIST_STEP, 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";
@@ -47,8 +47,8 @@ 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 { Legend, LegendItem, LegendSwatches, LegendTab, type LegendItemProps, type LegendProps, type LegendTabProps } from "./ui/Legend";
+export { legendStage, legendRoom, legendFolded, LEGEND_SHORT, 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";

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

@@ -51,6 +51,22 @@ export declare function cadSelectTarget(root: ModuleDef, lookup: ModuleLookup, d
 } | 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 lines a harness is drawn along on this level, when it has no card of
+ * its own: a cable between two parts is one line with the harness as a region
+ * along it, and the links that name a harness carry its region too. Empty for
+ * a harness drawn as a card (and for anything else).
+ */
+export declare function harnessLines(vm: ViewModel, id: string): ViewModel["links"];
+/**
+ * A module selection as the diagram can show it: a harness drawn along its
+ * lines (no card of its own) is selected as the line that carries its name
+ * tab, so a row of the hierarchy or a host's focus on it selects and frames
+ * something drawn. Anything else as it is.
+ */
+export declare function drawnSelection(vm: ViewModel, selection: LevelSelection): LevelSelection;
+/** The harness a selected line runs through (its path on the level), if any: its row in the hierarchy. */
+export declare function selectedHarness(vm: ViewModel, selection: LevelSelection): string | undefined;
 /**
  * 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

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

@@ -19,7 +19,10 @@ 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). */

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

@@ -9,10 +9,11 @@
  * they carry is drawn in two segments through them. System diagnostics
  * (checkSystem) are overlaid onto link state for DRC colouring.
  */
-import type { ChildLink, ModuleDef } from "@deltarobotics/uhd";
+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 } from "./types";
+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 {

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

@@ -153,15 +153,19 @@ export declare const HIERARCHY_WIDTH: {
 /** A kept state, checked; anything malformed falls back to the default. */
 export declare function panelState(v: unknown, fallbackOpen?: boolean): HierarchyPanelState;
 export declare const clampWidth: (w: number, room?: number) => number;
-/** The row that holds the wiring and hardware (harnesses, cables, fastener stacks): not a module of the system. */
+/** The row "Harnesses & links" that holds the harnesses, cables and fastener stacks: not a module of the system. */
 export declare const WIRING_PATH = "#wiring";
 /**
- * The tree as the panel shows it: the system's structure first, and its
- * wiring and hardware (every harness and fastener stack, wherever it sits)
- * folded into one group row at the bottom, `WIRING_PATH`. Without any, the
- * tree as it is.
+ * The tree as the panel shows it: the system's structure first, and the
+ * harnesses and links (harnesses, cables and fastener stacks) folded into one
+ * group row at the bottom, `WIRING_PATH`. With `level` (the instance path of
+ * the level on screen, "" for the root), the group holds only that level's own
+ * harnesses, not those of the modules inside it: they show once that module is
+ * the level. Without `level`, every harness, wherever it sits, each with the
+ * module it belongs to. Harnesses never show in the structure. Without any for
+ * the group, the structure alone.
  */
-export declare function groupWiring(nodes: readonly HierarchyNode[]): HierarchyNode[];
+export declare function groupWiring(nodes: readonly HierarchyNode[], level?: string): HierarchyNode[];
 /** The marks the tree shows, once each, in the order of their tones: a legend (the first sentence of a mark's label names it). */
 export declare function markLegend(nodes: readonly HierarchyNode[]): {
     tone: NodeMark["tone"];

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

@@ -0,0 +1,7 @@
+import type { ViewNode } from "./types";
+/**
+ * The modules a level draws: its nodes less what is not a module of its own
+ * (the drilled-into module's boundary ports, a board's net junctions and
+ * their taps). A level with none is empty, whatever ports it shows.
+ */
+export declare function levelModules(nodes: readonly ViewNode[]): ViewNode[];

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

@@ -83,6 +83,8 @@ export interface InterfaceSlot {
     usedBy?: string;
     /** Exported to the boundary of the module it is in, by that name: linked from outside, not open. */
     exportedAs?: string;
+    /** A pin bound into another interface of the module (a UART's RX inside its pad group), by that one's name: not on the outline, not linked on its own. */
+    partOf?: string;
     /** The worst state of its links. */
     state?: SlotState;
     pinMap: SlotPin[];

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

@@ -1,10 +1,13 @@
 /**
  * Legend primitives: a floating card with a title and swatches. A swatch is
  * a short line (links) or a dot (states). An item given `onSelect` is a
- * button: the legend then isolates what it stands for. A compact item is
- * its swatch alone, named by its label (`LegendSwatches` lays them out).
+ * button: the legend then isolates what it stands for. An item with a
+ * `meaning` reads as two lines, its name and what it stands for. A compact
+ * item is its swatch alone, named by its label (`LegendSwatches` lays them
+ * out). Folded, a legend is a tab at the right edge (`LegendTab`): a chevron
+ * and a dot per colour.
  */
-import type { HTMLAttributes, ReactNode, Ref } from "react";
+import type { ButtonHTMLAttributes, HTMLAttributes, ReactNode, Ref } from "react";
 export interface LegendProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
     title?: ReactNode;
     ref?: Ref<HTMLDivElement>;
@@ -30,11 +33,27 @@ export interface LegendItemProps {
     hintShortcut?: string;
     /** The swatch alone (a narrow legend): the label names the button and is its tooltip. */
     compact?: boolean;
+    /** What the entry stands for, in a few words: a second, muted line under the label. */
+    meaning?: string;
 }
-export declare function LegendItem({ color, label, shape, onSelect, pressed, dimmed, absent, hint, hintShortcut, compact }: LegendItemProps): import("react").JSX.Element;
+export declare function LegendItem({ color, label, shape, onSelect, pressed, dimmed, absent, hint, hintShortcut, compact, meaning }: LegendItemProps): import("react").JSX.Element;
 /** Compact items side by side, `columns` to a row: a legend as narrow as its swatches. */
 export declare function LegendSwatches({ columns, children, label }: {
     columns?: number;
     children?: ReactNode;
     label?: string;
 }): import("react").JSX.Element;
+export interface LegendTabProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children"> {
+    /** A dot per colour the legend explains (`dimmed`: it steps back, as an entry does while another is isolated). */
+    dots: {
+        key: string;
+        color: string;
+        dimmed?: boolean;
+    }[];
+    ref?: Ref<HTMLButtonElement>;
+}
+/**
+ * A folded legend: a narrow tab at the right edge, a chevron and the
+ * colours it explains as dots. A click opens the legend; its label names it.
+ */
+export declare function LegendTab({ dots, className, ...rest }: LegendTabProps): import("react").JSX.Element;

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

@@ -1,15 +1,19 @@
 /**
  * How much of the diagram's legend fits beside the bottom toolbar. The legend
- * stays where it is (bottom left) and gives way as the toolbar comes near:
+ * stays where it is (bottom right) and gives way as the toolbar comes near:
  * the full card, then a compact one (swatches without their labels), then,
- * at its smallest, a button in the toolbar that opens it. No DOM here: the
- * legend measures, this decides.
+ * at its smallest, a button in the toolbar that opens it. Folded, it is a
+ * narrow tab at the right edge, which gives way to the button the same way.
+ * A short canvas folds it (`legendShort`). No DOM here: the legend measures,
+ * this decides.
  */
 export type LegendStage = "full" | "compact" | "button";
 /** Space kept between the legend and the toolbar (px). */
 export declare const LEGEND_GAP = 8;
 /** A larger form comes back only with this much room to spare (px), so a width at the edge does not flicker between two. */
 export declare const LEGEND_HYSTERESIS = 6;
+/** Below this canvas height (px) the legend folds by itself: open, it would cover much of the drawing. */
+export declare const LEGEND_SHORT = 500;
 export interface Box {
     left: number;
     top: number;
@@ -17,26 +21,35 @@ export interface Box {
     bottom: number;
 }
 export interface LegendMeasure {
-    /** Where the legend's left edge is (the same for every form). */
-    left: number;
-    /** Each form's box, as it would sit (bottom left). */
+    /** Where the legend's right edge is (the same for every form). */
+    right: number;
+    /** Each form's box, as it would sit (bottom right). */
     full: Box;
     compact: Box;
+    /** The folded tab's box, as it would sit (at the right edge). */
+    tab?: Box;
     /** The toolbar's box, or none (no toolbar, or hidden). */
     toolbar?: Box | null;
     /** The legend's button in the toolbar takes this much of it (its width and gap), when it is there: the toolbar is measured as if it were not. */
     slot?: number;
 }
 /**
- * The room the legend has before the toolbar (px): from its left edge to
- * the toolbar's, less the gap. The toolbar is centred, so its button for the
- * legend moves its left edge by half the button: that half is given back,
- * and the room is the same whether or not the button is in it.
+ * The room the legend has before the toolbar (px): from the toolbar's right
+ * edge to the legend's, less the gap. The toolbar is centred, so its button
+ * for the legend moves its right edge by half the button: that half is taken
+ * back, and the room is the same whether or not the button is in it.
  */
-export declare function legendRoom(m: Pick<LegendMeasure, "left" | "toolbar" | "slot">): number;
+export declare function legendRoom(m: Pick<LegendMeasure, "right" | "toolbar" | "slot">): number;
 /**
  * The largest form that does not run into the toolbar. A form fits when it is
  * clear of the toolbar's height, or narrower than the room. Moving up to a
- * larger form than `current` takes `LEGEND_HYSTERESIS` more.
+ * larger form than `current` takes `LEGEND_HYSTERESIS` more. Folded
+ * (`folded`), the tab is the only form: "full" while it fits, else "button".
+ */
+export declare function legendStage(m: LegendMeasure, current?: LegendStage, folded?: boolean): LegendStage;
+/**
+ * Whether the legend shows folded: the user folded it, or the canvas is
+ * shorter than `LEGEND_SHORT` and the user has not opened it since it became
+ * so (`peek`).
  */
-export declare function legendStage(m: LegendMeasure, current?: LegendStage): LegendStage;
+export declare function legendFolded(open: boolean, canvasHeight: number, peek: boolean): boolean;

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

@@ -132,6 +132,7 @@ export declare function useViewerController(source: LoadedSource, options: Viewe
     centre: {
         id: string;
         seq: number;
+        lines?: readonly string[];
     } | undefined;
     reveal: {
         selection: NonNullable<Selection>;

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

@@ -12,7 +12,7 @@ export interface ViewerHierarchyProps {
     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). */
+    /** The panel opened or folded (at once). */
     onOpenChange?: (open: boolean) => void;
     command?: HierarchyCommand;
     /** Attributes a host puts on every row (`data-*`), e.g. for its own context menu. */
@@ -23,19 +23,35 @@ export interface ViewerHierarchyProps {
     narrow?: number;
     className?: string;
 }
-/** The folded panel's width. */
-export declare const RAIL_WIDTH = 36;
+/** What the folded panel keeps of the view's width: nothing (its button to open it again floats over the view). */
+export declare const RAIL_WIDTH = 0;
+/** The gap between the floating card and the view's edges, the host's header above it and the canvas beside it (px). */
+export declare const CARD_GAP = 4;
+/** How long the card takes to open or fold (ms); none when the system asks for reduced motion. */
+export declare const FOLD_MS = 200;
 /**
- * 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.
+ * The panel's look, in one place (PB-1042, PB-1070): a floating card like the
+ * host's header, 4 px from the view's edges and below the header, with the
+ * panel radius, a border all round and the panel shadow; 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 dock: "uhd-hierarchy-dock absolute bottom-1 left-1 z-30 flex flex-col top-[calc(var(--uhd-inset-top,0px)+4px)] transition-[transform,opacity] duration-200 ease-out motion-reduce:transition-none";
+    /** The dock while it opens or folds (and while folded): slid out to the left, faded. */
+    readonly dockAway: "pointer-events-none -translate-x-[calc(100%+8px)] opacity-0";
+    readonly panel: "relative flex min-h-0 flex-1 flex-col overflow-hidden rounded-panel border border-line bg-surface font-ui text-fg shadow-panel outline outline-1 -outline-offset-1 outline-contrast";
+    /**
+     * The folded panel: the icon alone, floating over the canvas at the card's
+     * corner (no border, face or shadow of its own), that opens it again. On
+     * hover it takes a soft rounded fill with a faint glow, in the theme's
+     * toolbar hover colour (high contrast: a dashed outline instead). It fades
+     * in as the card leaves and out as it comes.
+     */
+    readonly folded: "uhd-hierarchy-reopen absolute left-1 z-30 top-[calc(var(--uhd-inset-top,0px)+4px)] grid size-8 cursor-pointer place-items-center rounded-md border-0 bg-transparent p-0 text-fg-muted transition-[opacity,background-color,color,box-shadow] duration-200 ease-out motion-reduce:transition-none hover:bg-hover hover:text-fg hover:shadow-[0_0_10px_1px_var(--uhd-hover)] hover:outline hover:outline-1 hover:outline-dashed hover:-outline-offset-1 hover:outline-contrast-active focus-visible:outline focus-visible:outline-1 focus-visible:-outline-offset-1 focus-visible:outline-focus";
+    /** The button while it fades in or out (and while the panel is open). */
+    readonly foldedAway: "pointer-events-none opacity-0";
     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";
@@ -51,7 +67,13 @@ export declare const HIERARCHY_LOOK: {
 };
 /** 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. */
+/**
+ * A toolbar button that opens and folds the panel from a host's header.
+ *
+ * @deprecated The panel has its own fold button and, folded, its own button to
+ * open it again (PB-1070); a host needs no toggle of its own. Kept for hosts
+ * written against 0.2.0; it will be removed in a later minor release.
+ */
 export declare function HierarchyToggle({ open, onClick, disabled, className }: {
     open: boolean;
     onClick: () => void;

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

@@ -14,10 +14,19 @@ export interface DiagramCanvasProps {
     coveredRight?: boolean;
     /** What the shell adds to the notice about definitions the bundle does not hold (how its producer gets them). */
     missingHint?: ReactNode;
+    /**
+     * What a level with no modules offers: a dashed box with a plus and this
+     * label, a button (the shell's way to add one, such as its parts library).
+     * Without it the empty level only says so.
+     */
+    emptyAction?: {
+        label: string;
+        onClick: () => void;
+    };
     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;
+export declare function DiagramCanvas({ toolbar, legend, coveredRight, missingHint, emptyAction, 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;
 /**
@@ -46,11 +55,11 @@ export declare const CLASSIFICATION_OPTIONS: readonly [{
 export declare const DETAIL_OPTIONS: readonly [{
     readonly id: "bundled";
     readonly icon: "minus";
-    readonly label: "Basic: one line per link";
+    readonly label: "One line per link";
 }, {
     readonly id: "conductors";
     readonly icon: "rows-3";
-    readonly label: "Ribbon: every conductor";
+    readonly label: "Every conductor";
 }];
 /**
  * The pointer's tool: select (a drag on the empty canvas draws a selection
@@ -79,8 +88,9 @@ export declare function DiagramToolbar({ coveredRight, className, controls, lege
  * 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.
+ * click on another switches, and Shift, Ctrl or Cmd holds several. Each
+ * reads as its name and, under it, what it stands for. For a shell that
+ * draws its own legend card.
  */
 export declare function DiagramLegendItems({ compact, columns }?: {
     compact?: boolean;
@@ -90,32 +100,53 @@ export declare function DiagramLegendItems({ compact, columns }?: {
 export declare function IsolationClear({ className }: {
     className?: string;
 }): import("react").JSX.Element | null;
+/**
+ * The legend's fold button, at the right of its header: the legend becomes a
+ * tab at the right edge. Nothing where the legend does not fold (the
+ * toolbar's popover).
+ */
+export declare function LegendFold({ 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).
+ * names and meanings; `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 }: {
+export declare function DiagramLegend({ className, coveredRight }: {
     className?: string;
+    coveredRight?: boolean;
 }): import("react").JSX.Element;
+export interface FittedLegendProps {
+    label: string;
+    /** Draws a form of the card. `LegendFold` inside it folds the legend. */
+    render: (form: "full" | "compact") => ReactNode;
+    className?: string;
+    /** Open (the card) or folded (the tab at the right edge). Given: the shell keeps it, with `onOpenChange`; else the legend does, from `defaultOpen`. */
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** Where an uncontrolled legend starts. Default open. */
+    defaultOpen?: boolean;
+    /** A panel floats over the canvas's right side (an inspector): the legend sits left of it. */
+    coveredRight?: boolean;
+}
 /**
- * A legend card at the canvas's bottom left that stays there and gives way
+ * A legend card at the canvas's bottom right 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`).
+ * then offering it behind a button (`LegendToolbarButton`). Folded, it is a
+ * tab at the right edge with a dot per colour, which opens it; a canvas
+ * shorter than `LEGEND_SHORT` folds it until the user opens it there. It
+ * measures the room it has (a `ResizeObserver` on the canvas, the toolbar and
+ * every form) from hidden copies of the 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;
+export declare function FittedLegend({ label, render, className, open: given, onOpenChange, defaultOpen, coveredRight }: FittedLegendProps): 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