@jigs.design/server 0.1.2 → 0.3.0

package/dist/types.d.ts

@@ -2,8 +2,8 @@ import { Advice, DesignCheckCode, Placement } from "./design.js";
 import { ConfirmationStore } from "./confirm.js";
 import { EditFailureReason } from "@jigs.design/compiler";
 import { PromptMode } from "@jigs.design/prompt";
-import { ActionDefinition, CallPolicy, Catalog, Host, InputOf, MutationDefinition, OutputOf, ProcedureDefinition, Procedures } from "@jigs.design/host";
-import { ChatBlock, ChatBlockStatus, Diagnostic, Invalidation, JigsErrorData, Message, Program, SessionEvent } from "@jigs.design/runtime";
+import { ActionDefinition, CallPolicy, Catalog, Host, InputOf, JigDefinition, MutationDefinition, OutputOf, PageName, ProcedureDefinition, Procedures, QueryDefinition } from "@jigs.design/host";
+import { ChatBlock, ChatBlockStatus, Diagnostic, Invalidation, JigsErrorData, Message, PageInvalidation, PageProps, PageRef, Program, SessionEvent } from "@jigs.design/protocol";
 import { z } from "zod";
 //#region src/types.d.ts
 /**
@@ -25,7 +25,11 @@ export type ModelRequestKind = "chat-repair" | "repair" | "session";
 export interface ModelRequest<TContext, TOptions> {
   ctx: TContext;
   kind: ModelRequestKind;
-  /** The conversation, with the server's repair turns added. */
+  /**
+   * The conversation, with the server's repair turns added. In a session
+   * about a document, the last user message carries the current UI before
+   * the ask (`withDocument`), on every call.
+   */
   messages: ReadonlyArray<Message>;
   options: TOptions;
   signal: AbortSignal;
@@ -51,9 +55,10 @@ export interface TurnEdits {
   blocks: number;
   /**
    * Why the first edit that failed did: its SEARCH text is not in the
-   * source (`"missing"`) or is there more than once (`"ambiguous"`), the
-   * block is broken (`"malformed"`), or the edit left a tag unclosed or
-   * closed one twice (`"broken"`).
+   * source (`"missing"`) or is there more than once (`"ambiguous"`), an
+   * earlier edit of the reply changes some of the same lines
+   * (`"overlapping"`), the block is broken (`"malformed"`), or the edit
+   * left a tag unclosed or closed one twice (`"broken"`).
    */
   reason?: EditFailureReason;
 }
@@ -110,6 +115,12 @@ export interface Turn<TContext, TOptions> {
   ctx: TContext;
   /** The diagnostics sent with `done`; empty when the turn did not finish. */
   diagnostics: ReadonlyArray<Diagnostic>;
+  /**
+   * The source the turn started from, as the request carried it or the
+   * page it named resolved to; null when the turn wrote a new UI. A chat
+   * repair's is the block it repairs.
+   */
+  document: string | null;
   /**
    * Milliseconds from the start of the turn to its first `program` event;
    * null when it sent none. A chat repair sends its block once, when it is
@@ -118,6 +129,7 @@ export interface Turn<TContext, TOptions> {
   firstProgramMs: number | null;
   /** A session turn, or the repair of a chat block, which is a turn of its own. */
   kind: "chat-repair" | "session";
+  /** The conversation as the request carried it, without the document. */
   messages: ReadonlyArray<Message>;
   options: TOptions;
   /**
@@ -169,7 +181,10 @@ export type PolicyCall<TProcedures extends Procedures, TContext> = { [K in Mutat
  * "confirmed" when it ran with the user's approval.
  */
 export type CallReportOutcome = "confirmed" | "denied" | "error" | "requires-action" | "success";
-/** One call to a query, mutation or action, as `onCall` receives it. */
+/**
+ * One call to a query, mutation or action, or one page request, as
+ * `onCall` receives it.
+ */
 export interface CallReport<TContext> {
   ctx: TContext;
   /** From the call's arrival to its outcome, in milliseconds. */
@@ -181,26 +196,124 @@ export interface CallReport<TContext> {
    * failed before its input parsed.
    */
   input: unknown;
-  /** The kind the call declared. */
-  kind: ProcedureDefinition["kind"];
+  /**
+   * The kind the call declared, or "page" for a page request on the wire,
+   * whose `input` is its props.
+   */
+  kind: ProcedureDefinition["kind"] | "page";
   name: string;
   /**
-   * "denied" when a policy or a bad confirmation refused the call, "error"
-   * for any other failure, including one `run` threw.
+   * "denied" when a policy or a bad confirmation refused the call, or
+   * `pagePolicy` a page; "error" for any other failure, including one
+   * `run` threw and a page no list has.
    */
   outcome: CallReportOutcome;
 }
+/** The names of a host's queries. */
+type QueryName<TProcedures extends Procedures> = { [K in keyof TProcedures & string]: TProcedures[K] extends QueryDefinition ? K : never; }[keyof TProcedures & string];
+/**
+ * One query a push event refreshes, by name. `input` is typed against the
+ * query's input schema, as a mutation's scopes are, and the views' queries
+ * whose input contains it refetch; without it, every input does. It is a
+ * match key that every client the event reaches can read, never a record.
+ */
+export type PushInvalidation<TProcedures extends Procedures> = { [K in QueryName<TProcedures>]: {
+  input?: TProcedures[K]["input"] extends z.ZodType ? z.input<TProcedures[K]["input"]> : never;
+  name: K;
+}; }[QueryName<TProcedures>];
+/** Queries for one client's push stream to refetch. */
+export interface PushInvalidate<TProcedures extends Procedures> {
+  invalidate: ReadonlyArray<PushInvalidation<TProcedures>>;
+  type: "invalidate";
+}
+/**
+ * One page a push event refreshes: a page of the host by its name, or, with
+ * `saved: true`, any name `resolvePage` may answer. Without `props`, every
+ * props of the page refetches; with them, the pages whose props contain
+ * them. `saved` stays on the server: the client sees `{ name, props }`.
+ */
+export type PushPage<TPageName extends string> = PageInvalidation<TPageName> | (PageInvalidation & {
+  saved: true;
+});
+/** Pages for one client's push stream to refetch, by name. */
+export interface PushInvalidatePages<TPageName extends string> {
+  pages: ReadonlyArray<PushPage<TPageName>>;
+  type: "invalidate-pages";
+}
+/** What `send` writes to one client's push stream. */
+export type PushSend<TProcedures extends Procedures, TPageName extends string> = PushInvalidate<TProcedures> | PushInvalidatePages<TPageName>;
+/** One client's push stream, as the `events` option receives it. */
+export interface EventSubscriber<TProcedures extends Procedures, TContext, TPageName extends string = string> {
+  /**
+   * Writes a `close` event and ends the stream, for a platform that caps how
+   * long a response may last: the client reconnects and, having been told,
+   * refetches nothing.
+   */
+  close: () => void;
+  /** What `context` returned for the request that opened the stream. */
+  ctx: TContext;
+  /**
+   * Writes one event. `id` is yours (a log offset, a stream id), at most
+   * 200 printable characters; it comes back as `since` when the client
+   * reconnects. Give ids only if you replay from `since`: a client that
+   * resumed refetches nothing on its own. A send after the stream ended is
+   * ignored.
+   */
+  send: (event: PushSend<TProcedures, TPageName>, options?: {
+    id?: string;
+  }) => void;
+  /** Aborts when the client leaves or the stream ends. */
+  signal: AbortSignal;
+  /**
+   * The `Last-Event-ID` the client reconnected with, or null: none, or one
+   * longer than 200 characters or with a character that is not printable.
+   */
+  since: string | null;
+}
+/**
+ * The host's push fan-out: subscribe `send` to your own source of changes
+ * (an in-process emitter, Postgres `LISTEN`, Redis) and return the
+ * unsubscribe, which runs once when the stream ends. Filter by `ctx`: every
+ * event you send reaches that client.
+ */
+export type EventsFunction<TProcedures extends Procedures, TContext, TPageName extends string = string> = (subscriber: EventSubscriber<TProcedures, TContext, TPageName>) => (() => void) | Promise<() => void>;
 export interface ErrorInfo {
-  /** The procedure, for a call. */
+  /** The procedure, for a call; the page, for a page. */
   name?: string;
-  /** The request it came from: a call, a session turn, or a chat turn with its repairs. */
-  type: "call" | "chat" | "session";
+  /**
+   * The request it came from: a call, a session turn, a chat turn with its
+   * repairs, the push stream, or a page (`jigs.page` or its wire request).
+   */
+  type: "call" | "chat" | "events" | "page" | "session";
+}
+/** A page `resolvePage` found: the source as the app stored it. */
+export interface SavedPage {
+  /** The source, with its pragma line when the app kept it. */
+  source: string;
 }
+/**
+ * Finds a page the host does not ship, by name, for the caller `ctx` names.
+ * `null` is "no such page for this caller". Runs on every request for the
+ * name; cache in it if the store is slow. Throw a `JigsError` to refuse.
+ */
+export type PageResolver<TContext> = (name: string, call: {
+  ctx: TContext;
+  signal?: AbortSignal;
+}) => Promise<SavedPage | null> | SavedPage | null;
+/**
+ * Whether a shipped page may be served on the wire to the caller `ctx`
+ * names. Saved pages are scoped by `resolvePage` instead.
+ */
+export type PagePolicy<TContext, TPageName extends string = string> = (page: {
+  ctx: TContext;
+  name: TPageName;
+  props: PageProps;
+}) => "allow" | "deny";
 /**
  * `TContext` is inferred from `context`; `run` only reads it (`NoInfer`), so
  * a mistake in one `run` function is reported at that function.
  */
-export interface JigsServerOptions<TProcedures extends Procedures, TCatalog extends Catalog, TContext, TOptions, TSpecName extends string = never> {
+export interface JigsServerOptions<TProcedures extends Procedures, TCatalog extends Catalog, TContext, TJigs extends ReadonlyArray<JigDefinition> = ReadonlyArray<JigDefinition>> {
   /** Origins whose views may call this server and embed its frame. */
   allowedOrigins?: ReadonlyArray<string>;
   /**
@@ -221,12 +334,12 @@ export interface JigsServerOptions<TProcedures extends Procedures, TCatalog exte
    */
   context: ContextFunction<TContext>;
   /**
-   * Design checks whose advice gets a repair round, as errors do: at most
-   * one per turn or chat block, within `maxRepairs`. Default none, since a
-   * repair round is a full model call.
+   * Opens the push stream: a `GET` to the handler with `Accept:
+   * text/event-stream`, after `context`. Without it, that `GET` answers
+   * `204` and the client stops asking. See `EventsFunction`.
    */
-  designRepair?: ReadonlyArray<DesignCheckCode>;
-  host: Host<TProcedures, TCatalog>;
+  events?: EventsFunction<NoInfer<TProcedures>, NoInfer<TContext>, NoInfer<PageName<TJigs>>>;
+  host: Host<TProcedures, TCatalog, TJigs>;
   /**
    * The app's own instructions to the model, such as its persona, today's
    * date or its safety rules. Every prompt carries them: document-mode
@@ -235,23 +348,26 @@ export interface JigsServerOptions<TProcedures extends Procedures, TCatalog exte
   instructions?: string;
   /** The largest request body accepted, in bytes. Default 1,000,000. */
   maxBodyBytes?: number;
-  /** Repair rounds after a turn that ends with errors. Default 1. */
-  maxRepairs?: number;
-  model?: ModelFunction<TContext, TOptions>;
   /** The clock confirmation tokens expire by, in ms since the epoch. Default `Date.now`. */
   now?: () => number;
   /**
    * Runs after every call to a query, mutation or action, including ones
-   * refused before `run`. The response does not wait for it, and a value it
+   * refused before `run`, and after every page request on the wire, with
+   * `kind: "page"`, so both can be audited and rate-limited by `ctx`. The response does not wait for it, and a value it
    * throws or rejects with goes to `onError`.
    */
   onCall?: (call: CallReport<NoInfer<TContext>>) => Promise<void> | void;
   onError?: (cause: unknown, info: ErrorInfo) => void;
-  onTurn?: (turn: Turn<TContext, TOptions>) => Promise<void> | void;
-  /** Schema for the app options sent with each turn. */
-  options?: z.ZodType<TOptions>;
   /** This server's origin, when the request URL does not show it (behind a proxy). */
   origin?: string;
+  /**
+   * Decides whether a shipped page is served on the wire (`POST { type:
+   * "page" }`) to this `ctx`, after `context` and before any compile.
+   * "deny" answers `NOT_FOUND`, as for a page no list has. Default: every
+   * page to everyone `context` admits. A value it throws, or anything but
+   * "allow" or "deny", goes to `onError` and the page is denied.
+   */
+  pagePolicy?: PagePolicy<NoInfer<TContext>, PageName<TJigs>>;
   /**
    * Decides a mutation call's policy from its `ctx` and parsed input, after
    * the input parses and before `run`; `undefined` keeps the host's. A
@@ -259,13 +375,12 @@ export interface JigsServerOptions<TProcedures extends Procedures, TCatalog exte
    */
   policy?: (call: PolicyCall<NoInfer<TProcedures>, NoInfer<TContext>>) => CallPolicy | undefined;
   /**
-   * While a reply streams, the least time between two program updates, in
-   * ms. Each update carries the whole program, so a long reply that changed
-   * it at every line sent it hundreds of times. The first program goes out
-   * at once, a newer one replaces one still waiting, and the reply's last
-   * program always goes out. Default 250; 0 sends every change.
+   * Answers `page(name, props, { ctx })` and the wire's page requests for a
+   * name the host does not have, such as a page a user saved. A name on
+   * the host never reaches it. Saved pages compile leniently unless the
+   * call says `strict`. See `PageResolver`.
    */
-  programIntervalMs?: number;
+  resolvePage?: PageResolver<NoInfer<TContext>>;
   run: RunFunctions<NoInfer<TProcedures>, NoInfer<TContext>>;
   /**
    * Signs confirmation tokens, at least 32 characters; keep it out of the
@@ -273,11 +388,33 @@ export interface JigsServerOptions<TProcedures extends Procedures, TCatalog exte
    * "confirm": the server refuses to start without it.
    */
   secret?: string;
+}
+/**
+ * What `withModel` takes: everything that exists only because a model does.
+ * `TContext` is already the core's, so `ctx` is typed inside `model` and
+ * `onTurn` with no inference of its own.
+ */
+export interface ModelOptions<TContext, TOptions> {
   /**
-   * Stored specs by name, compiled once at startup. A diagnostic worse than
-   * info stops the server, as a bad recipe does. Read one with `spec(name)`.
+   * Design checks whose advice gets a repair round, as errors do: at most
+   * one per turn or chat block, within `maxRepairs`. Default none, since a
+   * repair round is a full model call.
    */
-  specs?: Readonly<Record<TSpecName, string>>;
+  designRepair?: ReadonlyArray<DesignCheckCode>;
+  /** Repair rounds after a turn that ends with errors. Default 1. */
+  maxRepairs?: number;
+  model: ModelFunction<TContext, TOptions>;
+  onTurn?: (turn: Turn<TContext, TOptions>) => Promise<void> | void;
+  /** Schema for the app options sent with each turn. */
+  options?: z.ZodType<TOptions>;
+  /**
+   * While a reply streams, the least time between two program updates, in
+   * ms. Each update carries the whole program, so a long reply that changed
+   * it at every line sent it hundreds of times. The first program goes out
+   * at once, a newer one replaces one still waiting, and the reply's last
+   * program always goes out. Default 250; 0 sends every change.
+   */
+  programIntervalMs?: number;
 }
 export interface CompileOptions {
   /**
@@ -328,14 +465,20 @@ export interface CallRequest {
   name: string;
 }
 export interface SessionRequest {
-  /** Plain JSON from the browser; parsed with the messages schema. */
+  /**
+   * Plain JSON from the browser: `{ source }`, or `{ name, props? }` for a
+   * page the server serves, opened as a document. Absent for a new UI.
+   */
+  document?: unknown;
+  /** Plain JSON from the browser; parsed with the session schema. */
   messages: unknown;
   /** Plain JSON from the browser; parsed with the `options` schema. */
   options?: unknown;
 }
 /** An earlier block of the conversation, as the chat stored it. */
 export interface ChatBlockSource {
-  id: string;
+  /** The block's name, the fence id. */
+  name: string;
   /** Its checked source; with or without the pragma line. */
   source: string;
 }
@@ -359,16 +502,19 @@ export interface ChatBlockResult {
   /** Set when the block was SEARCH/REPLACE edits to an earlier block. */
   edits?: TurnEdits;
   /**
-   * Set when the block is done without a program of its own: an edit to an
-   * id the conversation does not have (`NOT_FOUND`), a block past the
+   * Set when the block is done without a program of its own: an edit to a
+   * name the conversation does not have (`NOT_FOUND`), a block past the
    * reply's limit (`RATE_LIMITED`), or an edit or repair that failed
    * (`INTERNAL`). The same error the block carries.
    */
   error?: JigsErrorData;
   /** False for Jigs the model wrote without a fence. */
   fenced: boolean;
-  id: string;
   key: string;
+  /** The block's name, the fence id. */
+  name: string;
+  /** Set when the block is one tag naming a page, as on the block. */
+  ref?: PageRef;
   /**
    * The rounds of the block's repair, the ones its "chat-repair" turn gives
    * `onTurn`; empty when it had none. The last one's diagnostics are the
@@ -437,15 +583,58 @@ export interface ChatTurn {
   /** The start of `system` that is the same on every turn, as on `ModelRequest`. */
   systemPrefix: string;
 }
-export interface JigsServer<TContext, TSpecName extends string = never> {
-  call: (request: CallRequest, context: CallContext<TContext>) => Promise<CallOutcome>;
+/** A page, compiled, and what the checks said about it. */
+export interface ResolvedPage {
+  /** The design checks' advice, numbered like `diagnostics`. */
+  advice: ReadonlyArray<Advice>;
   /**
-   * Starts a chat reply for `request`. It refuses the request as `handler`
-   * would (an `Origin` that may not call this server, or a body that is not
-   * JSON), then runs `context` and parses `blocks` and `options`. Each
-   * failure rejects with a `JigsError`. See `ChatTurn`.
+   * Never an error or warning for a shipped page, or a saved one compiled
+   * with `strict`. A saved page is lenient by default: these say what
+   * broke, beside a program that still runs. Show a notice when one is.
    */
-  chat: (request: Request, options?: ChatOptions) => Promise<ChatTurn>;
+  diagnostics: ReadonlyArray<Diagnostic>;
+  /** "shipped": a jig listed on the host; "saved": one `resolvePage` found. */
+  origin: "saved" | "shipped";
+  program: Program;
+  /**
+   * What was compiled: a document page's source, or a define page's
+   * one-tag use, such as `<orders status={"open"}/>`.
+   */
+  source: string;
+}
+/** How `page` finds a name the host may not ship: through `resolvePage`, for `ctx`. */
+export interface PageCall<TContext> {
+  ctx: TContext;
+  signal?: AbortSignal;
+  /**
+   * Reject with a `JigsCompileError` when a saved page has an error or
+   * warning diagnostic, instead of resolving with them. Default false. A
+   * shipped page is always strict.
+   */
+  strict?: boolean;
+}
+/**
+ * A page by name: a shipped one with only a name and props, or any name
+ * with `{ ctx }`, which may ask `resolvePage`.
+ */
+export interface PageFunction<TContext, TPageName extends string> {
+  /**
+   * A shipped page. Rejects with a `JigsError` whose code is `BAD_INPUT`
+   * when the props are not the define's, so a route that takes props from
+   * a URL answers 400.
+   */
+  (name: TPageName, props?: PageProps, call?: {
+    signal?: AbortSignal;
+  }): Promise<ResolvedPage>;
+  /**
+   * Any name: a shipped page wins and never asks `resolvePage`; otherwise
+   * `resolvePage` with `ctx`. Null when neither has it. A saved page takes
+   * no props (`BAD_INPUT`).
+   */
+  (name: string, props: PageProps | undefined, call: PageCall<TContext>): Promise<ResolvedPage | null>;
+}
+export interface JigsServer<TContext, TPageName extends string = never> {
+  call: (request: CallRequest, context: CallContext<TContext>) => Promise<CallOutcome>;
   /** Checks and compiles a source with no model. Strict unless told otherwise. */
   compile: (source: string, options?: CompileOptions) => Promise<{
     /** The design checks' advice, numbered like `diagnostics`. */
@@ -453,11 +642,30 @@ export interface JigsServer<TContext, TSpecName extends string = never> {
     diagnostics: ReadonlyArray<Diagnostic>;
     program: Program;
   }>;
+  /**
+   * The push stream for `request`, whose `ctx` the caller already has: a
+   * foreign `Origin` is `403`, a server without `events` answers `204`, and
+   * an `events` that throws is `500`. `handler` does this for a `GET` that
+   * accepts `text/event-stream`, after `context`.
+   */
+  events: (request: Request, context: CallContext<TContext>) => Promise<Response>;
   /** The sandbox frame document, with its own content security policy. */
   frame: (request?: Request) => Response;
+  /**
+   * Serves the frame, the push stream, calls, pages and session turns. Without `withModel`, a
+   * session turn that would ask the model answers `404 NOT_FOUND`; one
+   * that carries a document and no ask is still compiled and streamed.
+   */
   handler: (request: Request) => Promise<Response>;
   /** The largest request body `handler` accepts, in bytes. */
   maxBodyBytes: number;
+  /**
+   * A page, compiled: a jig with `page: true`, by its name, with the props
+   * its `<define>` declares, or with `{ ctx }`, a page `resolvePage` finds.
+   * Shipped pages that need no props compile at startup, and every shipped
+   * page compiles strictly. See `PageFunction`.
+   */
+  page: PageFunction<TContext, TPageName>;
   /**
    * The system prompt for this host. "document" (default) is what sessions
    * use: every reply is one UI. "chat" is Markdown with UIs in fenced
@@ -471,11 +679,29 @@ export interface JigsServer<TContext, TSpecName extends string = never> {
    * `@jigs.design/ai-sdk`).
    */
   promptPrefix: (mode?: PromptMode) => string;
-  session: (body: SessionRequest, context: CallContext<TContext>) => AsyncIterable<SessionEvent>;
-  /** A spec from `specs`, compiled at startup. */
-  spec: (name: TSpecName) => Program;
   /** Changes whenever the compiler, the runtime or the host does. */
   version: string;
+  /**
+   * This server with a model: the same core, plus `session` and `chat`,
+   * and a handler that runs session turns that ask the model.
+   */
+  withModel: <TOptions = undefined>(options: ModelOptions<TContext, TOptions>) => JigsModelServer<TContext, TPageName>;
+}
+/** What `withModel` returns: the core, plus the turns that call the model. */
+export interface JigsModelServer<TContext, TPageName extends string = never> extends Omit<JigsServer<TContext, TPageName>, "withModel"> {
+  /**
+   * Starts a chat reply for `request`. It refuses the request as `handler`
+   * would (an `Origin` that may not call this server, or a body that is not
+   * JSON), then runs `context` and parses `blocks` and `options`. Each
+   * failure rejects with a `JigsError`. See `ChatTurn`.
+   */
+  chat: (request: Request, options?: ChatOptions) => Promise<ChatTurn>;
+  /**
+   * One session turn: a document whose conversation does not end with an
+   * ask is compiled again with no model call; otherwise the model answers,
+   * editing the document when there is one.
+   */
+  session: (body: SessionRequest, context: CallContext<TContext>) => AsyncIterable<SessionEvent>;
 }
 //#endregion
 export type { EditFailureReason };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jigs.design/server",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "createJigsServer: checks and streams programs, runs procedures, and serves the sandbox frame.",
   "license": "MIT",
   "repository": {
@@ -29,10 +29,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@jigs.design/host": "0.1.2",
-    "@jigs.design/prompt": "0.1.2",
-    "@jigs.design/compiler": "0.1.2",
-    "@jigs.design/runtime": "0.1.2"
+    "@jigs.design/compiler": "0.3.0",
+    "@jigs.design/prompt": "0.3.0",
+    "@jigs.design/protocol": "0.3.0",
+    "@jigs.design/runtime": "0.3.0",
+    "@jigs.design/host": "0.3.0"
   },
   "peerDependencies": {
     "zod": "^4.0.0"