@pasko70/pibo 1.1.0 → 1.2.0

package/dist/web-annotations/api.js

@@ -0,0 +1,348 @@
+import { randomBytes } from "node:crypto";
+import { PiboWebHttpError, readJsonBody, responseJson } from "../web/http.js";
+import { buildWebAnnotationOverlayScript, createWebAnnotationCdpService } from "./cdp.js";
+import { serializeWebAnnotationAttachment } from "./attachments.js";
+import { createDefaultWebAnnotationStore } from "./store.js";
+import { isWebAnnotationStatus, isWebAnnotationTargetKind } from "./types.js";
+import { assertWebAnnotationStatusTransition, normalizeWebAnnotationLimit, normalizeWebAnnotationScreenshotRef, normalizeWebAnnotationTarget, normalizeWebAnnotationViewport, requireWebAnnotationText, sanitizeWebAnnotationText, WEB_ANNOTATION_LIMITS, } from "./validation.js";
+export const WEB_ANNOTATIONS_API_PREFIX = "/api/web-annotations";
+export const WEB_ANNOTATIONS_APP_MOUNT = "/apps/web-annotations";
+let defaultStore;
+function getDefaultStore() {
+    defaultStore ??= createDefaultWebAnnotationStore();
+    return defaultStore;
+}
+function createSameOriginBinding(store, request, context, body) {
+    const bindingToken = randomBytes(24).toString("base64url");
+    const binding = store.createBinding({
+        ...context,
+        url: normalizeSameOriginBindingUrl(request, body.url),
+        title: optionalBodyString(body.title, WEB_ANNOTATION_LIMITS.title),
+        state: "active",
+        metadata: { source: "same-origin", overlaySubmissionToken: bindingToken },
+    });
+    return {
+        binding,
+        overlay: {
+            bindingId: binding.id,
+            bindingToken,
+            piboSessionId: binding.piboSessionId,
+            annotationShortcut: optionalBodyString(body.annotationShortcut, 80, false),
+        },
+    };
+}
+export function createWebAnnotationsWebApp(options = {}) {
+    const store = options.store ?? getDefaultStore();
+    const baseService = options.cdpService ?? createWebAnnotationCdpService({ store });
+    return {
+        name: "web-annotations",
+        mountPath: WEB_ANNOTATIONS_APP_MOUNT,
+        apiPrefix: WEB_ANNOTATIONS_API_PREFIX,
+        async handleRequest(request, context) {
+            const url = new URL(request.url);
+            if (url.pathname === `${WEB_ANNOTATIONS_APP_MOUNT}/overlay.js` && request.method === "GET") {
+                return responseJavaScript(buildWebAnnotationOverlayScript(), { headers: { "cache-control": "no-store" } });
+            }
+            if (url.pathname === WEB_ANNOTATIONS_APP_MOUNT && request.method === "GET") {
+                return responseJson({ ok: true, apiPrefix: WEB_ANNOTATIONS_API_PREFIX });
+            }
+            if (!url.pathname.startsWith(WEB_ANNOTATIONS_API_PREFIX))
+                return undefined;
+            try {
+                if (url.pathname === `${WEB_ANNOTATIONS_API_PREFIX}/submissions` && request.method === "OPTIONS") {
+                    return corsResponse(null, { status: 204 });
+                }
+                if (url.pathname === `${WEB_ANNOTATIONS_API_PREFIX}/submissions` && request.method === "POST") {
+                    const annotation = await handleOverlaySubmission(store, request);
+                    return corsJson({ ok: true, annotation }, { status: 201 });
+                }
+                const webSession = await context.requireSession({ request });
+                if (url.pathname === `${WEB_ANNOTATIONS_API_PREFIX}/targets` && request.method === "GET") {
+                    const service = serviceForRequest(baseService, url.searchParams.get("cdpUrl") ?? undefined, request, store, options);
+                    const targets = await service.listTargets();
+                    return responseJson({ ok: true, targets });
+                }
+                if (url.pathname === `${WEB_ANNOTATIONS_API_PREFIX}/bindings` && request.method === "GET") {
+                    const piboSessionId = requireQueryParam(url, "piboSessionId");
+                    const bindingContext = resolveBindingContext(context, webSession, { piboSessionId });
+                    const bindings = baseService.listBindings(bindingContext, parseLimit(url.searchParams.get("limit")));
+                    return responseJson({ ok: true, bindings });
+                }
+                if (url.pathname === `${WEB_ANNOTATIONS_API_PREFIX}/bindings` && request.method === "POST") {
+                    requireSameOriginJsonRequest(request);
+                    const body = await readJsonBody(request);
+                    const bindingContext = resolveBindingContext(context, webSession, body);
+                    const service = serviceForRequest(baseService, body.cdpUrl, request, store, options);
+                    if (body.url) {
+                        if (body.sameOrigin) {
+                            const result = createSameOriginBinding(store, request, bindingContext, body);
+                            return responseJson({ ok: true, ...result }, { status: 201 });
+                        }
+                        const result = await service.createUrlBinding({ ...bindingContext, url: body.url });
+                        return responseJson({ ok: true, ...result }, { status: 201 });
+                    }
+                    if (body.targetId) {
+                        const result = await service.createTargetBinding({ ...bindingContext, targetId: body.targetId });
+                        return responseJson({ ok: true, ...result }, { status: 201 });
+                    }
+                    throw new PiboWebHttpError("url or targetId is required", 400);
+                }
+                if (url.pathname === WEB_ANNOTATIONS_API_PREFIX && request.method === "GET") {
+                    const piboSessionId = requireQueryParam(url, "piboSessionId", "sessionId");
+                    const bindingContext = resolveBindingContext(context, webSession, { piboSessionId });
+                    const status = optionalStatus(url.searchParams.get("status"));
+                    const scope = url.searchParams.get("scope") === "app" || url.searchParams.get("allSessions") === "true" ? "app" : "session";
+                    const annotations = store.listAnnotations({
+                        ...(scope === "session" ? { piboSessionId: bindingContext.piboSessionId } : {}),
+                        status,
+                        limit: parseLimit(url.searchParams.get("limit")),
+                    }).map(serializeWebAnnotationAttachment);
+                    return responseJson({ ok: true, annotations, scope });
+                }
+                const annotationResource = matchAnnotationResource(url.pathname);
+                if (annotationResource) {
+                    if (request.method === "GET") {
+                        const piboSessionId = requireQueryParam(url, "piboSessionId", "sessionId");
+                        const bindingContext = resolveBindingContext(context, webSession, { piboSessionId });
+                        const annotation = store.getAnnotation(bindingContext.piboSessionId, annotationResource.id);
+                        if (!annotation)
+                            throw new PiboWebHttpError("Web Annotation was not found", 404);
+                        return responseJson({ ok: true, annotation });
+                    }
+                    if (request.method === "PATCH") {
+                        requireSameOriginJsonRequest(request);
+                        const body = await readJsonBody(request);
+                        const bindingContext = resolveBindingContext(context, webSession, body);
+                        const status = optionalStatus(body.status);
+                        const existing = store.getAnnotation(bindingContext.piboSessionId, annotationResource.id);
+                        if (!existing)
+                            throw new PiboWebHttpError("Web Annotation was not found", 404);
+                        try {
+                            assertWebAnnotationStatusTransition(existing.status, status);
+                        }
+                        catch (error) {
+                            throw new PiboWebHttpError(error instanceof Error ? error.message : String(error), 400);
+                        }
+                        const annotation = store.patchAnnotation(bindingContext.piboSessionId, annotationResource.id, {
+                            ...(status ? { status } : {}),
+                            ...(body.summary !== undefined ? { summary: body.summary } : {}),
+                        });
+                        if (!annotation)
+                            throw new PiboWebHttpError("Web Annotation was not found", 404);
+                        return responseJson({ ok: true, annotation: serializeWebAnnotationAttachment(annotation) });
+                    }
+                }
+                const bindingResource = matchBindingResource(url.pathname);
+                if (bindingResource) {
+                    if (request.method === "POST" && (bindingResource.action === "inject" || bindingResource.action === "reinject")) {
+                        requireSameOriginJsonRequest(request);
+                        const body = await readJsonBody(request);
+                        const bindingContext = resolveBindingContext(context, webSession, body);
+                        const service = serviceForRequest(baseService, body.cdpUrl, request, store, options);
+                        const result = await service.injectBinding(bindingContext, bindingResource.id, { annotationShortcut: optionalBodyString(body.annotationShortcut, 80, false) });
+                        return responseJson({ ok: true, ...result });
+                    }
+                    if (request.method === "POST" && bindingResource.action === "stop") {
+                        requireSameOriginJsonRequest(request);
+                        const body = await readJsonBody(request);
+                        const bindingContext = resolveBindingContext(context, webSession, body);
+                        const service = serviceForRequest(baseService, body.cdpUrl, request, store, options);
+                        const result = await service.stopBinding(bindingContext, bindingResource.id);
+                        return responseJson({ ok: true, ...result });
+                    }
+                    if (request.method === "DELETE" && !bindingResource.action) {
+                        requireSameOriginRequest(request);
+                        const piboSessionId = requireQueryParam(url, "piboSessionId");
+                        const bindingContext = resolveBindingContext(context, webSession, { piboSessionId });
+                        return responseJson({ ok: true, removed: baseService.removeBinding(bindingContext, bindingResource.id) });
+                    }
+                }
+                return undefined;
+            }
+            catch (error) {
+                if (error instanceof PiboWebHttpError)
+                    throw error;
+                const message = error instanceof Error ? error.message : String(error);
+                throw new PiboWebHttpError(message, 400);
+            }
+        },
+    };
+}
+async function handleOverlaySubmission(store, request) {
+    const contentType = request.headers.get("content-type")?.split(";")[0]?.trim().toLowerCase();
+    if (contentType !== "application/json")
+        throw new PiboWebHttpError("Content-Type must be application/json", 415);
+    const body = await readJsonBody(request);
+    const bindingId = requireBodyString(body.bindingId, "bindingId", WEB_ANNOTATION_LIMITS.id, false);
+    const bindingToken = requireBodyString(body.bindingToken, "bindingToken", WEB_ANNOTATION_LIMITS.bindingToken, false);
+    const binding = store.getBindingById(bindingId);
+    if (!binding)
+        throw new PiboWebHttpError("Web Annotation binding was not found", 404);
+    if (binding.state === "removed")
+        throw new PiboWebHttpError("Web Annotation binding was removed", 404);
+    if (binding.metadata?.overlaySubmissionToken !== bindingToken)
+        throw new PiboWebHttpError("Invalid Web Annotation binding token", 403);
+    const note = requireBodyString(body.note, "note", WEB_ANNOTATION_LIMITS.note);
+    const targetKind = requireTargetKind(body.targetKind);
+    const viewport = normalizeViewport(body.viewport);
+    return store.createAnnotation({
+        piboSessionId: binding.piboSessionId,
+        piboRoomId: binding.piboRoomId,
+        bindingId: binding.id,
+        note,
+        url: optionalBodyString(body.url, WEB_ANNOTATION_LIMITS.url, false) ?? binding.url,
+        title: optionalBodyString(body.title, WEB_ANNOTATION_LIMITS.title) ?? binding.title,
+        targetId: binding.targetId,
+        targetKind,
+        viewport,
+        target: normalizeTarget(body.target, targetKind),
+        screenshotRef: normalizeWebAnnotationScreenshotRef(body.screenshotRef),
+    });
+}
+function requireBodyString(value, field, max, redactSecrets = true) {
+    try {
+        return requireWebAnnotationText(value, { field, max, redactSecrets });
+    }
+    catch (error) {
+        throw new PiboWebHttpError(error instanceof Error ? error.message : String(error), 400);
+    }
+}
+function optionalBodyString(value, max, redactSecrets = true) {
+    try {
+        return sanitizeWebAnnotationText(value, { field: "field", max, redactSecrets });
+    }
+    catch (error) {
+        throw new PiboWebHttpError(error instanceof Error ? error.message : String(error), 400);
+    }
+}
+function normalizeSameOriginBindingUrl(request, value) {
+    const raw = requireBodyString(value, "url", WEB_ANNOTATION_LIMITS.url, false);
+    const requestOrigin = new URL(request.url).origin;
+    let parsed;
+    try {
+        parsed = new URL(raw, requestOrigin);
+    }
+    catch {
+        throw new PiboWebHttpError("url must be a valid URL", 400);
+    }
+    if (parsed.origin !== requestOrigin)
+        throw new PiboWebHttpError("same-origin annotations require a URL on this Pibo web origin", 400);
+    return parsed.href;
+}
+function requireTargetKind(value) {
+    if (!value || !isWebAnnotationTargetKind(value))
+        throw new PiboWebHttpError("Invalid annotation target kind", 400);
+    return value;
+}
+function normalizeViewport(value) {
+    if (!value || typeof value.width !== "number" || typeof value.height !== "number")
+        throw new PiboWebHttpError("viewport width and height are required", 400);
+    try {
+        return normalizeWebAnnotationViewport(value);
+    }
+    catch (error) {
+        throw new PiboWebHttpError(error instanceof Error ? error.message : String(error), 400);
+    }
+}
+function normalizeTarget(value, targetKind) {
+    if (value === undefined)
+        return { kind: targetKind };
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new PiboWebHttpError("target must be an object", 400);
+    try {
+        return normalizeWebAnnotationTarget({ ...value, kind: targetKind }, targetKind);
+    }
+    catch (error) {
+        throw new PiboWebHttpError(error instanceof Error ? error.message : String(error), 400);
+    }
+}
+function responseJavaScript(source, init = {}) {
+    return new Response(source, {
+        ...init,
+        headers: {
+            "content-type": "text/javascript; charset=utf-8",
+            ...init.headers,
+        },
+    });
+}
+function corsJson(payload, init = {}) {
+    return responseJson(payload, { ...init, headers: corsHeaders(init.headers) });
+}
+function corsResponse(body, init = {}) {
+    return new Response(body, { ...init, headers: corsHeaders(init.headers) });
+}
+function corsHeaders(existing) {
+    return {
+        "access-control-allow-origin": "*",
+        "access-control-allow-methods": "POST, OPTIONS",
+        "access-control-allow-headers": "content-type",
+        ...Object.fromEntries(new Headers(existing).entries()),
+    };
+}
+function requireSameOriginJsonRequest(request) {
+    const contentType = request.headers.get("content-type")?.split(";")[0]?.trim().toLowerCase();
+    if (contentType !== "application/json")
+        throw new PiboWebHttpError("Content-Type must be application/json", 415);
+    requireSameOriginRequest(request);
+}
+function requireSameOriginRequest(request) {
+    const origin = request.headers.get("origin");
+    if (!origin)
+        throw new PiboWebHttpError("Origin header is required", 403);
+    if (origin !== new URL(request.url).origin)
+        throw new PiboWebHttpError("Origin is not allowed", 403);
+}
+function serviceForRequest(baseService, cdpUrl, request, store, options) {
+    if (options.cdpService)
+        return baseService;
+    return createWebAnnotationCdpService({ store, cdpUrl, apiBaseUrl: new URL(request.url).origin });
+}
+function resolveBindingContext(context, _webSession, input) {
+    const piboSessionId = input.piboSessionId?.trim();
+    if (!piboSessionId)
+        throw new PiboWebHttpError("piboSessionId is required", 400);
+    const session = context.channelContext.getSession(piboSessionId);
+    if (!session)
+        throw new PiboWebHttpError("Pibo session not found", 404);
+    return {
+        piboSessionId,
+        piboRoomId: input.piboRoomId?.trim() || undefined,
+    };
+}
+function requireQueryParam(url, name, fallbackName) {
+    const value = (url.searchParams.get(name) ?? (fallbackName ? url.searchParams.get(fallbackName) : undefined))?.trim();
+    if (!value)
+        throw new PiboWebHttpError(`${name} is required`, 400);
+    return value;
+}
+function optionalStatus(value) {
+    if (!value)
+        return undefined;
+    if (!isWebAnnotationStatus(value))
+        throw new PiboWebHttpError("Invalid annotation status", 400);
+    return value;
+}
+function parseLimit(value) {
+    if (!value)
+        return undefined;
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) ? normalizeWebAnnotationLimit(parsed, 100, 500) : undefined;
+}
+function matchBindingResource(pathname) {
+    const prefix = `${WEB_ANNOTATIONS_API_PREFIX}/bindings/`;
+    if (!pathname.startsWith(prefix))
+        return undefined;
+    const parts = pathname.slice(prefix.length).split("/").filter(Boolean).map(decodeURIComponent);
+    if (parts.length === 0 || parts.length > 2)
+        return undefined;
+    return { id: parts[0], action: parts[1] };
+}
+function matchAnnotationResource(pathname) {
+    const prefix = `${WEB_ANNOTATIONS_API_PREFIX}/`;
+    if (!pathname.startsWith(prefix) || pathname.startsWith(`${WEB_ANNOTATIONS_API_PREFIX}/bindings/`))
+        return undefined;
+    const parts = pathname.slice(prefix.length).split("/").filter(Boolean).map(decodeURIComponent);
+    if (parts.length !== 1 || parts[0] === "targets" || parts[0] === "submissions" || parts[0] === "bindings")
+        return undefined;
+    return { id: parts[0] };
+}

package/dist/web-annotations/attachments.js

@@ -0,0 +1,201 @@
+import { sanitizeWebAnnotationText, WEB_ANNOTATION_LIMITS } from "./validation.js";
+export const WEB_ANNOTATION_MESSAGE_ATTACHMENT_LIMIT = WEB_ANNOTATION_LIMITS.attachments;
+export function normalizeWebAnnotationAttachmentIds(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error("webAnnotationIds must be an array");
+    if (value.length > WEB_ANNOTATION_MESSAGE_ATTACHMENT_LIMIT)
+        throw new Error(`At most ${WEB_ANNOTATION_MESSAGE_ATTACHMENT_LIMIT} web annotations can be attached`);
+    const ids = [];
+    const seen = new Set();
+    for (const item of value) {
+        if (typeof item !== "string")
+            throw new Error("webAnnotationIds entries must be strings");
+        const id = item.trim();
+        if (!id)
+            throw new Error("webAnnotationIds entries must be non-empty strings");
+        if (id.length > 160)
+            throw new Error("web annotation id is too long");
+        if (!seen.has(id)) {
+            seen.add(id);
+            ids.push(id);
+        }
+    }
+    return ids;
+}
+export function serializeWebAnnotationAttachment(annotation) {
+    const attachment = {
+        id: annotation.id,
+        status: annotation.status,
+        targetKind: annotation.targetKind,
+        piboSessionId: annotation.piboSessionId,
+        piboRoomId: annotation.piboRoomId,
+        url: truncateInline(annotation.url, 240) ?? annotation.url,
+        note: truncateInline(annotation.note, 400) ?? "",
+        createdAt: annotation.createdAt,
+    };
+    const label = truncateInline(annotation.target?.label, 160);
+    const selector = truncateInline(annotation.target?.selector ?? annotation.target?.domPath ?? annotation.target?.stableId, 220);
+    const sourceHint = truncateInline(sourceHintSummary(annotation.target?.sourceHints?.[0]), 220);
+    const sourceHints = sourceHintSummaries(annotation.target?.sourceHints).map((hint) => truncateInline(hint, 220)).filter((hint) => Boolean(hint));
+    const primaryTarget = truncateInline(primaryTargetSummary(annotation.target?.sourceHints), 220);
+    const piboContext = truncateInline(piboContextSummary(annotation.target?.sourceHints), 260);
+    const position = positionSummary(annotation);
+    const text = truncateInline(annotation.target?.selectedText ?? annotation.target?.text, 220);
+    if (label)
+        attachment.label = label;
+    if (selector)
+        attachment.selector = selector;
+    if (primaryTarget)
+        attachment.primaryTarget = primaryTarget;
+    if (piboContext)
+        attachment.piboContext = piboContext;
+    if (sourceHint)
+        attachment.sourceHint = sourceHint;
+    if (sourceHints.length)
+        attachment.sourceHints = sourceHints;
+    if (position)
+        attachment.position = position;
+    if (text)
+        attachment.text = text;
+    return attachment;
+}
+export function prepareWebAnnotationMessageAttachments(input) {
+    const ids = normalizeWebAnnotationAttachmentIds(input.attachmentIds);
+    if (!ids.length) {
+        return { ids: [], annotations: [], attachments: [], modelContext: "", messageText: input.messageText };
+    }
+    const annotations = ids.map((id) => {
+        const annotation = input.store.getAnnotationById(id);
+        if (!annotation)
+            throw new Error(`Web Annotation ${id} is not available in this app`);
+        if (annotation.status === "resolved" || annotation.status === "dismissed") {
+            throw new Error(`Web Annotation ${id} cannot be attached because it is ${annotation.status}`);
+        }
+        return annotation;
+    });
+    const modelContext = renderAttachedWebAnnotations(annotations);
+    return {
+        ids,
+        annotations,
+        attachments: annotations.map(serializeWebAnnotationAttachment),
+        modelContext,
+        messageText: modelContext ? `${input.messageText.trimEnd()}\n\n${modelContext}` : input.messageText,
+    };
+}
+export function renderAttachedWebAnnotations(annotations) {
+    const bounded = annotations.slice(0, WEB_ANNOTATION_MESSAGE_ATTACHMENT_LIMIT);
+    if (!bounded.length)
+        return "";
+    const lines = ["<attached-web-annotations>"];
+    bounded.forEach((annotation, index) => {
+        const target = annotation.target;
+        const sourceHint = sourceHintSummary(target?.sourceHints?.[0]);
+        const sourceHints = sourceHintSummaries(target?.sourceHints);
+        const primaryTarget = primaryTargetSummary(target?.sourceHints);
+        const piboContext = piboContextSummary(target?.sourceHints);
+        const position = positionSummary(annotation);
+        lines.push(`${index + 1}. ${escapeBlockValue(annotation.id)}`);
+        lines.push(`targetKind: ${escapeBlockValue(annotation.targetKind)}`);
+        lines.push(`sourceSession: ${escapeBlockValue(annotation.piboSessionId)}`);
+        if (annotation.piboRoomId)
+            lines.push(`sourceRoom: ${escapeBlockValue(annotation.piboRoomId)}`);
+        lines.push(`url: ${escapeBlockValue(truncateInline(annotation.url, 240) ?? "")}`);
+        if (target?.label)
+            lines.push(`label: ${escapeBlockValue(truncateInline(target.label, 160) ?? "")}`);
+        if (primaryTarget)
+            lines.push(`primaryTarget: ${escapeBlockValue(truncateInline(primaryTarget, 220) ?? "")}`);
+        if (piboContext)
+            lines.push(`piboContext: ${escapeBlockValue(truncateInline(piboContext, 260) ?? "")}`);
+        const selector = target?.selector ?? target?.domPath ?? target?.stableId;
+        if (selector)
+            lines.push(`selector: ${escapeBlockValue(truncateInline(selector, 220) ?? "")}`);
+        if (sourceHint)
+            lines.push(`sourceHint: ${escapeBlockValue(truncateInline(sourceHint, 220) ?? "")}`);
+        if (sourceHints.length > 1)
+            lines.push(`sourceHints: ${escapeBlockValue(truncateInline(sourceHints.slice(0, 5).join(" | "), 500) ?? "")}`);
+        if (position)
+            lines.push(`position: ${escapeBlockValue(position)}`);
+        const text = target?.selectedText ?? target?.text;
+        if (text)
+            lines.push(`text: ${escapeBlockValue(truncateInline(text, 220) ?? "")}`);
+        if (target?.htmlHint)
+            lines.push(`htmlHint: ${escapeBlockValue(truncateInline(target.htmlHint, 180) ?? "")}`);
+        lines.push(`comment: ${escapeBlockValue(truncateInline(annotation.note, 400) ?? "")}`);
+    });
+    lines.push("</attached-web-annotations>");
+    return lines.join("\n");
+}
+function primaryTargetSummary(hints) {
+    const hint = hints?.find((candidate) => candidate.kind === "pibo-shared-card")
+        ?? hints?.find((candidate) => candidate.kind === "pibo-markdown")
+        ?? hints?.find((candidate) => candidate.kind === "pibo-terminal-row")
+        ?? hints?.find((candidate) => candidate.kind === "pibo-component")
+        ?? hints?.[0];
+    if (!hint)
+        return undefined;
+    if (hint.kind === "pibo-shared-card")
+        return [hint.component, hint.id === "status" ? "status card" : hint.id].filter(Boolean).join(" ");
+    if (hint.kind === "pibo-terminal-row")
+        return [hint.component ?? "TerminalRow", rawString(hint, "rowKind") ?? hint.id].filter(Boolean).join(" ");
+    if (hint.kind === "pibo-markdown")
+        return [hint.component ?? "MarkdownRenderer", hint.id].filter(Boolean).join(" ");
+    return hint.component ?? hint.id;
+}
+function piboContextSummary(hints) {
+    if (!hints?.length)
+        return undefined;
+    const parts = [];
+    for (const hint of hints) {
+        if (!hint.kind.startsWith("pibo-"))
+            continue;
+        const values = [
+            hint.component ? `component=${hint.component}` : undefined,
+            hint.id ? `${hint.kind.replace(/^pibo-/, "")}=${hint.id}` : undefined,
+            rawString(hint, "rowKind") ? `rowKind=${rawString(hint, "rowKind")}` : undefined,
+            rawString(hint, "rowStatus") ? `rowStatus=${rawString(hint, "rowStatus")}` : undefined,
+            rawString(hint, "eventId") ? `eventId=${rawString(hint, "eventId")}` : undefined,
+            rawString(hint, "traceNodeId") ? `traceNodeId=${rawString(hint, "traceNodeId")}` : undefined,
+            rawString(hint, "runId") ? `runId=${rawString(hint, "runId")}` : undefined,
+            rawString(hint, "piboSessionId") ? `piboSessionId=${rawString(hint, "piboSessionId")}` : undefined,
+        ].filter(Boolean).join(", ");
+        if (values && !parts.includes(values))
+            parts.push(values);
+        if (parts.length >= 3)
+            break;
+    }
+    return parts.length ? parts.join(" | ") : undefined;
+}
+function sourceHintSummaries(hints) {
+    return hints?.map(sourceHintSummary).filter((summary) => Boolean(summary)).slice(0, 6) ?? [];
+}
+function sourceHintSummary(hint) {
+    if (!hint)
+        return undefined;
+    const location = hint.file
+        ? `${hint.file}${hint.line !== undefined ? `:${hint.line}` : ""}${hint.column !== undefined ? `:${hint.column}` : ""}`
+        : [hint.component, hint.id].filter(Boolean).join(" ") || undefined;
+    const rawBits = [rawString(hint, "rowKind"), rawString(hint, "eventId"), rawString(hint, "traceNodeId")].filter(Boolean).join(" · ");
+    return [location, hint.confidence, hint.kind, rawBits].filter(Boolean).join(" · ");
+}
+function rawString(hint, key) {
+    const value = hint.raw?.[key];
+    return typeof value === "string" && value ? value : undefined;
+}
+function positionSummary(annotation) {
+    const box = annotation.target?.boundingBox;
+    if (box)
+        return `x${formatNumber(box.x)} y${formatNumber(box.y)} ${formatNumber(box.width)}x${formatNumber(box.height)}`;
+    const position = annotation.target?.position;
+    return position ? `x${formatNumber(position.x)} y${formatNumber(position.y)}` : undefined;
+}
+function formatNumber(value) {
+    return Number.isInteger(value) ? String(value) : value.toFixed(1);
+}
+function truncateInline(value, max) {
+    return sanitizeWebAnnotationText(value, { max, field: "web annotation attachment" });
+}
+function escapeBlockValue(value) {
+    return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}