basis-design 0.1.1 → 0.2.0

package/shared/capture.ts

@@ -0,0 +1,75 @@
+/*
+ * Capturing views for verification: each screen of a view is photographed at fixed sizes, and the implementation
+ * of the feature is later checked against those screenshots pixel for pixel. Shared by the capture page (which
+ * renders one screen) and the server (which takes the screenshots).
+ */
+
+export type CaptureTheme = "light" | "dark";
+
+/** What a flow block may say about capturing (template/components/specimen.ts, `Capture`). */
+export interface CaptureOptions {
+  widths?: number[];
+  height?: "full" | number;
+  themes?: CaptureTheme[];
+}
+
+/** One screenshot of one screen. */
+export interface CaptureShot {
+  width: number;
+  /** The viewport's height. With `fullPage` the image is as tall as the page; without, exactly this tall. */
+  viewportHeight: number;
+  fullPage: boolean;
+  theme: CaptureTheme;
+}
+
+export const DEFAULT_CAPTURE_WIDTHS = [375, 768, 1440];
+
+/**
+ * The viewport height that goes with a width, for full-page captures too: elements sized in vh (an app shell,
+ * a full-height hero) take it, so the design and the implementation must be photographed with the same one.
+ */
+export function viewportHeightFor(width: number): number {
+  if (width <= 480) return 812;
+  if (width <= 1024) return 1024;
+  return 900;
+}
+
+const MIN_SIZE = 200;
+const MAX_SIZE = 4000;
+
+/** The screenshots a flow block asks for, with Basis' defaults filled in and nonsense left out. */
+export function captureShots(options: CaptureOptions | undefined): CaptureShot[] {
+  const widths = [...new Set((options?.widths?.length ? options.widths : DEFAULT_CAPTURE_WIDTHS).map(Math.round))]
+    .filter((width) => width >= MIN_SIZE && width <= MAX_SIZE)
+    .sort((a, b) => a - b);
+  const themes = [...new Set(options?.themes?.length ? options.themes : (["light"] as CaptureTheme[]))].filter(
+    (theme) => theme === "light" || theme === "dark",
+  );
+  const fixed = typeof options?.height === "number" ? Math.round(options.height) : null;
+  const height = fixed !== null && fixed >= MIN_SIZE && fixed <= MAX_SIZE ? fixed : null;
+  return themes.flatMap((theme) =>
+    widths.map((width) => ({
+      width,
+      viewportHeight: height ?? viewportHeightFor(width),
+      fullPage: height === null,
+      theme,
+    })),
+  );
+}
+
+/** The file name of a shot inside the kit: "screens/<view>/<screen>@<width>[-dark].png". */
+export function shotFile(view: string, screen: string, shot: CaptureShot): string {
+  const theme = shot.theme === "light" ? "" : `-${shot.theme}`;
+  const height = shot.fullPage ? "" : `x${shot.viewportHeight}`;
+  return `screens/${view}/${screen}@${shot.width}${height}${theme}.png`;
+}
+
+/** What the capture page reports about the views it can render (`?list`). */
+export interface CaptureView {
+  id: string;
+  title: string;
+  screens: { id: string; label: string; shots: CaptureShot[] }[];
+}
+
+/** The attribute the capture page sets on <html> once a screen has settled and can be photographed. */
+export const READY_ATTRIBUTE = "data-basis-ready";

package/shared/protocol.ts

@@ -115,6 +115,29 @@ export interface ExportWriteResult {
   error?: string;
 }
 
+/** What a finished verification kit holds, for the Export dialog to report. */
+export interface VerifyKitSummary {
+  /** The browser that took the screenshots, with its version. */
+  browser: string;
+  views: number;
+  screens: number;
+  shots: number;
+  /** Shots whose two captures differed: those screens do not render the same twice. */
+  unstable: string[];
+  /** Shots of screens that threw while rendering. */
+  failed: string[];
+  /** Specimen files that could not be loaded. */
+  problems: string[];
+}
+
+export type VerifyKitResult =
+  | {
+      ok: true;
+      summary: VerifyKitSummary;
+      /** Where it was written; absent for a zip, which is then ready to download. */ dir?: string;
+    }
+  | { ok: false; error: string };
+
 export interface DesignState {
   design: Design;
   /** Validation errors for the file on disk; null when it is valid. The preview keeps the last valid design. */
@@ -186,7 +209,10 @@ export type ServerMessage =
   | { type: "chat-remove"; id: string }
   | { type: "snapshot"; snapshot: Snapshot }
   | { type: "export-manifest"; folder: string; files: { path: string; bytes: number }[] }
-  | { type: "export-result"; result: ExportWriteResult };
+  | { type: "export-result"; result: ExportWriteResult }
+  /** How far the verification kit has come; `done`/`total` while it takes screenshots. */
+  | { type: "verify-progress"; step: string; done?: number; total?: number }
+  | { type: "verify-result"; result: VerifyKitResult };
 
 export type ClientMessage =
   /** With `alternatives` (2 or 3), the agent makes that many takes on the prompt to choose between. */
@@ -218,6 +244,8 @@ export type ClientMessage =
   | { type: "preview-errors"; errors: string[]; visible: boolean; checks?: string[]; checking?: boolean }
   | { type: "export-manifest" }
   | { type: "export-write"; target: string; overwrite: boolean }
+  /** Builds the verification kit: into `<project>/basis-verify/` with `project`, else as a zip to download. */
+  | { type: "verify-kit"; project?: string }
   | { type: "project-switch"; id: string }
   /** Creates a project from Basis' defaults, or as a copy of the open project's design system, and opens it. */
   /**

package/src/Workbench.tsx

@@ -336,6 +336,7 @@ export function Workbench({ state, send }: { state: BridgeState; send: (message:
           result={state.exportResult}
           send={send}
           onClose={() => setExporting(false)}
+          verify={{ repo: state.project?.repo, progress: state.verifyProgress, result: state.verifyResult }}
         />
       )}
     </div>

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;
+}