@dev.fast/whiteboard 0.5.1 → 0.5.2-preview.20261104.146

package/src/review-api/store.ts

@@ -362,6 +362,11 @@ export interface SharedProvenance {
   sharedAt?: number;
   cloneUrl?: string;
   key?: string;
+  revisionId?: string;
+  /** The version import wrote; anything later is the receiver's edit. */
+  importedVersion?: number;
+  /** Opened from a link naming a revision: never refreshed. */
+  pinned?: boolean;
 }
 
 /** Content a new board starts with, as another board left it. */
@@ -1110,16 +1115,24 @@ export class ReviewStore {
 
     return run;
   }
-  /** The board copied from a share link, until it is deleted. */
-  copyOf(key: string): string | undefined {
-    const row = this.db
+  /** The boards copied from a share link, newest first, until each is deleted. */
+  copiesOf(
+    key: string,
+  ): { reviewId: string; version: number; shared: SharedProvenance }[] {
+    return this.db
       .prepare(
-        `SELECT reviews.id FROM reviews JOIN versions ON versions.review_id=reviews.id AND versions.version=reviews.version
-        WHERE CASE WHEN json_valid(versions.snapshot) THEN json_extract(versions.snapshot,'$.shared.key') END=?`,
+        `SELECT reviews.id, reviews.version, json_extract(versions.snapshot,'$.shared') AS shared
+        FROM reviews JOIN versions ON versions.review_id=reviews.id AND versions.version=reviews.version
+        WHERE CASE WHEN json_valid(versions.snapshot) THEN json_extract(versions.snapshot,'$.shared.key') END=?
+        ORDER BY reviews.rowid DESC`,
       )
-      .get(key);
-
-    return row && String(row.id);
+      .all(key)
+      .map((row) => ({
+        reviewId: String(row.id),
+        version: Number(row.version),
+        // SAFETY: the key matched this row's seed.
+        shared: JSON.parse(String(row.shared)) as SharedProvenance,
+      }));
   }
   /** Checkouts whose remote is cloneUrl, most recently used first. */
   checkoutsOf(cloneUrl: string): string[] {
@@ -1600,6 +1613,50 @@ export class ReviewStore {
       author,
     ).then((source) => this.applyPreparedCommand(source, initial, author));
 
+    return this.track(prepared);
+  }
+
+  /** Replaces a share copy's content under the same board id; 409 once it moved past `baseVersion`. */
+  refreshCopy(
+    reviewId: string,
+    baseVersion: number,
+    // oxlint-disable-next-line anti-slop/no-unknown-parameters -- Command boundary: commandSchema.parse below rejects malformed input before mutation.
+    create: unknown,
+    seed: Seed,
+  ): Promise<Result> {
+    if (this.closing)
+      return Promise.reject(new Error("Review store is closing."));
+    const command = commandSchema.parse(create);
+    const op = command.operation;
+
+    if (
+      op.type !== "create" ||
+      op.pullRequestUrl ||
+      op.parentId ||
+      op.dependsOn ||
+      op.projectId
+    )
+      throw new ReviewInputError(
+        "A refresh takes a create command with a title and target alone.",
+      );
+    const person: Author = { kind: "person" };
+
+    return this.track(
+      this.prepareCommand(
+        command,
+        undefined,
+        Promise.resolve(undefined),
+        person,
+      ).then((source) =>
+        this.applyPreparedCommand(source, seed, person, {
+          reviewId,
+          baseVersion,
+        }),
+      ),
+    );
+  }
+
+  private track(prepared: Promise<Result>) {
     this.preparing.add(prepared);
     void prepared
       .finally(() => this.preparing.delete(prepared))
@@ -1690,6 +1747,7 @@ export class ReviewStore {
     prepared: PreparedCommand,
     initial: Seed | undefined,
     author: Author,
+    into?: { reviewId: string; baseVersion: number },
   ) {
     const {
       op,
@@ -1703,6 +1761,7 @@ export class ReviewStore {
 
     return this.enqueue(async () => {
       if (
+        !into &&
         op.type === "create" &&
         (op.pullRequestUrl
           ? op.reuseExisting !== false
@@ -1774,9 +1833,19 @@ export class ReviewStore {
           fromTrash: true,
         });
 
-      const id = op.type === "create" ? randomUUID() : op.reviewId;
+      const id =
+        into?.reviewId ?? (op.type === "create" ? randomUUID() : op.reviewId);
 
-      const previous = op.type === "create" ? undefined : this.read(id);
+      const previous =
+        op.type === "create" && !into ? undefined : this.read(id);
+
+      if (
+        into &&
+        (!previous?.shared?.key || previous.shared.key !== initial?.shared?.key)
+      )
+        throw new ReviewInputError(
+          "Only a copy of the same share link refreshes in place.",
+        );
 
       let snapshot: Snapshot =
         op.type === "create"
@@ -1994,9 +2063,11 @@ export class ReviewStore {
         restore: op.type === "restore",
         repin: op.type === "set_target",
         copied: initial !== undefined,
+        inPlace: into !== undefined,
+        baseVersion: into?.baseVersion,
         projectLive: op.type !== "restore" && !resolvedTarget,
         result: {
-          ...(op.type === "create" && { created: true }),
+          ...(op.type === "create" && !into && { created: true }),
           targetId: applied?.targetId ?? lensTarget?.targetId,
           ...(applied && { type: applied.type }),
           ...(lensTarget && { type: lensTarget.type }),
@@ -2039,6 +2110,8 @@ export class ReviewStore {
     repin?: boolean;
     /** A board made from another's content, whose images stayed behind. */
     copied?: boolean;
+    /** A share copy refreshed in place, in Trash or not. */
+    inPlace?: boolean;
     projectLive: boolean;
     /** The ids a person's save gave new blocks, by client key. */
     personIds?: Record<string, string>;
@@ -2104,6 +2177,9 @@ export class ReviewStore {
     }));
     warnings = [...(change.warnings ?? []), ...warnings];
 
+    if (change.copied && snapshot.shared)
+      snapshot.shared.importedVersion = snapshot.version;
+
     const result: Result = {
       ...change.result,
       reviewId: id,
@@ -2156,7 +2232,8 @@ export class ReviewStore {
       previous
         ? () => {
             // A board in Trash is read-only, whoever writes.
-            this.assertWritable(id);
+            if (change.inPlace) this.assertExists(id);
+            else this.assertWritable(id);
 
             if (change.baseVersion !== undefined)
               assertBaseVersion(change.baseVersion, this.currentVersion(id));

package/src/server/desktop-server.ts

@@ -54,6 +54,7 @@ import {
   ReviewTelemetry,
   type ReviewTelemetryContext,
 } from "@review/review-telemetry";
+import { remoteShare } from "@review/sharing/host.js";
 import { Hono } from "hono";
 import { z } from "zod";
 
@@ -204,6 +205,12 @@ export function createGlobalReviewServer(
     }
   }
 
+  const hooks = reviewLifecycleTelemetry(
+    telemetry,
+    (reviewId) => reviewStore.summary(reviewId)?.firstCreatedAt,
+    () => aliasInstallationToAccount(telemetry),
+  );
+
   const core = createWhiteboardCore({
     profile: {
       store: reviewStore,
@@ -229,11 +236,16 @@ export function createGlobalReviewServer(
         home: devReviewHome(),
       };
     },
-    hooks: reviewLifecycleTelemetry(
-      telemetry,
-      (reviewId) => reviewStore.summary(reviewId)?.firstCreatedAt,
-      () => aliasInstallationToAccount(telemetry),
-    ),
+    hooks: {
+      ...hooks,
+      sharing: {
+        ...hooks.sharing,
+        remoteShare: remoteShare(
+          (reviewId) => gateway.isRemote(reviewId),
+          (request) => gateway.fetch(request),
+        ),
+      },
+    },
     ask: { tools: askTools },
   });
 

package/src/server/headless-host.ts

@@ -18,6 +18,7 @@ import { cliAskTools } from "@review/ask/threads.js";
 import { desktopUsesHome } from "@review/desktop-discovery.js";
 import { findReviewPackageRoot } from "@review/package-paths.js";
 import { openReviewProfile } from "@review/review-api/profile.js";
+import { readAnimationsEnabled } from "@review/review-preferences.js";
 import {
   DESKTOP_TAKEOVER_SIGNAL,
   type ReviewServerDiscovery,
@@ -198,6 +199,8 @@ async function serve(input: HeadlessServerInput) {
     manageWorkspaces: true,
   });
 
+  const animationsEnabled = await readAnimationsEnabled(input.stateDir);
+
   const discovery: ReviewServerDiscovery = {
     version: 1,
     instanceId: randomUUID(),
@@ -221,6 +224,7 @@ async function serve(input: HeadlessServerInput) {
     token: discovery.token,
     instanceId: discovery.instanceId,
     softwareMapEnabled: input.softwareMapEnabled,
+    animations: () => animationsEnabled,
     status: () => ({ key: "headless", home: input.stateDir }),
     ask: {
       tools: cliAskTools(() => (existsSync(cliPath) ? cliPath : undefined), {

package/src/server/review-gateway.ts

@@ -69,6 +69,7 @@ const REMOTE_ROUTES: readonly RemoteRoute[] = [
   { method: "GET", path: "maps/:name" },
   { method: "POST", path: "navigator" },
   { method: "POST", path: "copy-context" },
+  { method: "POST", path: "share-bundle", slow: true },
   { method: "GET", path: "language-context", slow: true },
   { method: "GET", path: "ask/agents" },
   { method: "GET", path: "ask/agents/:agent/offer", slow: true },

package/src/server/review-server-core.ts

@@ -16,6 +16,11 @@ import {
   readBuildCommit,
   readReviewPackageVersion,
 } from "@review/package-paths.js";
+import {
+  type RenderRequest,
+  type RenderedFrame,
+  renderedFrameSchema,
+} from "@review/review-api/animation-render.js";
 import {
   type AuthoringCapabilities,
   type ReviewApiHooks,
@@ -95,7 +100,8 @@ export function createReviewServerApp(input: {
   mountFeedback(app);
   app.post("/control/result", async (context) => {
     const accepted = input.relay.acceptResult(
-      await readBoundedRequestJson(context.req.raw),
+      // A rendered frame's PNG rides back in a result.
+      await readBoundedRequestJson(context.req.raw, VERB_RESULT_MAX_BYTES),
     );
 
     return serverJson(accepted ? 200 : 404, { ok: accepted });
@@ -144,6 +150,10 @@ export interface WhiteboardCoreInput {
   };
 }
 
+/** A verb result may carry a captured frame: a PNG of up to 1600 pixels on
+ * its longest edge, base64. */
+const VERB_RESULT_MAX_BYTES = 16 * 1024 * 1024;
+
 export function createWhiteboardCore(input: WhiteboardCoreInput) {
   const { store, data } = input.profile;
 
@@ -154,7 +164,11 @@ export function createWhiteboardCore(input: WhiteboardCoreInput) {
     relay: input.relay,
   });
 
-  const callbacks = relayReviewCallbacks(input.relay, input.softwareMapEnabled);
+  const callbacks = relayReviewCallbacks(
+    input.relay,
+    input.softwareMapEnabled,
+    input.animations,
+  );
 
   const { ask } = input;
 
@@ -195,7 +209,8 @@ export function createWhiteboardCore(input: WhiteboardCoreInput) {
       threads: askThreads,
       agents: async () => detectAskAgents(await ask?.env),
     },
-    input.animations,
+    callbacks.animations,
+    callbacks.render,
   );
 
   // Desktop's sharing host mounts the publisher with the rest of sharing.
@@ -205,6 +220,7 @@ export function createWhiteboardCore(input: WhiteboardCoreInput) {
     app,
     api,
     close: () => {
+      callbacks.close();
       stopLocal?.();
       closeDeletedThreads();
       askThreads?.closeAll();
@@ -212,12 +228,53 @@ export function createWhiteboardCore(input: WhiteboardCoreInput) {
   };
 }
 
-/** The Desktop callbacks `createReviewApi` takes, answered over the relay. */
+const capabilitiesAnswerSchema = z.object({
+  softwareMapEnabled: z.boolean(),
+  // Older Desktops omit it.
+  animationsEnabled: z.boolean().optional(),
+});
+
+/**
+ * The Desktop callbacks `createReviewApi` takes, answered over the relay.
+ * `animations` never asks Desktop: it is the last answer while one is
+ * attached, else the host's own.
+ */
 export function relayReviewCallbacks(
   relay: ReviewDesktopVerbRelay,
   softwareMapEnabled = false,
+  animations: () => boolean = () => false,
 ) {
+  let desktopAnimations: boolean | undefined;
+
+  const capabilities = async (): Promise<AuthoringCapabilities> => {
+    if (!relay.attached) return { desktopAvailable: false, softwareMapEnabled };
+
+    const result = await relay.dispatch({
+      name: "authoringCapabilities",
+      args: {},
+    });
+
+    if (!result.ok) throw new ReviewInputError(result.error, 409);
+
+    const answer = capabilitiesAnswerSchema.parse(result.result);
+    desktopAnimations = answer.animationsEnabled;
+
+    return {
+      desktopAvailable: true,
+      softwareMapEnabled: answer.softwareMapEnabled,
+    };
+  };
+
+  const stop = relay.onAttachedChange(() => {
+    desktopAnimations = undefined;
+
+    if (relay.attached) capabilities().catch(() => {});
+  });
+
   return {
+    capabilities,
+    animations: () => desktopAnimations ?? animations(),
+    close: stop,
     async open(review: {
       reviewId: string;
       title: string;
@@ -231,21 +288,23 @@ export function relayReviewCallbacks(
 
       return z.object({ softwareMapEnabled: z.boolean() }).parse(result.result);
     },
-    async capabilities(): Promise<AuthoringCapabilities> {
+    async render(request: RenderRequest): Promise<RenderedFrame> {
       if (!relay.attached)
-        return { desktopAvailable: false, softwareMapEnabled };
+        throw new ReviewInputError(
+          "No Whiteboard Desktop is attached, so nothing can show the animation. Open the whiteboard in Desktop and render again.",
+          409,
+        );
+
+      const { reviewId, targetId, frame } = request;
 
       const result = await relay.dispatch({
-        name: "authoringCapabilities",
-        args: {},
+        name: "renderAnimation",
+        args: { reviewId, targetId, frame },
       });
 
       if (!result.ok) throw new ReviewInputError(result.error, 409);
 
-      return {
-        desktopAvailable: true,
-        ...z.object({ softwareMapEnabled: z.boolean() }).parse(result.result),
-      };
+      return renderedFrameSchema.parse(result.result);
     },
   };
 }

package/src/sharing/client.ts

@@ -4,8 +4,13 @@ import { type JsonValue, parseJsonText } from "@dev.fast/json";
 import {
   MAX_SHARE_BYTES,
   type ShareBundle,
+  type ShareRevisions,
+  type SharedMeta,
   capabilitySchema,
-  shareBundleSchema,
+  shareCreatedSchema,
+  shareIdSchema,
+  shareRevisionsSchema,
+  sharedMetaSchema,
 } from "@dev.fast/review-share-protocol";
 import {
   StreamLimitError,
@@ -15,6 +20,10 @@ import { Agent } from "undici";
 import { z } from "zod";
 
 import { shareRequestBody } from "./export.js";
+import {
+  WHITEBOARD_UPGRADE_REQUIRED_MESSAGE,
+  parseWhiteboardFile,
+} from "./file.js";
 
 const MAX_RESPONSE_BYTES = MAX_SHARE_BYTES;
 
@@ -37,14 +46,6 @@ const jwtPayloadSchema = z.object({ exp: z.number() });
 
 const bearers = new Map<string, Promise<{ bearer: string; until: number }>>();
 
-const linkSchema = z.strictObject({ shareId: z.uuid(), url: z.url() });
-
-const receivedSchema = z.object({
-  sender: z.strictObject({ login: z.string().min(1).max(256) }),
-  sharedAt: z.number(),
-  size: z.number().int().positive().max(MAX_SHARE_BYTES),
-});
-
 /** Size is checked while reading, even if Content-Length is absent or false. */
 export async function readBoundedBytes(
   response: Response,
@@ -76,6 +77,79 @@ export class ShareAuthError extends Error {
   }
 }
 
+export class ShareRequestError extends Error {
+  constructor(
+    readonly status: number,
+    message: string,
+  ) {
+    super(message);
+    this.name = "ShareRequestError";
+  }
+}
+
+const errorSchema = z.object({ error: z.object({ code: z.string() }) });
+
+async function errorCode(response: Response) {
+  if (!response.body) return undefined;
+
+  if (!response.headers.get("content-type")?.includes("application/json")) {
+    await response.body.cancel();
+
+    return undefined;
+  }
+
+  try {
+    const bytes = await readBoundedStream(response.body, 16 * 1024);
+
+    return errorSchema.safeParse(parseJsonText(bytes.toString())).data?.error
+      .code;
+  } catch {
+    return undefined;
+  }
+}
+
+function requestErrorMessage(response: Response, code: string | undefined) {
+  const { status, headers } = response;
+
+  if (status === 426 || code === "upgrade_required")
+    return WHITEBOARD_UPGRADE_REQUIRED_MESSAGE;
+
+  if (
+    status === 403 &&
+    headers.get("content-type")?.includes("text/html") &&
+    headers.get("server")?.toLowerCase() === "cloudflare"
+  )
+    return "The sharing service's security filter blocked this request. Please report this issue.";
+
+  if (status === 413)
+    return "This review is too large to share. Remove large resources, then retry.";
+
+  if (status === 429)
+    return code === "share_quota_exceeded"
+      ? "Your sharing storage limit has been reached. Please contact support."
+      : "Too many sharing requests. Wait a moment, then retry.";
+
+  if (status === 400 && code === "invalid_request")
+    return "The sharing service could not accept this review. Update Whiteboard or report this issue.";
+
+  if (status >= 500)
+    return `The sharing service is temporarily unavailable (HTTP ${status}). Try again shortly.`;
+
+  return `The sharing service refused this request (HTTP ${status}). Please report this issue.`;
+}
+
+async function requestError(response: Response) {
+  const message = requestErrorMessage(response, await errorCode(response));
+  const ray = response.headers.get("cf-ray");
+
+  const reference =
+    ray && /^[a-f0-9]{16}(?:-[a-z]{3})?$/i.test(ray)
+      ? ` Reference: ${ray}.`
+      : "";
+
+  return new ShareRequestError(response.status, message + reference);
+}
+
 /** Account tokens go only to the configured API origin. */
 export class ShareClient {
   private readonly origin: string;
@@ -132,10 +206,12 @@ export class ShareClient {
     const response = await this.send(this.origin + route, init);
 
     if (!response.ok) {
-      await response.body?.cancel();
+      if (response.status === 401 && !anonymous) {
+        await response.body?.cancel();
+        throw new ShareAuthError();
+      }
 
-      if (response.status === 401 && !anonymous) throw new ShareAuthError();
-      throw new Error(`Share request failed (${response.status}).`);
+      throw await requestError(response);
     }
 
     return readBoundedBytes(response, maxBytes);
@@ -169,14 +245,19 @@ export class ShareClient {
     });
 
     if (!response.ok) {
-      await response.body?.cancel();
-
       // A service without the JWT plugin still takes the device token.
-      if (response.status === 404 || response.status === 405)
+      if (response.status === 404 || response.status === 405) {
+        await response.body?.cancel();
+
         return { bearer: token, until: Date.now() + 10 * 60_000 };
+      }
 
-      if (response.status === 401) throw new ShareAuthError();
-      throw new Error(`Share request failed (${response.status}).`);
+      if (response.status === 401) {
+        await response.body?.cancel();
+        throw new ShareAuthError();
+      }
+
+      throw await requestError(response);
     }
 
     const { token: jwt } = jwtSchema.parse(
@@ -206,7 +287,7 @@ export class ShareClient {
   }
 
   async create(bundle: ShareBundle, requestId: string = randomUUID()) {
-    return linkSchema.parse(
+    return shareCreatedSchema.parse(
       await this.api(
         "/api/v2/shares",
         "POST",
@@ -222,7 +303,7 @@ export class ShareClient {
   }
 
   async recoverLink(shareId: string) {
-    return linkSchema.parse(
+    return shareCreatedSchema.parse(
       await this.api(`/api/v2/shares/${z.uuid().parse(shareId)}/link`),
     );
   }
@@ -231,16 +312,35 @@ export class ShareClient {
     return this.api(`/api/v2/shares/${z.uuid().parse(shareId)}`, "DELETE");
   }
 
-  /** The bundle and who shared it, read with the link's capability. */
-  async download(capability: string) {
-    const route = `/api/v2/shared/${capabilitySchema.parse(capability)}`;
+  async revisions(shareId: string): Promise<ShareRevisions> {
+    return shareRevisionsSchema.parse(
+      await this.api(
+        `/api/v2/shares/${shareIdSchema.parse(shareId)}/revisions`,
+      ),
+    );
+  }
+
+  /** Who shared a link's revision, and which revision is its latest. */
+  async shared(capability: string, revision?: string): Promise<SharedMeta> {
+    const query =
+      revision === undefined ? "" : `?rev=${shareIdSchema.parse(revision)}`;
 
-    const received = receivedSchema.parse(
-      await this.api(route, "GET", undefined, true),
+    return sharedMetaSchema.parse(
+      await this.api(
+        `/api/v2/shared/${capabilitySchema.parse(capability)}${query}`,
+        "GET",
+        undefined,
+        true,
+      ),
     );
+  }
+
+  /** The bundle of the revision the meta names, and who shared it. */
+  async download(capability: string, revision?: string) {
+    const meta = await this.shared(capability, revision);
 
     const bytes = await this.request(
-      `${route}/bundle`,
+      `/api/v2/shared/${capability}/bundle?rev=${meta.revision.id}`,
       "GET",
       undefined,
       true,
@@ -248,13 +348,10 @@ export class ShareClient {
     );
 
     return {
-      bundle: shareBundleSchema.parse(
-        parseJsonText(new TextDecoder().decode(bytes)),
-      ),
-      attribution: {
-        login: received.sender.login,
-        sharedAt: received.sharedAt,
-      },
+      bundle: parseWhiteboardFile(new TextDecoder().decode(bytes)),
+      attribution: { login: meta.sender.login, sharedAt: meta.sharedAt },
+      revision: meta.revision,
+      latest: meta.latest,
     };
   }
 }