@paneui/core 0.0.6 → 0.0.7

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,32 +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 session's `input_data` is validated against
-    // this JSON Schema before the session row is created — and any blob refs
-    // declared at `format: pane-blob-id` sites become reachable from the page
-    // via `window.pane.downloadBlob()`. Without this, blob refs in
-    // `input_data` are silently unreachable for inline sessions (the
-    // participant blob-download bridge walks input_data against the artifact
+    // 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
@@ -51,22 +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,
+    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.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 Artifact.name on the reference
+    // 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(),
@@ -74,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.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.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(),
@@ -103,9 +112,9 @@ 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/sessions — list the calling agent's sessions. The relay also
+// 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"]);
@@ -113,11 +122,11 @@ export const listSessionsQuerySchema = z.object({
     status: listSessionsStatusSchema.optional(),
     limit: z.number().int().positive().max(200).optional(),
     cursor: z.string().min(1).optional(),
-    artifact_id: z.string().min(1).optional(),
+    template_id: z.string().min(1).optional(),
 });
-// POST /v1/sessions/:id/participants — mint a fresh participant URL for an
-// existing session. v1 supports human participants only (the agent token is
-// minted at session-create and cannot be re-minted via this endpoint).
+// 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);
     }

package/dist/types.d.ts

@@ -4,7 +4,7 @@ export type AuthorKind = "human" | "agent" | "system";
 /** A single event envelope as emitted by the relay. */
 export interface PaneEvent {
     id: string;
-    session_id: string;
+    surface_id: string;
     author: {
         kind: AuthorKind;
         id: string;
@@ -15,14 +15,14 @@ export interface PaneEvent {
     causation_id: string | null;
     idempotency_key: string | null;
 }
-/** The artifact content type. `html-ref` is rejected by the relay for now. */
-export type ArtifactType = "html-inline" | "html-ref";
+/** The template content type. `html-ref` is rejected by the relay for now. */
+export type TemplateType = "html-inline" | "html-ref";
 /**
- * An artifact: discriminated on `type`. `html-inline` carries raw HTML in
+ * An template: discriminated on `type`. `html-inline` carries raw HTML in
  * `source`; `html-ref` carries a URL the relay/shell fetches on the human's
  * behalf. The discriminant keeps the type↔source coupling explicit.
  */
-export type Artifact = {
+export type Template = {
     type: "html-inline";
     source: string;
 } | {
@@ -36,13 +36,13 @@ export interface Callback {
     secret: string;
 }
 /**
- * Request body for POST /v1/sessions. Derived from `createSessionSchema` so the
+ * Request body for POST /v1/surfaces. Derived from `createSessionSchema` so the
  * runtime validator and the static type cannot drift.
  */
 export type CreateSessionRequest = z.infer<typeof createSessionSchema>;
-/** Response from POST /v1/sessions. */
+/** Response from POST /v1/surfaces. */
 export interface CreateSessionResponse {
-    session_id: string;
+    surface_id: string;
     tokens: {
         humans: string[];
         agent: string;
@@ -52,31 +52,31 @@ export interface CreateSessionResponse {
         agent_stream: string;
     };
     expires_at: string;
-    /** The resolved tab title persisted on the session (the agent's value, or
-     * the Artifact.name fallback). */
+    /** The resolved tab title persisted on the surface (the agent's value, or
+     * the Template.name fallback). */
     title: string;
 }
-/** Response from GET /v1/sessions/:id. */
-export interface SessionState {
-    session_id: string;
+/** Response from GET /v1/surfaces/:id. */
+export interface SurfaceState {
+    surface_id: string;
     status: string;
-    /** The artifact version this session is pinned to. */
-    artifact_id: string;
-    artifact_version_id: string;
-    artifact_version: number;
-    /** The tab title this session was created with (frozen for its lifetime). */
+    /** The template version this surface 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). */
     title: string;
     metadata: Record<string, unknown> | null;
     input_data: Record<string, unknown> | null;
     created_at: string;
     expires_at: string;
 }
-/** Response from GET /v1/sessions/:id/events. */
+/** Response from GET /v1/surfaces/:id/events. */
 export interface EventsPage {
     events: PaneEvent[];
     next_cursor: string | null;
 }
-/** A non-secret summary of one participant on a session — safe to list. */
+/** A non-secret summary of one participant on a surface — safe to list. */
 export interface ParticipantSummary {
     /** The revoke handle (Participant.id). */
     participant_id: string;
@@ -89,43 +89,43 @@ export interface ParticipantSummary {
     /** ISO timestamp the participant was revoked; null while still active. */
     revoked_at: string | null;
 }
-/** A row in the GET /v1/sessions list response (no secrets, lean). */
-export interface SessionSummary {
-    session_id: string;
-    /** Tab title (required column; agent input or Artifact.name fallback). */
+/** A row in the GET /v1/surfaces list response (no secrets, lean). */
+export interface SurfaceSummary {
+    surface_id: string;
+    /** Tab title (required column; agent input or Template.name fallback). */
     title: string;
     /** Effective status — respects expiresAt projection (the column may say
      *  "open" while `expires_at` is in the past; the projection reports "closed"). */
     status: "open" | "closed";
-    /** Owning artifact's head id. Null for inline (anonymous) artifacts. */
-    artifact_id: string | null;
-    artifact_version_id: string;
-    artifact_version: number;
+    /** Owning template's head id. Null for inline (anonymous) templates. */
+    template_id: string | null;
+    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 sessions
+     *  array is intentionally NOT inlined here — agents with many surfaces
      *  would pay the bandwidth on every list call. Fetch
-     *  `GET /v1/sessions/:id/participants` when you need the rows. */
+     *  `GET /v1/surfaces/:id/participants` when you need the rows. */
     active_human_participants: number;
     created_at: string;
     expires_at: string;
-    /** Whether the session has a webhook callback configured (URL is NOT
+    /** Whether the surface has a webhook callback configured (URL is NOT
      *  returned — it may carry a secret in the path). */
     has_callback: boolean;
 }
-/** Response from GET /v1/sessions/:id/participants — every participant on
- *  one session (active and revoked). Bounded by MAX_PARTICIPANTS_PER_SESSION
+/** Response from GET /v1/surfaces/:id/participants — every participant on
+ *  one surface (active and revoked). Bounded by MAX_PARTICIPANTS_PER_SESSION
  *  on the relay so no pagination is needed. */
 export interface ParticipantsList {
-    session_id: string;
+    surface_id: string;
     items: ParticipantSummary[];
 }
-/** Response from GET /v1/sessions. */
-export interface SessionsPage {
-    items: SessionSummary[];
+/** Response from GET /v1/surfaces. */
+export interface SurfacesPage {
+    items: SurfaceSummary[];
     /** Opaque cursor for the next page; null when no more rows. */
     next_cursor: string | null;
 }
-/** Response from POST /v1/sessions/:id/participants — one-shot, includes the
+/** Response from POST /v1/surfaces/:id/participants — one-shot, includes the
  *  plaintext token exactly once. The relay stores only the hash. */
 export interface MintParticipantResponse {
     participant_id: string;
@@ -136,17 +136,17 @@ export interface MintParticipantResponse {
     url: string;
     created_at: string;
 }
-/** One immutable version of an artifact's content. */
-export interface ArtifactVersion {
+/** One immutable version of an template's content. */
+export interface TemplateVersion {
     id: string;
     version: number;
-    type: ArtifactType;
+    type: TemplateType;
     source: string;
     event_schema: unknown;
     input_schema: Record<string, unknown> | null;
     created_at: string;
 }
-/** A full artifact — head metadata plus its version list. */
+/** A full template — head metadata plus its version list. */
 export interface Artifact_ {
     id: string;
     slug: string | null;
@@ -157,18 +157,18 @@ export interface Artifact_ {
     last_used_at: string | null;
     created_at: string;
     updated_at: string;
-    versions: ArtifactVersion[];
+    versions: TemplateVersion[];
 }
 /**
- * A full artifact — head metadata plus its version list. (`ArtifactRecord` is
- * the public name; `Artifact` is kept as the older inline-artifact union.)
+ * A full template — head metadata plus its version list. (`TemplateRecord` is
+ * the public name; `Template` is kept as the older inline-template union.)
  */
-export type ArtifactRecord = Artifact_;
+export type TemplateRecord = Artifact_;
 /**
- * A lean artifact summary for list/search responses — head metadata only, no
- * `source` blob. See GET /v1/artifacts.
+ * A lean template summary for list/search responses — head metadata only, no
+ * `source` attachment. See GET /v1/templates.
  */
-export interface ArtifactSummary {
+export interface TemplateSummary {
     id: string;
     slug: string | null;
     name: string | null;
@@ -177,9 +177,9 @@ export interface ArtifactSummary {
     latest_version: number;
     last_used_at: string | null;
 }
-/** Response from POST /v1/artifacts and POST /v1/artifacts/:id/versions. */
+/** Response from POST /v1/templates and POST /v1/templates/:id/versions. */
 export interface CreateArtifactResponse {
-    artifact_id: string;
+    template_id: string;
     version: number;
 }
 /**
@@ -197,7 +197,7 @@ export interface KeyInfo {
 }
 /**
  * Response from GET /v1/taste, PUT /v1/taste — the calling agent's freeform
- * "taste notes" markdown blob (presentation preferences the agent has picked
+ * "taste notes" markdown attachment (presentation preferences the agent has picked
  * up from human feedback over time). `taste` and `updated_at` are null when
  * the agent has never written notes; `bytes` is the utf8 byte length and 0
  * when `taste` is null.
@@ -220,7 +220,7 @@ export interface FeedbackRecord {
     id: string;
     type: FeedbackType;
     message: string;
-    session_id: string | null;
+    surface_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.6",
+  "version": "0.0.7",
   "description": "Pane relay client: typed HTTP + WebSocket operations against a Pane relay. Framework-free.",
   "license": "MIT",
   "type": "module",