@dev.fast/whiteboard 0.2.4 → 0.2.5-preview.20261013.109

package/tutorial/document.json

@@ -11,25 +11,7 @@
       "children": [
         {
           "type": "markdown",
-          "markdown": "A Review is a guided, interactive explanation of a code change. The document\nkeeps the important code and system views in one place.\n"
-        },
-        {
-          "type": "tutorial",
-          "kind": "conversation",
-          "conversation": {
-            "version": 1,
-            "title": "How this Review was made",
-            "messages": [
-              {
-                "role": "user",
-                "body": "Create a Review of the feature we just worked on."
-              },
-              {
-                "role": "assistant",
-                "body": "Ok, I'm on it..."
-              }
-            ]
-          }
+          "markdown": "A whiteboard is a guided, interactive explanation of a code change. Code,\ndiffs, and diagrams live in one document.\n"
         },
         {
           "type": "markdown",
@@ -41,42 +23,42 @@
         },
         {
           "type": "markdown",
-          "markdown": "### Put the keybindings to work\n\nThe editor below is live. Try hover, **Go to Definition**, or **Go to\nReferences** with the same commands you use in VS Code.\n"
+          "markdown": "### Read code like your editor\n\nThe editor below is live. Hover a symbol to see its type. **Go to\nDefinition** and **Find References** use the same keys as your editor.\n"
         },
         {
           "type": "code_peek",
-          "source": "head/src/orders/order-service.ts#L13-L29",
+          "source": "head/src/orders/order-service.ts#L13-L30",
           "caption": "Order service creates the order"
-        },
-        {
-          "type": "markdown",
-          "markdown": "Prose in the review also supports [links to code](review-source:head/src/orders/order-service.ts#L13-L29).\n"
         }
       ]
     },
     {
       "type": "section",
-      "title": "Commits and diffs",
+      "title": "Diffs and lenses",
       "children": [
         {
           "type": "markdown",
-          "markdown": "Whiteboard pins an exact base and head before the agent starts writing. Open\n**Commits** to see the change in author order. Expand the sample commit to see\nits files, then choose the **<>** button to inspect only that commit.\n\nThe **Diff** tab shows the complete change between the pinned base and head.\nChoose **Review** when you are ready to return to this tour.\n"
+          "markdown": "The **Diff** tab shows the whole change between the pinned base and head.\ndiffr folds unchanged structure so you read only what moved; select a fold to\nexpand it.\n"
         },
         {
           "type": "tutorial",
           "kind": "view",
-          "view": "commits",
-          "label": "Explore the sample commits"
+          "view": "diff",
+          "label": "Open the diff"
+        },
+        {
+          "type": "markdown",
+          "markdown": "**Lenses** split a change into the parts that matter. Select a lens to\nfilter the diff to just those lines. Mark lines viewed and the remaining\ncounts go down.\n\nAI summaries for folded code are opt-in under **Settings → Diff display and\nAI summaries**.\n"
         }
       ]
     },
     {
       "type": "section",
-      "title": "Interactive Diagrams",
+      "title": "Interactive diagrams",
       "children": [
         {
           "type": "markdown",
-          "markdown": "The sequence diagram connects the checkout request to fulfillment. Select any\nmessage to open its supporting code.\n"
+          "markdown": "The sequence diagram connects the checkout request to fulfillment. Select\n**Tour** to walk it fullscreen; each message opens its supporting code.\n"
         },
         {
           "type": "sequence",
@@ -104,7 +86,7 @@
               "to": "repository",
               "label": "Save order",
               "style": "call",
-              "source": "head/src/orders/order-service.ts#L13-L29"
+              "source": "head/src/orders/order-service.ts#L13-L30"
             },
             {
               "type": "step",
@@ -134,30 +116,33 @@
         },
         {
           "type": "markdown",
-          "markdown": "The database view groups writes by use case. Its operations open code too.\n"
+          "markdown": "The database view groups reads and writes by use case. Its operations open\ncode too.\n"
         },
         {
           "type": "database_lens",
           "title": "Order storage",
           "actors": {
             "orderService": {
-              "label": "Order service",
-              "softwareMapPath": "orderService.application.orders"
+              "label": "Order service"
             },
             "worker": {
-              "label": "Fulfillment worker",
-              "softwareMapPath": "orderService.fulfillment.worker"
+              "label": "Fulfillment worker"
             }
           },
           "stores": {
             "orderDatabase": {
               "label": "Order database",
               "storage": "relational",
-              "softwareMapPath": "orderService.data.ordersDatabase",
               "collections": {
                 "orders": {
                   "label": "orders",
                   "fields": {
+                    "id": {
+                      "label": "id",
+                      "dataType": "text",
+                      "primaryKey": true,
+                      "example": "order-customer-42"
+                    },
                     "customerId": {
                       "label": "customerId",
                       "dataType": "text",
@@ -178,7 +163,8 @@
                       "dataType": "timestamp",
                       "example": "2026-08-10T12:00:00Z"
                     }
-                  }
+                  },
+                  "source": "head/src/database/schema.ts#L3-L9"
                 }
               }
             }
@@ -213,63 +199,18 @@
               ]
             }
           ]
-        },
-        {
-          "type": "tutorial",
-          "kind": "feature",
-          "feature": "softwareMap",
-          "children": [
-            {
-              "type": "markdown",
-              "markdown": "The experimental **Map** moves from the order system to its components and\ncode. Select a node to explore the sample service.\n"
-            },
-            {
-              "type": "tutorial",
-              "kind": "view",
-              "view": "map",
-              "label": "Open the software map"
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "type": "section",
-      "title": "Agent traces",
-      "children": [
-        {
-          "type": "markdown",
-          "markdown": "Trace quotes connect a Review to the agent conversation behind a change.\nSelect this quote from an illustrative session to read it in context:\n"
-        },
-        {
-          "type": "trace_quote",
-          "traceId": "tutorial-trace",
-          "eventId": "0",
-          "text": "we want to have one shared server / source of truth for all agent chats."
-        },
-        {
-          "type": "markdown",
-          "markdown": "To capture your own sessions, open **Preferences → Settings → Experimental\nFeatures → Trace capture**. Enter your S3/R2 bucket credentials and choose\n**Enable**. Have everyone on your team do this (with the same bucket credentials) to sync and review each other's traces.\n\nTrace capture is off by default; this sample works without setup.\n"
         }
       ]
     },
     {
       "type": "section",
-      "title": "Get help",
+      "title": "You're all done",
       "children": [
         {
           "type": "markdown",
-          "markdown": "To connect Whiteboard to your agents, open **Preferences →\nSettings**. To revisit setup or take this tour again, open **Preferences →\nGetting Started**.\n"
+          "markdown": "To connect Whiteboard to your agents, open **Preferences → Settings**. To\nrevisit setup or take this tour again, open **Preferences → Getting Started**.\n"
         }
       ]
-    },
-    {
-      "type": "software_map",
-      "mapVersionId": "tutorial-map-base"
-    },
-    {
-      "type": "software_map",
-      "mapVersionId": "tutorial-map-head"
     }
   ]
 }

package/tutorial/lenses.json

@@ -0,0 +1,10 @@
+[
+  {
+    "title": "Inventory reservation",
+    "targets": [{ "kind": "files", "patterns": ["src/inventory/**"] }]
+  },
+  {
+    "title": "Payment charge",
+    "targets": [{ "kind": "files", "patterns": ["src/payments/**"] }]
+  }
+]

package/tutorial/runtime-manifest.json

@@ -1,11 +1,10 @@
 {
   "version": 1,
-  "reviewFiles": ["document.json", "trace.json", "software-map.json"],
+  "reviewFiles": ["document.json", "lenses.json"],
   "requiredPaths": [
     "sample-service/package.json",
     "document.json",
-    "trace.json",
-    "software-map.json",
+    "lenses.json",
     "pins.json",
     "git-stub/HEAD"
   ]

package/tutorial/sample-service/src/database/drizzle-orm.d.ts

@@ -0,0 +1,16 @@
+// The sample has no dependencies; this declares the slice of drizzle-orm it uses.
+declare module "drizzle-orm/pg-core" {
+  interface Column {
+    primaryKey(): Column;
+    notNull(): Column;
+    defaultNow(): Column;
+  }
+
+  export function text(name: string): Column;
+  export function integer(name: string): Column;
+  export function timestamp(name: string): Column;
+  export function pgTable(
+    name: string,
+    columns: Record<string, Column>,
+  ): Record<string, Column>;
+}

package/tutorial/sample-service/src/database/schema.ts

@@ -1,10 +1,9 @@
-export const ordersTable = {
-  name: "orders",
-  columns: {
-    id: { type: "text", primaryKey: true },
-    customerId: { type: "text" },
-    totalCents: { type: "integer" },
-    status: { type: "text" },
-    createdAt: { type: "timestamp" },
-  },
-} as const;
+import { integer, pgTable, text, timestamp } from "drizzle-orm/pg-core";
+
+export const orders = pgTable("orders", {
+  id: text("id").primaryKey(),
+  customerId: text("customer_id").notNull(),
+  totalCents: integer("total_cents").notNull(),
+  status: text("status").notNull(),
+  createdAt: timestamp("created_at").notNull().defaultNow(),
+});

package/tutorial/sample-service/src/inventory/forklift-mood.ts

@@ -0,0 +1,4 @@
+/** How the forklift feels today. Do not ask it twice. */
+export type ForkliftMood = "contemplative" | "grumpy" | "suspiciously cheerful";
+
+export const FORKLIFT_MOOD: ForkliftMood = "contemplative";

package/tutorial/sample-service/src/inventory/inventory-service.ts

@@ -1,6 +1,10 @@
-import type { CheckoutItem } from "../orders/order.js";
+import type { CheckoutItem, Sku } from "../orders/order.js";
+import { FORKLIFT_MOOD } from "./forklift-mood.js";
+import { blameTheGremlins, countShelvesTwice } from "./warehouse-lore.js";
 
 export class InventoryService {
+  private readonly held = new Map<string, number>();
+
   reserve(items: readonly CheckoutItem[]): void {
     const unavailable = items.find((item) => item.quantity < 1);
 
@@ -8,4 +12,17 @@ export class InventoryService {
       throw new Error(`Invalid quantity for ${unavailable.sku}`);
     }
   }
+
+  release(items: readonly CheckoutItem[]): void {
+    for (const item of items) {
+      this.held.delete(item.sku);
+    }
+  }
+
+  /** How sure the warehouse is about a shelf, given the forklift's mood. */
+  audit(sku: Sku): string {
+    if (countShelvesTwice(sku) === 0) return blameTheGremlins(sku);
+
+    return `${sku} was counted while the forklift felt ${FORKLIFT_MOOD}`;
+  }
 }

package/tutorial/sample-service/src/inventory/warehouse-lore.ts

@@ -0,0 +1,11 @@
+import type { Sku } from "../orders/order.js";
+
+/** Every shelf is counted twice, because the first count is always wrong. */
+export function countShelvesTwice(sku: Sku): number {
+  return sku.length * 2;
+}
+
+/** When stock goes missing, it was them. */
+export function blameTheGremlins(sku: Sku): string {
+  return `Gremlins took the last ${sku}`;
+}

package/tutorial/sample-service/src/orders/order-service.ts

@@ -1,6 +1,6 @@
 import type { InventoryService } from "../inventory/inventory-service.js";
 import type { PaymentGateway } from "../payments/payment-gateway.js";
-import type { CheckoutRequest, Order } from "./order.js";
+import type { Cents, CheckoutRequest, Order } from "./order.js";
 import type { OrdersRepository } from "./orders-repository.js";
 
 export class OrderService {
@@ -10,8 +10,9 @@ export class OrderService {
     private readonly orders: OrdersRepository,
   ) {}
 
+  /** Reserves the stock, charges the customer, and saves a pending order. */
   placeOrder(request: CheckoutRequest): Order {
-    const totalCents = request.items.reduce(
+    const totalCents: Cents = request.items.reduce(
       (sum, item) => sum + item.quantity * item.unitPriceCents,
       0,
     );

package/tutorial/sample-service/src/orders/order.ts

@@ -1,21 +1,43 @@
-export type OrderStatus = "pending" | "queued" | "fulfilled";
+/** Where an order is in its short, eventful life. */
+export type OrderStatus =
+  /** Charged, but still in the building. */
+  | "pending"
+  /** Waiting its turn on the fulfillment queue. */
+  | "queued"
+  /** Out the door. Regret is not a refund reason. */
+  | "fulfilled";
 
+/** A stock-keeping unit, like `SKU-RUBBER-DUCK`. */
+export type Sku = `SKU-${string}`;
+
+/** Money in whole cents, because floats cannot be trusted with money. */
+export type Cents = number;
+
+/** One line of a cart. */
 export interface CheckoutItem {
-  sku: string;
+  /** What the customer wants. */
+  sku: Sku;
+  /** How many they want. Zero is a cry for help. */
   quantity: number;
-  unitPriceCents: number;
+  /** The price of one unit, before the payment gateway takes its cut. */
+  unitPriceCents: Cents;
 }
 
+/** An order the service has accepted and charged for. */
 export interface Order {
-  id: string;
+  /** Derived from the customer, so each customer gets one order. Allegedly. */
+  id: `order-${string}`;
   customerId: string;
   items: readonly CheckoutItem[];
-  totalCents: number;
+  /** Every line's quantity times its unit price, in cents. */
+  totalCents: Cents;
   status: OrderStatus;
 }
 
+/** What the checkout API hands the order service. */
 export interface CheckoutRequest {
   customerId: string;
   items: readonly CheckoutItem[];
+  /** An opaque token from the payment provider. Never log it. */
   paymentToken: string;
 }

package/tutorial/sample-service/src/payments/fraud-vibes.ts

@@ -0,0 +1,4 @@
+/** A fraud score derived entirely from vibes: 0 is chill, 1 is not. */
+export function vibeCheck(paymentToken: string): number {
+  return paymentToken.startsWith("tok_sus") ? 1 : 0;
+}

package/tutorial/sample-service/src/payments/payment-gateway.ts

@@ -1,12 +1,29 @@
+import type { Cents } from "../orders/order.js";
+import { vibeCheck } from "./fraud-vibes.js";
+import { RACCOON_ON_DUTY, nervouslyRound } from "./raccoon-ledger.js";
+
 export interface PaymentReceipt {
   chargeId: string;
-  amountCents: number;
+  amountCents: Cents;
+  /** Who signed off on the charge. */
+  approvedBy: typeof RACCOON_ON_DUTY;
 }
 
 export class PaymentGateway {
   charge(paymentToken: string, amountCents: number): PaymentReceipt {
     if (!paymentToken) throw new Error("A payment token is required");
 
-    return { chargeId: `charge-${amountCents}`, amountCents };
+    return {
+      chargeId: `charge-${amountCents}`,
+      amountCents,
+      approvedBy: RACCOON_ON_DUTY,
+    };
+  }
+
+  /** Refunds a receipt, provided the vibes allow it. */
+  refund(receipt: PaymentReceipt, paymentToken: string): Cents {
+    if (vibeCheck(paymentToken) > 0.5) return 0;
+
+    return nervouslyRound(receipt.amountCents);
   }
 }

package/tutorial/sample-service/src/payments/raccoon-ledger.ts

@@ -0,0 +1,9 @@
+import type { Cents } from "../orders/order.js";
+
+/** The ledger is kept by a raccoon. It has never been audited. */
+export const RACCOON_ON_DUTY = "Gerald";
+
+/** Rounds to the nearest cent, then rounds again out of anxiety. */
+export function nervouslyRound(cents: Cents): Cents {
+  return Math.round(Math.round(cents));
+}

package/dist/agent-cli-BR2j-2n5.js

@@ -1,2 +0,0 @@
-import { n as runReviewAgentCli } from "./agent-cli-BrFqhnzM.js";
-export { runReviewAgentCli };

package/dist/input-error-OLgB_h31.js

@@ -1,11 +0,0 @@
-//#region src/review-api/input-error.ts
-/** Deliberately safe to show to API clients, unlike filesystem/provider errors. */
-var ReviewInputError = class extends Error {
-	status;
-	constructor(message, status = 400) {
-		super(message);
-		this.status = status;
-	}
-};
-//#endregion
-export { ReviewInputError as t };

package/dist/profile-BQGaX8aX.js

@@ -1,2 +0,0 @@
-import { t as openReviewProfile } from "./profile-RDEioF8b.js";
-export { openReviewProfile };