@ouispec/bindings 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Closure Studio
+
+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,19 @@
-# Temporary Holding Version
+# @ouispec/bindings
 
-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.
+Every UI capability declared once, in the code that implements it. A design-system control carries a binding (an id, a label, a description, and an input schema derived from its props) and registers its real handler under it, so the agent and the person go through the same code path.
+
+```sh
+npm install @ouispec/bindings
+```
+
+| Entry | What it has |
+|---|---|
+| `@ouispec/bindings` | The binding and control-table types, action effects (`effectKind`, `effectAccess`, `requiresApproval`), the room catalog contract, the generated manifest and knowledge and how they're read, and the registry of what is mounted. No dependencies on React, so the build-time generator reads it in plain Node. |
+| `@ouispec/bindings/react` | `AgentBindingProvider`, `useAgentBinding`, `useAgentBindings`, `useRoomRegistration`, `useAgentProblems`, `useAgentFacts`. |
+| `@ouispec/bindings/oui` | `connectBindings`, which turns what is mounted into the tab's OUI surfaces, and `createDeclaredJobTracker`, which follows a job on the product's declared events. |
+
+A design system declares its control table in `package.json` under `oui.agentControls`; a room names its catalog under `oui.agentCatalog`. `@ouispec/cli` generates an app's surfaces and knowledge from them, and `@ouispec/testing` checks that a design system keeps the contract.
+
+An app must have exactly one copy of this package and of `oui-spec`: two copies split the registry, and the agent sees no controls.
+
+Start with [the integrator guide](https://github.com/wesreid/oui/blob/main/packages/contract/INTEGRATOR-GUIDE.md).

package/dist/binding.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The semantic binding a design-system control carries (ADR-0220 §2.2): what
+ * the control means, in the user's terms, declared where the page uses it.
+ *
+ * It uses a room catalog entry's vocabulary (`RoomEntryInfo`'s id, title and
+ * description; `ActionEffect`; `destructive`), so to the generator a page
+ * control and a room entry look the same. What is never written: the input
+ * schema, which is derived from the control's own props, and where the control
+ * is, which the generator derives from the page's component tree.
+ */
+import type { ActionEffect } from './effect.js';
+import type { AgentBinding, AgentItem, AgentProp, NonAgentBinding } from '@ouispec/contract';
+export type { AgentBinding, AgentItem, AgentProp, NonAgentBinding };
+/**
+ * What using the control does.
+ * @deprecated Since 0.8: the one vocabulary is `ActionEffect` (ADR-0226 §2.6). Kept for one minor.
+ */
+export type BindingEffect = ActionEffect;
+/**
+ * The `agent` prop of a composite with several callbacks (a card with open,
+ * duplicate and delete): one binding per slot, and the row they all belong to.
+ */
+export type AgentSlots<Slot extends string> = {
+    item?: AgentItem;
+} & {
+    [K in Slot]?: AgentProp;
+};
+/**
+ * One slot's binding of a composite's `agent` prop, with the row the whole
+ * composite is (a card's voice, a missing font's replacements) carried into
+ * it. A composite registers each slot with this, never with `agent?.slot`:
+ * the generator reads `item` beside the slots, so a slot registered without
+ * it is a row-keyed action whose rows the page never reports.
+ */
+export declare function slotBinding<Slot extends string>(slots: AgentSlots<Slot> | undefined | null, slot: Slot): AgentProp | undefined;
+export declare function isNonAgent(prop: AgentProp | undefined | null): prop is NonAgentBinding;
+export declare function isAgentBinding(prop: unknown): prop is AgentBinding;
+/** Dotted lower-kebab segments, at least two: `area.control`. */
+export declare const BINDING_ID_PATTERN: RegExp;
+/** Longest tool name assistant runtimes accept. */
+export declare const MAX_TOOL_NAME_LENGTH = 64;
+/** The tool name for a binding or room entry id: `voices.detail.engine` → `voices_detail_engine`. */
+export declare function toolName(id: string): string;
+/** Why an id is not a valid binding id, or null. */
+export declare function bindingIdProblem(id: string): string | null;
+//# sourceMappingURL=binding.d.ts.map

package/dist/binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../src/binding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAG7F,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,eAAe,EAAE,CAAC;AAEpE;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,YAAY,CAAC;AAEzC;;;GAGG;AACH,MAAM,MAAM,UAAU,CAAC,IAAI,SAAS,MAAM,IAAI;IAAE,IAAI,CAAC,EAAE,SAAS,CAAA;CAAE,GAAG;KAAG,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,SAAS;CAAE,CAAC;AAEjG;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,SAAS,MAAM,EAC7C,KAAK,EAAE,UAAU,CAAC,IAAI,CAAC,GAAG,SAAS,GAAG,IAAI,EAC1C,IAAI,EAAE,IAAI,GACT,SAAS,GAAG,SAAS,CAIvB;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,GAAG,IAAI,GAAG,IAAI,IAAI,eAAe,CAEtF;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,YAAY,CAOlE;AAED,iEAAiE;AACjE,eAAO,MAAM,kBAAkB,QAA6C,CAAC;AAE7E,mDAAmD;AACnD,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC,qGAAqG;AACrG,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED,oDAAoD;AACpD,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQ1D"}

package/dist/binding.js

@@ -0,0 +1,51 @@
+/**
+ * The semantic binding a design-system control carries (ADR-0220 §2.2): what
+ * the control means, in the user's terms, declared where the page uses it.
+ *
+ * It uses a room catalog entry's vocabulary (`RoomEntryInfo`'s id, title and
+ * description; `ActionEffect`; `destructive`), so to the generator a page
+ * control and a room entry look the same. What is never written: the input
+ * schema, which is derived from the control's own props, and where the control
+ * is, which the generator derives from the page's component tree.
+ */
+/**
+ * One slot's binding of a composite's `agent` prop, with the row the whole
+ * composite is (a card's voice, a missing font's replacements) carried into
+ * it. A composite registers each slot with this, never with `agent?.slot`:
+ * the generator reads `item` beside the slots, so a slot registered without
+ * it is a row-keyed action whose rows the page never reports.
+ */
+export function slotBinding(slots, slot) {
+    const prop = slots?.[slot];
+    if (!prop || isNonAgent(prop) || !slots?.item || prop.item)
+        return prop;
+    return { ...prop, item: slots.item };
+}
+export function isNonAgent(prop) {
+    return !!prop && typeof prop.nonAgent === 'string';
+}
+export function isAgentBinding(prop) {
+    return (!!prop &&
+        typeof prop === 'object' &&
+        typeof prop.id === 'string' &&
+        typeof prop.description === 'string');
+}
+/** Dotted lower-kebab segments, at least two: `area.control`. */
+export const BINDING_ID_PATTERN = /^[a-z][a-z0-9-]*(\.[a-z0-9][a-z0-9-]*)+$/;
+/** Longest tool name assistant runtimes accept. */
+export const MAX_TOOL_NAME_LENGTH = 64;
+/** The tool name for a binding or room entry id: `voices.detail.engine` → `voices_detail_engine`. */
+export function toolName(id) {
+    return id.replace(/[.\-/]/g, '_');
+}
+/** Why an id is not a valid binding id, or null. */
+export function bindingIdProblem(id) {
+    if (!BINDING_ID_PATTERN.test(id)) {
+        return `"${id}" must be dotted lower-kebab with at least two segments, like "voices.library"`;
+    }
+    if (toolName(id).length > MAX_TOOL_NAME_LENGTH) {
+        return `"${id}" makes a tool name longer than ${MAX_TOOL_NAME_LENGTH} characters`;
+    }
+    return null;
+}
+//# sourceMappingURL=binding.js.map

package/dist/binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding.js","sourceRoot":"","sources":["../src/binding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAoBH;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CACzB,KAA0C,EAC1C,IAAU;IAEV,MAAM,IAAI,GAAG,KAAK,EAAE,CAAC,IAAI,CAA0B,CAAC;IACpD,IAAI,CAAC,IAAI,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,IAAI,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACxE,OAAO,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAkC;IAC3D,OAAO,CAAC,CAAC,IAAI,IAAI,OAAQ,IAAwB,CAAC,QAAQ,KAAK,QAAQ,CAAC;AAC1E,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAa;IAC1C,OAAO,CACL,CAAC,CAAC,IAAI;QACN,OAAO,IAAI,KAAK,QAAQ;QACxB,OAAQ,IAAqB,CAAC,EAAE,KAAK,QAAQ;QAC7C,OAAQ,IAAqB,CAAC,WAAW,KAAK,QAAQ,CACvD,CAAC;AACJ,CAAC;AAED,iEAAiE;AACjE,MAAM,CAAC,MAAM,kBAAkB,GAAG,0CAA0C,CAAC;AAE7E,mDAAmD;AACnD,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAEvC,qGAAqG;AACrG,MAAM,UAAU,QAAQ,CAAC,EAAU;IACjC,OAAO,EAAE,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;AACpC,CAAC;AAED,oDAAoD;AACpD,MAAM,UAAU,gBAAgB,CAAC,EAAU;IACzC,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;QACjC,OAAO,IAAI,EAAE,gFAAgF,CAAC;IAChG,CAAC;IACD,IAAI,QAAQ,CAAC,EAAE,CAAC,CAAC,MAAM,GAAG,oBAAoB,EAAE,CAAC;QAC/C,OAAO,IAAI,EAAE,mCAAmC,oBAAoB,aAAa,CAAC;IACpF,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/controls.d.ts

@@ -0,0 +1,69 @@
+/**
+ * What each kind of design-system control lets someone do, and the input
+ * schema that follows from its props (ADR-0220 §2.2).
+ *
+ * `deriveInputSchema` is the one derivation. A control runs it in the browser
+ * on its live props; the generator runs it at build time on the props it can
+ * read statically. So the schema a tool takes is never written by hand: a
+ * slider's range is its `min` and `max`, a select's options are its options.
+ */
+import type { AnyControlKind, ControlKind, ControlKindRegistration, ControlTable, JsonSchema, RegisteredControlKind, SchemaProps } from '@ouispec/contract';
+export type { AnyControlKind, ControlDescriptor, ControlKind, ControlKindRegistration, ControlOption, ControlTable, ControlTableFile, EntriesDescriptor, KindSchemaDerivation, OptionsSource, RegisteredControlKind, SchemaPropName, SchemaPropSources, SchemaProps, SlotDescriptor, } from '@ouispec/contract';
+/**
+ * Every built-in kind (`ControlKind`, documented in the contract). Closed: a
+ * design system adds a kind only by registering it (`registerControlKind`),
+ * under an `x-` name, in its control table.
+ */
+export declare const CONTROL_KINDS: readonly ControlKind[];
+/** What each kind's action does, as knowledge and tool descriptions say it. */
+export declare const CONTROL_VERBS: Readonly<Record<ControlKind, string>>;
+/** The schema of a control's value, from its kind and props. */
+/**
+ * How many of a choice's options its schema's description names. The enum
+ * always lists every value; the description is prose for the assistant, and a
+ * control with hundreds of options (a language picker) would otherwise fill
+ * the page state the assistant reads with option names and crowd out what the
+ * page shows.
+ */
+export declare const MAX_DESCRIBED_OPTIONS = 20;
+export declare function deriveValueSchema(kind: AnyControlKind, props?: SchemaProps): JsonSchema | null;
+export declare function isRegisteredKind(kind: string): kind is RegisteredControlKind;
+/** Why a registration is not valid, or null. */
+export declare function controlKindRegistrationProblem(registration: unknown): string | null;
+/**
+ * Register a design system's control kind, so controls of that kind derive
+ * their value schema and verb. Registering the same kind again with the same
+ * definition does nothing; with another definition it throws, as does an
+ * invalid registration.
+ */
+export declare function registerControlKind(registration: ControlKindRegistration): void;
+export declare function registeredControlKind(kind: string): ControlKindRegistration | undefined;
+/** What using a control of this kind does, as a tool description starts. */
+export declare function controlVerb(kind: AnyControlKind): string;
+/** The item parameter an action takes when its control is one of a list's rows. */
+export declare const ITEM_PROPERTY = "item";
+export declare function itemSchema(items?: readonly {
+    key: string;
+    title: string;
+}[]): JsonSchema;
+/** Beyond this many rows, the item parameter names none of them; the page observation lists them. */
+export declare const MAX_ITEM_ENUM = 100;
+/**
+ * The input schema of the action a control makes: `{ value }` for a field,
+ * nothing for a button or dialog, and an `item` when it is one of a list's rows.
+ */
+export declare function deriveInputSchema(kind: AnyControlKind, props?: SchemaProps, options?: {
+    itemized?: boolean;
+    items?: readonly {
+        key: string;
+        title: string;
+    }[];
+}): JsonSchema;
+/** Where a control table file lists the kinds its design system registers. */
+export declare const CONTROL_TABLE_KINDS_KEY = "$kinds";
+/** A control table file's controls and the kinds it registers. */
+export declare function readControlTable(file: unknown): {
+    controls: ControlTable;
+    kinds: readonly ControlKindRegistration[];
+};
+//# sourceMappingURL=controls.d.ts.map

package/dist/controls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controls.d.ts","sourceRoot":"","sources":["../src/controls.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,WAAW,EACX,uBAAuB,EACvB,YAAY,EACZ,UAAU,EACV,qBAAqB,EACrB,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAO3B,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,WAAW,EACX,uBAAuB,EACvB,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,aAAa,EACb,qBAAqB,EACrB,cAAc,EACd,iBAAiB,EACjB,WAAW,EACX,cAAc,GACf,MAAM,mBAAmB,CAAC;AAE3B;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,WAAW,EAa/C,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAa/D,CAAC;AASF,gEAAgE;AAChE;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,GAAE,WAAgB,GAAG,UAAU,GAAG,IAAI,CAiIlG;AAQD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,qBAAqB,CAE5E;AAED,gDAAgD;AAChD,wBAAgB,8BAA8B,CAAC,YAAY,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAcnF;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,uBAAuB,GAAG,IAAI,CAS/E;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,uBAAuB,GAAG,SAAS,CAEvF;AAED,4EAA4E;AAC5E,wBAAgB,WAAW,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAKxD;AA8CD,mFAAmF;AACnF,eAAO,MAAM,aAAa,SAAS,CAAC;AAEpC,wBAAgB,UAAU,CAAC,KAAK,CAAC,EAAE,SAAS;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,UAAU,CAQxF;AAED,qGAAqG;AACrG,eAAO,MAAM,aAAa,MAAM,CAAC;AAEjC;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,cAAc,EACpB,KAAK,GAAE,WAAgB,EACvB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CAAO,GACtF,UAAU,CAkBZ;AAID,8EAA8E;AAC9E,eAAO,MAAM,uBAAuB,WAAW,CAAC;AAEhD,kEAAkE;AAClE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG;IAAE,QAAQ,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,SAAS,uBAAuB,EAAE,CAAA;CAAE,CAMrH"}

package/dist/controls.js

@@ -0,0 +1,334 @@
+/**
+ * What each kind of design-system control lets someone do, and the input
+ * schema that follows from its props (ADR-0220 §2.2).
+ *
+ * `deriveInputSchema` is the one derivation. A control runs it in the browser
+ * on its live props; the generator runs it at build time on the props it can
+ * read statically. So the schema a tool takes is never written by hand: a
+ * slider's range is its `min` and `max`, a select's options are its options.
+ */
+import { stableStringify } from './json-schema.js';
+/**
+ * Every built-in kind (`ControlKind`, documented in the contract). Closed: a
+ * design system adds a kind only by registering it (`registerControlKind`),
+ * under an `x-` name, in its control table.
+ */
+export const CONTROL_KINDS = [
+    'button',
+    'toggle',
+    'text',
+    'number',
+    'choice',
+    'multi-choice',
+    'color',
+    'font',
+    'tabs',
+    'date',
+    'date-range',
+    'dialog',
+];
+/** What each kind's action does, as knowledge and tool descriptions say it. */
+export const CONTROL_VERBS = {
+    button: 'Press',
+    toggle: 'Turn on or off',
+    text: 'Type into',
+    number: 'Set',
+    choice: 'Choose',
+    'multi-choice': 'Choose any of',
+    color: 'Set the colour of',
+    font: 'Choose the face of',
+    tabs: 'Select a tab of',
+    date: 'Set the date of',
+    'date-range': 'Set the dates of',
+    dialog: 'Close',
+};
+const INPUT_FORMATS = {
+    email: 'email',
+    url: 'uri',
+    date: 'date',
+    time: 'time',
+};
+/** The schema of a control's value, from its kind and props. */
+/**
+ * How many of a choice's options its schema's description names. The enum
+ * always lists every value; the description is prose for the assistant, and a
+ * control with hundreds of options (a language picker) would otherwise fill
+ * the page state the assistant reads with option names and crowd out what the
+ * page shows.
+ */
+export const MAX_DESCRIBED_OPTIONS = 20;
+export function deriveValueSchema(kind, props = {}) {
+    if (isRegisteredKind(kind))
+        return registeredValueSchema(kind, props);
+    switch (kind) {
+        case 'button':
+        case 'dialog':
+            return null;
+        case 'toggle':
+            return { type: 'boolean', description: 'true to turn it on, false to turn it off' };
+        case 'text': {
+            if (props.inputType === 'number')
+                return numberSchema(props);
+            const format = props.inputType ? INPUT_FORMATS[props.inputType] : undefined;
+            return {
+                type: 'string',
+                description: 'The text to put in the field, replacing what is there',
+                ...(props.minLength !== undefined ? { minLength: props.minLength } : {}),
+                ...(props.maxLength !== undefined ? { maxLength: props.maxLength } : {}),
+                ...(props.pattern !== undefined ? { pattern: props.pattern } : {}),
+                ...(format ? { format } : {}),
+            };
+        }
+        case 'number':
+            return numberSchema(props);
+        case 'multi-choice': {
+            const options = (props.options ?? []).filter(o => !o.disabled);
+            const values = options.map(o => o.value);
+            const described = options.map(o => (String(o.value) === o.title ? o.title : `${o.value} = ${o.title}`));
+            return {
+                type: 'array',
+                description: 'The options to choose, replacing the ones chosen now; [] for none' +
+                    (described.length ? `: ${described.join('; ')}` : ''),
+                items: {
+                    type: values.every(v => typeof v === 'number') && values.length > 0 ? 'number' : 'string',
+                    ...(values.length ? { enum: values } : {}),
+                },
+                uniqueItems: true,
+            };
+        }
+        case 'choice':
+        case 'tabs': {
+            const options = (props.options ?? []).filter(o => !o.disabled);
+            const values = options.map(o => o.value);
+            // Named in the description up to a limit; every value stays in the enum.
+            const described = options
+                .slice(0, MAX_DESCRIBED_OPTIONS)
+                .map(o => (String(o.value) === o.title ? o.title : `${o.value} = ${o.title}`));
+            const unnamed = options.length - described.length;
+            const schema = {
+                type: values.every(v => typeof v === 'number') && values.length > 0 ? 'number' : 'string',
+                description: (kind === 'tabs' ? 'The tab to select' : 'The option to choose') +
+                    (described.length ? `: ${described.join('; ')}` : '') +
+                    (unnamed > 0 ? `; and ${unnamed} more, any of which may be chosen` : ''),
+                ...(values.length ? { enum: props.clearable ? [...values, null] : values } : {}),
+            };
+            if (props.clearable) {
+                return { ...schema, type: [schema.type, 'null'] };
+            }
+            return schema;
+        }
+        case 'color': {
+            const kinds = props.paintKinds ?? ['solid'];
+            const gradients = kinds.filter(k => k !== 'solid');
+            const css = {
+                type: 'string',
+                description: 'A CSS colour, e.g. "#eb0a1e" or "rgba(0,0,0,0.5)"',
+            };
+            const variants = [css];
+            if (gradients.length) {
+                variants.push({
+                    type: 'object',
+                    description: `A gradient paint: kind ${gradients.join(' or ')}, its stops from offset 0 to 1, and for a linear gradient its angle in degrees`,
+                    properties: {
+                        kind: { type: 'string', enum: gradients },
+                        angle: { type: 'number', 'x-unit': '°' },
+                        stops: {
+                            type: 'array',
+                            minItems: 2,
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    offset: { type: 'number', minimum: 0, maximum: 1 },
+                                    color: css,
+                                },
+                                required: ['offset', 'color'],
+                            },
+                        },
+                    },
+                    required: ['kind', 'stops'],
+                });
+            }
+            if (props.allowNone)
+                variants.push({ type: 'null', description: 'No paint' });
+            return variants.length === 1 ? css : { anyOf: variants, description: 'The paint to set' };
+        }
+        case 'font':
+            return {
+                type: 'object',
+                description: 'The face to set: a family by name, and optionally one of its styles and axis values',
+                properties: {
+                    family: {
+                        type: 'string',
+                        description: 'The family name as the picker lists it',
+                        ...(props.options?.length && props.options.length <= MAX_ITEM_ENUM
+                            ? { enum: props.options.map(o => o.title) }
+                            : {}),
+                    },
+                    style: { type: 'string', description: 'A named style of the family, e.g. "Bold Italic"' },
+                    variation: {
+                        type: 'object',
+                        description: 'Variable-font axis values by tag, e.g. {"wght": 650}',
+                        additionalProperties: { type: 'number' },
+                    },
+                },
+                required: ['family'],
+            };
+        case 'date':
+            return { type: 'string', format: 'date', description: 'A date, YYYY-MM-DD' };
+        case 'date-range':
+            return {
+                type: 'object',
+                description: 'A range of dates, YYYY-MM-DD: its first day and its last, the start on or before the end',
+                properties: {
+                    start: { type: 'string', format: 'date', description: 'The first day' },
+                    end: { type: 'string', format: 'date', description: 'The last day' },
+                },
+                required: ['start', 'end'],
+                additionalProperties: false,
+            };
+    }
+}
+// ─── Registered kinds ────────────────────────────────────────────────────────
+const REGISTERED_KIND = /^x-[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const registeredKinds = new Map();
+export function isRegisteredKind(kind) {
+    return kind.startsWith('x-');
+}
+/** Why a registration is not valid, or null. */
+export function controlKindRegistrationProblem(registration) {
+    const r = registration;
+    if (!r || typeof r !== 'object')
+        return 'a control kind registration is an object';
+    if (typeof r.kind !== 'string' || !REGISTERED_KIND.test(r.kind))
+        return `a registered control kind is named x-<lower-kebab>, not ${JSON.stringify(r.kind)}`;
+    if (typeof r.verb !== 'string' || !r.verb.trim())
+        return `${r.kind} needs the verb its tools start with`;
+    const d = r.deriveSchema;
+    if (!d || typeof d !== 'object' || !d.schema || typeof d.schema !== 'object')
+        return `${r.kind} needs deriveSchema.schema, the value's schema`;
+    for (const [pointer, prop] of Object.entries(d.props ?? {})) {
+        if (!pointer.startsWith('/'))
+            return `${r.kind}: "${pointer}" is not a JSON Pointer into its schema`;
+        if (typeof prop !== 'string')
+            return `${r.kind}: "${pointer}" names no prop`;
+    }
+    return null;
+}
+/**
+ * Register a design system's control kind, so controls of that kind derive
+ * their value schema and verb. Registering the same kind again with the same
+ * definition does nothing; with another definition it throws, as does an
+ * invalid registration.
+ */
+export function registerControlKind(registration) {
+    const problem = controlKindRegistrationProblem(registration);
+    if (problem)
+        throw new Error(problem);
+    const existing = registeredKinds.get(registration.kind);
+    // The same definition, whatever its key order: a shipped table's `$kinds` are written with sorted keys.
+    if (existing && stableStringify(existing) !== stableStringify(registration)) {
+        throw new Error(`${registration.kind} is already registered with another definition`);
+    }
+    registeredKinds.set(registration.kind, registration);
+}
+export function registeredControlKind(kind) {
+    return registeredKinds.get(kind);
+}
+/** What using a control of this kind does, as a tool description starts. */
+export function controlVerb(kind) {
+    if (!isRegisteredKind(kind))
+        return CONTROL_VERBS[kind];
+    const registration = registeredKinds.get(kind);
+    if (!registration)
+        throw new Error(`Control kind ${kind} is not registered`);
+    return registration.verb;
+}
+function registeredValueSchema(kind, props) {
+    const registration = registeredKinds.get(kind);
+    if (!registration)
+        throw new Error(`Control kind ${kind} is not registered`);
+    const schema = structuredClone(registration.deriveSchema.schema);
+    for (const [pointer, prop] of Object.entries(registration.deriveSchema.props ?? {})) {
+        const value = prop === 'options'
+            ? props.options?.filter(o => !o.disabled).map(o => o.value)
+            : props[prop];
+        if (value !== undefined)
+            setAtPointer(schema, pointer, value);
+    }
+    return schema;
+}
+/** Set `value` at a JSON Pointer, making the objects on its way. */
+function setAtPointer(target, pointer, value) {
+    const keys = pointer
+        .slice(1)
+        .split('/')
+        .map(k => k.replace(/~1/g, '/').replace(/~0/g, '~'));
+    let node = target;
+    for (const key of keys.slice(0, -1)) {
+        if (!node[key] || typeof node[key] !== 'object')
+            node[key] = {};
+        node = node[key];
+    }
+    node[keys[keys.length - 1]] = value;
+}
+function numberSchema(props) {
+    const unit = props.unit ? ` in ${props.unit}` : '';
+    const range = props.min !== undefined && props.max !== undefined
+        ? `, from ${props.min} to ${props.max}${props.wrap ? ' (it wraps past either end)' : ''}`
+        : '';
+    return {
+        type: 'number',
+        description: `The value${unit}${range}`,
+        ...(props.min !== undefined ? { minimum: props.min } : {}),
+        ...(props.max !== undefined ? { maximum: props.max } : {}),
+        ...(props.step !== undefined && props.step > 0 ? { multipleOf: props.step } : {}),
+        ...(props.unit ? { 'x-unit': props.unit } : {}),
+    };
+}
+/** The item parameter an action takes when its control is one of a list's rows. */
+export const ITEM_PROPERTY = 'item';
+export function itemSchema(items) {
+    return {
+        type: 'string',
+        description: 'Which one: the id or the exact title of a row the page shows' +
+            (items && items.length ? ` (${items.length} on screen now)` : ''),
+        ...(items && items.length && items.length <= MAX_ITEM_ENUM ? { enum: items.map(i => i.key) } : {}),
+    };
+}
+/** Beyond this many rows, the item parameter names none of them; the page observation lists them. */
+export const MAX_ITEM_ENUM = 100;
+/**
+ * The input schema of the action a control makes: `{ value }` for a field,
+ * nothing for a button or dialog, and an `item` when it is one of a list's rows.
+ */
+export function deriveInputSchema(kind, props = {}, options = {}) {
+    const properties = {};
+    const required = [];
+    const value = deriveValueSchema(kind, props);
+    if (value) {
+        properties.value = value;
+        required.push('value');
+    }
+    if (options.itemized) {
+        properties[ITEM_PROPERTY] = itemSchema(options.items);
+        required.push(ITEM_PROPERTY);
+    }
+    return {
+        type: 'object',
+        properties,
+        ...(required.length ? { required } : {}),
+        additionalProperties: false,
+    };
+}
+// ─── The design system's controls ────────────────────────────────────────────
+/** Where a control table file lists the kinds its design system registers. */
+export const CONTROL_TABLE_KINDS_KEY = '$kinds';
+/** A control table file's controls and the kinds it registers. */
+export function readControlTable(file) {
+    const { [CONTROL_TABLE_KINDS_KEY]: kinds, ...controls } = (file ?? {});
+    return {
+        controls: controls,
+        kinds: Array.isArray(kinds) ? kinds : [],
+    };
+}
+//# sourceMappingURL=controls.js.map

package/dist/controls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"controls.js","sourceRoot":"","sources":["../src/controls.ts"],"names":[],"mappings":"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"}

package/dist/effect.d.ts

@@ -0,0 +1,54 @@
+import { type OUIEffectKind } from 'oui-spec/spec';
+import type { ActionEffect } from '@ouispec/contract';
+/**
+ * What using an action does (ADR-0226 §2.6): one vocabulary for a
+ * design-system control's binding, a room catalog's entry and a generated API
+ * tool, so a page control, a room action and an API call are told apart by
+ * what they change, never by where they are declared.
+ *
+ * | Effect | What it changes | ADR-0210 access |
+ * |---|---|---|
+ * | `view`, `selection`, `navigate`, `open` | What is shown | read |
+ * | `edit` | The document, one undo step | write |
+ * | `file` | Imports or exports a file | write |
+ * | `mutate` | Backend data, through an API operation | write |
+ * | `job` | Starts work that outlives the call, settled on its outcome | write |
+ * | `transaction` | An irreversible external act: an order, a payment, a send, a publish | write, approved |
+ *
+ * A `transaction`, and any `write` declared `destructive`, runs only on an
+ * approval the person gave, bound to the call (ADR-0228).
+ */
+/** How long an approval for an action lasts at most, in minutes (ADR-0228 §2.3). */
+export declare const MAX_APPROVAL_MINUTES = 30;
+export type { ActionEffect, SimpleEffect, JobStatus, JobOutcome, JobSettlement } from '@ouispec/contract';
+/**
+ * The effect kinds. The vocabulary, what each one may change, and what needs
+ * the person's approval are OUI's (`oui-spec`), so the browser that checks an
+ * approval and every declaration here read one definition.
+ */
+export type ActionEffectKind = OUIEffectKind;
+/** Every effect, in the order of the table above. */
+export declare const ACTION_EFFECT_KINDS: readonly ActionEffectKind[];
+/** Whether an effect only changes what is shown, or changes something (ADR-0210 `effect`). */
+export declare const EFFECT_ACCESS: Readonly<Record<ActionEffectKind, 'read' | 'write'>>;
+/**
+ * An effect, or its bare kind: what an OUI surface carries for an action
+ * (`effect: 'transaction'`), and what any reader of effects accepts.
+ */
+export type EffectOrKind = ActionEffect | ActionEffectKind;
+export declare function effectKind(effect: EffectOrKind): ActionEffectKind;
+/** `read` or `write`, as ADR-0210 names it. An action that declares no effect is a `write`: nothing says it only shows. */
+export declare function effectAccess(effect: EffectOrKind | undefined): 'read' | 'write';
+/**
+ * Whether running the action needs the person's approval of the exact call
+ * (ADR-0228 §2.1): a `transaction` always, and a `write` declared destructive.
+ * A host's policy may require it of more; it never waives these. OUI's rule.
+ */
+export declare function requiresApproval(effect: EffectOrKind | undefined, destructive?: boolean): boolean;
+/**
+ * Why a value is not a valid effect, or null. Checks the shape only: whether a
+ * route, container or operation it names exists is the generator's to check
+ * against the app.
+ */
+export declare function effectProblem(value: unknown): string | null;
+//# sourceMappingURL=effect.d.ts.map

package/dist/effect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effect.d.ts","sourceRoot":"","sources":["../src/effect.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EACV,YAAY,EAGb,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;;;;;;;;;GAiBG;AAEH,oFAAoF;AACpF,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAGvC,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAE1G;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,aAAa,CAAC;AAY7C,qDAAqD;AACrD,eAAO,MAAM,mBAAmB,EAAE,SAAS,gBAAgB,EAAqB,CAAC;AAEjF,8FAA8F;AAC9F,eAAO,MAAM,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,CAAqB,CAAC;AAErG;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,gBAAgB,CAAC;AAE3D,wBAAgB,UAAU,CAAC,MAAM,EAAE,YAAY,GAAG,gBAAgB,CAEjE;AAED,2HAA2H;AAC3H,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAE/E;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,EAAE,WAAW,CAAC,EAAE,OAAO,GAAG,OAAO,CAEjG;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAsC3D"}