@plitzi/sdk-shared 0.37.1 → 0.37.3

package/dist/types/ServerTypes.d.ts

@@ -1,9 +1,12 @@
-import { ActionEmailConfig, ActionEntry, ActionLimits, ActionRejectReason, ActionRunSummary, ActionRejectRecord, ActionRunRecord, ActionRunStatus, ActionTaskDescriptor, ActionTriggerType } from './ActionTypes';
+import { ActionEmailConfig, ActionEntry, ActionJobQueue, ActionLimits, ActionRejectReason, ActionRunSummary, ActionRejectRecord, ActionRunRecord, ActionRunReport, ActionRunStatus, ActionTaskDescriptor, ActionTriggerType } from './ActionTypes';
 import { Environment } from './CommonTypes';
 import { ConnectorEntry } from './ConnectorTypes';
+import { FunctionsDraft, FunctionsSaveResult } from './FunctionTypes';
+import { SSRRealtimeConfig } from './RealtimeTypes';
 import { Schema } from './SchemaTypes';
 import { AnalyticsConfig, OfflineDataRaw } from './SdkTypes';
 import { FontHead, Style } from './StyleTypes';
+import { SpaceChange } from '../history/types';
 import { IncomingHttpHeaders } from 'node:http';
 import { FC } from 'react';
 export type ServerEnvironment = 'development' | 'production' | 'staging' | 'local';
@@ -24,8 +27,15 @@ export type SSRRequest = {
     query: Record<string, string>;
     /** Raw request body. Populated only for endpoints that consume it (e.g. the login/logout handlers). */
     body?: string;
+    /**
+     * The client's address, when the host resolved one — through the proxies it sits behind. Forgeable by a direct
+     * client like every forwarded header, so it names things (a session in a device list) and never decides anything.
+     */
+    ip?: string;
     ctx: SSRContext;
 };
+/** A body's compressed forms, by content encoding — filled as they are first asked for. */
+export type CompressedBodies = Partial<Record<'br' | 'gzip', Buffer>>;
 export type SSRResponseHelpers = {
     status: number;
     /** Multi-valued for the headers that genuinely are, `Set-Cookie` above all — see `setHeader`. */
@@ -37,8 +47,18 @@ export type SSRResponseHelpers = {
     /**
      * A `Buffer` is sent byte for byte and never compressed: it is how a binary reaches the wire — a font file, an
      * image — and what it holds is usually compressed already. A string keeps the encoding negotiation.
+     *
+     * `compressed` is where this body's compressed forms are kept, for a body that is sent again unchanged — a cached
+     * page, a static file. The first send of each encoding compresses and stores it; every later one sends the stored
+     * bytes. Without it a cache hit recompressed the same page on every request, which was nearly all the CPU a cached
+     * page cost.
+     *
+     * A function is a body read only when it is needed: when the stored form for this request's encoding is missing, or
+     * the client takes no compression. A static file is then read from disk once per encoding, not on every request.
      */
-    send: (body: string | Buffer) => void;
+    send: (body: string | Buffer | (() => string), options?: {
+        compressed?: CompressedBodies;
+    }) => void;
     write: (chunk: string | Buffer) => void;
     end: () => void;
 };
@@ -170,6 +190,23 @@ export type SSRGrant = {
     userId?: number;
     canWrite: boolean;
 };
+/** A page of a space's change history, newest first; `nextBefore` reads further back, null at the end. */
+export type SSRChangePage = {
+    changes: SpaceChange[];
+    nextBefore: number | null;
+};
+/** What to read of the history: older than `before`, only the changes that touched `entityId`, `limit` at a time. */
+export type SSRChangeQuery = {
+    before?: number;
+    entityId?: string;
+    limit: number;
+};
+/** Who a write is made for and which request made it, for a consumer that records its changes. Every document one
+ *  request writes shares its `batch`: one `plitzi_apply`, read back as one change. */
+export type SSRWriteContext = {
+    userId?: number;
+    batch: string;
+};
 /**
  * A session, as the thing that issued it describes it. Deliberately free of transport: whoever mints one says what
  * the credentials are and when they die, and the server decides how they are carried — which is what lets a
@@ -325,13 +362,25 @@ export type SSRAdapters = {
     saveAction?: (spaceId: number, entry: ActionEntry) => Promise<void>;
     /** Remove one action by its identifier. Omitted alongside `saveAction` for a read-only deployment. */
     deleteAction?: (spaceId: number, actionId: string) => Promise<void>;
+    /** The space's own functions: the draft's source files, which copy of them it is and what they declare.
+     *  Server-side code like the actions it serves — never a browser payload. When omitted, the MCP offers no functions
+     *  resource and refuses the function ops. */
+    getFunctions?: (spaceId: number) => Promise<FunctionsDraft | undefined>;
+    /** Save the draft's functions, whole. The deployment builds and checks them and answers what is wrong where it is;
+     *  `base` is the version the agent read, and a draft that moved on since is refused rather than overwritten. */
+    saveFunctions?: (spaceId: number, files: Record<string, string>, base: string, write: SSRWriteContext) => Promise<FunctionsSaveResult>;
+    /** Run one task of the draft's functions in the sandbox for the person behind the agent — the builder's Try. */
+    tryFunction?: (spaceId: number, task: string, params: Record<string, unknown>, write: SSRWriteContext) => Promise<ActionRunReport>;
     /** Persist the element schema mutated by the MCP `apply` tool. When omitted, `apply` reports `persisted: false`. */
-    saveSchema?: (spaceId: number, environment: Environment, schema: Schema) => Promise<void>;
+    saveSchema?: (spaceId: number, environment: Environment, schema: Schema, write: SSRWriteContext) => Promise<void>;
     /** Persist the style document mutated by the MCP `apply` tool — store it as given. `style.cache` arrives already
      *  compiled: the renderer serves that string and nothing else, so recomputing it is not a detail to delegate, and
      *  asking every deployment to remember it was one bug each of them could write alone. When omitted, `apply`
      *  reports `persisted: false`. */
-    saveStyle?: (spaceId: number, environment: Environment, style: Style) => Promise<void>;
+    saveStyle?: (spaceId: number, environment: Environment, style: Style, write: SSRWriteContext) => Promise<void>;
+    /** The space's change history, read-only: what every writer saved, and for whom. When omitted, the MCP offers no
+     *  history resource. */
+    getChanges?: (spaceId: number, environment: Environment, query: SSRChangeQuery) => Promise<SSRChangePage>;
     /** Who this request carries, if anyone. The adapter reads the credential and resolves it; the cookie it arrived
      *  in was written by the server, from {@link SSRAuthCookie}. */
     getUser?: (req: SSRRequest) => Promise<SSRUser | undefined>;
@@ -465,8 +514,12 @@ export type SpaceRevision = {
 export type ActionLookupsConfig = {
     getAction: (spaceId: number, actionId: string, at?: SpaceRevision) => Promise<unknown>;
     listActions?: (spaceId: number, at?: SpaceRevision) => Promise<unknown[]>;
+    /** Which spaces have something scheduled — the periodic reconcile's safety net. See `ActionLookups`. */
+    listScheduledSpaces?: () => Promise<number[]>;
     getCredential?: (spaceId: number, identifier: string) => Promise<Record<string, string> | undefined>;
     getConnector?: (spaceId: number, connectorId: string, at?: SpaceRevision) => Promise<unknown>;
+    /** The space's own functions as of that revision — `SpaceFunctions` in `@plitzi/sdk-server/functions`. */
+    getFunctions?: (spaceId: number, at?: SpaceRevision) => Promise<unknown>;
 };
 export type SSRActionConfig = {
     /** URL path for the write endpoint, and the base for the action-addressed routes. Defaults to '/_action'. */
@@ -476,8 +529,6 @@ export type SSRActionConfig = {
      * the endpoint keeps answering element-addressed connector writes alone.
      */
     lookups?: ActionLookupsConfig;
-    /** Deployment-owned tasks, shaped as `ActionTask` in `@plitzi/sdk-server/actions`. Validated at boot. */
-    tasks?: unknown[];
     /** Ceilings for every run this server accepts. A document may tighten them, never widen them. */
     limits?: ActionLimits;
     /**
@@ -537,10 +588,15 @@ export type SSRActionConfig = {
     idempotency?: {
         replayTtlMs?: number;
     };
+    /**
+     * What each space's functions sign with (`ctx.sign` / `ctx.verify`): at least 32 characters, the same on every
+     * replica. Each space and environment signs with a key derived from it. Absent, spaces sign nothing.
+     */
+    signingSecret?: string;
     /**
      * Where the `kv` tasks keep things — shaped as `ActionKvAdapter` in `@plitzi/sdk-server/actions`.
      *
-     * Five operations over strings, with no rule to obey: Redis, Memcached, a table, whatever this deployment
+     * Six operations over strings, with no rule to obey: Redis, Memcached, a table, whatever this deployment
      * already runs. How a counter BEHAVES — the key prefixing, the JSON round trip, and the rule that a window's
      * lifetime is set once by whoever created it — belongs to the server, not to the thing it writes into.
      *
@@ -553,7 +609,58 @@ export type SSRActionConfig = {
         delete: (key: string) => Promise<void>;
         increment: (key: string, amount: number) => Promise<number>;
         expire: (key: string, ttlSeconds: number) => Promise<void>;
+        /** Writes `next` only if the key holds `expected` (nothing, when undefined); answers whether it wrote. Atomic. */
+        swap: (key: string, expected: string | undefined, next: string, ttlSeconds?: number) => Promise<boolean>;
+    };
+    /**
+     * Scheduled runs: the durable queue they wait in, how many this replica runs at once, and whether it produces.
+     *
+     * On wherever `lookups.listActions` is answerable — a `schedule` trigger the editor offers is a trigger the
+     * server honours, which before this it only did if the deployment wrote a timer and a distributed lock of its
+     * own. With no `queue` it runs over this process's memory: right for one replica, and wrong for two, because
+     * each then keeps its own schedules and the nightly email goes out once per replica.
+     *
+     * `false` turns it off for a replica that must only serve pages.
+     */
+    jobs?: SSRActionJobsConfig | false;
+};
+/**
+ * How this deployment runs what a clock starts.
+ *
+ * Every default here is a safe one for a single machine; the two a cluster has to think about are `queue` — which
+ * must be shared, or the replicas do not see each other's work — and `workers`, which is how fast a backlog
+ * drains. Nothing in this config is a clock: the queue's own is the only one the scheduling path reads, so
+ * replicas in different countries agree about what has run without agreeing about what time it is.
+ */
+export type SSRActionJobsConfig = {
+    /** Shaped as `ActionJobQueue`. Omitted → this process's memory. */
+    queue?: ActionJobQueue;
+    /** Jobs this replica runs at once. Default 4; `0` produces without consuming. */
+    workers?: number;
+    /** Whether this replica sweeps due schedules into the queue. Default true. */
+    produce?: boolean;
+    /** The spaces this server schedules for, when it serves a known few — the self-hosted shape. */
+    spaces?: number[];
+    /** How often a free worker looks for a job. Default 1s. */
+    pollMs?: number;
+    /** How often this replica looks for due schedules. Default 15s. */
+    schedulePollMs?: number;
+    /** How long a claim is held before another replica may take the job over — the failover window. Default 30s. */
+    leaseMs?: number;
+    /** Attempts a job gets before it is left for an operator as `dead`. Default 3. */
+    maxAttempts?: number;
+    /** First retry delay, doubling per attempt, up to `maxMs`. Defaults to 30s and 15 minutes. */
+    backoff?: {
+        baseMs?: number;
+        maxMs?: number;
     };
+    /** Which environment scheduled runs execute in. Default `main`. */
+    environment?: Environment;
+    /** How often schedules are re-derived from documents. Default 15 minutes. */
+    reconcileMs?: number;
+    /** Names this replica in the job history. Defaults to the pid and a random suffix. */
+    workerId?: string;
+    onError?: (error: unknown) => void;
 };
 /**
  * How the server reaches a space's connectors: the manifest that describes one, and the credential it authenticates
@@ -599,8 +706,18 @@ export type SSRCompressionConfig = {
     encodings?: ('br' | 'gzip')[];
     /** Responses smaller than this many bytes go out uncompressed. Default 1024. */
     threshold?: number;
-    /** Brotli quality, 0–11. Default 4 — past that the CPU cost outgrows the bytes saved on HTML. */
+    /**
+     * Brotli quality, 0–11, for a body compressed on every request — a page rendered for this request alone. Default 2:
+     * measured on a quarter core, going to 4 cost a tenth of the pages a second to save half a kilobyte on each.
+     */
     brotliQuality?: number;
+    /**
+     * Brotli quality, 0–11, for a body compressed once and kept — a cached page, a static file such as the SDK bundle.
+     * Default 6: paid once, and every later response is that much smaller (the SDK bundle 10% under quality 4), for
+     * the same memory as 4. 9 needs ~40 MB more to compress the bundle, which a 128 MB server does not have; 10 and
+     * 11 cost seconds, which the request that fills the cache would wait for.
+     */
+    keptBrotliQuality?: number;
     /** Gzip level, 0–9. Default 6. */
     gzipLevel?: number;
 };
@@ -625,6 +742,12 @@ export type SSRRscConfig = {
     elementTimeoutMs?: number;
 };
 /** What every log event carries, whatever layer it came from. */
+/**
+ * How much a server says, from least to most: each level includes every one above it. `error` is what a production
+ * server shows unless told otherwise — something went wrong — and `warn`, `info` (every request answered, every
+ * plugin built) and `debug` are asked for. `silent` says nothing at all.
+ */
+export type LogLevel = 'error' | 'warn' | 'info' | 'debug';
 type ServerLogEventBase = {
     /** Wall-clock duration of the work the event describes, in milliseconds. */
     durationMs: number;
@@ -720,7 +843,18 @@ export type ActionRejectLogEvent = ServerLogEventBase & {
  *  are stripped from paths, tool arguments are reduced to their shape and a run to its steps. Two fields are NOT
  *  anonymous and a consumer shipping these events must handle them accordingly: `clientIp` on a request event, and
  *  the request path, which is kept verbatim because it is what makes the log usable. */
-export type ServerLogEvent = ServerRequestLogEvent | McpToolLogEvent | McpResourceLogEvent | ActionRunLogEvent | ActionRejectLogEvent;
+/** Anything else the server has to say — a plugin rebuilt, a manifest that would not load — at its own level. */
+export type ServerMessageLogEvent = {
+    kind: 'message';
+    level: LogLevel;
+    /** What is speaking: `SSR`, `RSC`, `Actions`, `auth`… — what a line used to start with in brackets. */
+    scope: string;
+    message: string;
+    ok: boolean;
+    error?: string;
+    timestamp: string;
+};
+export type ServerLogEvent = ServerRequestLogEvent | McpToolLogEvent | McpResourceLogEvent | ActionRunLogEvent | ActionRejectLogEvent | ServerMessageLogEvent;
 /** The sink a consumer provides to receive every {@link ServerLogEvent} (see `SSRServerConfig.logger`). */
 export type ServerLogger = (event: ServerLogEvent) => void;
 export type SSRServerConfig = {
@@ -749,6 +883,11 @@ export type SSRServerConfig = {
     /** Where a browser-obtained credential is handed over. Defaults to `/auth/exchange`; served only when the
      *  `exchangeCredential` adapter is supplied. */
     exchangePath?: string | false;
+    /**
+     * Signing visitors in by redirect, through an OAuth 2.1 authorization server — see {@link SSRSignInConfig}. Served
+     * only with the `exchangeCredential` adapter, which is what turns what comes back into a session on this host.
+     */
+    signIn?: SSRSignInConfig;
     /** Naming and scope of the session cookies this server writes. See {@link SSRAuthCookie}. */
     authCookie?: SSRAuthCookie;
     templateFn?: SSRTemplateFn;
@@ -757,6 +896,13 @@ export type SSRServerConfig = {
     pluginsTtlMs?: number;
     /** Auto-download and cache plugins declared in the schema's offlineData.plugins list. Default: true. */
     autoLoadSchemaPlugins?: boolean;
+    /**
+     * Whether a schema plugin may be read from a private address — `localhost`, the network this server runs in. A
+     * plugin's address is typed by whoever edits a space and read from inside this server, so it answers to the rule
+     * every authored request does and is refused there; turn this on only on a development machine whose bucket is on
+     * localhost. Default: false.
+     */
+    allowPrivatePluginHosts?: boolean;
     /** Where this deployment serves the font files a space uploaded — see {@link SSRFontsConfig}. */
     fonts?: SSRFontsConfig;
     /** Omit client-side JS from the rendered page — useful for verifying SSR HTML without hydration. Default: false. */
@@ -773,13 +919,34 @@ export type SSRServerConfig = {
     rsc?: SSRRscConfig;
     /** Write endpoint for server-driven providers. Absent means the server serves reads only. */
     action?: SSRActionConfig;
+    /**
+     * Code of this server's own, and the sandbox for the spaces' — shaped as `FunctionsConfig` in
+     * `@plitzi/sdk-server/functions`. `native` is trusted code loaded in the process (a self-hosted server's tasks, or a
+     * platform's own); `runner` runs each space's functions, isolated.
+     */
+    functions?: {
+        native?: unknown[];
+        runner?: unknown;
+        limits?: Record<string, number>;
+    };
+    /** Realtime channels the spaces declare — see {@link SSRRealtimeConfig}. On, in memory, when absent. */
+    realtime?: SSRRealtimeConfig;
     /** Connector manifest and credential lookups — see {@link ConnectorLookupsConfig}. They serve the RSC read path
      *  and the `/_action` write endpoint alike; without them neither can reach a connector. */
     connectors?: ConnectorLookupsConfig;
     /** Receives a {@link ServerLogEvent} for every HTTP request this server answers — whatever stage answered it
      *  and whatever the outcome — plus every MCP tool call and resource read inside those requests. Without it the
-     *  server reports nothing per request (the MCP events still reach the console when `MCP_DEBUG=1`). */
+     *  server reports nothing per request (the MCP events still reach the console when `MCP_DEBUG=1`). Everything
+     *  else the server has to say — a failure, a plugin rebuilt — comes here too as a `message` event, and goes to the
+     *  console when there is no logger. */
     logger?: ServerLogger;
+    /**
+     * The least severe thing worth saying — see {@link LogLevel}. `error` by default, `info` with `devMode`: a server
+     * in production reports what went wrong and nothing else, unless asked. A request that was answered is `info`, one
+     * that failed `error`; a refused action is `warn`. Below the level nothing is built, so a quiet server pays nothing
+     * per request for the log it is not keeping.
+     */
+    logLevel?: LogLevel | 'silent';
     /**
      * How responses are compressed. Omit for Brotli where the client takes it and gzip otherwise; `false` never
      * compresses, which is what to use when a proxy or CDN in front already does it.
@@ -798,6 +965,32 @@ export type SSRServerConfig = {
         host: string;
         label: string;
     }) => void;
+    /**
+     * How many processes serve this port. Node runs JavaScript on one thread, so one process renders on one core however
+     * many the machine has; each worker is a whole server of its own, and the connections are spread between them —
+     * more requests a second, and less time waiting behind another render.
+     *
+     * `true` / `'auto'`: one per core the process may actually use (a container's CPU quota included). `false`: one
+     * process. A number: that many, lowered to the cores there are (more only take turns on the same cores). Default: on
+     * under `NODE_ENV=production`, off otherwise — a development server and a test runner stay one process. The
+     * `SDK_SERVER_WORKERS` environment variable sets it when this does not.
+     *
+     * The workers are one server — one replica — and behave as one:
+     *
+     * - The stores kept in memory by default (an action's `kv`, the job queue, draft previews, the sign-in rate
+     *   limit) are the primary's, and each worker reaches them over the cluster channel. A store the deployment
+     *   supplies (Redis, a table) is used as it is.
+     * - The scheduler and the job consumers run in one worker only, so a schedule fires once and `jobs.workers` is the
+     *   whole server's concurrency; if that worker dies, its replacement takes them over.
+     * - `server.cache.invalidate()`, `server.plugins.register()` and `server.plugins.invalidate()` reach every worker,
+     *   whichever process calls them.
+     *
+     * Per worker: the rendered-page cache (each renders a page once), the plugin components, and the action run caps
+     * (`action.concurrency`: `perSpace`, `perProcess`, `renderPerProcess`), which a cluster of replicas already counts
+     * per replica. A plugin registered with a `component` stays in the process that registered it — register those
+     * where the server is created.
+     */
+    workers?: boolean | number | 'auto';
     adapters: SSRAdapters;
     /** Which request-handling services this server mounts: `ssr` on by default, `rsc` whenever
      *  `adapters.getRscData` exists. Stages a companion package contributes are deliberately NOT flags here —
@@ -824,6 +1017,28 @@ export type SSRServerConfig = {
  *  `createServer` from `@plitzi/sdk-server` takes and what the SSR stages are handed, so a page stage reaches
  *  `getOfflineData` without asking whether it is there — while a stage typed to the bare context (anything from
  *  `@plitzi/sdk-mcp`, which also runs in servers that have neither) still has to check. */
+/**
+ * A visitor signs in somewhere else and comes back signed in HERE: `GET <path>?return=/somewhere` sends them to the
+ * authorization server, and `GET <path>/callback` takes the code it answers with, redeems it server to server and
+ * hands the token to `exchangeCredential` — which is what makes the session, on this host, for this space.
+ *
+ * This server registers itself with the authorization server (RFC 7591) as the host the visitor is on, and proves the
+ * exchange with PKCE. The state travels in a `__Host-` cookie, which no sibling host can set: a sign-in somebody else
+ * started cannot be finished in this browser.
+ */
+export type SSRSignInConfig = {
+    /** What `exchangeCredential` knows the tokens by. */
+    provider: string;
+    /** Where the visitor's browser is sent: the authorization server's `/authorize`, as the public reaches it. */
+    authorizeUrl: string;
+    /** Where this server registers itself and redeems codes — reachable from here, which may be a private address. */
+    registerUrl: string;
+    tokenUrl: string;
+    /** What to ask for, for the space being signed into. */
+    scope: (spaceId: number) => string;
+    /** Where the flow answers. Default `/auth/sign-in`; the authorization server sends people back to `<path>/callback`. */
+    path?: string;
+};
 export type SSRPageServerConfig = SSRServerConfig & {
     adapters: SSRPageAdapters;
 };
@@ -910,8 +1125,15 @@ export type OAuthAdapters = {
      * first visit.
      */
     identify: (req: SSRRequest) => Promise<OAuthUser | undefined>;
-    /** What this user may grant access to. An empty list ends the flow with `access_denied`. */
-    grantTargets: (user: OAuthUser) => Promise<OAuthGrantTarget[]>;
+    /**
+     * What this user may grant access to. An empty list ends the flow with `access_denied`.
+     *
+     * `request.scope` is what the client asked for, so one deployment can offer different choices to different
+     * clients — a native client signing in as the person, and the same client asking which space to work in.
+     */
+    grantTargets: (user: OAuthUser, request: {
+        scope?: string;
+    }) => Promise<OAuthGrantTarget[]>;
     /**
      * End whatever session {@link OAuthAdapters.identify} was reading, so the person can connect as somebody else.
      *
@@ -923,13 +1145,53 @@ export type OAuthAdapters = {
      * that does not mean abandoning the connection and starting over from the host.
      */
     signOut?: (req: SSRRequest, res: SSRResponseHelpers) => void | Promise<void>;
-    /** Mint the bearer the client will send on every MCP request. Return undefined to deny the grant. */
-    issueToken: (user: OAuthUser, target: OAuthGrantTarget) => Promise<{
+    /** Mint the bearer the client will send on every request. Return undefined to deny the grant. */
+    issueToken: (user: OAuthUser, target: OAuthGrantTarget, context: OAuthIssueContext) => Promise<{
         token: string;
         expiresInSeconds?: number;
     } | undefined>;
+    /**
+     * End a credential {@link OAuthAdapters.issueToken} minted, when its grant is revoked (RFC 7009).
+     *
+     * Optional, for a credential that ends on its own. Without it, revoking a grant stops it being RENEWED, and what
+     * was already issued keeps working until it expires — which a person who just signed a device out reads as the
+     * sign-out not having happened, because the device is still there in their list.
+     */
+    revokeToken?: (credential: string) => Promise<void>;
     store: OAuthStore;
 };
+/**
+ * Who a credential is being issued to, beyond the person: which application, from where, and — on a renewal — which
+ * credential it takes the place of.
+ *
+ * This is what lets a deployment tell its user WHICH of their devices a credential lives on. The application names
+ * itself when it registers (RFC 7591 `client_name`, `software_id`); the request is the one the credential is being
+ * issued on — at consent, the person's browser, which for a loopback client is the same machine.
+ */
+export type OAuthIssueContext = {
+    client: {
+        clientId: string;
+        /** What the application registered as: `Plitzi CLI on carlos-mbp`, `Claude`. */
+        name: string;
+        /** RFC 7591 `software_id`, when it sent one: a stable name for the SOFTWARE, the same on every machine. */
+        softwareId?: string;
+    };
+    request?: {
+        userAgent?: string;
+        ip?: string;
+    };
+    /**
+     * Where the code of THIS grant is sent: the `redirect_uri` of the authorization request, at consent. A deployment
+     * whose credential is only good at certain addresses checks it here — registering a client is open to anybody, and
+     * the address it names is the one thing that says who will receive what the person agreed to. Absent on a renewal.
+     */
+    redirectUri?: string;
+    /**
+     * The credential this grant last issued, on a renewal. A deployment that keeps a row per credential updates that
+     * row rather than adding one, so a device renewing every hour stays one device.
+     */
+    replaces?: string;
+};
 /** A connection a visitor may take WITHOUT signing in, for a server whose public surface needs no identity — the
  *  MCP App, the tool and resource listings, the guide. The consent screen offers it as a second button beside the
  *  sign-in, and the grant is whatever `target` grants: point it at a target that carries no space, never at one
@@ -992,6 +1254,21 @@ export type OAuthConsentView = {
     canSwitchUser?: boolean;
     /** A message to show the user. */
     error?: string;
+    /**
+     * Who is asking, and where the grant goes if the person says yes.
+     *
+     * Anybody can register a client, call it anything and send somebody this screen on the deployment's own domain, so
+     * the name alone proves nothing. The host the code is sent back to is the one fact the requester cannot choose
+     * freely, and it is what tells "the app I just opened" apart from a stranger's server.
+     */
+    client: {
+        /** What the client registered itself as. Chosen by the client, so it is shown as a claim. */
+        name: string;
+        /** The host of the `redirect_uri` the grant is delivered to. */
+        redirectHost: string;
+        /** The grant goes back to an app listening on this computer (RFC 8252 loopback), not to a server. */
+        loopback: boolean;
+    };
     branding: OAuthBranding;
 };
 /** OAuth 2.1 authorization for the MCP server (RFC 9728 discovery + RFC 7591 dynamic client registration +
@@ -1040,6 +1317,15 @@ export type OAuthConfig = {
      * holds, and wrapping it costs a store read on every request and gives a second thing to revoke.
      */
     directTokens?: boolean;
+    /**
+     * Accept only loopback `redirect_uri`s (`http://127.0.0.1:<port>/…`, RFC 8252 §7.3), at registration and again at
+     * `/authorize`.
+     *
+     * Turn it on when every client is a native app on the person's own machine — a CLI, a desktop app — and above all
+     * with {@link directTokens}, where the grant IS the person's session. Registration is open to anybody, so with https
+     * redirects allowed a stranger's server can register, send somebody the link, and collect what they approve.
+     */
+    loopbackRedirectsOnly?: boolean;
 };
 /** A short-TTL, one-shot store for unsaved draft offline-data behind a preview token. The SDK ships an
  *  in-memory default (fine for a single replica); a multi-replica deployment injects a shared (e.g. Redis)
@@ -1056,11 +1342,15 @@ export type OAuthConfig = {
 export type DraftPutOptions = {
     ttlMs: number;
     reusable?: boolean;
+    /** The space the draft was made from. It is only ever rendered for that space. */
+    spaceId: number;
 };
 /** A stashed draft, and whether the read that resolved it left it there. */
 export type DraftEntry = {
     data: OfflineDataRaw;
     reusable: boolean;
+    /** The space the draft was made from — see {@link DraftPutOptions.spaceId}. */
+    spaceId: number;
 };
 export type DraftStore = {
     put: (token: string, data: OfflineDataRaw, options: DraftPutOptions) => void | Promise<void>;
@@ -1082,7 +1372,12 @@ export type SSRPreviewConfig = {
     enabled?: boolean;
     /** Internal endpoint path that mints a preview token. Default '/__preview'. */
     path?: string;
-    /** Shared secret required in the `x-preview-secret` header; requests without it are rejected. */
+    /**
+     * Shared secret required in the `x-preview-secret` header; requests without it are rejected.
+     *
+     * Required for the endpoint to answer at all: the page server that hosts it is the one the public reaches, so an
+     * enabled endpoint with no secret refuses every request rather than serving anyone.
+     */
     secret?: string;
     /** One-shot token time-to-live in milliseconds. Default 60000. */
     ttlMs?: number;

package/dist/types/SpaceTypes.d.ts

@@ -44,6 +44,59 @@ export type SpaceCredential = {
     createdAt: number;
     updatedAt: number;
 };
+/**
+ * A person given one of the space's visitor roles (`settings.visitorRoles`), by email. `claimed` says whether an
+ * account has taken it yet: a role given to an address waits for somebody to sign in with it, verified.
+ */
+export type SpaceVisitor = {
+    id: number;
+    email: string;
+    role: string;
+    claimed: boolean;
+    createdAt: number;
+    updatedAt: number;
+};
+/** One environment's runtime — the space's own server code run beside the platform — and how it last was. */
+export type SpaceRuntimeEnvironment = {
+    environment: string;
+    /** 0 for the draft. */
+    revision: number;
+    /** The packed code it runs, by what its bytes are. */
+    digest: string;
+    status: 'waiting' | 'starting' | 'ready' | 'failed' | 'stopping' | 'stopped';
+    /** Why it is not running, for whoever manages the space. */
+    error: string | null;
+    /** Why it is kept stopped: `idle` (unused for too long) or `manual`. */
+    stoppedReason: 'idle' | 'manual' | null;
+    /** When a running one stops for being unused, unless something uses it before — unix seconds. */
+    idleStopsAt: number | null;
+    /** The paths of the space it answers itself (`/mcp`). */
+    endpoints: string[];
+    /** Its tasks, as flows name them (`board.create`). */
+    tasks: string[];
+    startedAt: number | null;
+    /** The size it runs at — or will start at — by name (`SpaceRuntimeSizeOption['name']`). */
+    size: string;
+};
+/** A size a runtime may run at: what its pod may spend, and whether the space's plan includes it. */
+export type SpaceRuntimeSizeOption = {
+    name: string;
+    label: string;
+    /** As Kubernetes reads it: `250m` is a quarter of a core. */
+    cpu: string;
+    /** As Kubernetes reads it: `256Mi`. */
+    memory: string;
+    included: boolean;
+};
+/** A space's runtime: every environment's, and the names of the variables it starts with — never their values. */
+export type SpaceRuntime = {
+    environments: SpaceRuntimeEnvironment[];
+    variables: string[];
+    /** Every size there is, smallest first. */
+    sizes: SpaceRuntimeSizeOption[];
+    /** How long a runtime may go unused before it is stopped; 0 when the platform never stops one. */
+    idleMinutes: number;
+};
 export type SpaceDeployment = {
     id: number;
     environment: Environment;

package/dist/types/StateTypes.d.ts

@@ -4,4 +4,10 @@ export type RuntimeStateInstance = {
     setState: (value: RuntimeState | ((prev: RuntimeState) => RuntimeState)) => void;
     setStateByKey: (key: string, value: unknown) => void;
     clearState: () => void;
+    /**
+     * Called with the whole state after every change to it, until the returned function is called. What a host or a
+     * plugin that keeps the state somewhere of its own — a store, a URL, an analytics call — listens to instead of
+     * polling `state`.
+     */
+    subscribe: (listener: (state: RuntimeState) => void) => () => void;
 };

package/dist/types/StoreTypes.d.ts

@@ -3,6 +3,7 @@ import { SubscriptionCollaborator, SubscriptionCollaboratorPointer } from './Bui
 import { Environment, RenderMode } from './CommonTypes';
 import { Source } from './DataSourceTypes';
 import { QueryParams, RouteParams } from './NavigationTypes';
+import { RealtimeTransport } from './RealtimeTypes';
 import { Schema, Element } from './SchemaTypes';
 import { Segment } from './SegmentTypes';
 import { SpaceConnector } from './SpaceTypes';
@@ -44,6 +45,11 @@ export type CommonState = {
     sources?: Record<string, Source>;
     rsc?: RscState;
     actions?: ActionsState;
+    /** Where this origin's realtime channels answer — absent in a render with no server, where no channel opens. */
+    realtime?: {
+        endpoint?: string;
+        transport?: RealtimeTransport;
+    };
     render?: RenderSettings;
     /**
      * The theme, mirrored from `themeStore` so the devtools store viewer answers "which theme is this" in one line.
@@ -72,6 +78,11 @@ export type CommonState = {
         /** Scheme, host AND port — what a link needs to name this page absolutely. `hostname` has no port, which is why
          *  it answers `when` rules and cannot answer this. */
         origin: string;
+        /**
+         * The page's whole address — origin, path and query — as the server was asked for it and the browser shows it: what
+         * a link that shares THIS page is. Known in the first paint, so a text built from it is right before hydration.
+         */
+        href: string;
         currentPageId: string;
         navigate: (url: string, isExternal?: boolean) => void;
     };
@@ -102,7 +113,7 @@ export type RenderSettings = {
      *
      * Not the visitor's business and not the page's either — it is a fact about the account behind the site, which is
      * why it rides the render surface rather than the schema: nothing an author writes can set it, and nothing in the
-     * space's settings can turn it off. `branding` is forced on by the same state; this is what says WHY.
+     * space's settings can turn it off.
      */
     overQuota?: boolean;
     /**

package/dist/types/index.d.ts

@@ -12,6 +12,8 @@ export * from './NavigationTypes';
 export * from './CollectionTypes';
 export * from './ConnectorTypes';
 export * from './ActionTypes';
+export * from './FunctionTypes';
+export * from './RealtimeTypes';
 export * from './ComponentTypes';
 export * from './StateTypes';
 export * from './CommonTypes';

package/dist/types/index.mjs

@@ -1,2 +1,3 @@
-import { StyleVariableCategory as e } from "./StyleTypes.mjs";
-export { e as StyleVariableCategory };
+import { WHILE_RUNNING_MODES as e } from "./SchemaTypes.mjs";
+import { StyleVariableCategory as t } from "./StyleTypes.mjs";
+export { t as StyleVariableCategory, e as WHILE_RUNNING_MODES };