ezship 0.1.10 → 0.1.12

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,61 @@
1
+ import type { InstanceDiscovery } from "./types.d.mts";
2
+ export type Connection = InstanceDiscovery & {
3
+ token: string;
4
+ builder: string;
5
+ email: string;
6
+ site?: string;
7
+ };
8
+ export type SavedConnections = {
9
+ version: number;
10
+ primary?: string;
11
+ logins: Record<string, Connection>;
12
+ };
13
+ export const CONNECTION_VERSION: 1;
14
+ export const DISCOVERY_PATH: "/.well-known/ezship";
15
+ /** A bare Instance name means `https://<name>.<MANAGED_DOMAIN>`. */
16
+ export const MANAGED_DOMAIN: "ezship.dev";
17
+ /** ADR 0072: the contract's compatibility number, raised only by a change an older client cannot survive. */
18
+ export const CONTRACT: number;
19
+ /** ADR 0072: the oldest client contract this release serves; older clients are answered 426. */
20
+ export const OLDEST_CONTRACT: number;
21
+ export const CONTRACT_HEADER: "ez-contract";
22
+ export function localOrigin(input: string): boolean;
23
+ export function normalizeOrigin(input: string): string;
24
+ export function instanceAddress(input: string): string;
25
+ /** The Studio's path for an Instance's app origin: `/i/<name>` for managed names, else `/i/<authority>`. */
26
+ export function studioPath(app: string): string;
27
+ export function discoverInstance(
28
+ input: string,
29
+ send?: typeof fetch,
30
+ signal?: AbortSignal,
31
+ ): Promise<InstanceDiscovery>;
32
+ export function instanceKey(value: Pick<Connection, "app" | "uid">): string;
33
+ export function connectionKey(value: Pick<Connection, "app" | "uid" | "builder">): string;
34
+ export function emptyConnections(): SavedConnections;
35
+ export function readConnections(raw: unknown): SavedConnections;
36
+ export function saveConnection(saved: SavedConnections, connection: Connection): SavedConnections;
37
+ export function findConnection(
38
+ saved: SavedConnections,
39
+ target?: string,
40
+ account?: string,
41
+ ): Connection;
42
+ export function makePrimary(
43
+ saved: SavedConnections,
44
+ target: string,
45
+ account?: string,
46
+ ): SavedConnections;
47
+ export function forgetConnection(saved: SavedConnections, connection: Connection): SavedConnections;
48
+ export function connectionRequest(
49
+ connection: Pick<Connection, "api" | "instance" | "token">,
50
+ path: string,
51
+ init?: RequestInit,
52
+ send?: typeof fetch,
53
+ ): Promise<Response>;
54
+ export function contractNote(response: Pick<Response, "headers">, client?: number): string;
55
+ export function usesWorkingCopy(words: string[]): boolean;
56
+ export function extractTarget(words: string[]): {
57
+ args: string[];
58
+ instance?: string;
59
+ site?: string;
60
+ account?: string;
61
+ };
@@ -0,0 +1,312 @@
1
+ // Instance connections shared by the terminal and Studio (ADR 0026). Persistence stays in each client.
2
+ /** @type {typeof import("./connections.d.mts").CONNECTION_VERSION} */
3
+ export const CONNECTION_VERSION = 1;
4
+ /** @type {typeof import("./connections.d.mts").DISCOVERY_PATH} */
5
+ export const DISCOVERY_PATH = "/.well-known/ezship";
6
+ /** A bare Instance name means `https://<name>.<MANAGED_DOMAIN>`. */
7
+ export const MANAGED_DOMAIN = "ezship.dev";
8
+ /**
9
+ * The contract's compatibility number (ADR 0072): raised only by a change an older client cannot survive.
10
+ * @type {typeof import("./connections.d.mts").CONTRACT}
11
+ */
12
+ export const CONTRACT = 1;
13
+ /**
14
+ * The oldest client contract this release still serves; a Host answers an older one 426.
15
+ * @type {typeof import("./connections.d.mts").OLDEST_CONTRACT}
16
+ */
17
+ export const OLDEST_CONTRACT = 1;
18
+ /**
19
+ * Sent by every client request and on every API response, each side's own `CONTRACT`.
20
+ * @type {typeof import("./connections.d.mts").CONTRACT_HEADER}
21
+ */
22
+ export const CONTRACT_HEADER = "ez-contract";
23
+
24
+ /** @type {typeof import("./connections.d.mts").localOrigin} */
25
+ export function localOrigin(input) {
26
+ const { hostname } = new URL(input);
27
+ return (
28
+ hostname === "localhost" ||
29
+ hostname.endsWith(".localhost") ||
30
+ hostname === "127.0.0.1" ||
31
+ hostname === "[::1]"
32
+ );
33
+ }
34
+
35
+ /** @type {typeof import("./connections.d.mts").normalizeOrigin} */
36
+ export function normalizeOrigin(input) {
37
+ const url = new URL(input);
38
+ if (url.username || url.password || url.search || url.hash || url.pathname !== "/")
39
+ throw new Error("Use an Instance origin without a path, query or credentials.");
40
+ if (url.protocol !== "https:" && !(url.protocol === "http:" && localOrigin(url.origin)))
41
+ throw new Error("Use HTTPS, or HTTP for a local development Instance.");
42
+ return url.origin;
43
+ }
44
+
45
+ /** @type {typeof import("./connections.d.mts").instanceAddress} */
46
+ export function instanceAddress(input) {
47
+ if (!input) throw new Error("Choose an Instance: ez login <instance or URL>.");
48
+ return normalizeOrigin(input.includes("://") ? input : `https://${input}.${MANAGED_DOMAIN}`);
49
+ }
50
+
51
+ /**
52
+ * The Studio's path for an Instance's app origin (ADR 0032): managed names stay short, other origins keep
53
+ * their authority so links remain shareable. Invite emails (ADR 0055) and the Studio both use it.
54
+ * @type {typeof import("./connections.d.mts").studioPath}
55
+ */
56
+ export function studioPath(app) {
57
+ const url = new URL(normalizeOrigin(app));
58
+ const managed =
59
+ url.protocol === "https:" && !url.port && url.hostname.endsWith(`.${MANAGED_DOMAIN}`)
60
+ ? /^[a-z0-9-]+$/.exec(url.hostname.slice(0, -MANAGED_DOMAIN.length - 1))?.[0]
61
+ : undefined;
62
+ const address =
63
+ managed ??
64
+ (url.protocol === "http:"
65
+ ? `http:${url.host}`
66
+ : url.host.includes(".") || url.host.includes(":")
67
+ ? url.host
68
+ : `https:${url.host}`);
69
+ return `/i/${encodeURI(address)}`;
70
+ }
71
+
72
+ /**
73
+ * Discovery never sends a credential and never follows a redirect.
74
+ * @type {typeof import("./connections.d.mts").discoverInstance}
75
+ */
76
+ export async function discoverInstance(input, send = fetch, signal) {
77
+ const app = instanceAddress(input);
78
+ const response = await send(app + DISCOVERY_PATH, {
79
+ credentials: "omit",
80
+ redirect: "error",
81
+ signal,
82
+ });
83
+ if (!response.ok) throw new Error(`Cannot connect to this Instance (HTTP ${response.status}).`);
84
+ const value = await response.json();
85
+ if (value?.version !== CONNECTION_VERSION)
86
+ throw new Error("This Instance needs a compatible ezship version.");
87
+ if (
88
+ typeof value.uid !== "string" ||
89
+ !/^[A-Za-z0-9_-]{16,80}$/.test(value.uid) ||
90
+ typeof value.instance !== "string" ||
91
+ !/^[a-z][a-z0-9]{0,31}$/.test(value.instance) ||
92
+ typeof value.name !== "string" ||
93
+ value.app !== app ||
94
+ typeof value.api !== "string"
95
+ )
96
+ throw new Error("Invalid Instance connection information.");
97
+ const api = normalizeOrigin(value.api);
98
+ if (api === app || (!localOrigin(app) && localOrigin(api)))
99
+ throw new Error("The Instance must have a separate, valid Builder API origin.");
100
+ return {
101
+ version: CONNECTION_VERSION,
102
+ uid: value.uid,
103
+ instance: value.instance,
104
+ name: value.name,
105
+ app,
106
+ api,
107
+ };
108
+ }
109
+
110
+ /** @type {typeof import("./connections.d.mts").instanceKey} */
111
+ export const instanceKey = (value) => JSON.stringify([value.app, value.uid]);
112
+ /** @type {typeof import("./connections.d.mts").connectionKey} */
113
+ export const connectionKey = (value) => JSON.stringify([value.app, value.uid, value.builder]);
114
+ /** @type {typeof import("./connections.d.mts").emptyConnections} */
115
+ export const emptyConnections = () => ({ version: CONNECTION_VERSION, logins: {} });
116
+
117
+ /** @type {typeof import("./connections.d.mts").readConnections} */
118
+ export function readConnections(raw) {
119
+ if (!raw) return emptyConnections();
120
+ let value;
121
+ try {
122
+ value = typeof raw === "string" ? JSON.parse(raw) : raw;
123
+ } catch {
124
+ return emptyConnections();
125
+ }
126
+ if (value?.version !== CONNECTION_VERSION || !value.logins || typeof value.logins !== "object")
127
+ return emptyConnections();
128
+ /** @type {import("./connections.d.mts").SavedConnections["logins"]} */
129
+ const logins = {};
130
+ for (const [key, c] of Object.entries(value.logins)) {
131
+ try {
132
+ if (
133
+ !c ||
134
+ typeof c.uid !== "string" ||
135
+ typeof c.instance !== "string" ||
136
+ typeof c.builder !== "string" ||
137
+ typeof c.email !== "string" ||
138
+ typeof c.token !== "string" ||
139
+ normalizeOrigin(c.app) !== c.app ||
140
+ normalizeOrigin(c.api) !== c.api ||
141
+ c.api === c.app ||
142
+ connectionKey(c) !== key
143
+ )
144
+ continue;
145
+ logins[key] = c;
146
+ } catch {
147
+ /* Preserve invalid/legacy data at its old persistence key; never adopt its credentials. */
148
+ }
149
+ }
150
+ return {
151
+ version: CONNECTION_VERSION,
152
+ logins,
153
+ ...(typeof value.primary === "string" && logins[value.primary]
154
+ ? { primary: value.primary }
155
+ : {}),
156
+ };
157
+ }
158
+
159
+ /** @type {typeof import("./connections.d.mts").saveConnection} */
160
+ export function saveConnection(saved, connection) {
161
+ const key = connectionKey(connection);
162
+ return {
163
+ ...saved,
164
+ version: CONNECTION_VERSION,
165
+ logins: { ...saved.logins, [key]: connection },
166
+ primary: saved.primary || key,
167
+ };
168
+ }
169
+
170
+ /** @type {typeof import("./connections.d.mts").findConnection} */
171
+ export function findConnection(saved, target, account) {
172
+ if (!target) {
173
+ const primary = saved.primary && saved.logins[saved.primary];
174
+ if (primary && (!account || primary.email === account)) return primary;
175
+ throw new Error("Choose a primary Instance with ez switch <instance>, or pass --instance.");
176
+ }
177
+ // Login normalizes a bare name to its app origin, so a slug must match the saved
178
+ // origin too: the Instance id itself may differ (`acme-labs` logs into the
179
+ // `acmelabs` Instance at https://acme-labs.ezship.dev).
180
+ let app = null;
181
+ try {
182
+ app = instanceAddress(target);
183
+ } catch {
184
+ /* Not a name or URL: compare the raw target only. */
185
+ }
186
+ const matches = Object.entries(saved.logins).filter(
187
+ ([key, c]) =>
188
+ (key === target ||
189
+ c.instance === target ||
190
+ c.app === target.replace(/\/$/, "") ||
191
+ (app !== null && c.app === app) ||
192
+ instanceKey(c) === target) &&
193
+ (!account || c.email === account),
194
+ );
195
+ if (matches.length === 1) return matches[0][1];
196
+ if (matches.length > 1)
197
+ throw new Error(
198
+ `Several saved accounts match ${target}. Select its address and --account email.`,
199
+ );
200
+ throw new Error(`No saved connection for ${target}. Run ez login ${target}.`);
201
+ }
202
+
203
+ /** @type {typeof import("./connections.d.mts").makePrimary} */
204
+ export function makePrimary(saved, target, account) {
205
+ return { ...saved, primary: connectionKey(findConnection(saved, target, account)) };
206
+ }
207
+
208
+ /** @type {typeof import("./connections.d.mts").forgetConnection} */
209
+ export function forgetConnection(saved, connection) {
210
+ const key = connectionKey(connection);
211
+ const { [key]: _removed, ...logins } = saved.logins;
212
+ return {
213
+ version: CONNECTION_VERSION,
214
+ logins,
215
+ ...(saved.primary && saved.primary !== key ? { primary: saved.primary } : {}),
216
+ };
217
+ }
218
+
219
+ /**
220
+ * Every request is permanently bound to this credential and Instance, including after a primary switch.
221
+ * @type {typeof import("./connections.d.mts").connectionRequest}
222
+ */
223
+ export async function connectionRequest(connection, path, init = {}, send = fetch) {
224
+ if (!path.startsWith("/") || path.startsWith("//") || path.includes("\\"))
225
+ throw new Error("Expected an Instance-relative API path.");
226
+ const target = new URL(connection.api + path);
227
+ const scope = /^\/api\/i\/([^/]+)(?:\/|$)/.exec(target.pathname);
228
+ if (
229
+ target.origin !== connection.api ||
230
+ (scope && decodeURIComponent(scope[1]) !== connection.instance)
231
+ )
232
+ throw new Error("The request belongs to another Instance.");
233
+ const headers = new Headers(init.headers);
234
+ headers.delete("cookie");
235
+ headers.set("authorization", `Bearer ${connection.token}`);
236
+ headers.set(CONTRACT_HEADER, String(CONTRACT));
237
+ return send(target.href, { ...init, headers, credentials: "omit", redirect: "error" });
238
+ }
239
+
240
+ /**
241
+ * For a failed request: a note when the Host speaks an older contract than this client, whose command it
242
+ * may not have yet; otherwise empty.
243
+ * @type {typeof import("./connections.d.mts").contractNote}
244
+ */
245
+ export function contractNote(response, client = CONTRACT) {
246
+ const host = Number(response.headers.get(CONTRACT_HEADER));
247
+ return Number.isInteger(host) && host > 0 && host < client
248
+ ? ` This Host speaks contract ${host} and this client ${client}; the Host may predate this command.`
249
+ : "";
250
+ }
251
+
252
+ /**
253
+ * Commands needing the target's own Working Copy; remote-only commands can select another Instance.
254
+ * @type {typeof import("./connections.d.mts").usesWorkingCopy}
255
+ */
256
+ export function usesWorkingCopy(words) {
257
+ const [command, ...rest] = words[0] === "global" ? words.slice(1) : words;
258
+ return (
259
+ [
260
+ "status",
261
+ "pull",
262
+ "push",
263
+ "check",
264
+ "format",
265
+ "preview",
266
+ "init",
267
+ "clone",
268
+ "dev",
269
+ "ls",
270
+ "cat",
271
+ "put",
272
+ "edit",
273
+ "delete",
274
+ "rm",
275
+ "mv",
276
+ ].includes(command) && !(command === "preview" && ["ls", "delete", "rm"].includes(rest[0]))
277
+ );
278
+ }
279
+
280
+ /** @type {typeof import("./connections.d.mts").extractTarget} */
281
+ export function extractTarget(words) {
282
+ const args = [];
283
+ /** @type {{instance?: string, site?: string, account?: string}} */
284
+ const target = {};
285
+ /** @type {Record<string, keyof typeof target>} */
286
+ const fields = { "--instance": "instance", "--site": "site", "--account": "account" };
287
+ for (let i = 0; i < words.length; i++) {
288
+ // `audit --site` is a result filter, not a Working Copy target.
289
+ if (words[0] === "audit" && words[i] === "--site") {
290
+ args.push(words[i], words[++i]);
291
+ continue;
292
+ }
293
+ const field = fields[words[i]];
294
+ if (!field) {
295
+ args.push(words[i]);
296
+ continue;
297
+ }
298
+ if (!words[i + 1] || words[i + 1].startsWith("--"))
299
+ throw new Error(`${words[i]} requires a value.`);
300
+ if (target[field] && target[field] !== words[i + 1])
301
+ throw new Error(`Conflicting ${words[i]} values.`);
302
+ target[field] = words[++i];
303
+ }
304
+ if (target.site?.includes("/")) {
305
+ const [instance, site, extra] = target.site.split("/");
306
+ if (!instance || !site || extra || (target.instance && target.instance !== instance))
307
+ throw new Error("The explicit Instance and Site targets disagree.");
308
+ target.instance = instance;
309
+ target.site = site;
310
+ }
311
+ return { args, ...target };
312
+ }
package/cron.d.mts ADDED
@@ -0,0 +1,17 @@
1
+ /** A parsed five-field UTC cron (docs/adr/0076). Day of week 7 is folded into 0 (Sunday). */
2
+ export type Cron = {
3
+ minute: Set<number>;
4
+ hour: Set<number>;
5
+ dom: Set<number>;
6
+ month: Set<number>;
7
+ dow: Set<number>;
8
+ /** Whether the field was written with `*`: a starred day field does not widen the other (the cron OR rule). */
9
+ domStar: boolean;
10
+ dowStar: boolean;
11
+ };
12
+ /** The parsed cron, or why the text is not one. */
13
+ export function parseCron(text: string): Cron | string;
14
+ /** The first matching minute strictly after `after` (ms since the epoch, UTC). */
15
+ export function nextDue(cron: Cron, after: number): number;
16
+ /** The last matching minute at or before `atOrBefore`, within a year; null when there is none. */
17
+ export function latestDue(cron: Cron, atOrBefore: number): number | null;
package/cron.mjs ADDED
@@ -0,0 +1,124 @@
1
+ // Five-field UTC cron for the Global Workspace's schedules.json (docs/adr/0076, 0136). Zero dependencies: the
2
+ // contract checks a file with it and the Host's scheduler computes due times with it, so both agree on every
3
+ // minute.
4
+
5
+ const MONTHS = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"];
6
+ const DAYS = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"];
7
+ /** @type {{ label: string; min: number; max: number; names?: string[]; base?: number }[]} */
8
+ const FIELDS = [
9
+ { label: "minute", min: 0, max: 59 },
10
+ { label: "hour", min: 0, max: 23 },
11
+ { label: "day of month", min: 1, max: 31 },
12
+ { label: "month", min: 1, max: 12, names: MONTHS, base: 1 },
13
+ { label: "day of week", min: 0, max: 7, names: DAYS, base: 0 },
14
+ ];
15
+ const MAX_DAYS_IN_MONTH = [31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
16
+ const MINUTE = 60_000;
17
+ const DAY = 24 * 60 * MINUTE;
18
+ /** How far `nextDue` searches: long enough for the next leap day. */
19
+ const FORWARD_DAYS = 5 * 366;
20
+ /** How far `latestDue` searches: a missed run older than a year is not caught up. */
21
+ const BACKWARD_DAYS = 366;
22
+
23
+ /** @param {string} text @param {(typeof FIELDS)[number]} field */
24
+ function value(text, field) {
25
+ const named = field.names?.indexOf(text.toLowerCase()) ?? -1;
26
+ if (named >= 0) return named + (field.base ?? 0);
27
+ return /^\d{1,2}$/.test(text) ? Number(text) : NaN;
28
+ }
29
+
30
+ /** @param {string} text @param {(typeof FIELDS)[number]} field @returns {Set<number> | string} */
31
+ function parseField(text, field) {
32
+ const out = new Set();
33
+ for (const part of text.split(",")) {
34
+ const m = /^(\*|[a-z0-9]+(?:-[a-z0-9]+)?)(?:\/(\d{1,2}))?$/i.exec(part);
35
+ if (!m) return `"${part}" is not a cron ${field.label}.`;
36
+ const step = m[2] === undefined ? 1 : Number(m[2]);
37
+ if (step < 1) return `"${part}": a step is at least 1.`;
38
+ const bounds =
39
+ m[1] === "*" ? [field.min, field.max] : m[1].split("-").map((p) => value(p, field));
40
+ const lo = bounds[0];
41
+ const hi = bounds[1] ?? (m[2] === undefined ? lo : field.max);
42
+ if (!(lo >= field.min && hi <= field.max && lo <= hi))
43
+ return `"${part}": a ${field.label} is ${field.min}-${field.max}.`;
44
+ for (let v = lo; v <= hi; v += step) out.add(v);
45
+ }
46
+ return out;
47
+ }
48
+
49
+ /** @type {typeof import("./cron.d.mts").parseCron} */
50
+ export function parseCron(text) {
51
+ const parts = typeof text === "string" ? text.trim().split(/\s+/) : [];
52
+ if (parts.length !== 5)
53
+ return "A cron has five fields: minute hour day-of-month month day-of-week, in UTC.";
54
+ /** @type {Set<number>[]} */
55
+ const sets = [];
56
+ for (let i = 0; i < 5; i++) {
57
+ const set = parseField(parts[i], FIELDS[i]);
58
+ if (typeof set === "string") return set;
59
+ sets.push(set);
60
+ }
61
+ const [minute, hour, dom, month, dow] = sets;
62
+ if (dow.delete(7)) dow.add(0);
63
+ const cron = {
64
+ minute,
65
+ hour,
66
+ dom,
67
+ month,
68
+ dow,
69
+ domStar: parts[2].startsWith("*"),
70
+ dowStar: parts[4].startsWith("*"),
71
+ };
72
+ // Only the day of month restricts the days: some chosen month must have one of them.
73
+ if (
74
+ cron.dowStar &&
75
+ !cron.domStar &&
76
+ ![...month].some((m) => [...dom].some((d) => d <= MAX_DAYS_IN_MONTH[m - 1]))
77
+ )
78
+ return "This cron never fires: no chosen month has that day.";
79
+ return cron;
80
+ }
81
+
82
+ /** Whether the UTC day starting at `day` matches; day-of-month and day-of-week are ORed when both are restricted. */
83
+ function dayMatches(/** @type {import("./cron.d.mts").Cron} */ cron, /** @type {number} */ day) {
84
+ const d = new Date(day);
85
+ if (!cron.month.has(d.getUTCMonth() + 1)) return false;
86
+ const domOk = cron.dom.has(d.getUTCDate());
87
+ const dowOk = cron.dow.has(d.getUTCDay());
88
+ return cron.domStar || cron.dowStar ? domOk && dowOk : domOk || dowOk;
89
+ }
90
+
91
+ /** @param {Set<number>} set */
92
+ const ascending = (set) => [...set].sort((a, b) => a - b);
93
+
94
+ /** @type {typeof import("./cron.d.mts").nextDue} */
95
+ export function nextDue(cron, after) {
96
+ const from = Math.floor(after / MINUTE) * MINUTE + MINUTE;
97
+ const hours = ascending(cron.hour);
98
+ const minutes = ascending(cron.minute);
99
+ for (let day = Math.floor(from / DAY) * DAY, i = 0; i < FORWARD_DAYS; i++, day += DAY) {
100
+ if (!dayMatches(cron, day)) continue;
101
+ for (const h of hours)
102
+ for (const m of minutes) {
103
+ const at = day + h * 60 * MINUTE + m * MINUTE;
104
+ if (at >= from) return at;
105
+ }
106
+ }
107
+ throw new Error("This cron never fires.");
108
+ }
109
+
110
+ /** @type {typeof import("./cron.d.mts").latestDue} */
111
+ export function latestDue(cron, atOrBefore) {
112
+ const until = Math.floor(atOrBefore / MINUTE) * MINUTE;
113
+ const hours = ascending(cron.hour).reverse();
114
+ const minutes = ascending(cron.minute).reverse();
115
+ for (let day = Math.floor(until / DAY) * DAY, i = 0; i <= BACKWARD_DAYS; i++, day -= DAY) {
116
+ if (!dayMatches(cron, day)) continue;
117
+ for (const h of hours)
118
+ for (const m of minutes) {
119
+ const at = day + h * 60 * MINUTE + m * MINUTE;
120
+ if (at <= until) return at;
121
+ }
122
+ }
123
+ return null;
124
+ }
@@ -0,0 +1,26 @@
1
+ // The Document element tree (docs/adr/0105): what a template stage may return and the renderer may draw.
2
+ import type { DocumentNode } from "./types.d.mts";
3
+
4
+ /** The element types, the props each accepts, and the children it may hold. */
5
+ export const DOCUMENT_ELEMENTS: Readonly<
6
+ Record<string, { props: readonly string[]; children: readonly string[]; text: boolean }>
7
+ >;
8
+ /** The style properties a Document may set; values are numbers or short strings. */
9
+ export const DOCUMENT_STYLES: ReadonlySet<string>;
10
+ /** The PDF standard font families; `fontWeight` and `fontStyle` pick their faces. */
11
+ export const DOCUMENT_FONTS: readonly ["Helvetica", "Times-Roman", "Courier"];
12
+ export const MAX_DOCUMENT_TREE_BYTES: 4000000;
13
+ export const MAX_DOCUMENT_NODES: 100000;
14
+ export const MAX_DOCUMENT_PAGES: 200;
15
+ export const MAX_DOCUMENT_BYTES: 20000000;
16
+ /** An image reference in a tree: an Instance Asset by name or an Attachment by id. */
17
+ export type ImageRef = { asset: string } | { attachment: string };
18
+ /** The key a reference's bytes travel under, from the Host to the renderer. */
19
+ export function imageKey(ref: ImageRef): string;
20
+ /**
21
+ * A checked tree: a Document of Pages whose elements, props and styles are all on the allow-lists, with the
22
+ * images it names. A refusal names the first problem.
23
+ */
24
+ export function checkDocumentTree(
25
+ tree: unknown,
26
+ ): { ok: true; tree: DocumentNode; images: ImageRef[] } | { ok: false; error: string };