@jigs.design/host 0.0.0-stage → 0.1.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,52 @@
-# Temporary Holding Version
+# @jigs.design/host
 
-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.
+Defines a host: the contract between your product and the model. A host lists the components a spec may draw, the recipes built from them, the procedures it may call, the image hosts it may load from, and the design guidance and situations the model designs by. It holds schemas, not the code that runs a procedure.
+
+Import it from server code and config. No browser package imports it; the browser imports `ActionEvent` as a type at most.
+
+```ts
+import { catalog } from "@jigs.design/catalog";
+import { defineHost, mutation, query } from "@jigs.design/host";
+import { z } from "zod";
+
+export const host = defineHost({
+	components: catalog,
+	procedures: {
+		orders: query({
+			input: z.object({ status: z.enum(["open", "archived"]) }),
+			output: z.array(z.object({ id: z.string(), total: z.number() })),
+			description: "Lists the caller's orders with the given status.",
+		}),
+		archiveOrder: mutation({
+			input: z.object({ id: z.string() }),
+			invalidates: ["orders"],
+			description: "Archives one of the caller's orders.",
+		}),
+	},
+});
+```
+
+## Exports
+
+| Export                                                                                                | What it is                                                                                          |
+| ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `defineHost`                                                                                          | Builds a host from `components`, `procedures`, `recipes`, `imageHosts`, `guidance` and `situations` |
+| `query`, `mutation`, `action`                                                                         | The three kinds of procedure. An action is handled by the embedding page                            |
+| `recipe`                                                                                              | A compound component written in Pickle from catalog components                                      |
+| `situation`                                                                                           | Design guidance for when the reader has a given job, with a checked example                         |
+| `defineCatalog`, `defineComponent`                                                                    | Build your own catalog                                                                              |
+| `string`, `number`, `boolean`, `oneOf`, `handler`, `image`, `link`, `list`, `block`, `inline`, `none` | Prop and children builders for components                                                           |
+| `contentSecurityPolicy`                                                                               | The page's `frame-src` and `img-src` directives, merged into yours                                  |
+| `CatalogProps`, `PropsOf`, `ActionEvent`                                                              | Types for a registry and for a page's `onAction`                                                    |
+
+## Source
+
+- `src/host.ts`: `defineHost`, `contentSecurityPolicy` and `ActionEvent`.
+- `src/catalog.ts`: catalogs, components and the prop builders.
+- `src/procedures.ts`: `query`, `mutation`, `action` and invalidation scopes.
+- `src/recipes.ts`: `recipe`, compiled against the host's catalog.
+- `src/guidance.ts`: `situation` and the design guidance types; the host's replace the catalog's.
+
+## Docs
+
+[Host](../../apps/docs/docs/host/index.mdx), [Catalog](../../apps/docs/docs/host/catalog.mdx), [Recipes](../../apps/docs/docs/host/recipes.mdx), [Design guidance](../../apps/docs/docs/host/guidance.mdx), [Queries](../../apps/docs/docs/host/queries.mdx), [Mutations](../../apps/docs/docs/host/mutations.mdx), [Actions](../../apps/docs/docs/host/actions.mdx).

package/dist/catalog.d.ts

@@ -0,0 +1,143 @@
+import { DesignGuidance, GuidanceInput, SituationDefinition } from "./guidance.js";
+import { ChildrenKind, ComponentSchema, PropSchema, Row } from "@jigs.design/runtime";
+//#region src/catalog.d.ts
+/**
+ * One prop of a catalog component. `schema` is what the browser checks;
+ * `value` exists only in types, so `PropsOf` can type a registry component.
+ */
+export interface PropDefinition<TValue> {
+  /** For a handler: the props the component calls it with, in order, which the prompt prints as its signature. */
+  args?: ReadonlyArray<PropDefinition<unknown>>;
+  /** Pairs a value prop with its change handler, e.g. `value` with `onChange`. */
+  controlled?: string;
+  default?: boolean | number | string;
+  description?: string;
+  schema: PropSchema;
+  /**
+   * What the prompt calls an enum's values when it declares them once
+   * under Types, e.g. `ChartColor`. Without it, the prompt names them.
+   */
+  typeName?: string;
+  readonly value?: TValue;
+}
+interface PropOptions<TDefault> {
+  default?: TDefault;
+  description?: string;
+}
+export declare function string(options?: PropOptions<string> & {
+  controlled?: string;
+}): PropDefinition<string>;
+export declare function number(options?: PropOptions<number> & {
+  controlled?: string;
+  max?: number;
+  min?: number;
+}): PropDefinition<number>;
+export declare function boolean(options?: PropOptions<boolean> & {
+  controlled?: string;
+}): PropDefinition<boolean>;
+export declare function oneOf<const TValues extends ReadonlyArray<string>>(values: TValues, options?: PropOptions<TValues[number]> & {
+  controlled?: string;
+  typeName?: string;
+}): PropDefinition<TValues[number]>;
+/** An `https` URL on one of the host's image hosts. */
+export declare function image(options?: PropOptions<string>): PropDefinition<string>;
+/** An `http` or `https` URL that loads nothing until the user clicks it. */
+export declare function link(options?: PropOptions<string>): PropDefinition<string>;
+/** A list of flat objects, such as chart rows or select options. */
+export declare function list(options?: PropOptions<never>): PropDefinition<ReadonlyArray<Row>>;
+type ValueOfDefinition<D> = D extends PropDefinition<infer V> ? V : never;
+type HandlerArgs<TArgs extends ReadonlyArray<PropDefinition<unknown>>> = { [K in keyof TArgs]: ValueOfDefinition<TArgs[K]>; };
+/**
+ * A function prop. `args` are what the component passes back to the
+ * program: they type the registry component's prop, and the prompt prints
+ * them as the handler's signature, `(value: number) => void`.
+ */
+export declare function handler<const TArgs extends ReadonlyArray<PropDefinition<unknown>> = []>(args?: TArgs, options?: PropOptions<never>): PropDefinition<(...values: HandlerArgs<TArgs>) => void>;
+export declare const none: () => ChildrenKind;
+export declare const inline: () => ChildrenKind;
+export declare const block: () => ChildrenKind;
+export type PropDefinitions = Readonly<Record<string, PropDefinition<unknown>>>;
+/**
+ * What a component is to the server's design checks. Only the catalog knows
+ * which of its components is a card or a button, and which props make a
+ * button the primary one, so it says so here.
+ */
+export type ComponentDesign = {
+  /**
+   * The prop values that make it the primary action, with the props'
+   * defaults filled in, e.g. `{ variant: "solid", color: "primary" }`.
+   * A view has at most one.
+   */
+  primary?: Readonly<Record<string, boolean | number | string>>;
+  /**
+   * A control the reader acts with. Each counts toward a chat block's
+   * limit of two; one with no children needs its `ariaLabel`.
+   */
+  role: "action";
+} | {
+  /**
+   * `chart` draws data and needs its `ariaLabel`; `field` takes input
+   * and needs a `label` or an `ariaLabel`; `surface` is a card, and
+   * one never sits inside another.
+   */
+  role: "chart" | "field" | "surface";
+};
+export interface ComponentDefinition<TName extends string = string, TProps extends PropDefinitions = PropDefinitions> {
+  /** Plausible wrong uses, and the concrete thing to reach for instead. */
+  avoid: ReadonlyArray<{
+    useInstead: string;
+    when: string;
+  }>;
+  children: ChildrenKind;
+  description: string;
+  /** What the design checks take it for; a component without one is none of those. */
+  design?: ComponentDesign;
+  name: TName;
+  props: TProps;
+}
+export declare function defineComponent<const TName extends string, const TProps extends PropDefinitions>(name: TName, definition: {
+  avoid?: ReadonlyArray<{
+    useInstead: string;
+    when: string;
+  }>;
+  children: ChildrenKind;
+  description: string;
+  design?: ComponentDesign;
+  props: TProps;
+}): ComponentDefinition<TName, TProps>;
+export interface Catalog<TComponents extends ReadonlyArray<ComponentDefinition> = ReadonlyArray<ComponentDefinition>> {
+  components: TComponents;
+  /**
+   * Design guidance for every UI drawn with this catalog. Not part of
+   * `version`: it changes no compiled program.
+   */
+  guidance: DesignGuidance;
+  /** Guidance for what the reader will do with a UI; the model picks by `when`. */
+  situations: ReadonlyArray<SituationDefinition>;
+  /** Raise it when a component or a prop changes. */
+  version: number;
+}
+/**
+ * A catalog. Throws on two components with one name, a version that is not
+ * a non-negative integer, or a situation name that is not kebab-case or is
+ * listed twice.
+ */
+export declare function defineCatalog<const TComponents extends ReadonlyArray<ComponentDefinition>>(definition: {
+  components: TComponents;
+  /** A string for every placement, or `{ shared, chat, document }`. */
+  guidance?: GuidanceInput;
+  situations?: ReadonlyArray<SituationDefinition>;
+  version: number;
+}): Catalog<TComponents>;
+/** The props a registry component receives for a catalog component. */
+export type PropsOf<C extends ComponentDefinition> = { [K in keyof C["props"]]?: ValueOfDefinition<C["props"][K]>; };
+/** The props of every component in a catalog, by tag name. Type a registry with it. */
+export type CatalogProps<TCatalog extends Catalog> = { [K in TCatalog["components"][number]["name"]]: PropsOf<ComponentNamed<TCatalog, K>>; };
+/** A catalog component by name. */
+export type ComponentNamed<TCatalog extends Catalog, TName extends string> = Extract<TCatalog["components"][number], {
+  name: TName;
+}>;
+/** What the browser checks for a component. */
+export declare function componentSchema(component: ComponentDefinition): ComponentSchema;
+//#endregion
+export {};

package/dist/catalog.js

@@ -0,0 +1,99 @@
+import { checkSituations, normalizeGuidance } from "./guidance.js";
+//#region src/catalog.ts
+function prop(schema, options) {
+	const definition = { schema };
+	if (options.controlled !== void 0) definition.controlled = options.controlled;
+	if (options.default !== void 0) definition.default = options.default;
+	if (options.description !== void 0) definition.description = options.description;
+	if (options.typeName !== void 0) definition.typeName = options.typeName;
+	return definition;
+}
+function string(options = {}) {
+	return prop({ kind: "string" }, options);
+}
+function number(options = {}) {
+	const schema = { kind: "number" };
+	if (options.min !== void 0) schema.min = options.min;
+	if (options.max !== void 0) schema.max = options.max;
+	return prop(schema, options);
+}
+function boolean(options = {}) {
+	return prop({ kind: "boolean" }, options);
+}
+function oneOf(values, options = {}) {
+	return prop({
+		kind: "enum",
+		values
+	}, options);
+}
+/** An `https` URL on one of the host's image hosts. */
+function image(options = {}) {
+	return prop({ kind: "image" }, options);
+}
+/** An `http` or `https` URL that loads nothing until the user clicks it. */
+function link(options = {}) {
+	return prop({ kind: "link" }, options);
+}
+/** A list of flat objects, such as chart rows or select options. */
+function list(options = {}) {
+	return prop({ kind: "list" }, options);
+}
+/**
+* A function prop. `args` are what the component passes back to the
+* program: they type the registry component's prop, and the prompt prints
+* them as the handler's signature, `(value: number) => void`.
+*/
+function handler(args, options = {}) {
+	const definition = prop({ kind: "handler" }, options);
+	return args === void 0 || args.length === 0 ? definition : {
+		...definition,
+		args
+	};
+}
+const none = () => "none";
+const inline = () => "inline";
+const block = () => "block";
+function defineComponent(name, definition) {
+	if (!/^[a-z][A-Za-z0-9]*$/.test(name)) throw new Error(`Component name "${name}" must start with a lowercase letter and use letters and digits only`);
+	const component = {
+		avoid: definition.avoid ?? [],
+		children: definition.children,
+		description: definition.description,
+		name,
+		props: definition.props
+	};
+	if (definition.design !== void 0) component.design = definition.design;
+	return component;
+}
+/**
+* A catalog. Throws on two components with one name, a version that is not
+* a non-negative integer, or a situation name that is not kebab-case or is
+* listed twice.
+*/
+function defineCatalog(definition) {
+	if (!Number.isInteger(definition.version) || definition.version < 0) throw new Error("Catalog version must be a non-negative integer");
+	const seen = /* @__PURE__ */ new Set();
+	for (const component of definition.components) {
+		if (seen.has(component.name)) throw new Error(`Catalog lists <${component.name}> twice`);
+		seen.add(component.name);
+	}
+	const situations = definition.situations ?? [];
+	checkSituations(situations);
+	return {
+		components: definition.components,
+		guidance: normalizeGuidance(definition.guidance),
+		situations,
+		version: definition.version
+	};
+}
+/** What the browser checks for a component. */
+function componentSchema(component) {
+	const props = {};
+	for (const [name, definition] of Object.entries(component.props)) props[name] = definition.schema;
+	return {
+		children: component.children,
+		props
+	};
+}
+//#endregion
+export { block, boolean, componentSchema, defineCatalog, defineComponent, handler, image, inline, link, list, none, number, oneOf, string };

package/dist/guidance.d.ts

@@ -0,0 +1,44 @@
+//#region src/guidance.d.ts
+/**
+ * Design guidance: how to design a good UI with a catalog, not only a valid
+ * one. Foundations apply to every UI; a situation applies when its `when`
+ * matches what the reader will do with the UI. See
+ * `docs/design-guidance/rfc.md`.
+ */
+/** Guidance for every placement (`shared`), and for one prompt mode each. */
+export interface DesignGuidance {
+  /** A UI in a chat reply. */
+  chat?: string;
+  /** A UI that is the whole reply. */
+  document?: string;
+  /** Every UI, in either mode. */
+  shared?: string;
+}
+/** What `guidance` takes: a string, for every placement, or the three parts. */
+export type GuidanceInput = DesignGuidance | string;
+/**
+ * Conditional design guidance, keyed on what the reader does with the UI.
+ * The prompt lists every situation; the model follows the one whose `when`
+ * matches.
+ */
+export interface SituationDefinition {
+  /** Pickle the server compiles against the host at startup. */
+  example?: string;
+  /** How to design for this situation, stating where it differs from the foundations. */
+  guidance: string;
+  /** Kebab-case label for apps, logs and evals. The model selects on `when`. */
+  name: string;
+  /** What the reader will do with the UI, as a sentence. */
+  when: string;
+}
+/**
+ * A situation. Throws when `name` is not kebab-case, or `when` or `guidance`
+ * is empty. The server compiles `example` at startup.
+ */
+export declare function situation(definition: {
+  example?: string;
+  guidance: string;
+  name: string;
+  when: string;
+}): SituationDefinition;
+//#endregion

package/dist/guidance.js

@@ -0,0 +1,52 @@
+//#region src/guidance.ts
+const SITUATION_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** Throws unless `name` is kebab-case: lower-case letters and digits, single hyphens. */
+function checkSituationName(name) {
+	if (!SITUATION_NAME.test(name)) throw new Error(`Situation name "${name}" must be kebab-case: lower-case letters and digits, joined by single hyphens`);
+}
+function isSharedOnly(input) {
+	return typeof input === "string";
+}
+/** Guidance with each part trimmed and empty parts left out. */
+function normalizeGuidance(input) {
+	const given = input ?? {};
+	const parts = isSharedOnly(given) ? { shared: given } : given;
+	const out = {};
+	const chat = parts.chat?.trim() ?? "";
+	const document = parts.document?.trim() ?? "";
+	const shared = parts.shared?.trim() ?? "";
+	if (chat !== "") out.chat = chat;
+	if (document !== "") out.document = document;
+	if (shared !== "") out.shared = shared;
+	return out;
+}
+/**
+* A situation. Throws when `name` is not kebab-case, or `when` or `guidance`
+* is empty. The server compiles `example` at startup.
+*/
+function situation(definition) {
+	checkSituationName(definition.name);
+	const when = definition.when.trim();
+	const guidance = definition.guidance.trim();
+	if (when === "") throw new Error(`Situation "${definition.name}" needs a \`when\``);
+	if (guidance === "") throw new Error(`Situation "${definition.name}" needs \`guidance\``);
+	const built = {
+		guidance,
+		name: definition.name,
+		when
+	};
+	const example = definition.example?.trim() ?? "";
+	if (example !== "") built.example = example;
+	return built;
+}
+/** Throws on a situation name that is not kebab-case or is listed twice. */
+function checkSituations(situations) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const entry of situations) {
+		checkSituationName(entry.name);
+		if (seen.has(entry.name)) throw new Error(`Situation "${entry.name}" is listed twice`);
+		seen.add(entry.name);
+	}
+}
+//#endregion
+export { checkSituations, normalizeGuidance, situation };

package/dist/host.d.ts

@@ -0,0 +1,88 @@
+import { DesignGuidance, GuidanceInput, SituationDefinition } from "./guidance.js";
+import { Catalog } from "./catalog.js";
+import { ActionDefinition, MutationDefinition, Parsed, Procedures, QueryDefinition } from "./procedures.js";
+import { RecipeDefinition } from "./recipes.js";
+import { z } from "zod";
+//#region src/host.d.ts
+export interface Host<TProcedures extends Procedures = Procedures, TCatalog extends Catalog = Catalog> {
+  components: TCatalog;
+  /** The host's design guidance, or the catalog's when the host sets none. */
+  guidance: DesignGuidance;
+  imageHosts: ReadonlyArray<string>;
+  procedures: TProcedures;
+  /** Compound components written in Pickle; the server checks them at startup. */
+  recipes: ReadonlyArray<RecipeDefinition>;
+  /** The host's situations, or the catalog's when the host sets none. */
+  situations: ReadonlyArray<SituationDefinition>;
+}
+/**
+ * What a page's `onAction` receives for a host: one member per action, with
+ * the input as its schema parsed it. Import it as a type in the browser:
+ * `onAction={(action: ActionEvent<typeof host>) => …}`.
+ */
+export type ActionEvent<THost extends {
+  procedures: Procedures;
+}> = { [K in keyof THost["procedures"] & string]: THost["procedures"][K] extends {
+  input: infer I extends z.ZodType | undefined;
+  kind: ActionDefinition["kind"];
+} ? {
+  input: Parsed<I>;
+  name: K;
+} : never; }[keyof THost["procedures"] & string];
+/**
+ * What a scope may return for query `Q`: an input as the view would send it
+ * (the view's queries whose input contains it refresh), an array of those,
+ * or `true`.
+ */
+type ScopeResult<Q extends QueryDefinition> = true | QueryInput<Q> | ReadonlyArray<QueryInput<Q>>;
+type QueryInput<Q extends QueryDefinition> = Q["input"] extends z.ZodType ? z.input<Q["input"]> : undefined;
+type CheckedScopes<TProcedures extends Procedures, I extends z.ZodType | undefined, O extends z.ZodType | undefined, S> = { readonly [Q in keyof S]: Q extends keyof TProcedures ? TProcedures[Q] extends QueryDefinition ? true | ((input: Parsed<I>, output: Parsed<O>) => ScopeResult<TProcedures[Q]>) : never : never; };
+/** Each mutation's scopes, with returns checked against their query's input. */
+type CheckedProcedures<TProcedures extends Procedures> = { readonly [K in keyof TProcedures]: TProcedures[K] extends MutationDefinition<infer I, infer O, infer S> ? {
+  scopes: CheckedScopes<TProcedures, I, O, S>;
+} : TProcedures[K]; };
+/**
+ * The product's boundary with the spec. Throws at startup when a schema has
+ * no JSON form, `invalidates` names something that is not a query, a
+ * procedure name is not an identifier, an image host is malformed, or a
+ * situation name is not kebab-case or is listed twice.
+ *
+ * `guidance` and `situations` replace the catalog's when set; to extend the
+ * catalog's, spread them in.
+ */
+export declare function defineHost<const TProcedures extends Procedures, const TCatalog extends Catalog>(definition: {
+  components: TCatalog;
+  /** A string for every placement, or `{ shared, chat, document }`. */
+  guidance?: GuidanceInput;
+  imageHosts?: ReadonlyArray<string>;
+  procedures: TProcedures & CheckedProcedures<TProcedures>;
+  recipes?: ReadonlyArray<RecipeDefinition>;
+  situations?: ReadonlyArray<SituationDefinition>;
+}): Host<TProcedures, TCatalog>;
+/** A policy as directive names and their sources, e.g. `{ "img-src": ["'self'"] }`. */
+export type PolicyDirectives = Readonly<Record<string, ReadonlyArray<string>>>;
+/** The embedding page's policy, and where it must not be sent. */
+export interface PagePolicy {
+  /**
+   * False for the endpoint, true for every other URL. The endpoint serves the
+   * sandbox frame with its own policy; sending the page's there replaces it,
+   * and the frame then refuses to run.
+   */
+  appliesTo: (url: string | URL) => boolean;
+  /** The page's directives with the ones Pickle needs merged in. */
+  directives: PolicyDirectives;
+  /** `directives` as one `Content-Security-Policy` header value. */
+  header: string;
+}
+/**
+ * The embedding page's policy: the page's own `directives` plus what Pickle
+ * needs, `frame-src` for the sandbox frame and `img-src` for the host's image
+ * hosts. Send `header` on every response `appliesTo` accepts; the endpoint's
+ * frame carries its own policy, and a page policy sent there replaces it.
+ */
+export declare function contentSecurityPolicy(host: Host, options: {
+  directives?: PolicyDirectives;
+  endpoint: string;
+}): PagePolicy;
+//#endregion
+export {};

package/dist/host.js

@@ -0,0 +1,104 @@
+import { checkSituations, normalizeGuidance } from "./guidance.js";
+import { isCallPolicy } from "./procedures.js";
+import { isImageHostEntry, normalizeImageHost } from "@jigs.design/runtime";
+import { z } from "zod";
+//#region src/host.ts
+const PROCEDURE_NAME = /^[A-Za-z][A-Za-z0-9_]*$/;
+function checkJsonSchema(label, schema) {
+	try {
+		z.toJSONSchema(schema);
+	} catch (error) {
+		throw new Error(`${label} has no JSON Schema form, so it cannot travel as JSON. Use plain values, such as an ISO string for a date.`, { cause: error });
+	}
+}
+/**
+* The product's boundary with the spec. Throws at startup when a schema has
+* no JSON form, `invalidates` names something that is not a query, a
+* procedure name is not an identifier, an image host is malformed, or a
+* situation name is not kebab-case or is listed twice.
+*
+* `guidance` and `situations` replace the catalog's when set; to extend the
+* catalog's, spread them in.
+*/
+function defineHost(definition) {
+	const { procedures } = definition;
+	const recipes = definition.recipes ?? [];
+	const situations = definition.situations ?? definition.components.situations;
+	checkSituations(situations);
+	const components = new Set(definition.components.components.map((component) => component.name));
+	const recipeNames = /* @__PURE__ */ new Set();
+	for (const entry of recipes) {
+		if (components.has(entry.name)) throw new Error(`Recipe "${entry.name}" has the name of a catalog component`);
+		if (recipeNames.has(entry.name)) throw new Error(`Recipe "${entry.name}" is listed twice`);
+		recipeNames.add(entry.name);
+	}
+	for (const [name, procedure] of Object.entries(procedures)) {
+		if (!PROCEDURE_NAME.test(name)) throw new Error(`Procedure name "${name}" must be an identifier: letters, digits and underscores, starting with a letter`);
+		if (procedure.input !== void 0) checkJsonSchema(`The input of "${name}"`, procedure.input);
+		if (procedure.output !== void 0) checkJsonSchema(`The output of "${name}"`, procedure.output);
+		if (procedure.kind !== "action" && procedure.projection !== void 0) checkJsonSchema(`The projection of "${name}"`, procedure.projection.schema);
+		if (procedure.kind === "mutation") {
+			if (!isCallPolicy(procedure.policy)) throw new Error(`"${name}" has policy ${JSON.stringify(procedure.policy)}: write "allow", "confirm" or "deny"`);
+			if (procedure.policy === "confirm" && procedure.confirm === void 0) throw new Error(`"${name}" asks for confirmation but has no confirm message: give it confirm: (input) => text`);
+			for (const target of procedure.invalidates) if ((Object.hasOwn(procedures, target) ? procedures[target] : void 0)?.kind !== "query") throw new Error(`"${name}" invalidates "${target}", which is not a query on this host`);
+		}
+	}
+	const imageHosts = (definition.imageHosts ?? []).map((entry) => {
+		if (!isImageHostEntry(entry)) throw new Error(`Invalid image host "${entry}"; use a hostname such as "cdn.example.com" or "*.example.com", optionally with a path prefix ending in "/"`);
+		return normalizeImageHost(entry);
+	});
+	return {
+		components: definition.components,
+		guidance: definition.guidance === void 0 ? definition.components.guidance : normalizeGuidance(definition.guidance),
+		imageHosts,
+		procedures,
+		recipes,
+		situations
+	};
+}
+/** The source a CSP needs for `endpoint`: `'self'` for a path, the origin for a URL. */
+function endpointSource(endpoint) {
+	if (endpoint.startsWith("/")) return "'self'";
+	return new URL(endpoint).origin;
+}
+/**
+* Where a directive Pickle adds takes its sources from when the page has not
+* set it: once the directive exists, the browser stops falling back.
+*/
+const FALLBACKS = /* @__PURE__ */ new Map([["frame-src", ["child-src", "default-src"]], ["img-src", ["default-src"]]]);
+/** Adds `extra` to `directives`, keeping each source once and dropping a `'none'` that now has company. */
+function mergeDirectives(directives, extra) {
+	const merged = new Map(Object.entries(directives).map(([name, sources]) => [name, [...sources]]));
+	for (const [name, sources] of Object.entries(extra)) {
+		const fallback = (FALLBACKS.get(name) ?? []).map((other) => directives[other]).find((found) => found !== void 0);
+		const list = merged.get(name) ?? [...fallback ?? []];
+		for (const source of sources) if (!list.includes(source)) list.push(source);
+		merged.set(name, list.length > 1 ? list.filter((source) => source !== "'none'") : list);
+	}
+	return Object.fromEntries(merged);
+}
+/**
+* The embedding page's policy: the page's own `directives` plus what Pickle
+* needs, `frame-src` for the sandbox frame and `img-src` for the host's image
+* hosts. Send `header` on every response `appliesTo` accepts; the endpoint's
+* frame carries its own policy, and a page policy sent there replaces it.
+*/
+function contentSecurityPolicy(host, options) {
+	const directives = mergeDirectives(options.directives ?? {}, {
+		"frame-src": [endpointSource(options.endpoint)],
+		"img-src": ["'self'", ...host.imageHosts.map((entry) => `https://${entry}`)]
+	});
+	const absolute = !options.endpoint.startsWith("/");
+	const endpoint = new URL(options.endpoint, "https://page.invalid");
+	const path = endpoint.pathname.replace(/\/$/, "");
+	return {
+		appliesTo: (url) => {
+			const target = new URL(url, endpoint);
+			return !((!absolute || target.origin === endpoint.origin) && (target.pathname === path || target.pathname.startsWith(`${path}/`)));
+		},
+		directives,
+		header: Object.entries(directives).map(([name, sources]) => [name, ...sources].join(" ")).join("; ")
+	};
+}
+//#endregion
+export { contentSecurityPolicy, defineHost };

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { DesignGuidance, GuidanceInput, SituationDefinition, situation } from "./guidance.js";
+import { Catalog, CatalogProps, ComponentDefinition, ComponentDesign, ComponentNamed, PropDefinition, PropDefinitions, PropsOf, block, boolean, componentSchema, defineCatalog, defineComponent, handler, image, inline, link, list, none, number, oneOf, string } from "./catalog.js";
+import { ActionDefinition, CallPolicy, InputOf, InvalidationScope, InvalidationScopes, MutationDefinition, OutputOf, ProcedureDefinition, Procedures, Projection, QueryDefinition, action, dataSchema, isCallPolicy, mutation, query } from "./procedures.js";
+import { RecipeDefinition, recipe } from "./recipes.js";
+import { ActionEvent, Host, PagePolicy, PolicyDirectives, contentSecurityPolicy, defineHost } from "./host.js";
+export { type ActionDefinition, type ActionEvent, type CallPolicy, type Catalog, type CatalogProps, type ComponentDefinition, type ComponentDesign, type ComponentNamed, type DesignGuidance, type GuidanceInput, type Host, type InputOf, type InvalidationScope, type InvalidationScopes, type MutationDefinition, type OutputOf, type PagePolicy, type PolicyDirectives, type ProcedureDefinition, type Procedures, type Projection, type PropDefinition, type PropDefinitions, type PropsOf, type QueryDefinition, type RecipeDefinition, type SituationDefinition, action, block, boolean, componentSchema, contentSecurityPolicy, dataSchema, defineCatalog, defineComponent, defineHost, handler, image, inline, isCallPolicy, link, list, mutation, none, number, oneOf, query, recipe, situation, string };

package/dist/index.js

@@ -0,0 +1,6 @@
+import { situation } from "./guidance.js";
+import { block, boolean, componentSchema, defineCatalog, defineComponent, handler, image, inline, link, list, none, number, oneOf, string } from "./catalog.js";
+import { action, dataSchema, isCallPolicy, mutation, query } from "./procedures.js";
+import { contentSecurityPolicy, defineHost } from "./host.js";
+import { recipe } from "./recipes.js";
+export { action, block, boolean, componentSchema, contentSecurityPolicy, dataSchema, defineCatalog, defineComponent, defineHost, handler, image, inline, isCallPolicy, link, list, mutation, none, number, oneOf, query, recipe, situation, string };

package/dist/procedures.d.ts

@@ -0,0 +1,148 @@
+import { JsonValue } from "@jigs.design/runtime";
+import { z } from "zod";
+//#region src/procedures.d.ts
+/**
+ * The part of a procedure's output its views read, and how to make it. The
+ * server parses the whole output, as the contract with `run`, then calls
+ * `project` on it and parses the result with `schema`; that is what the
+ * view receives. The prompt shows `schema` in the output's place, so a
+ * generated API's large records reach the model as the fields a UI shows.
+ */
+export interface Projection<TOutput = unknown> {
+  project(output: TOutput): Unparsed;
+  schema: z.ZodType;
+}
+/** What a projection's `project` returns, before its `schema` parses it. */
+type Unparsed = z.input<z.ZodType>;
+/** A procedure the spec reads with `useQuery`. */
+export interface QueryDefinition<TInput extends z.ZodType | undefined = z.ZodType | undefined, TOutput extends z.ZodType = z.ZodType> {
+  description: string;
+  input: TInput;
+  kind: "query";
+  output: TOutput;
+  /** What views read instead of the whole output; see `Projection`. */
+  projection?: Projection<z.output<TOutput>>;
+}
+/**
+ * Which inputs of one query a mutation refreshes. `true` refreshes every
+ * input. A function receives the mutation's parsed input and output, and
+ * returns the query input to refresh, an array of them, or `true`, all of
+ * which travel as JSON. `defineHost` narrows the return to the query's input.
+ */
+export type InvalidationScope<TInput = never, TOutput = never> = true | ((input: TInput, output: TOutput) => JsonValue);
+/** Per query name, which of its inputs a mutation refreshes. */
+export type InvalidationScopes<TInput = never, TOutput = never> = Readonly<Record<string, InvalidationScope<TInput, TOutput>>>;
+/**
+ * What the server does with a call to a mutation: run it (`"allow"`), ask
+ * the user through the page first (`"confirm"`), or refuse it with
+ * `FORBIDDEN` (`"deny"`). A denied mutation stays in the prompt; the refusal
+ * happens at call time, never by hiding the procedure.
+ */
+export type CallPolicy = "allow" | "confirm" | "deny";
+/**
+ * Whether `policy` is one of the three. A plain-JavaScript host, or a server
+ * override that returns a Promise, can hand over anything; the server denies
+ * a call whose policy is not one of these rather than running it.
+ */
+export declare function isCallPolicy(policy: CallPolicy): boolean;
+/** A procedure the spec calls with `useMutation`. */
+export interface MutationDefinition<TInput extends z.ZodType | undefined = z.ZodType | undefined, TOutput extends z.ZodType | undefined = z.ZodType | undefined, TScopes extends InvalidationScopes = InvalidationScopes> {
+  /**
+   * The text the page shows when it asks the user to confirm a call, from
+   * the parsed input. The host writes it, never the model.
+   */
+  confirm?(input: Parsed<TInput>): string;
+  description: string;
+  input: TInput;
+  /** Every query a success refreshes. */
+  invalidates: ReadonlyArray<string>;
+  kind: "mutation";
+  output: TOutput;
+  /** Whether a call runs; the server's `policy` option may override it. */
+  policy: CallPolicy;
+  /** What views read instead of the whole output; see `Projection`. */
+  projection?: Projection<Parsed<TOutput>>;
+  /** For each name in `invalidates`, which of that query's inputs refresh. */
+  scopes: TScopes;
+}
+/**
+ * A procedure the spec calls with `useMutation` that the embedding page
+ * handles instead of the server: the server checks the input and the view
+ * hands it to `onAction`. It has no output and refreshes nothing.
+ */
+export interface ActionDefinition<TInput extends z.ZodType | undefined = z.ZodType | undefined> {
+  description: string;
+  input: TInput;
+  kind: "action";
+  output: undefined;
+}
+export type ProcedureDefinition = ActionDefinition | MutationDefinition | QueryDefinition;
+export type Procedures = Readonly<Record<string, ProcedureDefinition>>;
+/**
+ * The schema of what a procedure's views read: its projection's when it has
+ * one, else its output; `undefined` for an action or a procedure with no
+ * output. The prompt shows it, and the member check reads against it.
+ */
+export declare function dataSchema(procedure: ProcedureDefinition): z.ZodType | undefined;
+/** What `run` receives for a procedure: the parsed input, or `undefined` when it takes none. */
+export type InputOf<P extends ProcedureDefinition> = P["input"] extends z.ZodType ? z.output<P["input"]> : undefined;
+/** What `run` returns for a procedure, before the server parses it. */
+export type OutputOf<P extends ProcedureDefinition> = P["output"] extends z.ZodType ? z.input<P["output"]> : unknown;
+/** How `query` and `mutation` take a projection: `project` returns what `schema` parses. */
+interface ProjectionOption<TOutput, TProjection extends z.ZodType> {
+  project: (output: TOutput) => z.input<TProjection>;
+  schema: TProjection;
+}
+export declare function query<TOutput extends z.ZodType, TInput extends z.ZodType | undefined = undefined, TProjection extends z.ZodType = z.ZodType>(definition: {
+  description: string;
+  input?: TInput;
+  output: TOutput;
+  /** What views read instead of the whole output; see `Projection`. */
+  projection?: ProjectionOption<z.output<TOutput>, TProjection>;
+}): QueryDefinition<TInput, TOutput>;
+/** A schema's parsed value, or `undefined` when there is no schema. */
+export type Parsed<T extends z.ZodType | undefined> = T extends z.ZodType ? z.output<T> : undefined;
+/**
+ * The scopes an `invalidates` value means. A list or nothing leaves `TScopes`
+ * at its default, with a `string` key, and refreshes every input of each name.
+ */
+type ScopesOf<TScopes, TNames extends ReadonlyArray<string>> = string extends keyof TScopes ? { readonly [K in TNames[number]]: true; } : { readonly [K in keyof TScopes]: Extract<TScopes[K], InvalidationScope>; };
+/**
+ * Any function, by a member every function has. It has no call signature on
+ * purpose: see `mutation`'s `TScopes`.
+ */
+interface ScopeFunction {
+  readonly name: string;
+}
+/** What `mutation` infers scopes from: `true` or a function, per name. */
+type WrittenScope = ScopeFunction | true;
+type WrittenScopes = Readonly<Record<string, WrittenScope>>;
+export declare function mutation<TInput extends z.ZodType | undefined = undefined, TOutput extends z.ZodType | undefined = undefined, TProjection extends z.ZodType = z.ZodType, const TScopes extends WrittenScopes = WrittenScopes, const TNames extends ReadonlyArray<string> = readonly []>(definition: {
+  /**
+   * What the page asks the user before a call runs, written from the parsed
+   * input. With it, `policy` defaults to `"confirm"`.
+   */
+  confirm?: (input: Parsed<TInput>) => string;
+  description: string;
+  input?: TInput;
+  /**
+   * The queries a success refreshes. A list of names refreshes every input
+   * of each; an object keyed by name scopes each one (`InvalidationScope`).
+   */
+  invalidates?: TNames | { readonly [K in keyof TScopes]: TScopes[K] & InvalidationScope<Parsed<TInput>, Parsed<TOutput>>; };
+  output?: TOutput;
+  /**
+   * Whether a call runs; see `CallPolicy`. Default `"confirm"` with a
+   * `confirm` message and `"allow"` without one. `"confirm"` needs the
+   * message: the model never writes what the user is asked.
+   */
+  policy?: CallPolicy;
+  /** What views read instead of the whole output; see `Projection`. */
+  projection?: ProjectionOption<Parsed<TOutput>, TProjection>;
+}): MutationDefinition<TInput, TOutput, NoInfer<ScopesOf<TScopes, TNames>>>;
+export declare function action<TInput extends z.ZodType | undefined = undefined>(definition: {
+  description: string;
+  input?: TInput;
+}): ActionDefinition<NoInfer<TInput>>;
+//#endregion
+export {};

package/dist/procedures.js

@@ -0,0 +1,61 @@
+import "zod";
+//#region src/procedures.ts
+/**
+* Whether `policy` is one of the three. A plain-JavaScript host, or a server
+* override that returns a Promise, can hand over anything; the server denies
+* a call whose policy is not one of these rather than running it.
+*/
+function isCallPolicy(policy) {
+	return policy === "allow" || policy === "confirm" || policy === "deny";
+}
+/**
+* The schema of what a procedure's views read: its projection's when it has
+* one, else its output; `undefined` for an action or a procedure with no
+* output. The prompt shows it, and the member check reads against it.
+*/
+function dataSchema(procedure) {
+	return procedure.kind === "action" ? void 0 : procedure.projection?.schema ?? procedure.output;
+}
+function query(definition) {
+	const input = definition.input;
+	const created = {
+		description: definition.description,
+		input,
+		kind: "query",
+		output: definition.output
+	};
+	if (definition.projection !== void 0) created.projection = definition.projection;
+	return created;
+}
+function isNameList(value) {
+	return Array.isArray(value);
+}
+function mutation(definition) {
+	const input = definition.input;
+	const output = definition.output;
+	const invalidates = definition.invalidates ?? [];
+	const scopes = isNameList(invalidates) ? Object.fromEntries(invalidates.map((name) => [name, true])) : invalidates;
+	const created = {
+		description: definition.description,
+		input,
+		invalidates: Object.keys(scopes),
+		kind: "mutation",
+		output,
+		policy: definition.policy ?? (definition.confirm === void 0 ? "allow" : "confirm"),
+		scopes
+	};
+	if (definition.confirm !== void 0) created.confirm = definition.confirm;
+	if (definition.projection !== void 0) created.projection = definition.projection;
+	return created;
+}
+function action(definition) {
+	const input = definition.input;
+	return {
+		description: definition.description,
+		input,
+		kind: "action",
+		output: void 0
+	};
+}
+//#endregion
+export { action, dataSchema, isCallPolicy, mutation, query };

package/dist/recipes.d.ts

@@ -0,0 +1,24 @@
+//#region src/recipes.d.ts
+/**
+ * A recipe: a compound component the product writes in Pickle, from catalog
+ * components and other recipes. The model uses it like any tag. Because it is
+ * written in catalog tags, it runs on every renderer whose catalog has those
+ * tags, and the server checks it against the host at startup.
+ */
+export interface RecipeDefinition {
+  /** One line: when the model should reach for this recipe. */
+  description: string;
+  /** A one-line use, shown to the model. */
+  example?: string;
+  /** The name of the `<define>` in `source`. */
+  name: string;
+  /** Pickle source with exactly one `<define name="…">`. */
+  source: string;
+}
+/** A recipe named by the `<define>` in its source. */
+export declare function recipe(definition: {
+  description: string;
+  example?: string;
+  source: string;
+}): RecipeDefinition;
+//#endregion

package/dist/recipes.js

@@ -0,0 +1,79 @@
+//#region src/recipes.ts
+const RECIPE_NAME = /^[a-z][A-Za-z0-9]*$/;
+const DEFINE_TAG = /<define(?=[\s/>])/g;
+const ATTR_NAME = /[A-Za-z_][\w-]*/y;
+/** Index just past the `}` matching the `{` at `start`, or -1 if unbalanced. */
+function skipBraced(source, start) {
+	let depth = 0;
+	let quote = null;
+	for (let index = start; index < source.length; index++) {
+		const char = source.charAt(index);
+		if (quote !== null) {
+			if (char === "\\") index++;
+			else if (char === quote) quote = null;
+		} else if (char === "\"" || char === "'" || char === "`") quote = char;
+		else if (char === "{") depth++;
+		else if (char === "}") {
+			depth--;
+			if (depth === 0) return index + 1;
+		}
+	}
+	return -1;
+}
+/** A literal attribute value: `"x"`, `'x'` or `{"x"}`. */
+function literal(value) {
+	const quoted = /^\s*\{?\s*(?:"([^"\\]*)"|'([^'\\]*)')\s*\}?\s*$/.exec(value);
+	return quoted === null ? null : quoted[1] ?? quoted[2] ?? null;
+}
+/**
+* The `name` attribute of the opening tag at `start`, read the way the
+* compiler reads it. The compiler checks the whole source again at startup.
+*/
+function nameAttribute(source, start) {
+	let cursor = start + 7;
+	while (cursor < source.length) {
+		const char = source.charAt(cursor);
+		if (/\s/.test(char)) {
+			cursor++;
+			continue;
+		}
+		if (char === ">" || char === "/") return null;
+		ATTR_NAME.lastIndex = cursor;
+		const attr = ATTR_NAME.exec(source)?.[0];
+		if (attr === void 0) return null;
+		cursor += attr.length;
+		if (source.charAt(cursor) !== "=") continue;
+		cursor++;
+		const opener = source.charAt(cursor);
+		let end;
+		if (opener === "\"" || opener === "'") end = source.indexOf(opener, cursor + 1) + 1;
+		else if (opener === "{") end = skipBraced(source, cursor);
+		else return null;
+		if (end <= 0) return null;
+		if (attr === "name") return literal(source.slice(cursor, end));
+		cursor = end;
+	}
+	return null;
+}
+/** The name of the one `<define>` in a recipe's source. */
+function defineName(source) {
+	const starts = [...source.matchAll(DEFINE_TAG)].map((match) => match.index);
+	const [start] = starts;
+	if (start === void 0 || starts.length > 1) throw new Error(`A recipe's source must contain exactly one <define>; found ${starts.length}`);
+	const name = nameAttribute(source, start);
+	if (name === null) throw new Error("A recipe's <define> needs a literal name, e.g. <define name=\"orderRow\">");
+	if (!RECIPE_NAME.test(name)) throw new Error(`Recipe name "${name}" must start with a lowercase letter and use letters and digits only`);
+	return name;
+}
+/** A recipe named by the `<define>` in its source. */
+function recipe(definition) {
+	const built = {
+		description: definition.description,
+		name: defineName(definition.source),
+		source: definition.source
+	};
+	if (definition.example !== void 0) built.example = definition.example;
+	return built;
+}
+//#endregion
+export { recipe };

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@jigs.design/host",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Define a host: the catalog a spec may draw, the procedures it may call, and the image hosts.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yoamomonstruos/pickle.git",
+    "directory": "packages/host"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@jigs.design/runtime": "0.1.0"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "zod": "4.6.7"
+  }
 }