iterate 0.2.7 → 0.4.0

package/dist/oauth-scopes.d.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+/** The platform's OAuth scopes — what an app may ask for and what a consent grants:
+ *   - `iterate`             — reach the projects the person grants (every app; implied, always granted)
+ *   - `account`             — manage the person's sessions and personal access tokens
+ *   - `organizations:write` — the person's organizations: list every one they belong to, create new ones
+ *  Consent is task-based (the shape Cloudflare's own OAuth consent took in August 2026: a client
+ *  requests a set, the person may deselect the optional ones, the token carries what was granted):
+ *  `iterate` is required, every other requested scope is optional on the consent page, and an app
+ *  reads the granted set from `session.info().scopes` rather than assuming its request. */
+export declare const OAuthScope: z.ZodEnum<{
+    iterate: "iterate";
+    account: "account";
+    "organizations:write": "organizations:write";
+}>;
+export type OAuthScope = z.infer<typeof OAuthScope>;
+export declare const OAuthScopes: z.ZodPipe<z.ZodArray<z.ZodEnum<{
+    iterate: "iterate";
+    account: "account";
+    "organizations:write": "organizations:write";
+}>>, z.ZodTransform<string[], ("iterate" | "account" | "organizations:write")[]>>;
+/** A requested scope as the consent page shows it: its name, what it means to the person, and
+ *  whether they may untick it (`iterate` never). */
+export interface ConsentScope {
+    name: OAuthScope;
+    title: string;
+    note: string;
+    required: boolean;
+}
+/** What each scope means to the person — the consent page's copy, sent with `consent.describe` so
+ *  the page renders what it is given: a scope added to `OAuthScope` is described here or it does
+ *  not compile. */
+export declare const OAuthScopeDescriptions: Record<OAuthScope, Omit<ConsentScope, "name">>;

package/dist/oauth-scopes.mjs

@@ -0,0 +1,40 @@
+import { z } from "zod";
+//#region src/oauth-scopes.ts
+/** The platform's OAuth scopes — what an app may ask for and what a consent grants:
+*   - `iterate`             — reach the projects the person grants (every app; implied, always granted)
+*   - `account`             — manage the person's sessions and personal access tokens
+*   - `organizations:write` — the person's organizations: list every one they belong to, create new ones
+*  Consent is task-based (the shape Cloudflare's own OAuth consent took in August 2026: a client
+*  requests a set, the person may deselect the optional ones, the token carries what was granted):
+*  `iterate` is required, every other requested scope is optional on the consent page, and an app
+*  reads the granted set from `session.info().scopes` rather than assuming its request. */
+const OAuthScope = z.enum([
+	"iterate",
+	"account",
+	"organizations:write"
+]);
+const OAuthScopes = z.array(OAuthScope).transform((scopes) => [...new Set(["iterate", ...scopes])]);
+/** What each scope means to the person — the consent page's copy, sent with `consent.describe` so
+*  the page renders what it is given: a scope added to `OAuthScope` is described here or it does
+*  not compile. */
+const OAuthScopeDescriptions = {
+	iterate: {
+		title: "Read and make changes in the projects you grant it",
+		note: "Required — what the app is for.",
+		required: true
+	},
+	account: {
+		title: "See and end your sessions, and mint personal access tokens",
+		note: "Optional.",
+		required: false
+	},
+	"organizations:write": {
+		title: "See all your organizations and create new ones",
+		note: "Optional.",
+		required: false
+	}
+};
+//#endregion
+export { OAuthScope, OAuthScopeDescriptions, OAuthScopes };
+
+//# sourceMappingURL=oauth-scopes.mjs.map

package/dist/oauth-scopes.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-scopes.mjs","names":[],"sources":["../src/oauth-scopes.ts"],"sourcesContent":["import { z } from \"zod\";\n\n/** The platform's OAuth scopes — what an app may ask for and what a consent grants:\n *   - `iterate`             — reach the projects the person grants (every app; implied, always granted)\n *   - `account`             — manage the person's sessions and personal access tokens\n *   - `organizations:write` — the person's organizations: list every one they belong to, create new ones\n *  Consent is task-based (the shape Cloudflare's own OAuth consent took in August 2026: a client\n *  requests a set, the person may deselect the optional ones, the token carries what was granted):\n *  `iterate` is required, every other requested scope is optional on the consent page, and an app\n *  reads the granted set from `session.info().scopes` rather than assuming its request. */\nexport const OAuthScope = z.enum([\"iterate\", \"account\", \"organizations:write\"]);\nexport type OAuthScope = z.infer<typeof OAuthScope>;\n\nexport const OAuthScopes = z\n  .array(OAuthScope)\n  .transform((scopes) => [...new Set([\"iterate\", ...scopes])]);\n\n/** A requested scope as the consent page shows it: its name, what it means to the person, and\n *  whether they may untick it (`iterate` never). */\nexport interface ConsentScope {\n  name: OAuthScope;\n  title: string;\n  note: string;\n  required: boolean;\n}\n\n/** What each scope means to the person — the consent page's copy, sent with `consent.describe` so\n *  the page renders what it is given: a scope added to `OAuthScope` is described here or it does\n *  not compile. */\nexport const OAuthScopeDescriptions: Record<OAuthScope, Omit<ConsentScope, \"name\">> = {\n  iterate: {\n    title: \"Read and make changes in the projects you grant it\",\n    note: \"Required — what the app is for.\",\n    required: true,\n  },\n  account: {\n    title: \"See and end your sessions, and mint personal access tokens\",\n    note: \"Optional.\",\n    required: false,\n  },\n  \"organizations:write\": {\n    title: \"See all your organizations and create new ones\",\n    note: \"Optional.\",\n    required: false,\n  },\n};\n"],"mappings":";;;;;;;;;;AAUA,MAAa,aAAa,EAAE,KAAK;CAAC;CAAW;CAAW;AAAqB,CAAC;AAG9E,MAAa,cAAc,EACxB,MAAM,UAAU,CAAC,CACjB,WAAW,WAAW,CAAC,GAAG,IAAI,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,CAAC,CAAC;;;;AAc7D,MAAa,yBAAyE;CACpF,SAAS;EACP,OAAO;EACP,MAAM;EACN,UAAU;CACZ;CACA,SAAS;EACP,OAAO;EACP,MAAM;EACN,UAAU;CACZ;CACA,uBAAuB;EACrB,OAAO;EACP,MAAM;EACN,UAAU;CACZ;AACF"}

package/dist/oauth.mjs

@@ -0,0 +1,41 @@
+import { OAuthScopes } from "./oauth-scopes.mjs";
+import * as oauth from "oauth4webapi";
+//#region src/client/oauth.ts
+/** The platform's issuer as oauth4webapi's authorization server: its endpoints under `/oauth2`, and
+*  the `iss` it adds to every authorization response (RFC 9207), which `validateAuthResponse` then
+*  requires. The same description for an app's browser session and the CLI. */
+function authorizationServer(issuer) {
+	return {
+		issuer,
+		authorization_endpoint: `${issuer}/oauth2/auth`,
+		token_endpoint: `${issuer}/oauth2/token`,
+		registration_endpoint: `${issuer}/oauth2/register`,
+		authorization_response_iss_parameter_supported: true
+	};
+}
+/** The same code/PKCE parameters for browser login and a console-minted token. */
+async function authorizationCodeRequest(input) {
+	const verifier = oauth.generateRandomCodeVerifier();
+	const challenge = await oauth.calculatePKCECodeChallenge(verifier);
+	const state = oauth.generateRandomState();
+	const url = new URL("/oauth2/auth", input.issuer);
+	url.search = new URLSearchParams({
+		response_type: "code",
+		client_id: input.clientId,
+		redirect_uri: input.redirectUri,
+		scope: OAuthScopes.parse(input.scopes || []).join(" "),
+		state,
+		code_challenge: challenge,
+		code_challenge_method: "S256"
+	}).toString();
+	for (const resource of input.resources) url.searchParams.append("resource", resource);
+	return {
+		url,
+		state,
+		verifier
+	};
+}
+//#endregion
+export { authorizationCodeRequest, authorizationServer };
+
+//# sourceMappingURL=oauth.mjs.map

package/dist/oauth.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.mjs","names":[],"sources":["../src/client/oauth.ts"],"sourcesContent":["import * as oauth from \"oauth4webapi\";\nimport { OAuthScopes } from \"../oauth-scopes.ts\";\n\n/** The platform's issuer as oauth4webapi's authorization server: its endpoints under `/oauth2`, and\n *  the `iss` it adds to every authorization response (RFC 9207), which `validateAuthResponse` then\n *  requires. The same description for an app's browser session and the CLI. */\nexport function authorizationServer(issuer: string): oauth.AuthorizationServer {\n  return {\n    issuer,\n    authorization_endpoint: `${issuer}/oauth2/auth`,\n    token_endpoint: `${issuer}/oauth2/token`,\n    registration_endpoint: `${issuer}/oauth2/register`,\n    authorization_response_iss_parameter_supported: true,\n  };\n}\n\n/** The same code/PKCE parameters for browser login and a console-minted token. */\nexport async function authorizationCodeRequest(input: {\n  issuer: string;\n  clientId: string;\n  redirectUri: string;\n  resources: string[];\n  scopes?: string[];\n}) {\n  const verifier = oauth.generateRandomCodeVerifier();\n  const challenge = await oauth.calculatePKCECodeChallenge(verifier);\n  const state = oauth.generateRandomState();\n  const url = new URL(\"/oauth2/auth\", input.issuer);\n  url.search = new URLSearchParams({\n    response_type: \"code\",\n    client_id: input.clientId,\n    redirect_uri: input.redirectUri,\n    scope: OAuthScopes.parse(input.scopes || []).join(\" \"),\n    state,\n    code_challenge: challenge,\n    code_challenge_method: \"S256\",\n  }).toString();\n  for (const resource of input.resources) url.searchParams.append(\"resource\", resource);\n  return { url, state, verifier };\n}\n"],"mappings":";;;;;;AAMA,SAAgB,oBAAoB,QAA2C;CAC7E,OAAO;EACL;EACA,wBAAwB,GAAG,OAAO;EAClC,gBAAgB,GAAG,OAAO;EAC1B,uBAAuB,GAAG,OAAO;EACjC,gDAAgD;CAClD;AACF;;AAGA,eAAsB,yBAAyB,OAM5C;CACD,MAAM,WAAW,MAAM,2BAA2B;CAClD,MAAM,YAAY,MAAM,MAAM,2BAA2B,QAAQ;CACjE,MAAM,QAAQ,MAAM,oBAAoB;CACxC,MAAM,MAAM,IAAI,IAAI,gBAAgB,MAAM,MAAM;CAChD,IAAI,SAAS,IAAI,gBAAgB;EAC/B,eAAe;EACf,WAAW,MAAM;EACjB,cAAc,MAAM;EACpB,OAAO,YAAY,MAAM,MAAM,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG;EACrD;EACA,gBAAgB;EAChB,uBAAuB;CACzB,CAAC,CAAC,CAAC,SAAS;CACZ,KAAK,MAAM,YAAY,MAAM,WAAW,IAAI,aAAa,OAAO,YAAY,QAAQ;CACpF,OAAO;EAAE;EAAK;EAAO;CAAS;AAChC"}

package/dist/principal.d.ts

@@ -0,0 +1,8 @@
+/** Who is acting: a stable actor id (the control plane's user id) and, when known, an email. */
+export type Principal = {
+    actor: string;
+    email?: string;
+};
+/** The header the edge sets on a Request it forwards on a principal's behalf — the ingress after
+ *  the cookie check, a session's terminal `fetch` — and strips from every inbound Request. */
+export declare const ITX_PRINCIPAL_HEADER = "x-itx-principal";

package/dist/principal.mjs

@@ -0,0 +1,8 @@
+//#region src/principal.ts
+/** The header the edge sets on a Request it forwards on a principal's behalf — the ingress after
+*  the cookie check, a session's terminal `fetch` — and strips from every inbound Request. */
+const ITX_PRINCIPAL_HEADER = "x-itx-principal";
+//#endregion
+export { ITX_PRINCIPAL_HEADER };
+
+//# sourceMappingURL=principal.mjs.map

package/dist/principal.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"principal.mjs","names":[],"sources":["../src/principal.ts"],"sourcesContent":["// principal.ts — WHO user code is acting for, as the platform tells it: the verified `Principal`\n// (`itx.whoami()`, `source.principal` on an event) and the header the platform stamps it in on a\n// Request it forwards to a project's worker (sdk/auth.ts reads it). How the platform admits and\n// carries a caller, and signs its own tokens, stays in the platform.\n\n/** Who is acting: a stable actor id (the control plane's user id) and, when known, an email. */\nexport type Principal = { actor: string; email?: string };\n\n/** The header the edge sets on a Request it forwards on a principal's behalf — the ingress after\n *  the cookie check, a session's terminal `fetch` — and strips from every inbound Request. */\nexport const ITX_PRINCIPAL_HEADER = \"x-itx-principal\";\n"],"mappings":";;;AAUA,MAAa,uBAAuB"}

package/dist/project-ingress.d.ts

@@ -0,0 +1,58 @@
+/** THE ROUTING SLUG a project host named (`notes` for `notes--<project>.<hostname>`), as the project's
+ *  config worker `fetch` reads it; absent on the apex. Written only by the platform: the edge sets or
+ *  deletes it on every project-host request, and the context DO deletes it from every other
+ *  expression fetch, so neither a visitor nor loaded code can pick a routing slug. */
+export declare const ITERATE_ROUTING_SLUG_HEADER = "x-iterate-routing-slug";
+/** How projects are reached over HTTP; null ⇒ no ingress (`/api` and `/mcp` still answer). */
+export type IngressRouting = {
+    type: "subdomains";
+    hostname: string;
+} | {
+    type: "paths";
+} | null;
+/** What a request names: the project (its slug, as written — whether it EXISTS is the directory's
+ *  answer), the routing slug (null ⇒ the apex; either way the project's config worker answers), and
+ *  the path prefix the edge strips before the config worker sees the URL ("" under subdomains;
+ *  "/projects/<project>" or "/projects/<project>/<routingSlug>" under paths). */
+export type ProjectAddress = {
+    project: string;
+    routingSlug: string | null;
+    basePath: string;
+};
+/** The project + routing slug `url` names under `routing`, or null when it names none. Pure. */
+export declare function projectAddressOf(routing: IngressRouting, url: URL, platformOrigin: string): ProjectAddress | null;
+/** A PROJECT WILDCARD — an owned zone served as one project's apex (apps/os
+ *  `urls.projectWildcard`, `{ hostname: "iterate.com", project: "iterate" }`): the zone's apex and
+ *  every first-level name under it but the excluded ones, in the apex shape, `routingSlug: null`, so the
+ *  project's config worker `fetch` answers exactly as it does on `<project>.<hostname>`. Null for
+ *  anything else. Case and a trailing dot are forgiven. Pure. */
+export declare function projectWildcardHostOf(hostname: string, wildcard: {
+    hostname: string;
+    project: string;
+    excludedHostnames?: string[];
+} | undefined): {
+    routingSlug: null;
+    project: string;
+} | null;
+/** A PROJECT'S OWN HOSTNAME — `iterate.example.com`, added by the project (apps/os
+ *  project/custom-hostnames.ts) — is that project's apex, and one label under it names a routing
+ *  slug: `notes.iterate.example.com` carries `notes`, as `notes--<project>.<hostname>` does. The
+ *  hostnames a request's host could be a project's own hostname for, most specific first: the host
+ *  itself (the apex), then its parent with the first label as the routing slug. The caller
+ *  looks them up in that order; the first a project holds wins. Case and a trailing dot are
+ *  forgiven. Pure. */
+export declare function customHostnameCandidatesOf(host: string): {
+    hostname: string;
+    routingSlug: string | null;
+}[];
+/** The URL of `routingSlug` (null ⇒ the apex) in `project` under `routing`, at `path` (default "/",
+ *  must start with "/"). Null when there is no ingress, or when the result would not parse back to
+ *  the same address (a bad slug; a `path` that climbs out of its routing slug). subdomains: the
+ *  protocol and port are `platformOrigin`'s (local dev is `http://localhost:8788`, so
+ *  `http://<routingSlug>--<project>.localhost:8788/…`); paths:
+ *  `<platformOrigin>/projects/<project>[/<routingSlug>]<path>`. Pure. */
+export declare function projectUrlOf(routing: IngressRouting, platformOrigin: string, target: {
+    project: string;
+    routingSlug?: string | null;
+    path?: string;
+}): URL | null;

package/dist/project-ingress.mjs

@@ -0,0 +1,104 @@
+//#region src/project-ingress.ts
+/** THE ROUTING SLUG a project host named (`notes` for `notes--<project>.<hostname>`), as the project's
+*  config worker `fetch` reads it; absent on the apex. Written only by the platform: the edge sets or
+*  deletes it on every project-host request, and the context DO deletes it from every other
+*  expression fetch, so neither a visitor nor loaded code can pick a routing slug. */
+const ITERATE_ROUTING_SLUG_HEADER = "x-iterate-routing-slug";
+/** A DNS label: lowercase letters and digits, single hyphens inside. */
+const DNS_LABEL = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** A routing slug: a DNS label starting with a letter. */
+const ROUTING_SLUG = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+/** The labels `host` has under `hostname` — `site--p.iterate.app` ⇒ `["site--p"]` — lowercased, a
+*  trailing dot (a fully-qualified Host, `site--p.base.`) dropped; null when `host` is not under
+*  `hostname` at all. */
+function labelsUnder(host, hostname) {
+	const name = host.toLowerCase().replace(/\.$/, "");
+	const suffix = `.${hostname.toLowerCase()}`;
+	return name.endsWith(suffix) ? name.slice(0, -suffix.length).split(".") : null;
+}
+/** The project + routing slug `url` names under `routing`, or null when it names none. Pure. */
+function projectAddressOf(routing, url, platformOrigin) {
+	if (!routing) return null;
+	if (routing.type === "subdomains") {
+		const labels = labelsUnder(url.hostname, routing.hostname);
+		if (!labels || labels.length > 2) return null;
+		const [first, second] = labels;
+		const separator = first.startsWith("xn--") ? -1 : first.indexOf("--");
+		const [routingSlug, project] = second !== void 0 ? [first, second] : separator === -1 ? [null, first] : [first.slice(0, separator), first.slice(separator + 2)];
+		if (!DNS_LABEL.test(project) || routingSlug !== null && !ROUTING_SLUG.test(routingSlug)) return null;
+		return {
+			routingSlug,
+			project,
+			basePath: ""
+		};
+	}
+	if (url.origin !== new URL(platformOrigin).origin) return null;
+	const [, prefix, project = "", routingSlug] = url.pathname.split("/");
+	if (prefix !== "projects" || !DNS_LABEL.test(project)) return null;
+	if (routingSlug === void 0 || routingSlug === "") return {
+		routingSlug: null,
+		project,
+		basePath: `/projects/${project}`
+	};
+	if (!ROUTING_SLUG.test(routingSlug)) return null;
+	return {
+		routingSlug,
+		project,
+		basePath: `/projects/${project}/${routingSlug}`
+	};
+}
+/** A PROJECT WILDCARD — an owned zone served as one project's apex (apps/os
+*  `urls.projectWildcard`, `{ hostname: "iterate.com", project: "iterate" }`): the zone's apex and
+*  every first-level name under it but the excluded ones, in the apex shape, `routingSlug: null`, so the
+*  project's config worker `fetch` answers exactly as it does on `<project>.<hostname>`. Null for
+*  anything else. Case and a trailing dot are forgiven. Pure. */
+function projectWildcardHostOf(hostname, wildcard) {
+	if (!wildcard) return null;
+	const normalized = hostname.toLowerCase().replace(/\.$/, "");
+	if (wildcard.excludedHostnames?.includes(normalized)) return null;
+	const suffix = `.${wildcard.hostname}`;
+	const label = normalized.endsWith(suffix) ? normalized.slice(0, -suffix.length) : null;
+	return normalized === wildcard.hostname || label && !label.includes(".") ? {
+		routingSlug: null,
+		project: wildcard.project
+	} : null;
+}
+/** A PROJECT'S OWN HOSTNAME — `iterate.example.com`, added by the project (apps/os
+*  project/custom-hostnames.ts) — is that project's apex, and one label under it names a routing
+*  slug: `notes.iterate.example.com` carries `notes`, as `notes--<project>.<hostname>` does. The
+*  hostnames a request's host could be a project's own hostname for, most specific first: the host
+*  itself (the apex), then its parent with the first label as the routing slug. The caller
+*  looks them up in that order; the first a project holds wins. Case and a trailing dot are
+*  forgiven. Pure. */
+function customHostnameCandidatesOf(host) {
+	const hostname = host.toLowerCase().replace(/\.$/, "");
+	const dot = hostname.indexOf(".");
+	const [routingSlug, parent] = [hostname.slice(0, dot), hostname.slice(dot + 1)];
+	return [{
+		hostname,
+		routingSlug: null
+	}, ...dot > 0 && parent.includes(".") && ROUTING_SLUG.test(routingSlug) ? [{
+		hostname: parent,
+		routingSlug
+	}] : []];
+}
+/** The URL of `routingSlug` (null ⇒ the apex) in `project` under `routing`, at `path` (default "/",
+*  must start with "/"). Null when there is no ingress, or when the result would not parse back to
+*  the same address (a bad slug; a `path` that climbs out of its routing slug). subdomains: the
+*  protocol and port are `platformOrigin`'s (local dev is `http://localhost:8788`, so
+*  `http://<routingSlug>--<project>.localhost:8788/…`); paths:
+*  `<platformOrigin>/projects/<project>[/<routingSlug>]<path>`. Pure. */
+function projectUrlOf(routing, platformOrigin, target) {
+	if (!routing) return null;
+	const path = target.path || "/";
+	if (!path.startsWith("/")) throw new Error(`projectUrlOf: path must start with "/": ${path}`);
+	const routingSlug = target.routingSlug || null;
+	const origin = new URL(platformOrigin);
+	const url = routing.type === "subdomains" ? new URL(path, `${origin.protocol}//${routingSlug ? `${routingSlug}--` : ""}${target.project}.${routing.hostname}${origin.port ? `:${origin.port}` : ""}`) : new URL(`/projects/${target.project}${routingSlug ? `/${routingSlug}` : ""}${path}`, origin.origin);
+	const parsed = projectAddressOf(routing, url, platformOrigin);
+	return parsed && parsed.project === target.project && parsed.routingSlug === routingSlug ? url : null;
+}
+//#endregion
+export { ITERATE_ROUTING_SLUG_HEADER, customHostnameCandidatesOf, projectAddressOf, projectUrlOf, projectWildcardHostOf };
+
+//# sourceMappingURL=project-ingress.mjs.map

package/dist/project-ingress.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-ingress.mjs","names":[],"sources":["../src/project-ingress.ts"],"sourcesContent":["// project-ingress.ts — HOW PROJECTS ARE REACHED OVER HTTP, both directions in ONE pure file. A\n// deployment's `urls.ingressRouting` (apps/os app-config.ts) names the mechanism; `projectAddressOf`\n// parses a request's URL into the project and routing slug it names, `projectUrlOf` composes the URL\n// of a routing slug in a project. The platform's edge parses; the platform, the dash and an app\n// compose — one implementation, table-tested to round-trip (project-ingress.test.ts). No imports.\n//\n// The edge picks the PROJECT only: every host of a project reaches the project's config worker\n// `fetch`, with the routing slug in `x-iterate-routing-slug` (absent on the apex), and the config\n// worker routes on it in plain code.\n//\n//   subdomains  `<routingSlug>--<project>.<hostname>`, `<routingSlug>.<project>.<hostname>`, the apex\n//               `<project>.<hostname>` — every routing slug its own origin, under one wildcard on `hostname`.\n//   paths       `<platformOrigin>/projects/<project>/<routingSlug>/…`, the apex `<platformOrigin>/projects/<project>/`\n//               — one origin (workers.dev has no wildcard), every project under `/projects/` so the\n//               platform's own paths (`/api`, `/mcp`, `/login`, …) need no reserved list; the edge\n//               sandboxes what a project serves.\n\n/** THE ROUTING SLUG a project host named (`notes` for `notes--<project>.<hostname>`), as the project's\n *  config worker `fetch` reads it; absent on the apex. Written only by the platform: the edge sets or\n *  deletes it on every project-host request, and the context DO deletes it from every other\n *  expression fetch, so neither a visitor nor loaded code can pick a routing slug. */\nexport const ITERATE_ROUTING_SLUG_HEADER = \"x-iterate-routing-slug\";\n\n/** How projects are reached over HTTP; null ⇒ no ingress (`/api` and `/mcp` still answer). */\nexport type IngressRouting = { type: \"subdomains\"; hostname: string } | { type: \"paths\" } | null;\n\n/** What a request names: the project (its slug, as written — whether it EXISTS is the directory's\n *  answer), the routing slug (null ⇒ the apex; either way the project's config worker answers), and\n *  the path prefix the edge strips before the config worker sees the URL (\"\" under subdomains;\n *  \"/projects/<project>\" or \"/projects/<project>/<routingSlug>\" under paths). */\nexport type ProjectAddress = { project: string; routingSlug: string | null; basePath: string };\n\n/** A DNS label: lowercase letters and digits, single hyphens inside. */\nconst DNS_LABEL = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;\n/** A routing slug: a DNS label starting with a letter. */\nconst ROUTING_SLUG = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;\n\n/** The labels `host` has under `hostname` — `site--p.iterate.app` ⇒ `[\"site--p\"]` — lowercased, a\n *  trailing dot (a fully-qualified Host, `site--p.base.`) dropped; null when `host` is not under\n *  `hostname` at all. */\nfunction labelsUnder(host: string, hostname: string): string[] | null {\n  const name = host.toLowerCase().replace(/\\.$/, \"\");\n  const suffix = `.${hostname.toLowerCase()}`;\n  return name.endsWith(suffix) ? name.slice(0, -suffix.length).split(\".\") : null;\n}\n\n/** The project + routing slug `url` names under `routing`, or null when it names none. Pure. */\nexport function projectAddressOf(\n  routing: IngressRouting,\n  url: URL,\n  platformOrigin: string,\n): ProjectAddress | null {\n  if (!routing) return null;\n  if (routing.type === \"subdomains\") {\n    const labels = labelsUnder(url.hostname, routing.hostname);\n    if (!labels || labels.length > 2) return null; // deeper than `<routingSlug>.<project>` is not a project host\n    const [first, second] = labels as [string, string?];\n    const separator = first.startsWith(\"xn--\") ? -1 : first.indexOf(\"--\"); // `xn--…` is an IDN label (punycode), never `<routingSlug>--<project>`\n    const [routingSlug, project] =\n      // oxlint-disable-next-line iterate/simple-truthiness-check -- a PRESENT-but-empty second label (`<routingSlug>..<base>`) is the `<routingSlug>.<project>` shape (rejected below by DNS_LABEL), not the single-label `<project>` shape a truthiness check would route it to\n      second !== undefined\n        ? [first, second] // `<routingSlug>.<project>`\n        : separator === -1\n          ? [null, first] // the apex, `<project>`\n          : [first.slice(0, separator), first.slice(separator + 2)]; // `<routingSlug>--<project>`\n    // oxlint-disable-next-line iterate/simple-truthiness-check -- an empty routing slug (`--<project>.<base>`) must still be rejected by ROUTING_SLUG; truthiness would skip the check and admit it\n    if (!DNS_LABEL.test(project) || (routingSlug !== null && !ROUTING_SLUG.test(routingSlug)))\n      return null;\n    return { routingSlug, project, basePath: \"\" };\n  }\n  if (url.origin !== new URL(platformOrigin).origin) return null;\n  const [, prefix, project = \"\", routingSlug] = url.pathname.split(\"/\");\n  if (prefix !== \"projects\" || !DNS_LABEL.test(project)) return null;\n  // oxlint-disable-next-line iterate/simple-truthiness-check -- `/projects/<project>` and `/projects/<project>/` are both the apex; a present-but-empty next segment is not a routing slug\n  if (routingSlug === undefined || routingSlug === \"\")\n    return { routingSlug: null, project, basePath: `/projects/${project}` };\n  if (!ROUTING_SLUG.test(routingSlug)) return null;\n  return { routingSlug, project, basePath: `/projects/${project}/${routingSlug}` };\n}\n\n/** A PROJECT WILDCARD — an owned zone served as one project's apex (apps/os\n *  `urls.projectWildcard`, `{ hostname: \"iterate.com\", project: \"iterate\" }`): the zone's apex and\n *  every first-level name under it but the excluded ones, in the apex shape, `routingSlug: null`, so the\n *  project's config worker `fetch` answers exactly as it does on `<project>.<hostname>`. Null for\n *  anything else. Case and a trailing dot are forgiven. Pure. */\nexport function projectWildcardHostOf(\n  hostname: string,\n  wildcard: { hostname: string; project: string; excludedHostnames?: string[] } | undefined,\n): { routingSlug: null; project: string } | null {\n  if (!wildcard) return null;\n  const normalized = hostname.toLowerCase().replace(/\\.$/, \"\");\n  if (wildcard.excludedHostnames?.includes(normalized)) return null;\n  const suffix = `.${wildcard.hostname}`;\n  const label = normalized.endsWith(suffix) ? normalized.slice(0, -suffix.length) : null;\n  return normalized === wildcard.hostname || (label && !label.includes(\".\"))\n    ? { routingSlug: null, project: wildcard.project }\n    : null;\n}\n\n/** A PROJECT'S OWN HOSTNAME — `iterate.example.com`, added by the project (apps/os\n *  project/custom-hostnames.ts) — is that project's apex, and one label under it names a routing\n *  slug: `notes.iterate.example.com` carries `notes`, as `notes--<project>.<hostname>` does. The\n *  hostnames a request's host could be a project's own hostname for, most specific first: the host\n *  itself (the apex), then its parent with the first label as the routing slug. The caller\n *  looks them up in that order; the first a project holds wins. Case and a trailing dot are\n *  forgiven. Pure. */\nexport function customHostnameCandidatesOf(\n  host: string,\n): { hostname: string; routingSlug: string | null }[] {\n  const hostname = host.toLowerCase().replace(/\\.$/, \"\");\n  const dot = hostname.indexOf(\".\");\n  const [routingSlug, parent] = [hostname.slice(0, dot), hostname.slice(dot + 1)];\n  return [\n    { hostname, routingSlug: null },\n    ...(dot > 0 && parent.includes(\".\") && ROUTING_SLUG.test(routingSlug)\n      ? [{ hostname: parent, routingSlug }]\n      : []),\n  ];\n}\n\n/** The URL of `routingSlug` (null ⇒ the apex) in `project` under `routing`, at `path` (default \"/\",\n *  must start with \"/\"). Null when there is no ingress, or when the result would not parse back to\n *  the same address (a bad slug; a `path` that climbs out of its routing slug). subdomains: the\n *  protocol and port are `platformOrigin`'s (local dev is `http://localhost:8788`, so\n *  `http://<routingSlug>--<project>.localhost:8788/…`); paths:\n *  `<platformOrigin>/projects/<project>[/<routingSlug>]<path>`. Pure. */\nexport function projectUrlOf(\n  routing: IngressRouting,\n  platformOrigin: string,\n  target: { project: string; routingSlug?: string | null; path?: string },\n): URL | null {\n  if (!routing) return null;\n  const path = target.path || \"/\";\n  if (!path.startsWith(\"/\")) throw new Error(`projectUrlOf: path must start with \"/\": ${path}`);\n  const routingSlug = target.routingSlug || null;\n  const origin = new URL(platformOrigin);\n  const url =\n    routing.type === \"subdomains\"\n      ? new URL(\n          path,\n          `${origin.protocol}//${routingSlug ? `${routingSlug}--` : \"\"}${target.project}.${routing.hostname}${origin.port ? `:${origin.port}` : \"\"}`,\n        )\n      : new URL(\n          `/projects/${target.project}${routingSlug ? `/${routingSlug}` : \"\"}${path}`,\n          origin.origin,\n        );\n  const parsed = projectAddressOf(routing, url, platformOrigin);\n  return parsed && parsed.project === target.project && parsed.routingSlug === routingSlug\n    ? url\n    : null;\n}\n"],"mappings":"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"}

package/dist/react.mjs

@@ -0,0 +1,285 @@
+import { connectLiveState } from "./client.mjs";
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+//#region src/client/react.tsx
+/** @jsxImportSource react */
+/** Subscribe to a producer's live state and render its latest value. Pass a ready `itx` (a capnweb
+*  `api.authenticate(credentials).user` or `.projects.get(id)`), the producer's `key`, and a `readSeed`
+*  thunk that reads `{rev, state}` (`() => itx.invoke("itx.facets.get('slug').liveSnapshot()")`).
+*  Re-subscribes when the session, `key`, or `name` changes; unmount (and every re-subscribe)
+*  disposes the previous server-side subscription. */
+function useLiveState(itx, opts) {
+	const [store, setStore] = useState();
+	const [status, setStatus] = useState("connecting");
+	const [error, setError] = useState();
+	const readSeedRef = useRef(opts.readSeed);
+	readSeedRef.current = opts.readSeed;
+	useEffect(() => {
+		setStore(void 0);
+		setStatus("connecting");
+		setError(void 0);
+		if (!itx) return;
+		const readSeed = readSeedRef.current;
+		let disposed = false;
+		let dispose;
+		const unmounted = new AbortController();
+		connectLiveState(itx, {
+			key: opts.key,
+			name: opts.name,
+			readSeed,
+			signal: unmounted.signal,
+			onResync: (r) => {
+				if (disposed) return;
+				if (r === "healed") {
+					setStatus("live");
+					setError(void 0);
+				} else {
+					setStatus("error");
+					setError(r.message);
+				}
+			}
+		}).then((conn) => {
+			dispose = conn.dispose;
+			if (disposed) {
+				conn.dispose();
+				return;
+			}
+			setStore(conn.store);
+			setStatus("live");
+		}, (e) => {
+			if (disposed) return;
+			setError(e instanceof Error ? e.message : String(e));
+			setStatus("error");
+		});
+		return () => {
+			disposed = true;
+			unmounted.abort();
+			dispose?.();
+		};
+	}, [
+		itx,
+		opts.key,
+		opts.name
+	]);
+	return {
+		value: useSyncExternalStore(useCallback((cb) => store ? store.subscribe(cb) : () => {}, [store]), () => store?.get(), () => void 0),
+		rev: store?.rev() ?? null,
+		status,
+		error
+	};
+}
+/** A wire event (a capnweb proxy value or a plain object) as a `StreamEvent`, or null when
+*  it is not a committed row. Structural, not a schema: the transport validated it; this only refuses
+*  a shape the view cannot place (no offset, type or time). */
+function toStreamEvent(raw) {
+	const value = JSON.parse(JSON.stringify(raw));
+	if (!value || typeof value.offset !== "number" || typeof value.type !== "string" || typeof value.createdAt !== "string") return null;
+	return value;
+}
+/** A named live state before its first seed lands — and before the effect that opens it has run. */
+const LIVE_STATE_CONNECTING = {
+	value: void 0,
+	rev: null,
+	status: "connecting"
+};
+/** THE ITERATE CONTEXT, live — one hook, one stream subscription. THE LOG: subscribe to every
+*  committed event (or `consumes`) BEFORE the catch-up read, so nothing lands between the two;
+*  pushes and pages both dedupe into one map by offset; `caughtUp` once the read reached the head;
+*  `error` when the connect failed. Off that same log, THE PROCESSORS TABLE, re-read whenever the
+*  log grows a row-changing event (a subscription configured, halted or resumed — the table is core
+*  state, one call away, no push of its own), and WHO IS HERE: the rpc stubs lent right now
+*  (`itx.rpcStubs.list()` — physical, re-read at every new head, since presence changes are
+*  ephemeral facts) and, from the log, every principal that acted, newest first. And named facets'
+*  LIVE STATE, each seeded through `itx.facets.get('<name>').liveSnapshot()` — one entry per name,
+*  always. `liveState` OMITTED opens `core` (the core reduce answers under that name) plus every
+*  hosted facet in the processors table the hook holds, following the table as it loads and changes;
+*  `liveState` GIVEN is exactly the names to open, no implicit `core`. Re-connects when `itx`
+*  changes; unmount disposes every server-side subscription. */
+function useIterateContext(itx, opts = {}) {
+	const [events, setEvents] = useState(() => /* @__PURE__ */ new Map());
+	const [caughtUp, setCaughtUp] = useState(false);
+	const [error, setError] = useState();
+	const consumesKey = JSON.stringify(opts.consumes || ["*"]);
+	useEffect(() => {
+		setEvents(/* @__PURE__ */ new Map());
+		setCaughtUp(false);
+		setError(void 0);
+		if (!itx) return;
+		let disposed = false;
+		const merge = (batch) => setEvents((held) => {
+			const next = new Map(held);
+			for (const raw of batch) {
+				const event = toStreamEvent(raw);
+				if (event) next.set(event.offset, event);
+			}
+			return next;
+		});
+		let subscription;
+		(async () => {
+			const handle = await itx.subscribe({
+				consumes: JSON.parse(consumesKey),
+				target: (batch) => !disposed && merge(batch)
+			});
+			if (disposed) {
+				handle[Symbol.dispose]();
+				return;
+			}
+			subscription = handle;
+			for (let after = 0;;) {
+				const page = await itx.readEvents(after, 500);
+				if (disposed) return;
+				merge(page.events);
+				if (page.atHead || page.scannedThroughOffset <= after) break;
+				after = page.scannedThroughOffset;
+			}
+			setCaughtUp(true);
+		})().catch((e) => !disposed && setError(e instanceof Error ? e.message : String(e)));
+		return () => {
+			disposed = true;
+			subscription?.[Symbol.dispose]();
+		};
+	}, [itx, consumesKey]);
+	const sorted = useMemo(() => [...events.values()].sort((a, b) => a.offset - b.offset), [events]);
+	const [table, setTable] = useState();
+	const [failure, setFailure] = useState();
+	useEffect(() => {
+		if (!itx) return;
+		let disposed = false;
+		Promise.resolve(itx.processors.list()).then((list) => {
+			if (disposed) return;
+			setTable({
+				itx,
+				rows: list
+			});
+			setFailure(void 0);
+		}, (e) => !disposed && setFailure({
+			itx,
+			message: e instanceof Error ? e.message : String(e)
+		}));
+		return () => {
+			disposed = true;
+		};
+	}, [itx, sorted.reduce((last, event) => event.type.startsWith("events.iterate.com/itx/subscription-") ? event.offset : last, 0)]);
+	const currentTable = itx && table?.itx === itx ? table : void 0;
+	const [census, setCensus] = useState();
+	useEffect(() => {
+		if (!itx) return;
+		let disposed = false;
+		Promise.resolve(itx.rpcStubs.list()).then((list) => !disposed && setCensus({
+			itx,
+			rpcStubs: list
+		}), () => void 0);
+		return () => {
+			disposed = true;
+		};
+	}, [itx, sorted.at(-1)?.offset ?? 0]);
+	const rpcStubs = itx && census?.itx === itx ? census.rpcStubs : [];
+	const actors = useMemo(() => {
+		const byActor = /* @__PURE__ */ new Map();
+		for (const event of sorted) {
+			const principal = event.source?.principal;
+			if (!principal) continue;
+			byActor.set(principal.actor, {
+				actor: principal.actor,
+				email: principal.email,
+				grant: event.source?.grant,
+				lastSeenAt: event.createdAt
+			});
+		}
+		return [...byActor.values()].sort((a, b) => b.lastSeenAt.localeCompare(a.lastSeenAt));
+	}, [sorted]);
+	const liveStateKey = JSON.stringify(opts.liveState || ["core", ...(currentTable?.rows || []).flatMap((row) => row.hostedFacet ? [row.hostedFacet.name] : [])]);
+	const [liveStates, setLiveStates] = useState();
+	useEffect(() => {
+		if (!itx) return;
+		const names = JSON.parse(liveStateKey);
+		if (names.length === 0) return;
+		let disposed = false;
+		const unmounted = new AbortController();
+		const disposers = [];
+		const patch = (name, change) => setLiveStates((held) => held && held.itx === itx && held.key === liveStateKey ? {
+			...held,
+			entries: {
+				...held.entries,
+				[name]: {
+					...held.entries[name],
+					...change
+				}
+			}
+		} : held);
+		setLiveStates({
+			itx,
+			key: liveStateKey,
+			entries: Object.fromEntries(names.map((name) => [name, LIVE_STATE_CONNECTING]))
+		});
+		for (const name of names) connectLiveState(itx, {
+			key: name,
+			readSeed: async () => await itx.invoke(`itx.facets.get('${name}').liveSnapshot()`),
+			signal: unmounted.signal,
+			onResync: (result) => {
+				if (disposed) return;
+				if (result === "healed") patch(name, {
+					status: "live",
+					error: void 0
+				});
+				else patch(name, {
+					status: "error",
+					error: result.message
+				});
+			}
+		}).then((connection) => {
+			if (disposed) {
+				connection.dispose();
+				return;
+			}
+			disposers.push(connection.dispose);
+			disposers.push(connection.store.subscribe(() => patch(name, {
+				value: connection.store.get(),
+				rev: connection.store.rev()
+			})));
+			patch(name, {
+				value: connection.store.get(),
+				rev: connection.store.rev(),
+				status: "live"
+			});
+		}, (e) => {
+			if (disposed) return;
+			patch(name, {
+				status: "error",
+				error: e instanceof Error ? e.message : String(e)
+			});
+		});
+		return () => {
+			disposed = true;
+			unmounted.abort();
+			for (const dispose of disposers) dispose();
+		};
+	}, [itx, liveStateKey]);
+	const liveState = useMemo(() => {
+		const names = JSON.parse(liveStateKey);
+		const held = itx && liveStates?.itx === itx && liveStates.key === liveStateKey ? liveStates.entries : {};
+		return Object.fromEntries(names.map((name) => [name, held[name] || LIVE_STATE_CONNECTING]));
+	}, [
+		itx,
+		liveStateKey,
+		liveStates
+	]);
+	return {
+		events: sorted,
+		caughtUp,
+		error,
+		processors: {
+			rows: currentTable?.rows || [],
+			loaded: Boolean(currentTable),
+			error: itx && failure?.itx === itx ? failure.message : void 0
+		},
+		presence: {
+			actors,
+			rpcStubs
+		},
+		liveState
+	};
+}
+//#endregion
+export { useIterateContext, useLiveState };
+
+//# sourceMappingURL=react.mjs.map