@jigs.design/protocol 0.2.0 → 0.3.1

package/dist/diagnostics.d.ts

@@ -9,7 +9,7 @@
  *
  * - `error`: what the model wrote is wrong there. The program still runs,
  *   with that part dropped or replaced, but the turn is not valid: the server
- *   asks the model for a repair, and a strict compile (a stored spec, a
+ *   asks the model for a repair, and a strict compile (a page, a
  *   situation's example, `jigs.compile`) fails.
  * - `warning`: the source itself may be fine, but it was written for a
  *   language or catalog newer than this server's, so it may not mean what it

package/dist/diagnostics.js

@@ -9,7 +9,7 @@
 *
 * - `error`: what the model wrote is wrong there. The program still runs,
 *   with that part dropped or replaced, but the turn is not valid: the server
-*   asks the model for a repair, and a strict compile (a stored spec, a
+*   asks the model for a repair, and a strict compile (a page, a
 *   situation's example, `jigs.compile`) fails.
 * - `warning`: the source itself may be fine, but it was written for a
 *   language or catalog newer than this server's, so it may not mean what it

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Diagnostic, DiagnosticFix, Severity, Span, severities } from "./diagnostics.js";
-import { ChatBlock, ChatBlockStatus, ChildrenKind, ComponentSchema, Invalidation, JigsErrorCode, JigsErrorData, JsonValue, Message, NumberPropSchema, PROGRAM_FORMAT, ProcedureEntry, ProcedureKind, Program, PropSchema, SessionBody, SessionEvent, SessionOptions, jigsErrorCodes } from "./types.js";
+import { ChatBlock, ChatBlockStatus, ChildrenKind, ComponentSchema, Invalidation, JigsErrorCode, JigsErrorData, JsonValue, Message, NumberPropSchema, PROGRAM_FORMAT, PageInvalidation, PageProps, PageRef, PageReply, ProcedureEntry, ProcedureKind, Program, PropSchema, PushEvent, SessionBody, SessionDocument, SessionEvent, SessionOptions, jigsErrorCodes } from "./types.js";
 import { FrameMessage, HostMessage, MutationCall, MutationResult, Op, QueryRead, QueryResult, ROOT_ID, Row, RuntimeError, WireArg, WireProps, WireValue, WorkerMessage } from "./protocol.js";
-import { parseErrorData, parseInvalidations, parseProgram, parseSessionEvent } from "./parse.js";
+import { parseErrorData, parseInvalidations, parsePageReply, parseProgram, parsePushEvent, parseSessionEvent } from "./parse.js";
 import { isAllowedImage, isAllowedLink, isImageHostEntry, normalizeImageHost } from "./urls.js";
-export { type ChatBlock, type ChatBlockStatus, type ChildrenKind, type ComponentSchema, type Diagnostic, type DiagnosticFix, type FrameMessage, type HostMessage, type Invalidation, type JigsErrorCode, type JigsErrorData, type JsonValue, type Message, type MutationCall, type MutationResult, type NumberPropSchema, type Op, PROGRAM_FORMAT, type ProcedureEntry, type ProcedureKind, type Program, type PropSchema, type QueryRead, type QueryResult, ROOT_ID, type Row, type RuntimeError, type SessionBody, type SessionEvent, type SessionOptions, type Severity, type Span, type WireArg, type WireProps, type WireValue, type WorkerMessage, isAllowedImage, isAllowedLink, isImageHostEntry, jigsErrorCodes, normalizeImageHost, parseErrorData, parseInvalidations, parseProgram, parseSessionEvent, severities };
+export { type ChatBlock, type ChatBlockStatus, type ChildrenKind, type ComponentSchema, type Diagnostic, type DiagnosticFix, type FrameMessage, type HostMessage, type Invalidation, type JigsErrorCode, type JigsErrorData, type JsonValue, type Message, type MutationCall, type MutationResult, type NumberPropSchema, type Op, PROGRAM_FORMAT, type PageInvalidation, type PageProps, type PageRef, type PageReply, type ProcedureEntry, type ProcedureKind, type Program, type PropSchema, type PushEvent, type QueryRead, type QueryResult, ROOT_ID, type Row, type RuntimeError, type SessionBody, type SessionDocument, type SessionEvent, type SessionOptions, type Severity, type Span, type WireArg, type WireProps, type WireValue, type WorkerMessage, isAllowedImage, isAllowedLink, isImageHostEntry, jigsErrorCodes, normalizeImageHost, parseErrorData, parseInvalidations, parsePageReply, parseProgram, parsePushEvent, parseSessionEvent, severities };

package/dist/index.js

@@ -1,6 +1,6 @@
 import { PROGRAM_FORMAT, jigsErrorCodes } from "./types.js";
 import { severities } from "./diagnostics.js";
 import { ROOT_ID } from "./protocol.js";
-import { parseErrorData, parseInvalidations, parseProgram, parseSessionEvent } from "./parse.js";
+import { parseErrorData, parseInvalidations, parsePageReply, parseProgram, parsePushEvent, parseSessionEvent } from "./parse.js";
 import { isAllowedImage, isAllowedLink, isImageHostEntry, normalizeImageHost } from "./urls.js";
-export { PROGRAM_FORMAT, ROOT_ID, isAllowedImage, isAllowedLink, isImageHostEntry, jigsErrorCodes, normalizeImageHost, parseErrorData, parseInvalidations, parseProgram, parseSessionEvent, severities };
+export { PROGRAM_FORMAT, ROOT_ID, isAllowedImage, isAllowedLink, isImageHostEntry, jigsErrorCodes, normalizeImageHost, parseErrorData, parseInvalidations, parsePageReply, parseProgram, parsePushEvent, parseSessionEvent, severities };

package/dist/parse.d.ts

@@ -1,9 +1,17 @@
-import { Invalidation, JigsErrorData, Program, SessionEvent } from "./types.js";
+import { Invalidation, JigsErrorData, PageReply, Program, PushEvent, SessionEvent } from "./types.js";
 //#region src/parse.d.ts
 export declare function parseErrorData(value: unknown): JigsErrorData | null;
 /** The `invalidate` list of a mutation's reply. */
 export declare function parseInvalidations(value: unknown): ReadonlyArray<Invalidation> | null;
 export declare function parseProgram(value: unknown): Program | null;
+/** A page request's reply body, or null when it is not one. */
+export declare function parsePageReply(value: unknown): PageReply | null;
 /** One session event from its JSON text, or null when it is not one. */
 export declare function parseSessionEvent(text: string): SessionEvent | null;
+/**
+ * One event of the push stream from its JSON text, or null when it is not
+ * one the server may send. `open` and `version` come from the transport,
+ * never the wire, so they are null here.
+ */
+export declare function parsePushEvent(text: string): PushEvent | null;
 //#endregion

package/dist/parse.js

@@ -41,6 +41,27 @@ function parseInvalidations(value) {
 	}
 	return out;
 }
+const isScalar = (value) => typeof value === "boolean" || typeof value === "number" || typeof value === "string";
+function parsePageInvalidation(value) {
+	if (!isRecord(value) || !isString(value.name)) return null;
+	if (!("props" in value)) return { name: value.name };
+	const props = recordOf(value.props, (entry) => isScalar(entry) ? entry : null);
+	return props === null ? null : {
+		name: value.name,
+		props
+	};
+}
+/** The `pages` list of an `invalidate-pages` event. */
+function parsePageInvalidations(value) {
+	if (!Array.isArray(value)) return null;
+	const out = [];
+	for (const entry of value) {
+		const parsed = parsePageInvalidation(entry);
+		if (parsed === null) return null;
+		out.push(parsed);
+	}
+	return out;
+}
 function parsePropSchema(value) {
 	if (!isRecord(value)) return null;
 	switch (value.kind) {
@@ -73,7 +94,7 @@ function parseComponentSchema(value) {
 	};
 }
 function parseProcedure(value) {
-	if (!isRecord(value) || value.kind !== "query" && value.kind !== "mutation" && value.kind !== "action" || !isStringList(value.invalidates)) return null;
+	if (!isRecord(value) || value.kind !== "query" && value.kind !== "mutation" && value.kind !== "action" && value.kind !== "data" || !isStringList(value.invalidates)) return null;
 	return {
 		invalidates: value.invalidates,
 		kind: value.kind
@@ -111,6 +132,17 @@ function parseDiagnostics(value) {
 		return parsed === null ? [] : [parsed];
 	});
 }
+/** A page request's reply body, or null when it is not one. */
+function parsePageReply(value) {
+	if (!isRecord(value) || !isString(value.version)) return null;
+	const program = parseProgram(value.program);
+	const diagnostics = parseDiagnostics(value.diagnostics);
+	return program === null || diagnostics === null ? null : {
+		diagnostics,
+		program,
+		version: value.version
+	};
+}
 /** One session event from its JSON text, or null when it is not one. */
 function parseSessionEvent(text) {
 	let value;
@@ -139,7 +171,13 @@ function parseSessionEvent(text) {
 			type: "program"
 		};
 	}
-	if (value.type === "done" && isString(value.source)) return {
+	if (value.type === "done" && isString(value.source)) return isString(value.reply) ? {
+		diagnostics,
+		reply: value.reply,
+		revision: value.revision,
+		source: value.source,
+		type: "done"
+	} : {
 		diagnostics,
 		revision: value.revision,
 		source: value.source,
@@ -147,5 +185,35 @@ function parseSessionEvent(text) {
 	};
 	return null;
 }
+/**
+* One event of the push stream from its JSON text, or null when it is not
+* one the server may send. `open` and `version` come from the transport,
+* never the wire, so they are null here.
+*/
+function parsePushEvent(text) {
+	let value;
+	try {
+		value = JSON.parse(text);
+	} catch {
+		return null;
+	}
+	if (!isRecord(value)) return null;
+	if (value.type === "close") return { type: "close" };
+	if (value.type === "invalidate") {
+		const invalidate = parseInvalidations(value.invalidate);
+		return invalidate === null ? null : {
+			invalidate,
+			type: "invalidate"
+		};
+	}
+	if (value.type === "invalidate-pages") {
+		const pages = parsePageInvalidations(value.pages);
+		return pages === null ? null : {
+			pages,
+			type: "invalidate-pages"
+		};
+	}
+	return null;
+}
 //#endregion
-export { parseErrorData, parseInvalidations, parseProgram, parseSessionEvent };
+export { parseErrorData, parseInvalidations, parsePageReply, parseProgram, parsePushEvent, parseSessionEvent };

package/dist/types.d.ts

@@ -40,8 +40,11 @@ export interface ComponentSchema {
   children: ChildrenKind;
   props: Readonly<Record<string, PropSchema>>;
 }
-/** `action` is a mutation the embedding page handles instead of the server. */
-export type ProcedureKind = "action" | "mutation" | "query";
+/**
+ * `action` is a mutation the embedding page handles instead of the server;
+ * `data` is a slot the page provides, read with `useQuery` and never fetched.
+ */
+export type ProcedureKind = "action" | "data" | "mutation" | "query";
 export interface ProcedureEntry {
   invalidates: ReadonlyArray<string>;
   kind: ProcedureKind;
@@ -51,10 +54,35 @@ export interface ProcedureEntry {
  * data. Without `input`, every input of the query refetches. With it, only
  * the queries whose input contains those values.
  */
-export interface Invalidation {
+export interface Invalidation<TName extends string = string> {
   input?: JsonValue;
-  name: string;
+  name: TName;
 }
+/**
+ * What the push channel carries. The server sends `invalidate` (the queries
+ * to refetch, by name), `invalidate-pages` (the pages to refetch, by name)
+ * and `close` (it is ending the stream on purpose, so the next connection is
+ * no gap). The transport adds `open` on every connection it makes, with
+ * `replayed` true when it asked the server to resume from the last event
+ * id, and `version`, the server's `jigs-version` on that connection. A
+ * server cannot send `open` or `version`. No event carries a program: a
+ * page refetches its own.
+ */
+export type PushEvent = {
+  invalidate: ReadonlyArray<Invalidation>;
+  type: "invalidate";
+} | {
+  pages: ReadonlyArray<PageInvalidation>;
+  type: "invalidate-pages";
+} | {
+  replayed: boolean;
+  type: "open";
+} | {
+  type: "close";
+} | {
+  type: "version";
+  version: string;
+};
 /**
  * A compiled spec. Opaque to apps: pass it from the server to the view and
  * nowhere else. The view trusts its schemas and image hosts.
@@ -70,6 +98,10 @@ export interface Program {
   /** Text nodes pulled out of the code, so a prose edit swaps a table. */
   prose: Readonly<Record<string, string>>;
 }
+/**
+ * One message of a session's conversation: the user's ask, or the model's
+ * reply as it wrote it. The current UI travels beside it, as `document`.
+ */
 export interface Message {
   content: string;
   role: "assistant" | "user";
@@ -87,13 +119,52 @@ export type SessionEvent = {
   type: "program";
 } | {
   diagnostics: ReadonlyArray<Diagnostic>;
+  /**
+   * The assistant's message for the conversation, absent when no model
+   * ran: the reply as written when the turn took one round and the
+   * server did not reorder it, otherwise the checked source.
+   */
+  reply?: string;
   revision: number;
+  /** The new document: the checked source, with its pragma. */
   source: string;
   type: "done";
 } | {
   error: JigsErrorData;
   type: "error";
 };
+/**
+ * A page's props. Scalars only: the compiler types a prop only when it is
+ * a literal, and a define cannot declare an object prop.
+ */
+export type PageProps = Readonly<Record<string, boolean | number | string>>;
+/** A page of the host and the props it was asked for. */
+export interface PageRef {
+  /** The page jig's name. */
+  name: string;
+  /** Its props, keys sorted. */
+  props: PageProps;
+}
+/**
+ * One page a push event refreshes, by name. Without `props`, every props of
+ * the page refetches; with them, only the pages whose props contain those
+ * values, as an `Invalidation`'s `input` matches.
+ */
+export interface PageInvalidation<TName extends string = string> {
+  name: TName;
+  props?: PageProps;
+}
+/**
+ * The answer to a page request, `POST { type: "page", name, props }`: the
+ * page's program, its diagnostics (a saved page is compiled leniently, so
+ * they may hold errors), and the server's `jigs-version`, so a client can
+ * drop programs an older server compiled.
+ */
+export interface PageReply {
+  diagnostics: ReadonlyArray<Diagnostic>;
+  program: Program;
+  version: string;
+}
 /**
  * Where a chat block is: still arriving, being repaired after it closed with
  * errors, or final.
@@ -109,15 +180,23 @@ export interface ChatBlock {
   diagnostics: ReadonlyArray<Diagnostic>;
   /** Set when the block could not be built, e.g. an edit to a missing UI. */
   error?: JigsErrorData;
-  /** The id the model gave the block, e.g. "monthly-spending". */
-  id: string;
-  /** `${id}@${version}`: unique in a conversation. */
+  /** `${name}@${version}`: unique in a conversation. */
   key: string;
+  /**
+   * The fence id the model gave the block, e.g. "monthly-spending": the
+   * jig's name in the conversation's scope.
+   */
+  name: string;
   program: Program;
+  /**
+   * Set when the whole block is one tag naming a page of the host, with
+   * literal props: the block is that page, so the app can link to it.
+   */
+  ref?: PageRef;
   /** The checked source, with its pragma. Store this, not the program. */
   source: string;
   status: ChatBlockStatus;
-  /** 1 for the first block with this id in the conversation, then 2, 3… */
+  /** 1 for the first block with this name in the conversation, then 2, 3… */
   version: number;
 }
 /** A value that travels as JSON. */
@@ -126,8 +205,21 @@ export type JsonValue = boolean | null | number | string | ReadonlyArray<JsonVal
 };
 /** App options sent with a turn; the server parses them with its `options` schema. */
 export type SessionOptions = Readonly<Record<string, JsonValue>>;
+/**
+ * What a session is about: an inline source, or a page the server serves,
+ * by name, opened as a document.
+ */
+export type SessionDocument = {
+  source: string;
+} | {
+  name: string;
+  props?: PageProps;
+};
 /** What a session request carries. */
 export interface SessionBody {
+  /** The current UI. Absent when the turn writes a new one. */
+  document?: SessionDocument;
+  /** The conversation about it: the user's asks and the model's replies. */
   messages: ReadonlyArray<Message>;
   options?: SessionOptions;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jigs.design/protocol",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "The program format, the diagnostics, and the types and messages the server, the browser and the sandbox share. No runtime and no dependencies.",
   "license": "MIT",
   "repository": {