@spacefast/common 0.0.24 → 0.2.1

package/dist/contracts/zero.js

@@ -1,30 +1,28 @@
 import { z } from "zod";
 import { appRoutePathSchema, EXECUTION_ENV_MAX_KEYS, executionBundleSchema, executionCapabilitiesSchema, executionEnvNameSchema, executionIdentifierSchema, executionInspectPolicySchema, executionSha256Schema, executionStaticFileSchema, httpMethodSchema, LAKEBED_SERVER_ENV_FILE, PLATFORM_ROUTE_PREFIX, runtimeRealtimeModeSchema, SERVER_ENV_FILE, } from "./execution.js";
 /**
- * Spacefast Zero: capsules — schema, queries, mutations and endpoints that run
- * together inside one parent-owned transaction — executed by the native runner
- * on a dedicated wp.cloud site, against that site's own MySQL.
+ * Spacefast Zero: capsules of schema, queries, mutations and endpoints that run
+ * together inside one parent-owned transaction, executed by the native runner
+ * on a dedicated wp.cloud site against that site's own MySQL.
  *
- * The transaction is what makes this a separate product rather than a
- * placement option for `./functions.js`. A capsule handler's semantics depend
- * on the transaction wrapped around it, and an isolate reaching the database
- * over a relay cannot offer one. See `endpointIsPortable` in `./execution.js`
- * for the narrow surface both products can host.
+ * The transaction is what makes this a separate product rather than a placement
+ * option for `./functions.js`: an isolate reaching the database over a relay
+ * cannot offer one. See `endpointIsPortable` in `./execution.js` for the narrow
+ * surface both products can host.
  */
 export const ZERO_SOURCE_METADATA_KEY = "statticZero";
 /**
- * The tag a compiled capsule artifact carries — in the finalize payload, the
- * runtime config, the install profile, the client config the browser reads, and
- * every realtime event — so PHP and the Rust runner can tell what they were
- * handed. It is a property of the artifact the tree produced, not a kind a
- * space declares: a publish can carry this beside a worker.
+ * The tag a compiled capsule artifact carries everywhere it travels, so PHP and
+ * the Rust runner can tell what they were handed. It is a property of the
+ * artifact, not a kind a space declares: a publish can carry this beside a
+ * worker.
  */
 export const ZERO_RUNTIME_KIND = "zero";
 export const ZERO_PLATFORM_ROUTE_PREFIX = `${PLATFORM_ROUTE_PREFIX}/zero`;
 /**
- * Entry paths the Zero scaffold writes into `sf.jsonc#runtime`. They are
- * starting points, not the contract: a capsule's entries are whatever its
- * `runtime.server`/`runtime.client` say, and nothing infers them.
+ * Entry paths the Zero scaffold writes into `sf.jsonc#runtime`. Starting points
+ * only: a capsule's entries are whatever its `runtime.server`/`runtime.client`
+ * say, and nothing infers them.
  */
 export const ZERO_CLIENT_ENTRY = "client/index.tsx";
 export const ZERO_SERVER_ENTRY = "server/index.ts";
@@ -42,7 +40,7 @@ export const ZERO_RUNTIME_STORAGE_ROOT = "__spacefast/zero";
 export const ZERO_RUNTIME_ARTIFACT_PATH = `${ZERO_RUNTIME_STORAGE_ROOT}/artifact.json`;
 export const ZERO_RUNTIME_CONFIG_PATH = `${ZERO_RUNTIME_STORAGE_ROOT}/config.json`;
 export const ZERO_RUNTIME_BINARY_PATH = `${ZERO_RUNTIME_STORAGE_ROOT}/bin/stattic-runtime`;
-export const ZERO_RUNTIME_BINARY_COMPATIBILITY_TARGET = "wpcloud-linux-x86_64-gnu-v1";
+export const ZERO_RUNTIME_BINARY_COMPATIBILITY_TARGET = "linux-x86_64-gnu-v1";
 export const ZERO_RUNTIME_BUNDLE_ROOT = `${ZERO_RUNTIME_STORAGE_ROOT}/bundles`;
 export const ZERO_RUNTIME_SERVER_BUNDLE_PATH = `${ZERO_RUNTIME_BUNDLE_ROOT}/server.qjs.mjs`;
 /** The compiled capsule client, served at the app root. */
@@ -51,15 +49,13 @@ export const ZERO_PUBLIC_CLIENT_BUNDLE_PATH = "client.js";
  * Where platform-owned client bytes serve from: same origin as the space, one
  * content-addressed directory per platform build.
  *
- * Same origin is the whole point. Browsers have partitioned the HTTP cache by
- * top-level site since 2020, so a shared third-party CDN buys nothing a
- * same-origin URL does not — and costs a `script-src` hole. What a stable,
- * content-addressed URL does buy is real: the digest changes only when the
- * platform bytes change, so publishing a capsule a hundred times re-downloads
- * the capsule's own bundle a hundred times and the platform's exactly once.
+ * Browsers have partitioned the HTTP cache by top-level site since 2020, so a
+ * shared third-party CDN buys nothing a same-origin URL does not, and costs a
+ * `script-src` hole. The digest changes only when the platform bytes change, so
+ * republishing a capsule re-downloads its own bundle but not the platform's.
  *
  * Underscore-prefixed by framework convention (`_next/static`, `_astro`), which
- * is also how the runtime recognises it as immutable — see `immutable_path` in
+ * is also how the runtime recognises it as immutable. See `immutable_path` in
  * `crates/stattic-runtime-core/src/finalize.rs`.
  */
 export const ZERO_PLATFORM_ASSET_NAMESPACE = "_spacefast";
@@ -71,39 +67,33 @@ export function zeroPlatformAssetPath(digest, fileName) {
 /**
  * The compiled capsule server, which the QuickJS runner instantiates whole.
  *
- * 768 KiB is inherited, not measured: nobody has yet established what the
- * runner actually tolerates, and DS77 keeps the number only until someone does.
- * It binds a real resource — the runner holds the module graph in the site's
- * PHP-worker memory before executing anything — so it stays low deliberately;
- * server code is handlers, not an application.
+ * 768 KiB is inherited, not measured: nobody has established what the runner
+ * actually tolerates. It binds a real resource, since the runner holds the
+ * module graph in the site's PHP-worker memory before executing anything, so it
+ * stays low deliberately.
  */
 export const ZERO_SERVER_BUNDLE_MAX_BYTES = 786_432;
 /**
  * The tenant client bundle, and every other file the compile ships as content.
  *
- * This measures what the tenant publishes, and only that: the SDK, the kit, the
+ * This measures what the tenant publishes, and only that. The SDK, the kit, the
  * chart layer, preact, recharts and lucide are externals resolved through the
  * shell's import map to {@link ZERO_PLATFORM_ASSET_ROOT}, so platform bytes are
- * never weighed here (DS42). What remains is author code plus whatever npm the
- * author chose to bundle.
+ * never weighed here.
  *
- * 8 MiB matches the Functions per-entry cap (DS77) because the same reasoning
- * applies: a client bundle is static bytes to a browser, so nothing on the
- * serving side binds it, and the cap exists to fail an accidental
- * hundred-megabyte dependency in our tooling — where the build can say which
- * modules are large — rather than at upload. It is a guardrail, not a budget;
- * the size report is what an author should be reading.
+ * 8 MiB matches the Functions per-entry cap. A client bundle is static bytes to
+ * a browser, so nothing on the serving side binds it; the cap exists to fail an
+ * accidental hundred-megabyte dependency in tooling that can say which modules
+ * are large, rather than at upload.
  */
 export const ZERO_CLIENT_BUNDLE_MAX_BYTES = 8 * 1024 * 1024;
 /**
  * A capsule's compiled server travels as version metadata, not as content, so a
- * server-only change leaves the published app shell byte-identical — and the
- * version intent's manifest comparison would read it as "no changes" and never
- * deploy it. The publish writes this one small file into the version instead:
- * it holds a digest of everything the deploy would install, so any server,
- * schema, or runtime-config change moves the manifest. Same channel a Functions
- * bundle uses (`functionsBundleStoragePath`) — an ordinary manifest entry, no
- * artifact-specific plumbing.
+ * server-only change would leave the app shell byte-identical and the version
+ * intent's manifest comparison would read it as "no changes". The publish writes
+ * this one small file into the version instead: it holds a digest of everything
+ * the deploy would install, so any server, schema, or runtime-config change
+ * moves the manifest.
  */
 export const ZERO_RUNTIME_DEPLOY_PATH = `${ZERO_RUNTIME_STORAGE_ROOT}/deploy.json`;
 export const ZERO_MANAGED_TABLE_COLUMNS = ["id", "createdAt", "updatedAt"];
@@ -118,9 +108,8 @@ export const ZERO_RESERVED_APP_ROUTE_PATHS = [
     `/${ZERO_PUBLIC_CLIENT_BUNDLE_PATH}`,
     "/auth/callback",
 ];
-// The whole platform namespace is reserved, not just the one directory a build
-// happens to write: an endpoint claiming a path under it would shadow bytes the
-// shell's import map already told the browser to fetch.
+// The whole platform namespace is reserved: an endpoint claiming a path under it
+// would shadow bytes the shell's import map already told the browser to fetch.
 export const ZERO_RESERVED_APP_ROUTE_PREFIXES = [
     "/auth/",
     `/${ZERO_PLATFORM_ASSET_NAMESPACE}/`,
@@ -137,7 +126,7 @@ export const zeroEndpointSchema = z
     path: zeroRoutePathSchema,
 })
     .strict();
-function zeroEndpointRouteMatchShape(path) {
+function zeroEndpointRouteMatch(path) {
     const segments = [];
     let score = 0;
     let splat = false;
@@ -166,17 +155,17 @@ export function zeroEndpointRoutesAmbiguous(left, right) {
         (left.method === "HEAD" && right.method === "GET");
     if (!methodsOverlap)
         return false;
-    const leftShape = zeroEndpointRouteMatchShape(left.path);
-    const rightShape = zeroEndpointRouteMatchShape(right.path);
-    if (leftShape.score !== rightShape.score)
+    const leftMatch = zeroEndpointRouteMatch(left.path);
+    const rightMatch = zeroEndpointRouteMatch(right.path);
+    if (leftMatch.score !== rightMatch.score)
         return false;
-    if (!leftShape.splat && leftShape.segments.length < rightShape.segments.length)
+    if (!leftMatch.splat && leftMatch.segments.length < rightMatch.segments.length)
         return false;
-    if (!rightShape.splat && rightShape.segments.length < leftShape.segments.length)
+    if (!rightMatch.splat && rightMatch.segments.length < leftMatch.segments.length)
         return false;
-    return Array.from({ length: Math.min(leftShape.segments.length, rightShape.segments.length) }, (_, index) => index).every((index) => {
-        const segment = leftShape.segments[index];
-        const other = rightShape.segments[index];
+    return Array.from({ length: Math.min(leftMatch.segments.length, rightMatch.segments.length) }, (_, index) => index).every((index) => {
+        const segment = leftMatch.segments[index];
+        const other = rightMatch.segments[index];
         return segment === null || other === null || segment === other;
     });
 }
@@ -264,12 +253,12 @@ export const zeroTableSchema = z
 export const zeroDatabaseSchema = z.record(z.string(), zeroTableSchema);
 const zeroSha256Schema = executionSha256Schema;
 /**
- * The compiled server travels inline in the finalize payload; inlining keeps the
- * whole version one atomic write. Functions bundles do the opposite and land
- * in the content store first; see `functionsBundleRefSchema`.
+ * The compiled server travels inline in the finalize payload, which keeps the
+ * whole version one atomic write. Functions bundles land in the content store
+ * first; see `functionsBundleRefSchema`.
  *
- * The client never travels this way. It is content — the browser fetches it
- * from the version tree like any other asset — so it ships as a static file.
+ * The client never travels this way: it is content the browser fetches from the
+ * version tree, so it ships as a static file.
  */
 export const zeroRuntimeBundleSchema = executionBundleSchema({
     bundleRoot: ZERO_RUNTIME_BUNDLE_ROOT,
@@ -536,7 +525,7 @@ export const zeroCapsuleArtifactSchema = z
         .strict(),
     db: z
         .object({
-        backend: z.literal("wpcloud-mysql"),
+        backend: z.literal("mysql"),
         migrations: z.array(zeroMigrationOperationSchema).default([]),
     })
         .strict(),
@@ -636,18 +625,13 @@ export const zeroDeployMetadataSchema = z
  * What a live Zero capsule is, as the `capsule` member of a space's runtime
  * status.
  *
- * There is no `versionId` here: this only ever describes the version the status
- * response already names as live, and repeating it would invite the two to
- * disagree. `artifactId` stays because it identifies the built capsule rather
- * than the publish that carries it. There is no kind tag either — the member it
- * rides in already says which product answered.
+ * No `versionId`: the status response already names the live version, and
+ * repeating it would invite the two to disagree. `artifactId` stays because it
+ * identifies the built capsule rather than the publish that carries it.
  *
- * Every field is derived from the version's own finalize metadata, which is
- * what makes this safe to answer for a space whose runtime is asleep,
- * mid-move, or failing: nothing here costs a call to the space's origin. It is
- * also why there are no counts of things listed here — a caller that wants
- * `tables.length` can take it — and why the database is not a field: a capsule
- * always owns one, so its presence already said so.
+ * Every field is derived from the version's own finalize metadata, so this is
+ * safe to answer for a space whose runtime is asleep, mid-move, or failing.
+ * Nothing here costs a call to the space's origin.
  */
 export const zeroAppSchema = z
     .object({
@@ -667,9 +651,27 @@ export const zeroAppSchema = z
     endpoints: z.array(zeroEndpointSchema).default([]),
     sockets: z.array(z.string()).default([]),
     /**
-     * Migrations are operations, not names — `create_table`, `add_column` and
-     * friends — so a count is the honest summary here. The operations
-     * themselves are the database surface's answer (`GET /v1/spaces/{id}/db`).
+     * Compiled bundle sizes in bytes, read from the finalize payload's own
+     * declarations. Null — never 0 — when a legacy version's metadata predates
+     * size reporting, so absence stays honest. Meter these against
+     * {@link ZERO_SERVER_BUNDLE_MAX_BYTES} and {@link ZERO_CLIENT_BUNDLE_MAX_BYTES}.
+     */
+    serverBundleSize: z
+        .number()
+        .int()
+        .nonnegative()
+        .nullable()
+        .describe("Compiled server bundle size in bytes, or null when this version's metadata does not record it."),
+    clientBundleSize: z
+        .number()
+        .int()
+        .nonnegative()
+        .nullable()
+        .describe("Compiled client bundle size in bytes, or null when this version's metadata does not record it."),
+    /**
+     * Migrations are operations, not names, so a count is the summary here. The
+     * operations themselves are the database surface's answer
+     * (`GET /v1/spaces/{id}/db`).
      */
     migrationCount: z.number().int().nonnegative(),
     /** Digest of the schema the live migration plan settled on, if it ran one. */
@@ -726,7 +728,7 @@ export function createZeroCapsuleArtifact(input) {
             sockets: input.sockets ?? [],
         },
         db: {
-            backend: "wpcloud-mysql",
+            backend: "mysql",
             migrations: [],
         },
         realtime: {

package/dist/dashboard-paths/index.d.ts

@@ -1,46 +1,49 @@
 /**
- * Dashboard route first-segments that cannot be used as team slugs.
- *
- * Append-only: add a new top-level static dashboard route's first segment here
- * before its route module lands. A repository structural test enforces this.
+ * `connect` is held for the team-level connect page (see
+ * `reservedSegmentActivationContract` in apps/my's dashboard route ledger).
  */
-export declare const TEAM_SLUG_ROUTE_RESERVATIONS: readonly ["accept-beta-invite", "accept-invitation", "account", "access", "agent", "claim", "device", "drop", "new-team", "oauth", "push", "sign-in", "start", "terminal", "two-factor"];
-/**
- * Dashboard route first-segments that cannot be used as space slugs.
- *
- * Append-only: add a new static route directly below a team's first segment
- * here before its route module lands. A repository structural test enforces
- * this.
- */
-export declare const SPACE_SLUG_ROUTE_RESERVATIONS: readonly ["billing", "connect", "domains", "drop", "members", "new", "resume", "settings"];
+export declare const UNBUILT_SPACE_SLUG_ROUTE_RESERVATIONS: readonly ["connect"];
+/** Dashboard route first-segments that cannot be used as team slugs. */
+export declare const TEAM_SLUG_ROUTE_RESERVATIONS: readonly ["accept-beta-invite", "accept-invitation", "access", "account", "approvals", "claim", "device", "drop", "new-team", "oauth", "push", "sign-in", "start", "terminal", "two-factor"];
+/** Dashboard route first-segments that cannot be used as space slugs. */
+export declare const SPACE_SLUG_ROUTE_RESERVATIONS: readonly ["agents", "api-keys", "billing", "domains", "drop", "handoffs", "members", "new", "resume", "settings", "variables", "webhooks", "connect"];
 export type TeamSlugRouteReservation = (typeof TEAM_SLUG_ROUTE_RESERVATIONS)[number];
 export type SpaceSlugRouteReservation = (typeof SPACE_SLUG_ROUTE_RESERVATIONS)[number];
 export declare const TEAM_SLUG_ROUTE_RESERVATION_SET: ReadonlySet<string>;
 export declare const SPACE_SLUG_ROUTE_RESERVATION_SET: ReadonlySet<string>;
 /**
- * The Runtime page's sections. They are search params rather than path
- * segments, so `runtime` stays a single route (and a single ledger row) and a
- * space slugged "runtime" keeps its own Runtime page at
+ * The Runtime page's sections. Search params, not path segments, so `runtime`
+ * stays one route and a space slugged "runtime" keeps its own Runtime page at
  * `/<team>/runtime/runtime`.
  */
 export declare const SPACE_RUNTIME_SECTIONS: readonly ["overview", "database", "storage", "logs"];
 export type SpaceRuntimeSection = (typeof SPACE_RUNTIME_SECTIONS)[number];
 export declare const DEFAULT_SPACE_RUNTIME_SECTION: SpaceRuntimeSection;
-export type SpaceSettingsDestination = "access" | "advanced" | "builds" | "integrations" | "integrations/add" | "source-builds";
-export type TeamSettingsDestination = "access" | "audit" | "developer" | "developer/agents" | "developer/environment-variables" | "developer/handoffs" | "developer/webhooks" | "integrations";
+/**
+ * What is left under a Space's Settings dialog. Builds, Integrations, and
+ * Variables are top-level Space surfaces with their own builders below.
+ */
+export type SpaceSettingsDestination = "advanced" | "data-sources";
+export type TeamSettingsDestination = "access" | "activity" | "billing" | "integrations" | "usage";
+/** Top-level team surfaces; the name comes from the old Settings > Developer group. */
+export type TeamDeveloperSurface = "agents" | "api-keys" | "handoffs" | "variables" | "webhooks";
 export declare function teamPath(teamSlug: string): string;
 export declare function spacePath(teamSlug: string, spaceSlug: string): string;
 export declare function versionDetailPath(teamSlug: string, spaceSlug: string, versionRef: string): string;
 export declare function buildDetailPath(teamSlug: string, spaceSlug: string, buildId: string): string;
 export declare function spaceDomainsPath(teamSlug: string, spaceSlug: string): string;
+/** Build runs and the repository connection that produces them. */
+export declare function spaceBuildsPath(teamSlug: string, spaceSlug: string): string;
+export declare function spaceIntegrationsPath(teamSlug: string, spaceSlug: string): string;
+export declare function spaceVariablesPath(teamSlug: string, spaceSlug: string): string;
 /**
- * The space's Runtime page. The default section is the bare URL — the route
- * strips it back out of the address bar — so a link to "overview" and a link to
- * the page itself are the same link.
+ * The space's Runtime page. The route strips the default section back out of the
+ * address bar, so a link to "overview" and a link to the page are the same link.
  */
 export declare function spaceRuntimePath(teamSlug: string, spaceSlug: string, section?: SpaceRuntimeSection): string;
 export declare function spaceSettingsPath(teamSlug: string, spaceSlug: string, destination?: SpaceSettingsDestination): string;
 export declare function teamDomainsPath(teamSlug: string): string;
 export declare function teamBillingPath(teamSlug: string): string;
+export declare function teamDeveloperSurfacePath(teamSlug: string, surface: TeamDeveloperSurface): string;
 export declare function teamDomainDetailPath(teamSlug: string, domainRef: string): string;
 export declare function teamSettingsPath(teamSlug: string, destination?: TeamSettingsDestination): string;

package/dist/dashboard-paths/index.js

@@ -1,55 +1,31 @@
+import { DERIVED_SPACE_SLUG_ROUTE_RESERVATIONS, DERIVED_TEAM_SLUG_ROUTE_RESERVATIONS, } from "./route-reservations.generated.js";
 /**
- * Dashboard route first-segments that cannot be used as team slugs.
- *
- * Append-only: add a new top-level static dashboard route's first segment here
- * before its route module lands. A repository structural test enforces this.
+ * Reservations for a dashboard surface that has not shipped yet. Shipped
+ * surfaces are derived in route-reservations.generated.ts, so this is the only
+ * hand-authored list. Delete an entry once the generator starts deriving it;
+ * leaving both is a duplicate that fails this module's own test.
  */
-export const TEAM_SLUG_ROUTE_RESERVATIONS = [
-    "accept-beta-invite",
-    "accept-invitation",
-    "account",
-    "access",
-    // Not a TanStack route module: /agent* is the edge-served handoff-document
-    // surface (apps/my/public/_redirects + vite middleware, #417). Those rewrite
-    // rules deliberately swallow every /agent-prefixed path, so a team named
-    // "agent" could never reach its canonical dashboard. Reserved per the spec's
-    // own rule that a static first segment is reserved before the surface owning
-    // it ships (#417 predates this set; this closes that drift).
-    "agent",
-    "claim",
-    "device",
-    "drop",
-    "new-team",
-    "oauth",
-    "push",
-    "sign-in",
-    "start",
-    "terminal",
-    "two-factor",
-];
+const UNBUILT_TEAM_SLUG_ROUTE_RESERVATIONS = [];
 /**
- * Dashboard route first-segments that cannot be used as space slugs.
- *
- * Append-only: add a new static route directly below a team's first segment
- * here before its route module lands. A repository structural test enforces
- * this.
+ * `connect` is held for the team-level connect page (see
+ * `reservedSegmentActivationContract` in apps/my's dashboard route ledger).
  */
+export const UNBUILT_SPACE_SLUG_ROUTE_RESERVATIONS = ["connect"];
+/** Dashboard route first-segments that cannot be used as team slugs. */
+export const TEAM_SLUG_ROUTE_RESERVATIONS = [
+    ...DERIVED_TEAM_SLUG_ROUTE_RESERVATIONS,
+    ...UNBUILT_TEAM_SLUG_ROUTE_RESERVATIONS,
+];
+/** Dashboard route first-segments that cannot be used as space slugs. */
 export const SPACE_SLUG_ROUTE_RESERVATIONS = [
-    "billing",
-    "connect",
-    "domains",
-    "drop",
-    "members",
-    "new",
-    "resume",
-    "settings",
+    ...DERIVED_SPACE_SLUG_ROUTE_RESERVATIONS,
+    ...UNBUILT_SPACE_SLUG_ROUTE_RESERVATIONS,
 ];
 export const TEAM_SLUG_ROUTE_RESERVATION_SET = new Set(TEAM_SLUG_ROUTE_RESERVATIONS);
 export const SPACE_SLUG_ROUTE_RESERVATION_SET = new Set(SPACE_SLUG_ROUTE_RESERVATIONS);
 /**
- * The Runtime page's sections. They are search params rather than path
- * segments, so `runtime` stays a single route (and a single ledger row) and a
- * space slugged "runtime" keeps its own Runtime page at
+ * The Runtime page's sections. Search params, not path segments, so `runtime`
+ * stays one route and a space slugged "runtime" keeps its own Runtime page at
  * `/<team>/runtime/runtime`.
  */
 export const SPACE_RUNTIME_SECTIONS = ["overview", "database", "storage", "logs"];
@@ -72,10 +48,19 @@ export function buildDetailPath(teamSlug, spaceSlug, buildId) {
 export function spaceDomainsPath(teamSlug, spaceSlug) {
     return `${spacePath(teamSlug, spaceSlug)}/domains`;
 }
+/** Build runs and the repository connection that produces them. */
+export function spaceBuildsPath(teamSlug, spaceSlug) {
+    return `${spacePath(teamSlug, spaceSlug)}/builds`;
+}
+export function spaceIntegrationsPath(teamSlug, spaceSlug) {
+    return `${spacePath(teamSlug, spaceSlug)}/integrations`;
+}
+export function spaceVariablesPath(teamSlug, spaceSlug) {
+    return `${spacePath(teamSlug, spaceSlug)}/variables`;
+}
 /**
- * The space's Runtime page. The default section is the bare URL — the route
- * strips it back out of the address bar — so a link to "overview" and a link to
- * the page itself are the same link.
+ * The space's Runtime page. The route strips the default section back out of the
+ * address bar, so a link to "overview" and a link to the page are the same link.
  */
 export function spaceRuntimePath(teamSlug, spaceSlug, section = DEFAULT_SPACE_RUNTIME_SECTION) {
     const root = `${spacePath(teamSlug, spaceSlug)}/runtime`;
@@ -89,7 +74,10 @@ export function teamDomainsPath(teamSlug) {
     return `${teamPath(teamSlug)}/domains`;
 }
 export function teamBillingPath(teamSlug) {
-    return `${teamPath(teamSlug)}/billing`;
+    return teamSettingsPath(teamSlug, "billing");
+}
+export function teamDeveloperSurfacePath(teamSlug, surface) {
+    return `${teamPath(teamSlug)}/${surface}`;
 }
 export function teamDomainDetailPath(teamSlug, domainRef) {
     return `${teamDomainsPath(teamSlug)}/${dynamicSegment(domainRef)}`;

package/dist/dashboard-paths/route-reservations.generated.d.ts

@@ -0,0 +1,2 @@
+export declare const DERIVED_TEAM_SLUG_ROUTE_RESERVATIONS: readonly ["accept-beta-invite", "accept-invitation", "access", "account", "approvals", "claim", "device", "drop", "new-team", "oauth", "push", "sign-in", "start", "terminal", "two-factor"];
+export declare const DERIVED_SPACE_SLUG_ROUTE_RESERVATIONS: readonly ["agents", "api-keys", "billing", "domains", "drop", "handoffs", "members", "new", "resume", "settings", "variables", "webhooks"];

package/dist/dashboard-paths/route-reservations.generated.js

@@ -0,0 +1,36 @@
+// @generated by `bun run check:dashboard-route-reservations -- --write`.
+// Source: apps/my/src/routes (static first segments of route modules) and
+// apps/my/public/_redirects (same-origin edge rules that claim a path before the
+// router sees it). Add the route or the rule, regenerate, and the slug stops
+// being claimable. Hand edits are overwritten.
+export const DERIVED_TEAM_SLUG_ROUTE_RESERVATIONS = [
+    "accept-beta-invite",
+    "accept-invitation",
+    "access",
+    "account",
+    "approvals",
+    "claim",
+    "device",
+    "drop",
+    "new-team",
+    "oauth",
+    "push",
+    "sign-in",
+    "start",
+    "terminal",
+    "two-factor",
+];
+export const DERIVED_SPACE_SLUG_ROUTE_RESERVATIONS = [
+    "agents",
+    "api-keys",
+    "billing",
+    "domains",
+    "drop",
+    "handoffs",
+    "members",
+    "new",
+    "resume",
+    "settings",
+    "variables",
+    "webhooks",
+];

package/dist/docs/agent-arrival.d.ts

@@ -0,0 +1,92 @@
+import { type AnonymousAgentHandoffStatus } from "../contracts/device-auth.js";
+export declare const AGENT_HANDOFF_REQUEST_FAILED_MESSAGE = "Request failed.";
+export declare const AGENT_HANDOFF_INVALID_RESPONSE_MESSAGE = "Invalid agent handoff response.";
+/**
+ * The messages that say nothing a person can act on. A UI showing an error
+ * detail line suppresses these, so it never renders "failed: Request failed."
+ */
+export declare const AGENT_HANDOFF_GENERIC_MESSAGES: ReadonlySet<string>;
+export declare class AgentHandoffRequestError extends Error {
+    readonly code: string | null;
+    constructor(message: string, code?: string | null);
+}
+export type AgentArrivalConfig = {
+    /** Origin the anonymous handoff endpoints live on. */
+    apiOrigin: string;
+    /**
+     * Origins a minted link may legitimately carry, most likely first. A deploy
+     * may mint on the API origin or on a front-end origin that proxies
+     * `/handoffs/*` to it, so this is a list, not a guess. Defaults to the API
+     * origin alone.
+     */
+    allowedOrigins?: readonly string[];
+    /** Transport seam: tests and the dashboard's attributed client swap it. */
+    fetch?: typeof globalThis.fetch;
+    /** Clock seam for the cadence and reuse policies. */
+    now?: () => number;
+};
+export type MintedAnonymousArrival = {
+    /** Ledger id of the handoff. Not a secret — the poll and analytics key off it. */
+    id: string;
+    /**
+     * Composes the copy-ready prompt for the task selected RIGHT NOW. It is a
+     * function, not a stored string, for two reasons: one handoff is reused
+     * across a visit while the task behind the prompt keeps changing, and the
+     * bearer stays captured in this closure instead of sitting in caller state.
+     * The result contains the one-use URL: clipboard only.
+     */
+    promptFor: (context: string) => string;
+    /** Epoch ms. */
+    expiresAt: number;
+};
+/**
+ * Mints the signed-out handoff a copied prompt carries.
+ *
+ * The anonymous surface is anonymous by contract, so this deliberately sends no
+ * credentials: it works signed out, and a mint that carried a session would
+ * answer differently for gated accounts.
+ */
+export declare function mintAnonymousArrival(config: AgentArrivalConfig): Promise<MintedAnonymousArrival>;
+/** Reads one anonymous handoff's fetch state by its non-secret ledger id. */
+export declare function readAnonymousArrivalStatus(id: string, config: AgentArrivalConfig): Promise<AnonymousAgentHandoffStatus>;
+export declare const AGENT_ARRIVAL_EAGER_POLL_MS = 2000;
+export declare const AGENT_ARRIVAL_EAGER_WINDOW_MS: number;
+export declare const AGENT_ARRIVAL_RELAXED_POLL_MS = 10000;
+/**
+ * The handoff's own TTL is the clock: with no `since` to carry, "how much
+ * runway is left" says how long ago it was minted.
+ */
+export declare const AGENT_ARRIVAL_RELAXED_AFTER_MS: number;
+/**
+ * One live handoff per visit is reused while it still has this much runway.
+ * Every copy gesture minting its own would spend rows against the caller's
+ * budget for a signal that only has to flip once.
+ */
+export declare const AGENT_ARRIVAL_REFRESH_RUNWAY_MS: number;
+/** How long to wait before the next status read, or `false` to stop polling. */
+export declare function anonymousArrivalPollDelayMs(status: AnonymousAgentHandoffStatus | undefined, now?: number): number | false;
+/** The arrival itself: one fetch of the private URL is the whole signal. */
+export declare function hasAgentArrived(status: AnonymousAgentHandoffStatus | undefined): boolean;
+export type ComposedAnonymousPrompt = {
+    /** Ledger id to watch for the arrival. */
+    id: string;
+    /** Copy-ready text carrying the one-use URL. Clipboard only. */
+    prompt: string;
+    /** Epoch ms. */
+    expiresAt: number;
+};
+export type AnonymousArrival = {
+    /** The visit's handoff: minted once, reused while it still has runway. */
+    ensureMinted: () => Promise<MintedAnonymousArrival>;
+    /** ensureMinted, then the prompt for the task selected at this moment. */
+    promptFor: (context: string) => Promise<ComposedAnonymousPrompt>;
+    readStatus: (id: string) => Promise<AnonymousAgentHandoffStatus>;
+    nextPollDelayMs: (status: AnonymousAgentHandoffStatus | undefined) => number | false;
+    hasArrived: (status: AnonymousAgentHandoffStatus | undefined) => boolean;
+};
+/**
+ * One visit's arrival flow. Hold one of these for as long as the visitor is on
+ * the surface: the reuse discipline lives in the instance, so re-copies keep
+ * the same handoff instead of piling fresh rows behind one signal.
+ */
+export declare function createAnonymousArrival(config: AgentArrivalConfig): AnonymousArrival;