@deltarobotics/uhd-viewer 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to **uhd-viewer** (`@deltarobotics/uhd-viewer`) are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] — 2026-10-25
+
+The first public release, and the first on npmjs. The 0.1.x versions were built with the Protoboard stack and never published to npmjs; this section summarises what changed since them.
+
+### Added
+
+- **Open source.** The viewer is under the Apache License 2.0 (`LICENSE`, `NOTICE`). Contributions are welcome with a Developer Certificate of Origin sign-off and no CLA (`CONTRIBUTING.md`, `DCO`). `TRADEMARKS.md` says how the Protoboard name and logo may be used.
+- **UHD 0.3.0.** The viewer reads UHD 0.3.0 bundles: an export may be a net port, and a module may be marked as a board.
+- **A hierarchy panel** (`ViewerHierarchy`): the whole module tree, docked at the left of the view and kept in step with the canvas. A click selects a module, a double-click opens it, and you can type to filter it. It folds, resizes, works from the keyboard as a tree, and stays within its view's width.
+- **A new inspector layout**: sections with clear headers, and cards for interfaces that expand to show their pins. Alike interfaces share one card ("Motor pads ×4"), power comes before signal, and an exported interface says what it is exported as.
+- **Automatic layout that reads better.** A level of modules is laid out as a block rather than one long row, in reading order. A proposed layout replaces a saved one only when it is clearly better. Layout metrics and the layout itself are available without a browser from `@deltarobotics/uhd-viewer/headless`.
+- **The 3D view borrows placement.** A module with no assembly of its own is shown in the nearest assembly above it, and the view says where the placement comes from.
+- **Canvas controls**: right-drag pans (a right-click without a drag still opens the menu); Space-drag pans from over a module too.
+- **The legend makes way**: on a small view it shrinks to a compact form, then to a toolbar button.
+
+### Changed
+
+- Labels and headers use bold Kode Mono (SIL Open Font License, shipped with its licence text) in place of the earlier commercial face.
+- Shorter interface text throughout, and an empty level says what to do in one line.
+- A module picked again while it is selected is reported to the host again, so a host's inspector comes back each time.
+- Viewports a host gives after the viewer has started are applied.
+
+### Security
+
+- `uhd-viewer serve` sends every artifact with a sandboxing content security policy and `X-Content-Type-Options: nosniff`, and an HTML artifact is downloaded rather than shown, so a file in a bundle cannot run script on the viewer's origin.
+
+### Packaging
+
+- The package is public on npmjs with provenance, released from a tag by `.github/workflows/release.yml`. It carries `LICENSE`, `NOTICE` and the font licence.
+
+## 0.1.0 – 0.1.4 — 2026-09-26 to 2026-10-11
+
+Built and published with the Protoboard stack only, not on npmjs. In brief: the system diagram (modules, interfaces, links routed orthogonally, harnesses, bundles that open into their conductors, domain, DRC and signal classifications, the pair view, system checks and fault scenarios); boards, nets and enclosures; the 3D view assembled from UHD's mechanical links, with exploded and section views and callout labels; the viewer as a library (`mountViewer`), a React component library with token theming (a VS Code adapter included), and `uhd-viewer serve`; the host message protocol (focus, select, drill, set view, and the events back); marks on modules; isolating a legend entry; artifacts as cards in the inspector; and the select and pan tools with a selection box and keys.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,22 @@
+Protoboard Stack: UHD Viewer (@deltarobotics/uhd-viewer)
+Copyright 2026 Delta Robotics, Inc.
+
+This product includes software developed at Delta Robotics, Inc.
+(https://deltaroboticsinc.com).
+
+Licensed under the Apache License, Version 2.0 (the "License").
+See the LICENSE file in the root of this repository for full terms.
+
+"Protoboard", the Protoboard logo and the "0" mark are trademarks of
+Delta Robotics, Inc. The License grants no rights to them (section 6);
+see TRADEMARKS.md.
+
+The built application and headless bundles (dist/app, dist/headless)
+include third-party packages (React, three.js, React Flow, Radix UI,
+Lucide), each under its own licence, which applies to that code.
+
+The stylesheets (src/styles, and the built dist/components and dist/app)
+carry the Kode Mono font, Copyright 2023 The Kode Mono Project Authors
+(https://github.com/isaozler/kode-mono), under the SIL Open Font License
+1.1: src/styles/fonts/OFL.txt. The .woff2 files are the released fonts
+converted to WOFF2, glyphs unchanged.

package/README.md

@@ -1,3 +1,169 @@
-# Temporary Holding Version
+# uhd-viewer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**See a hardware system as a diagram and in 3D, from its UHD description.**
+
+[![npm](https://img.shields.io/npm/v/@deltarobotics/uhd-viewer.svg)](https://www.npmjs.com/package/@deltarobotics/uhd-viewer)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+
+`@deltarobotics/uhd-viewer` draws systems described in
+[UHD](https://github.com/Delta-Robotics-Inc/OpenUHD) (Universal Hardware
+Description, an open language for multidisciplinary hardware): the modules,
+their interfaces, the links between them and the harnesses that carry them.
+You give it one UHD bundle (a JSON file) and it shows:
+
+- **a system diagram**: modules as cards, links routed between their ports, bundles and cables that open into
+  their conductors, colours by domain, signal type or check result, and a module opened as a level of its own;
+- **a 3D view**: the system assembled from its mechanical links, with exploded and section views and labels;
+- **boards and enclosures**: a board's nets, pins and drawings;
+- **a hierarchy and an inspector**: the module tree, and the details, interfaces, checks and files of what is selected;
+- **system checks**: supply budgets, bus addresses, interface reuse and the other checks UHD runs, on the
+  diagram and in a panel.
+
+It knows only UHD and needs no account or service. It is the viewer of the
+[Protoboard stack](https://github.com/Delta-Robotics-Inc/protoboard-stack),
+and works the same in any web page, an editor webview or a test harness.
+
+![A quadcopter in the viewer, coloured by domain](docs/screenshots/01-quadcopter-domain.png)
+
+## Install
+
+```bash
+npm install @deltarobotics/uhd-viewer
+```
+
+Node.js 22 or later for the server; any current browser for the viewer.
+
+## Look at a bundle
+
+The package has a small server for the built viewer, a bundle and the files
+the bundle references:
+
+```bash
+npx @deltarobotics/uhd-viewer serve path/to/uhd-bundle.json --open
+```
+
+It binds to `127.0.0.1:5179`, serves only the files the bundle names as
+artifacts, and re-reads the bundle when it changes, so a rebuild shows on
+reload. `--port`, `--host` and `--host-origin` (to let another page frame it)
+are in the [reference](docs/reference.md#uhd-viewer-serve).
+
+A bundle (`uhd.bundle/v0`, defined in UHD) holds a root module, the
+definitions it uses, scenarios, where each definition's files are, and
+display hints. The Protoboard stack writes one with `protoboard build`;
+[`fixtures/imu-pod/uhd-bundle.json`](fixtures/imu-pod/uhd-bundle.json) in this
+repository is a small example.
+
+## Embed it
+
+### The whole viewer in an element
+
+```ts
+import { mountViewer } from "@deltarobotics/uhd-viewer";
+import "@deltarobotics/uhd-viewer/style.css";
+
+const viewer = mountViewer(document.getElementById("viewer")!, {
+  bundleUrl: "/uhd-bundle.json", // or bundle: a parsed bundle
+  theme: "system", // "dark", "light", "vscode", or a theme of your own
+  onSelectionChanged: (selection) => console.log(selection),
+});
+
+viewer.focus("arm_fl/motor"); // drill to a module, select it and bring it into view
+viewer.setView("3d");
+viewer.update({ bundle: rebuilt }); // after a rebuild
+viewer.unmount();
+```
+
+The element needs a height; the viewer fills it. This entry bundles React,
+three.js and React Flow, so it works on any page.
+
+### React components
+
+For a React app with its own layout, `/components` gives the views on their
+own, with React, three.js and React Flow shared with your app:
+
+```tsx
+import { ThemeProvider, UhdViewer, DiagramCanvas, ViewerInspector, defaultThemeAdapter } from "@deltarobotics/uhd-viewer/components";
+import "@deltarobotics/uhd-viewer/components.css";
+
+export function SystemView() {
+  return (
+    <ThemeProvider adapter={defaultThemeAdapter("system")}>
+      <UhdViewer bundleUrl="/uhd-bundle.json">
+        <DiagramCanvas />
+        <ViewerInspector />
+      </UhdViewer>
+    </ThemeProvider>
+  );
+}
+```
+
+Every colour is a theme token (`--uhd-*`); `vscodeThemeAdapter()` follows a VS
+Code webview's theme, and `defineTheme` makes your own.
+
+### Driving it from a host
+
+A host can tell the viewer to focus, select, drill into a level or switch
+view, and hears what the user selects and opens. The messages are the same
+through the handle or, with the viewer in a frame, through `postMessage`:
+
+```js
+frame.contentWindow.postMessage({ type: "uhd-viewer:focus", path: "arm_fl/motor" }, viewerOrigin);
+window.addEventListener("message", (e) => {
+  if (e.data?.type === "uhd-viewer:selectionChanged") show(e.data.selection);
+});
+```
+
+A framed viewer listens only to the origins its server allows
+(`serve --host-origin`).
+
+### Entry points
+
+| Import | What |
+| --- | --- |
+| `@deltarobotics/uhd-viewer` (+ `/style.css`) | `mountViewer`: the whole viewer in an element, everything bundled |
+| `@deltarobotics/uhd-viewer/components` (+ `/components.css`) | The views as React components, the theme provider and adapters, the inspector's details on their own |
+| `@deltarobotics/uhd-viewer/headless` | The layout and its metrics without a browser |
+| `@deltarobotics/uhd-viewer/serve` | `viewerHandler`: the server's routes for a Node server of your own |
+| `@deltarobotics/uhd-viewer/tailwind-theme.css` | The Tailwind 4 theme, for a host's own build |
+| `@deltarobotics/uhd-viewer/app/*` | The built standalone app |
+
+The [reference](docs/reference.md) has the rest: every option, the host
+messages, URL parameters, pointer and keys, the 3D view, boards and nets,
+and how the bundle is read.
+
+## Develop
+
+The viewer builds against UHD's source in a sibling checkout:
+
+```bash
+git clone https://github.com/Delta-Robotics-Inc/OpenUHD uhd
+git -C uhd checkout v0.3.0
+git clone https://github.com/Delta-Robotics-Inc/uhd-viewer
+cd uhd-viewer
+npm install
+npm run dev    # http://localhost:5178/?bundle=<url of a bundle>
+npm test
+npm run build  # type-check, then the app, the library, the components and the headless entry into dist/
+```
+
+[CONTRIBUTING.md](CONTRIBUTING.md) has the details, and how to sign off
+your commits.
+
+## Related
+
+- [OpenUHD](https://github.com/Delta-Robotics-Inc/OpenUHD): the description language the viewer reads (`@deltarobotics/uhd`).
+- [Protoboard stack](https://github.com/Delta-Robotics-Inc/protoboard-stack): the command line, VS Code extension and agent tools that build UHD bundles from a project, and show them in this viewer.
+
+## Licence
+
+Apache License 2.0: see [LICENSE](LICENSE) and [NOTICE](NOTICE). The fonts are
+Kode Mono under the SIL Open Font License 1.1
+([OFL.txt](src/styles/fonts/OFL.txt)). Contributions are welcome under the
+same licence, with a Developer Certificate of Origin sign-off and no CLA
+([CONTRIBUTING.md](CONTRIBUTING.md)). Report security problems privately
+([SECURITY.md](.github/SECURITY.md)).
+
+"Protoboard", its logo and the "0" mark are trademarks of Delta Robotics,
+Inc.; the licence does not grant them ([TRADEMARKS.md](TRADEMARKS.md)). The
+hosted Protoboard cloud (the parts library, accounts and cloud services) is a
+separate service with its own terms, not covered by this licence.

package/bin/serve.d.mts

@@ -0,0 +1,62 @@
+/**
+ * Declarations for `@deltarobotics/uhd-viewer/serve` (bin/serve.mjs), written
+ * by hand: the server is plain JavaScript. test/serve-types.test.ts checks
+ * that they match what the module exports.
+ */
+import type { IncomingMessage, Server, ServerResponse } from "node:http";
+
+export declare const BUNDLE_SCHEMA: "uhd.bundle/v0";
+/** URL path of the served (rewritten) bundle, relative to the app. */
+export declare const BUNDLE_URL: "uhd-bundle.json";
+export declare const DEFAULT_PORT: number;
+/** The built app (dist/app) next to this file. */
+export declare const APP_DIR: string;
+
+export interface BundlePlan {
+  /** URL name → base folder. */
+  mounts: Map<string, string>;
+  /** "<name>/<artifact path>" → file on disk. */
+  files: Map<string, string>;
+  /** Definition id → mount name or URL. */
+  bases: Record<string, string>;
+  /** The bundle as served from `origin` (artifact bases rewritten to URLs, everything else as given). */
+  rewrite: (origin: string) => { [key: string]: unknown; artifactBases: Record<string, string> };
+}
+
+/** What to serve for one parsed `uhd.bundle/v0` read from `bundleFile`. Throws if it is not a bundle. */
+export declare function planBundle(bundle: unknown, bundleFile: string): BundlePlan;
+
+/** Headers every artifact response carries: a sandboxing Content-Security-Policy and `X-Content-Type-Options: nosniff`. */
+export declare const ARTIFACT_HEADERS: Readonly<Record<"content-security-policy" | "x-content-type-options", string>>;
+/** The headers an artifact file is sent with: ARTIFACT_HEADERS, and `Content-Disposition: attachment` for an HTML file. */
+export declare function artifactHeaders(file: string): Record<string, string>;
+
+/** The app's index.html with `config` injected as `<script type="application/json" id="uhd-viewer-config">`. */
+export declare function injectConfig(html: string, config: { bundleUrl?: string; hostOrigins?: string[] }): string;
+
+export interface ViewerHandlerOptions {
+  /** The bundle on disk (re-read when it changes). */
+  bundleFile: string;
+  /** The built app; defaults to APP_DIR. */
+  appDir?: string;
+  /** Which Host header names to answer; defaults to loopback names only. */
+  allowHost?: (hostname: string) => boolean;
+  /** Parent origins the app takes host messages from when framed (exact, `scheme://*` or `*`); none by default. */
+  hostOrigins?: string[];
+}
+
+/** A request handler for the viewer, a bundle and its artifacts. It answers every request it is given. */
+export declare function viewerHandler(options: ViewerHandlerOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+
+export interface StartServerOptions {
+  bundleFile: string;
+  port?: number;
+  /** Interface to bind; defaults to 127.0.0.1. */
+  host?: string;
+  appDir?: string;
+  /** Parent origins the app takes host messages from when framed (`--host-origin`). */
+  hostOrigins?: string[];
+}
+
+/** Starts the server. Fails before listening if the bundle or the built app is missing. */
+export declare function startServer(options: StartServerOptions): Promise<{ url: string; server: Server; close: () => Promise<void> }>;