@protoboardai/web-viewer 0.0.0-stage → 0.2.0

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@protoboardai/web-viewer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Protoboard's shells over the viewer stack: the browser shell (`protoboard dev`: the Protoboard theme, view tabs from the view registry, its own inspector, hierarchy and DRC) and the VS Code shell (one viewer editor tab: VS Code's theme, no inspector or DRC of its own)",
+  "license": "Apache-2.0",
+  "author": "Delta Robotics, Inc.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Delta-Robotics-Inc/protoboard-stack.git",
+    "directory": "packages/web-viewer"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./dist/*": "./dist/*",
+    "./package.json": "./package.json",
+    "./vscode": "./src/vscode/index.ts",
+    "./vscode/protocol": "./src/vscode/protocol.ts"
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vite build && vite build -c vite.vscode.config.ts",
+    "prepack": "npm run build",
+    "build:vscode": "vite build -c vite.vscode.config.ts"
+  },
+  "dependencies": {
+    "@deltarobotics/uhd-viewer": "^0.2.0",
+    "@protoboardai/views": "^0.2.0",
+    "@radix-ui/react-scroll-area": "^1.2.18",
+    "@xyflow/react": "^12.12.0",
+    "lucide-react": "^1.48.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "three": "^0.180.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.3.3",
+    "@types/react-dom": "^19.2.3",
+    "tailwindcss": "^4.3.3",
+    "vite": "^8.3.1"
+  }
+}

package/src/Logo.tsx

@@ -0,0 +1,24 @@
+/**
+ * The Protoboard mark (the "0" of PR0TOBOARD, PB-916) and wordmark. Its
+ * colour is the theme's accent: orange in the Protoboard theme, the host's
+ * accent anywhere else (PB-900: the brand colour is never hard-coded, not
+ * even here).
+ */
+import { MARK_PATH } from "./logo-mark.js";
+
+export function Logo({ compact = false }: { compact?: boolean }) {
+  return (
+    <span className="flex h-8 shrink-0 items-center gap-2 px-1.5 select-none" aria-label="Protoboard">
+      <svg aria-hidden width="18" height="18" viewBox="0 0 24 24" className="text-accent">
+        <path fill="currentColor" d={MARK_PATH} />
+      </svg>
+      {!compact && <span className="font-label text-[13px] leading-none tracking-[0.08em] text-fg max-[900px]:hidden">PROTOBOARD</span>}
+    </span>
+  );
+}
+
+/** The mark as a standalone SVG in one colour (the page's favicon, in the theme's accent). */
+export function markSvg(color: string): string {
+  const c = color.replace(/[^#a-zA-Z0-9(),.% ]/g, "");
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24"><path fill="${c}" d="${MARK_PATH}"/></svg>`;
+}

package/src/Shell.tsx

@@ -0,0 +1,313 @@
+/**
+ * The web shell: Protoboard's browser viewer over the viewer stack. A floating
+ * header with the logo, the level's breadcrumb, the view tabs the registry
+ * offers for the focused module (the drilled level), the active view's tools
+ * and the panel toggles; the hierarchy at the left (PB-1042: the module tree,
+ * synced with the canvas, as in a VS Code viewer tab); the view; and its own
+ * inspector and DRC (the viewer's panels). The VS Code shell keeps those in
+ * native views instead (docs/specs/viewer-stack.md).
+ */
+import { useEffect, useMemo, useRef, useState, useSyncExternalStore, type CSSProperties } from "react";
+import {
+  Icon,
+  IconButton,
+  ThemeProvider,
+  ToolbarSeparator,
+  HierarchyToggle,
+  UhdViewer,
+  ViewerHierarchy,
+  ViewerInspector,
+  ViewerNodeMenu,
+  applyTheme,
+  cx,
+  tokenColor,
+  useTheme,
+  useViewer,
+  type HierarchyCommand,
+  type HierarchyPanelState,
+  type UhdViewerOptions,
+} from "@deltarobotics/uhd-viewer/components";
+import type { ResolvedView } from "@protoboardai/core";
+import { PartStatusStyles, PartsDataProvider, PlannedView, ViewIcon, ViewRegistry, createViewRegistry, nodeMarks, registerContributedViews, themeAdapterFor, type HostAdapter, type PartTrust, type PartsData, type ViewDefinition } from "@protoboardai/views";
+import { Logo, markSvg } from "./Logo.js";
+
+export interface WebViewerOptions extends UhdViewerOptions {
+  /** `protoboard-dark` (default), `protoboard-light`, `protoboard-system`, `vscode`, `default-dark`, `default-light`. */
+  themeChoice?: string;
+  /** Views the project's extensions declare (core's resolveViews), added to the built-in ones. */
+  views?: ResolvedView[];
+  /** A registry of the host's own (default: the built-in views plus `views`). */
+  registry?: ViewRegistry;
+  /** The viewer's requests for the pair view (`mountWebViewer` wires them; `open` events with `{ linkId, a, b }`). */
+  pairRequests?: EventTarget;
+  /** The library and BOM tabs' data (`createDevPartsData` for `protoboard dev`); without it they say it is missing. */
+  partsData?: PartsData;
+  /**
+   * Every definition's part status by id (PB-932; the dev server's state):
+   * the dot on a module in the diagram takes its colour (gray local, yellow
+   * unverified, green verified, blue official) and says what it means.
+   */
+  partStatus?: Record<string, { trust: PartTrust; basis?: string; blank?: boolean }>;
+}
+
+const THEME_KEY = "protoboard-web:theme";
+/** The hierarchy panel's open rows, width and fold: per browser tab (session storage), as a VS Code tab keeps them per tab. */
+const HIERARCHY_KEY = "protoboard-web:hierarchy";
+
+function keptHierarchy(): unknown {
+  try {
+    return JSON.parse(sessionStorage.getItem(HIERARCHY_KEY) ?? "null") ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function keepHierarchy(state: HierarchyPanelState) {
+  try {
+    sessionStorage.setItem(HIERARCHY_KEY, JSON.stringify(state));
+  } catch {
+    /* storage unavailable: the panel's state lasts this visit */
+  }
+}
+
+/** Views with no module tree to follow: the library and the BOM are the project's, not a level's. */
+const NO_HIERARCHY = new Set(["library", "bom"]);
+
+function storedTheme(): string | null {
+  try {
+    return localStorage.getItem(THEME_KEY);
+  } catch {
+    return null;
+  }
+}
+
+/** The theme: `themeChoice` when the page names one, else the viewer's last pick, else Protoboard dark. */
+function useThemeChoice(given?: string): [string, (next: string) => void] {
+  const [picked, setPicked] = useState<string | null>(() => storedTheme());
+  const choice = given ?? picked ?? "protoboard-dark";
+  const set = (next: string) => {
+    setPicked(next);
+    try {
+      localStorage.setItem(THEME_KEY, next);
+    } catch {
+      /* storage unavailable: the choice lasts this visit */
+    }
+  };
+  return [choice, set];
+}
+
+export function WebShell(props: WebViewerOptions) {
+  const [choice, setChoice] = useThemeChoice(props.themeChoice);
+  const adapter = useMemo(() => themeAdapterFor(choice), [choice]);
+  // the viewer knows marks, not parts: the status becomes a tone and a tooltip here
+  const marks = useMemo(() => nodeMarks(props.partStatus), [props.partStatus]);
+  return (
+    <ThemeProvider adapter={adapter} className="pb-web">
+      <DocumentTheme />
+      <PartStatusStyles />
+      <PartsDataProvider data={props.partsData ?? null}>
+        <UhdViewer {...props} nodeMarks={props.nodeMarks ?? marks}>
+          <Shell views={props.views} registry={props.registry} pairRequests={props.pairRequests} theme={choice} onTheme={props.themeChoice ? undefined : setChoice} />
+        </UhdViewer>
+      </PartsDataProvider>
+    </ThemeProvider>
+  );
+}
+
+/**
+ * The shell owns its page: the theme's tokens go on the document too (so the
+ * page behind the viewer, overscroll included, has the theme's background,
+ * not the stylesheet's dark default), and the tab's icon is the mark in the
+ * theme's accent (the page's own icon is neutral: no hard-coded brand colour).
+ */
+function DocumentTheme() {
+  const { theme, root } = useTheme();
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+    const html = document.documentElement;
+    const undo = applyTheme(html, theme);
+    html.style.background = "var(--uhd-background)";
+    return () => {
+      undo();
+      html.style.background = "";
+    };
+  }, [theme]);
+  useEffect(() => {
+    if (typeof document === "undefined" || !root) return;
+    const link = document.querySelector<HTMLLinkElement>('link[rel~="icon"]');
+    if (!link) return;
+    link.href = `data:image/svg+xml,${encodeURIComponent(markSvg(tokenColor(root, "accent", "#888888")))}`;
+  }, [theme, root]);
+  return null;
+}
+
+function useRegistry(views: ResolvedView[] | undefined, given?: ViewRegistry): ViewRegistry {
+  const registry = useMemo(() => {
+    if (given) return given;
+    const r = createViewRegistry();
+    if (views?.length) registerContributedViews(r, views);
+    return r;
+  }, [views, given]);
+  // re-render when views register later (an extension's component arriving)
+  useSyncExternalStore(
+    (l) => registry.subscribe(l),
+    () => registry.list().length + registry.list().filter((v) => v.status === "ready").length * 1000,
+  );
+  return registry;
+}
+
+/** Space the floating header covers at the top of the view (the viewer's floating cards sit below it). */
+const INSETS = { "--uhd-inset-top": "44px", "--uhd-inset-left": "0px" } as CSSProperties;
+
+function Shell({ views, registry: given, pairRequests, theme, onTheme }: { views?: ResolvedView[]; registry?: ViewRegistry; pairRequests?: EventTarget; theme: string; onTheme?: (t: string) => void }) {
+  const c = useViewer();
+  const registry = useRegistry(views, given);
+  const path = c.drill.join("/");
+  const tabs = registry.forModule(c.levelDef, c.source.bundle, path);
+  // a domain tab (schematic, BOM, …) when one is open; the viewer's own view (diagram, 3D) otherwise
+  const [domain, setDomain] = useState<string | null>(null);
+  // what a domain tab was opened with (the pair view's pair, a board)
+  const [params, setParams] = useState<Record<string, string> | undefined>(undefined);
+  // a host's setView (or anything else that changes the viewer's view) shows that view
+  useEffect(() => setDomain(null), [c.view]);
+  const wanted = domain ?? c.view;
+  const active = tabs.find((t) => t.id === wanted) ?? tabs[0];
+  const open = (v: ViewDefinition, with_?: Record<string, string>) => {
+    setParams(with_);
+    if (v.uhd && (v.id === "diagram" || v.id === "3d")) {
+      setDomain(null);
+      c.setView(v.id);
+    } else setDomain(v.id);
+  };
+  // the inspector's pair preview opens the pair tab on that pair
+  useEffect(() => {
+    if (!pairRequests) return;
+    const onOpen = (e: Event) => {
+      const r = (e as CustomEvent<{ linkId: string; a: string; b: string }>).detail;
+      const pair = registry.get("pair");
+      if (pair) open(pair, { link: r.linkId, a: r.a, b: r.b });
+    };
+    pairRequests.addEventListener("open", onOpen);
+    return () => pairRequests.removeEventListener("open", onOpen);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [pairRequests, registry]);
+  const host = useMemo<HostAdapter>(
+    () => ({
+      kind: "web",
+      openSource: c.hostActions.openSource ? (r) => c.hostActions.openSource!(r.defId, r.instancePath) : undefined,
+      openArtifact: c.hostActions.openArtifact ? (r) => c.hostActions.openArtifact!(r.defId, r.artifactId) : undefined,
+      openView: (id, at, with_) => {
+        const v = registry.get(id);
+        if (!v) return;
+        open(v, with_);
+        // the diagram of another level: go there, and select what was asked for
+        if (v.id === "diagram") {
+          if (at !== c.drill.join("/")) c.onGoto({ drill: at ? at.split("/") : [], selection: with_?.select ? { kind: "node", id: with_.select } : null });
+          else if (with_?.select) c.setSelection({ kind: "node", id: with_.select });
+        }
+      },
+      artifactUrl: (defId, filePath) => c.source.resolveArtifact(defId, filePath),
+    }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [c.hostActions, registry, c.source, c.drill],
+  );
+  const View = active?.component ?? PlannedView;
+  const diagram = active?.id === "diagram";
+  const light = theme.endsWith("light");
+  // the hierarchy at the left: kept per browser tab; the header's button opens and folds it
+  const [hierarchyState] = useState(keptHierarchy);
+  const [hierarchyOpen, setHierarchyOpen] = useState<boolean | null>(null);
+  const [hierarchyCommand, setHierarchyCommand] = useState<HierarchyCommand>();
+  const seq = useRef(0);
+  const showHierarchy = !NO_HIERARCHY.has(active?.id ?? "");
+
+  return (
+    <div className="relative h-full overflow-hidden bg-background text-fg" style={INSETS}>
+      <header className="absolute top-1 right-1 left-1 z-50 flex h-10 items-center gap-1 rounded-panel border border-line bg-surface px-1 shadow-panel outline outline-1 -outline-offset-1 outline-contrast">
+        <Logo />
+        <ToolbarSeparator />
+        <HierarchyToggle open={showHierarchy && (hierarchyOpen ?? true)} disabled={!showHierarchy} onClick={() => setHierarchyCommand({ type: "toggle", seq: ++seq.current })} />
+        <ToolbarSeparator />
+        <nav role="tablist" aria-label="Views" className="flex min-w-0 items-center gap-0.5 overflow-x-auto [scrollbar-width:none]">
+          {tabs.map((t) => (
+            <Tab key={t.id} view={t} active={t.id === active?.id} onClick={() => open(t)} />
+          ))}
+        </nav>
+        <ToolbarSeparator />
+        <Breadcrumb />
+        <span className="min-w-2 flex-1" />
+        <ToolbarSeparator />
+        <IconButton icon="panel-right" label="Inspector" pressed={c.panel === "hierarchy"} disabled={!active?.uhd} onClick={() => c.setPanel(c.panel === "hierarchy" ? null : "hierarchy")} />
+        <IconButton
+          icon="shield-check"
+          label={`Design rule checks${c.errors ? ` · ${c.errors} error${c.errors === 1 ? "" : "s"}` : ""}`}
+          pressed={c.panel === "checks"}
+          badge={c.errors || undefined}
+          disabled={!active?.uhd}
+          onClick={() => {
+            c.setSelection(null);
+            c.setPanel(c.panel === "checks" ? null : "checks");
+          }}
+        />
+        {onTheme && <IconButton icon={light ? "moon" : "sun"} label={light ? "Dark theme" : "Light theme"} onClick={() => onTheme(light ? "protoboard-dark" : "protoboard-light")} />}
+      </header>
+      {showHierarchy && <ViewerHierarchy state={hierarchyState} command={hierarchyCommand} onStateChange={keepHierarchy} onOpenChange={setHierarchyOpen} />}
+      <div className="workspace" role="tabpanel" aria-label={active?.title}>
+        {active && <View key={active.id} module={c.levelDef} path={path} bundle={c.source.bundle} host={host} view={active} params={active.uhd ? undefined : params} />}
+        {diagram && <ViewerInspector />}
+      </div>
+      <ViewerNodeMenu />
+    </div>
+  );
+}
+
+function Tab({ view, active, onClick }: { view: ViewDefinition; active: boolean; onClick: () => void }) {
+  const planned = view.status === "planned";
+  return (
+    <button
+      type="button"
+      role="tab"
+      aria-selected={active}
+      data-tooltip={`${view.title}${planned ? " · planned" : ""}${view.description ? `: ${view.description}` : ""}`}
+      onClick={onClick}
+      className={cx(
+        "relative flex h-8 shrink-0 cursor-pointer items-center gap-1.5 rounded-md border border-transparent px-2 font-ui text-[12px] tracking-[-0.01em] transition-colors",
+        active ? "bg-accent-tint text-fg outline outline-1 -outline-offset-1 outline-contrast-active" : "text-fg-muted hover:bg-hover hover:text-fg",
+        planned && !active && "text-fg-faint",
+        "focus-visible:outline focus-visible:outline-1 focus-visible:-outline-offset-1 focus-visible:outline-focus",
+      )}
+    >
+      <ViewIcon name={view.icon} size={15} strokeWidth={1.75} className={active ? "text-accent" : undefined} aria-hidden />
+      <span className="max-[1180px]:hidden">{view.title}</span>
+      {active && <span aria-hidden className="absolute right-2 bottom-0 left-2 h-0.5 rounded-full bg-accent" />}
+    </button>
+  );
+}
+
+function Breadcrumb() {
+  const c = useViewer();
+  const path = c.vm.path;
+  return (
+    <nav aria-label="Level" className="flex min-w-0 shrink items-center gap-0.5 overflow-hidden">
+      {path.map((p, i) => {
+        const current = i === path.length - 1;
+        return (
+          <span key={p.id || "root"} className="flex min-w-0 items-center gap-0.5">
+            {i > 0 && <Icon name="chevron-right" size={12} className="shrink-0 text-fg-faint" aria-hidden />}
+            <button
+              type="button"
+              aria-current={current ? "location" : undefined}
+              onClick={() => c.onNavigate(i)}
+              className={cx(
+                "h-8 max-w-56 cursor-pointer truncate rounded-md px-2 font-ui text-[12px]",
+                current ? "text-fg" : "text-fg-muted hover:bg-hover hover:text-fg",
+              )}
+            >
+              {p.label}
+            </button>
+          </span>
+        );
+      })}
+    </nav>
+  );
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+/**
+ * @protoboardai/web-viewer: Protoboard's browser shell (docs/specs/viewer-stack.md).
+ *
+ *   import { mountWebViewer } from "@protoboardai/web-viewer";  // or dist/web-viewer.js
+ *   const viewer = mountWebViewer(el, { bundleUrl, themeChoice: "protoboard-dark", ...hostCallbacks });
+ *
+ * The handle is the viewer's (`focus`, `select`, `drill`, `setView`, `post`,
+ * `update`): hosts drive it with the same messages as the plain viewer.
+ */
+import "@deltarobotics/uhd-viewer/components.css";
+import "./styles.css";
+import { renderViewer, type ViewerHandle } from "@deltarobotics/uhd-viewer/components";
+import { WebShell, type WebViewerOptions } from "./Shell.js";
+
+export { WebShell, type WebViewerOptions };
+export { createDevPartsData, type DevPartsOptions } from "./partsData.js";
+export type { ViewerHandle };
+
+export function mountWebViewer(element: HTMLElement, options: WebViewerOptions): ViewerHandle {
+  if (!options.bundle && !options.bundleUrl) throw new Error("mountWebViewer: give a bundle or a bundleUrl");
+  // the pair view is a tab of the shell's own: the viewer hands it over (and tells a host too)
+  const pairRequests = new EventTarget();
+  const hostPair = options.onOpenPair;
+  return renderViewer(
+    element,
+    {
+      ...options,
+      pairRequests,
+      onOpenPair: (request) => {
+        pairRequests.dispatchEvent(new CustomEvent("open", { detail: request }));
+        hostPair?.(request);
+      },
+    },
+    WebShell,
+  );
+}

package/src/logo-mark.ts

@@ -0,0 +1,2 @@
+// Generated by packages/vscode-protoboard/scripts/logo-assets.py: the Protoboard "0" mark (PB-916) in a 24 × 24 box.
+export const MARK_PATH = "M8.529 13.629 15.272 6.885C15.348 6.81 15.385 6.715 15.385 6.6C15.385 6.486 15.348 6.39 15.272 6.315L13.815 4.886C13.624 4.695 13.386 4.6 13.101 4.6H10.9C10.614 4.6 10.376 4.695 10.186 4.886L8.529 6.543C8.338 6.733 8.243 6.972 8.243 7.257V13.486C8.243 13.638 8.281 13.714 8.357 13.714C8.414 13.714 8.472 13.686 8.529 13.629ZM10.9 19.4H13.101C13.386 19.4 13.624 19.305 13.815 19.114L15.472 17.457C15.662 17.267 15.757 17.029 15.757 16.743V10.514C15.757 10.362 15.719 10.286 15.643 10.286C15.586 10.286 15.529 10.315 15.472 10.372L8.729 17.115C8.634 17.209 8.586 17.305 8.586 17.4C8.586 17.496 8.634 17.591 8.729 17.685L10.186 19.114C10.376 19.305 10.614 19.4 10.9 19.4ZM6.015 5.372 9.015 2.4C9.243 2.133 9.548 2 9.929 2H14.072C14.433 2 14.738 2.124 14.986 2.372L17.958 5.372C18.224 5.6 18.357 5.905 18.357 6.286V17.714C18.357 18.076 18.224 18.391 17.958 18.657L14.986 21.628C14.738 21.876 14.433 22 14.072 22H9.929C9.548 22 9.243 21.867 9.015 21.6L6.015 18.628C5.767 18.381 5.643 18.076 5.643 17.714V6.286C5.643 5.924 5.767 5.619 6.015 5.372Z";

package/src/partsData.ts

@@ -0,0 +1,80 @@
+/**
+ * The parts views' data from `protoboard dev` (its `/__protoboard/parts/`
+ * routes, packages/cli/src/dev/parts.ts): the library's search and parts,
+ * the project's parts, the bill of materials, and adding a part with the
+ * page's session token.
+ */
+import type { BomModel, LibraryQuery, PartDetailModel, PartPages, PartPricesModel, PartsData, ProjectPartsModel, LibraryPageResult } from "@protoboardai/views";
+
+export interface DevPartsOptions {
+  /** The parts routes' base URL (`…/__protoboard/parts/`), absolute. */
+  base: string;
+  /** The session token writes carry, and the header it goes in. */
+  token?: string;
+  tokenHeader?: string;
+}
+
+export function createDevPartsData(o: DevPartsOptions): PartsData {
+  const base = o.base.endsWith("/") ? o.base : `${o.base}/`;
+  const at = (path: string) => new URL(path, base);
+  const get = async <T>(path: string, params: Record<string, string | undefined> = {}): Promise<T> => {
+    const url = at(path);
+    for (const [k, v] of Object.entries(params)) if (v) url.searchParams.set(k, v);
+    const res = await fetch(url, { cache: "no-store" });
+    const body = (await res.json().catch(() => ({ error: `${path}: ${res.status}` }))) as T & { error?: string };
+    if (!res.ok) throw new Error(body.error ?? `${path}: ${res.status}`);
+    return body;
+  };
+  // thumbnails and models come back as paths relative to the dev page's root: make them absolute here
+  const root = new URL("../../", base);
+  const abs = (u: string | undefined) => (u ? new URL(u, root).href : u);
+  // a part's pages carry pictures the same way
+  const absPages = (p: PartPages): PartPages => ({ ...p, images: p.images.map((i) => ({ ...i, url: abs(i.url)! })), ...(p.cad ? { cad: { ...p.cad, ...(p.cad.preview ? { preview: abs(p.cad.preview) } : {}) } } : {}) });
+  return {
+    async search(q: LibraryQuery, cursor?: string): Promise<LibraryPageResult> {
+      const r = await get<LibraryPageResult>("library", { text: q.text, category: q.category, domain: q.domain, protocol: q.protocol, sort: q.sort, cursor });
+      return { ...r, model: { ...r.model, items: r.model.items.map((x) => ({ ...x, ...(x.thumbnail ? { thumbnail: abs(x.thumbnail) } : {}) })) } };
+    },
+    async part(key: string, revision?: number): Promise<PartDetailModel> {
+      const d = await get<PartDetailModel>("part", { key, revision: revision ? String(revision) : undefined });
+      return { ...d, ...(d.thumbnail ? { thumbnail: abs(d.thumbnail) } : {}), ...(d.model ? { model: abs(d.model) } : {}), ...(d.pages ? { pages: absPages(d.pages) } : {}) };
+    },
+    // asked for when a card first shows a page; a revision never changes, so the views keep what they got
+    async pages(ref) {
+      return absPages(await get<PartPages>("pages", { key: ref.key, revision: ref.revision ? String(ref.revision) : undefined }));
+    },
+    prices: (key) => get<PartPricesModel>("prices", { key }),
+    async vendor(key, kind, revision) {
+      const res = await fetch(at("vendor"), {
+        method: "POST",
+        headers: { "content-type": "application/json", ...(o.token ? { [o.tokenHeader ?? "x-protoboard-dev"]: o.token } : {}) },
+        body: JSON.stringify({ key, kind: kind === "add" ? "add" : "update", revision }),
+      });
+      const body = (await res.json().catch(() => ({}))) as { message?: string; error?: string };
+      if (!res.ok) throw new Error(body.error ?? `vendor: ${res.status}`);
+      return body.message ?? "done";
+    },
+    // pictures come back as paths relative to the dev page's root, like the library's
+    projectParts: async (check?: boolean) => {
+      const r = await get<ProjectPartsModel>("project", { check: check ? "1" : undefined });
+      return { ...r, parts: r.parts.map((p) => ({ ...p, ...(p.thumbnail ? { thumbnail: abs(p.thumbnail) } : {}) })) };
+    },
+    bom: () => get<BomModel>("bom"),
+    async saveBom(change) {
+      const res = await fetch(at("bom"), {
+        method: "POST",
+        headers: { "content-type": "application/json", ...(o.token ? { [o.tokenHeader ?? "x-protoboard-dev"]: o.token } : {}) },
+        body: JSON.stringify(change),
+      });
+      const body = (await res.json().catch(() => ({}))) as { error?: string };
+      if (!res.ok) throw new Error(body.error ?? `bom: ${res.status}`);
+    },
+    async refreshOffers() {
+      const res = await fetch(at("offers"), { method: "POST", headers: { "content-type": "application/json", ...(o.token ? { [o.tokenHeader ?? "x-protoboard-dev"]: o.token } : {}) }, body: "{}" });
+      const body = (await res.json().catch(() => ({}))) as { message?: string; error?: string };
+      if (!res.ok) throw new Error(body.error ?? `offers: ${res.status}`);
+      return body.message ?? "The offers were refreshed.";
+    },
+    openLink: (url) => void window.open(url, "_blank", "noopener"),
+  };
+}

package/src/styles.css

@@ -0,0 +1,46 @@
+/* The web shell's stylesheet: Tailwind 4 utilities over the viewer's token
+ * theme (the same names as the viewer's own components), 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 "../../views/src";
+
+@layer base {
+  html,
+  body {
+    height: 100%;
+    margin: 0;
+  }
+}
+
+/* the parts views' controls start bare (no Preflight): utilities draw them */
+@layer base {
+  .pb-parts,
+  .pb-parts :where(*, ::before, ::after) {
+    box-sizing: border-box;
+  }
+  .pb-parts :where(button, input, select, textarea) {
+    font: inherit;
+    color: inherit;
+    background: none;
+    border: 0 solid;
+    padding: 0;
+    margin: 0;
+  }
+  .pb-parts :where(h1, h2, h3, p, ul, ol) {
+    margin: 0;
+    padding: 0;
+  }
+  .pb-parts :where(ul, ol) {
+    list-style: none;
+  }
+  .pb-parts :where(img, svg) {
+    display: block;
+  }
+  .pb-parts :where(code) {
+    font-family: var(--uhd-font-mono);
+  }
+}