repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

feat(mockup): preview mockups in Pi

9c49592704f7684e24cbe21e5cc70b7e48b32154

Oliver Krylow <o.krylow@isp-insoft.de> ·

SSH signature · not checked

Browse filesCompare with HEAD

Changed files (9)

CHANGELOG.md

Modified
13 13 - Add Parallel and Google WML search fallbacks; use Codex, MiniMax, Parallel, Google WML, DuckDuckGo, then Z.AI, preserving full excerpts and stopping fallback on cancellation
14 14 - Add `mise run //extensions/web:evaluate-search` to compare configured search providers live on five fixed queries, recording target rank, latency, and full results
15 15 - Reduce mockup tool context with shorter metadata while retaining on-demand HTML guidance and option limits; give interactive scripts an explicit reference to their fragment root and preserve fragment-local data scripts
16 +- Show terminal-pixel-matched animated mockup option previews directly in Pi with transparent terminal-composited backgrounds, replay them up to ten times after a one-second pause, and keep the final frame visible after playback
17 +- Show mockup HTML generation size, queue and browser-opening states, feedback readiness, and expanded server and opener timings in Pi
16 18 - Replace Web's separate tools with one compact `web` tool using `action: fetch | map | search`, validating action-specific arguments before I/O; remove legacy aliases and MiniMax image analysis, and require tool allowlists to use `web`
17 19 - Reduce Ultra's context footprint with a compact workflow tool schema while retaining strict runtime validation
18 20 - Add `mise run //:context-extensions` to discover extensions automatically and measure removal savings one at a time, including uncertain registrations; report provider input and heuristic deltas, and withhold savings when repeated controls differ
152 154 - Add a generally invocable vertical-slicing skill and require `/system exec` to use it for thin, complete, verified slices
153 155 - Prevent The System E2E tests from opening a browser
154 156 - Extract Mockup into a standalone extension while retaining System visual-asset integration
155 -- Keep one mockup page open across connected iterations with clickable live URLs, browser-open failure status, disconnected-page reopening, authenticated agent cancellation, abandoned-transport cleanup, explicit continuation prompts, and best-effort closing on acceptance
157 +- Keep one mockup page open across connected browser iterations, automatically continue in the browser after Iterate, retain clickable live URLs, report browser-open failures, reopen disconnected pages, support authenticated agent cancellation and abandoned-transport cleanup, prompt explicitly for continuation, and close best-effort on acceptance
156 158 - Fix mockups on Windows so the browser opens in the foreground through the native URL handler
157 159 - Fix mockup edge annotations so they stay contained without horizontal scrolling
158 160 - Preserve mockup iteration HTML, feedback, summaries, selection metadata, and result context in the OS cache and across compaction, while keeping only essential accepted visual assets in project bundles

extensions/mockup/__e2e__/mockup.spec.ts

Modified
5 5 type MockupServer,
6 6 startMockupServer,
7 7 } from "../mockup.ts";
8 +import {
9 + createMockupPreviewManager,
10 + renderMockupPreviewPage,
11 +} from "../mockup-preview.ts";
9 13 let server: MockupServer | undefined;
22 26 server = undefined;
29 +test("capture preview runs fragment scripts and preserves animation", async ({
30 + page,
31 +}) => {
32 + await page.setContent(
33 + renderMockupPreviewPage({
34 + title: "Preview",
35 + question: "Does it move?",
36 + options: [
37 + {
38 + id: "animated",
39 + label: "Animated",
40 + html: `<div class="dot"></div><style>.dot { width:20px; height:20px; background:red; animation:move .4s linear infinite alternate } @keyframes move { to { transform:translateX(120px) } }</style><script>(() => { const root = document.currentScript.mockupRoot; root.querySelector('.dot').dataset.ready = 'yes'; })();</script>`,
41 + },
42 + ],
43 + }),
44 + );
45 + const card = page.locator(".preview-card");
46 + await expect(card).toHaveCount(1);
47 + await expect
48 + .poll(() =>
49 + card.evaluate((element) => {
50 + const content = element.querySelector(".fragment-content");
51 + const root = content?.shadowRoot;
52 + return {
53 + ready: root?.querySelector(".dot")?.getAttribute("data-ready"),
54 + controls: document.querySelectorAll("#accept, #iterate").length,
55 + };
56 + }),
57 + )
58 + .toEqual({ ready: "yes", controls: 0 });
59 + const first = await card.screenshot({ animations: "allow" });
60 + await expect
61 + .poll(async () => {
62 + const next = await card.screenshot({ animations: "allow" });
63 + return first.equals(next);
64 + })
65 + .toBe(false);
66 +});
68 +test("grows a shared bounded canvas and reports unavoidable cropping", async ({
69 + page,
70 +}) => {
71 + await page.setContent(
72 + renderMockupPreviewPage({
73 + title: "Sizing",
74 + question: "Is all ordinary content visible?",
75 + options: [
76 + {
77 + id: "tall",
78 + label: "Tall",
79 + html: '<div style="height:420px;display:flex;align-items:flex-end"><span id="bottom">bottom</span></div>',
80 + },
81 + {
82 + id: "short",
83 + label: "Short",
84 + html: '<div style="height:100px">short</div>',
85 + },
86 + {
87 + id: "oversized",
88 + label: "Oversized",
89 + html: '<div style="height:900px">oversized</div>',
90 + },
91 + ],
92 + }),
93 + );
94 + await expect
95 + .poll(() =>
96 + page.evaluate(() => document.documentElement.dataset.mockupPreviewReady),
97 + )
98 + .toBe("true");
100 + const cards = page.locator(".preview-card");
101 + const heights = await cards.evaluateAll((elements) =>
102 + elements.map((element) => element.getBoundingClientRect().height),
103 + );
104 + expect(new Set(heights).size).toBe(1);
105 + expect(heights[0]).toBe(720);
106 + expect(await cards.nth(0).getAttribute("data-preview-cropped")).toBeNull();
107 + expect(await cards.nth(2).getAttribute("data-preview-cropped")).toBe("");
108 + const ordinaryBounds = await cards.nth(0).evaluate((card) => {
109 + const bottom = card
110 + .querySelector<HTMLElement>(".fragment-content")
111 + ?.shadowRoot?.querySelector<HTMLElement>("#bottom")
112 + ?.getBoundingClientRect();
113 + const bounds = card.getBoundingClientRect();
114 + return { bottom: bottom?.bottom, cardBottom: bounds.bottom };
115 + });
116 + expect(ordinaryBounds.bottom).toBeLessThanOrEqual(
117 + ordinaryBounds.cardBottom ?? 0,
118 + );
119 +});
121 +test("captures sharp frames and loops them after completion", async () => {
122 + const manager = createMockupPreviewManager();
123 + try {
124 + const preview = await manager.start("loop", {
125 + title: "Loop",
126 + question: "Does it repeat?",
127 + options: [
129 + id: "animated",
130 + label: "Animated",
131 + html: `<div class="dot"></div><style>.dot { width:20px; height:20px; background:red; animation:move .6s linear infinite alternate } @keyframes move { to { transform:translateX(120px) } }</style>`,
132 + },
133 + ],
134 + });
135 + const png = Buffer.from(preview.current()?.[0] ?? "", "base64");
136 + expect(png.readUInt32BE(16)).toBe(720);
138 + await preview.done;
139 + const completedVersion = preview.version();
140 + await expect
141 + .poll(() => preview.version(), { timeout: 2_500 })
142 + .toBeGreaterThan(completedVersion);
144 + await manager.start("replacement", {
145 + title: "Replacement",
146 + question: "Static?",
147 + options: [{ id: "static", label: "Static", html: "<p>Still</p>" }],
148 + });
149 + const frozenVersion = preview.version();
150 + expect(manager.get("loop")).toBe(preview);
151 + expect(preview.expired()).toBe(false);
152 + expect(preview.current()).toBeDefined();
153 + await new Promise((resolve) => setTimeout(resolve, 1_200));
154 + expect(preview.version()).toBe(frozenVersion);
155 + } finally {
156 + await manager.close();
158 +});
25 160 test("iterates in one page with live Pi progress, stop, and optional selection", async ({
27 162 }) => {

extensions/mockup/__tests__/mockup-tool.test.ts

Modified
15 15 type ExtensionContext,
16 16 initTheme,
17 17 } from "@earendil-works/pi-coding-agent";
18 +import {
19 + resetCapabilitiesCache,
20 + setCapabilities,
21 +} from "@earendil-works/pi-tui";
18 22 import { afterEach, beforeAll, describe, it, vi } from "vitest";
19 23 import type { MockupRequest, MockupResult } from "../mockup.ts";
24 +import {
25 + type MockupPreview,
26 + type MockupPreviewManager,
27 + PreviewCancelledError,
28 +} from "../mockup-preview.ts";
20 29 import {
21 30 createMockupRuntime,
22 31 formatContextCapsule,
90 99 return component.render(120).join("\n");
93 -function renderContext(expanded: boolean, lastComponent?: unknown) {
102 +function renderContext(
103 + expanded: boolean,
104 + lastComponent?: unknown,
105 + state: Partial<{
106 + isPartial: boolean;
107 + argsComplete: boolean;
108 + executionStarted: boolean;
109 + }> = {},
110 +) {
94 111 return {
95 112 expanded,
96 113 lastComponent,
97 114 isError: false,
115 + isPartial: false,
116 + argsComplete: true,
117 + executionStarted: true,
118 + ...state,
98 119 } as never;
109 130 assert.strictEqual(tool.label, "mockup");
110 - assert.strictEqual(tool.promptSnippet, "Review HTML mockups in a browser");
131 + assert.strictEqual(
132 + tool.promptSnippet,
133 + "Preview HTML mockups in Pi or review them interactively in a browser",
134 + );
111 135 assert.notStrictEqual(tool.promptSnippet, tool.description);
112 136 assert.deepStrictEqual(tool.promptGuidelines, [
113 137 "Use mockup when visual comparison beats prose for UI, layout, styling, or interaction decisions.",
147 171 assert.match(expanded, /dense Dense/);
148 172 assert.match(expanded, /calm Calm/);
149 173 assert.doesNotMatch(expanded, /<section>/);
175 + const generating = rendered(
176 + tool.renderCall(
177 + request,
178 + plainTheme(),
179 + renderContext(false, undefined, {
180 + isPartial: true,
181 + argsComplete: false,
182 + executionStarted: false,
183 + }),
184 + ),
185 + );
186 + assert.match(generating, /generating HTML · \d+ chars/);
188 + const queued = rendered(
189 + tool.renderCall(
190 + request,
191 + plainTheme(),
192 + renderContext(false, undefined, {
193 + isPartial: true,
194 + argsComplete: true,
195 + executionStarted: false,
196 + }),
197 + ),
198 + );
199 + assert.match(queued, /waiting to run/);
201 + const restored = rendered(
202 + tool.renderCall(
203 + request,
204 + plainTheme(),
205 + renderContext(false, undefined, {
206 + isPartial: false,
207 + argsComplete: false,
208 + executionStarted: false,
209 + }),
210 + ),
211 + );
212 + assert.doesNotMatch(restored, /generating|waiting to run/);
213 + });
215 + it("previews inside Pi without putting frame bytes in tool results", async () => {
216 + setCapabilities({ images: "kitty", trueColor: true, hyperlinks: true });
217 + try {
218 + let selected = 0;
219 + let startedWith: MockupRequest | undefined;
220 + const preview: MockupPreview = {
221 + labels: request.options.map((option) => option.label),
222 + done: Promise.resolve(),
223 + current: () => [
224 + "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=",
225 + "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=",
226 + ],
227 + cropped: () => [false, true],
228 + expired: () => false,
229 + version: () => 0,
230 + subscribe: () => () => undefined,
231 + close: () => undefined,
232 + };
233 + const manager: MockupPreviewManager = {
234 + start: async (_id, value) => {
235 + startedWith = value;
236 + return preview;
237 + },
238 + get: () => preview,
239 + close: async () => undefined,
240 + };
241 + const ctx = {
242 + mode: "tui",
243 + ui: {
244 + select: async () => {
245 + selected++;
246 + return "Show previews in Pi";
247 + },
248 + notify: () => undefined,
249 + },
250 + sessionManager: {
251 + getSessionId: () => "preview-session",
252 + getBranch: () => [],
253 + },
254 + } as unknown as ExtensionContext;
255 + const runtime = createMockupRuntime({ previewManager: manager });
256 + const updates: Array<{ details?: unknown }> = [];
257 + const output = await runtime.tool.execute(
258 + "preview-call",
259 + request,
260 + undefined,
261 + (update) => updates.push(update),
262 + ctx,
263 + );
265 + assert.strictEqual(selected, 1);
266 + assert.deepStrictEqual(startedWith, { ...request, multi: false });
267 + assert.deepStrictEqual(
268 + updates.map((update) => update.details),
270 + { kind: "preview", status: "starting" },
271 + { kind: "preview", status: "running" },
272 + ],
273 + );
274 + assert.deepStrictEqual(output.details, {
275 + kind: "preview",
276 + status: "complete",
277 + });
278 + assert.doesNotMatch(JSON.stringify(output), /data:image|iVBOR/);
279 + assert.strictEqual(output.terminate, true);
281 + assert.ok(runtime.tool.renderResult);
282 + const hidden = runtime.tool.renderResult(
283 + output,
284 + { expanded: false, isPartial: false },
285 + plainTheme(),
287 + ...renderContext(false),
288 + toolCallId: "preview-call",
289 + showImages: false,
290 + invalidate: () => undefined,
291 + } as never,
292 + );
293 + assert.match(rendered(hidden), /Inline image previews are disabled/);
294 + const visible = runtime.tool.renderResult(
295 + output,
296 + { expanded: false, isPartial: false },
297 + plainTheme(),
299 + ...renderContext(false, hidden),
300 + toolCallId: "preview-call",
301 + showImages: true,
302 + invalidate: () => undefined,
303 + } as never,
304 + );
305 + assert.strictEqual(visible, hidden);
306 + assert.match(rendered(visible), /\x1b_G/);
307 + assert.match(rendered(visible), /Preview cropped · use browser review/);
308 + const cancelled = runtime.tool.renderResult(
310 + content: [{ type: "text", text: "cancelled" }],
311 + details: { kind: "cancelled" },
312 + },
313 + { expanded: false, isPartial: false },
314 + plainTheme(),
316 + ...renderContext(false, visible),
317 + toolCallId: "preview-call",
318 + } as never,
319 + );
320 + assert.match(rendered(cancelled), /Mockup cancelled/);
321 + } finally {
322 + resetCapabilitiesCache();
324 + });
326 + it("does not offer browser fallback when preview startup is cancelled", async () => {
327 + setCapabilities({ images: "kitty", trueColor: true, hyperlinks: true });
328 + try {
329 + let selections = 0;
330 + let notifications = 0;
331 + const manager: MockupPreviewManager = {
332 + start: async () => {
333 + throw new PreviewCancelledError();
334 + },
335 + get: () => undefined,
336 + close: async () => undefined,
337 + };
338 + const ctx = {
339 + mode: "tui",
340 + ui: {
341 + select: async () => {
342 + selections++;
343 + return "Show previews in Pi";
344 + },
345 + notify: () => notifications++,
346 + },
347 + sessionManager: {
348 + getSessionId: () => "cancelled-preview-session",
349 + getBranch: () => [],
350 + },
351 + } as unknown as ExtensionContext;
352 + const output = await createMockupRuntime({
353 + previewManager: manager,
354 + }).tool.execute("cancelled-preview", request, undefined, undefined, ctx);
356 + assert.strictEqual(selections, 1);
357 + assert.strictEqual(notifications, 0);
358 + assert.deepStrictEqual(output.details, { kind: "cancelled" });
359 + } finally {
360 + resetCapabilitiesCache();
152 364 it("keeps feedback compact until expanded and renders errors", () => {
195 407 content: [{ type: "text", text: "Waiting for browser feedback" }],
196 408 details: {
197 409 kind: "waiting",
410 + status: "waiting",
198 411 url: "http://127.0.0.1:4321/?k=secret",
199 412 iteration: 2,
200 413 browserFailed: true,
256 469 describe("mockup runtime lifecycle", () => {
257 - it("reports every URL, reopens a disconnected page, and recovers after abandonment", async () => {
470 + it("pins active browser iterations and prompts again after abandonment", async () => {
471 + setCapabilities({ images: "kitty", trueColor: true, hyperlinks: true });
258 472 const root = await temporaryRoot();
259 473 const branch: unknown[] = [];
260 474 const opened: string[] = [];
261 475 const notifications: string[] = [];
476 + let selections = 0;
262 477 const ctx = {
478 + mode: "tui",
263 479 hasUI: true,
264 480 isIdle: () => false,
265 481 abort: () => undefined,
266 - ui: { notify: (message: string) => notifications.push(message) },
482 + ui: {
483 + notify: (message: string) => notifications.push(message),
484 + select: async () => {
485 + selections++;
486 + return "Open interactive browser";
487 + },
488 + },
267 489 sessionManager: {
268 490 getSessionId: () => "session",
269 491 getSessionFile: () => undefined,
296 518 const first = await firstExecution;
297 519 const firstDetails = first.details as MockupToolDetails;
298 520 assert.strictEqual(firstDetails.url, firstProgress.url);
521 + assert.deepStrictEqual(
522 + updates.map(
523 + (update) => (update.details as { status?: string } | undefined)?.status,
524 + ),
525 + ["opening", "waiting"],
526 + );
527 + const measuredProgress = updates.at(-1)?.details as
528 + | { timings?: { serverMs?: number; openerMs?: number } }
529 + | undefined;
530 + assert.strictEqual(typeof measuredProgress?.timings?.serverMs, "number");
531 + assert.strictEqual(typeof measuredProgress?.timings?.openerMs, "number");
299 532 assert.match(
300 533 (first.content[0] as { text: string }).text,
301 534 /Apply the feedback and call mockup again/,
361 594 secondProgress.url,
362 595 thirdProgress.url,
597 + assert.strictEqual(selections, 2);
364 598 assert.deepStrictEqual(notifications, []);
599 + resetCapabilitiesCache();

extensions/mockup/__tests__/mockup.test.ts

Modified
9 9 startMockupServer,
10 10 validateMockupRequest,
11 11 } from "../mockup.ts";
12 +import {
13 + previewDeviceScaleFactor,
14 + renderMockupPreviewPage,
15 + thinReplayFrames,
16 +} from "../mockup-preview.ts";
13 18 const client = {
14 19 userAgent: "mockup-test-browser/1",
83 88 describe("mockup page", () => {
89 + it("matches capture pixels to the terminal image dimensions", () => {
90 + const scale = previewDeviceScaleFactor(1, 174, {
91 + widthPx: 11,
92 + heightPx: 26,
93 + });
94 + assert.ok(Math.abs(scale - 880 / 680) < Number.EPSILON);
95 + });
97 + it("bounds replay memory while preserving the cycle endpoints", () => {
98 + const frames = Array.from({ length: 9 }, (_, capturedAt) => ({
99 + capturedAt,
100 + frames: ["x".repeat(10)],
101 + }));
102 + const retained = thinReplayFrames(frames, 4, 40);
104 + assert.ok(retained.length <= 4);
105 + assert.ok(
106 + retained.reduce((total, frame) => total + frame.frames[0].length, 0) <=
107 + 40,
108 + );
109 + assert.strictEqual(retained[0], frames[0]);
110 + assert.strictEqual(retained.at(-1), frames.at(-1));
111 + });
113 + it("renders a capture-only preview without interactive review controls", () => {
114 + const html = renderMockupPreviewPage(baseRequest);
115 + assert.match(html, /class="preview-card"/);
116 + assert.match(html, /class="fragment-content"/);
117 + assert.match(html, /attachShadow/);
118 + assert.match(html, /mockupRoot/);
119 + assert.match(html, /background:transparent/);
120 + assert.match(html, /\\u003csection>/);
121 + assert.doesNotMatch(html, /id="accept"|id="iterate"|api\/events/);
122 + });
84 124 it("renders fragments inside selectable cards with checkbox controls", () => {
85 125 const html = renderMockupPage(baseRequest, "tok");
86 126 assert.match(html, /type="checkbox"/);

extensions/mockup/guidance/mockup-html/SKILL.md

Modified
17 17 - Preserve the review frame's selection, notes, annotation, iterate, accept, and stop controls; the fragment supplies only the design under review.
18 18 - Use realistic labels, data, lengths, empty/error states, and constraints relevant to the decision.
19 19 - Rich interactions, scripts, and animations are allowed when they help answer the question.
20 -- Avoid frameworks and large boilerplate by default, not useful interaction.
20 +- Keep fragments concise because mockup execution waits for the complete HTML arguments; avoid frameworks and large boilerplate by default, not useful interaction.
21 21 - Prefer self-contained HTML, CSS, assets, and data.
22 22 Do not call external services unless the human approved that dependency.
23 23 The runtime does not claim to sandbox or block fragment network access.
27 27 ## Runtime boundary
29 29 Each option is rendered in its own open `ShadowRoot`, not an iframe.
30 +Pi previews use a fixed 680 CSS-pixel outer width and a shared content-aware outer height from 304 to 720 CSS pixels; content beyond that bound is visibly reported as cropped.
30 31 Scope styles to the fragment and use `:host` for root defaults; document-level selectors such as `html`, `body`, and `:root` do not describe the fragment host.
31 32 Do not query the review page globally.
32 33 Use classic inline scripts and wrap each script in an IIFE.

extensions/mockup/mockup-preview.ts

Added
new file mode 100644
1 +import type { ThemeColor } from "@earendil-works/pi-coding-agent";
2 +import {
3 + allocateImageId,
4 + type Component,
5 + getCapabilities,
6 + getCellDimensions,
7 + Image,
8 +} from "@earendil-works/pi-tui";
9 +import type { Browser, Page } from "playwright";
10 +import type { MockupRequest } from "./mockup.js";
12 +const PREVIEW_DURATION_MS = 4_000;
13 +const STATIC_OBSERVATION_MS = 600;
14 +const LOOP_PAUSE_MS = 1_000;
15 +const MAX_REPLAY_FRAME_SETS = 120;
16 +const MAX_REPLAY_BYTES = 16 * 1024 * 1024;
17 +const MAX_SNAPSHOT_BYTES = 16 * 1024 * 1024;
18 +const MAX_REPLAY_LOOPS = 10;
19 +const MAX_PLAYBACK_FPS = 30;
20 +const PREVIEW_WIDTH_PX = 680;
21 +const PREVIEW_HEIGHT_PX = 304;
22 +const MAX_PREVIEW_HEIGHT_PX = 720;
23 +const PREVIEW_BORDER_PX = 4;
25 +export type PreviewFrameSet = {
26 + capturedAt: number;
27 + frames: string[];
28 + cropped?: boolean[];
29 +};
31 +export type MockupPreview = {
32 + readonly labels: string[];
33 + readonly done: Promise<void>;
34 + current(): readonly string[] | undefined;
35 + cropped(): readonly boolean[];
36 + expired(): boolean;
37 + version(): number;
38 + subscribe(listener: () => void): () => void;
39 + close(): void;
40 +};
42 +export type MockupPreviewManager = {
43 + start(
44 + id: string,
45 + request: MockupRequest,
46 + signal?: AbortSignal,
47 + ): Promise<MockupPreview>;
48 + get(id: string): MockupPreview | undefined;
49 + close(): Promise<void>;
50 +};
52 +export class PreviewCancelledError extends Error {
53 + constructor() {
54 + super("mockup preview cancelled");
55 + this.name = "PreviewCancelledError";
56 + }
59 +export function createMockupPreviewManager(): MockupPreviewManager {
60 + const previews = new Map<string, PreviewSession>();
61 + let browser: Browser | undefined;
62 + let browserPromise: Promise<Browser> | undefined;
63 + let generation = 0;
64 + let managerClosed = false;
66 + const acquireBrowser = async (): Promise<Browser> => {
67 + if (managerClosed) throw new PreviewCancelledError();
68 + if (browser?.isConnected()) return browser;
69 + const launch =
70 + browserPromise ??
71 + import("playwright").then(({ chromium }) =>
72 + chromium.launch({ headless: true, timeout: 10_000 }),
73 + );
74 + browserPromise = launch;
75 + try {
76 + const candidate = await launch;
77 + if (managerClosed) {
78 + await candidate.close().catch(() => undefined);
79 + throw new PreviewCancelledError();
80 + }
81 + browser = candidate;
82 + return candidate;
83 + } finally {
84 + if (browserPromise === launch) browserPromise = undefined;
85 + }
86 + };
88 + const pruneSnapshots = (): void => {
89 + let bytes = [...previews.values()].reduce(
90 + (total, preview) => total + preview.snapshotBytes(),
91 + 0,
92 + );
93 + for (const preview of previews.values()) {
94 + if (bytes <= MAX_SNAPSHOT_BYTES) break;
95 + bytes -= preview.snapshotBytes();
96 + preview.close();
97 + }
98 + };
100 + return {
101 + async start(id, request, signal) {
102 + const owner = ++generation;
103 + for (const preview of previews.values()) preview.freeze();
104 + pruneSnapshots();
105 + const assertActive = () => {
106 + if (managerClosed || signal?.aborted || owner !== generation)
107 + throw new PreviewCancelledError();
108 + };
109 + assertActive();
110 + const activeBrowser = await acquireBrowser();
111 + assertActive();
112 + const page = await activeBrowser.newPage({
113 + viewport: { width: 720, height: 480 },
114 + deviceScaleFactor: previewDeviceScaleFactor(
115 + request.options.length,
116 + process.stdout.columns,
117 + ),
118 + });
119 + const abort = () => void page.close().catch(() => undefined);
120 + let preview: PreviewSession | undefined;
121 + signal?.addEventListener("abort", abort, { once: true });
122 + try {
123 + assertActive();
124 + page.setDefaultTimeout(5_000);
125 + page.setDefaultNavigationTimeout(5_000);
126 + await page.setContent(renderMockupPreviewPage(request), {
127 + waitUntil: "load",
128 + timeout: 5_000,
129 + });
130 + await page.waitForFunction(
131 + () => document.documentElement.dataset.mockupPreviewReady === "true",
132 + undefined,
133 + { timeout: 5_000 },
134 + );
135 + assertActive();
136 + preview = new PreviewSession(request, page, () => {
137 + if (previews.get(id) === preview) previews.delete(id);
138 + });
139 + await preview.start();
140 + assertActive();
141 + previews.set(id, preview);
142 + return preview;
143 + } catch (error) {
144 + preview?.close();
145 + await page.close().catch(() => undefined);
146 + if (signal?.aborted || owner !== generation || managerClosed)
147 + throw new PreviewCancelledError();
148 + throw error;
149 + } finally {
150 + signal?.removeEventListener("abort", abort);
152 + },
153 + get: (id) => previews.get(id),
154 + async close() {
155 + managerClosed = true;
156 + generation++;
157 + for (const preview of previews.values()) preview.close();
158 + previews.clear();
159 + const launching = browserPromise;
160 + if (launching)
161 + await launching.then((value) => value.close()).catch(() => undefined);
162 + await browser?.close().catch(() => undefined);
163 + browser = undefined;
164 + },
165 + };
168 +class PreviewSession implements MockupPreview {
169 + readonly labels: string[];
170 + readonly done: Promise<void>;
171 + private readonly listeners = new Set<() => void>();
172 + private readonly resolveDone: () => void;
173 + private readonly rejectDone: (error: Error) => void;
174 + private recording: PreviewFrameSet[] = [];
175 + private recordingDurationMs = 0;
176 + private currentFrames: string[] | undefined;
177 + private currentCropped: boolean[] = [];
178 + private currentVersion = 0;
179 + private completedReplayLoops = 0;
180 + private disposed = false;
181 + private frozen = false;
182 + private doneSettled = false;
183 + private replayTimer: NodeJS.Timeout | undefined;
185 + constructor(
186 + private readonly request: MockupRequest,
187 + private readonly page: Page,
188 + private readonly onClose: () => void,
189 + ) {
190 + this.labels = request.options.map((option) => option.label);
191 + let resolveDone!: () => void;
192 + let rejectDone!: (error: Error) => void;
193 + this.done = new Promise<void>((resolve, reject) => {
194 + resolveDone = resolve;
195 + rejectDone = reject;
196 + });
197 + this.resolveDone = resolveDone;
198 + this.rejectDone = rejectDone;
201 + async start(): Promise<void> {
202 + const first = await this.capture();
203 + this.present(first);
204 + void this.produce(first).then(
205 + () => this.finish(),
206 + (error) =>
207 + this.finish(error instanceof Error ? error : new Error(String(error))),
208 + );
211 + current(): readonly string[] | undefined {
212 + return this.currentFrames;
215 + cropped(): readonly boolean[] {
216 + return this.currentCropped;
219 + expired(): boolean {
220 + return this.disposed;
223 + version(): number {
224 + return this.currentVersion;
227 + subscribe(listener: () => void): () => void {
228 + this.listeners.clear();
229 + this.listeners.add(listener);
230 + return () => this.listeners.delete(listener);
233 + snapshotBytes(): number {
234 + return this.frozen && this.currentFrames
235 + ? this.currentFrames.reduce((total, image) => total + image.length, 0)
236 + : 0;
239 + freeze(): void {
240 + if (this.disposed || this.frozen) return;
241 + this.frozen = true;
242 + if (this.replayTimer) clearTimeout(this.replayTimer);
243 + this.replayTimer = undefined;
244 + const final = this.recording.at(-1);
245 + if (final) this.present(final);
246 + this.recording = [];
247 + void this.page.close().catch(() => undefined);
248 + if (!this.doneSettled) {
249 + this.doneSettled = true;
250 + this.resolveDone();
254 + close(): void {
255 + if (this.disposed) return;
256 + this.freeze();
257 + this.disposed = true;
258 + this.currentFrames = undefined;
259 + this.currentVersion++;
260 + for (const listener of this.listeners) listener();
261 + this.listeners.clear();
262 + void this.page.close().catch(() => undefined);
263 + if (!this.doneSettled) {
264 + this.doneSettled = true;
265 + this.resolveDone();
267 + this.onClose();
270 + private async produce(first: PreviewFrameSet): Promise<void> {
271 + const startedAt = performance.now();
272 + this.retain(first);
273 + let previous = first;
274 + let sawChange = false;
275 + while (
276 + !this.disposed &&
277 + !this.frozen &&
278 + performance.now() - startedAt < PREVIEW_DURATION_MS
279 + ) {
280 + const untilNextFrame =
281 + 1000 / MAX_PLAYBACK_FPS - (performance.now() - previous.capturedAt);
282 + if (untilNextFrame > 0)
283 + await new Promise((resolve) => setTimeout(resolve, untilNextFrame));
284 + const next = await this.capture();
285 + if (this.disposed || this.frozen) return;
286 + if (
287 + !sameFrames(previous.frames, next.frames) ||
288 + !sameFlags(previous.cropped, next.cropped)
289 + ) {
290 + sawChange = true;
291 + this.retain(next);
292 + this.present(next);
294 + previous = next;
295 + if (!sawChange && performance.now() - startedAt >= STATIC_OBSERVATION_MS)
296 + break;
298 + this.recordingDurationMs = previous.capturedAt - first.capturedAt;
299 + if (
300 + !this.disposed &&
301 + !this.frozen &&
302 + sawChange &&
303 + this.recording.length > 1
305 + this.scheduleReplay(0, this.endPauseMs());
308 + private async capture(): Promise<PreviewFrameSet> {
309 + const cards = this.page.locator(".preview-card");
310 + const frames: string[] = [];
311 + for (let index = 0; index < this.request.options.length; index++) {
312 + const png = await cards.nth(index).screenshot({
313 + type: "png",
314 + animations: "allow",
315 + omitBackground: true,
316 + timeout: 5_000,
317 + });
318 + frames.push(png.toString("base64"));
319 + if (
320 + frames.reduce((total, frame) => total + frame.length, 0) >
321 + MAX_REPLAY_BYTES
323 + throw new Error("Mockup preview frame set exceeds the 16 MiB limit");
325 + const cropped = await cards.evaluateAll((elements) =>
326 + elements.map((card) => {
327 + const content = card.querySelector<HTMLElement>(".fragment-content");
328 + if (!content) return false;
329 + const value =
330 + content.scrollHeight > content.clientHeight ||
331 + content.scrollWidth > content.clientWidth;
332 + card.toggleAttribute("data-preview-cropped", value);
333 + return value;
334 + }),
335 + );
336 + return { capturedAt: performance.now(), frames, cropped };
339 + private retain(frame: PreviewFrameSet): void {
340 + this.recording = thinReplayFrames([...this.recording, frame]);
343 + private scheduleReplay(index: number, delayMs: number): void {
344 + this.replayTimer = setTimeout(() => {
345 + this.replayTimer = undefined;
346 + if (this.disposed || this.frozen) return;
347 + const frame = this.recording[index];
348 + if (!frame) return;
349 + this.present(frame);
350 + const nextIndex = index + 1;
351 + if (nextIndex >= this.recording.length) {
352 + this.completedReplayLoops++;
353 + if (this.completedReplayLoops < MAX_REPLAY_LOOPS)
354 + this.scheduleReplay(0, this.endPauseMs());
355 + return;
357 + const next = this.recording[nextIndex];
358 + this.scheduleReplay(
359 + nextIndex,
360 + Math.max(1000 / MAX_PLAYBACK_FPS, next.capturedAt - frame.capturedAt),
361 + );
362 + }, delayMs);
363 + this.replayTimer.unref?.();
366 + private endPauseMs(): number {
367 + const final = this.recording.at(-1);
368 + const first = this.recording[0];
369 + const uncapturedTail =
370 + first && final
371 + ? Math.max(
372 + 0,
373 + this.recordingDurationMs - (final.capturedAt - first.capturedAt),
375 + : 0;
376 + return uncapturedTail + LOOP_PAUSE_MS;
379 + private present(frame: PreviewFrameSet): void {
380 + this.currentFrames = frame.frames;
381 + this.currentCropped = frame.cropped ?? [];
382 + this.currentVersion++;
383 + for (const listener of this.listeners) listener();
386 + private finish(error?: Error): void {
387 + if (this.disposed || this.doneSettled) return;
388 + this.doneSettled = true;
389 + void this.page.close().catch(() => undefined);
390 + if (error) this.rejectDone(error);
391 + else this.resolveDone();
395 +export class MockupPreviewComponent implements Component {
396 + private imageIds: number[];
397 + private readonly unsubscribe: () => void;
398 + private cachedLines: string[] | undefined;
399 + private complete = false;
400 + private cachedVersion = -1;
401 + private cachedWidth = -1;
403 + constructor(
404 + private readonly preview: MockupPreview,
405 + private color: (style: ThemeColor, text: string) => string,
406 + private requestRender: () => void,
407 + private showImages: boolean,
408 + ) {
409 + this.imageIds = preview.labels.map(() => allocateImageId());
410 + this.unsubscribe = preview.subscribe(() => {
411 + this.invalidate();
412 + this.requestRender();
413 + });
416 + update(
417 + color: (style: ThemeColor, text: string) => string,
418 + requestRender: () => void,
419 + showImages: boolean,
420 + ): void {
421 + this.color = color;
422 + this.requestRender = requestRender;
423 + if (this.showImages !== showImages) {
424 + this.showImages = showImages;
425 + this.invalidate();
429 + settle(): void {
430 + if (this.complete) return;
431 + this.complete = true;
432 + this.imageIds = this.preview.labels.map(() => allocateImageId());
433 + this.invalidate();
436 + render(width: number): string[] {
437 + const version = this.preview.version();
438 + if (
439 + this.cachedLines &&
440 + this.cachedVersion === version &&
441 + this.cachedWidth === width
443 + return this.cachedLines;
444 + if (this.preview.expired()) {
445 + this.cachedLines = [this.color("muted", "Preview expired.")];
446 + return this.cachedLines;
448 + if (!this.showImages || !getCapabilities().images) {
449 + this.cachedLines = [
450 + this.color("warning", "Inline image previews are disabled."),
451 + ];
452 + return this.cachedLines;
454 + const frames = this.preview.current();
455 + if (!frames) {
456 + this.cachedLines = [this.color("accent", "Preparing previews…")];
457 + return this.cachedLines;
459 + const cropped = this.preview.cropped();
460 + const maxHeightCells =
461 + frames.length === 1 ? 20 : frames.length === 2 ? 12 : 8;
462 + const lines: string[] = [];
463 + for (let index = 0; index < frames.length; index++) {
464 + if (index > 0) lines.push("");
465 + lines.push(
466 + this.color(
467 + "accent",
468 + this.preview.labels[index] ?? `Option ${index + 1}`,
469 + ),
470 + );
471 + if (cropped[index])
472 + lines.push(
473 + this.color("warning", "Preview cropped · use browser review"),
474 + );
475 + const image = new Image(
476 + frames[index] ?? "",
477 + "image/png",
478 + { fallbackColor: (text) => this.color("muted", text) },
480 + imageId: this.imageIds[index],
481 + maxWidthCells: Math.min(80, Math.max(1, width - 2)),
482 + maxHeightCells,
483 + },
484 + );
485 + lines.push(...image.render(width));
487 + this.cachedLines = lines;
488 + this.cachedVersion = version;
489 + this.cachedWidth = width;
490 + return lines;
493 + invalidate(): void {
494 + this.cachedLines = undefined;
495 + this.cachedVersion = -1;
496 + this.cachedWidth = -1;
499 + dispose(): void {
500 + this.unsubscribe();
504 +export function renderMockupPreviewPage(request: MockupRequest): string {
505 + const cards = request.options
506 + .map(
507 + (option) => `<article class="preview-card">
508 +<div class="fragment-content"></div>
509 +<script type="application/json" class="fragment-html">${jsonScript(option.html)}</script>
510 +</article>`,
512 + .join("\n");
513 + return `<!doctype html>
514 +<html lang="en">
515 +<head>
516 +<meta charset="utf-8">
517 +<style>
518 +:root { color-scheme:dark light; --text:#ededed; --muted:#9a9a9a; --line:#ededed; font:14px/1.45 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; }
519 +@media (prefers-color-scheme:light) { :root { --text:#151515; --muted:#666; --line:#151515; } }
520 +* { box-sizing:border-box; }
521 +html,body { margin:0; width:720px; background:transparent; color:var(--text); }
522 +body { padding:20px; display:grid; gap:20px; }
523 +.preview-card { width:680px; border:2px solid var(--line); background:transparent; overflow:hidden; }
524 +.fragment-content { display:block; width:676px; min-height:300px; padding:16px; overflow:visible; }
525 +</style>
526 +</head>
527 +<body>${cards}
528 +<script>
529 +(() => {
530 + document.querySelectorAll('.preview-card').forEach(card => {
531 + const content = card.querySelector('.fragment-content');
532 + const data = card.querySelector('.fragment-html');
533 + const root = content.attachShadow({ mode:'open' });
534 + root.innerHTML = JSON.parse(data.textContent || '""');
535 + root.querySelectorAll('script').forEach(old => {
536 + const script = document.createElement('script');
537 + [...old.attributes].forEach(attr => script.setAttribute(attr.name, attr.value));
538 + script.textContent = old.textContent;
539 + Object.defineProperty(script, 'mockupRoot', { value:root });
540 + const pending = Boolean(script.src) || script.type === 'module';
541 + if (pending) {
542 + script.addEventListener('load', () => script.remove(), { once:true });
543 + script.addEventListener('error', () => script.remove(), { once:true });
545 + document.head.append(script);
546 + if (!pending) script.remove();
547 + });
548 + data.remove();
549 + });
550 + requestAnimationFrame(() => requestAnimationFrame(() => {
551 + const contents = [...document.querySelectorAll('.fragment-content')];
552 + const maximumContentHeight = ${MAX_PREVIEW_HEIGHT_PX - PREVIEW_BORDER_PX};
553 + const commonHeight = Math.min(
554 + maximumContentHeight,
555 + Math.max(300, ...contents.map(content => Math.ceil(content.getBoundingClientRect().height))),
556 + );
557 + contents.forEach(content => {
558 + content.style.height = commonHeight + 'px';
559 + content.style.overflow = 'hidden';
560 + const cropped = content.scrollHeight > content.clientHeight || content.scrollWidth > content.clientWidth;
561 + content.parentElement.toggleAttribute('data-preview-cropped', cropped);
562 + });
563 + document.documentElement.dataset.mockupPreviewReady = 'true';
564 + }));
565 +})();
566 +</script>
567 +</body>
568 +</html>`;
571 +export function previewDeviceScaleFactor(
572 + optionCount: number,
573 + terminalColumns = 82,
574 + cells = getCellDimensions(),
575 +): number {
576 + const maxHeightCells = optionCount === 1 ? 20 : optionCount === 2 ? 12 : 8;
577 + const widthScale =
578 + (Math.min(80, Math.max(1, terminalColumns - 2)) * cells.widthPx) /
579 + PREVIEW_WIDTH_PX;
580 + const heightScale = (maxHeightCells * cells.heightPx) / PREVIEW_HEIGHT_PX;
581 + return Math.min(2, Math.max(0.5, Math.min(widthScale, heightScale)));
584 +export function thinReplayFrames(
585 + frames: readonly PreviewFrameSet[],
586 + maxFrames = MAX_REPLAY_FRAME_SETS,
587 + maxBytes = MAX_REPLAY_BYTES,
588 +): PreviewFrameSet[] {
589 + let retained = [...frames];
590 + let bytes = retained.reduce((total, frame) => total + frameBytes(frame), 0);
591 + while (
592 + (retained.length > maxFrames || bytes > maxBytes) &&
593 + retained.length > 1
594 + ) {
595 + if (retained.length === 2) {
596 + retained = [retained[1]];
597 + } else {
598 + const last = retained.at(-1);
599 + retained = retained.filter((_, index) => index % 2 === 0);
600 + if (last && retained.at(-1) !== last) retained.push(last);
602 + bytes = retained.reduce((total, frame) => total + frameBytes(frame), 0);
604 + return bytes <= maxBytes ? retained : [];
607 +function frameBytes(frame: PreviewFrameSet): number {
608 + return frame.frames.reduce((total, image) => total + image.length, 0);
611 +function sameFrames(
612 + left: readonly string[] | undefined,
613 + right: readonly string[],
614 +): boolean {
615 + return (
616 + left?.length === right.length &&
617 + left.every((frame, index) => frame === right[index])
618 + );
621 +function sameFlags(
622 + left: readonly boolean[] | undefined,
623 + right: readonly boolean[] | undefined,
624 +): boolean {
625 + return (
626 + left?.length === right?.length &&
627 + (left?.every((flag, index) => flag === right?.[index]) ?? true)
628 + );
631 +function jsonScript(value: string): string {
632 + return JSON.stringify(value).replaceAll("<", "\\u003c");

extensions/mockup/mockup-tool.ts

Modified
24 24 startMockupServer,
25 25 validateMockupRequest,
26 26 } from "./mockup.js";
27 +import {
28 + createMockupPreviewManager,
29 + MockupPreviewComponent,
30 + type MockupPreviewManager,
31 + PreviewCancelledError,
32 +} from "./mockup-preview.js";
28 34 const DESCRIPTION =
29 - "Show HTML-fragment mockups in a browser for visual review. Returns accept or iterate, selected option IDs, notes, and annotations.";
35 + "Show HTML-fragment mockups as previews in Pi or open an interactive browser review. Browser reviews return accept or iterate, selected option IDs, notes, and annotations.";
30 36 const MOCKUP_GUIDANCE_PATH = path.join(
31 37 import.meta.dirname,
32 38 "guidance",
97 103 type MockupProgressDetails = {
98 104 kind: "waiting";
105 + status: "opening" | "waiting";
99 106 url: string;
100 107 iteration: number;
101 108 browserFailed?: boolean;
109 + timings?: {
110 + serverMs?: number;
111 + openerMs?: number;
112 + };
115 +type PreviewProgressDetails = {
116 + kind: "preview";
117 + status: "starting" | "running" | "complete";
120 +type CancelledDetails = {
121 + kind: "cancelled";
104 124 type ActiveChain = {
110 130 cacheRoot?: string;
111 131 openBrowser?: boolean;
112 132 browserOpener?: (url: string) => Promise<boolean>;
133 + previewManager?: MockupPreviewManager;
115 136 export function createMockupRuntime(options: RuntimeOptions = {}) {
116 137 const active = new Map<string, ActiveChain>();
117 138 const contexts = new Map<string, ExtensionContext>();
139 + const previews = options.previewManager ?? createMockupPreviewManager();
118 140 const cacheRoot = options.cacheRoot ?? mockupCacheRoot();
119 141 const browserOpeningEnabled =
120 142 options.openBrowser ?? process.env.PI_MOCKUP_NO_OPEN !== "1";
147 169 name: "mockup",
148 170 label: "mockup",
149 171 description: DESCRIPTION,
150 - promptSnippet: "Review HTML mockups in a browser",
172 + promptSnippet:
173 + "Preview HTML mockups in Pi or review them interactively in a browser",
151 174 promptGuidelines: [
152 175 "Use mockup when visual comparison beats prose for UI, layout, styling, or interaction decisions.",
153 176 `Before creating or revising mockups, read \`${MOCKUP_GUIDANCE_PATH}\`.`,
154 177 "After mockup returns iterate, apply its feedback and call mockup again unless the human redirects or stops the review.",
156 179 parameters,
180 + renderShell: "self",
157 181 renderCall(args, theme, context) {
158 182 const text =
159 183 (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
160 - const optionCount = Array.isArray(args.options) ? args.options.length : 0;
184 + const options = Array.isArray(args.options) ? args.options : [];
185 + const optionCount = options.length;
161 186 const optionWord = `option${optionCount === 1 ? "" : "s"}`;
162 - let output = `${theme.fg("toolTitle", theme.bold("mockup"))} ${theme.fg("accent", args.title ?? "untitled")} ${theme.fg("toolOutput", `· ${optionCount} ${optionWord}${args.multi ? " · multi-select" : ""}`)}`;
187 + const htmlCharacters = options.reduce(
188 + (total, option) =>
189 + total + (typeof option.html === "string" ? option.html.length : 0),
190 + 0,
191 + );
192 + const phase =
193 + context.isPartial && !context.argsComplete
194 + ? ` · generating HTML${htmlCharacters > 0 ? ` · ${htmlCharacters} chars` : ""}`
195 + : context.isPartial && !context.executionStarted
196 + ? " · waiting to run"
197 + : "";
198 + let output = `${theme.fg("toolTitle", theme.bold("mockup"))} ${theme.fg("accent", args.title ?? "untitled")} ${theme.fg("toolOutput", `· ${optionCount} ${optionWord}${args.multi ? " · multi-select" : ""}${phase}`)}`;
163 199 if (!context.expanded) {
164 200 output += theme.fg(
165 201 "dim",
179 215 return text;
181 217 renderResult(result, { expanded, isPartial }, theme, context) {
182 - const text =
183 - (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
184 218 const details = result.details as
185 219 | Partial<MockupToolDetails>
186 220 | MockupProgressDetails
221 + | PreviewProgressDetails
222 + | CancelledDetails
187 223 | undefined;
224 + if (details && "kind" in details && details.kind === "preview") {
225 + const preview = previews.get(context.toolCallId);
226 + if (preview) {
227 + if (context.lastComponent instanceof MockupPreviewComponent) {
228 + context.lastComponent.update(
229 + (style, value) => theme.fg(style, value),
230 + context.invalidate,
231 + context.showImages,
232 + );
233 + if (details.status === "complete") context.lastComponent.settle();
234 + return context.lastComponent;
236 + return new MockupPreviewComponent(
237 + preview,
238 + (style, value) => theme.fg(style, value),
239 + context.invalidate,
240 + context.showImages,
241 + );
243 + if (details.status === "starting")
244 + return new Text(theme.fg("accent", "Preparing previews…"), 0, 0);
245 + return new Text(
246 + theme.fg(
247 + "muted",
248 + "Preview expired. Run the mockup again to render it.",
249 + ),
250 + 0,
251 + 0,
252 + );
254 + const text =
255 + context.lastComponent instanceof Text
256 + ? context.lastComponent
257 + : new Text("", 0, 0);
258 + if (details && "kind" in details && details.kind === "cancelled") {
259 + text.setText(theme.fg("muted", "Mockup cancelled."));
260 + return text;
189 263 isPartial &&
190 264 details &&
194 268 const status = details.browserFailed
195 269 ? theme.fg("warning", "Browser did not open. Open this mockup:")
196 - : theme.fg("accent", "Waiting for browser feedback");
197 - const iteration = expanded
270 + : details.status === "opening"
271 + ? theme.fg("accent", "Review ready · opening browser…")
272 + : theme.fg("accent", "Review ready · awaiting feedback");
273 + let diagnostics = expanded
198 274 ? theme.fg("dim", ` · iteration ${details.iteration}`)
200 - text.setText(`${status}${iteration}\n${linkedUrl(details.url)}`);
276 + if (expanded && details.timings) {
277 + if (details.timings.serverMs !== undefined)
278 + diagnostics += theme.fg(
279 + "dim",
280 + ` · server ${details.timings.serverMs}ms`,
281 + );
282 + if (details.timings.openerMs !== undefined)
283 + diagnostics += theme.fg(
284 + "dim",
285 + ` · opener ${details.timings.openerMs}ms`,
286 + );
288 + text.setText(`${status}${diagnostics}\n${linkedUrl(details.url)}`);
201 289 return text;
203 291 if (context.isError || !details || "kind" in details) {
247 335 const previous = latestMockupDetails(ctx);
248 336 const continuing =
249 337 previous?.sessionId === sessionId && previous.action === "iterate";
250 - let chain = active.get(sessionId);
338 + const pendingChain = active.get(sessionId);
339 + const continuingInBrowser =
340 + continuing && pendingChain?.chainId === previous.chainId;
341 + const lane = continuingInBrowser
342 + ? "browser"
343 + : await selectMockupLane(ctx, signal);
344 + if (lane === "cancel") return cancelledResult();
345 + if (pendingChain && !continuingInBrowser) {
346 + pendingChain.server.close("superseded");
347 + active.delete(sessionId);
349 + if (lane === "preview") {
350 + onUpdate?.({
351 + content: [{ type: "text", text: "Preparing mockup previews in Pi." }],
352 + details: { kind: "preview", status: "starting" },
353 + });
354 + try {
355 + const preview = await previews.start(toolCallId, request, signal);
356 + onUpdate?.({
357 + content: [{ type: "text", text: "Showing mockup previews in Pi." }],
358 + details: { kind: "preview", status: "running" },
359 + });
360 + await abortable(preview.done, signal, () => preview.close());
361 + return {
362 + content: [
364 + type: "text" as const,
365 + text: JSON.stringify({
366 + action: "previewed",
367 + next: "Wait for the human's conversational feedback. Do not infer acceptance, rejection, or selection from previewing.",
368 + }),
369 + },
370 + ],
371 + details: { kind: "preview" as const, status: "complete" as const },
372 + terminate: true,
373 + };
374 + } catch (error) {
375 + previews.get(toolCallId)?.close();
376 + if (signal?.aborted || error instanceof PreviewCancelledError)
377 + return cancelledResult();
378 + ctx.ui.notify(
379 + `Pi preview unavailable: ${error instanceof Error ? error.message : String(error)}`,
380 + "warning",
381 + );
382 + if ((await selectBrowserFallback(ctx, signal)) !== "browser")
383 + return cancelledResult();
386 + let chain = continuingInBrowser ? pendingChain : undefined;
251 387 const created = !chain;
388 + let serverMs: number | undefined;
252 389 if (!chain) {
390 + const serverStartedAt = performance.now();
253 391 chain = {
254 392 chainId: continuing ? previous.chainId : randomUUID(),
255 393 server: await startMockupServer(request, {
258 396 abortAgent: () => abortAgent(sessionId),
399 + serverMs = Math.round(performance.now() - serverStartedAt);
261 400 active.set(sessionId, chain);
263 402 const iteration = continuing ? previous.iteration + 1 : 1;
267 406 const resultPromise = created
268 407 ? chain.server.result
269 408 : chain.server.present(request);
270 - const progress = (browserFailed = false) =>
409 + let openerMs: number | undefined;
410 + const progress = (
411 + status: MockupProgressDetails["status"],
412 + browserFailed = false,
413 + ) =>
271 414 onUpdate?.({
272 415 content: [
274 417 type: "text" as const,
275 - text: `Waiting for browser feedback: ${chain.server.url}`,
418 + text:
419 + status === "opening"
420 + ? `Review ready; opening browser: ${chain.server.url}`
421 + : `Review ready; awaiting feedback: ${chain.server.url}`,
278 424 details: {
279 425 kind: "waiting" as const,
426 + status,
280 427 url: chain.server.url,
281 428 iteration,
429 + timings: {
430 + ...(serverMs !== undefined && { serverMs }),
431 + ...(openerMs !== undefined && { openerMs }),
432 + },
282 433 ...(browserFailed && { browserFailed: true }),
285 - progress();
286 - if (!connected && (await chain.server.open()) === false) progress(true);
436 + if (!connected) {
437 + progress("opening");
438 + const openerStartedAt = performance.now();
439 + const opened = await chain.server.open();
440 + openerMs = Math.round(performance.now() - openerStartedAt);
441 + progress("waiting", opened === false);
442 + } else {
443 + progress("waiting");
287 445 const result = await abortable(resultPromise, signal, () =>
288 446 chain?.server.close("aborted"),
377 535 schedulePrune(sessionId);
380 - shutdown(ctx: ExtensionContext): void {
538 + async shutdown(ctx: ExtensionContext): Promise<void> {
381 539 const sessionId = ctx.sessionManager.getSessionId();
382 540 active.get(sessionId)?.server.close("session ended");
383 541 active.delete(sessionId);
384 542 contexts.delete(sessionId);
543 + await previews.close();
385 544 schedulePrune();
549 +type MockupLane = "preview" | "browser" | "cancel";
551 +async function selectMockupLane(
552 + ctx: ExtensionContext,
553 + signal?: AbortSignal,
554 +): Promise<MockupLane> {
555 + if (ctx.mode !== "tui") return "browser";
556 + const unavailable = previewUnavailableReason();
557 + if (unavailable) {
558 + ctx.ui.notify(unavailable, "warning");
559 + return selectBrowserFallback(ctx, signal);
561 + const choice = await ctx.ui.select(
562 + "How should this mockup open?",
563 + ["Show previews in Pi", "Open interactive browser", "Cancel"],
564 + { signal },
565 + );
566 + if (choice === "Show previews in Pi") return "preview";
567 + if (choice === "Open interactive browser") return "browser";
568 + return "cancel";
571 +async function selectBrowserFallback(
572 + ctx: ExtensionContext,
573 + signal?: AbortSignal,
574 +): Promise<"browser" | "cancel"> {
575 + if (ctx.mode !== "tui") return "browser";
576 + const choice = await ctx.ui.select(
577 + "Use the interactive browser instead?",
578 + ["Open interactive browser", "Cancel"],
579 + { signal },
580 + );
581 + return choice === "Open interactive browser" ? "browser" : "cancel";
584 +function previewUnavailableReason(): string | undefined {
585 + if (!getCapabilities().images)
586 + return "This terminal does not support inline image previews.";
587 + const fullscreen = process.argv.some(
588 + (argument, index) =>
589 + argument === "--tui-mode=fullscreen" ||
590 + (argument === "--tui-mode" && process.argv[index + 1] === "fullscreen"),
591 + );
592 + if (fullscreen && getCapabilities().images === "kitty")
593 + return "Inline previews are unavailable in fullscreen mode until Pi's image redraw regression is fixed.";
594 + return undefined;
597 +function cancelledResult() {
598 + return {
599 + content: [
601 + type: "text" as const,
602 + text: JSON.stringify({
603 + action: "cancelled",
604 + next: "Do not continue the mockup review.",
605 + }),
606 + },
607 + ],
608 + details: { kind: "cancelled" as const },
609 + terminate: true,
610 + };
390 613 function latestMockupDetails(
391 614 ctx: ExtensionContext,
392 615 ): MockupToolDetails | undefined {

extensions/mockup/package.json

Modified
15 15 "@earendil-works/pi-tui": "*",
16 16 "typebox": "*"
18 + "dependencies": {
19 + "playwright": "^1.62.1"
20 + },
18 21 "devDependencies": {
19 22 "@marcfargas/pi-test-harness": "^0.6.1",
20 23 "@playwright/test": "^1.61.0",

package-lock.json

Modified
212 212 "extensions/mockup": {
213 213 "name": "@bugabinga/pi-ext-mockup",
214 214 "license": "MIT",
215 + "dependencies": {
216 + "playwright": "^1.62.1"
217 + },
215 218 "devDependencies": {
216 219 "@marcfargas/pi-test-harness": "^0.6.1",
217 220 "@playwright/test": "^1.61.0",
7019 7022 "version": "2.3.2",
7020 7023 "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz",
7021 7024 "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==",
7022 - "dev": true,
7023 7025 "hasInstallScript": true,
7024 7026 "license": "MIT",
7025 7027 "optional": true,
9535 9537 "version": "1.62.1",
9536 9538 "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.62.1.tgz",
9537 9539 "integrity": "sha512-0M+L3LAD8/nm554LOla9Ayx0j0tmFZ0FBcoQ7F1VuVHpM/XpiC8RcDzBQB8W5+hA8L22THxELzeF+2WcUzvcLg==",
9538 - "dev": true,
9539 9540 "license": "Apache-2.0",
9540 9541 "dependencies": {
9541 9542 "playwright-core": "1.62.1"
9554 9555 "version": "1.62.1",
9555 9556 "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.62.1.tgz",
9556 9557 "integrity": "sha512-wPYSwEBJY9GHraISXqyqtx0na0LpO3XEX7jNDhntbex7tzUS7kLnZsOlFruFJB4Hi/rhDMjXGqHewDZ68nYZVw==",
9557 - "dev": true,
9558 9558 "license": "Apache-2.0",
9559 9559 "bin": {
9560 9560 "playwright-core": "cli.js"