@ouispec/contract 0.4.5 → 0.4.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/INTEGRATOR-GUIDE.md +14 -14
- package/README.md +1 -1
- package/dist/generated/contract.d.ts +90 -91
- package/dist/generated/contract.d.ts.map +1 -1
- package/dist/generated/schemas.d.ts.map +1 -1
- package/dist/generated/schemas.js +35 -31
- package/dist/generated/schemas.js.map +1 -1
- package/dist/index.d.ts +3 -3
- package/dist/index.js +3 -3
- package/dist/render-contract.d.ts +2 -2
- package/dist/render-contract.js +10 -10
- package/dist/render-contract.js.map +1 -1
- package/package.json +2 -2
- package/schemas/action-effect.json +4 -4
- package/schemas/agent-binding.json +3 -3
- package/schemas/approvals.json +9 -5
- package/schemas/control-kind-registration.json +2 -2
- package/schemas/control-table.json +3 -3
- package/schemas/event-declarations.json +1 -1
- package/schemas/generated-knowledge.json +1 -1
- package/schemas/json-schema.json +4 -4
- package/schemas/oui-config.json +1 -1
- package/schemas/oui-manifest.json +1 -1
- package/schemas/room-catalog-data.json +5 -5
- package/schemas/tier2-mapping.json +1 -1
package/dist/render-contract.js
CHANGED
|
@@ -9,22 +9,22 @@ import { doc, renderNamed } from './codegen.js';
|
|
|
9
9
|
export const CONTRACT_SCHEMA_HOST = 'https://schemas.closurestudio.ai';
|
|
10
10
|
/**
|
|
11
11
|
* Every schema of the contract, in dependency order. One major covers them
|
|
12
|
-
* all
|
|
13
|
-
* The event declarations keep their own document version
|
|
12
|
+
* all: it is `MANIFEST_VERSION`, and it is in each `$id`.
|
|
13
|
+
* The event declarations keep their own document version and `$id`.
|
|
14
14
|
*/
|
|
15
15
|
export const CONTRACT_FILES = [
|
|
16
16
|
{ file: 'json-schema.json', heading: 'JSON Schema, as capabilities declare their inputs and values' },
|
|
17
|
-
{ file: 'action-effect.json', heading: 'What an action does
|
|
18
|
-
{ file: 'agent-binding.json', heading: 'The binding a control carries
|
|
17
|
+
{ file: 'action-effect.json', heading: 'What an action does, and how a job settles' },
|
|
18
|
+
{ file: 'agent-binding.json', heading: 'The binding a control carries' },
|
|
19
19
|
{ file: 'control-kind-registration.json', heading: 'Control kinds, and the props their schemas come from' },
|
|
20
|
-
{ file: 'control-table.json', root: 'ControlTableFile', heading: 'A design system’s control table
|
|
21
|
-
{ file: 'tier2-mapping.json', heading: 'A tier 2 mapping
|
|
22
|
-
{ file: 'room-catalog-data.json', heading: 'A room catalog, as data
|
|
20
|
+
{ file: 'control-table.json', root: 'ControlTableFile', heading: 'A design system’s control table' },
|
|
21
|
+
{ file: 'tier2-mapping.json', heading: 'A tier 2 mapping' },
|
|
22
|
+
{ file: 'room-catalog-data.json', heading: 'A room catalog, as data' },
|
|
23
23
|
{ file: 'oui-manifest.json', heading: 'The generated manifest' },
|
|
24
24
|
{ file: 'generated-knowledge.json', heading: 'The generated knowledge' },
|
|
25
|
-
{ file: 'oui-config.json', root: 'OuiConfigFile', heading: '`oui.config.json`
|
|
26
|
-
{ file: 'approvals.json', root: null, arrays: 'Array', heading: 'Approvals
|
|
27
|
-
{ file: 'event-declarations.json', root: 'EventDeclarationDocument', heading: 'Event declarations
|
|
25
|
+
{ file: 'oui-config.json', root: 'OuiConfigFile', heading: '`oui.config.json`' },
|
|
26
|
+
{ file: 'approvals.json', root: null, arrays: 'Array', heading: 'Approvals' },
|
|
27
|
+
{ file: 'event-declarations.json', root: 'EventDeclarationDocument', heading: 'Event declarations' },
|
|
28
28
|
];
|
|
29
29
|
const hasBody = (schema) => ['type', 'properties', 'oneOf', 'anyOf', 'allOf', '$ref', 'enum', 'const'].some((k) => k in schema);
|
|
30
30
|
/** The version every `$id` of the contract carries, from the manifest's `version`. */
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"render-contract.js","sourceRoot":"","sources":["../src/render-contract.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,GAAG,EAAE,WAAW,EAA6C,MAAM,cAAc,CAAC;AAE3F,mIAAmI;AACnI,MAAM,CAAC,MAAM,oBAAoB,GAAG,kCAAkC,CAAC;AAiBvE;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAA4B;IACrD,EAAE,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,8DAA8D,EAAE;IACrG,EAAE,IAAI,EAAE,oBAAoB,EAAE,OAAO,EAAE,
|
|
1
|
+
{"version":3,"file":"render-contract.js","sourceRoot":"","sources":["../src/render-contract.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ouispec/contract",
|
|
3
|
-
"version": "0.4.
|
|
4
|
-
"description": "The OUI integrator contract
|
|
3
|
+
"version": "0.4.8",
|
|
4
|
+
"description": "The OUI integrator contract: versioned JSON Schemas for the control table, control-kind registration, tier 2 mapping, binding, action effect, room catalog, manifest, knowledge, oui.config.json, approvals and event declarations; the TypeScript types generated from them; a validator; and the integrator guide",
|
|
5
5
|
"homepage": "https://github.com/wesreid/oui/tree/main/packages/contract#readme",
|
|
6
6
|
"bugs": {
|
|
7
7
|
"url": "https://github.com/wesreid/oui/issues"
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
3
|
"$id": "https://schemas.closurestudio.ai/oui/v1/action-effect.json",
|
|
4
4
|
"title": "ActionEffect",
|
|
5
|
-
"description": "What using an action does
|
|
5
|
+
"description": "What using an action does: 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.\n\n| Effect | What it changes | Access |\n|---|---|---|\n| `view`, `selection`, `navigate`, `open` | What is shown | read |\n| `edit` | The document, one undo step | write |\n| `file` | Imports or exports a file | write |\n| `mutate` | Backend data, through an API operation | write |\n| `job` | Starts work that outlives the call, settled on its outcome | write |\n| `transaction` | An irreversible external act: an order, a payment, a send, a publish | write, approved |\n\nA `transaction`, and any `write` declared `destructive`, runs only on an approval the person gave, bound to the call.",
|
|
6
6
|
"oneOf": [
|
|
7
7
|
{ "$ref": "#/$defs/SimpleEffect" },
|
|
8
8
|
{
|
|
@@ -38,7 +38,7 @@
|
|
|
38
38
|
"additionalProperties": false
|
|
39
39
|
},
|
|
40
40
|
{
|
|
41
|
-
"description": "An irreversible external act: an order placed, a payment made, a message sent, something published. Modelled on `job`: its handler may return `pending: { jobId }` and it settles on the outcome. It always needs the person's approval of the exact call
|
|
41
|
+
"description": "An irreversible external act: an order placed, a payment made, a message sent, something published. Modelled on `job`: its handler may return `pending: { jobId }` and it settles on the outcome. It always needs the person's approval of the exact call, which no policy waives.\n\n- `operation`: the API operation it goes through, when it is one.\n- `approvalMinutes`: how long an approval of it lasts, at most 30 (default 5).",
|
|
42
42
|
"type": "object",
|
|
43
43
|
"properties": {
|
|
44
44
|
"kind": { "const": "transaction" },
|
|
@@ -61,11 +61,11 @@
|
|
|
61
61
|
"enum": ["view", "selection", "navigate", "open", "edit", "file", "mutate", "job", "transaction"]
|
|
62
62
|
},
|
|
63
63
|
"EffectAccess": {
|
|
64
|
-
"description": "Whether an effect only changes what is shown (`read`), or changes something (`write`)
|
|
64
|
+
"description": "Whether an effect only changes what is shown (`read`), or changes something (`write`). An action that declares no effect is a `write`.",
|
|
65
65
|
"enum": ["read", "write"]
|
|
66
66
|
},
|
|
67
67
|
"JobStatus": {
|
|
68
|
-
"description": "Where an action whose effect is `job` or `transaction` is
|
|
68
|
+
"description": "Where an action whose effect is `job` or `transaction` is:\n\n- `started`: the handler returned; the job is tracked from this moment, so an outcome that arrives before the first poll is kept.\n- `running`: still going; the runtime polls the app's `JobTracker`.\n- `complete`: the job's declared completion arrived; the result exists.\n- `failed`: its declared failure arrived; the result never will.\n- `timeout`: it did not finish within `timeoutMs`. A failure, never a late success.\n- `unverified`: no `JobTracker`, or no job id to follow: the work was started but cannot be confirmed from the page.",
|
|
69
69
|
"enum": ["started", "running", "complete", "failed", "timeout", "unverified"]
|
|
70
70
|
},
|
|
71
71
|
"JobOutcome": {
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
3
|
"$id": "https://schemas.closurestudio.ai/oui/v1/agent-binding.json",
|
|
4
4
|
"title": "AgentBinding",
|
|
5
|
-
"description": "The semantic binding a design-system control carries
|
|
5
|
+
"description": "The semantic binding a design-system control carries: what the control means, in the user's terms, declared where the page uses it, as its `agent` prop.\n\nIt uses a room catalog entry's vocabulary (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.\n\n**Every value is a build-time constant**. The generator reads bindings from source without running it, so each value is a literal, a `const` it can follow, a property of a constant object, a template literal or `+` over those, or a single-literal type read through the type checker. A value built by a call (`t('save')`, `format(...)`) is refused, naming the binding. A field's build-time `hint` and `placeholder` are added to its tool description the same way.",
|
|
6
6
|
"type": "object",
|
|
7
7
|
"properties": {
|
|
8
8
|
"id": {
|
|
@@ -13,11 +13,11 @@
|
|
|
13
13
|
"title": { "description": "Defaults to the control's visible label or aria-label.", "type": "string" },
|
|
14
14
|
"description": { "description": "What using it does, for someone who cannot see the screen.", "type": "string", "minLength": 1 },
|
|
15
15
|
"effect": {
|
|
16
|
-
"description": "What using it does: what reach paths, data and verification are derived from
|
|
16
|
+
"description": "What using it does: what reach paths, data and verification are derived from.",
|
|
17
17
|
"$ref": "action-effect.json"
|
|
18
18
|
},
|
|
19
19
|
"destructive": {
|
|
20
|
-
"description": "It removes or replaces something the person made; running it needs the person's approval
|
|
20
|
+
"description": "It removes or replaces something the person made; running it needs the person's approval.",
|
|
21
21
|
"type": "boolean"
|
|
22
22
|
},
|
|
23
23
|
"confirm": {
|
package/schemas/approvals.json
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
3
|
"$id": "https://schemas.closurestudio.ai/oui/v1/approvals.json",
|
|
4
4
|
"title": "Approvals",
|
|
5
|
-
"description": "Approvals
|
|
5
|
+
"description": "Approvals: the shapes the agent worker, the approval store in the realtime server, the browser's approval card, OUI's surface runtime and a conversation engine exchange. An irreversible action — a `transaction`, or a `write` declared `destructive` — runs only on an approval the person gave, bound to the exact call by a single-use token.\n\n1. The worker stops the turn at the call and stores it (`PendingApprovalInput`); the person's tab receives `agent:approval_required` (`ApprovalRequiredEvent`) and renders the approval card from its `preview`, whose every word comes from the action's declaration, never from the model.\n2. In a UI only a click on the card counts: the card sends `approval:decide` (`ApprovalDecidePayload`) from the person's own socket. On a conversation channel, the verbatim `readback` and an affirmative next turn.\n3. The store answers the decider only (`ApprovalDecideResult`): a single-use token, a compact JWS (`ApprovalTokenClaims`), and the call's `argsHash`. The tab's OUI runtime holds an `ApprovalGrant`.\n4. The next turn carries the token (`ApprovalContinuation`); the worker redeems it for the stored call, exactly (`ApprovedCall`), and runs it. A UI action request then carries `approval` (`ActionRequestApproval`), which the browser checks against its grant before it runs the handler.\n\nThe args hash is SHA-256 over the RFC 8785 (JCS) canonical JSON of the call's arguments, lowercase hex; `oui-spec/approval-vectors.json` holds every implementation, in any language, to it.",
|
|
6
6
|
"$defs": {
|
|
7
7
|
"ArgsHash": {
|
|
8
8
|
"description": "SHA-256 of the RFC 8785 canonical JSON of a call's arguments, lowercase hex.",
|
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
"pattern": "^[0-9a-f]{64}$"
|
|
11
11
|
},
|
|
12
12
|
"ApprovalChannel": {
|
|
13
|
-
"description": "Where the person confirmed. In a UI only a click on the card counts (`ui`); in a conversation channel, the verbatim readback and an affirmative next turn
|
|
13
|
+
"description": "Where the person confirmed. In a UI only a click on the card counts (`ui`); in a conversation channel, the verbatim readback and an affirmative next turn.",
|
|
14
14
|
"enum": ["ui", "voice", "phone", "sms", "chat"]
|
|
15
15
|
},
|
|
16
16
|
"ApprovalDecision": { "enum": ["approve", "decline"] },
|
|
@@ -26,7 +26,7 @@
|
|
|
26
26
|
"additionalProperties": false
|
|
27
27
|
},
|
|
28
28
|
"ApprovalPreview": {
|
|
29
|
-
"description": "What the person is asked to approve.
|
|
29
|
+
"description": "What the person is asked to approve. By default every word comes from the action's declaration (its title, description and input schema labels), never from the model. A host may write this display copy itself (the worker's `approvals.preview`), to redact a value or to speak the person's language: the call that runs, and the args hash it is bound to, stay the original.",
|
|
30
30
|
"type": "object",
|
|
31
31
|
"properties": {
|
|
32
32
|
"title": { "type": "string" },
|
|
@@ -35,13 +35,17 @@
|
|
|
35
35
|
"readback": {
|
|
36
36
|
"description": "One sentence composed from the fields above, read or sent verbatim on a conversation channel.",
|
|
37
37
|
"type": "string"
|
|
38
|
+
},
|
|
39
|
+
"spokenReadback": {
|
|
40
|
+
"description": "The readback as a voice should say it, when the host wrote one: dates, times and numbers in words, digits grouped for speech. A voice channel speaks it in place of `readback`; every other channel uses `readback`.",
|
|
41
|
+
"type": "string"
|
|
38
42
|
}
|
|
39
43
|
},
|
|
40
44
|
"required": ["title", "arguments", "readback"],
|
|
41
45
|
"additionalProperties": false
|
|
42
46
|
},
|
|
43
47
|
"ApprovalEffect": {
|
|
44
|
-
"description": "The effect the approval is for: the action's declared effect kind (
|
|
48
|
+
"description": "The effect the approval is for: the action's declared effect kind (`transaction` for an irreversible external act), or `write` when it declares none.",
|
|
45
49
|
"type": "string",
|
|
46
50
|
"minLength": 1
|
|
47
51
|
},
|
|
@@ -225,7 +229,7 @@
|
|
|
225
229
|
]
|
|
226
230
|
},
|
|
227
231
|
"ActionRequestApproval": {
|
|
228
|
-
"description": "What a UI action request carries when it runs an approved call (`OUIActionApproval`): the browser runs a `transaction` or destructive action only when this matches a grant this tab received from its own card click
|
|
232
|
+
"description": "What a UI action request carries when it runs an approved call (`OUIActionApproval`): the browser runs a `transaction` or destructive action only when this matches a grant this tab received from its own card click.",
|
|
229
233
|
"type": "object",
|
|
230
234
|
"properties": {
|
|
231
235
|
"approvalId": { "type": "string" },
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
3
|
"$id": "https://schemas.closurestudio.ai/oui/v1/control-kind-registration.json",
|
|
4
4
|
"title": "ControlKindRegistration",
|
|
5
|
-
"description": "A control kind a design system adds
|
|
5
|
+
"description": "A control kind a design system adds. `ControlKind` is closed: a design system adds a kind only by registering it, under an `x-` name. The registration ships in the design system's control table (`$kinds`), where the generator reads it, and the design system registers it at run time with `registerControlKind`, so the browser and the generator derive the same schema.",
|
|
6
6
|
"type": "object",
|
|
7
7
|
"properties": {
|
|
8
8
|
"kind": {
|
|
@@ -26,7 +26,7 @@
|
|
|
26
26
|
"additionalProperties": false,
|
|
27
27
|
"$defs": {
|
|
28
28
|
"ControlKind": {
|
|
29
|
-
"description": "The built-in control kinds, closed:\n\n- `button`: press it (buttons, toolbar buttons, menu items, a row's action).\n- `toggle`: set it on or off (switches, checkboxes).\n- `text`: type into it (inputs, text areas).\n- `number`: set a number (sliders, scrub fields).\n- `choice`: choose one of its options (selects, radio groups, preset tiles).\n- `multi-choice`: choose any of its options (multi-selects, checkbox groups, filter chips).\n- `color`: set a colour or paint (colour pickers, swatches).\n- `font`: choose a family and style (font pickers).\n- `tabs`: select a tab.\n- `date`: set a date.\n- `date-range`: set a start and an end date.\n- `file`: give it a file (upload zones, file buttons): the user's attached file, by its id, which the client resolves to a `File
|
|
29
|
+
"description": "The built-in control kinds, closed:\n\n- `button`: press it (buttons, toolbar buttons, menu items, a row's action).\n- `toggle`: set it on or off (switches, checkboxes).\n- `text`: type into it (inputs, text areas).\n- `number`: set a number (sliders, scrub fields).\n- `choice`: choose one of its options (selects, radio groups, preset tiles).\n- `multi-choice`: choose any of its options (multi-selects, checkbox groups, filter chips).\n- `color`: set a colour or paint (colour pickers, swatches).\n- `font`: choose a family and style (font pickers).\n- `tabs`: select a tab.\n- `date`: set a date.\n- `date-range`: set a start and an end date.\n- `file`: give it a file (upload zones, file buttons): the user's attached file, by its id, which the client resolves to a `File`.\n- `dialog`: close it. Opening is its trigger's.",
|
|
30
30
|
"enum": [
|
|
31
31
|
"button",
|
|
32
32
|
"toggle",
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
3
|
"$id": "https://schemas.closurestudio.ai/oui/v1/control-table.json",
|
|
4
4
|
"title": "ControlTableFile",
|
|
5
|
-
"description": "A design-system package's control table as it ships (`agent-controls.json
|
|
5
|
+
"description": "A design-system package's control table as it ships (`agent-controls.json`): each interactive export's `ControlDescriptor` by export name, and under `$kinds` the control kinds the design system registers, if any. The package declares the table next to its controls, writes it at build time, and names it in its `package.json` under `oui.agentControls` (`closure.agentControls` is read during the transition; declaring both is an error). The conformance kit holds every listed component to registering with the kind declared here.",
|
|
6
6
|
"type": "object",
|
|
7
7
|
"properties": {
|
|
8
8
|
"$kinds": {
|
|
@@ -211,7 +211,7 @@
|
|
|
211
211
|
"additionalProperties": false
|
|
212
212
|
},
|
|
213
213
|
"OuiPackageDeclaration": {
|
|
214
|
-
"description": "What a package declares to the generator under the `oui` key of its `package.json
|
|
214
|
+
"description": "What a package declares to the generator under the `oui` key of its `package.json`: its control table, its room catalog, and the components only the person may use. During the transition the generator and the kit also read `closure.agentControls` and `closure.agentCatalog`; a package declaring a key under both `oui` and `closure` is an error.",
|
|
215
215
|
"type": "object",
|
|
216
216
|
"properties": {
|
|
217
217
|
"agentControls": {
|
|
@@ -223,7 +223,7 @@
|
|
|
223
223
|
"$ref": "room-catalog-data.json#/$defs/AgentCatalogManifestEntry"
|
|
224
224
|
},
|
|
225
225
|
"personOnly": {
|
|
226
|
-
"description": "Export name → why only the person may use it, such as the approval card
|
|
226
|
+
"description": "Export name → why only the person may use it, such as the approval card. The generator refuses an `agent` binding on one.",
|
|
227
227
|
"type": "object",
|
|
228
228
|
"additionalProperties": {
|
|
229
229
|
"type": "string",
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
3
|
"$id": "https://schemas.closurestudio.ai/agent-sdk/event-declarations/v1.json",
|
|
4
4
|
"title": "Event declarations",
|
|
5
|
-
"description": "Every event a product emits over realtime: its payload schema, the rooms it is published to, its correlation fields and its role in a job
|
|
5
|
+
"description": "Every event a product emits over realtime: its payload schema, the rooms it is published to, its correlation fields and its role in a job.",
|
|
6
6
|
"type": "object",
|
|
7
7
|
"required": [
|
|
8
8
|
"version",
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
3
|
"$id": "https://schemas.closurestudio.ai/oui/v1/generated-knowledge.json",
|
|
4
4
|
"title": "GeneratedKnowledge",
|
|
5
|
-
"description": "The knowledge the generator emits with the manifest (`oui-knowledge.json
|
|
5
|
+
"description": "The knowledge the generator emits with the manifest (`oui-knowledge.json`), from the same declarations: the map of the app, every page in full with its relationships and recipes, and the app's frame. No word of it is written by hand. Each turn carries the part for the page the person is on (`resolveKnowledge`): the map, the frame parts around that page, the page in full, and one paragraph for each adjacent page.",
|
|
6
6
|
"type": "object",
|
|
7
7
|
"properties": {
|
|
8
8
|
"version": { "description": "The contract major (`MANIFEST_VERSION`).", "const": 1 },
|
package/schemas/json-schema.json
CHANGED
|
@@ -133,15 +133,15 @@
|
|
|
133
133
|
"type": "string"
|
|
134
134
|
},
|
|
135
135
|
"x-space": {
|
|
136
|
-
"description": "The frame a length, a point or a fraction is measured in, in the room's own words: `artboard` (from its top left), `canvas`, `layer` (the layer's own content), `artboard-fraction` (0–1 of the artboard's width and height). A room names its spaces in its description or a recipe
|
|
136
|
+
"description": "The frame a length, a point or a fraction is measured in, in the room's own words: `artboard` (from its top left), `canvas`, `layer` (the layer's own content), `artboard-fraction` (0–1 of the artboard's width and height). A room names its spaces in its description or a recipe.",
|
|
137
137
|
"type": "string"
|
|
138
138
|
},
|
|
139
139
|
"x-rows": {
|
|
140
|
-
"description": "On an array of objects in an observation: the list is a collection the assistant addresses rows of (a document's layers, its artboards). It names the property each row is addressed by and the one a person calls it by, so a list too long for the page state keeps an index of every row instead of a count, and a title given where an id is expected resolves to its row
|
|
140
|
+
"description": "On an array of objects in an observation: the list is a collection the assistant addresses rows of (a document's layers, its artboards). It names the property each row is addressed by and the one a person calls it by, so a list too long for the page state keeps an index of every row instead of a count, and a title given where an id is expected resolves to its row.",
|
|
141
141
|
"$ref": "#/$defs/RowList"
|
|
142
142
|
},
|
|
143
143
|
"x-ref": {
|
|
144
|
-
"description": "On a string (or the items of an array of strings) in an action's input: the value addresses a row of one of the surface's `x-rows` lists, each named `<observation id>/<list property>`, or `<observation id>` when the observation itself is the list. The row's id, or its exact title when one row has it
|
|
144
|
+
"description": "On a string (or the items of an array of strings) in an action's input: the value addresses a row of one of the surface's `x-rows` lists, each named `<observation id>/<list property>`, or `<observation id>` when the observation itself is the list. The row's id, or its exact title when one row has it.",
|
|
145
145
|
"type": "array",
|
|
146
146
|
"items": {
|
|
147
147
|
"type": "string",
|
|
@@ -154,7 +154,7 @@
|
|
|
154
154
|
"type": "number"
|
|
155
155
|
},
|
|
156
156
|
"x-oui-attachment": {
|
|
157
|
-
"description": "On a string with `format: oui-attachment`: what the action takes once the client resolves the attachment's id
|
|
157
|
+
"description": "On a string with `format: oui-attachment`: what the action takes once the client resolves the attachment's id. `as`: `file` (a `File`, as the user's own file choice produces) or `text` (the file's text, for an input that takes markup or JSON). `mediaTypes`: the types it accepts, `type/*` for a family; any when absent.",
|
|
158
158
|
"type": "object",
|
|
159
159
|
"properties": {
|
|
160
160
|
"as": {
|
package/schemas/oui-config.json
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
3
|
"$id": "https://schemas.closurestudio.ai/oui/v1/oui-config.json",
|
|
4
4
|
"title": "OuiConfigFile",
|
|
5
|
-
"description": "`oui.config.json` at the app's root
|
|
5
|
+
"description": "`oui.config.json` at the app's root: where the app keeps its routes, navigation and output, which design systems and mappings its controls come from, where its API is described, and which of its pages are not yet bound. Paths are relative to the file. It is required and explicit: nothing an app depends on has a default, so a misconfigured app fails here, naming the setting, instead of generating an assistant that can do nothing. A setting the generator does not know is an error.",
|
|
6
6
|
"type": "object",
|
|
7
7
|
"properties": {
|
|
8
8
|
"$schema": {
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
3
|
"$id": "https://schemas.closurestudio.ai/oui/v1/oui-manifest.json",
|
|
4
4
|
"title": "OuiManifest",
|
|
5
|
-
"description": "What the generator emits for each build (`oui-manifest.json
|
|
5
|
+
"description": "What the generator emits for each build (`oui-manifest.json`): every surface, action and observation the build's UI offers. The runtime (`connectBindings`) offers the intersection of the manifest and the handlers mounted right now, so an action the build declares is a tool only while its control, or its room, is on screen. CI regenerates it and diffs it (`oui generate --check`).",
|
|
6
6
|
"type": "object",
|
|
7
7
|
"properties": {
|
|
8
8
|
"version": {
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
3
|
"$id": "https://schemas.closurestudio.ai/oui/v1/room-catalog-data.json",
|
|
4
4
|
"title": "RoomCatalogData",
|
|
5
|
-
"description": "A room catalog as plain data (
|
|
5
|
+
"description": "A room catalog as plain data (tier 3): what a room with its own editing model — a canvas, a chart, a timeline, a player — declares about everything a person can do in it, so the assistant's actions and knowledge are generated from the room's code. Every declaration, none of the functions: a room's package writes it as `agent-catalog.json` (named in `package.json` under `oui.agentCatalog`) so a build-time generator reads the catalog without loading React or the room's code; an app's own catalog is read through the app's Vite config.\n\n- **actions**: its operations, each carried out through the room's own reducer and commands, with a JSON schema for the input;\n- **fields**: its inspector's fields, each with its value's schema, unit, range, its animation where the room has a timeline, and which kinds of thing it applies to;\n- **commands**: its keymap, each command with its keys and what it does;\n- **observations**: what the host reports about the room's state, including the problems it has drawing it.\n\nA room derives each action's input from the schema its reducer already validates with (`z.toJSONSchema`) and re-checks input with the same schema before applying it.",
|
|
6
6
|
"type": "object",
|
|
7
7
|
"properties": {
|
|
8
8
|
"room": {
|
|
@@ -120,7 +120,7 @@
|
|
|
120
120
|
"$ref": "action-effect.json"
|
|
121
121
|
},
|
|
122
122
|
"destructive": {
|
|
123
|
-
"description": "It removes or replaces something the person made; running it needs the person's approval
|
|
123
|
+
"description": "It removes or replaces something the person made; running it needs the person's approval.",
|
|
124
124
|
"type": "boolean"
|
|
125
125
|
}
|
|
126
126
|
},
|
|
@@ -151,7 +151,7 @@
|
|
|
151
151
|
"additionalProperties": false
|
|
152
152
|
},
|
|
153
153
|
"RoomFieldAnimation": {
|
|
154
|
-
"description": "A field's animation, in a room with a timeline. Animation is a capability, not a requirement
|
|
154
|
+
"description": "A field's animation, in a room with a timeline. Animation is a capability, not a requirement.",
|
|
155
155
|
"type": "object",
|
|
156
156
|
"properties": {
|
|
157
157
|
"keyframeable": {
|
|
@@ -404,7 +404,7 @@
|
|
|
404
404
|
"additionalProperties": false
|
|
405
405
|
},
|
|
406
406
|
"RoomResult": {
|
|
407
|
-
"description": "What running a catalog entry or a bound control did: its data, or why it could not be done, in words a person would read. `pending` says the work outlives the call: a job was started and is done only when its completion arrives (an action whose effect is `job` or `transaction`). Every binding's `run` returns what the consumer's callback returned
|
|
407
|
+
"description": "What running a catalog entry or a bound control did: its data, or why it could not be done, in words a person would read. `pending` says the work outlives the call: a job was started and is done only when its completion arrives (an action whose effect is `job` or `transaction`). Every binding's `run` returns what the consumer's callback returned, so a handler's `{ ok, pending: { jobId } }` reaches the runtime.",
|
|
408
408
|
"oneOf": [
|
|
409
409
|
{
|
|
410
410
|
"type": "object",
|
|
@@ -429,7 +429,7 @@
|
|
|
429
429
|
"additionalProperties": false
|
|
430
430
|
},
|
|
431
431
|
"changed": {
|
|
432
|
-
"description": "The rows it changed, added or removed, each as its list's reader reports it now
|
|
432
|
+
"description": "The rows it changed, added or removed, each as its list's reader reports it now: what the assistant checks its edit against, and the rows the page state keeps whole.",
|
|
433
433
|
"type": "array",
|
|
434
434
|
"items": {
|
|
435
435
|
"$ref": "#/$defs/RoomChangedRow"
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
3
|
"$id": "https://schemas.closurestudio.ai/oui/v1/tier2-mapping.json",
|
|
4
4
|
"title": "Tier2Mapping",
|
|
5
|
-
"description": "A tier 2 mapping
|
|
5
|
+
"description": "A tier 2 mapping: how an app binds the controls of a third-party design system it does not own (MUI, Mantine, shadcn/Radix). It is a declaration, not handler code: `oui generate` emits one module per mapping into `<out>/bound/`. Each wrapper accepts `agent`, calls `useAgentBinding` with the app's own callback, returns that callback's result, and renders the third-party component unchanged. The emitted module ships its own control table and is treated exactly like a tier 1 package. On an enforced page, importing a mapped component straight from the third-party package fails the build.",
|
|
6
6
|
"type": "object",
|
|
7
7
|
"properties": {
|
|
8
8
|
"$schema": {
|