basis-design 0.1.0 → 0.2.0

package/src/bridge.ts

@@ -1,163 +1,173 @@
-import { useCallback, useEffect, useReducer, useRef } from "react";
-import type {
-  AgentState,
-  Baseline,
-  ChatItem,
-  ClientMessage,
-  DesignState,
-  HistoryEntry,
-  ExportWriteResult,
-  ProjectEntry,
-  ServerMessage,
-  Snapshot,
-} from "../shared/protocol.ts";
-import type { ReviewState } from "../shared/review.ts";
-
-export interface BridgeState {
-  connected: boolean;
-  /** The open project, and every project on the list. */
-  project: ProjectEntry | null;
-  projects: ProjectEntry[];
-  /** The project being opened, while Basis switches to it. */
-  switching: ProjectEntry | null;
-  /** Why the last project request failed, until the next one. */
-  /** The last failed project request's answer; a new object each time, so a repeated message is a new answer. */
-  projectError: { message: string } | null;
-  design: DesignState | null;
-  history: HistoryEntry[];
-  agent: AgentState | null;
-  chat: ChatItem[];
-  /** History snapshots fetched for inspection, by entry id. */
-  snapshots: Record<string, Snapshot>;
-  /** The open review, if any. */
-  review: ReviewState | null;
-  /** Past versions materialised for reviews, by commit id. */
-  baselines: Record<string, Baseline>;
-  /** Port of the sandboxed preview origin, from the server. */
-  previewPort: number | null;
-  exportManifest: { folder: string; files: { path: string; bytes: number }[] } | null;
-  exportResult: ExportWriteResult | null;
-}
-
-const initial: BridgeState = {
-  connected: false,
-  project: null,
-  projects: [],
-  switching: null,
-  projectError: null,
-  design: null,
-  history: [],
-  agent: null,
-  chat: [],
-  snapshots: {},
-  review: null,
-  baselines: {},
-  previewPort: null,
-  exportManifest: null,
-  exportResult: null,
-};
-
-type Action = ServerMessage | { type: "connected"; connected: boolean };
-
-function reduce(state: BridgeState, action: Action): BridgeState {
-  switch (action.type) {
-    case "connected":
-      return { ...state, connected: action.connected };
-    case "hello": {
-      // A hello for another project replaces everything that belonged to the previous one.
-      const same = state.project?.id === action.project.id;
-      return {
-        ...(same ? state : { ...initial, projectError: state.projectError }),
-        connected: true,
-        project: action.project,
-        projects: action.projects,
-        switching: null,
-        previewPort: action.previewPort,
-        design: action.design,
-        history: action.history,
-        agent: action.agent,
-        chat: action.chat,
-        review: action.review,
-        // The server may have restarted and removed its copies of past versions; ask for them again.
-        baselines: {},
-      };
-    }
-    case "projects":
-      // The open project's entry can change too (a product repo linked).
-      return {
-        ...state,
-        projects: action.projects,
-        project: action.projects.find((entry) => entry.id === state.project?.id) ?? state.project,
-      };
-    case "project-switching":
-      return { ...state, switching: action.project, projectError: null };
-    case "project-error":
-      return { ...state, projectError: { message: action.message } };
-    case "design":
-      return { ...state, design: action.design };
-    case "history":
-      return { ...state, history: action.history };
-    case "agent":
-      return { ...state, agent: action.agent };
-    case "chat-reset":
-      return { ...state, chat: [] };
-    case "chat-upsert": {
-      const index = state.chat.findIndex((item) => item.id === action.item.id);
-      if (index === -1) return { ...state, chat: [...state.chat, action.item] };
-      const chat = state.chat.slice();
-      chat[index] = action.item;
-      return { ...state, chat };
-    }
-    case "export-manifest":
-      return { ...state, exportManifest: { folder: action.folder, files: action.files } };
-    case "export-result":
-      return { ...state, exportResult: action.result };
-    case "review":
-      // A review that ends takes the server's copies of past versions with it.
-      return { ...state, review: action.review, baselines: action.review ? state.baselines : {} };
-    case "chat-remove":
-      return { ...state, chat: state.chat.filter((item) => item.id !== action.id) };
-    case "baseline":
-      return { ...state, baselines: { ...state.baselines, [action.baseline.id]: action.baseline } };
-    case "snapshot":
-      return { ...state, snapshots: { ...state.snapshots, [action.snapshot.id]: action.snapshot } };
-  }
-}
-
-/** Keeps a WebSocket to the Basis server open and mirrors its state. */
-export function useBridge(): { state: BridgeState; send: (message: ClientMessage) => void } {
-  const [state, dispatch] = useReducer(reduce, initial);
-  const socket = useRef<WebSocket | null>(null);
-
-  useEffect(() => {
-    let closed = false;
-    let retry: ReturnType<typeof setTimeout> | undefined;
-    const connect = () => {
-      const ws = new WebSocket(`${location.protocol === "https:" ? "wss" : "ws"}://${location.host}/bridge`);
-      socket.current = ws;
-      ws.onmessage = (event) => dispatch(JSON.parse(String(event.data)) as ServerMessage);
-      ws.onclose = () => {
-        dispatch({ type: "connected", connected: false });
-        if (!closed) retry = setTimeout(connect, 1000);
-      };
-    };
-    connect();
-    return () => {
-      closed = true;
-      clearTimeout(retry);
-      const ws = socket.current;
-      if (!ws) return;
-      ws.onmessage = null;
-      ws.onclose = null;
-      // Closing a socket that is still connecting logs a browser warning, so let it open first.
-      if (ws.readyState === WebSocket.CONNECTING) ws.onopen = () => ws.close();
-      else ws.close();
-    };
-  }, []);
-
-  const send = useCallback((message: ClientMessage) => {
-    if (socket.current?.readyState === WebSocket.OPEN) socket.current.send(JSON.stringify(message));
-  }, []);
-
-  return { state, send };
-}
+import { useCallback, useEffect, useReducer, useRef } from "react";
+import type {
+  AgentState,
+  Baseline,
+  ChatItem,
+  ClientMessage,
+  DesignState,
+  HistoryEntry,
+  ExportWriteResult,
+  ProjectEntry,
+  ServerMessage,
+  Snapshot,
+  VerifyKitResult,
+} from "../shared/protocol.ts";
+import type { ReviewState } from "../shared/review.ts";
+
+export interface BridgeState {
+  connected: boolean;
+  /** The open project, and every project on the list. */
+  project: ProjectEntry | null;
+  projects: ProjectEntry[];
+  /** The project being opened, while Basis switches to it. */
+  switching: ProjectEntry | null;
+  /** Why the last project request failed, until the next one. */
+  /** The last failed project request's answer; a new object each time, so a repeated message is a new answer. */
+  projectError: { message: string } | null;
+  design: DesignState | null;
+  history: HistoryEntry[];
+  agent: AgentState | null;
+  chat: ChatItem[];
+  /** History snapshots fetched for inspection, by entry id. */
+  snapshots: Record<string, Snapshot>;
+  /** The open review, if any. */
+  review: ReviewState | null;
+  /** Past versions materialised for reviews, by commit id. */
+  baselines: Record<string, Baseline>;
+  /** Port of the sandboxed preview origin, from the server. */
+  previewPort: number | null;
+  exportManifest: { folder: string; files: { path: string; bytes: number }[] } | null;
+  exportResult: ExportWriteResult | null;
+  /** The verification kit being built (its current step), or null. */
+  verifyProgress: { step: string; done?: number; total?: number } | null;
+  verifyResult: VerifyKitResult | null;
+}
+
+const initial: BridgeState = {
+  connected: false,
+  project: null,
+  projects: [],
+  switching: null,
+  projectError: null,
+  design: null,
+  history: [],
+  agent: null,
+  chat: [],
+  snapshots: {},
+  review: null,
+  baselines: {},
+  previewPort: null,
+  exportManifest: null,
+  exportResult: null,
+  verifyProgress: null,
+  verifyResult: null,
+};
+
+type Action = ServerMessage | { type: "connected"; connected: boolean };
+
+function reduce(state: BridgeState, action: Action): BridgeState {
+  switch (action.type) {
+    case "connected":
+      return { ...state, connected: action.connected };
+    case "hello": {
+      // A hello for another project replaces everything that belonged to the previous one.
+      const same = state.project?.id === action.project.id;
+      return {
+        ...(same ? state : { ...initial, projectError: state.projectError }),
+        connected: true,
+        project: action.project,
+        projects: action.projects,
+        switching: null,
+        previewPort: action.previewPort,
+        design: action.design,
+        history: action.history,
+        agent: action.agent,
+        chat: action.chat,
+        review: action.review,
+        // The server may have restarted and removed its copies of past versions; ask for them again.
+        baselines: {},
+      };
+    }
+    case "projects":
+      // The open project's entry can change too (a product repo linked).
+      return {
+        ...state,
+        projects: action.projects,
+        project: action.projects.find((entry) => entry.id === state.project?.id) ?? state.project,
+      };
+    case "project-switching":
+      return { ...state, switching: action.project, projectError: null };
+    case "project-error":
+      return { ...state, projectError: { message: action.message } };
+    case "design":
+      return { ...state, design: action.design };
+    case "history":
+      return { ...state, history: action.history };
+    case "agent":
+      return { ...state, agent: action.agent };
+    case "chat-reset":
+      return { ...state, chat: [] };
+    case "chat-upsert": {
+      const index = state.chat.findIndex((item) => item.id === action.item.id);
+      if (index === -1) return { ...state, chat: [...state.chat, action.item] };
+      const chat = state.chat.slice();
+      chat[index] = action.item;
+      return { ...state, chat };
+    }
+    case "export-manifest":
+      return { ...state, exportManifest: { folder: action.folder, files: action.files } };
+    case "export-result":
+      return { ...state, exportResult: action.result };
+    case "verify-progress":
+      return { ...state, verifyProgress: { step: action.step, done: action.done, total: action.total } };
+    case "verify-result":
+      return { ...state, verifyProgress: null, verifyResult: action.result };
+    case "review":
+      // A review that ends takes the server's copies of past versions with it.
+      return { ...state, review: action.review, baselines: action.review ? state.baselines : {} };
+    case "chat-remove":
+      return { ...state, chat: state.chat.filter((item) => item.id !== action.id) };
+    case "baseline":
+      return { ...state, baselines: { ...state.baselines, [action.baseline.id]: action.baseline } };
+    case "snapshot":
+      return { ...state, snapshots: { ...state.snapshots, [action.snapshot.id]: action.snapshot } };
+  }
+}
+
+/** Keeps a WebSocket to the Basis server open and mirrors its state. */
+export function useBridge(): { state: BridgeState; send: (message: ClientMessage) => void } {
+  const [state, dispatch] = useReducer(reduce, initial);
+  const socket = useRef<WebSocket | null>(null);
+
+  useEffect(() => {
+    let closed = false;
+    let retry: ReturnType<typeof setTimeout> | undefined;
+    const connect = () => {
+      const ws = new WebSocket(`${location.protocol === "https:" ? "wss" : "ws"}://${location.host}/bridge`);
+      socket.current = ws;
+      ws.onmessage = (event) => dispatch(JSON.parse(String(event.data)) as ServerMessage);
+      ws.onclose = () => {
+        dispatch({ type: "connected", connected: false });
+        if (!closed) retry = setTimeout(connect, 1000);
+      };
+    };
+    connect();
+    return () => {
+      closed = true;
+      clearTimeout(retry);
+      const ws = socket.current;
+      if (!ws) return;
+      ws.onmessage = null;
+      ws.onclose = null;
+      // Closing a socket that is still connecting logs a browser warning, so let it open first.
+      if (ws.readyState === WebSocket.CONNECTING) ws.onopen = () => ws.close();
+      else ws.close();
+    };
+  }, []);
+
+  const send = useCallback((message: ClientMessage) => {
+    if (socket.current?.readyState === WebSocket.OPEN) socket.current.send(JSON.stringify(message));
+  }, []);
+
+  return { state, send };
+}

package/src/capture/capture.css

@@ -0,0 +1,50 @@
+/*
+ * The page a captured screen renders on, and nothing else: no gallery around it, no transitions, no caret. The
+ * base below is what a screen inherits; an implementation that is checked against the screenshots needs the
+ * same (the kit's manifest repeats it as `base`).
+ */
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+  transition: none !important;
+  animation: none !important;
+  caret-color: transparent !important;
+}
+
+html,
+body {
+  margin: 0;
+}
+
+html {
+  scrollbar-width: none;
+}
+
+html::-webkit-scrollbar {
+  display: none;
+}
+
+.ds-root {
+  min-height: 100vh;
+  background: var(--color-bg);
+  color: var(--color-text);
+  font-family: var(--font-sans);
+  font-size: var(--text-base);
+  line-height: var(--leading-normal);
+  color-scheme: light;
+}
+
+.ds-root[data-theme="dark"] {
+  color-scheme: dark;
+}
+
+.capture-problem {
+  padding: 24px;
+  font:
+    14px/1.5 ui-monospace,
+    Consolas,
+    monospace;
+  color: #b42318;
+}

package/src/capture/main.tsx

@@ -0,0 +1,146 @@
+import { Component, useEffect, useMemo, useState, type ReactNode } from "react";
+import { createRoot } from "react-dom/client";
+import { captureShots, READY_ATTRIBUTE, type CaptureView } from "../../shared/capture.ts";
+import { parseDesignText, type Design } from "../../shared/design.ts";
+import { previewCss } from "../../shared/tokens.ts";
+import type { ScreenProps, SpecimenBlock } from "../../template/components/specimen.ts";
+import { loadSpecimens, type LoadedSpecimen } from "../preview/specimens.tsx";
+import "./capture.css";
+
+/*
+ * One screen of a view, alone on the page at the size the browser gives it, for the verification kit's
+ * screenshots: `?view=<view id>&screen=<screen id>&theme=light|dark`. `?list` instead reports every view and
+ * the shots its screens ask for (window.__basisViews). The design comes from design.json beside this page, so
+ * the same page runs on Basis' preview server and as the kit's static copy of the design.
+ */
+
+declare global {
+  interface Window {
+    __basisViews?: { views: CaptureView[]; problems: string[] };
+  }
+}
+
+const params = new URLSearchParams(location.search);
+type FlowBlock = Extract<SpecimenBlock, { kind: "flow" }>;
+
+function flows(specimen: LoadedSpecimen): FlowBlock[] {
+  return specimen.blocks.filter((block): block is FlowBlock => block.kind === "flow");
+}
+
+function views(): { views: CaptureView[]; problems: string[] } {
+  const { specimens, problems } = loadSpecimens();
+  const list = specimens
+    .filter((specimen) => specimen.page === "views")
+    .map((specimen) => ({
+      id: specimen.id,
+      title: specimen.title,
+      screens: flows(specimen).flatMap((flow) =>
+        flow.screens.map((screen) => ({ id: screen.id, label: screen.label, shots: captureShots(flow.capture) })),
+      ),
+    }))
+    .filter((view) => view.screens.length > 0);
+  return { views: list, problems: problems.map((problem) => `${problem.file}: ${problem.message}`) };
+}
+
+const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Marks the page ready once it has settled: fonts loaded, images decoded, and the layout the same size twice in
+ * a row. Timers rather than animation frames, which a background tab does not run.
+ */
+async function markReady(): Promise<void> {
+  await document.fonts.ready;
+  await Promise.all([...document.images].map((image) => image.decode().catch(() => undefined)));
+  let last = "";
+  for (let attempt = 0; attempt < 40; attempt++) {
+    await wait(50);
+    const size = `${document.documentElement.scrollWidth}x${document.documentElement.scrollHeight}`;
+    if (size === last) break;
+    last = size;
+  }
+  document.documentElement.setAttribute(READY_ATTRIBUTE, "true");
+}
+
+class Boundary extends Component<{ children: ReactNode }, { error: unknown }> {
+  state = { error: null as unknown };
+  static getDerivedStateFromError(error: unknown) {
+    return { error };
+  }
+  componentDidCatch() {
+    document.documentElement.setAttribute("data-basis-error", "true");
+  }
+  render() {
+    const { error } = this.state;
+    if (error === null) return this.props.children;
+    return <p className="capture-problem">This screen failed to render: {String(error)}</p>;
+  }
+}
+
+function Screen({ design, theme }: { design: Design; theme: "light" | "dark" }) {
+  const { specimens } = useMemo(() => loadSpecimens(), []);
+  const view = specimens.find((specimen) => specimen.page === "views" && specimen.id === params.get("view"));
+  const screens = view ? flows(view).flatMap((flow) => flow.screens) : [];
+  // The kit's copy of the design is clickable: `go` moves through the flow as in the gallery.
+  const [position, setPosition] = useState<{ id: string; data?: unknown }>({
+    id: params.get("screen") ?? screens[0]?.id ?? "",
+  });
+  const screen = screens.find((item) => item.id === position.id);
+
+  useEffect(() => {
+    void markReady();
+  }, [position]);
+
+  if (!view || !screen) {
+    return (
+      <p className="capture-problem">
+        No screen "{position.id}" in the view "{params.get("view")}".
+      </p>
+    );
+  }
+  const go: ScreenProps["go"] = (id, data) => {
+    const next = new URLSearchParams(location.search);
+    next.set("screen", id);
+    history.replaceState(null, "", `?${next}`);
+    document.documentElement.removeAttribute(READY_ATTRIBUTE);
+    setPosition({ id, data });
+  };
+  const Render = screen.render;
+  return (
+    <div className="ds-root" data-theme={theme}>
+      <Boundary key={screen.id}>
+        <Render design={design as unknown as ScreenProps["design"]} go={go} data={position.data} />
+      </Boundary>
+    </div>
+  );
+}
+
+function Page({ design }: { design: Design }) {
+  const theme = params.get("theme") === "dark" ? "dark" : "light";
+  return (
+    <>
+      <style>{previewCss(design, ".ds-root")}</style>
+      {design.typography.fontImports.map((href) => (
+        <link key={href} rel="stylesheet" href={href} />
+      ))}
+      <Screen design={design} theme={theme} />
+    </>
+  );
+}
+
+async function start(): Promise<void> {
+  const root = createRoot(document.getElementById("root")!);
+  if (params.has("list")) {
+    window.__basisViews = views();
+    document.documentElement.setAttribute(READY_ATTRIBUTE, "true");
+    return;
+  }
+  const result = parseDesignText(await (await fetch("./design.json", { cache: "no-store" })).text());
+  if (!result.ok) {
+    root.render(<p className="capture-problem">design.json is not valid: {result.errors.join("; ")}</p>);
+    document.documentElement.setAttribute(READY_ATTRIBUTE, "true");
+    return;
+  }
+  root.render(<Page design={result.design} />);
+}
+
+void start();

package/src/chat/ChatPanel.tsx

@@ -1,4 +1,4 @@
-import { useLayoutEffect, useRef } from "react";
+import { useLayoutEffect, useRef, type ReactNode } from "react";
 import type { Annotation } from "../../shared/annotations.ts";
 import {
   AGENT_IDS,
@@ -38,6 +38,8 @@ interface ChatPanelProps {
   onTogglePick: () => void;
   /** True while a review is open. */
   reviewing: boolean;
+  /** The handle that resizes the panel; inside it, so it belongs to the panel's landmark. */
+  resizer?: ReactNode;
 }
 
 const STATUS_TEXT: Record<AgentState["status"], string> = {
@@ -58,6 +60,7 @@ export function ChatPanel({
   onDraft,
   send,
   composerRef,
+  resizer,
   ...composer
 }: ChatPanelProps) {
   const scroller = useRef<HTMLDivElement>(null);
@@ -116,9 +119,14 @@ export function ChatPanel({
         </div>
       )}
 
+      {/* Focusable, so the conversation scrolls from the keyboard too; not role="log", which would read the
+          streamed reply aloud as it arrives. */}
       <div
         ref={scroller}
         className={styles.log}
+        role="region"
+        aria-label="Conversation"
+        tabIndex={0}
         onScroll={(event) => {
           const el = event.currentTarget;
           pinned.current = el.scrollHeight - el.scrollTop - el.clientHeight < 40;
@@ -213,6 +221,7 @@ export function ChatPanel({
         }}
         {...composer}
       />
+      {resizer}
     </aside>
   );
 }

package/src/preview/specimens.tsx

@@ -53,6 +53,26 @@ function isComponent(value: unknown): value is ComponentType<never> {
   return typeof value === "function" || (typeof value === "object" && value !== null && "$$typeof" in value);
 }
 
+/** What is wrong with a flow block's `capture`, or null when it is absent or well formed. */
+function captureProblem(capture: unknown): string | null {
+  if (capture === undefined) return null;
+  if (!capture || typeof capture !== "object") return "capture must be an object: { widths, height, themes }";
+  const { widths, height, themes } = capture as Record<string, unknown>;
+  if (widths !== undefined && (!Array.isArray(widths) || widths.some((width) => typeof width !== "number"))) {
+    return "capture.widths must be an array of numbers (viewport widths in px)";
+  }
+  if (height !== undefined && height !== "full" && typeof height !== "number") {
+    return 'capture.height must be "full" or a number (viewport height in px)';
+  }
+  if (
+    themes !== undefined &&
+    (!Array.isArray(themes) || themes.some((theme) => theme !== "light" && theme !== "dark"))
+  ) {
+    return 'capture.themes must be an array of "light" and "dark"';
+  }
+  return null;
+}
+
 /** Why a block cannot be rendered, or null when it is well formed. */
 function blockProblem(block: unknown): string | null {
   if (!block || typeof block !== "object") return "a block is not an object";
@@ -78,6 +98,7 @@ function blockProblem(block: unknown): string | null {
     if (screens.some((screen) => !screen || typeof screen.id !== "string" || !isComponent(screen.render))) {
       return "every screen needs an id, a label and a render component";
     }
+    return captureProblem(b.capture);
   } else if (!isComponent(b.render)) {
     return `a ${String(b.kind)} block needs a render component`;
   }