peekable 0.5.0 → 0.6.0

package/dist/api.d.ts

@@ -1,6 +1,7 @@
 import { type ShareConfig } from "./config.js";
 export declare const DEFAULT_REQUEST_TIMEOUT_MS = 15000;
 export declare const DEFAULT_UPLOAD_TIMEOUT_MS = 300000;
+export declare function sanitizeTerminalText(value: string): string;
 export declare const USER_AGENT: string;
 export declare class ApiError extends Error {
     status: number;
@@ -10,6 +11,7 @@ export declare class ApiError extends Error {
 export declare function api(config: ShareConfig, method: string, path: string, body?: unknown, opts?: {
     timeoutMs?: number;
 }): Promise<any>;
+export declare function apiBinary(config: ShareConfig, path: string): Promise<Buffer>;
 export declare function uploadVideo(config: ShareConfig, sessionId: string, opts: {
     video: Blob;
     filename: string;

package/dist/api.js

@@ -2,7 +2,7 @@ import { CLI_VERSION } from "./version.js";
 export const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
 export const DEFAULT_UPLOAD_TIMEOUT_MS = 300_000;
 const CONTROL_CHARS = new RegExp("[\\x00-\\x1f\\x7f-\\x9f]", "g");
-function sanitizeTerminalText(value) {
+export function sanitizeTerminalText(value) {
     return value.replace(CONTROL_CHARS, "").slice(0, 500);
 }
 export const USER_AGENT = `peekable-cli/${CLI_VERSION} (${process.platform}; ${process.arch}; node ${process.version})`;
@@ -31,6 +31,30 @@ export async function api(config, method, path, body, opts = {}) {
     }
     return res.json();
 }
+export async function apiBinary(config, path) {
+    const apiPath = path.startsWith("/api/") ? path.slice(4) : path;
+    const res = await fetchWithTimeout(`${config.url}/api${apiPath}`, {
+        method: "GET",
+        headers: {
+            Authorization: `Bearer ${config.api_key}`,
+            "User-Agent": USER_AGENT,
+        },
+    });
+    if (!res.ok) {
+        throw await buildApiError(res);
+    }
+    // Stored frames are server-capped at 120KB; anything past 1MB is a
+    // misbehaving server and must not be buffered into memory unbounded.
+    const declaredLength = Number(res.headers.get("content-length"));
+    if (Number.isFinite(declaredLength) && declaredLength > 1_000_000) {
+        throw new Error("frame exceeds 1MB");
+    }
+    const buffer = Buffer.from(await res.arrayBuffer());
+    if (buffer.byteLength > 1_000_000) {
+        throw new Error("frame exceeds 1MB");
+    }
+    return buffer;
+}
 export async function uploadVideo(config, sessionId, opts) {
     const form = new FormData();
     form.set("video", opts.video, opts.filename);

package/dist/commands/feedback.js

@@ -1,21 +1,65 @@
 import { Command } from "commander";
 import { requireConfig } from "../config.js";
-import { api } from "../api.js";
+import { api, apiBinary, sanitizeTerminalText } from "../api.js";
 import { CommandFailure, printCommandError } from "../command-error.js";
 import { runWithTelemetry } from "../telemetry.js";
+function formatTimecode(atS) {
+    const seconds = Number.isFinite(atS) ? Math.max(0, atS) : 0;
+    return `${Math.floor(seconds / 60)}:${String(Math.floor(seconds % 60)).padStart(2, "0")}`;
+}
+function isVideoAnnotation(annotation) {
+    return typeof annotation.comment === "string" && typeof annotation.at_s === "number";
+}
+const FRAME_URL_PATTERN = /^\/api\/sessions\/[A-Za-z0-9_-]+\/annotations\/[A-Za-z0-9_-]+\/frame$/;
+async function includeFrames(config, annotationsData) {
+    const items = Array.isArray(annotationsData.annotations)
+        ? annotationsData.annotations.flatMap((group) => Array.isArray(group.items) ? group.items : [])
+        : [];
+    const candidates = items.filter((item) => typeof item.frame_url === "string");
+    const frameItems = candidates.filter((item) => {
+        // Only canonical annotation-frame paths are fetched with the bearer key —
+        // a server response must not be able to steer the CLI at other endpoints.
+        if (FRAME_URL_PATTERN.test(item.frame_url))
+            return true;
+        item.frame_jpeg = null;
+        console.error(`Warning: skipping unexpected frame_url ${sanitizeTerminalText(item.frame_url)}`);
+        return false;
+    });
+    let nextIndex = 0;
+    async function worker() {
+        while (nextIndex < frameItems.length) {
+            const item = frameItems[nextIndex++];
+            try {
+                const frame = await apiBinary(config, item.frame_url);
+                item.frame_jpeg = `data:image/jpeg;base64,${frame.toString("base64")}`;
+            }
+            catch {
+                item.frame_jpeg = null;
+                console.error(`Warning: failed to fetch frame ${sanitizeTerminalText(item.frame_url)}`);
+            }
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(4, frameItems.length) }, () => worker()));
+}
 export const feedbackCommand = new Command("feedback")
     .argument("<session-id>", "Session ID")
     .description("Fetch feedback for a session")
     .option("--json", "Output JSON")
+    .option("--include-frames", "Inline frame JPEGs as data URIs (requires --json)")
     .action(async (sessionId, opts) => {
     await runWithTelemetry("feedback", async () => {
         try {
+            if (opts.includeFrames && !opts.json) {
+                throw new Error("--include-frames requires --json");
+            }
             const config = requireConfig();
             const [eventsData, annotationsData] = await Promise.all([
                 api(config, "GET", `/sessions/${sessionId}/feedback`),
                 api(config, "GET", `/sessions/${sessionId}/annotations`).catch(() => ({ annotations: [] })),
             ]);
             if (opts.json) {
+                if (opts.includeFrames)
+                    await includeFrames(config, annotationsData);
                 console.log(JSON.stringify({ ...eventsData, ...annotationsData }));
                 return;
             }
@@ -42,6 +86,15 @@ export const feedbackCommand = new Command("feedback")
                 for (const group of annotationsData.annotations) {
                     console.log(`\n--- Version ${group.version} ---`);
                     for (const ann of group.items) {
+                        if (isVideoAnnotation(ann)) {
+                            const layer = sanitizeTerminalText(typeof ann.resolved?.layer === "string" ? ann.resolved.layer : "(unresolved)");
+                            const status = ann.status === "addressed" && typeof ann.addressed_in === "number"
+                                ? `addressed in v${ann.addressed_in}`
+                                : sanitizeTerminalText(typeof ann.status === "string" ? ann.status : "");
+                            console.log(`  [${formatTimecode(ann.at_s)}] ${layer} — ${status}`);
+                            console.log(`    "${sanitizeTerminalText(ann.comment)}"`);
+                            continue;
+                        }
                         const who = ann.viewer ?? "Anonymous";
                         const elementName = ann.element_name || "Unknown";
                         const selector = ann.selector || "";

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const CLI_VERSION = "0.5.0";
+export declare const CLI_VERSION = "0.6.0";

package/dist/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "0.5.0";
+export const CLI_VERSION = "0.6.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peekable",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "Share HTML mockups with collaborators — CLI for peekable-server",
   "bin": {

package/skill/SKILL.md

@@ -218,6 +218,7 @@ Video items come back in the same `peekable feedback <id> --json` payload as can
   },
   "comment": "unreadable at phone size — make it bigger",
   "status": "pending",                      // pending | resolved | addressed
+  "addressed_in": null,                    // always present; version that addressed it
   "frame_url": "/api/sessions/<id>/annotations/a_01j9x4kq/frame"
 }
 ```
@@ -243,3 +244,9 @@ The rule is an array of server annotation IDs:
 >   per-layer rather than per-item.
 
 Always use server annotation `id` values from `peekable feedback --json` in the array. If those IDs are unknown, use the layer-granularity fallback; it means the layer changed in response to feedback, not that a particular item was addressed.
+
+> an item whose id (or layer, in fallback) appears in the new manifest's `changed_by` renders as 'addressed in vN'
+
+Video items always include `addressed_in`; it is the addressing version when `status` is `addressed`, otherwise `null`.
+
+The non-JSON feedback view renders video comments with timecodes. Frame bytes remain by reference through `frame_url`; use `peekable feedback <id> --json --include-frames` to inline each frame as an item's `frame_jpeg` data URI.