nudge-ui 0.2.0 → 0.2.1

package/dist/internal/agent-protocol.d.ts

@@ -6,7 +6,7 @@
  * imports. Hosts can use the same validation and message shapes without
  * pulling the companion into a browser bundle.
  */
-export declare const AGENT_PROTOCOL_VERSION: 1;
+export declare const AGENT_PROTOCOL_VERSION: 2;
 export declare const AGENT_PROTOCOL_LIMITS: {
     readonly projectId: 256;
     readonly workspaceRoot: 4096;
@@ -14,7 +14,21 @@ export declare const AGENT_PROTOCOL_LIMITS: {
     readonly sessionToken: 256;
     readonly requestId: 256;
     readonly commandId: 256;
+    readonly clientDispatchId: 256;
     readonly prompt: 32000;
+    readonly sketchId: 256;
+    readonly sketchRevision: 2147483647;
+    readonly sketchFilename: 256;
+    readonly sketchDescription: 2000;
+    readonly sketchCount: 4;
+    readonly sketchImageBytes: number;
+    readonly sketchTotalBytes: number;
+    readonly sketchEncodedBytes: number;
+    readonly sketchAnnotationCount: 50;
+    readonly sketchUrl: 2048;
+    readonly sketchTitle: 512;
+    readonly sketchFramework: 128;
+    readonly sketchHost: 128;
     readonly groupId: 256;
     readonly label: 160;
     readonly routeUrl: 2048;
@@ -108,6 +122,47 @@ export interface AgentPromptRequest {
     readonly prompt: string;
     /** The browser's canonical change revision captured at dispatch time. */
     readonly changeRevision?: number;
+    /** Correlates the durable browser handoff batch across a lost response. */
+    readonly clientDispatchId?: string;
+    /** Metadata for the exact sketch revisions included in this request. */
+    readonly sketches?: readonly AgentSketchMetadata[];
+}
+export interface AgentSketchCaptureMetadata {
+    readonly url: string;
+    readonly title: string;
+    readonly timestamp: number;
+    readonly viewportWidth: number;
+    readonly viewportHeight: number;
+    readonly scrollX: number;
+    readonly scrollY: number;
+    readonly devicePixelRatio: number;
+    readonly host: string;
+    readonly framework: string;
+}
+export interface AgentSketchAnnotation {
+    readonly number: number;
+    readonly description: string;
+}
+/** Metadata retained in statuses and acknowledgements without image bytes. */
+export interface AgentSketchMetadata {
+    readonly id: string;
+    readonly revision: number;
+    readonly filename: string;
+    readonly mimeType: "image/png";
+    readonly width: number;
+    readonly height: number;
+    readonly byteSize: number;
+    readonly capture: AgentSketchCaptureMetadata;
+    readonly description?: string;
+    readonly annotations?: readonly AgentSketchAnnotation[];
+}
+/** The only protocol shape that carries screenshot bytes. */
+export interface AgentSketchAttachment extends AgentSketchMetadata {
+    readonly data: string;
+}
+/** Internal companion delivery shape; attachment bytes are never status data. */
+export interface AgentDeliveredPrompt extends AgentPromptRequest {
+    readonly attachments?: readonly AgentSketchAttachment[];
 }
 export type AgentRequestStatus = "working" | "completed" | "failed" | "interrupted";
 export interface AgentRequestOutcome {
@@ -166,6 +221,8 @@ export interface CanvasCommandAcknowledgement {
 export interface PairingRequest {
     readonly projectId: string;
     readonly origin: string;
+    /** Reuses an existing pairing across a same-browser reload. */
+    readonly sessionToken?: string;
     /** The active page is retained only while this process is alive. */
     readonly pageUrl?: string;
 }
@@ -182,6 +239,8 @@ export interface PromptDispatchRequest {
     readonly sessionToken: string;
     readonly prompt: string;
     readonly changeRevision?: number;
+    readonly clientDispatchId?: string;
+    readonly attachments?: readonly AgentSketchAttachment[];
 }
 export interface PromptDispatchResponse {
     readonly request: AgentPromptRequest;
@@ -223,6 +282,11 @@ export declare function validateRoutes(value: unknown, origin: string): AgentRou
 /** Validates the fields shared by every companion message. */
 export declare function isProtocolVersion(value: unknown): value is AgentProtocolVersion;
 export declare function isProjectIdentity(value: unknown): value is AgentProjectIdentity;
+export declare function isAgentSketchCaptureMetadata(value: unknown): value is AgentSketchCaptureMetadata;
+export declare function isAgentSketchAnnotation(value: unknown): value is AgentSketchAnnotation;
+export declare function isAgentSketchMetadata(value: unknown): value is AgentSketchMetadata;
+export declare function isAgentSketchAttachment(value: unknown): value is AgentSketchAttachment;
+export declare function validateSketchAttachments(value: unknown): AgentSketchAttachment[];
 export declare function isAgentPromptRequest(value: unknown): value is AgentPromptRequest;
 export declare function isAgentStatusUpdate(value: unknown): value is AgentStatusUpdate;
 export declare function isCanvasState(value: unknown): value is CanvasState;

package/dist/internal/agent-protocol.js

@@ -6,7 +6,7 @@
  * imports. Hosts can use the same validation and message shapes without
  * pulling the companion into a browser bundle.
  */
-export const AGENT_PROTOCOL_VERSION = 1;
+export const AGENT_PROTOCOL_VERSION = 2;
 export const AGENT_PROTOCOL_LIMITS = {
     projectId: 256,
     workspaceRoot: 4096,
@@ -14,7 +14,21 @@ export const AGENT_PROTOCOL_LIMITS = {
     sessionToken: 256,
     requestId: 256,
     commandId: 256,
+    clientDispatchId: 256,
     prompt: 32_000,
+    sketchId: 256,
+    sketchRevision: 2_147_483_647,
+    sketchFilename: 256,
+    sketchDescription: 2_000,
+    sketchCount: 4,
+    sketchImageBytes: 2 * 1024 * 1024,
+    sketchTotalBytes: 8 * 1024 * 1024,
+    sketchEncodedBytes: 12 * 1024 * 1024,
+    sketchAnnotationCount: 50,
+    sketchUrl: 2_048,
+    sketchTitle: 512,
+    sketchFramework: 128,
+    sketchHost: 128,
     groupId: 256,
     label: 160,
     routeUrl: 2048,
@@ -64,6 +78,25 @@ function optionalString(value, maximum) {
 function optionalRevision(value) {
     return value === undefined || (typeof value === "number" && Number.isSafeInteger(value) && value >= 0);
 }
+function boundedNumber(value, maximum) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 && value <= maximum;
+}
+function boundedFiniteNumber(value, maximum) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= maximum;
+}
+function boundedString(value, maximum) {
+    return typeof value === "string" && value.length <= maximum;
+}
+function validBase64(value, maximum) {
+    return typeof value === "string"
+        && value.length > 0
+        && value.length <= maximum
+        && /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value);
+}
+function encodedByteLength(value) {
+    const padding = value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0;
+    return Math.max(0, Math.floor(value.length * 3 / 4) - padding);
+}
 /**
  * Returns a canonical origin or null. Credentials, paths, and fragments are
  * rejected so the browser cannot broaden the pairing boundary accidentally.
@@ -157,13 +190,160 @@ export function isProjectIdentity(value) {
         && (value.origin === undefined || isCanonicalOrigin(value.origin))
         && optionalString(value.workspaceRoot, AGENT_PROTOCOL_LIMITS.workspaceRoot);
 }
+export function isAgentSketchCaptureMetadata(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, [
+        "url",
+        "title",
+        "timestamp",
+        "viewportWidth",
+        "viewportHeight",
+        "scrollX",
+        "scrollY",
+        "devicePixelRatio",
+        "host",
+        "framework",
+    ]))
+        return false;
+    if (!nonEmptyString(value.url, AGENT_PROTOCOL_LIMITS.sketchUrl)
+        || !boundedString(value.title, AGENT_PROTOCOL_LIMITS.sketchTitle)
+        || !boundedNumber(value.timestamp, Number.MAX_SAFE_INTEGER)
+        || !boundedNumber(value.viewportWidth, 100_000)
+        || !boundedNumber(value.viewportHeight, 100_000)
+        || !boundedFiniteNumber(value.scrollX, Number.MAX_SAFE_INTEGER)
+        || !boundedFiniteNumber(value.scrollY, Number.MAX_SAFE_INTEGER)
+        || !boundedFiniteNumber(value.devicePixelRatio, 100)
+        || value.devicePixelRatio <= 0
+        || !nonEmptyString(value.host, AGENT_PROTOCOL_LIMITS.sketchHost)
+        || !nonEmptyString(value.framework, AGENT_PROTOCOL_LIMITS.sketchFramework)) {
+        return false;
+    }
+    try {
+        const url = new URL(value.url);
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            return false;
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
+export function isAgentSketchAnnotation(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, ["number", "description"]))
+        return false;
+    return boundedNumber(value.number, AGENT_PROTOCOL_LIMITS.sketchAnnotationCount)
+        && value.number >= 1
+        && nonEmptyString(value.description, AGENT_PROTOCOL_LIMITS.sketchDescription);
+}
+function validSketchAnnotationList(value) {
+    if (!Array.isArray(value)
+        || value.length > AGENT_PROTOCOL_LIMITS.sketchAnnotationCount
+        || !value.every(isAgentSketchAnnotation))
+        return false;
+    return new Set(value.map((annotation) => annotation.number)).size === value.length;
+}
+export function isAgentSketchMetadata(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, [
+        "id",
+        "revision",
+        "filename",
+        "mimeType",
+        "width",
+        "height",
+        "byteSize",
+        "capture",
+        "description",
+        "annotations",
+    ]))
+        return false;
+    return nonEmptyString(value.id, AGENT_PROTOCOL_LIMITS.sketchId)
+        && boundedNumber(value.revision, AGENT_PROTOCOL_LIMITS.sketchRevision)
+        && value.revision > 0
+        && nonEmptyString(value.filename, AGENT_PROTOCOL_LIMITS.sketchFilename)
+        && value.mimeType === "image/png"
+        && boundedNumber(value.width, 2_048)
+        && value.width > 0
+        && boundedNumber(value.height, 2_048)
+        && value.height > 0
+        && boundedNumber(value.byteSize, AGENT_PROTOCOL_LIMITS.sketchImageBytes)
+        && value.byteSize > 0
+        && isAgentSketchCaptureMetadata(value.capture)
+        && (value.description === undefined
+            || boundedString(value.description, AGENT_PROTOCOL_LIMITS.sketchDescription))
+        && (value.annotations === undefined || validSketchAnnotationList(value.annotations));
+}
+export function isAgentSketchAttachment(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, [
+        "id",
+        "revision",
+        "filename",
+        "mimeType",
+        "width",
+        "height",
+        "byteSize",
+        "capture",
+        "description",
+        "annotations",
+        "data",
+    ]) || !isAgentSketchMetadata({
+        id: value.id,
+        revision: value.revision,
+        filename: value.filename,
+        mimeType: value.mimeType,
+        width: value.width,
+        height: value.height,
+        byteSize: value.byteSize,
+        capture: value.capture,
+        ...(value.description === undefined ? {} : { description: value.description }),
+        ...(value.annotations === undefined ? {} : { annotations: value.annotations }),
+    }))
+        return false;
+    return validBase64(value.data, AGENT_PROTOCOL_LIMITS.sketchEncodedBytes)
+        && encodedByteLength(value.data) === value.byteSize;
+}
+export function validateSketchAttachments(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.length > AGENT_PROTOCOL_LIMITS.sketchCount) {
+        throw new TypeError(`attachments must contain at most ${AGENT_PROTOCOL_LIMITS.sketchCount} items`);
+    }
+    const attachments = value.map((candidate, index) => {
+        if (!isAgentSketchAttachment(candidate)) {
+            throw new TypeError(`attachments[${index}] is not a valid PNG attachment`);
+        }
+        return { ...candidate, capture: { ...candidate.capture } };
+    });
+    if (new Set(attachments.map((attachment) => `${attachment.id}\u0000${attachment.revision}`)).size
+        !== attachments.length) {
+        throw new TypeError("attachments must not contain duplicate sketch revisions");
+    }
+    const totalBytes = attachments.reduce((total, attachment) => total + attachment.byteSize, 0);
+    if (totalBytes > AGENT_PROTOCOL_LIMITS.sketchTotalBytes) {
+        throw new TypeError(`attachments must contain at most ${AGENT_PROTOCOL_LIMITS.sketchTotalBytes} decoded bytes`);
+    }
+    return attachments;
+}
+function validSketchMetadataList(value) {
+    if (!Array.isArray(value) || value.length > AGENT_PROTOCOL_LIMITS.sketchCount
+        || !value.every(isAgentSketchMetadata))
+        return false;
+    return new Set(value.map((sketch) => `${sketch.id}\u0000${sketch.revision}`)).size === value.length;
+}
 export function isAgentPromptRequest(value) {
-    if (!isRecord(value) || !hasOnlyKeys(value, ["requestId", "projectId", "prompt", "changeRevision"]))
+    if (!isRecord(value) || !hasOnlyKeys(value, [
+        "requestId",
+        "projectId",
+        "prompt",
+        "changeRevision",
+        "clientDispatchId",
+        "sketches",
+    ]))
         return false;
     return nonEmptyString(value.requestId, AGENT_PROTOCOL_LIMITS.requestId)
         && nonEmptyString(value.projectId, AGENT_PROTOCOL_LIMITS.projectId)
         && nonEmptyString(value.prompt, AGENT_PROTOCOL_LIMITS.prompt)
-        && optionalRevision(value.changeRevision);
+        && optionalRevision(value.changeRevision)
+        && (value.clientDispatchId === undefined || nonEmptyString(value.clientDispatchId, AGENT_PROTOCOL_LIMITS.clientDispatchId))
+        && (value.sketches === undefined || validSketchMetadataList(value.sketches));
 }
 export function isAgentStatusUpdate(value) {
     if (!isRecord(value) || !hasOnlyKeys(value, ["requestId", "status", "summary", "error"]))