nudge-ui 0.2.0 → 0.2.2

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"]))