@frockbot/plugin-computer 0.2.4 → 0.3.0

package/src/client/progress.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, test } from "bun:test";
+import type { ComputerProgressViewV1 } from "../protocol.js";
+import {
+  COLD_PROVISION_PROGRESS_BUDGET_MS,
+  computerProgressFraction,
+  computerProgressFrame,
+  computerProgressRunKind,
+  UPDATE_PROGRESS_BUDGET_MS,
+} from "./progress.js";
+
+function progress(
+  provisioningIndex: number,
+  options: {
+    provisioningKind?: "provision" | "update";
+    resumed?: boolean;
+    updatedAfterMs?: number;
+  } = {},
+): ComputerProgressViewV1 {
+  const provisioningKind = options.provisioningKind ?? "provision";
+  return {
+    version: 1,
+    kind: "connect",
+    startedAt: "2026-09-03T00:00:00.000Z",
+    updatedAt: new Date(
+      Date.parse("2026-09-03T00:00:00.000Z") + (options.updatedAfterMs ?? 0),
+    ).toISOString(),
+    index: 1,
+    total: 5,
+    provisioning: {
+      version: 1,
+      kind: provisioningKind,
+      label: "Installing the browser",
+      index: provisioningIndex,
+      total: 5,
+      resumed: options.resumed ?? false,
+    },
+    steps: [
+      {
+        version: 1,
+        id: "waking",
+        label: "Waking the Computer",
+        status: "active",
+      },
+    ],
+  };
+}
+
+function projection(progressValue?: ComputerProgressViewV1) {
+  return {
+    phase: "provisioning" as const,
+    ...(progressValue ? { progress: progressValue } : {}),
+  };
+}
+
+describe("Computer progress easing", () => {
+  test("never regresses when a refreshed durable phase has a lower local eased position", () => {
+    const beforeRefresh = computerProgressFraction({
+      projection: projection(progress(1)),
+      elapsedMs: 20_000,
+    });
+    const afterRefresh = computerProgressFraction({
+      projection: projection(progress(1, { updatedAfterMs: 20_000 })),
+      elapsedMs: 21_000,
+    });
+
+    expect(beforeRefresh).toBeDefined();
+    expect(afterRefresh).toBeGreaterThanOrEqual(beforeRefresh!);
+  });
+
+  test("never eases beyond the next real provisioning boundary", () => {
+    const frame = computerProgressFrame({
+      projection: projection(progress(2)),
+      elapsedMs: COLD_PROVISION_PROGRESS_BUDGET_MS * 10,
+    });
+
+    expect(frame.fraction).toBe(frame.nextBoundary);
+    expect(frame.nextBoundary).toBeCloseTo(2 / 25);
+  });
+
+  test("a late durable phase ahead of the eased value jumps forward", () => {
+    const eased = computerProgressFraction({
+      projection: projection(progress(1)),
+      elapsedMs: 1_000,
+    });
+    const advanced = computerProgressFraction({
+      projection: projection(progress(4, { updatedAfterMs: 1_000 })),
+      elapsedMs: 1_000,
+    });
+
+    expect(eased).toBeLessThan(3 / 25);
+    expect(advanced).toBe(3 / 25);
+  });
+
+  test("durable completion snaps to 100 percent regardless of budget", () => {
+    expect(
+      computerProgressFraction({
+        projection: { phase: "ready" },
+        elapsedMs: 1,
+      }),
+    ).toBe(1);
+  });
+
+  test("a warm wake has no long-budget determinate bar", () => {
+    const warmProgress = progress(1);
+    delete warmProgress.provisioning;
+
+    expect(
+      computerProgressFrame({
+        projection: projection(warmProgress),
+        elapsedMs: 1_000,
+      }),
+    ).toEqual({ runKind: "warm-wake" });
+  });
+
+  test("updates are distinguished from cold and resumed provisions", () => {
+    const cold = projection(progress(1));
+    const resumed = projection(progress(1, { resumed: true }));
+    const update = projection(progress(1, { provisioningKind: "update" }));
+
+    expect(computerProgressRunKind(cold)).toBe("cold-provision");
+    expect(computerProgressRunKind(resumed)).toBe("resumed-provision");
+    expect(computerProgressRunKind(update)).toBe("update");
+    expect(
+      computerProgressFrame({ projection: update, elapsedMs: 0 }).remainingMs,
+    ).toBe(UPDATE_PROGRESS_BUDGET_MS / 5);
+    expect(UPDATE_PROGRESS_BUDGET_MS).toBeLessThan(
+      COLD_PROVISION_PROGRESS_BUDGET_MS,
+    );
+  });
+
+  test("top-level update progress is determinate without provisioning detail", () => {
+    const updateProgress = progress(1);
+    delete updateProgress.provisioning;
+    updateProgress.kind = "update";
+    updateProgress.total = 2;
+
+    const frame = computerProgressFrame({
+      projection: { phase: "updating", progress: updateProgress },
+      elapsedMs: 0,
+    });
+    expect(frame).toMatchObject({
+      runKind: "update",
+      fraction: 0,
+      nextBoundary: 0.5,
+      remainingMs: UPDATE_PROGRESS_BUDGET_MS / 2,
+    });
+  });
+});

package/src/client/progress.ts

@@ -0,0 +1,171 @@
+import type {
+  ComputerProgressViewV1,
+  ComputerProjectionV1,
+} from "../protocol.js";
+
+/** The midpoint of the measured two-to-three-minute cold setup expectation. */
+export const COLD_PROVISION_PROGRESS_BUDGET_MS = 150_000;
+
+/** Updates are small, in-place installs and must not imply a cold-setup wait. */
+export const UPDATE_PROGRESS_BUDGET_MS = 30_000;
+
+export type ComputerProgressRunKind =
+  "cold-provision" | "resumed-provision" | "update" | "warm-wake";
+
+export type ComputerProgressProjection = Pick<
+  ComputerProjectionV1,
+  "phase" | "progress"
+>;
+
+export interface ComputerProgressFrame {
+  runKind: ComputerProgressRunKind;
+  /** Present only when durable state provides a real phase position. */
+  fraction?: number;
+  /** The boundary of the next durable phase; easing cannot pass it. */
+  nextBoundary?: number;
+  /** Remaining presentational travel time to the next boundary. */
+  remainingMs?: number;
+}
+
+export interface ComputerProgressFractionInput {
+  projection: ComputerProgressProjection;
+  /** Elapsed time since progress.startedAt, supplied by the rendering clock. */
+  elapsedMs: number;
+}
+
+interface ProgressBounds {
+  floor: number;
+  nextBoundary: number;
+  timingStart: number;
+  timingSpan: number;
+  phaseCount: number;
+}
+
+function ordinal(index: number): number {
+  return Math.max(1, index);
+}
+
+function progressBounds(progress: ComputerProgressViewV1): ProgressBounds {
+  const outerOrdinal = ordinal(progress.index);
+  const outerFloor = (outerOrdinal - 1) / progress.total;
+  const outerSpan = 1 / progress.total;
+  const provisioning = progress.provisioning;
+
+  if (!provisioning) {
+    return {
+      floor: outerFloor,
+      nextBoundary: outerFloor + outerSpan,
+      timingStart: 0,
+      timingSpan: 1,
+      phaseCount: progress.total,
+    };
+  }
+
+  const provisioningOrdinal = ordinal(provisioning.index);
+  const phaseSpan = outerSpan / provisioning.total;
+  return {
+    floor: outerFloor + (provisioningOrdinal - 1) * phaseSpan,
+    nextBoundary: outerFloor + provisioningOrdinal * phaseSpan,
+    timingStart: outerFloor,
+    timingSpan: outerSpan,
+    phaseCount: provisioning.total,
+  };
+}
+
+function elapsedInCurrentPhase(
+  progress: ComputerProgressViewV1,
+  elapsedMs: number,
+): number {
+  const startedAt = Date.parse(progress.startedAt);
+  const updatedAt = Date.parse(progress.updatedAt);
+  const phaseStartedAfter = Math.max(0, updatedAt - startedAt);
+  return Math.max(0, elapsedMs - phaseStartedAfter);
+}
+
+export function computerProgressRunKind(
+  projection: ComputerProgressProjection,
+): ComputerProgressRunKind {
+  const progress = projection.progress;
+  const provisioning = progress?.provisioning;
+  if (
+    projection.phase === "updating" ||
+    progress?.kind === "update" ||
+    provisioning?.kind === "update"
+  ) {
+    return "update";
+  }
+  if (provisioning?.kind === "provision") {
+    return provisioning.resumed ? "resumed-provision" : "cold-provision";
+  }
+  return "warm-wake";
+}
+
+/**
+ * Projects durable phase truth into one presentational frame.
+ *
+ * The durable floor always wins. Time advances only inside the current real
+ * phase, and a run-wide time baseline prevents a refreshed projection for the
+ * same phase from moving the fill backwards. Neither path can cross the next
+ * durable boundary.
+ */
+export function computerProgressFrame({
+  projection,
+  elapsedMs,
+}: ComputerProgressFractionInput): ComputerProgressFrame {
+  const runKind = computerProgressRunKind(projection);
+  if (projection.phase === "ready") {
+    return { runKind, fraction: 1, nextBoundary: 1, remainingMs: 0 };
+  }
+
+  const progress = projection.progress;
+  if (!progress || runKind === "warm-wake") return { runKind };
+
+  const budgetMs =
+    runKind === "update"
+      ? UPDATE_PROGRESS_BUDGET_MS
+      : COLD_PROVISION_PROGRESS_BUDGET_MS;
+  const elapsed = Math.max(0, Number.isFinite(elapsedMs) ? elapsedMs : 0);
+  const bounds = progressBounds(progress);
+  const phaseBudgetMs = budgetMs / bounds.phaseCount;
+  const phaseElapsedMs = elapsedInCurrentPhase(progress, elapsed);
+  const phaseTimedFraction =
+    bounds.floor +
+    ((bounds.nextBoundary - bounds.floor) * phaseElapsedMs) / phaseBudgetMs;
+  const runTimedFraction =
+    bounds.timingStart + (bounds.timingSpan * elapsed) / budgetMs;
+  const fraction = Math.min(
+    bounds.nextBoundary,
+    Math.max(bounds.floor, phaseTimedFraction, runTimedFraction),
+  );
+
+  const phaseRemainingMs = Math.max(0, phaseBudgetMs - phaseElapsedMs);
+  const runBoundaryElapsedMs =
+    ((bounds.nextBoundary - bounds.timingStart) / bounds.timingSpan) * budgetMs;
+  const runRemainingMs = Math.max(0, runBoundaryElapsedMs - elapsed);
+
+  return {
+    runKind,
+    fraction,
+    nextBoundary: bounds.nextBoundary,
+    remainingMs:
+      fraction === bounds.nextBoundary
+        ? 0
+        : Math.round(Math.min(phaseRemainingMs, runRemainingMs)),
+  };
+}
+
+/** Pure `{ durable projection, elapsed ms } -> fraction` test seam. */
+export function computerProgressFraction(
+  input: ComputerProgressFractionInput,
+): number | undefined {
+  return computerProgressFrame(input).fraction;
+}
+
+export function computerProgressElapsedMs(
+  progress: ComputerProgressViewV1 | undefined,
+  nowMs: number,
+): number {
+  if (!progress) return 0;
+  const startedAt = Date.parse(progress.startedAt);
+  return Number.isFinite(startedAt) ? Math.max(0, nowMs - startedAt) : 0;
+}

package/src/client/state-machine.test.ts

@@ -122,7 +122,7 @@ describe("Computer client state machine", () => {
     });
   });
 
-  test("an idle strip click expands before its connect request", () => {
+  test("an idle card click expands before its connect request", () => {
     const idle = {
       ...initialComputerMachineState(),
       phase: "idle" as const,

package/src/client/styles.css

@@ -2,107 +2,6 @@
   margin: 0;
 }
 
-.computer-strip {
-  display: grid;
-  width: 100%;
-  grid-template-columns: 72px minmax(0, 1fr);
-  align-items: center;
-  gap: 10px;
-  padding: 6px;
-  border: 0;
-  border-radius: var(--frock-radius-control);
-  color: var(--frock-text);
-  background: transparent;
-  font: inherit;
-  text-align: left;
-  cursor: pointer;
-  transition: background-color var(--frock-motion-fast);
-}
-
-.computer-strip:hover:not(:disabled),
-.computer-strip:focus-visible {
-  background: var(--frock-fill-hover);
-  outline: none;
-}
-
-.computer-strip:disabled {
-  cursor: default;
-}
-
-.computer-strip-capture {
-  position: relative;
-  display: block;
-  overflow: hidden;
-  aspect-ratio: 16 / 10;
-  border: 1px solid var(--frock-border);
-  border-radius: 7px;
-  background: var(--frock-surface-subtle);
-  box-shadow: inset 0 0 0 1px var(--frock-computer-inset);
-}
-
-.computer-strip-capture img {
-  display: block;
-  width: 100%;
-  height: 100%;
-  object-fit: cover;
-}
-
-.computer-strip-placeholder {
-  position: absolute;
-  inset: 0;
-  display: grid;
-  place-items: center;
-  color: var(--frock-computer-accent-text);
-  background:
-    linear-gradient(var(--frock-computer-grid) 1px, transparent 1px),
-    linear-gradient(90deg, var(--frock-computer-grid) 1px, transparent 1px),
-    var(--frock-surface-subtle);
-  background-size: 12px 12px;
-}
-
-.computer-strip-phase {
-  display: flex;
-  min-width: 0;
-  align-items: center;
-  gap: 7px;
-  color: var(--frock-text-muted);
-  font-size: var(--frock-text-xs);
-  text-transform: capitalize;
-}
-
-.computer-strip-phase > :last-child {
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-
-.computer-strip-dot {
-  width: 7px;
-  height: 7px;
-  flex: 0 0 auto;
-  border-radius: 999px;
-  background: var(--frock-text-disabled);
-  box-shadow: 0 0 0 2px var(--frock-computer-inset);
-}
-
-.computer-strip-dot.phase-ready {
-  background: var(--frock-success);
-}
-
-.computer-strip-dot.phase-human-control,
-.computer-strip-dot.phase-taking-control {
-  background: var(--frock-computer-accent);
-}
-
-.computer-strip-dot.phase-updating {
-  background: var(--frock-warning);
-}
-
-.computer-strip-dot.phase-error,
-.computer-strip-dot.phase-disconnected {
-  background: var(--frock-danger-strong);
-}
-
 .computer-status {
   flex: 0 0 auto;
   padding: 3px 7px;
@@ -230,8 +129,27 @@ button.computer-screen {
   background-size: 18px 18px;
 }
 
+.computer-setup-expectation,
+.computer-progress-phase {
+  display: block;
+  max-width: 320px;
+  color: var(--frock-viewer-content-muted);
+  font-size: var(--frock-text-sm);
+  line-height: var(--frock-leading-normal);
+}
+
+.computer-setup-expectation {
+  margin: 6px 0 0;
+}
+
+.computer-progress-phase {
+  margin: 9px 0 0;
+  color: var(--frock-viewer-content-text);
+}
+
 .computer-progress-track {
   position: relative;
+  display: block;
   overflow: hidden;
   width: min(320px, 70vw);
   height: 4px;
@@ -242,6 +160,8 @@ button.computer-screen {
 
 .computer-progress-track > span {
   position: absolute;
+  inset-block: 0;
+  inset-inline-start: 0;
   width: 42%;
   height: 100%;
   border-radius: inherit;
@@ -249,6 +169,36 @@ button.computer-screen {
   animation: computer-progress 1.25s ease-in-out infinite;
 }
 
+.computer-progress-track.is-determinate > span {
+  animation: none;
+  transition: width 1s linear;
+}
+
+.computer-progress-track.is-css-timed > span {
+  width: 100%;
+  transform: scaleX(var(--computer-progress-from));
+  transform-origin: left;
+  animation: computer-progress-determinate var(--computer-progress-duration)
+    linear forwards;
+  transition: none;
+}
+
+.computer-progress-track-compact {
+  width: min(210px, 80%);
+  height: 3px;
+  margin: 11px 0 0;
+}
+
+.computer-screen-thumbnail .computer-setup-expectation,
+.computer-screen-thumbnail .computer-progress-phase {
+  max-width: 230px;
+  font-size: var(--frock-text-xs);
+}
+
+.computer-screen-thumbnail .computer-progress-phase {
+  margin-top: 6px;
+}
+
 .computer-progress-meta {
   display: flex;
   width: min(320px, 70vw);
@@ -309,6 +259,30 @@ button.computer-screen {
   }
 }
 
+@keyframes computer-progress-determinate {
+  from {
+    transform: scaleX(var(--computer-progress-from));
+  }
+
+  to {
+    transform: scaleX(var(--computer-progress-to));
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .computer-progress-track > span {
+    animation: none;
+  }
+
+  .computer-progress-track.is-determinate > span {
+    transition: none;
+  }
+
+  .computer-progress-track.is-css-timed > span {
+    transform: scaleX(var(--computer-progress-from));
+  }
+}
+
 .computer-mark {
   display: grid;
   width: 28px;

package/src/protocol.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import {
   ComputerProtocolDecodeError,
+  decodeComputerCommandResponse,
   decodeComputerProjectionV1,
   type ComputerProgressViewV1,
   type ComputerProjectionV1,
@@ -20,6 +21,14 @@ const projection: ComputerProjectionV1 & { progress: ComputerProgressViewV1 } =
       updatedAt: "2026-09-03T00:00:02.000Z",
       index: 2,
       total: 3,
+      provisioning: {
+        version: 1,
+        kind: "provision",
+        label: "installing the browser",
+        index: 4,
+        total: 5,
+        resumed: false,
+      },
       steps: [
         {
           version: 1,
@@ -51,6 +60,14 @@ describe("Computer projection progress", () => {
     );
   });
 
+  test("decodes the previous V1 progress shape without provisioning detail", () => {
+    const { provisioning: _provisioning, ...previous } = projection.progress;
+    expect(
+      decodeComputerProjectionV1({ ...projection, progress: previous })
+        .progress,
+    ).toEqual(previous);
+  });
+
   test("refuses malformed or extended progress at the client seam", () => {
     expect(() =>
       decodeComputerProjectionV1({
@@ -75,3 +92,23 @@ describe("Computer projection progress", () => {
     ).toThrow(ComputerProtocolDecodeError);
   });
 });
+
+describe("Computer command acceptance", () => {
+  test("keeps durable admission distinct from a terminal receipt", () => {
+    expect(
+      decodeComputerCommandResponse({
+        version: 2,
+        commandId: "connect-1",
+        type: "connect",
+        status: "accepted",
+        admittedAt: "2026-09-03T00:00:00.000Z",
+      }),
+    ).toEqual({
+      version: 2,
+      commandId: "connect-1",
+      type: "connect",
+      status: "accepted",
+      admittedAt: "2026-09-03T00:00:00.000Z",
+    });
+  });
+});