@hollis-labs/surface-genui 0.0.0-stage → 0.2.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.
@@ -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