@paneui/core 0.0.5 → 0.0.7

package/dist/schemas.d.ts

@@ -1,211 +1,109 @@
 import { z } from "zod";
-export declare const artifactTypeSchema: z.ZodEnum<["html-inline", "html-ref"]>;
-export declare const artifactSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+export declare const artifactTypeSchema: z.ZodEnum<{
+    "html-inline": "html-inline";
+    "html-ref": "html-ref";
+}>;
+export declare const artifactSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"html-inline">;
     source: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    type: "html-inline";
-    source: string;
-}, {
-    type: "html-inline";
-    source: string;
-}>, z.ZodObject<{
+}, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"html-ref">;
     source: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    type: "html-ref";
-    source: string;
-}, {
-    type: "html-ref";
-    source: string;
-}>]>;
+}, z.core.$strip>], "type">;
 export declare const callbackSchema: z.ZodObject<{
     url: z.ZodString;
-    events: z.ZodArray<z.ZodString, "many">;
+    events: z.ZodArray<z.ZodString>;
     secret: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    url: string;
-    events: string[];
-    secret: string;
-}, {
-    url: string;
-    events: string[];
-    secret: string;
-}>;
+}, z.core.$strip>;
 export declare const createSessionSchema: z.ZodObject<{
-    artifact: z.ZodEffects<z.ZodUnion<[z.ZodObject<{
+    template: z.ZodUnion<readonly [z.ZodObject<{
         id: z.ZodString;
         version: z.ZodOptional<z.ZodNumber>;
-    }, "strip", z.ZodTypeAny, {
-        id: string;
-        version?: number | undefined;
-    }, {
-        id: string;
-        version?: number | undefined;
-    }>, z.ZodObject<{
+    }, z.core.$strip>, z.ZodObject<{
         source: z.ZodString;
-        type: z.ZodEnum<["html-inline", "html-ref"]>;
+        type: z.ZodEnum<{
+            "html-inline": "html-inline";
+            "html-ref": "html-ref";
+        }>;
         event_schema: z.ZodOptional<z.ZodUnknown>;
-    }, "strip", z.ZodTypeAny, {
-        type: "html-inline" | "html-ref";
-        source: string;
-        event_schema?: unknown;
-    }, {
-        type: "html-inline" | "html-ref";
-        source: string;
-        event_schema?: unknown;
-    }>]>, {
-        type: "html-inline" | "html-ref";
-        source: string;
-        event_schema?: unknown;
-    } | {
-        id: string;
-        version?: number | undefined;
-    }, {
-        type: "html-inline" | "html-ref";
-        source: string;
-        event_schema?: unknown;
-    } | {
-        id: string;
-        version?: number | undefined;
-    }>;
+        input_schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>]>;
     input_data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     participants: z.ZodOptional<z.ZodObject<{
         humans: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
-        humans: number;
-    }, {
-        humans: number;
-    }>>;
+    }, z.core.$strip>>;
     ttl: z.ZodOptional<z.ZodNumber>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     callback: z.ZodOptional<z.ZodObject<{
         url: z.ZodString;
-        events: z.ZodArray<z.ZodString, "many">;
+        events: z.ZodArray<z.ZodString>;
         secret: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        url: string;
-        events: string[];
-        secret: string;
-    }, {
-        url: string;
-        events: string[];
-        secret: string;
-    }>>;
-}, "strip", z.ZodTypeAny, {
-    artifact: {
-        type: "html-inline" | "html-ref";
-        source: string;
-        event_schema?: unknown;
-    } | {
-        id: string;
-        version?: number | undefined;
-    };
-    input_data?: Record<string, unknown> | undefined;
-    participants?: {
-        humans: number;
-    } | undefined;
-    ttl?: number | undefined;
-    metadata?: Record<string, unknown> | undefined;
-    callback?: {
-        url: string;
-        events: string[];
-        secret: string;
-    } | undefined;
-}, {
-    artifact: {
-        type: "html-inline" | "html-ref";
-        source: string;
-        event_schema?: unknown;
-    } | {
-        id: string;
-        version?: number | undefined;
-    };
-    input_data?: Record<string, unknown> | undefined;
-    participants?: {
-        humans: number;
-    } | undefined;
-    ttl?: number | undefined;
-    metadata?: Record<string, unknown> | undefined;
-    callback?: {
-        url: string;
-        events: string[];
-        secret: string;
-    } | undefined;
-}>;
+    }, z.core.$strip>>;
+    title: z.ZodOptional<z.ZodString>;
+    context_key: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 export declare const createArtifactSchema: z.ZodObject<{
     name: z.ZodString;
     slug: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
-    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
     source: z.ZodString;
-    type: z.ZodEnum<["html-inline", "html-ref"]>;
+    type: z.ZodEnum<{
+        "html-inline": "html-inline";
+        "html-ref": "html-ref";
+    }>;
     event_schema: z.ZodOptional<z.ZodUnknown>;
     input_schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, "strip", z.ZodTypeAny, {
-    type: "html-inline" | "html-ref";
-    source: string;
-    name: string;
-    event_schema?: unknown;
-    slug?: string | undefined;
-    description?: string | undefined;
-    tags?: string[] | undefined;
-    input_schema?: Record<string, unknown> | undefined;
-}, {
-    type: "html-inline" | "html-ref";
-    source: string;
-    name: string;
-    event_schema?: unknown;
-    slug?: string | undefined;
-    description?: string | undefined;
-    tags?: string[] | undefined;
-    input_schema?: Record<string, unknown> | undefined;
-}>;
+}, z.core.$strip>;
 export declare const createArtifactVersionSchema: z.ZodObject<{
     source: z.ZodString;
-    type: z.ZodEnum<["html-inline", "html-ref"]>;
+    type: z.ZodEnum<{
+        "html-inline": "html-inline";
+        "html-ref": "html-ref";
+    }>;
     event_schema: z.ZodOptional<z.ZodUnknown>;
     input_schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, "strip", z.ZodTypeAny, {
-    type: "html-inline" | "html-ref";
-    source: string;
-    event_schema?: unknown;
-    input_schema?: Record<string, unknown> | undefined;
-}, {
-    type: "html-inline" | "html-ref";
-    source: string;
-    event_schema?: unknown;
-    input_schema?: Record<string, unknown> | undefined;
-}>;
+}, 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, "many">>;
-}, "strip", z.ZodTypeAny, {
-    name?: string | undefined;
-    slug?: string | undefined;
-    description?: string | undefined;
-    tags?: string[] | undefined;
-}, {
-    name?: string | undefined;
-    slug?: string | undefined;
-    description?: string | undefined;
-    tags?: string[] | undefined;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const feedbackTypeSchema: z.ZodEnum<{
+    bug: "bug";
+    feature: "feature";
+    note: "note";
 }>;
-export declare const feedbackTypeSchema: z.ZodEnum<["bug", "feature", "note"]>;
 export declare const submitFeedbackSchema: z.ZodObject<{
-    type: z.ZodEnum<["bug", "feature", "note"]>;
-    message: z.ZodPipeline<z.ZodEffects<z.ZodString, string, string>, z.ZodString>;
-    session_id: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    type: "bug" | "feature" | "note";
-    message: string;
-    session_id?: string | undefined;
-}, {
-    type: "bug" | "feature" | "note";
-    message: string;
-    session_id?: string | undefined;
-}>;
+    type: z.ZodEnum<{
+        bug: "bug";
+        feature: "feature";
+        note: "note";
+    }>;
+    message: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>;
+    surface_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<{
+    open: "open";
+    closed: "closed";
+    all: "all";
+}>;
+export type ListSessionsStatus = z.infer<typeof listSessionsStatusSchema>;
+export declare const listSessionsQuerySchema: z.ZodObject<{
+    status: z.ZodOptional<z.ZodEnum<{
+        open: "open";
+        closed: "closed";
+        all: "all";
+    }>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    cursor: z.ZodOptional<z.ZodString>;
+    template_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ListSessionsQuery = z.infer<typeof listSessionsQuerySchema>;
+export declare const mintParticipantSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"human">;
+}, z.core.$strip>;
+export type MintParticipantInput = z.infer<typeof mintParticipantSchema>;

package/dist/schemas.js

@@ -1,12 +1,12 @@
 // Zod schemas for the Pane relay request shapes. These let callers (the CLI,
-// other clients) validate user-supplied input — e.g. an inline JSON artifact
+// 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";
-// The artifact `type` discriminant. `html-inline` carries raw HTML in `source`;
+// 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"]);
 // Discriminated on `type`: both require a non-empty `source`. Kept for callers
-// that want to validate a bare artifact (no event schema attached).
+// that want to validate a bare template (no event schema attached).
 export const artifactSchema = z.discriminatedUnion("type", [
     z.object({ type: z.literal("html-inline"), source: z.string().min(1) }),
     z.object({ type: z.literal("html-ref"), source: z.string().min(1) }),
@@ -16,24 +16,32 @@ export const callbackSchema = z.object({
     events: z.array(z.string().min(1)).min(1),
     secret: z.string().min(8),
 });
-// The inline artifact form for POST /v1/sessions — carries the event schema
-// INSIDE the artifact object (one-off, no registered artifact). The relay
-// transparently creates an anonymous artifact behind it.
+// The inline template form for POST /v1/surfaces — 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({
     source: z.string().min(1),
     type: artifactTypeSchema,
     // Optional: omit for a view-only one-off (a report/dashboard the human only
-    // views — the session then accepts no page/agent events).
+    // views — the surface 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
+    // 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
+    // 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(),
 });
-// The reference form for POST /v1/sessions — instances an existing named
-// artifact. `id` accepts the artifact id or its slug; `version` is optional
-// and defaults to the artifact's latest version.
+// The reference form for POST /v1/surfaces — 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 session-create `artifact` field: exactly one of the two forms. A union
+// The surface-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
@@ -43,17 +51,31 @@ const sessionArtifactSchema = z
     const hasSource = "source" in a && a.source !== undefined;
     return hasId !== hasSource;
 }, {
-    message: "artifact must carry exactly one of `id` (reference an existing artifact) or `source` (inline a one-off artifact)",
+    message: "template must carry exactly one of `id` (reference an existing template) or `source` (inline a one-off template)",
 });
 export const createSessionSchema = z.object({
-    artifact: sessionArtifactSchema,
-    input_data: z.record(z.unknown()).optional(),
+    template: sessionArtifactSchema,
+    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.unknown()).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.
+    title: z.string().optional(),
+    // Phase G — natural-key dedup. When set, the relay collapses repeated
+    // creates with the same (template, owner, context_key) into one surface
+    // row. NULL = ad-hoc, no dedup. See HUMAN-SIDE-PROPOSAL.md §7.1.
+    context_key: z
+        .string()
+        .min(1)
+        .max(256)
+        .regex(/^[A-Za-z0-9_:.-]+$/, "context_key must be a short identifier")
+        .optional(),
 });
-// POST /v1/artifacts — create a named, reusable artifact plus its v1 content.
+// POST /v1/templates — create a named, reusable template plus its v1 content.
 export const createArtifactSchema = z.object({
     name: z.string().min(1),
     slug: z.string().min(1).optional(),
@@ -61,19 +83,19 @@ export const createArtifactSchema = z.object({
     tags: z.array(z.string().min(1)).optional(),
     source: z.string().min(1),
     type: artifactTypeSchema,
-    // Optional: omit for a view-only artifact (no event vocabulary).
+    // Optional: omit for a view-only template (no event vocabulary).
     event_schema: z.unknown().optional(),
-    input_schema: z.record(z.unknown()).optional(),
+    input_schema: z.record(z.string(), z.unknown()).optional(),
 });
-// POST /v1/artifacts/:id/versions — append a new version (content only).
+// POST /v1/templates/:id/versions — append a new version (content only).
 export const createArtifactVersionSchema = z.object({
     source: z.string().min(1),
     type: artifactTypeSchema,
-    // Optional: omit for a view-only artifact (no event vocabulary).
+    // Optional: omit for a view-only template (no event vocabulary).
     event_schema: z.unknown().optional(),
-    input_schema: z.record(z.unknown()).optional(),
+    input_schema: z.record(z.string(), z.unknown()).optional(),
 });
-// PATCH /v1/artifacts/:id — update head metadata only (never content).
+// PATCH /v1/templates/:id — update head metadata only (never content).
 export const patchArtifactMetadataSchema = z.object({
     name: z.string().min(1).optional(),
     slug: z.string().min(1).optional(),
@@ -90,5 +112,21 @@ export const submitFeedbackSchema = z.object({
         .string()
         .transform((s) => s.trim())
         .pipe(z.string().min(1).max(4000)),
-    session_id: z.string().min(1).optional(),
+    surface_id: z.string().min(1).optional(),
+});
+// GET /v1/surfaces — list the calling agent's surfaces. 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(),
+    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).
+export const mintParticipantSchema = z.object({
+    kind: z.literal("human"),
 });

package/dist/stream.d.ts

@@ -3,8 +3,8 @@ import type { PaneEvent } from "./types.js";
 export interface OpenStreamOptions {
     /** WebSocket base URL, e.g. wss://pane.example.com (no trailing slash). */
     wsBaseUrl: string;
-    /** Session id. */
-    sessionId: string;
+    /** Surface id. */
+    surfaceId: string;
     /** Agent (or participant) bearer token. */
     token: string;
     /** Opaque cursor: replay only events strictly after this id. */
@@ -32,7 +32,7 @@ export interface StreamHandlers {
 }
 /** A live handle to an open stream. */
 export interface StreamHandle {
-    /** Send an event frame into the session. */
+    /** Send an event frame into the surface. */
     send(frame: {
         type: string;
         data?: unknown;
@@ -45,7 +45,7 @@ export interface StreamHandle {
     readonly socket: WebSocket;
 }
 /**
- * Open a WebSocket stream to a Pane session. Replays on connect, then streams
+ * Open a WebSocket stream to a Pane surface. 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/sessions/:id/stream.
+// WebSocket client for WS /v1/surfaces/: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,12 +16,12 @@
 import { WebSocket } from "ws";
 import { MAX_FRAME_SNIPPET_LENGTH } from "./limits.js";
 /**
- * Open a WebSocket stream to a Pane session. Replays on connect, then streams
+ * Open a WebSocket stream to a Pane surface. 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/sessions/${encodeURIComponent(opts.sessionId)}/stream`);
+    const u = new URL(`${base}/v1/surfaces/${encodeURIComponent(opts.surfaceId)}/stream`);
     if (opts.since != null && opts.since !== "") {
         u.searchParams.set("since", opts.since);
     }