dsh-generative-ui 0.0.0 → 0.0.2

package/src/client/canvas/index.ts

@@ -0,0 +1,255 @@
+/**
+ * Wires the canvas column: watch the transcript for canvas writes, mount the panel when
+ * there are any, unmount when there are none.
+ */
+import { createElement } from "react";
+import { createRoot } from "react-dom/client";
+import { CanvasPanel, type Canvas } from "./CanvasPanel.tsx";
+import { CanvasLauncher } from "./CanvasLauncher.tsx";
+import { PANEL_CSS } from "./panel-css.ts";
+import { collectCanvases, type ToolCallView } from "./collect.ts";
+import { listCanvasIds, readCanvasFile } from "./read.ts";
+import { createColumn, injectStyles, whenFrameReady } from "./mount.ts";
+import { observeTranscript, scheduleSweep } from "../runtime/observe.ts";
+
+export type CanvasHostOptions = {
+  /** Every tool call in the current session, oldest first. */
+  calls: () => readonly ToolCallView[];
+  /** The current session's workspace directory, when it has one. */
+  cwd: () => string | undefined;
+  /** Identity of the current session; dismissals are remembered against it. */
+  sessionId: () => string;
+  /**
+   * Where a canvas's compile failure goes. Optional because a host may have no chat channel;
+   * absent, the error is still painted for the reader and simply reaches nobody else.
+   */
+  onCardError?: (message: string, phase: string) => void;
+  /** A canvas that painted; cancels a deferred error report the next frame made untrue. */
+  onCardRendered?: () => void;
+};
+
+const EMPTY: ReadonlySet<string> = new Set();
+
+/**
+ * A call whose arguments carry executable code rather than a file operation.
+ *
+ * Matched on the argument text, not the tool name, for the same reason `collect.ts` classifies
+ * by shape: the day the host renames `run_code`, a name list stops matching and canvases
+ * silently stop appearing.
+ *
+ * It must also mention the canvases directory. All 29 opaque canvas writes in the corpus do,
+ * even the 27 whose path is built from a variable — and without that clause a session doing
+ * ordinary shell work re-lists once per command (measured: median 0, but one session hit 94).
+ */
+/**
+ * What a sweep would paint, as a string. Equal signatures mean nothing to do.
+ *
+ * The observer fires on every streamed token, so this is what stands between the panel and a
+ * React render per token. `code.length` rather than the code: a growing card changes length on
+ * every frame, which is exactly when it should repaint, and comparing megabytes of source per
+ * token would cost more than the render. The offerable list belongs in it too — closing the
+ * last canvas changes nothing about the visible list, and without it the launcher never paints.
+ */
+export const paintSignature = (canvases: readonly Canvas[], offerable: readonly string[]): string => `${canvases.map((c) => `${c.id}:${c.code.length}:${String(c.streaming)}`).join("|")}#${offerable.join(",")}`;
+
+export const OPAQUE_WRITE = /"(?:code|command)"\s*:[\s\S]*canvases/;
+
+export function mountCanvasHost({ calls, cwd, sessionId, onCardError, onCardRendered }: CanvasHostOptions): { dispose: () => void; show: (id: string) => void } {
+  /**
+   * Canvas bodies re-read from disk, for the ones a patch left stale.
+   *
+   * Keyed by canvas id and versioned by how many mutating calls it has seen, so a further
+   * edit invalidates the entry while repeated sweeps over the same state reuse it. Without
+   * the version the choice is between never refetching and refetching every frame.
+   */
+  const fromFile = new Map<string, { version: number; code?: string }>();
+  const disposers: (() => void)[] = [injectStyles(PANEL_CSS)];
+  /**
+   * Canvases the reader dismissed, per session.
+   *
+   * Closing hides what is on screen without opting out of the feature — a canvas written
+   * afterwards still opens. Keyed by session because ids are only unique within one: a
+   * dismissal must not follow the reader into another conversation, and returning to a
+   * session should find it as they left it.
+   */
+  const dismissed = new Map<string, Set<string>>();
+  /**
+   * Canvases the reader opened from the launcher that this session never wrote.
+   *
+   * A canvas outlives its session, so the launcher offers everything in the workspace —
+   * but those have no tool call to reconstruct them from, and their bodies come off disk.
+   * Keyed by session for the same reason `dismissed` is.
+   */
+  const opened = new Map<string, Set<string>>();
+  /** Bodies of the launcher-opened canvases. Read once: nothing in this session changes them. */
+  const openedCode = new Map<string, string>();
+  /** Every canvas on disk, for the launcher. Refreshed per workspace, not per sweep. */
+  let workspaceIds: readonly string[] = [];
+  let listedFor: string | undefined;
+  /** Settled opaque calls at the time of the last listing — see the sweep for why. */
+  let listedAfter = -1;
+  // `null` until the first paint, so an empty first paint is still a paint. An empty string
+  // would collide with the signature of "no canvases" and skip it.
+  let signature: string | null = null;
+
+  /**
+   * Show a canvas the reader picked, whether or not this session wrote it.
+   *
+   * Defined out here rather than inside the sweep because callers outside the panel reach
+   * it too — the transcript's file links, which would otherwise hand a `.ui4a.tsx` to the
+   * OS file opener.
+   */
+  const show = (id: string): void => {
+    const session = sessionId();
+    dismissed.get(session)?.delete(id);
+    const showing = opened.get(session) ?? new Set<string>();
+    showing.add(id);
+    opened.set(session, showing);
+    signature = null;
+    scheduleSweep();
+  };
+
+  const stopWaiting = whenFrameReady((frameElement) => {
+    const column = createColumn(frameElement);
+    const root = createRoot(column.element);
+    disposers.push(() => root.unmount(), column.remove);
+
+    // `collectCanvases` walks every argument string by hand, which is what makes it correct on a
+    // half-arrived JSON prefix — and it costs 0.16ms per canvas per sweep. The sweep runs on
+    // every transcript mutation, so a session with 34 canvas calls (the corpus maximum) spent
+    // ~5ms per streamed token re-deriving a result that had not changed. Keyed on the calls'
+    // own bytes: a streamed argument grows, so its length moves on every frame that matters and
+    // on none that do not.
+    let callsKey: string | null = null;
+    let collected = collectCanvases([]);
+
+    const paint = () => {
+      const allCalls = calls();
+      const key = `${allCalls.length}:${allCalls.reduce((total, call) => total + call.argsRaw.length + (call.settled ? 1 : 0), 0)}`;
+      if (key !== callsKey) {
+        callsKey = key;
+        collected = collectCanvases(allCalls);
+      }
+      const workspace = cwd();
+      const session = sessionId();
+      const hidden = dismissed.get(session) ?? EMPTY;
+      // The workspace listing backs the launcher. Fetched once per workspace rather than per
+      // sweep — the sweep runs per streamed token, and a directory listing is not free.
+      // A call that ran arbitrary code may have written a canvas without any argument saying
+      // so: 29 canvas writes in the corpus go through `run_code`, and in 27 of them the path is
+      // built from a variable, so nothing in the arguments names the id. `collect.ts` cannot
+      // classify what the arguments do not contain — but the workspace listing already knows,
+      // it just never refreshed. Counting settled opaque calls re-lists once each time one
+      // finishes, which is a directory read per code execution and nothing per streamed token.
+      let opaque = 0;
+      for (const call of allCalls) if (call.settled && OPAQUE_WRITE.test(call.argsRaw)) opaque += 1;
+      if (workspace !== undefined && (workspace !== listedFor || opaque !== listedAfter)) {
+        listedFor = workspace;
+        listedAfter = opaque;
+        void listCanvasIds(workspace).then((ids) => {
+          workspaceIds = ids;
+          signature = null;
+          scheduleSweep();
+        });
+      }
+      const canvases: Canvas[] = collected.canvases
+        .filter((canvas) => !hidden.has(canvas.id))
+        .map((canvas) => {
+          const version = collected.stale.get(canvas.id);
+          // Not patched: the write's own arguments are the canvas, streaming included.
+          if (version === undefined) return canvas;
+          // One entry per canvas covers both states: `code` absent means a read is in
+          // flight, present means it settled. Two collections would only be two things to
+          // keep in sync.
+          const cached = fromFile.get(canvas.id);
+          if (cached?.version === version) return cached.code === undefined ? canvas : { ...canvas, code: cached.code };
+          if (workspace !== undefined) {
+            fromFile.set(canvas.id, { version });
+            void readCanvasFile(workspace, canvas.id).then((code) => {
+              // A miss keeps the entry (with no body) rather than dropping it: deleting it
+              // makes the very next sweep — one per streamed token — fire the same failing
+              // read again, forever. The version already invalidates it when a real change
+              // lands, which is the only thing that could make the answer differ.
+              if (code === null) return;
+              fromFile.set(canvas.id, { version, code });
+              // The body changed underneath the signature, so force the next sweep to paint.
+              signature = null;
+              scheduleSweep();
+            });
+          }
+          // Until it arrives, the previous body still beats an empty panel.
+          return cached?.code === undefined ? canvas : { ...canvas, code: cached.code };
+        });
+
+      // Canvases the reader picked out of the launcher. Their code is not in any tool call,
+      // so it comes off disk once and then stays — nothing this session does can change it.
+      for (const id of opened.get(session) ?? EMPTY) {
+        if (hidden.has(id) || canvases.some((canvas) => canvas.id === id)) continue;
+        const code = openedCode.get(id);
+        if (code !== undefined) canvases.push({ id, code, streaming: false });
+        else if (workspace !== undefined) {
+          openedCode.set(id, "");
+          void readCanvasFile(workspace, id).then((body) => {
+            if (body === null) return;
+            openedCode.set(id, body);
+            signature = null;
+            scheduleSweep();
+          });
+        }
+      }
+
+      // What the launcher can offer: everything on disk, plus anything written this session
+      // whose file has not landed yet. Sorted so the button does not reshuffle between sweeps.
+      const offerable = [...new Set([...workspaceIds, ...collected.canvases.map((canvas) => canvas.id)])].toSorted();
+
+      const next = paintSignature(canvases, offerable);
+      if (next === signature) return;
+      signature = next;
+      if (canvases.length === 0) column.setWidth(0);
+
+      const repaint = () => {
+        signature = null;
+        scheduleSweep();
+      };
+
+      root.render(
+        canvases.length > 0
+          ? createElement(CanvasPanel, {
+              canvases,
+              offerable,
+              cwd: cwd(),
+              onOpen: show,
+              onCardError,
+              onCardRendered,
+              onWidth: column.setWidth,
+              onClose: () => {
+                const hiding = dismissed.get(session) ?? new Set<string>();
+                for (const canvas of canvases) hiding.add(canvas.id);
+                dismissed.set(session, hiding);
+                // Anything opened from the launcher is closed for good rather than left to
+                // reappear on the next sweep: `dismissed` covers the ones with a tool call
+                // behind them, and this covers the ones without.
+                opened.delete(session);
+                repaint();
+              },
+            })
+          : offerable.length > 0
+            ? createElement(CanvasLauncher, {
+                ids: offerable,
+                onOpen: show,
+              })
+            : null,
+      );
+    };
+
+    disposers.push(observeTranscript(paint));
+  });
+
+  disposers.push(stopWaiting);
+  return {
+    dispose: () => {
+      for (const dispose of disposers.toReversed()) dispose();
+    },
+    show,
+  };
+}

package/src/client/canvas/mount.ts

@@ -0,0 +1,91 @@
+/**
+ * Mounts the canvas column into the host's AppFrame.
+ *
+ * There is no additive slot for a whole column: `details` is a single-occupant slot the
+ * conversation already owns, and taking it would remove the tool-details seat declared
+ * inside it. A portal into the frame's own flex row adds a column without contending for
+ * anything — the same shape dsh-better-sidebar uses for its right sidebar.
+ */
+const FRAME = ".pI_x6G_frame, [class*='_frame']";
+const PLUGIN_ID = "dsh-generative-ui";
+
+/**
+ * Injects the panel stylesheet.
+ *
+ * The `data-plugin` attribute is required, not decorative: the client module loader
+ * claims every `style:not([data-plugin])` for whichever plugin is currently
+ * materializing, so an unmarked sheet gets adopted by a stranger and torn out with them.
+ */
+export function injectStyles(css: string): () => void {
+  const style = document.createElement("style");
+  style.setAttribute("data-plugin", PLUGIN_ID);
+  style.setAttribute("data-plugin-css", `${PLUGIN_ID}/panel`);
+  style.textContent = css;
+  document.head.append(style);
+  return () => style.remove();
+}
+
+/**
+ * Resolves the frame element, waiting for it when the shell has not painted yet.
+ * @param onFound - called once with the container; not called if disposed first.
+ */
+export function whenFrameReady(onFound: (frame: HTMLElement) => void): () => void {
+  const found = document.querySelector<HTMLElement>(FRAME);
+  if (found !== null) {
+    onFound(found);
+    return () => {};
+  }
+  const observer = new MutationObserver(() => {
+    const frame = document.querySelector<HTMLElement>(FRAME);
+    if (frame === null) return;
+    observer.disconnect();
+    window.clearTimeout(timer);
+    onFound(frame);
+  });
+  observer.observe(document.body, { subtree: true, childList: true });
+  // The selector tracks a hashed class name, so a host rebuild can invalidate it. Without
+  // this the failure is a canvas panel that silently never appears; one warning turns a
+  // mystery into a starting point.
+  const timer = window.setTimeout(() => {
+    observer.disconnect();
+    console.warn(`[dsh-generative-ui] no AppFrame matched ${FRAME} — canvases cannot mount. The host's layout markup likely changed.`);
+  }, 15_000);
+  return () => {
+    observer.disconnect();
+    window.clearTimeout(timer);
+  };
+}
+
+/**
+ * Creates the panel's host element and makes room for it.
+ *
+ * The frame's own columns are sized to fill the viewport exactly, so an extra flex child
+ * is laid out past the right edge no matter where it is inserted — present in the DOM,
+ * correctly sized, and entirely off screen (that is what the first attempt did). Instead
+ * the panel is fixed to the right edge and the frame is given matching right padding, so
+ * the conversation reflows into the remaining width and nothing overlaps.
+ *
+ * @param frame - the host's AppFrame element.
+ * @param width - the panel's current width in pixels.
+ */
+export function createColumn(frame: HTMLElement): {
+  element: HTMLElement;
+  setWidth: (width: number) => void;
+  remove: () => void;
+} {
+  const element = document.createElement("div");
+  element.setAttribute("data-dgu-canvas-column", "");
+  document.body.append(element);
+  const previousPadding = frame.style.paddingRight;
+  const setWidth = (width: number) => {
+    frame.style.paddingRight = width === 0 ? previousPadding : `${width}px`;
+  };
+  return {
+    element,
+    setWidth,
+    remove: () => {
+      frame.style.paddingRight = previousPadding;
+      element.remove();
+    },
+  };
+}

package/src/client/canvas/panel-css.ts

@@ -0,0 +1,2 @@
+/* Generated from panel.css by scripts/build.ts — edit the .css, not this file. */
+export const PANEL_CSS = "/*\n * The canvas column. Everything visual comes from the host's design tokens, so the panel\n * tracks theme changes for free and never introduces a second palette\n * (docs/web-styling.md: feature packages consume aliases, they do not define colors).\n */\n.dgu-panel {\n  --dgu-panel-width: 420px;\n  position: fixed;\n  top: 0;\n  right: 0;\n  bottom: 0;\n  z-index: 20;\n  display: flex;\n  flex-direction: column;\n  width: var(--dgu-panel-width);\n  background: var(--dsw-alias-bg-base);\n  border-left: 1px solid var(--dsw-alias-border-l1);\n  color: var(--dsw-alias-label-primary);\n  font-family: var(--dsw-font-family);\n  overflow: hidden;\n}\n\n.dgu-header {\n  display: flex;\n  align-items: center;\n  gap: 8px;\n  padding: 0 8px 0 14px;\n  height: 44px;\n  flex: none;\n}\n\n/* No hairline under either the title bar or the tab strip, and that is the host's own language,\n * not a preference: measured on dsh web's conversation header (`wSkVaW_header`), the computed\n * `border-bottom-color` is `rgba(0, 0, 0, 0)` on a transparent background with no box-shadow —\n * it separates itself from the scroll area with 76px of height and nothing else. Two `border-l1`\n * rules here put lines across a panel that sits inside that same frame, which reads as chrome the\n * app does not otherwise have. */\n\n.dgu-title {\n  font-size: var(--dsw-font-s-14-font-size);\n  line-height: var(--dsw-font-s-14-line-height);\n  font-weight: var(--dsw-font-s-strong-14-font-weight);\n  white-space: nowrap;\n  overflow: hidden;\n  text-overflow: ellipsis;\n}\n\n.dgu-spacer {\n  flex: 1 1 auto;\n}\n\n.dgu-icon-button {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  width: 28px;\n  height: 28px;\n  flex: none;\n  border: 0;\n  border-radius: 6px;\n  background: transparent;\n  color: var(--dsw-alias-label-secondary);\n  cursor: pointer;\n}\n.dgu-icon-button:hover {\n  background: var(--dsw-alias-interactive-bg-hover);\n  color: var(--dsw-alias-label-primary);\n}\n.dgu-icon-button:focus-visible {\n  outline: 2px solid var(--dsw-alias-state-business-primary);\n  outline-offset: -2px;\n}\n\n/* Tabs only appear from the second canvas on: one canvas needs no chooser. */\n.dgu-tabs {\n  display: flex;\n  gap: 2px;\n  padding: 6px 8px;\n  flex: none;\n  overflow-x: auto;\n  scrollbar-width: none;\n}\n.dgu-tabs::-webkit-scrollbar {\n  display: none;\n}\n\n.dgu-tab {\n  padding: 4px 10px;\n  border: 0;\n  border-radius: 6px;\n  background: transparent;\n  color: var(--dsw-alias-label-secondary);\n  font-family: inherit;\n  font-size: var(--dsw-font-xs-13-font-size);\n  line-height: var(--dsw-font-xs-13-line-height);\n  white-space: nowrap;\n  cursor: pointer;\n}\n.dgu-tab:hover {\n  background: var(--dsw-alias-interactive-bg-hover);\n}\n.dgu-tab[aria-selected=\"true\"] {\n  background: var(--dsw-specific-sidebar-nav-item-active);\n  color: var(--dsw-alias-label-primary);\n}\n\n/*\n * The canvas owns this space entirely — the panel already provides the frame, so the body\n * adds no padding and no background of its own. Generated UI is told to fill it.\n */\n.dgu-body {\n  flex: 1 1 auto;\n  min-height: 0;\n  overflow: auto;\n}\n.dgu-body > * {\n  min-height: 100%;\n}\n\n.dgu-empty {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  height: 100%;\n  padding: 24px;\n  text-align: center;\n  color: var(--dsw-alias-label-secondary);\n  font-size: var(--dsw-font-xs-13-font-size);\n  line-height: var(--dsw-font-xs-13-line-height);\n}\n\n/* Invisible hit strip, matching how the host draws its own sidebar boundary. */\n.dgu-resize {\n  position: absolute;\n  top: 0;\n  bottom: 0;\n  width: 8px;\n  cursor: col-resize;\n  z-index: 1;\n}\n.dgu-resize:hover,\n.dgu-resize[data-dragging] {\n  /* The foreground token on purpose: this wants a wash that contrasts with whatever is\n     behind it, and `brand-primary` tracks the body text colour in both themes. */\n  background: var(--dsw-alias-brand-primary);\n  opacity: 0.12;\n}\n\n/*\n * Sits where the panel's left edge was, so reopening is a click in the place it closed\n * from. Fixed like the panel because it shares the same \"outside the frame\" problem —\n * an extra flex child in the frame's row lands off screen.\n */\n.dgu-launcher-dock {\n  position: fixed;\n  top: 50%;\n  right: 0;\n  transform: translateY(-50%);\n  z-index: 20;\n  display: flex;\n  align-items: center;\n  gap: 6px;\n}\n\n.dgu-launcher {\n  display: inline-flex;\n  align-items: center;\n  gap: 4px;\n  padding: 8px 6px;\n  border: 1px solid var(--dsw-alias-border-l1);\n  border-right: 0;\n  border-radius: 8px 0 0 8px;\n  background: var(--dsw-alias-bg-layer-1);\n  color: var(--dsw-alias-label-secondary);\n  font-family: var(--dsw-font-family);\n  font-size: var(--dsw-font-xs-13-font-size);\n  line-height: var(--dsw-font-xs-13-line-height);\n  cursor: pointer;\n}\n.dgu-launcher:hover {\n  background: var(--dsw-alias-interactive-bg-hover);\n  color: var(--dsw-alias-label-primary);\n}\n.dgu-launcher:focus-visible {\n  outline: 2px solid var(--dsw-alias-state-business-primary);\n  outline-offset: -2px;\n}\n\n.dgu-launcher-count {\n  font-variant-numeric: tabular-nums;\n}\n\n/* Opens leftward: the dock is already against the right edge, so there is nowhere else. */\n.dgu-launcher-menu {\n  display: flex;\n  flex-direction: column;\n  gap: 2px;\n  margin: 0;\n  padding: 4px;\n  max-height: 60vh;\n  overflow-y: auto;\n  list-style: none;\n  border: 1px solid var(--dsw-alias-border-l1);\n  border-radius: 8px;\n  /* A floating surface has to occlude: `bg-layer-1` is a tint over whatever it sits on, so\n     it needs the panel's own opaque ground underneath before the tint reads as a menu. */\n  background: var(--dsw-alias-bg-base);\n  background-image: linear-gradient(var(--dsw-alias-bg-layer-1), var(--dsw-alias-bg-layer-1));\n  box-shadow: 0 8px 24px rgb(0 0 0 / 0.24);\n}\n\n.dgu-launcher-item {\n  display: block;\n  width: 100%;\n  padding: 5px 10px;\n  border: 0;\n  border-radius: 6px;\n  background: transparent;\n  color: var(--dsw-alias-label-primary);\n  font-family: var(--dsw-font-family);\n  font-size: var(--dsw-font-xs-13-font-size);\n  line-height: var(--dsw-font-xs-13-line-height);\n  text-align: left;\n  white-space: nowrap;\n  cursor: pointer;\n}\n.dgu-launcher-item:hover {\n  background: var(--dsw-alias-interactive-bg-hover);\n}\n\n/* Anchors the header's canvas picker; the menu drops below the button. */\n.dgu-picker {\n  position: relative;\n  display: flex;\n}\n\n.dgu-picker-menu {\n  position: absolute;\n  top: calc(100% + 4px);\n  right: 0;\n  z-index: 1;\n}\n";

package/src/client/canvas/panel.css

@@ -0,0 +1,242 @@
+/*
+ * The canvas column. Everything visual comes from the host's design tokens, so the panel
+ * tracks theme changes for free and never introduces a second palette
+ * (docs/web-styling.md: feature packages consume aliases, they do not define colors).
+ */
+.dgu-panel {
+  --dgu-panel-width: 420px;
+  position: fixed;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  z-index: 20;
+  display: flex;
+  flex-direction: column;
+  width: var(--dgu-panel-width);
+  background: var(--dsw-alias-bg-base);
+  border-left: 1px solid var(--dsw-alias-border-l1);
+  color: var(--dsw-alias-label-primary);
+  font-family: var(--dsw-font-family);
+  overflow: hidden;
+}
+
+.dgu-header {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 0 8px 0 14px;
+  height: 44px;
+  flex: none;
+}
+
+/* No hairline under either the title bar or the tab strip, and that is the host's own language,
+ * not a preference: measured on dsh web's conversation header (`wSkVaW_header`), the computed
+ * `border-bottom-color` is `rgba(0, 0, 0, 0)` on a transparent background with no box-shadow —
+ * it separates itself from the scroll area with 76px of height and nothing else. Two `border-l1`
+ * rules here put lines across a panel that sits inside that same frame, which reads as chrome the
+ * app does not otherwise have. */
+
+.dgu-title {
+  font-size: var(--dsw-font-s-14-font-size);
+  line-height: var(--dsw-font-s-14-line-height);
+  font-weight: var(--dsw-font-s-strong-14-font-weight);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.dgu-spacer {
+  flex: 1 1 auto;
+}
+
+.dgu-icon-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  flex: none;
+  border: 0;
+  border-radius: 6px;
+  background: transparent;
+  color: var(--dsw-alias-label-secondary);
+  cursor: pointer;
+}
+.dgu-icon-button:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+  color: var(--dsw-alias-label-primary);
+}
+.dgu-icon-button:focus-visible {
+  outline: 2px solid var(--dsw-alias-state-business-primary);
+  outline-offset: -2px;
+}
+
+/* Tabs only appear from the second canvas on: one canvas needs no chooser. */
+.dgu-tabs {
+  display: flex;
+  gap: 2px;
+  padding: 6px 8px;
+  flex: none;
+  overflow-x: auto;
+  scrollbar-width: none;
+}
+.dgu-tabs::-webkit-scrollbar {
+  display: none;
+}
+
+.dgu-tab {
+  padding: 4px 10px;
+  border: 0;
+  border-radius: 6px;
+  background: transparent;
+  color: var(--dsw-alias-label-secondary);
+  font-family: inherit;
+  font-size: var(--dsw-font-xs-13-font-size);
+  line-height: var(--dsw-font-xs-13-line-height);
+  white-space: nowrap;
+  cursor: pointer;
+}
+.dgu-tab:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+.dgu-tab[aria-selected="true"] {
+  background: var(--dsw-specific-sidebar-nav-item-active);
+  color: var(--dsw-alias-label-primary);
+}
+
+/*
+ * The canvas owns this space entirely — the panel already provides the frame, so the body
+ * adds no padding and no background of its own. Generated UI is told to fill it.
+ */
+.dgu-body {
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow: auto;
+}
+.dgu-body > * {
+  min-height: 100%;
+}
+
+.dgu-empty {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 100%;
+  padding: 24px;
+  text-align: center;
+  color: var(--dsw-alias-label-secondary);
+  font-size: var(--dsw-font-xs-13-font-size);
+  line-height: var(--dsw-font-xs-13-line-height);
+}
+
+/* Invisible hit strip, matching how the host draws its own sidebar boundary. */
+.dgu-resize {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  width: 8px;
+  cursor: col-resize;
+  z-index: 1;
+}
+.dgu-resize:hover,
+.dgu-resize[data-dragging] {
+  /* The foreground token on purpose: this wants a wash that contrasts with whatever is
+     behind it, and `brand-primary` tracks the body text colour in both themes. */
+  background: var(--dsw-alias-brand-primary);
+  opacity: 0.12;
+}
+
+/*
+ * Sits where the panel's left edge was, so reopening is a click in the place it closed
+ * from. Fixed like the panel because it shares the same "outside the frame" problem —
+ * an extra flex child in the frame's row lands off screen.
+ */
+.dgu-launcher-dock {
+  position: fixed;
+  top: 50%;
+  right: 0;
+  transform: translateY(-50%);
+  z-index: 20;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+
+.dgu-launcher {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  padding: 8px 6px;
+  border: 1px solid var(--dsw-alias-border-l1);
+  border-right: 0;
+  border-radius: 8px 0 0 8px;
+  background: var(--dsw-alias-bg-layer-1);
+  color: var(--dsw-alias-label-secondary);
+  font-family: var(--dsw-font-family);
+  font-size: var(--dsw-font-xs-13-font-size);
+  line-height: var(--dsw-font-xs-13-line-height);
+  cursor: pointer;
+}
+.dgu-launcher:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+  color: var(--dsw-alias-label-primary);
+}
+.dgu-launcher:focus-visible {
+  outline: 2px solid var(--dsw-alias-state-business-primary);
+  outline-offset: -2px;
+}
+
+.dgu-launcher-count {
+  font-variant-numeric: tabular-nums;
+}
+
+/* Opens leftward: the dock is already against the right edge, so there is nowhere else. */
+.dgu-launcher-menu {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  margin: 0;
+  padding: 4px;
+  max-height: 60vh;
+  overflow-y: auto;
+  list-style: none;
+  border: 1px solid var(--dsw-alias-border-l1);
+  border-radius: 8px;
+  /* A floating surface has to occlude: `bg-layer-1` is a tint over whatever it sits on, so
+     it needs the panel's own opaque ground underneath before the tint reads as a menu. */
+  background: var(--dsw-alias-bg-base);
+  background-image: linear-gradient(var(--dsw-alias-bg-layer-1), var(--dsw-alias-bg-layer-1));
+  box-shadow: 0 8px 24px rgb(0 0 0 / 0.24);
+}
+
+.dgu-launcher-item {
+  display: block;
+  width: 100%;
+  padding: 5px 10px;
+  border: 0;
+  border-radius: 6px;
+  background: transparent;
+  color: var(--dsw-alias-label-primary);
+  font-family: var(--dsw-font-family);
+  font-size: var(--dsw-font-xs-13-font-size);
+  line-height: var(--dsw-font-xs-13-line-height);
+  text-align: left;
+  white-space: nowrap;
+  cursor: pointer;
+}
+.dgu-launcher-item:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+
+/* Anchors the header's canvas picker; the menu drops below the button. */
+.dgu-picker {
+  position: relative;
+  display: flex;
+}
+
+.dgu-picker-menu {
+  position: absolute;
+  top: calc(100% + 4px);
+  right: 0;
+  z-index: 1;
+}

package/src/client/canvas/read.ts

@@ -0,0 +1,55 @@
+/**
+ * Reads a canvas's current file contents through the plugin's own host route.
+ *
+ * Needed because `edit`-style tool calls carry a patch rather than the file: after one,
+ * the tool-call stream no longer describes the canvas and only the file does.
+ */
+import { CANVAS_READ_PATH } from "../../contract-assets.ts";
+
+/** Monotonic per-read, so no two reads of one canvas can share a cache entry. */
+let readSerial = 0;
+
+/** Every canvas in the workspace, including ones this session never wrote. */
+export async function listCanvasIds(cwd: string): Promise<readonly string[]> {
+  try {
+    const response = await fetch(`${CANVAS_READ_PATH}?cwd=${encodeURIComponent(cwd)}`, { cache: "no-store" });
+    return response.ok ? ((await response.json()) as string[]) : [];
+  } catch {
+    return [];
+  }
+}
+
+export async function readCanvasFile(cwd: string, id: string): Promise<string | null> {
+  // A distinct URL per read on top of `no-store`: the file is re-read precisely because it
+  // changed, so any reuse of an earlier response is guaranteed to be the wrong answer.
+  readSerial += 1;
+  const url = `${CANVAS_READ_PATH}?cwd=${encodeURIComponent(cwd)}&id=${encodeURIComponent(id)}&r=${readSerial}`;
+  try {
+    // `cache: "no-store"` on the request as well as the response: a canvas is re-read
+    // precisely because it just changed, and a cached body is the one answer that is
+    // guaranteed wrong.
+    const response = await fetch(url, { cache: "no-store" });
+    // 404 is ordinary: a canvas whose write is still streaming has no file yet.
+    return response.ok ? await response.text() : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Reads one of a canvas's sub-page files, named by the relative specifier as written in the
+ * canvas source. The server resolves it through the contract; anything outside this canvas's
+ * own child directory comes back 400 and reads here as null.
+ */
+export async function readCanvasChild(cwd: string, id: string, specifier: string, from: string): Promise<{ source: string; filename: string } | null> {
+  readSerial += 1;
+  const url = `${CANVAS_READ_PATH}?cwd=${encodeURIComponent(cwd)}&id=${encodeURIComponent(id)}&child=${encodeURIComponent(specifier)}&from=${encodeURIComponent(from)}&r=${readSerial}`;
+  try {
+    const response = await fetch(url, { cache: "no-store" });
+    if (!response.ok) return null;
+    // The server resolved the extension; the compiler needs it to pick a syntax.
+    return { source: await response.text(), filename: response.headers.get("x-ui4a-filename") ?? `${specifier}.tsx` };
+  } catch {
+    return null;
+  }
+}