@paneui/core 0.0.9 → 0.0.10

package/dist/index.js

@@ -3,5 +3,6 @@
 export { PaneClient, PaneApiError } from "./client.js";
 export { openStream } from "./stream.js";
 export { registerAgent } from "./register.js";
-export { artifactSchema, callbackSchema, createSessionSchema, artifactTypeSchema, createArtifactSchema, createArtifactVersionSchema, patchArtifactMetadataSchema, feedbackTypeSchema, submitFeedbackSchema, listSessionsStatusSchema, listSessionsQuerySchema, mintParticipantSchema, } from "./schemas.js";
+export { artifactSchema, callbackSchema, createPaneSchema, artifactTypeSchema, createArtifactSchema, createArtifactVersionSchema, patchArtifactMetadataSchema, feedbackTypeSchema, submitFeedbackSchema, listPanesStatusSchema, listPanesQuerySchema, mintParticipantSchema, upgradePaneSchema, } from "./schemas.js";
+export { validateIconEmoji, isValidIconEmoji, isRasterImageMime, RASTER_ICON_MIME_ALLOWLIST, MAX_ICON_EMOJI_BYTES, } from "./icons.js";
 export { MAX_EVENT_TYPE_LENGTH, MAX_IDEMPOTENCY_KEY_LENGTH, MAX_RESPONSE_SNIPPET_LENGTH, MAX_FRAME_SNIPPET_LENGTH, } from "./limits.js";

package/dist/register.js

@@ -4,7 +4,7 @@
 // the call that *obtains* one. Whether the relay endpoint is reachable depends
 // on its REGISTRATION_MODE: a `secret`-mode relay requires the shared
 // registration secret to be passed as a Bearer token (see the `secret` option
-// below). Abuse is bounded server-side by a per-IP rate limit (a 429 surfaces
+// below). Abuse is bounded server-side by a per-IP rate limit (a 429 panes
 // here as a PaneApiError with status 429).
 import { PaneApiError } from "./client.js";
 import { MAX_RESPONSE_SNIPPET_LENGTH } from "./limits.js";

package/dist/schemas.d.ts

@@ -15,11 +15,13 @@ export declare const callbackSchema: z.ZodObject<{
     events: z.ZodArray<z.ZodString>;
     secret: z.ZodString;
 }, z.core.$strip>;
-export declare const createSessionSchema: z.ZodObject<{
+export declare const createPaneSchema: z.ZodObject<{
     template: z.ZodUnion<readonly [z.ZodObject<{
         id: z.ZodString;
         version: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>, z.ZodObject<{
+        name: z.ZodString;
+        slug: z.ZodOptional<z.ZodString>;
         source: z.ZodString;
         type: z.ZodEnum<{
             "html-inline": "html-inline";
@@ -27,6 +29,7 @@ export declare const createSessionSchema: z.ZodObject<{
         }>;
         event_schema: z.ZodOptional<z.ZodUnknown>;
         input_schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        record_schema: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$strip>]>;
     input_data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     participants: z.ZodOptional<z.ZodObject<{
@@ -40,7 +43,10 @@ export declare const createSessionSchema: z.ZodObject<{
         secret: z.ZodString;
     }, z.core.$strip>>;
     title: z.ZodOptional<z.ZodString>;
+    preamble: z.ZodOptional<z.ZodString>;
     context_key: z.ZodOptional<z.ZodString>;
+    icon_emoji: z.ZodOptional<z.ZodString>;
+    icon_attachment_id: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const createArtifactSchema: z.ZodObject<{
     name: z.ZodString;
@@ -54,6 +60,9 @@ export declare const createArtifactSchema: z.ZodObject<{
     }>;
     event_schema: z.ZodOptional<z.ZodUnknown>;
     input_schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    record_schema: z.ZodOptional<z.ZodUnknown>;
+    template_record_schema: z.ZodOptional<z.ZodUnknown>;
+    icon_emoji: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const createArtifactVersionSchema: z.ZodObject<{
     source: z.ZodString;
@@ -63,12 +72,16 @@ export declare const createArtifactVersionSchema: z.ZodObject<{
     }>;
     event_schema: z.ZodOptional<z.ZodUnknown>;
     input_schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    record_schema: z.ZodOptional<z.ZodUnknown>;
+    template_record_schema: z.ZodOptional<z.ZodUnknown>;
 }, z.core.$strip>;
 export declare const patchArtifactMetadataSchema: z.ZodObject<{
     name: z.ZodOptional<z.ZodString>;
     slug: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    icon_emoji: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    icon_attachment_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 export declare const feedbackTypeSchema: z.ZodEnum<{
     bug: "bug";
@@ -82,17 +95,17 @@ export declare const submitFeedbackSchema: z.ZodObject<{
         note: "note";
     }>;
     message: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>;
-    surface_id: z.ZodOptional<z.ZodString>;
+    pane_id: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
-/** @deprecated use `CreateSessionRequest` from ./types.js (same type). */
-export type CreateSessionInput = z.infer<typeof createSessionSchema>;
-export declare const listSessionsStatusSchema: z.ZodEnum<{
+/** @deprecated use `CreatePaneRequest` from ./types.js (same type). */
+export type CreatePaneInput = z.infer<typeof createPaneSchema>;
+export declare const listPanesStatusSchema: z.ZodEnum<{
     open: "open";
     closed: "closed";
     all: "all";
 }>;
-export type ListSessionsStatus = z.infer<typeof listSessionsStatusSchema>;
-export declare const listSessionsQuerySchema: z.ZodObject<{
+export type ListPanesStatus = z.infer<typeof listPanesStatusSchema>;
+export declare const listPanesQuerySchema: z.ZodObject<{
     status: z.ZodOptional<z.ZodEnum<{
         open: "open";
         closed: "closed";
@@ -102,8 +115,16 @@ export declare const listSessionsQuerySchema: z.ZodObject<{
     cursor: z.ZodOptional<z.ZodString>;
     template_id: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
-export type ListSessionsQuery = z.infer<typeof listSessionsQuerySchema>;
+export type ListPanesQuery = z.infer<typeof listPanesQuerySchema>;
 export declare const mintParticipantSchema: z.ZodObject<{
     kind: z.ZodLiteral<"human">;
 }, z.core.$strip>;
 export type MintParticipantInput = z.infer<typeof mintParticipantSchema>;
+export declare const upgradePaneSchema: z.ZodObject<{
+    template_version: z.ZodOptional<z.ZodNumber>;
+    compat: z.ZodOptional<z.ZodEnum<{
+        strict: "strict";
+        force: "force";
+    }>>;
+}, z.core.$strip>;
+export type UpgradePaneInput = z.infer<typeof upgradePaneSchema>;

package/dist/schemas.js

@@ -2,6 +2,13 @@
 // other clients) validate user-supplied input — e.g. an inline JSON template
 // or callback config — before it hits the relay, producing clear errors.
 import { z } from "zod";
+import { validateIconEmoji } from "./icons.js";
+// A validated icon emoji: exactly one emoji grapheme (see ./icons.ts). Used in
+// template/pane create + patch payloads. Rejects letters/digits/control chars
+// and multi-grapheme strings with a clear message.
+const iconEmojiSchema = z.string().refine((s) => validateIconEmoji(s).ok, {
+    message: "icon_emoji must be exactly one emoji (a single grapheme)",
+});
 // The template `type` discriminant. `html-inline` carries raw HTML in `source`;
 // `html-ref` carries a URL. The relay rejects `html-ref` in this release.
 export const artifactTypeSchema = z.enum(["html-inline", "html-ref"]);
@@ -16,35 +23,47 @@ export const callbackSchema = z.object({
     events: z.array(z.string().min(1)).min(1),
     secret: z.string().min(8),
 });
-// The inline template form for POST /v1/surfaces — carries the event schema
+// The inline template form for POST /v1/panes — carries the event schema
 // INSIDE the template object (one-off, no registered template). The relay
 // transparently creates an anonymous template behind it.
 const inlineArtifactSchema = z.object({
+    // Inline panes now name their auto-created template so the owner-shell UI
+    // has a readable label instead of falling back to the template's cuid id.
+    // Keeps the reference and inline forms symmetric: both yield a named
+    // template (name required min(1), slug optional — same as
+    // createArtifactSchema below).
+    name: z.string().min(1),
+    slug: z.string().min(1).optional(),
     source: z.string().min(1),
     type: artifactTypeSchema,
     // Optional: omit for a view-only one-off (a report/dashboard the human only
-    // views — the surface then accepts no page/agent events).
+    // views — the pane then accepts no page/agent events).
     event_schema: z.unknown().optional(),
-    // Optional: when present, the surface's `input_data` is validated against
-    // this JSON Schema before the surface row is created — and any attachment refs
+    // Optional: when present, the pane's `input_data` is validated against
+    // this JSON Schema before the pane row is created — and any attachment refs
     // declared at `format: pane-attachment-id` sites become reachable from the page
     // via `window.pane.downloadBlob()`. Without this, attachment refs in
-    // `input_data` are silently unreachable for inline surfaces (the
+    // `input_data` are silently unreachable for inline panes (the
     // participant attachment-download bridge walks input_data against the template
     // version's inputSchema; no schema means no walkable sites). See #208.
     input_schema: z.record(z.string(), z.unknown()).optional(),
+    // Optional JSON Schema 2020-12 document with an `x-pane-collections`
+    // extension declaring the template's record collections (#287 / #289).
+    // Validated by the relay at create time. Persistence ships once the
+    // schema migration (#288) lands.
+    record_schema: z.unknown().optional(),
 });
-// The reference form for POST /v1/surfaces — instances an existing named
+// The reference form for POST /v1/panes — instances an existing named
 // template. `id` accepts the template id or its slug; `version` is optional
 // and defaults to the template's latest version.
 const refArtifactSchema = z.object({
     id: z.string().min(1),
     version: z.number().int().positive().optional(),
 });
-// The surface-create `template` field: exactly one of the two forms. A union
+// The pane-create `template` field: exactly one of the two forms. A union
 // (not a discriminated union — the two forms share no discriminant key) with a
 // refine enforcing exactly-one-of `id` / `source`.
-const sessionArtifactSchema = z
+const paneTemplateSchema = z
     .union([refArtifactSchema, inlineArtifactSchema])
     .refine((a) => {
     const hasId = "id" in a && a.id !== undefined;
@@ -53,20 +72,26 @@ const sessionArtifactSchema = z
 }, {
     message: "template must carry exactly one of `id` (reference an existing template) or `source` (inline a one-off template)",
 });
-export const createSessionSchema = z.object({
-    template: sessionArtifactSchema,
+export const createPaneSchema = z.object({
+    template: paneTemplateSchema,
     input_data: z.record(z.string(), z.unknown()).optional(),
     participants: z.object({ humans: z.number().int().positive() }).optional(),
     ttl: z.number().int().positive().optional(),
     metadata: z.record(z.string(), z.unknown()).optional(),
     callback: callbackSchema.optional(),
     // Tab title for the human's browser. Optional on the wire because the relay
-    // also accepts the implicit fallback (an Template.name on the reference
-    // form). The relay enforces "required-or-fallback" + length/control-char
-    // rules — Zod only confirms it's a string here.
+    // also accepts the implicit fallback: the reference form falls back to the
+    // existing Template.name, and the inline form now carries its own `name`
+    // (see inlineArtifactSchema above) so it can fall back to that too. The
+    // relay enforces "required-or-fallback" + length/control-char rules — Zod
+    // only confirms it's a string here.
     title: z.string().optional(),
+    // Optional context preamble shown in the shell band above the iframe so the
+    // human reads "who is asking, why" before the artifact. Wire cap is 300 to
+    // leave the relay's trimmed 280-char rejection as the one callers see.
+    preamble: z.string().max(300).optional(),
     // Phase G — natural-key dedup. When set, the relay collapses repeated
-    // creates with the same (template, owner, context_key) into one surface
+    // creates with the same (template, owner, context_key) into one pane
     // row. NULL = ad-hoc, no dedup. See HUMAN-SIDE-PROPOSAL.md §7.1.
     context_key: z
         .string()
@@ -74,6 +99,12 @@ export const createSessionSchema = z.object({
         .max(256)
         .regex(/^[A-Za-z0-9_:.-]+$/, "context_key must be a short identifier")
         .optional(),
+    // Per-pane icon override. `icon_emoji` is a single emoji grapheme;
+    // `icon_attachment_id` references a ready, agent-accessible raster image
+    // attachment (validated server-side). NULL/absent = inherit the template's
+    // icon. NO external URLs.
+    icon_emoji: iconEmojiSchema.optional(),
+    icon_attachment_id: z.string().min(1).optional(),
 });
 // POST /v1/templates — create a named, reusable template plus its v1 content.
 export const createArtifactSchema = z.object({
@@ -86,6 +117,17 @@ export const createArtifactSchema = z.object({
     // Optional: omit for a view-only template (no event vocabulary).
     event_schema: z.unknown().optional(),
     input_schema: z.record(z.string(), z.unknown()).optional(),
+    // Optional records declaration (#287 / #289). See inlineArtifactSchema above.
+    record_schema: z.unknown().optional(),
+    // Optional template-level records declaration. Same JSON Schema 2020-12 +
+    // x-pane-collections grammar as record_schema; stored separately on the
+    // version so the publisher can curate shared content visible to every
+    // derived pane.
+    template_record_schema: z.unknown().optional(),
+    // Optional template icon emoji (a single emoji grapheme). Image icons are
+    // set post-create via PATCH /v1/templates/:id, since the uploaded
+    // attachment must reference this template's id first.
+    icon_emoji: iconEmojiSchema.optional(),
 });
 // POST /v1/templates/:id/versions — append a new version (content only).
 export const createArtifactVersionSchema = z.object({
@@ -94,6 +136,10 @@ export const createArtifactVersionSchema = z.object({
     // Optional: omit for a view-only template (no event vocabulary).
     event_schema: z.unknown().optional(),
     input_schema: z.record(z.string(), z.unknown()).optional(),
+    // Optional records declaration (#287 / #289). See inlineArtifactSchema above.
+    record_schema: z.unknown().optional(),
+    // Optional template-level records declaration. Same grammar as record_schema.
+    template_record_schema: z.unknown().optional(),
 });
 // PATCH /v1/templates/:id — update head metadata only (never content).
 export const patchArtifactMetadataSchema = z.object({
@@ -101,6 +147,12 @@ export const patchArtifactMetadataSchema = z.object({
     slug: z.string().min(1).optional(),
     description: z.string().optional(),
     tags: z.array(z.string().min(1)).optional(),
+    // Template icon. Pass a single emoji grapheme (icon_emoji) or a ready,
+    // template-scoped raster image attachment id (icon_attachment_id). Pass
+    // `null` to CLEAR that side. Setting an image and an emoji are independent —
+    // the renderer prefers the image when both are present. NO external URLs.
+    icon_emoji: iconEmojiSchema.nullable().optional(),
+    icon_attachment_id: z.string().min(1).nullable().optional(),
 });
 // POST /v1/feedback — an agent submits a bug report, feature request, or note
 // to the relay operator. Message is trimmed before length check so whitespace
@@ -112,21 +164,32 @@ export const submitFeedbackSchema = z.object({
         .string()
         .transform((s) => s.trim())
         .pipe(z.string().min(1).max(4000)),
-    surface_id: z.string().min(1).optional(),
+    pane_id: z.string().min(1).optional(),
 });
-// GET /v1/surfaces — list the calling agent's surfaces. The relay also
+// GET /v1/panes — list the calling agent's panes. The relay also
 // re-parses these on its side (defence in depth); this schema is for the CLI
 // to fail fast with a clear error before a round trip.
-export const listSessionsStatusSchema = z.enum(["open", "closed", "all"]);
-export const listSessionsQuerySchema = z.object({
-    status: listSessionsStatusSchema.optional(),
+export const listPanesStatusSchema = z.enum(["open", "closed", "all"]);
+export const listPanesQuerySchema = z.object({
+    status: listPanesStatusSchema.optional(),
     limit: z.number().int().positive().max(200).optional(),
     cursor: z.string().min(1).optional(),
     template_id: z.string().min(1).optional(),
 });
-// POST /v1/surfaces/:id/participants — mint a fresh participant URL for an
-// existing surface. v1 supports human participants only (the agent token is
-// minted at surface-create and cannot be re-minted via this endpoint).
+// POST /v1/panes/:id/participants — mint a fresh participant URL for an
+// existing pane. v1 supports human participants only (the agent token is
+// minted at pane-create and cannot be re-minted via this endpoint).
 export const mintParticipantSchema = z.object({
     kind: z.literal("human"),
 });
+// POST /v1/panes/:id/upgrade — re-pin a live pane to a newer version
+// of the same template (#267). `template_version` is optional; the relay
+// defaults to the template's latest version. `compat` defaults to "strict",
+// which makes the relay refuse 422 if the target schema isn't a superset
+// of the current one (events written under the old schema would no longer
+// validate). "force" overrides the gate — used sparingly when the operator
+// knows data loss is acceptable.
+export const upgradePaneSchema = z.object({
+    template_version: z.number().int().positive().optional(),
+    compat: z.enum(["strict", "force"]).optional(),
+});

package/dist/stream.d.ts

@@ -1,21 +1,40 @@
 import { WebSocket } from "ws";
-import type { PaneEvent } from "./types.js";
+import type { PaneEvent, RecordDeltaMessage } from "./types.js";
 export interface OpenStreamOptions {
     /** WebSocket base URL, e.g. wss://pane.example.com (no trailing slash). */
     wsBaseUrl: string;
-    /** Surface id. */
-    surfaceId: string;
+    /** Pane id. */
+    paneId: string;
     /** Agent (or participant) bearer token. */
     token: string;
     /** Opaque cursor: replay only events strictly after this id. */
     since?: string | null;
+    /**
+     * #297 — subscribe to record-collection deltas. `"*"` expands to every
+     * declared collection on the pane's template; a comma list filters
+     * to those names. Absent = no record traffic (legacy event-only stream).
+     */
+    subscribeRecords?: string;
+    /**
+     * #297 — per-collection record-replay cursors. Map of collection name →
+     * last observed seq, sent as `?since_record_seq.<name>=<seq>` so the
+     * relay's replay (#295) skips already-observed rows on reconnect.
+     */
+    sinceRecordSeq?: Record<string, number>;
 }
 /** Callbacks for a live stream. */
 export interface StreamHandlers {
     /** Fired for every event envelope (replayed and live). */
     onEvent?: (event: PaneEvent) => void;
-    /** Fired once when the initial replay finishes. */
+    /** Fired once when the initial event replay finishes. */
     onReplayComplete?: () => void;
+    /**
+     * #297 — fired for every record-delta message (record.upsert /
+     * record.delete / record.replay.complete) on the stream. Per-collection
+     * record.replay.complete fires once per subscribed collection after
+     * the replay set has been drained.
+     */
+    onRecord?: (msg: RecordDeltaMessage) => void;
     /** Fired on a relay error frame. */
     onRelayError?: (error: {
         code?: string;
@@ -32,7 +51,7 @@ export interface StreamHandlers {
 }
 /** A live handle to an open stream. */
 export interface StreamHandle {
-    /** Send an event frame into the surface. */
+    /** Send an event frame into the pane. */
     send(frame: {
         type: string;
         data?: unknown;
@@ -45,7 +64,7 @@ export interface StreamHandle {
     readonly socket: WebSocket;
 }
 /**
- * Open a WebSocket stream to a Pane surface. Replays on connect, then streams
+ * Open a WebSocket stream to a Pane pane. Replays on connect, then streams
  * live. Returns a handle for sending frames and closing.
  */
 export declare function openStream(opts: OpenStreamOptions, handlers: StreamHandlers): StreamHandle;

package/dist/stream.js

@@ -1,4 +1,4 @@
-// WebSocket client for WS /v1/surfaces/:id/stream.
+// WebSocket client for WS /v1/panes/:id/stream.
 //
 // The relay protocol (see the relay's src/ws/handler.ts):
 //   - on connect, the relay replays every event since `?since=` (or from the
@@ -16,15 +16,23 @@
 import { WebSocket } from "ws";
 import { MAX_FRAME_SNIPPET_LENGTH } from "./limits.js";
 /**
- * Open a WebSocket stream to a Pane surface. Replays on connect, then streams
+ * Open a WebSocket stream to a Pane pane. Replays on connect, then streams
  * live. Returns a handle for sending frames and closing.
  */
 export function openStream(opts, handlers) {
     const base = opts.wsBaseUrl.replace(/\/$/, "");
-    const u = new URL(`${base}/v1/surfaces/${encodeURIComponent(opts.surfaceId)}/stream`);
+    const u = new URL(`${base}/v1/panes/${encodeURIComponent(opts.paneId)}/stream`);
     if (opts.since != null && opts.since !== "") {
         u.searchParams.set("since", opts.since);
     }
+    if (opts.subscribeRecords && opts.subscribeRecords.length > 0) {
+        u.searchParams.set("subscribe_records", opts.subscribeRecords);
+    }
+    if (opts.sinceRecordSeq) {
+        for (const [name, seq] of Object.entries(opts.sinceRecordSeq)) {
+            u.searchParams.set(`since_record_seq.${name}`, String(seq));
+        }
+    }
     // Token via Authorization header (Node ws supports it); the relay also
     // accepts ?token= but the header keeps it out of any URL access log.
     const socket = new WebSocket(u.toString(), {
@@ -38,7 +46,7 @@ export function openStream(opts, handlers) {
         }
         catch (e) {
             // A malformed frame must never be silently dropped — a dropped event
-            // makes `watch --type X` hang forever. Surface it as a transport error.
+            // makes `watch --type X` hang forever. Pane it as a transport error.
             const snippet = text.length > MAX_FRAME_SNIPPET_LENGTH
                 ? text.slice(0, MAX_FRAME_SNIPPET_LENGTH) + "…"
                 : text;
@@ -59,7 +67,15 @@ export function openStream(opts, handlers) {
             return;
         }
         if ("ack" in obj) {
-            // Ack for a frame we sent; nothing to surface by default.
+            // Ack for a frame we sent; nothing to pane by default.
+            return;
+        }
+        // #297 — record deltas. record.upsert / record.delete / record.replay.complete.
+        const kind = obj["kind"];
+        if (kind === "record.upsert" ||
+            kind === "record.delete" ||
+            kind === "record.replay.complete") {
+            handlers.onRecord?.(obj);
             return;
         }
         if (typeof obj["id"] === "string" && typeof obj["type"] === "string") {

package/dist/types.d.ts

@@ -1,10 +1,10 @@
 import type { z } from "zod";
-import type { createSessionSchema } from "./schemas.js";
+import type { createPaneSchema } from "./schemas.js";
 export type AuthorKind = "human" | "agent" | "system";
 /** A single event envelope as emitted by the relay. */
 export interface PaneEvent {
     id: string;
-    surface_id: string;
+    pane_id: string;
     author: {
         kind: AuthorKind;
         id: string;
@@ -14,7 +14,60 @@ export interface PaneEvent {
     data: unknown;
     causation_id: string | null;
     idempotency_key: string | null;
+    /**
+     * The template version this event was written under — the pane's pinned
+     * templateVersionId at the moment of the write. Stamped at write time and
+     * never rewritten, so a downstream upgrade (#267) can read old events
+     * under the new schema (Level 1 polymorphic render). Nullable for events
+     * written before #268 landed; the relay's one-shot migration backfilled
+     * those from the pane's current pin where possible.
+     */
+    template_version_id: string | null;
+    /** Denormalised integer version number for `template_version_id`. */
+    template_version: number | null;
 }
+/**
+ * One record on the wire (#287). Returned by the records CRUD routes
+ * (#292) and by the WS record-delta messages (#294). Structurally
+ * identical to the relay-side SerializedRecord; mirrored here so the
+ * core package is self-contained.
+ */
+export interface SerializedRecord {
+    id: string;
+    collection: string;
+    key: string;
+    data: unknown;
+    version: number;
+    seq: number;
+    author: {
+        kind: AuthorKind;
+        id: string;
+    };
+    created_at: string;
+    updated_at: string;
+    deleted_at: string | null;
+}
+/** Wire shape for a soft-deleted record on the WS channel. */
+export interface DeletedRecordRef {
+    id: string;
+    key: string;
+    seq: number;
+    deleted_at: string;
+}
+/** Discriminated wire shape for record-state changes. */
+export type RecordDeltaMessage = {
+    kind: "record.upsert";
+    collection: string;
+    record: SerializedRecord;
+} | {
+    kind: "record.delete";
+    collection: string;
+    record: DeletedRecordRef;
+} | {
+    kind: "record.replay.complete";
+    collection: string;
+    seq: number;
+};
 /** The template content type. `html-ref` is rejected by the relay for now. */
 export type TemplateType = "html-inline" | "html-ref";
 /**
@@ -36,13 +89,13 @@ export interface Callback {
     secret: string;
 }
 /**
- * Request body for POST /v1/surfaces. Derived from `createSessionSchema` so the
+ * Request body for POST /v1/panes. Derived from `createPaneSchema` so the
  * runtime validator and the static type cannot drift.
  */
-export type CreateSessionRequest = z.infer<typeof createSessionSchema>;
-/** Response from POST /v1/surfaces. */
-export interface CreateSessionResponse {
-    surface_id: string;
+export type CreatePaneRequest = z.infer<typeof createPaneSchema>;
+/** Response from POST /v1/panes. */
+export interface CreatePaneResponse {
+    pane_id: string;
     tokens: {
         humans: string[];
         agent: string;
@@ -52,31 +105,31 @@ export interface CreateSessionResponse {
         agent_stream: string;
     };
     expires_at: string;
-    /** The resolved tab title persisted on the surface (the agent's value, or
+    /** The resolved tab title persisted on the pane (the agent's value, or
      * the Template.name fallback). */
     title: string;
 }
-/** Response from GET /v1/surfaces/:id. */
-export interface SurfaceState {
-    surface_id: string;
+/** Response from GET /v1/panes/:id. */
+export interface PaneState {
+    pane_id: string;
     status: string;
-    /** The template version this surface is pinned to. */
+    /** The template version this pane is pinned to. */
     template_id: string;
     template_version_id: string;
     template_version: number;
-    /** The tab title this surface was created with (frozen for its lifetime). */
+    /** The tab title this pane was created with (frozen for its lifetime). */
     title: string;
     metadata: Record<string, unknown> | null;
     input_data: Record<string, unknown> | null;
     created_at: string;
     expires_at: string;
 }
-/** Response from GET /v1/surfaces/:id/events. */
+/** Response from GET /v1/panes/:id/events. */
 export interface EventsPage {
     events: PaneEvent[];
     next_cursor: string | null;
 }
-/** A non-secret summary of one participant on a surface — safe to list. */
+/** A non-secret summary of one participant on a pane — safe to list. */
 export interface ParticipantSummary {
     /** The revoke handle (Participant.id). */
     participant_id: string;
@@ -89,9 +142,9 @@ export interface ParticipantSummary {
     /** ISO timestamp the participant was revoked; null while still active. */
     revoked_at: string | null;
 }
-/** A row in the GET /v1/surfaces list response (no secrets, lean). */
-export interface SurfaceSummary {
-    surface_id: string;
+/** A row in the GET /v1/panes list response (no secrets, lean). */
+export interface PaneSummary {
+    pane_id: string;
     /** Tab title (required column; agent input or Template.name fallback). */
     title: string;
     /** Effective status — respects expiresAt projection (the column may say
@@ -102,30 +155,50 @@ export interface SurfaceSummary {
     template_version_id: string;
     template_version: number;
     /** Count of active (non-revoked) human participants. The full participant
-     *  array is intentionally NOT inlined here — agents with many surfaces
+     *  array is intentionally NOT inlined here — agents with many panes
      *  would pay the bandwidth on every list call. Fetch
-     *  `GET /v1/surfaces/:id/participants` when you need the rows. */
+     *  `GET /v1/panes/:id/participants` when you need the rows. */
     active_human_participants: number;
     created_at: string;
     expires_at: string;
-    /** Whether the surface has a webhook callback configured (URL is NOT
+    /** Whether the pane has a webhook callback configured (URL is NOT
      *  returned — it may carry a secret in the path). */
     has_callback: boolean;
 }
-/** Response from GET /v1/surfaces/:id/participants — every participant on
- *  one surface (active and revoked). Bounded by MAX_PARTICIPANTS_PER_SESSION
+/** Response from GET /v1/panes/:id/participants — every participant on
+ *  one pane (active and revoked). Bounded by MAX_PARTICIPANTS_PER_PANE
  *  on the relay so no pagination is needed. */
 export interface ParticipantsList {
-    surface_id: string;
+    pane_id: string;
     items: ParticipantSummary[];
 }
-/** Response from GET /v1/surfaces. */
-export interface SurfacesPage {
-    items: SurfaceSummary[];
+/** Response from GET /v1/panes. */
+export interface PanesPage {
+    items: PaneSummary[];
     /** Opaque cursor for the next page; null when no more rows. */
     next_cursor: string | null;
 }
-/** Response from POST /v1/surfaces/:id/participants — one-shot, includes the
+/** A trashed pane in the GET /v1/trash response (#306). */
+export interface TrashedPaneEntry {
+    pane_id: string;
+    title: string;
+    agent_name: string;
+    /** ISO-8601 timestamp the pane was soft-deleted. Always present here. */
+    deleted_at: string;
+}
+/** A trashed template in the GET /v1/trash response (#306). */
+export interface TrashedTemplateEntry {
+    template_id: string;
+    name: string | null;
+    slug: string | null;
+    deleted_at: string;
+}
+/** Response from GET /v1/trash (#306). */
+export interface TrashListResponse {
+    panes: TrashedPaneEntry[];
+    templates: TrashedTemplateEntry[];
+}
+/** Response from POST /v1/panes/:id/participants — one-shot, includes the
  *  plaintext token exactly once. The relay stores only the hash. */
 export interface MintParticipantResponse {
     participant_id: string;
@@ -220,7 +293,7 @@ export interface FeedbackRecord {
     id: string;
     type: FeedbackType;
     message: string;
-    surface_id: string | null;
+    pane_id: string | null;
     created_at: string;
 }
 /** Response from GET /v1/feedback — page of the calling agent's own submissions. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paneui/core",
-  "version": "0.0.9",
+  "version": "0.0.10",
   "description": "Pane relay client: typed HTTP + WebSocket operations against a Pane relay. Framework-free.",
   "license": "MIT",
   "type": "module",