@hollis-labs/surface-genui 0.0.0-stage → 0.1.0
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/README.md +26 -2
- package/contract/LICENSE +21 -0
- package/contract/provenance.json +203 -0
- package/contract/schema/catalog.json +917 -0
- package/contract/schema/contract.schema.json +1078 -0
- package/dist/contract/schema/contract.schema.json +1078 -0
- package/dist/src/contract.d.ts +40 -0
- package/dist/src/contract.js +194 -0
- package/dist/src/controller.d.ts +59 -0
- package/dist/src/controller.js +261 -0
- package/dist/src/decode.d.ts +8 -0
- package/dist/src/decode.js +156 -0
- package/dist/src/generated.d.ts +206 -0
- package/dist/src/generated.js +1 -0
- package/dist/src/index.d.ts +4 -0
- package/dist/src/index.js +3 -0
- package/dist/src/validators.d.ts +33 -0
- package/dist/src/validators.js +6717 -0
- package/package.json +42 -4
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
export class ContractError extends Error {
|
|
2
|
+
constructor(message = "The GenUI message is not supported.") {
|
|
3
|
+
super(message);
|
|
4
|
+
this.name = "ContractError";
|
|
5
|
+
}
|
|
6
|
+
}
|
|
7
|
+
/** Raw-token validation happens before a JavaScript number or duplicate key can lose information. */
|
|
8
|
+
export function decodeJSON(input, maxBytes, maxDepth = 32) {
|
|
9
|
+
let source;
|
|
10
|
+
if (typeof input === "string") {
|
|
11
|
+
if (new TextEncoder().encode(input).length > maxBytes)
|
|
12
|
+
throw new ContractError("The GenUI message is too large.");
|
|
13
|
+
source = input;
|
|
14
|
+
}
|
|
15
|
+
else {
|
|
16
|
+
if (input.byteLength > maxBytes)
|
|
17
|
+
throw new ContractError("The GenUI message is too large.");
|
|
18
|
+
try {
|
|
19
|
+
source = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(input);
|
|
20
|
+
}
|
|
21
|
+
catch {
|
|
22
|
+
throw new ContractError();
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
let pos = 0;
|
|
26
|
+
const fail = () => {
|
|
27
|
+
throw new ContractError();
|
|
28
|
+
};
|
|
29
|
+
const whitespace = () => {
|
|
30
|
+
while (/[\x20\t\r\n]/u.test(source[pos] ?? "\0"))
|
|
31
|
+
pos++;
|
|
32
|
+
};
|
|
33
|
+
function string() {
|
|
34
|
+
const start = pos++;
|
|
35
|
+
let escaped = false;
|
|
36
|
+
while (pos < source.length) {
|
|
37
|
+
const c = source[pos++];
|
|
38
|
+
if (c === '"' && !escaped) {
|
|
39
|
+
let value;
|
|
40
|
+
try {
|
|
41
|
+
value = JSON.parse(source.slice(start, pos));
|
|
42
|
+
}
|
|
43
|
+
catch {
|
|
44
|
+
return fail();
|
|
45
|
+
}
|
|
46
|
+
for (let n = 0; n < value.length; n++) {
|
|
47
|
+
const unit = value.charCodeAt(n);
|
|
48
|
+
if (unit >= 0xd800 && unit <= 0xdbff) {
|
|
49
|
+
const next = value.charCodeAt(++n);
|
|
50
|
+
if (!(next >= 0xdc00 && next <= 0xdfff))
|
|
51
|
+
return fail();
|
|
52
|
+
}
|
|
53
|
+
else if (unit >= 0xdc00 && unit <= 0xdfff)
|
|
54
|
+
return fail();
|
|
55
|
+
}
|
|
56
|
+
if (new TextEncoder().encode(value).length > 16384)
|
|
57
|
+
return fail();
|
|
58
|
+
return value;
|
|
59
|
+
}
|
|
60
|
+
if (escaped)
|
|
61
|
+
escaped = false;
|
|
62
|
+
else if (c === "\\")
|
|
63
|
+
escaped = true;
|
|
64
|
+
}
|
|
65
|
+
return fail();
|
|
66
|
+
}
|
|
67
|
+
function value(depth) {
|
|
68
|
+
if (depth > maxDepth)
|
|
69
|
+
return fail();
|
|
70
|
+
whitespace();
|
|
71
|
+
const c = source[pos];
|
|
72
|
+
if (c === '"')
|
|
73
|
+
return string();
|
|
74
|
+
if (c === "{") {
|
|
75
|
+
pos++;
|
|
76
|
+
whitespace();
|
|
77
|
+
const result = Object.create(null);
|
|
78
|
+
if (source[pos] === "}") {
|
|
79
|
+
pos++;
|
|
80
|
+
return result;
|
|
81
|
+
}
|
|
82
|
+
for (;;) {
|
|
83
|
+
whitespace();
|
|
84
|
+
if (source[pos] !== '"')
|
|
85
|
+
return fail();
|
|
86
|
+
const key = string();
|
|
87
|
+
if (new TextEncoder().encode(key).length > 256 ||
|
|
88
|
+
Object.hasOwn(result, key) ||
|
|
89
|
+
Object.keys(result).length >= 256)
|
|
90
|
+
return fail();
|
|
91
|
+
whitespace();
|
|
92
|
+
if (source[pos++] !== ":")
|
|
93
|
+
return fail();
|
|
94
|
+
result[key] = value(depth + 1);
|
|
95
|
+
whitespace();
|
|
96
|
+
const end = source[pos++];
|
|
97
|
+
if (end === "}")
|
|
98
|
+
return result;
|
|
99
|
+
if (end !== ",")
|
|
100
|
+
return fail();
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
if (c === "[") {
|
|
104
|
+
pos++;
|
|
105
|
+
whitespace();
|
|
106
|
+
const result = [];
|
|
107
|
+
if (source[pos] === "]") {
|
|
108
|
+
pos++;
|
|
109
|
+
return result;
|
|
110
|
+
}
|
|
111
|
+
for (;;) {
|
|
112
|
+
if (result.length >= 256)
|
|
113
|
+
return fail();
|
|
114
|
+
result.push(value(depth + 1));
|
|
115
|
+
whitespace();
|
|
116
|
+
const end = source[pos++];
|
|
117
|
+
if (end === "]")
|
|
118
|
+
return result;
|
|
119
|
+
if (end !== ",")
|
|
120
|
+
return fail();
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
for (const [token, decoded] of [
|
|
124
|
+
["true", true],
|
|
125
|
+
["false", false],
|
|
126
|
+
["null", null],
|
|
127
|
+
]) {
|
|
128
|
+
if (source.startsWith(token, pos)) {
|
|
129
|
+
pos += token.length;
|
|
130
|
+
return decoded;
|
|
131
|
+
}
|
|
132
|
+
}
|
|
133
|
+
const token = /^-?(?:0|[1-9][0-9]*)/u.exec(source.slice(pos))?.[0];
|
|
134
|
+
if (!token || token === "-0")
|
|
135
|
+
return fail();
|
|
136
|
+
pos += token.length;
|
|
137
|
+
const parsed = Number(token);
|
|
138
|
+
if (!Number.isSafeInteger(parsed))
|
|
139
|
+
return fail();
|
|
140
|
+
return parsed;
|
|
141
|
+
}
|
|
142
|
+
const decoded = value(0);
|
|
143
|
+
whitespace();
|
|
144
|
+
if (pos !== source.length)
|
|
145
|
+
return fail();
|
|
146
|
+
return decoded;
|
|
147
|
+
}
|
|
148
|
+
/** Immutable browser snapshots are presentation state, never an authorization proof. */
|
|
149
|
+
export function freeze(value) {
|
|
150
|
+
if (value && typeof value === "object") {
|
|
151
|
+
Object.freeze(value);
|
|
152
|
+
for (const entry of Object.values(value))
|
|
153
|
+
freeze(entry);
|
|
154
|
+
}
|
|
155
|
+
return value;
|
|
156
|
+
}
|
|
@@ -0,0 +1,206 @@
|
|
|
1
|
+
export type Subject = {
|
|
2
|
+
"kind": string;
|
|
3
|
+
"id": string;
|
|
4
|
+
};
|
|
5
|
+
export type Basis = {
|
|
6
|
+
"revision": string;
|
|
7
|
+
"projectionRevision"?: string;
|
|
8
|
+
};
|
|
9
|
+
export type Action = {
|
|
10
|
+
"id": string;
|
|
11
|
+
"subject": Subject;
|
|
12
|
+
"risk"?: "low" | "medium" | "high";
|
|
13
|
+
"basis": Basis;
|
|
14
|
+
"confirmation"?: string;
|
|
15
|
+
};
|
|
16
|
+
export type JSONValue = (null) | (boolean) | (number) | (string) | (Array<JSONValue>) | ({
|
|
17
|
+
[key: string]: JSONValue;
|
|
18
|
+
});
|
|
19
|
+
export type Input = {
|
|
20
|
+
[key: string]: JSONValue;
|
|
21
|
+
};
|
|
22
|
+
export type CallArgs = {
|
|
23
|
+
"genui_action": Action;
|
|
24
|
+
"input": Input;
|
|
25
|
+
};
|
|
26
|
+
export type FunctionCall = {
|
|
27
|
+
"@call": "genui_action";
|
|
28
|
+
"catalogId"?: "urn:hollis-labs:genui:catalog:1";
|
|
29
|
+
"args": CallArgs;
|
|
30
|
+
};
|
|
31
|
+
export type Call = {
|
|
32
|
+
"version": "1.0";
|
|
33
|
+
"callAgentFunction": {
|
|
34
|
+
"surfaceId": string;
|
|
35
|
+
"functionCallId": string;
|
|
36
|
+
"callFunction": FunctionCall;
|
|
37
|
+
};
|
|
38
|
+
};
|
|
39
|
+
export type Confirm = {
|
|
40
|
+
"what": string;
|
|
41
|
+
"scope": Array<string>;
|
|
42
|
+
"ttlMs": number;
|
|
43
|
+
"who"?: string;
|
|
44
|
+
};
|
|
45
|
+
export type RefusedReason = "unsupported-action" | "invalid-arguments" | "denied" | "unregistered-route" | "unresolved-target" | "stale-owner" | "absent-scope" | "cancelled";
|
|
46
|
+
export type Outcome = ({
|
|
47
|
+
"status": "ok";
|
|
48
|
+
"result"?: JSONValue;
|
|
49
|
+
"receipt"?: string;
|
|
50
|
+
}) | ({
|
|
51
|
+
"status": "accepted";
|
|
52
|
+
"handle": string;
|
|
53
|
+
"poll"?: boolean;
|
|
54
|
+
}) | ({
|
|
55
|
+
"status": "needs_confirmation";
|
|
56
|
+
"confirm": Confirm;
|
|
57
|
+
}) | ({
|
|
58
|
+
"status": "refused";
|
|
59
|
+
"reason": RefusedReason;
|
|
60
|
+
}) | ({
|
|
61
|
+
"status": "conflict";
|
|
62
|
+
"recorded": Outcome;
|
|
63
|
+
}) | ({
|
|
64
|
+
"status": "stale";
|
|
65
|
+
"current": Basis;
|
|
66
|
+
}) | ({
|
|
67
|
+
"status": "canceled";
|
|
68
|
+
"cause"?: string;
|
|
69
|
+
}) | ({
|
|
70
|
+
"status": "expired";
|
|
71
|
+
}) | ({
|
|
72
|
+
"status": "superseded";
|
|
73
|
+
"by"?: string;
|
|
74
|
+
}) | ({
|
|
75
|
+
"status": "failed";
|
|
76
|
+
"code": string;
|
|
77
|
+
"message": string;
|
|
78
|
+
"detail"?: JSONValue;
|
|
79
|
+
});
|
|
80
|
+
export type ProtocolError = {
|
|
81
|
+
"code": string;
|
|
82
|
+
"message": string;
|
|
83
|
+
};
|
|
84
|
+
export type FunctionResponse = ({
|
|
85
|
+
"functionCallId": string;
|
|
86
|
+
"value": Outcome;
|
|
87
|
+
}) | ({
|
|
88
|
+
"functionCallId": string;
|
|
89
|
+
"error": ProtocolError;
|
|
90
|
+
});
|
|
91
|
+
export type Response = {
|
|
92
|
+
"version": "1.0";
|
|
93
|
+
"agentFunctionResponse": FunctionResponse;
|
|
94
|
+
};
|
|
95
|
+
export type Choice = {
|
|
96
|
+
"label": string;
|
|
97
|
+
"callFunction": FunctionCall;
|
|
98
|
+
};
|
|
99
|
+
export type ViewState = "ready" | "loading" | "empty" | "error" | "stale" | "conflict" | "expired";
|
|
100
|
+
export type Change = {
|
|
101
|
+
"label": string;
|
|
102
|
+
"before": string;
|
|
103
|
+
"after": string;
|
|
104
|
+
};
|
|
105
|
+
export type ApprovalProps = {
|
|
106
|
+
"title": string;
|
|
107
|
+
"summary"?: string;
|
|
108
|
+
"changes": Array<Change>;
|
|
109
|
+
"choices": Array<Choice>;
|
|
110
|
+
"state": ViewState;
|
|
111
|
+
};
|
|
112
|
+
export type FormField = {
|
|
113
|
+
"key": string;
|
|
114
|
+
"label": string;
|
|
115
|
+
"type": "text" | "textarea" | "checkbox" | "integer";
|
|
116
|
+
"required": boolean;
|
|
117
|
+
"help"?: string;
|
|
118
|
+
"min"?: number;
|
|
119
|
+
"max"?: number;
|
|
120
|
+
"maxLength"?: number;
|
|
121
|
+
};
|
|
122
|
+
export type FormProps = {
|
|
123
|
+
"title": string;
|
|
124
|
+
"fields": Array<FormField>;
|
|
125
|
+
"submit": Choice;
|
|
126
|
+
"state": ViewState;
|
|
127
|
+
};
|
|
128
|
+
export type ListItem = {
|
|
129
|
+
"id": string;
|
|
130
|
+
"title": string;
|
|
131
|
+
"summary"?: string;
|
|
132
|
+
};
|
|
133
|
+
export type ListDetailProps = {
|
|
134
|
+
"title": string;
|
|
135
|
+
"items": Array<ListItem>;
|
|
136
|
+
"selectedId"?: string;
|
|
137
|
+
"detail"?: {
|
|
138
|
+
"title": string;
|
|
139
|
+
"body": string;
|
|
140
|
+
};
|
|
141
|
+
"state": ViewState;
|
|
142
|
+
};
|
|
143
|
+
export type Root = ({
|
|
144
|
+
"id": "root";
|
|
145
|
+
"component": "GenuiApproval";
|
|
146
|
+
"props": ApprovalProps;
|
|
147
|
+
}) | ({
|
|
148
|
+
"id": "root";
|
|
149
|
+
"component": "GenuiForm";
|
|
150
|
+
"props": FormProps;
|
|
151
|
+
}) | ({
|
|
152
|
+
"id": "root";
|
|
153
|
+
"component": "GenuiListDetail";
|
|
154
|
+
"props": ListDetailProps;
|
|
155
|
+
});
|
|
156
|
+
export type Pattern = {
|
|
157
|
+
"id": "approval" | "form" | "list_detail";
|
|
158
|
+
"version": "1.0.0";
|
|
159
|
+
};
|
|
160
|
+
export type Metadata = {
|
|
161
|
+
"extensions": {
|
|
162
|
+
"genui_surface": {
|
|
163
|
+
"contract_version": "1";
|
|
164
|
+
};
|
|
165
|
+
"genui_pattern": Pattern;
|
|
166
|
+
};
|
|
167
|
+
};
|
|
168
|
+
export type DataModel = {
|
|
169
|
+
"draft"?: Input;
|
|
170
|
+
};
|
|
171
|
+
export type CreateSurface = {
|
|
172
|
+
"surfaceId": string;
|
|
173
|
+
"catalogId": "urn:hollis-labs:genui:catalog:1";
|
|
174
|
+
"components": Array<Root>;
|
|
175
|
+
"dataModel": DataModel;
|
|
176
|
+
"metadata": Metadata;
|
|
177
|
+
};
|
|
178
|
+
export type SurfaceMessage = {
|
|
179
|
+
"version": "1.0";
|
|
180
|
+
"createSurface": CreateSurface;
|
|
181
|
+
};
|
|
182
|
+
export type Envelope = {
|
|
183
|
+
"v": 1;
|
|
184
|
+
"id": string;
|
|
185
|
+
"type": "genui.declarative-surface";
|
|
186
|
+
"typeVersion": "1.0.0";
|
|
187
|
+
"title"?: string;
|
|
188
|
+
"context"?: string;
|
|
189
|
+
"presentation"?: "inline" | "modal" | "drawer" | "fullscreen";
|
|
190
|
+
"data": SurfaceMessage;
|
|
191
|
+
};
|
|
192
|
+
export type UnknownOutcome = {
|
|
193
|
+
"status": string;
|
|
194
|
+
[key: string]: JSONValue;
|
|
195
|
+
};
|
|
196
|
+
export type ReceiverFunctionResponse = ({
|
|
197
|
+
"functionCallId": string;
|
|
198
|
+
"value": (Outcome) | (UnknownOutcome);
|
|
199
|
+
}) | ({
|
|
200
|
+
"functionCallId": string;
|
|
201
|
+
"error": ProtocolError;
|
|
202
|
+
});
|
|
203
|
+
export type ReceiverResponse = {
|
|
204
|
+
"version": "1.0";
|
|
205
|
+
"agentFunctionResponse": ReceiverFunctionResponse;
|
|
206
|
+
};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
export { CATALOG_ID, draftErrors, isTerminal, parseCall, parseEnvelope, parseOutcome, parseRecovery, parseResponse, type ResponseObservation, SURFACE_KIND, SURFACE_VERSION, serializeCall, } from "./contract.ts";
|
|
2
|
+
export { type ConfirmationRequest, GenuiController, type GenuiSnapshot, type GenuiTransport, type Phase, type RecoverRequest, type Recovery, } from "./controller.ts";
|
|
3
|
+
export { ContractError } from "./decode.ts";
|
|
4
|
+
export type * from "./generated.ts";
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
export { CATALOG_ID, draftErrors, isTerminal, parseCall, parseEnvelope, parseOutcome, parseRecovery, parseResponse, SURFACE_KIND, SURFACE_VERSION, serializeCall, } from "./contract.js";
|
|
2
|
+
export { GenuiController, } from "./controller.js";
|
|
3
|
+
export { ContractError } from "./decode.js";
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
// Generated from the canonical schema. Do not edit.
|
|
2
|
+
export declare function Subject(value: unknown): boolean
|
|
3
|
+
export declare function Basis(value: unknown): boolean
|
|
4
|
+
export declare function Action(value: unknown): boolean
|
|
5
|
+
export declare function JSONValue(value: unknown): boolean
|
|
6
|
+
export declare function Input(value: unknown): boolean
|
|
7
|
+
export declare function CallArgs(value: unknown): boolean
|
|
8
|
+
export declare function FunctionCall(value: unknown): boolean
|
|
9
|
+
export declare function Call(value: unknown): boolean
|
|
10
|
+
export declare function Confirm(value: unknown): boolean
|
|
11
|
+
export declare function RefusedReason(value: unknown): boolean
|
|
12
|
+
export declare function Outcome(value: unknown): boolean
|
|
13
|
+
export declare function ProtocolError(value: unknown): boolean
|
|
14
|
+
export declare function FunctionResponse(value: unknown): boolean
|
|
15
|
+
export declare function Response(value: unknown): boolean
|
|
16
|
+
export declare function Choice(value: unknown): boolean
|
|
17
|
+
export declare function ViewState(value: unknown): boolean
|
|
18
|
+
export declare function Change(value: unknown): boolean
|
|
19
|
+
export declare function ApprovalProps(value: unknown): boolean
|
|
20
|
+
export declare function FormField(value: unknown): boolean
|
|
21
|
+
export declare function FormProps(value: unknown): boolean
|
|
22
|
+
export declare function ListItem(value: unknown): boolean
|
|
23
|
+
export declare function ListDetailProps(value: unknown): boolean
|
|
24
|
+
export declare function Root(value: unknown): boolean
|
|
25
|
+
export declare function Pattern(value: unknown): boolean
|
|
26
|
+
export declare function Metadata(value: unknown): boolean
|
|
27
|
+
export declare function DataModel(value: unknown): boolean
|
|
28
|
+
export declare function CreateSurface(value: unknown): boolean
|
|
29
|
+
export declare function SurfaceMessage(value: unknown): boolean
|
|
30
|
+
export declare function Envelope(value: unknown): boolean
|
|
31
|
+
export declare function UnknownOutcome(value: unknown): boolean
|
|
32
|
+
export declare function ReceiverFunctionResponse(value: unknown): boolean
|
|
33
|
+
export declare function ReceiverResponse(value: unknown): boolean
|