@paneui/core 0.0.8 → 0.0.10

package/dist/client.js

@@ -87,7 +87,7 @@ export class PaneClient {
                 }
                 catch {
                     // Body was not JSON (HTML error page, plain-text proxy error, …).
-                    // Don't discard it — surface the raw text so callers can diagnose.
+                    // Don't discard it — pane the raw text so callers can diagnose.
                     const snippet = text.length > MAX_RESPONSE_SNIPPET_LENGTH
                         ? text.slice(0, MAX_RESPONSE_SNIPPET_LENGTH) + "…"
                         : text;
@@ -121,34 +121,38 @@ export class PaneClient {
             docsUrl: err?.docs_url,
         });
     }
-    /** POST /v1/surfaces — create a surface. */
-    async createSession(req) {
-        const r = await this.call("POST", "/v1/surfaces", {
+    /** POST /v1/panes — create a pane. */
+    async createPane(req) {
+        const r = await this.call("POST", "/v1/panes", {
             template: req.template,
             title: req.title,
+            preamble: req.preamble,
             input_data: req.input_data,
             participants: req.participants,
             ttl: req.ttl,
             metadata: req.metadata,
             callback: req.callback,
+            context_key: req.context_key,
+            icon_emoji: req.icon_emoji,
+            icon_attachment_id: req.icon_attachment_id,
         });
         if (!r.ok)
             this.fail(r);
         return this.asObject(r);
     }
-    /** GET /v1/surfaces/:id — non-blocking surface metadata. */
-    async getSession(surfaceId) {
-        const r = await this.call("GET", `/v1/surfaces/${encodeURIComponent(surfaceId)}`);
+    /** GET /v1/panes/:id — non-blocking pane metadata. */
+    async getPane(paneId) {
+        const r = await this.call("GET", `/v1/panes/${encodeURIComponent(paneId)}`);
         if (!r.ok)
             this.fail(r);
         return this.asObject(r);
     }
     /**
-     * GET /v1/surfaces/:id/events — fetch the event log.
+     * GET /v1/panes/:id/events — fetch the event log.
      * `since` is an opaque cursor; `waitSeconds` enables the relay long-poll
      * (0 = non-blocking, capped at 30 by the relay).
      */
-    async getEvents(surfaceId, opts = {}) {
+    async getEvents(paneId, opts = {}) {
         const q = new URLSearchParams();
         if (opts.since != null && opts.since !== "")
             q.set("since", opts.since);
@@ -156,14 +160,175 @@ export class PaneClient {
             q.set("wait", String(Math.floor(opts.waitSeconds)));
         }
         const qs = q.toString();
-        const r = await this.call("GET", `/v1/surfaces/${encodeURIComponent(surfaceId)}/events${qs ? "?" + qs : ""}`);
+        const r = await this.call("GET", `/v1/panes/${encodeURIComponent(paneId)}/events${qs ? "?" + qs : ""}`);
         if (!r.ok)
             this.fail(r);
         return this.asObject(r);
     }
-    /** POST /v1/surfaces/:id/events — append an agent event. */
-    async sendEvent(surfaceId, ev) {
-        const r = await this.call("POST", `/v1/surfaces/${encodeURIComponent(surfaceId)}/events`, {
+    // ----- #355: SQL query API --------------------------------------------
+    /**
+     * POST /v1/query — run a read-only SQL query against the agent's own
+     * scoped data (panes, records, events). The relay scopes the result at
+     * the view layer; the agent can never see rows whose pane.owner_human_id
+     * does not match the caller's scope. Three generic views (panes, records,
+     * events) are always exposed; per-collection / per-event-type views are
+     * also materialized for any schemas declared on the caller's templates.
+     *
+     * `opts.paneId` narrows the scope to a single pane — handy when two of
+     * the caller's panes declare the same collection with incompatible types
+     * and the materializer would otherwise raise view_conflict.
+     *
+     * `data` is a JSON column — use Postgres-style operators (->>, ->) to
+     * project into it. Cap: 10,000 result rows (response.truncated=true
+     * signals the cap was hit); statement timeout: 10 seconds.
+     */
+    async query(sql, opts = {}) {
+        const body = { sql };
+        if (opts.paneId !== undefined)
+            body.pane_id = opts.paneId;
+        const r = await this.call("POST", "/v1/query", body);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    // ----- #297: records CRUD ---------------------------------------------
+    /**
+     * GET /v1/panes/:id/records/:collection — cursor-paginated list.
+     * Includes tombstones (`deleted_at` set) so reconnecting clients can
+     * observe deletions.
+     */
+    async listRecords(paneId, collection, opts = {}) {
+        const q = new URLSearchParams();
+        if (opts.since != null)
+            q.set("since", String(opts.since));
+        if (opts.limit != null)
+            q.set("limit", String(opts.limit));
+        const qs = q.toString();
+        const r = await this.call("GET", `/v1/panes/${encodeURIComponent(paneId)}/records/${encodeURIComponent(collection)}${qs ? "?" + qs : ""}`);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * Convenience: walk listRecords until the named recordKey is found OR
+     * the collection is exhausted. The relay has no dedicated single-get
+     * route today; this client-side scan trades round trips for not adding
+     * a route. Fine for typical CLI use; not appropriate for hot paths.
+     */
+    async getRecord(paneId, collection, recordKey) {
+        let since;
+        for (;;) {
+            const page = await this.listRecords(paneId, collection, {
+                since,
+                limit: 200,
+            });
+            const hit = page.records.find((r) => r.key === recordKey);
+            if (hit)
+                return hit;
+            if (!page.has_more)
+                return null;
+            since = page.next_since;
+        }
+    }
+    /**
+     * POST /v1/panes/:id/records/:collection — create-or-return-existing.
+     * Duplicate `recordKey` returns the existing row with `deduped: true`.
+     */
+    async upsertRecord(paneId, collection, body) {
+        const r = await this.call("POST", `/v1/panes/${encodeURIComponent(paneId)}/records/${encodeURIComponent(collection)}`, body);
+        if (!r.ok)
+            this.fail(r);
+        const out = this.asObject(r);
+        return { record: out.record, deduped: out.deduped ?? false };
+    }
+    /**
+     * PATCH /v1/panes/:id/records/:collection/:recordKey — optimistic
+     * update. On 409 the relay returns the current row in `details.current`.
+     */
+    async updateRecord(paneId, collection, recordKey, body) {
+        const r = await this.call("PATCH", `/v1/panes/${encodeURIComponent(paneId)}/records/${encodeURIComponent(collection)}/${encodeURIComponent(recordKey)}`, body);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * DELETE /v1/panes/:id/records/:collection/:recordKey — soft-delete.
+     * Optional `if_match` returns 409 + `details.current` on mismatch.
+     */
+    async deleteRecord(paneId, collection, recordKey, opts = {}) {
+        const body = opts.ifMatch != null ? { if_match: opts.ifMatch } : undefined;
+        const r = await this.call("DELETE", `/v1/panes/${encodeURIComponent(paneId)}/records/${encodeURIComponent(collection)}/${encodeURIComponent(recordKey)}`, body);
+        if (!r.ok)
+            this.fail(r);
+    }
+    // ----- template-level records CRUD ------------------------------------
+    /**
+     * GET /v1/templates/:id/template-records/:collection — owner-only list of
+     * a template's curated records. Same wire shape as listRecords, separate
+     * route so the relay can route owner-vs-page access independently.
+     */
+    async listTemplateRecords(templateIdOrSlug, collection, opts = {}) {
+        const q = new URLSearchParams();
+        if (opts.since != null)
+            q.set("since", String(opts.since));
+        if (opts.limit != null)
+            q.set("limit", String(opts.limit));
+        const qs = q.toString();
+        const r = await this.call("GET", `/v1/templates/${encodeURIComponent(templateIdOrSlug)}/template-records/${encodeURIComponent(collection)}${qs ? "?" + qs : ""}`);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * Client-side scan helper — same shape as `getRecord` but for template
+     * records. Walks listTemplateRecords until the key matches.
+     */
+    async getTemplateRecord(templateIdOrSlug, collection, recordKey) {
+        let since;
+        for (;;) {
+            const page = await this.listTemplateRecords(templateIdOrSlug, collection, { since, limit: 200 });
+            const hit = page.records.find((r) => r.key === recordKey);
+            if (hit)
+                return hit;
+            if (!page.has_more)
+                return null;
+            since = page.next_since;
+        }
+    }
+    /**
+     * POST /v1/templates/:id/template-records/:collection — owner-only
+     * create-or-return-existing.
+     */
+    async upsertTemplateRecord(templateIdOrSlug, collection, body) {
+        const r = await this.call("POST", `/v1/templates/${encodeURIComponent(templateIdOrSlug)}/template-records/${encodeURIComponent(collection)}`, body);
+        if (!r.ok)
+            this.fail(r);
+        const out = this.asObject(r);
+        return { record: out.record, deduped: out.deduped ?? false };
+    }
+    /**
+     * PATCH /v1/templates/:id/template-records/:collection/:recordKey —
+     * optimistic-locked update.
+     */
+    async updateTemplateRecord(templateIdOrSlug, collection, recordKey, body) {
+        const r = await this.call("PATCH", `/v1/templates/${encodeURIComponent(templateIdOrSlug)}/template-records/${encodeURIComponent(collection)}/${encodeURIComponent(recordKey)}`, body);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * DELETE /v1/templates/:id/template-records/:collection/:recordKey —
+     * soft-delete.
+     */
+    async deleteTemplateRecord(templateIdOrSlug, collection, recordKey, opts = {}) {
+        const body = opts.ifMatch != null ? { if_match: opts.ifMatch } : undefined;
+        const r = await this.call("DELETE", `/v1/templates/${encodeURIComponent(templateIdOrSlug)}/template-records/${encodeURIComponent(collection)}/${encodeURIComponent(recordKey)}`, body);
+        if (!r.ok)
+            this.fail(r);
+    }
+    /** POST /v1/panes/:id/events — append an agent event. */
+    async sendEvent(paneId, ev) {
+        const r = await this.call("POST", `/v1/panes/${encodeURIComponent(paneId)}/events`, {
             type: ev.type,
             data: ev.data,
             causation_id: ev.causationId,
@@ -188,6 +353,7 @@ export class PaneClient {
             type: req.type,
             event_schema: req.event_schema,
             input_schema: req.input_schema,
+            icon_emoji: req.icon_emoji,
         });
         if (!r.ok)
             this.fail(r);
@@ -219,6 +385,10 @@ export class PaneClient {
             slug: metadata.slug,
             description: metadata.description,
             tags: metadata.tags,
+            // Forward null explicitly (clears the icon); undefined is dropped by
+            // JSON.stringify so an omitted field is a no-op server-side.
+            icon_emoji: metadata.icon_emoji,
+            icon_attachment_id: metadata.icon_attachment_id,
         });
         if (!r.ok)
             this.fail(r);
@@ -280,7 +450,7 @@ export class PaneClient {
      * POST /v1/agents/claim — bind this agent to a human via a one-shot
      * claim code the human generated in their settings UI. After a
      * successful claim the agent's existing API key continues to work,
-     * but the agent (and its surfaces/templates) now belong to the
+     * but the agent (and its panes/templates) now belong to the
      * claiming human. One-way operation — there is no unclaim in v1.
      */
     async claimAgent(code) {
@@ -333,7 +503,7 @@ export class PaneClient {
         const r = await this.call("POST", "/v1/feedback", {
             type: req.type,
             message: req.message,
-            surface_id: req.surfaceId,
+            pane_id: req.paneId,
         });
         if (!r.ok)
             this.fail(r);
@@ -356,14 +526,14 @@ export class PaneClient {
         return this.asObject(r);
     }
     /**
-     * GET /v1/surfaces — list the calling agent's surfaces. Default filter is
+     * GET /v1/panes — list the calling agent's panes. Default filter is
      * `status=open` (effective status — respects expiresAt). Response items
      * carry NO secrets: no participant token plaintext, no callback URL, no
      * metadata or input_data. Use `participant_id` from the list as the handle
      * for {@link revokeParticipant}; use {@link mintParticipant} to issue a
      * fresh URL when the original was lost.
      */
-    async listSessions(opts = {}) {
+    async listPanes(opts = {}) {
         const q = new URLSearchParams();
         if (opts.status !== undefined)
             q.set("status", opts.status);
@@ -374,69 +544,115 @@ export class PaneClient {
         if (opts.template_id !== undefined && opts.template_id !== "")
             q.set("template_id", opts.template_id);
         const qs = q.toString();
-        const r = await this.call("GET", `/v1/surfaces${qs ? "?" + qs : ""}`);
+        const r = await this.call("GET", `/v1/panes${qs ? "?" + qs : ""}`);
         if (!r.ok)
             this.fail(r);
         return this.asObject(r);
     }
     /**
-     * GET /v1/surfaces/:id/participants — list every participant on one
-     * surface (active and revoked). Bounded by MAX_PARTICIPANTS_PER_SESSION
+     * GET /v1/panes/:id/participants — list every participant on one
+     * pane (active and revoked). Bounded by MAX_PARTICIPANTS_PER_PANE
      * on the relay, so the full list is returned with no pagination.
      * Use this to find the `participant_id` you need to pass to
      * {@link revokeParticipant}, or to audit revoked rows.
      */
-    async listParticipants(surfaceId) {
-        const r = await this.call("GET", `/v1/surfaces/${encodeURIComponent(surfaceId)}/participants`);
+    async listParticipants(paneId) {
+        const r = await this.call("GET", `/v1/panes/${encodeURIComponent(paneId)}/participants`);
         if (!r.ok)
             this.fail(r);
         return this.asObject(r);
     }
     /**
-     * POST /v1/surfaces/:id/participants — mint a fresh participant URL for an
-     * existing surface. The one-shot recovery primitive when the original URL
-     * was dropped: the surface keeps its event log, template pin, and created_at.
+     * POST /v1/panes/:id/participants — mint a fresh participant URL for an
+     * existing pane. The one-shot recovery primitive when the original URL
+     * was dropped: the pane keeps its event log, template pin, and created_at.
      * v1 supports `kind: "human"` only.
      *
      * The plaintext token is returned EXACTLY ONCE in the response — the relay
      * stores only the hash. Save the response (e.g. pipe to a JSONL log) before
      * delivering the URL to the human.
      */
-    async mintParticipant(surfaceId, opts = {}) {
-        const r = await this.call("POST", `/v1/surfaces/${encodeURIComponent(surfaceId)}/participants`, { kind: opts.kind ?? "human" });
+    async mintParticipant(paneId, opts = {}) {
+        const r = await this.call("POST", `/v1/panes/${encodeURIComponent(paneId)}/participants`, { kind: opts.kind ?? "human" });
         if (!r.ok)
             this.fail(r);
         return this.asObject(r);
     }
     /**
-     * DELETE /v1/surfaces/:id/participants/:participant_id — revoke a single
-     * participant URL. The surface's other participants (and the agent's own
+     * DELETE /v1/panes/:id/participants/:participant_id — revoke a single
+     * participant URL. The pane's other participants (and the agent's own
      * WebSocket) are untouched. Idempotent: revoking an unknown or already-
      * revoked participant returns 204. The agent participant cannot be revoked
-     * via this endpoint — use {@link deleteSession} instead.
+     * via this endpoint — use {@link deletePane} instead.
      *
      * Existing WebSocket connections held under the revoked token are NOT
      * actively kicked in v1; new HTTP and WS connections are refused.
      */
-    async revokeParticipant(surfaceId, participantId) {
-        const r = await this.call("DELETE", `/v1/surfaces/${encodeURIComponent(surfaceId)}/participants/${encodeURIComponent(participantId)}`);
+    async revokeParticipant(paneId, participantId) {
+        const r = await this.call("DELETE", `/v1/panes/${encodeURIComponent(paneId)}/participants/${encodeURIComponent(participantId)}`);
+        if (!r.ok)
+            this.fail(r);
+    }
+    /**
+     * DELETE /v1/panes/:id — close/delete a pane. Idempotent on the relay
+     * side (an already-closed pane still returns 204 with no body).
+     */
+    async deletePane(id) {
+        const r = await this.call("DELETE", `/v1/panes/${encodeURIComponent(id)}`);
+        if (!r.ok)
+            this.fail(r);
+    }
+    /**
+     * GET /v1/trash — list soft-deleted panes + templates in the caller's
+     * agent-scope. The trash UI / `pane trash list` lives off this. (#306)
+     */
+    async listTrash() {
+        const r = await this.call("GET", "/v1/trash");
+        if (!r.ok)
+            this.fail(r);
+        return r.data;
+    }
+    /**
+     * POST /v1/trash/panes/:id/restore — un-trash a soft-deleted pane (clear
+     * deletedAt + audit row). (#306)
+     */
+    async restorePane(id) {
+        const r = await this.call("POST", `/v1/trash/panes/${encodeURIComponent(id)}/restore`);
+        if (!r.ok)
+            this.fail(r);
+    }
+    /**
+     * POST /v1/trash/templates/:id/restore — un-trash a soft-deleted template. (#306)
+     */
+    async restoreTemplate(id) {
+        const r = await this.call("POST", `/v1/trash/templates/${encodeURIComponent(id)}/restore`);
+        if (!r.ok)
+            this.fail(r);
+    }
+    /**
+     * DELETE /v1/trash/panes/:id — permanently hard-delete a trashed pane
+     * (bypass retention window). (#306)
+     */
+    async permanentDeletePane(id) {
+        const r = await this.call("DELETE", `/v1/trash/panes/${encodeURIComponent(id)}`);
         if (!r.ok)
             this.fail(r);
     }
     /**
-     * DELETE /v1/surfaces/:id — close/delete a surface. Idempotent on the relay
-     * side (an already-closed surface still returns 204 with no body).
+     * DELETE /v1/trash/templates/:id — permanently hard-delete a trashed
+     * template. Refused 409 if a live pane still references one of its
+     * versions. (#306)
      */
-    async deleteSession(id) {
-        const r = await this.call("DELETE", `/v1/surfaces/${encodeURIComponent(id)}`);
+    async permanentDeleteTemplate(id) {
+        const r = await this.call("DELETE", `/v1/trash/templates/${encodeURIComponent(id)}`);
         if (!r.ok)
             this.fail(r);
     }
     /**
      * DELETE /v1/templates/:id — remove an template and (server-side) all its
      * versions. Strict cascade: the relay refuses with 409 conflict if any
-     * surface in any state still references one of the template's versions —
-     * surface that as a typed PaneApiError so the CLI can render a hint
+     * pane in any state still references one of the template's versions —
+     * pane that as a typed PaneApiError so the CLI can render a hint
      * instead of swallowing it.
      */
     async deleteArtifact(idOrSlug) {
@@ -444,6 +660,49 @@ export class PaneClient {
         if (!r.ok)
             this.fail(r);
     }
+    /**
+     * POST /v1/templates/:id/publish — enter the public catalog. The optional
+     * `scopes` list locks the permissions the template will request from
+     * installers at this version (see Phase F §4.5 / §8). Passing an empty
+     * array clears the stored scopes; omitting `scopes` keeps the existing
+     * ones.
+     */
+    async publishTemplate(idOrSlug, body = {}) {
+        const r = await this.call("POST", `/v1/templates/${encodeURIComponent(idOrSlug)}/publish`, body);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * POST /v1/templates/:id/unpublish — leave the public catalog. Existing
+     * installs are unaffected (humans keep their pinned version), but the
+     * template no longer appears in `searchPublicTemplates` results.
+     */
+    async unpublishTemplate(idOrSlug) {
+        const r = await this.call("POST", `/v1/templates/${encodeURIComponent(idOrSlug)}/unpublish`);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * GET /v1/templates/catalog?q=... — agent-side public catalog search.
+     * Lets an agent discover already-published apps before authoring a
+     * duplicate. Sorted by install_count desc, then publish recency.
+     */
+    async searchPublicTemplates(query, opts = {}) {
+        const params = new URLSearchParams();
+        if (query != null && query !== "")
+            params.set("q", query);
+        if (opts.limit != null)
+            params.set("limit", String(opts.limit));
+        if (opts.offset != null)
+            params.set("offset", String(opts.offset));
+        const qs = params.toString();
+        const r = await this.call("GET", `/v1/templates/catalog${qs ? "?" + qs : ""}`);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
     // ------------------------------------------------------------------------
     // Blobs (v0.1.0). Three-scope binary attachments with multipart upload.
     // See proposal pane#152 for the full design.
@@ -453,9 +712,9 @@ export class PaneClient {
      * in event payloads (the relay's `format: pane-attachment-id` schema vocab
      * validates the id) or in `pane create --input-data`.
      *
-     * Scope defaults to "agent" (reusable across the agent's surfaces). For
-     * `scope: "surface"` pass `surfaceId`; for `scope: "template"` pass
-     * `templateId`. The agent must own the referenced surface / template;
+     * Scope defaults to "agent" (reusable across the agent's panes). For
+     * `scope: "pane"` pass `paneId`; for `scope: "template"` pass
+     * `templateId`. The agent must own the referenced pane / template;
      * cross-tenant attempts return attachment_not_found.
      *
      * MIME is inferred from `mime` if supplied; otherwise the relay sniffs
@@ -492,8 +751,8 @@ export class PaneClient {
         fd.set("file", attachment, opts.filename ?? "attachment");
         if (opts.scope)
             fd.set("scope", opts.scope);
-        if (opts.surfaceId)
-            fd.set("surface_id", opts.surfaceId);
+        if (opts.paneId)
+            fd.set("pane_id", opts.paneId);
         if (opts.templateId)
             fd.set("template_id", opts.templateId);
         if (opts.filename)
@@ -575,7 +834,7 @@ export class PaneClient {
     }
     /**
      * Mint a `/b/<token>` capability URL for `attachmentId`. Default TTL is set by
-     * the relay (24h agent, surface-TTL surface, 30d template). `once: true`
+     * the relay (24h agent, pane-TTL pane, 30d template). `once: true`
      * tokens self-delete on first GET.
      */
     async mintBlobToken(attachmentId, opts = {}) {
@@ -637,7 +896,7 @@ export class PaneClient {
             size: opts.size,
             sha256: opts.sha256,
             scope: opts.scope,
-            surface_id: opts.surfaceId,
+            pane_id: opts.paneId,
             template_id: opts.templateId,
             filename: opts.filename,
         });

package/dist/icons.d.ts

@@ -0,0 +1,24 @@
+export declare const RASTER_ICON_MIME_ALLOWLIST: readonly ["image/png", "image/jpeg", "image/webp", "image/gif"];
+export type RasterIconMime = (typeof RASTER_ICON_MIME_ALLOWLIST)[number];
+/** True iff `mime` is a raster image type allowed as an icon. */
+export declare function isRasterImageMime(mime: string | null | undefined): boolean;
+export declare const MAX_ICON_EMOJI_BYTES = 64;
+/**
+ * Validate an icon emoji. Returns `{ ok: true }` for a single emoji grapheme,
+ * or `{ ok: false, error }` with a human-readable reason otherwise.
+ *
+ * Rules:
+ *  - non-empty, ≤ MAX_ICON_EMOJI_BYTES bytes
+ *  - no control characters
+ *  - exactly ONE grapheme cluster (via Intl.Segmenter)
+ *  - that grapheme contains at least one Extended_Pictographic code point
+ *    (so plain ASCII letters/digits and bare symbols are rejected)
+ */
+export declare function validateIconEmoji(raw: string): {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/** Convenience boolean form of {@link validateIconEmoji}. */
+export declare function isValidIconEmoji(raw: string): boolean;

package/dist/icons.js

@@ -0,0 +1,99 @@
+// Icon helpers shared by the relay and CLI — emoji validation and the raster
+// image MIME allowlist for template/pane icons.
+//
+// Icons are deliberately constrained: either ONE emoji grapheme (rendered
+// inline as text) or an uploaded raster image (served from the relay's blob
+// store). No external URLs, no SVG (XSS vector), no multi-character strings.
+// Raster image MIME types accepted as an uploaded icon. SVG is deliberately
+// EXCLUDED — it can carry script and is an XSS vector when rendered in an
+// <img> from a same-origin route. Vector/animated-vector and non-image types
+// are rejected.
+export const RASTER_ICON_MIME_ALLOWLIST = [
+    "image/png",
+    "image/jpeg",
+    "image/webp",
+    "image/gif",
+];
+/** True iff `mime` is a raster image type allowed as an icon. */
+export function isRasterImageMime(mime) {
+    if (!mime)
+        return false;
+    // Normalise: drop any `; charset=...` parameter and lowercase.
+    const base = mime.split(";")[0].trim().toLowerCase();
+    return RASTER_ICON_MIME_ALLOWLIST.includes(base);
+}
+// Upper bound on the raw byte length of an emoji string. A single rendered
+// emoji can be a long ZWJ sequence (e.g. a family/flag with skin-tone
+// modifiers), but 64 bytes is well beyond any real single grapheme and bounds
+// the work the segmenter does.
+export const MAX_ICON_EMOJI_BYTES = 64;
+// Matches a code point with the Extended_Pictographic property — the Unicode
+// property that flags "this is an emoji-ish pictograph". Used to ensure the
+// grapheme actually contains an emoji and isn't a plain letter/digit/symbol.
+const EXTENDED_PICTOGRAPHIC_RE = /\p{Extended_Pictographic}/u;
+// Control characters (C0 + DEL + C1) are never valid in an icon emoji. The
+// control chars in the class are intentional — that's exactly what we reject.
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHAR_RE = /[\u0000-\u001f\u007f-\u009f]/;
+const byteLength = (s) => typeof TextEncoder !== "undefined"
+    ? new TextEncoder().encode(s).length
+    : Buffer.byteLength(s, "utf8");
+/**
+ * Validate an icon emoji. Returns `{ ok: true }` for a single emoji grapheme,
+ * or `{ ok: false, error }` with a human-readable reason otherwise.
+ *
+ * Rules:
+ *  - non-empty, ≤ MAX_ICON_EMOJI_BYTES bytes
+ *  - no control characters
+ *  - exactly ONE grapheme cluster (via Intl.Segmenter)
+ *  - that grapheme contains at least one Extended_Pictographic code point
+ *    (so plain ASCII letters/digits and bare symbols are rejected)
+ */
+export function validateIconEmoji(raw) {
+    if (typeof raw !== "string" || raw.length === 0) {
+        return { ok: false, error: "icon_emoji must be a non-empty string" };
+    }
+    if (byteLength(raw) > MAX_ICON_EMOJI_BYTES) {
+        return {
+            ok: false,
+            error: `icon_emoji must be at most ${MAX_ICON_EMOJI_BYTES} bytes`,
+        };
+    }
+    if (CONTROL_CHAR_RE.test(raw)) {
+        return {
+            ok: false,
+            error: "icon_emoji must not contain control characters",
+        };
+    }
+    // Count grapheme clusters. Intl.Segmenter is available in Node 20+ and all
+    // evergreen browsers (our targets); guard defensively anyway.
+    let graphemeCount;
+    if (typeof Intl !== "undefined" && typeof Intl.Segmenter === "function") {
+        const seg = new Intl.Segmenter("en", { granularity: "grapheme" });
+        // Iterate the segmenter to count grapheme clusters. `[...iterable].length`
+        // materialises the segments, but a single emoji is tiny so it's fine.
+        graphemeCount = [...seg.segment(raw)].length;
+    }
+    else {
+        // Fallback: count code points (over-counts ZWJ sequences, but the
+        // pictographic check below still gates non-emoji input).
+        graphemeCount = Array.from(raw).length;
+    }
+    if (graphemeCount !== 1) {
+        return {
+            ok: false,
+            error: "icon_emoji must be exactly one emoji (a single grapheme)",
+        };
+    }
+    if (!EXTENDED_PICTOGRAPHIC_RE.test(raw)) {
+        return {
+            ok: false,
+            error: "icon_emoji must be an emoji, not a letter, digit, or symbol",
+        };
+    }
+    return { ok: true };
+}
+/** Convenience boolean form of {@link validateIconEmoji}. */
+export function isValidIconEmoji(raw) {
+    return validateIconEmoji(raw).ok;
+}

package/dist/index.d.ts

@@ -1,10 +1,12 @@
 export { PaneClient, PaneApiError } from "./client.js";
-export type { ClientOptions, RelayResponse, CreateArtifactRequest, CreateArtifactVersionRequest, PatchArtifactMetadataRequest, AttachmentRef, UploadBlobOptions, PresignBlobOptions, AttachmentTokenMintResponse, ListBlobsOptions, AttachmentTokenAuditEntry, AttachmentTokenListResponse, } from "./client.js";
+export type { ClientOptions, RelayResponse, CreateArtifactRequest, CreateArtifactVersionRequest, PatchArtifactMetadataRequest, AttachmentRef, UploadBlobOptions, PresignBlobOptions, AttachmentTokenMintResponse, ListBlobsOptions, AttachmentTokenAuditEntry, AttachmentTokenListResponse, QueryResponse, } from "./client.js";
 export { openStream } from "./stream.js";
 export type { OpenStreamOptions, StreamHandlers, StreamHandle, } from "./stream.js";
 export { registerAgent } from "./register.js";
 export type { RegisterAgentOptions, RegisterAgentResult } from "./register.js";
-export { artifactSchema, callbackSchema, createSessionSchema, artifactTypeSchema, createArtifactSchema, createArtifactVersionSchema, patchArtifactMetadataSchema, feedbackTypeSchema, submitFeedbackSchema, listSessionsStatusSchema, listSessionsQuerySchema, mintParticipantSchema, } from "./schemas.js";
-export type { CreateSessionInput, ListSessionsStatus, ListSessionsQuery, MintParticipantInput, } from "./schemas.js";
+export { artifactSchema, callbackSchema, createPaneSchema, artifactTypeSchema, createArtifactSchema, createArtifactVersionSchema, patchArtifactMetadataSchema, feedbackTypeSchema, submitFeedbackSchema, listPanesStatusSchema, listPanesQuerySchema, mintParticipantSchema, upgradePaneSchema, } from "./schemas.js";
+export type { CreatePaneInput, ListPanesStatus, ListPanesQuery, MintParticipantInput, UpgradePaneInput, } from "./schemas.js";
+export { validateIconEmoji, isValidIconEmoji, isRasterImageMime, RASTER_ICON_MIME_ALLOWLIST, MAX_ICON_EMOJI_BYTES, } from "./icons.js";
+export type { RasterIconMime } from "./icons.js";
 export { MAX_EVENT_TYPE_LENGTH, MAX_IDEMPOTENCY_KEY_LENGTH, MAX_RESPONSE_SNIPPET_LENGTH, MAX_FRAME_SNIPPET_LENGTH, } from "./limits.js";
-export type { AuthorKind, PaneEvent, Template, TemplateType, TemplateVersion, TemplateRecord, TemplateSummary, CreateArtifactResponse, KeyInfo, TasteInfo, FeedbackType, FeedbackSubmission, FeedbackRecord, FeedbackPage, Callback, CreateSessionRequest, CreateSessionResponse, SurfaceState, EventsPage, ParticipantSummary, ParticipantsList, SurfaceSummary, SurfacesPage, MintParticipantResponse, RelayError, } from "./types.js";
+export type { AuthorKind, PaneEvent, SerializedRecord, DeletedRecordRef, RecordDeltaMessage, Template, TemplateType, TemplateVersion, TemplateRecord, TemplateSummary, CreateArtifactResponse, KeyInfo, TasteInfo, FeedbackType, FeedbackSubmission, FeedbackRecord, FeedbackPage, Callback, CreatePaneRequest, CreatePaneResponse, PaneState, EventsPage, ParticipantSummary, ParticipantsList, PaneSummary, PanesPage, MintParticipantResponse, TrashedPaneEntry, TrashedTemplateEntry, TrashListResponse, RelayError, } from "./types.js";