@protoboardai/web-viewer 0.0.0-stage → 0.2.0

package/src/vscode/index.ts

@@ -0,0 +1,263 @@
+/**
+ * The viewer webview's script (dist/vscode/protoboard-viewer.js): the VS Code
+ * shell (./Shell.tsx) in one editor tab, loaded from the extension itself,
+ * never from a server.
+ *
+ * - The bundle, its artifacts and live rebuilds come from the project's
+ *   `protoboard dev` server (its `uhd-bundle.json` and server-sent events);
+ *   the extension says where it is (`dev`) and when it moves.
+ * - The viewer's events, the tab's state, layout edits and requests for new
+ *   tabs go to the extension (protocol.ts); its host messages come back.
+ * - Keys the viewer does not use reach VS Code: the webview forwards every
+ *   key press to the workbench, and nothing here stops one.
+ */
+import "@deltarobotics/uhd-viewer/components.css";
+import "./styles.css";
+import { renderViewer, type ViewerHandle } from "@deltarobotics/uhd-viewer/components";
+import type { UhdBundle } from "@deltarobotics/uhd";
+import type { ResolvedView } from "@protoboardai/core";
+import { VsCodeShell, type ShellBridge, type VsCodeViewerOptions } from "./Shell.js";
+import { DevLink, type EventSourceLike, type ViewerStatus } from "./devLink.js";
+import { emptyLayout, hasEdits, type FromWebview, type HierarchyAction, type HierarchyRowReport, type LayoutSnapshot, type ModuleSource, type ToWebview, type ViewerLayout, type ViewerViewport, type WebviewConfig } from "./protocol.js";
+
+export { VsCodeShell, vscodeShellThemeAdapter, isProtoboardTheme } from "./Shell.js";
+export * from "./protocol.js";
+export * from "./devLink.js";
+
+interface VsCodeApi {
+  postMessage(message: unknown): void;
+  getState(): unknown;
+  setState(state: unknown): void;
+}
+declare function acquireVsCodeApi(): VsCodeApi;
+
+/** Where every node and edge of the diagram on screen is drawn (absolute canvas coordinates), as the display file needs for a first save of a level. */
+export function snapshot(doc: Document = document): LayoutSnapshot | undefined {
+  const flow = doc.querySelector(".react-flow");
+  if (!flow) return undefined;
+  const nodes: LayoutSnapshot["nodes"] = {};
+  for (const el of flow.querySelectorAll<HTMLElement>(".react-flow__node[data-id]")) {
+    const m = /translate\((-?[\d.]+)px,\s*(-?[\d.]+)px\)/.exec(el.style.transform);
+    if (m && el.dataset.id) nodes[el.dataset.id] = { x: Number(m[1]), y: Number(m[2]) };
+  }
+  const edges = [...flow.querySelectorAll<HTMLElement>(".react-flow__edge[data-id]")].map((el) => el.dataset.id!).filter(Boolean);
+  return { nodes, edges };
+}
+
+/** The hierarchy panel's rows on screen, whether it is open, and the tab's width (the extension's tests ask). */
+export function hierarchyReport(doc: Document = document): { open: boolean; rows: HierarchyRowReport[]; width: number } {
+  const rows = [...doc.querySelectorAll<HTMLElement>('[role="treeitem"][data-hierarchy-path]')].map((el) => ({
+    path: el.dataset.hierarchyPath ?? "",
+    label: el.getAttribute("aria-label") ?? el.textContent ?? "",
+    ...(el.dataset.kind ? { kind: el.dataset.kind } : {}),
+    ...(el.getAttribute("aria-selected") === "true" ? { selected: true } : {}),
+    ...(el.getAttribute("aria-current") ? { current: true } : {}),
+  }));
+  return { open: Boolean(doc.querySelector('[data-hierarchy="open"]')), rows, width: doc.defaultView?.innerWidth ?? 0 };
+}
+
+/** The bundle's artifact bases are named by the host the server was asked on: reach them through the URL the webview uses. */
+export function rebase(bundle: UhdBundle & { artifactBases?: Record<string, string> }, devUrl: string): UhdBundle {
+  for (const [id, base] of Object.entries(bundle.artifactBases ?? {})) {
+    const m = /^https?:\/\/[^/]+\/(artifacts\/.*)$/.exec(base);
+    if (m) bundle.artifactBases![id] = new URL(m[1], devUrl).href;
+  }
+  return bundle;
+}
+
+/** Mount the shell in `element` with the page's config; returns the viewer's handle once the first bundle loads. */
+export function mountVsCodeViewer(element: HTMLElement, config: WebviewConfig, vscode: VsCodeApi = acquireVsCodeApi()) {
+  const post = (m: FromWebview) => vscode.postMessage(m);
+  const showListeners = new Set<(view: string) => void>();
+  const statusListeners = new Set<() => void>();
+  let status: ViewerStatus | null = { message: "Connecting to the project…", busy: true };
+  const setStatus = (next: typeof status) => {
+    status = next;
+    for (const l of statusListeners) l();
+  };
+  // the source file of each module the extension has told the tab about (the header's path)
+  const sources = new Map<string, ModuleSource | null>(config.source ? [[config.path ?? "", config.source]] : []);
+  const sourceListeners = new Set<() => void>();
+  // where the user left each level's view: kept with the tab (the webview's own state), so it comes back
+  // when the tab is shown again or VS Code restores it; a level with none is fitted
+  const kept = (vscode.getState() ?? {}) as { viewports?: Record<string, ViewerViewport>; hierarchy?: unknown };
+  const hierarchyListeners = new Set<(command: { type: HierarchyAction; path?: string }) => void>();
+  // a command that came before the shell drew its panel goes to the panel when it does
+  let unheardHierarchy: { type: HierarchyAction; path?: string } | undefined;
+  let viewports: Record<string, ViewerViewport> = kept.viewports && typeof kept.viewports === "object" ? kept.viewports : {};
+  const bridge: ShellBridge = {
+    post,
+    source: (path) => sources.get(path),
+    onSource: (l) => (sourceListeners.add(l), () => void sourceListeners.delete(l)),
+    startView: config.view,
+    startPath: config.path ?? "",
+    ...(config.params ? { startParams: config.params } : {}),
+    onShowView: (l) => (showListeners.add(l), () => void showListeners.delete(l)),
+    status: () => status,
+    onStatus: (l) => (statusListeners.add(l), () => void statusListeners.delete(l)),
+    // the hierarchy panel's open rows, width and fold stay with the tab, as its viewports do
+    hierarchyState: kept.hierarchy,
+    onHierarchyState: (state) => vscode.setState({ ...((vscode.getState() ?? {}) as object), hierarchy: state }),
+    onHierarchy: (l) => {
+      hierarchyListeners.add(l);
+      if (unheardHierarchy) {
+        const m = unheardHierarchy;
+        unheardHierarchy = undefined;
+        queueMicrotask(() => l(m));
+      }
+      return () => void hierarchyListeners.delete(l);
+    },
+    devAction: (action) => {
+      post({ type: "devAction", action });
+      // the tab tries by itself too: the extension answers with the same endpoint when the server is where it was
+      if (action === "retry") link.retry();
+    },
+  };
+
+  let viewer: ViewerHandle | undefined;
+  let layout: ViewerLayout = config.layout ?? emptyLayout();
+  /** Our edits were saved: drop them with the rebuilt bundle that carries them. */
+  let savedPending = false;
+  const waiting: ToWebview[] = [];
+  let views: ResolvedView[] = [];
+  let partStatus: VsCodeViewerOptions["partStatus"];
+
+  const options = (): Omit<VsCodeViewerOptions, "bundle" | "bundleUrl"> => ({
+    bridge,
+    views,
+    ...(partStatus ? { partStatus } : {}),
+    layout,
+    onLayoutChange: (next) => {
+      layout = next;
+      post({ type: "edit", layout: next, ...(hasEdits(next) ? { snapshot: snapshot() } : {}) });
+    },
+    onReady: () => post({ type: "event", event: { type: "uhd-viewer:ready" } }),
+    onSelectionChanged: (selection) => post({ type: "event", event: { type: "uhd-viewer:selectionChanged", selection } }),
+    onOpenSource: (r) => post({ type: "event", event: { type: "uhd-viewer:openSource", ...r } }),
+    onOpenArtifact: (r) => post({ type: "event", event: { type: "uhd-viewer:openArtifact", ...r } }),
+    onOpenModule: (r) => post({ type: "event", event: { type: "uhd-viewer:openModule", path: r.path } }),
+    // the pair view is an editor tab of its own (PB-894 §3): the extension opens it
+    onOpenPair: (r) => post({ type: "event", event: { type: "uhd-viewer:openPair", linkId: r.linkId, a: r.a, b: r.b } }),
+    // INSPECT in a module's menu: the Protoboard Inspector (this tab has no inspector of its own)
+    onInspect: (r) => post({ type: "event", event: { type: "uhd-viewer:inspect", path: r.path, ...(r.defId ? { defId: r.defId } : {}) } }),
+    viewports,
+    onViewportChange: (next) => {
+      viewports = next;
+      vscode.setState({ ...((vscode.getState() ?? {}) as object), viewports: next });
+    },
+  });
+
+  // nothing to draw until there is a bundle: the shell says why
+  viewer = renderViewer(element, options() as VsCodeViewerOptions, VsCodeShell);
+  let loaded = false;
+
+  const log = (level: "info" | "warn" | "error", message: string) => post({ type: "log", level, message });
+  const link = new DevLink({
+    fetch: (url, init) => fetch(url, init),
+    eventSource: (url) => new EventSource(url) as unknown as EventSourceLike,
+    log,
+    onStatus: setStatus,
+    onLoad: ({ base, state, bundle }) => {
+      views = Array.isArray(state.views) ? (state.views as ResolvedView[]) : [];
+      partStatus = state.partStatus && typeof state.partStatus === "object" ? (state.partStatus as VsCodeViewerOptions["partStatus"]) : undefined;
+      viewer!.update({ ...options(), bundle: rebase(bundle as UhdBundle, base), bundleUrl: new URL("uhd-bundle.json", base).href, diagnostics: state.diagnostics } as Partial<VsCodeViewerOptions>);
+      if (!loaded) {
+        loaded = true;
+        if (config.path) viewer!.drill(config.path);
+        if (config.view === "3d") viewer!.setView("3d");
+        for (const m of waiting.splice(0)) receive(m);
+      }
+    },
+    onBundle: ({ base, bundle, event }) => {
+      // the display file changed (our save, a checkout, an edit by hand): edits it now holds go
+      // (`poll`: the build was found by asking, which does not say why it was made)
+      const reset = savedPending && (event.reason === "display" || event.reason === "layout" || event.reason === "poll");
+      if (reset) {
+        savedPending = false;
+        layout = emptyLayout();
+      }
+      // a rebuild says the parts' status again (a part added, an update taken)
+      if (event.partStatus && typeof event.partStatus === "object") partStatus = event.partStatus as VsCodeViewerOptions["partStatus"];
+      viewer!.update({ bundle: rebase(bundle as UhdBundle, base), diagnostics: event.diagnostics, ...(reset ? { layout } : {}), ...(partStatus ? { partStatus } : {}) } as Partial<VsCodeViewerOptions>);
+    },
+  });
+  // the extension answers `ready` with where the dev server is; a page that hears nothing asks again, then says so
+  let heard = Boolean(config.dev);
+  const ask = (n: number) =>
+    setTimeout(() => {
+      if (heard) return;
+      post({ type: "ready" });
+      if (n === 2) {
+        log("warn", "the viewer tab has not been told where the dev server is (asked 3 times in 6 s)");
+        setStatus({ message: "This tab is not connected to a project.", problem: true });
+      }
+      if (n < 10) ask(n + 1);
+    }, 2000);
+
+  function receive(m: ToWebview) {
+    if (!loaded && (m.type === "command" || m.type === "showView" || m.type === "layout" || m.type === "hierarchy")) {
+      waiting.push(m);
+      return;
+    }
+    switch (m.type) {
+      case "dev":
+        heard = true;
+        link.set(m.dev, m.message, m.busy);
+        return;
+      case "command":
+        viewer?.post(m.command);
+        return;
+      case "showView":
+        if (m.view === "diagram" || m.view === "3d") viewer?.setView(m.view);
+        for (const l of showListeners) l(m.view);
+        return;
+      case "layout":
+        layout = m.layout;
+        viewer?.update({ layout });
+        return;
+      case "saved":
+        savedPending = true;
+        return;
+      case "source":
+        sources.set(m.path, m.source);
+        for (const l of sourceListeners) l();
+        return;
+      case "hierarchy": {
+        const command = { type: m.command, ...(m.path !== undefined ? { path: m.path } : {}) };
+        if (!hierarchyListeners.size) unheardHierarchy = command;
+        for (const l of hierarchyListeners) l(command);
+        return;
+      }
+      case "reportHierarchy":
+        post({ type: "hierarchy", ...hierarchyReport() });
+        return;
+      case "reportTheme": {
+        const style = document.documentElement.style;
+        const vars: Record<string, string> = {};
+        for (let i = 0; i < style.length; i++) {
+          const k = style[i];
+          if (k.startsWith("--vscode-")) vars[k] = style.getPropertyValue(k).trim();
+        }
+        post({ type: "theme", vars, classes: [...document.body.classList], themeId: document.body.dataset.vscodeThemeId });
+        return;
+      }
+    }
+  }
+
+  window.addEventListener("message", (e) => {
+    const m = e.data as ToWebview | undefined;
+    if (m && typeof m === "object" && typeof m.type === "string") receive(m);
+  });
+  window.addEventListener("online", () => log("info", "the browser reports the network is back"));
+  window.addEventListener("offline", () => log("warn", "the browser reports the network is gone (loopback connections are closed with it)"));
+  if (config.dev) link.set(config.dev);
+  post({ type: "ready" });
+  ask(0);
+  return { get viewer() { return viewer; }, receive, link };
+}
+
+// the page: config in a JSON script, the shell in #viewer
+if (typeof document !== "undefined" && document.getElementById("protoboard-viewer-config")) {
+  const config = JSON.parse(document.getElementById("protoboard-viewer-config")!.textContent!) as WebviewConfig;
+  (window as unknown as { protoboardViewer: unknown }).protoboardViewer = mountVsCodeViewer(document.getElementById("viewer")!, config);
+}

package/src/vscode/protocol.ts

@@ -0,0 +1,314 @@
+/**
+ * The messages between the VS Code extension and its viewer webview (the
+ * VS Code shell, ./Shell.tsx). One viewer editor tab is one webview showing
+ * one module of a project; the bundle and live rebuilds come from the
+ * project's `protoboard dev` server, everything else (selection, sources,
+ * artifacts, new tabs, layout saving) goes through the extension.
+ *
+ * No React and no VS Code API here: the extension imports this file too.
+ */
+
+/** The viewer's own host messages, as the extension sends them (uhd-viewer's protocol). */
+export type ViewerCommand =
+  | { type: "uhd-viewer:focus"; path: string }
+  | { type: "uhd-viewer:select"; ids: string[]; reveal?: boolean }
+  | { type: "uhd-viewer:drill"; path: string }
+  | { type: "uhd-viewer:setView"; view: "diagram" | "3d" };
+
+export interface ViewerSelection {
+  kind: "node" | "link";
+  id: string;
+  defId?: string;
+  /** Modules selected together (two or more, paths from the root); `id` is the first (QA B10). */
+  ids?: string[];
+}
+
+/** As in uhd-viewer's host contract (`LinkLayout`). */
+export interface LinkLayout {
+  waypoints?: [number, number][];
+  labelT?: number;
+  labelFlip?: boolean;
+  tabT?: number;
+  tabFlip?: boolean;
+}
+
+/** As in uhd-viewer's host contract (`ViewerLayout`): both maps keyed by drill level ("" = top). */
+export interface ViewerLayout {
+  positions: Record<string, Record<string, { x: number; y: number }>>;
+  links: Record<string, Record<string, LinkLayout>>;
+}
+
+/** Where every node and edge of the diagram on screen is drawn (as the dev server's layout route takes it). */
+export interface LayoutSnapshot {
+  nodes: Record<string, { x: number; y: number }>;
+  edges: string[];
+}
+
+/** What the page starts with (a JSON script in the page). */
+export interface WebviewConfig {
+  /** The module the tab shows: its instance path ("" is the root system). */
+  path: string;
+  /** The view the tab opens on (`diagram`, `3d`, or a registry view id). */
+  view: string;
+  /** The extension's media folder as the webview reaches it, no trailing slash. */
+  media: string;
+  /** The dev server, when it is already known. */
+  dev?: DevEndpoint;
+  /** A layout the tab had (a restored backup or unsaved edits). */
+  layout?: ViewerLayout;
+  /** What the view was opened with (the pair view's `link`, `a`, `b`), as `ViewProps.params`. */
+  params?: Record<string, string>;
+  /** The source file of the module the tab opens on, when the extension knows it already. */
+  source?: ModuleSource;
+}
+
+/** The file a module is written in: project-relative, with the line of its definition when the build records it. */
+export interface ModuleSource {
+  file: string;
+  line?: number;
+}
+
+/** A view of the diagram, as uhd-viewer's host contract has it (`ViewerViewport`). */
+export interface ViewerViewport {
+  x: number;
+  y: number;
+  zoom: number;
+}
+
+export interface DevEndpoint {
+  /** The dev server's page URL as the webview reaches it, with a trailing slash. */
+  url: string;
+  session: string;
+}
+
+/** Extension → webview. */
+export type ToWebview =
+  /** The dev server to load from (`null`: there is none; `message` says why). */
+  | { type: "dev"; dev: DevEndpoint | null; message?: string; busy?: boolean }
+  /** A host message for the viewer (focus, select, drill, setView). */
+  | { type: "command"; command: ViewerCommand }
+  /** Show a view of the tab's registry (`diagram`, `3d`, `schematic`, …). */
+  | { type: "showView"; view: string }
+  /** Replace the viewer's layout edits (undo, redo, revert). */
+  | { type: "layout"; layout: ViewerLayout }
+  /** The edits were written to the display file: drop them once the rebuilt bundle carries them. */
+  | { type: "saved" }
+  /** The source file of the module the tab shows now (`null`: none is recorded), for the header's path. */
+  | { type: "source"; path: string; source: ModuleSource | null }
+  /** Test hook: report the page's `--vscode-*` variables and body classes. */
+  | { type: "reportTheme" }
+  /**
+   * The tab's hierarchy panel (PB-1042): show a module's row (`reveal`, with its
+   * instance path), put the keyboard in its filter, open or fold it.
+   */
+  | { type: "hierarchy"; command: HierarchyAction; path?: string }
+  /** Test hook: report the hierarchy panel's rows. */
+  | { type: "reportHierarchy" };
+
+export type HierarchyAction = "reveal" | "filter" | "open" | "close" | "toggle";
+
+/** One row of a tab's hierarchy panel, as the page reports it (tests). */
+export interface HierarchyRowReport {
+  path: string;
+  label: string;
+  kind?: string;
+  selected?: boolean;
+  current?: boolean;
+}
+
+/**
+ * What a hierarchy row tells VS Code for its right-click menu (`data-vscode-context`;
+ * the manifest's `webview/context` menus read it, and the commands get it as their argument).
+ */
+export interface HierarchyRowContext {
+  webviewSection: "hierarchy";
+  /** The module's instance path ("" is the root). */
+  pbPath: string;
+  pbKind: string;
+  pbDefId: string;
+  /** It has a level of its own (Open in New Tab). */
+  pbLevel: boolean;
+  /** Its definition lists artifacts. */
+  pbArtifacts: boolean;
+  preventDefaultContextMenuItems: true;
+}
+
+/** A command's argument when it comes from a hierarchy row's menu: the row's context with the webview's id; anything else is undefined. */
+export function hierarchyRowArg(v: unknown): { path: string; defId?: string } | undefined {
+  if (!obj(v) || v.webviewSection !== "hierarchy" || !str(v.pbPath)) return undefined;
+  return { path: v.pbPath, ...(str(v.pbDefId) && v.pbDefId ? { defId: v.pbDefId } : {}) };
+}
+
+/** Webview → extension. */
+export type FromWebview =
+  /** The page runs. The extension answers every one with where the dev server is (`dev`): a page that loaded again asks again. */
+  | { type: "ready" }
+  /** A line for the extension's log (Protoboard: Show Log): what the page tried to reach and the error it got. */
+  | { type: "log"; level: "info" | "warn" | "error"; message: string }
+  /** The buttons of the tab's dev server message: find or start the server again, reload the window, show the log. */
+  | { type: "devAction"; action: DevAction }
+  /** The viewer's events: ready, selectionChanged, openSource, openArtifact, openModule, openPair. */
+  | { type: "event"; event: ViewerEvent }
+  /** What the tab shows now: the level, its label, the view, how many nodes the diagram draws. */
+  | {
+      type: "state";
+      path: string;
+      label: string;
+      view: string;
+      nodes: number;
+      views: { id: string; title: string }[];
+      error?: string;
+      /** Definitions the bundle names and does not hold (drawn as placeholders). */
+      missing?: number;
+      /** The module the tab is on when it is not the level shown: a part with nothing inside, opened as a tab (its `label` is the part's). */
+      at?: string;
+    }
+  /** The layout edits changed (`dirty`: edits beyond what the display file holds). */
+  | { type: "edit"; layout: ViewerLayout; snapshot?: LayoutSnapshot }
+  /** Open a view of a module as its own editor tab (`params` as the view takes them). */
+  | { type: "openView"; view: string; path: string; params?: Record<string, string> }
+  | { type: "notify"; message: string; severity?: "info" | "warning" | "error" }
+  /** The header's path of the module in view: open its file, show it in the Explorer, or copy its path. */
+  | { type: "source"; action: SourceAction }
+  | { type: "theme"; vars: Record<string, string>; classes: string[]; themeId?: string }
+  /** The hierarchy panel's rows (`reportHierarchy`), whether it is open, and the tab's width in CSS pixels. */
+  | { type: "hierarchy"; open: boolean; rows: HierarchyRowReport[]; width?: number };
+
+export type SourceAction = "open" | "reveal" | "copy" | "copyRelative";
+const SOURCE_ACTIONS: readonly SourceAction[] = ["open", "reveal", "copy", "copyRelative"];
+
+/** `signIn`, `signInDevice`, `signOut` and `checkAccount` are account buttons a page may show (Fetch Parts asks for a sign-in). */
+export type DevAction = "retry" | "reload" | "showLog" | "signIn" | "signInDevice" | "signOut" | "checkAccount" | "fetchParts";
+const DEV_ACTIONS: readonly DevAction[] = ["retry", "reload", "showLog", "signIn", "signInDevice", "signOut", "checkAccount", "fetchParts"];
+
+export type ViewerEvent =
+  | { type: "uhd-viewer:ready" }
+  | { type: "uhd-viewer:selectionChanged"; selection: ViewerSelection | null }
+  | { type: "uhd-viewer:openSource"; defId: string; instancePath?: string }
+  | { type: "uhd-viewer:openArtifact"; defId: string; artifactId: string }
+  | { type: "uhd-viewer:openModule"; path: string }
+  | { type: "uhd-viewer:openPair"; linkId: string; a: string; b: string }
+  /** INSPECT in a module's context menu: the Protoboard Inspector, in front and focused. */
+  | { type: "uhd-viewer:inspect"; path: string; defId?: string };
+
+const str = (v: unknown): v is string => typeof v === "string";
+const obj = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
+
+/** An empty layout: no edits. */
+export const emptyLayout = (): ViewerLayout => ({ positions: {}, links: {} });
+
+/** A layout holds edits when any level has a moved node or an edited link. */
+export function hasEdits(layout: ViewerLayout | undefined): boolean {
+  if (!layout) return false;
+  return Object.values(layout.positions ?? {}).some((l) => Object.keys(l ?? {}).length > 0) || Object.values(layout.links ?? {}).some((l) => Object.keys(l ?? {}).length > 0);
+}
+
+function parseLayout(v: unknown): ViewerLayout | undefined {
+  if (!obj(v) || !obj(v.positions) || !obj(v.links)) return undefined;
+  for (const level of Object.values(v.positions)) {
+    if (!obj(level)) return undefined;
+    for (const p of Object.values(level)) if (!obj(p) || typeof p.x !== "number" || typeof p.y !== "number") return undefined;
+  }
+  for (const level of Object.values(v.links)) if (!obj(level) || !Object.values(level).every(obj)) return undefined;
+  return v as unknown as ViewerLayout;
+}
+
+function parseSnapshot(v: unknown): LayoutSnapshot | undefined {
+  if (!obj(v) || !obj(v.nodes) || !Array.isArray(v.edges) || !v.edges.every(str)) return undefined;
+  for (const p of Object.values(v.nodes)) if (!obj(p) || typeof p.x !== "number" || typeof p.y !== "number") return undefined;
+  return v as unknown as LayoutSnapshot;
+}
+
+/** A view's params: a few short strings by name, nothing else. */
+export function parseParams(v: unknown): Record<string, string> | undefined {
+  if (!obj(v)) return undefined;
+  const out: Record<string, string> = {};
+  for (const [k, x] of Object.entries(v)) if (/^[a-z][a-zA-Z0-9]{0,31}$/.test(k) && str(x) && x.length <= 512) out[k] = x;
+  return Object.keys(out).length && Object.keys(out).length <= 8 ? out : undefined;
+}
+
+function parseEvent(v: unknown): ViewerEvent | undefined {
+  if (!obj(v)) return undefined;
+  switch (v.type) {
+    case "uhd-viewer:ready":
+      return { type: v.type };
+    case "uhd-viewer:selectionChanged": {
+      const s = v.selection;
+      if (s === null || s === undefined) return { type: v.type, selection: null };
+      if (!obj(s) || (s.kind !== "node" && s.kind !== "link") || !str(s.id)) return undefined;
+      const ids = Array.isArray(s.ids) ? s.ids.filter(str).slice(0, 500) : [];
+      return { type: v.type, selection: { kind: s.kind, id: s.id, ...(str(s.defId) ? { defId: s.defId } : {}), ...(ids.length > 1 ? { ids } : {}) } };
+    }
+    case "uhd-viewer:openSource":
+      return str(v.defId) ? { type: v.type, defId: v.defId, ...(str(v.instancePath) ? { instancePath: v.instancePath } : {}) } : undefined;
+    case "uhd-viewer:openArtifact":
+      return str(v.defId) && str(v.artifactId) ? { type: v.type, defId: v.defId, artifactId: v.artifactId } : undefined;
+    case "uhd-viewer:openModule":
+      return str(v.path) ? { type: v.type, path: v.path } : undefined;
+    case "uhd-viewer:openPair":
+      return str(v.linkId) && str(v.a) && str(v.b) ? { type: v.type, linkId: v.linkId, a: v.a, b: v.b } : undefined;
+    case "uhd-viewer:inspect":
+      return str(v.path) ? { type: v.type, path: v.path, ...(str(v.defId) ? { defId: v.defId } : {}) } : undefined;
+    default:
+      return undefined;
+  }
+}
+
+/** A message from the webview, checked field by field; anything else is undefined. */
+export function parseFromWebview(data: unknown): FromWebview | undefined {
+  if (!obj(data)) return undefined;
+  switch (data.type) {
+    case "ready":
+      return { type: "ready" };
+    case "log": {
+      if (!str(data.message)) return undefined;
+      const level = data.level === "warn" || data.level === "error" ? data.level : "info";
+      return { type: "log", level, message: data.message.slice(0, 2000) };
+    }
+    case "devAction":
+      return (DEV_ACTIONS as readonly unknown[]).includes(data.action) ? { type: "devAction", action: data.action as DevAction } : undefined;
+    case "event": {
+      const event = parseEvent(data.event);
+      return event && { type: "event", event };
+    }
+    case "state": {
+      if (!str(data.path) || !str(data.label) || !str(data.view) || typeof data.nodes !== "number") return undefined;
+      const views = Array.isArray(data.views) ? data.views.filter((v): v is { id: string; title: string } => obj(v) && str(v.id) && str(v.title)).map((v) => ({ id: v.id, title: v.title })) : [];
+      return { type: "state", path: data.path, label: data.label, view: data.view, nodes: data.nodes, views, ...(str(data.error) ? { error: data.error } : {}), ...(typeof data.missing === "number" && data.missing > 0 ? { missing: data.missing } : {}), ...(str(data.at) && data.at ? { at: data.at } : {}) };
+    }
+    case "edit": {
+      const layout = parseLayout(data.layout);
+      if (!layout) return undefined;
+      const snapshot = data.snapshot === undefined ? undefined : parseSnapshot(data.snapshot);
+      return { type: "edit", layout, ...(snapshot ? { snapshot } : {}) };
+    }
+    case "openView": {
+      if (!str(data.view) || !str(data.path)) return undefined;
+      const params = parseParams(data.params);
+      return { type: "openView", view: data.view, path: data.path, ...(params ? { params } : {}) };
+    }
+    case "notify": {
+      if (!str(data.message)) return undefined;
+      const severity = data.severity === "warning" || data.severity === "error" || data.severity === "info" ? data.severity : undefined;
+      return { type: "notify", message: data.message, ...(severity ? { severity } : {}) };
+    }
+    case "source":
+      return (SOURCE_ACTIONS as readonly unknown[]).includes(data.action) ? { type: "source", action: data.action as SourceAction } : undefined;
+    case "theme": {
+      if (!obj(data.vars) || !Array.isArray(data.classes)) return undefined;
+      const vars: Record<string, string> = {};
+      for (const [k, v] of Object.entries(data.vars)) if (str(v) && k.startsWith("--vscode-")) vars[k] = v;
+      return { type: "theme", vars, classes: data.classes.filter(str), ...(str(data.themeId) ? { themeId: data.themeId } : {}) };
+    }
+    case "hierarchy": {
+      if (typeof data.open !== "boolean" || !Array.isArray(data.rows)) return undefined;
+      const rows = data.rows
+        .filter((r): r is Record<string, unknown> => obj(r) && str(r.path) && str(r.label))
+        .slice(0, 5000)
+        .map((r) => ({ path: r.path as string, label: r.label as string, ...(str(r.kind) ? { kind: r.kind } : {}), ...(r.selected === true ? { selected: true } : {}), ...(r.current === true ? { current: true } : {}) }));
+      return { type: "hierarchy", open: data.open, rows, ...(typeof data.width === "number" && Number.isFinite(data.width) ? { width: data.width } : {}) };
+    }
+    default:
+      return undefined;
+  }
+}

package/src/vscode/styles.css

@@ -0,0 +1,43 @@
+/* The VS Code shell's stylesheet: Tailwind 4 utilities over the viewer's token
+ * theme, no Preflight (the viewer's rules set their own base). */
+@layer theme, base, components, utilities;
+@import "tailwindcss/theme.css" layer(theme);
+@import "tailwindcss/utilities.css" layer(utilities);
+@import "@deltarobotics/uhd-viewer/tailwind-theme.css";
+@source "./";
+@source "../Logo.tsx";
+@source "../../../views/src";
+
+/* Outside the layers on purpose: VS Code puts its own default webview styles
+ * (body padding, scrollbars) unlayered at the top of the page, and these must win. */
+html,
+body {
+  height: 100%;
+  margin: 0;
+  padding: 0;
+  overflow: hidden;
+  background: var(--vscode-editor-background);
+  scrollbar-color: auto;
+}
+#viewer {
+  height: 100vh;
+}
+/* the shell's root fills the tab */
+#viewer > .uhd-root {
+  height: 100%;
+}
+
+/* an editor tab is no place for a link out of VS Code */
+.pb-vscode .react-flow__attribution {
+  display: none;
+}
+
+/* the dev server message's main button: VS Code's own button colours (orange only under a Protoboard theme, which sets them) */
+.pb-vscode .pb-dev-primary {
+  background: var(--vscode-button-background);
+  color: var(--vscode-button-foreground);
+  border-color: var(--vscode-button-border, transparent);
+}
+.pb-vscode .pb-dev-primary:hover {
+  background: var(--vscode-button-hoverBackground, var(--vscode-button-background));
+}

package/src/vscode/tab-module.ts

@@ -0,0 +1,18 @@
+/** No React and no VS Code API here: the extension's tests import this file too. */
+
+/**
+ * The module a tab is on, for its name, its title and its source file: the
+ * level the viewer shows, or, for a tab opened on a part with nothing inside
+ * (which has no level of its own, so the viewer shows the level that holds
+ * it), that part. A tab is never named after the parent of what it was
+ * opened on.
+ */
+export function tabModule(drill: readonly string[], startPath: string, levelLabel: string, nodes: readonly { id: string; label: string }[]): { path: string; label: string; part: boolean } {
+  const level = drill.join("/");
+  const start = startPath ? startPath.split("/") : [];
+  const below = start.length > drill.length && drill.every((d, i) => start[i] === d);
+  if (!below) return { path: level, label: levelLabel, part: false };
+  const local = start.slice(drill.length).join("/");
+  const node = nodes.find((n) => n.id === local);
+  return { path: startPath, label: node?.label ?? start[start.length - 1], part: true };
+}

package/src/vscode/tabs-fit.ts

@@ -0,0 +1,26 @@
+/**
+ * Which of a viewer tab's view tabs fit its header (B8), from the widths the
+ * shell measures: all with their titles, all as icons, or the first few as
+ * icons and a More menu for the rest. No DOM here: the tests call it.
+ */
+export function fitTabs(full: number[], compact: number[], avail: number, activeIndex: number, more = 34, gap = 2): { compact: boolean; shown: number[] } {
+  const total = (ws: number[]) => ws.reduce((a, w) => a + w, 0) + gap * Math.max(0, ws.length - 1);
+  const all = full.map((_, i) => i);
+  if (total(full) <= avail) return { compact: false, shown: all };
+  if (total(compact) <= avail) return { compact: true, shown: all };
+  const shown: number[] = [];
+  let used = more;
+  for (const i of all) {
+    if (used + compact[i] + gap > avail) break;
+    shown.push(i);
+    used += compact[i] + gap;
+  }
+  // the active tab is always one of those shown: it takes the last place
+  if (activeIndex >= 0 && !shown.includes(activeIndex)) {
+    if (shown.length) shown.pop();
+    shown.push(activeIndex);
+    shown.sort((a, b) => a - b);
+  }
+  return { compact: true, shown };
+}
+