@jigs.design/protocol 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tom Bates
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,29 @@
-# Temporary Holding Version
+# @jigs.design/protocol
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+What the server, the browser and the sandbox agree on: the program format, the session and chat types, the diagnostics, and the messages between the page, the frame and the worker. It has no dependencies and runs nothing, so every other package can import it: the compiler for its diagnostic types, the host for the prop schemas, the browser packages for the wire.
+
+`@jigs.design/server`, `@jigs.design/client` and `@jigs.design/react` re-export the shared types, so most code imports them from one of those.
+
+## Exports
+
+| Export                                                                         | What it is                                                                                 |
+| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
+| `Program`, `PROGRAM_FORMAT`, `ComponentSchema`, `PropSchema`, `ProcedureEntry` | A compiled program and what it carries                                                     |
+| `SessionEvent`, `SessionBody`, `Message`, `ChatBlock`, `JsonValue`             | The session stream, the request and chat blocks                                            |
+| `Diagnostic`, `Severity`, `severities`, `Span`, `DiagnosticFix`                | The one diagnostic shape the compiler reports, the server sends and the eval results store |
+| `JigsErrorCode`, `jigsErrorCodes`, `JigsErrorData`, `Invalidation`             | Failures and the queries a mutation refreshed                                              |
+| `HostMessage`, `FrameMessage`, `WorkerMessage`, `Op`, `ROOT_ID` and the rest   | The frame protocol                                                                         |
+| `parseProgram`, `parseSessionEvent`, `parseErrorData`, `parseInvalidations`    | The checks the browser runs on JSON from the server, since it imports no schema library    |
+| `isAllowedImage`, `isAllowedLink`, `isImageHostEntry`, `normalizeImageHost`    | The image and link allowlists                                                              |
+
+## Source
+
+- `src/types.ts`: the shared types and `PROGRAM_FORMAT`.
+- `src/diagnostics.ts`: `Diagnostic` and the severities, with what each means.
+- `src/protocol.ts`: messages between the page, the frame and the worker.
+- `src/parse.ts`: checks for JSON arriving in the browser.
+- `src/urls.ts`: allowed images and links.
+
+## Docs
+
+[Diagnostics](../../apps/docs/docs/spec/diagnostics.mdx), [Frame protocol](../../apps/docs/docs/renderers/protocol.mdx) and [Packages](../../apps/docs/docs/packages/index.mdx).

package/dist/diagnostics.d.ts

@@ -0,0 +1,61 @@
+//#region src/diagnostics.d.ts
+/**
+ * The one diagnostic shape: the compiler reports it, the server adds its own
+ * checks in it and sends it, the browser parses it, and the eval results
+ * store it.
+ */
+/**
+ * How much a diagnostic matters, from most to least.
+ *
+ * - `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
+ *   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
+ *   says. No repair, since the model cannot fix it; a strict compile fails.
+ * - `info`: nothing to do. The compiler made a change itself (a fix it
+ *   applied, a tag it closed), or a stored spec names an older catalog.
+ */
+export declare const severities: readonly ["error", "warning", "info"];
+export type Severity = (typeof severities)[number];
+/**
+ * Where a diagnostic points. Every span has a line; one about something the
+ * compiler can place in the source also has its range, as offsets into the
+ * source the line counts (JavaScript string indices), and the column of its
+ * start.
+ */
+export interface Span {
+  /** 1-based, on `line`. */
+  column?: number;
+  /** Just past the range. */
+  end?: number;
+  line: number;
+  /** The range's first character. */
+  start?: number;
+}
+/**
+ * A rewrite that makes a diagnostic's problem go away: replace each edit's
+ * span with its text. The compiler attaches one only when there is a single
+ * way to write it, and applies it itself, so its diagnostic is `info`.
+ */
+export interface DiagnosticFix {
+  edits: Array<{
+    span: Span;
+    text: string;
+  }>;
+  /** What the fix does, such as "Replace with `q.status === "pending"`". */
+  title: string;
+}
+/**
+ * One problem or note about a source. `Code` narrows `code` where one
+ * producer's codes are known, as the compiler's are.
+ */
+export interface Diagnostic<Code extends string = string> {
+  code: Code;
+  fix?: DiagnosticFix;
+  message: string;
+  severity: Severity;
+  span: Span;
+}
+//#endregion

package/dist/diagnostics.js

@@ -0,0 +1,29 @@
+//#region src/diagnostics.ts
+/**
+* The one diagnostic shape: the compiler reports it, the server adds its own
+* checks in it and sends it, the browser parses it, and the eval results
+* store it.
+*/
+/**
+* How much a diagnostic matters, from most to least.
+*
+* - `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
+*   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
+*   says. No repair, since the model cannot fix it; a strict compile fails.
+* - `info`: nothing to do. The compiler made a change itself (a fix it
+*   applied, a tag it closed), or a stored spec names an older catalog.
+*/
+const severities = [
+	"error",
+	"warning",
+	"info"
+];
+function isSeverity(value) {
+	return severities.some((severity) => severity === value);
+}
+//#endregion
+export { isSeverity, severities };

package/dist/index.d.ts

@@ -0,0 +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 { 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 { 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 };

package/dist/index.js

@@ -0,0 +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 { isAllowedImage, isAllowedLink, isImageHostEntry, normalizeImageHost } from "./urls.js";
+export { PROGRAM_FORMAT, ROOT_ID, isAllowedImage, isAllowedLink, isImageHostEntry, jigsErrorCodes, normalizeImageHost, parseErrorData, parseInvalidations, parseProgram, parseSessionEvent, severities };

package/dist/parse.d.ts

@@ -0,0 +1,9 @@
+import { Invalidation, JigsErrorData, Program, 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;
+/** One session event from its JSON text, or null when it is not one. */
+export declare function parseSessionEvent(text: string): SessionEvent | null;
+//#endregion

package/dist/parse.js

@@ -0,0 +1,151 @@
+import { jigsErrorCodes } from "./types.js";
+import { isSeverity } from "./diagnostics.js";
+//#region src/parse.ts
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isString = (value) => typeof value === "string";
+const isStringList = (value) => Array.isArray(value) && value.every(isString);
+function recordOf(value, item) {
+	if (!isRecord(value)) return null;
+	const out = {};
+	for (const [key, entry] of Object.entries(value)) {
+		const parsed = item(entry);
+		if (parsed === null) return null;
+		out[key] = parsed;
+	}
+	return out;
+}
+const isErrorCode = (value) => jigsErrorCodes.some((code) => code === value);
+function parseErrorData(value) {
+	if (!isRecord(value) || !isErrorCode(value.code) || !isString(value.message)) return null;
+	return {
+		code: value.code,
+		message: value.message
+	};
+}
+function parseInvalidation(value) {
+	if (!isRecord(value) || !isString(value.name)) return null;
+	if (!("input" in value)) return { name: value.name };
+	return {
+		input: value.input,
+		name: value.name
+	};
+}
+/** The `invalidate` list of a mutation's reply. */
+function parseInvalidations(value) {
+	if (!Array.isArray(value)) return null;
+	const out = [];
+	for (const entry of value) {
+		const parsed = parseInvalidation(entry);
+		if (parsed === null) return null;
+		out.push(parsed);
+	}
+	return out;
+}
+function parsePropSchema(value) {
+	if (!isRecord(value)) return null;
+	switch (value.kind) {
+		case "boolean":
+		case "handler":
+		case "image":
+		case "link":
+		case "list":
+		case "string": return { kind: value.kind };
+		case "enum": return isStringList(value.values) ? {
+			kind: "enum",
+			values: value.values
+		} : null;
+		case "number": {
+			const schema = { kind: "number" };
+			if (typeof value.min === "number") schema.min = value.min;
+			if (typeof value.max === "number") schema.max = value.max;
+			return schema;
+		}
+		default: return null;
+	}
+}
+const isChildrenKind = (value) => value === "block" || value === "inline" || value === "none";
+function parseComponentSchema(value) {
+	if (!isRecord(value) || !isChildrenKind(value.children)) return null;
+	const props = recordOf(value.props, parsePropSchema);
+	return props === null ? null : {
+		children: value.children,
+		props
+	};
+}
+function parseProcedure(value) {
+	if (!isRecord(value) || value.kind !== "query" && value.kind !== "mutation" && value.kind !== "action" || !isStringList(value.invalidates)) return null;
+	return {
+		invalidates: value.invalidates,
+		kind: value.kind
+	};
+}
+function parseProgram(value) {
+	if (!isRecord(value) || value.format !== 1 || !isString(value.code) || !isStringList(value.imageHosts)) return null;
+	const components = recordOf(value.components, parseComponentSchema);
+	const procedures = recordOf(value.procedures, parseProcedure);
+	const prose = recordOf(value.prose, (entry) => isString(entry) ? entry : null);
+	if (components === null || procedures === null || prose === null) return null;
+	return {
+		code: value.code,
+		components,
+		format: 1,
+		imageHosts: value.imageHosts,
+		procedures,
+		prose
+	};
+}
+function parseDiagnostic(value) {
+	if (!isRecord(value) || !isString(value.code) || !isString(value.message) || !isSeverity(value.severity) || !isRecord(value.span) || typeof value.span.line !== "number") return null;
+	return {
+		code: value.code,
+		message: value.message,
+		severity: value.severity,
+		span: { line: value.span.line }
+	};
+}
+/** The diagnostics that parse; one the browser cannot read is skipped, not the event. */
+function parseDiagnostics(value) {
+	if (!Array.isArray(value)) return null;
+	return value.flatMap((entry) => {
+		const parsed = parseDiagnostic(entry);
+		return parsed === null ? [] : [parsed];
+	});
+}
+/** One session event from its JSON text, or null when it is not one. */
+function parseSessionEvent(text) {
+	let value;
+	try {
+		value = JSON.parse(text);
+	} catch {
+		return null;
+	}
+	if (!isRecord(value)) return null;
+	if (value.type === "error") {
+		const error = parseErrorData(value.error);
+		return error === null ? null : {
+			error,
+			type: "error"
+		};
+	}
+	const diagnostics = parseDiagnostics(value.diagnostics);
+	if (diagnostics === null || typeof value.revision !== "number") return null;
+	if (value.type === "program") {
+		const program = parseProgram(value.program);
+		return program === null ? null : {
+			diagnostics,
+			fresh: value.fresh === true,
+			program,
+			revision: value.revision,
+			type: "program"
+		};
+	}
+	if (value.type === "done" && isString(value.source)) return {
+		diagnostics,
+		revision: value.revision,
+		source: value.source,
+		type: "done"
+	};
+	return null;
+}
+//#endregion
+export { parseErrorData, parseInvalidations, parseProgram, parseSessionEvent };

package/dist/protocol.d.ts

@@ -0,0 +1,132 @@
+import { JigsErrorData, ProcedureEntry } from "./types.js";
+//#region src/protocol.d.ts
+/**
+ * Prop value on the wire. Functions never leave the worker; they travel as
+ * `{ fn }` ids. Lists of plain objects travel as `{ rows }`.
+ */
+export type WireValue = boolean | number | string | {
+  fn: string;
+} | {
+  rows: ReadonlyArray<Row>;
+};
+/** One row of a list prop: flat fields only. */
+export type Row = Readonly<Record<string, boolean | number | string | null>>;
+export type WireArg = boolean | number | string;
+/** The props of one node on the wire. */
+export type WireProps = Record<string, WireValue>;
+/** UI operations produced by the worker's reconciler. The root container has id 0. */
+export type Op = {
+  id: number;
+  op: "create";
+  props: WireProps;
+  type: string;
+} | {
+  id: number;
+  op: "createText";
+  text: string;
+} | {
+  id: number;
+  index: number;
+  op: "place";
+  parent: number;
+} | {
+  id: number;
+  op: "remove";
+} | {
+  id: number;
+  op: "set";
+  props: Record<string, WireValue | null>;
+} | {
+  id: number;
+  op: "text";
+  text: string;
+};
+export interface RuntimeError {
+  line: number | null;
+  message: string;
+}
+/** A query as the program sees it from `useQuery`. */
+export type QueryResult = {
+  data: null;
+  error: null;
+  status: "pending";
+} | {
+  data: unknown;
+  error: null;
+  status: "success";
+} | {
+  data: null;
+  error: JigsErrorData;
+  status: "error";
+};
+/** How a mutation settled. */
+export type MutationResult = {
+  data: unknown;
+  status: "success";
+} | {
+  error: JigsErrorData;
+  status: "error";
+};
+/** A query the program read during a render. `key` is stable for a name and input. */
+export interface QueryRead {
+  input: unknown;
+  key: string;
+  name: string;
+}
+/** A `mutate()` call made inside a handler. */
+export interface MutationCall {
+  id: number;
+  input: unknown;
+  name: string;
+}
+/** Page to worker. */
+export type HostMessage = {
+  args: ReadonlyArray<WireArg>;
+  fn: string;
+  seq: number;
+  type: "call";
+} | {
+  id: number;
+  result: MutationResult;
+  seq: number;
+  type: "mutation";
+} | {
+  key: string;
+  result: QueryResult;
+  seq: number;
+  type: "query";
+} | {
+  code: string;
+  /** Drop the state and mutation statuses of the program before. */
+  fresh: boolean;
+  procedures: Readonly<Record<string, ProcedureEntry>>;
+  prose: Readonly<Record<string, string>>;
+  seq: number;
+  type: "update";
+};
+/** Worker to page. */
+export type WorkerMessage = {
+  errors: Array<RuntimeError>;
+  mutations: Array<MutationCall>;
+  ops: Array<Op>;
+  queries: Array<QueryRead>;
+  seq: number;
+  type: "result";
+} | {
+  message: string;
+  seq: number;
+  type: "failed";
+};
+/** What the frame sends to the page. */
+export type FrameMessage = WorkerMessage | {
+  seq: number;
+  type: "quarantined";
+} | {
+  type: "ready";
+} |
+/** The frame's own security policy is not in force, so it will not run. */
+{
+  type: "unprotected";
+};
+export declare const ROOT_ID = 0;
+//#endregion

package/dist/protocol.js

@@ -0,0 +1,4 @@
+//#region src/protocol.ts
+const ROOT_ID = 0;
+//#endregion
+export { ROOT_ID };

package/dist/types.d.ts

@@ -0,0 +1,134 @@
+import { Diagnostic } from "./diagnostics.js";
+//#region src/types.d.ts
+/**
+ * Types the server and the browser share. The server builds these values;
+ * the browser receives them as JSON and checks them with `parse.ts`.
+ */
+/** The version of the program format. The runtime refuses any other. */
+export declare const PROGRAM_FORMAT = 1;
+export declare const jigsErrorCodes: readonly ["BAD_INPUT", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "RATE_LIMITED", "INTERNAL", "UNKNOWN_PROCEDURE", "UNAVAILABLE", "NETWORK", "DECLINED"];
+export type JigsErrorCode = (typeof jigsErrorCodes)[number];
+/** A failure as the spec and the browser see it. */
+export interface JigsErrorData {
+  code: JigsErrorCode;
+  message: string;
+}
+export interface NumberPropSchema {
+  kind: "number";
+  max?: number;
+  min?: number;
+}
+/** How the view checks one prop before a registry component sees it. */
+export type PropSchema = {
+  kind: "boolean";
+} | {
+  kind: "enum";
+  values: ReadonlyArray<string>;
+} | {
+  kind: "handler";
+} | {
+  kind: "image";
+} | {
+  kind: "link";
+} | {
+  kind: "list";
+} | NumberPropSchema | {
+  kind: "string";
+};
+export type ChildrenKind = "block" | "inline" | "none";
+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";
+export interface ProcedureEntry {
+  invalidates: ReadonlyArray<string>;
+  kind: ProcedureKind;
+}
+/**
+ * One query a mutation refreshed, as the server sends it with the mutation's
+ * data. Without `input`, every input of the query refetches. With it, only
+ * the queries whose input contains those values.
+ */
+export interface Invalidation {
+  input?: JsonValue;
+  name: 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.
+ */
+export interface Program {
+  code: string;
+  /** Prop schemas of the components the program draws. */
+  components: Readonly<Record<string, ComponentSchema>>;
+  format: typeof PROGRAM_FORMAT;
+  imageHosts: ReadonlyArray<string>;
+  /** Procedures the program calls, with their kind and `invalidates` list. */
+  procedures: Readonly<Record<string, ProcedureEntry>>;
+  /** Text nodes pulled out of the code, so a prose edit swaps a table. */
+  prose: Readonly<Record<string, string>>;
+}
+export interface Message {
+  content: string;
+  role: "assistant" | "user";
+}
+export type SessionEvent = {
+  diagnostics: ReadonlyArray<Diagnostic>;
+  /**
+   * True on the first program of a new UI: the model wrote a whole
+   * document rather than editing the last one, or a stored one was
+   * restored. The view starts it from fresh state.
+   */
+  fresh: boolean;
+  program: Program;
+  revision: number;
+  type: "program";
+} | {
+  diagnostics: ReadonlyArray<Diagnostic>;
+  revision: number;
+  source: string;
+  type: "done";
+} | {
+  error: JigsErrorData;
+  type: "error";
+};
+/**
+ * Where a chat block is: still arriving, being repaired after it closed with
+ * errors, or final.
+ */
+export type ChatBlockStatus = "done" | "repairing" | "streaming";
+/**
+ * A jig in a chat reply: one fenced `jigs` block, compiled on its own.
+ * The server sends it again whenever its program changes, under the same
+ * `key`.
+ */
+export interface ChatBlock {
+  /** Lines refer to `source`, which starts with its pragma line. */
+  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. */
+  key: string;
+  program: Program;
+  /** 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… */
+  version: number;
+}
+/** A value that travels as JSON. */
+export type JsonValue = boolean | null | number | string | ReadonlyArray<JsonValue> | {
+  readonly [key: string]: JsonValue;
+};
+/** App options sent with a turn; the server parses them with its `options` schema. */
+export type SessionOptions = Readonly<Record<string, JsonValue>>;
+/** What a session request carries. */
+export interface SessionBody {
+  messages: ReadonlyArray<Message>;
+  options?: SessionOptions;
+}
+//#endregion

package/dist/types.js

@@ -0,0 +1,22 @@
+//#region src/types.ts
+/**
+* Types the server and the browser share. The server builds these values;
+* the browser receives them as JSON and checks them with `parse.ts`.
+*/
+/** The version of the program format. The runtime refuses any other. */
+const PROGRAM_FORMAT = 1;
+const jigsErrorCodes = [
+	"BAD_INPUT",
+	"UNAUTHORIZED",
+	"FORBIDDEN",
+	"NOT_FOUND",
+	"CONFLICT",
+	"RATE_LIMITED",
+	"INTERNAL",
+	"UNKNOWN_PROCEDURE",
+	"UNAVAILABLE",
+	"NETWORK",
+	"DECLINED"
+];
+//#endregion
+export { PROGRAM_FORMAT, jigsErrorCodes };

package/dist/urls.d.ts

@@ -0,0 +1,14 @@
+//#region src/urls.d.ts
+/**
+ * A hostname, or `*.example.com` for its subdomains (not the apex),
+ * optionally followed by a path prefix that ends in `/`, such as
+ * `images.example.com/products/`.
+ */
+export declare function isImageHostEntry(entry: string): boolean;
+/** The entry with its host lowercased; the path keeps its case. */
+export declare function normalizeImageHost(entry: string): string;
+/** An `https` URL with no credentials or port, on one of `hosts`. */
+export declare function isAllowedImage(src: string, hosts: ReadonlyArray<string>): boolean;
+/** An absolute `http` or `https` URL. Anything else, such as `javascript:`, is refused. */
+export declare function isAllowedLink(href: string): boolean;
+//#endregion

package/dist/urls.js

@@ -0,0 +1,59 @@
+//#region src/urls.ts
+const HOST = /^(\*\.)?[a-z0-9-]+(\.[a-z0-9-]+)*$/;
+const PATH_PREFIX = /^\/(?:[A-Za-z0-9._~!$&'()*+,;=:@%/-]*\/)?$/;
+/** An image host entry split into its host and optional path prefix. */
+function splitEntry(entry) {
+	const slash = entry.indexOf("/");
+	return slash === -1 ? {
+		host: entry.toLowerCase(),
+		path: "/"
+	} : {
+		host: entry.slice(0, slash).toLowerCase(),
+		path: entry.slice(slash)
+	};
+}
+/**
+* A hostname, or `*.example.com` for its subdomains (not the apex),
+* optionally followed by a path prefix that ends in `/`, such as
+* `images.example.com/products/`.
+*/
+function isImageHostEntry(entry) {
+	const parts = splitEntry(entry);
+	return HOST.test(parts.host) && PATH_PREFIX.test(parts.path);
+}
+/** The entry with its host lowercased; the path keeps its case. */
+function normalizeImageHost(entry) {
+	const parts = splitEntry(entry);
+	return entry.includes("/") ? `${parts.host}${parts.path}` : parts.host;
+}
+/**
+* An encoded `/`, `\`, `.` or `%`: a server that decodes it after matching can
+* be walked out of the prefix with `..%2F`, or with `..%252F` if it decodes
+* twice, and the URL parser leaves it alone. So a prefix can't serve object
+* keys that hold an encoded `/`, such as Firebase Storage's `o/a%2Fb.jpg`.
+*/
+const ENCODED_SEPARATOR = /%(?:2f|5c|2e|25)/i;
+function matchesHost(url, entry) {
+	if (!isImageHostEntry(entry)) return false;
+	const parts = splitEntry(entry);
+	return (parts.host.startsWith("*.") ? url.hostname.endsWith(parts.host.slice(1)) : url.hostname === parts.host) && url.pathname.startsWith(parts.path) && (parts.path === "/" || !ENCODED_SEPARATOR.test(url.pathname));
+}
+function parseUrl(text) {
+	try {
+		return new URL(text);
+	} catch {
+		return null;
+	}
+}
+/** An `https` URL with no credentials or port, on one of `hosts`. */
+function isAllowedImage(src, hosts) {
+	const url = parseUrl(src);
+	return url !== null && url.protocol === "https:" && url.username === "" && url.password === "" && url.port === "" && hosts.some((entry) => matchesHost(url, entry));
+}
+/** An absolute `http` or `https` URL. Anything else, such as `javascript:`, is refused. */
+function isAllowedLink(href) {
+	const url = parseUrl(href);
+	return url !== null && (url.protocol === "https:" || url.protocol === "http:") && url.username === "" && url.password === "";
+}
+//#endregion
+export { isAllowedImage, isAllowedLink, isImageHostEntry, normalizeImageHost };

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@jigs.design/protocol",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "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": {
+    "type": "git",
+    "url": "git+https://github.com/yoamomonstruos/jigs.git",
+    "directory": "packages/protocol"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
 }