@plitzi/sdk-shared 0.37.2 → 0.37.3

package/dist/types/SchemaTypes.d.ts

@@ -1,4 +1,5 @@
 import { InteractionCallbackParamValues, InteractionCallbackType } from './InteractionTypes';
+import { ChannelDeclarations } from './RealtimeTypes';
 import { Style } from './StyleTypes';
 import { RuleGroup } from '@plitzi/plitzi-ui/QueryBuilder';
 export type ElementRuntime = 'server' | 'client' | 'shared';
@@ -44,6 +45,15 @@ export type ElementBinding = {
     enabled?: boolean;
     to: string;
 };
+/**
+ * What a trigger does when it fires again while the flow it started is still running.
+ *
+ * - `skip` (the default): the new firing is ignored — what keeps a double click from submitting twice.
+ * - `parallel`: every firing runs its own flow, at the same time.
+ * - `queue`: every firing runs, one after another, in the order they came — none lost, none overlapping.
+ */
+export type WhileRunning = 'skip' | 'parallel' | 'queue';
+export declare const WHILE_RUNNING_MODES: readonly WhileRunning[];
 export type ElementInteraction<T extends Record<string, unknown> = Record<string, unknown>> = {
     id: string;
     title: string;
@@ -57,6 +67,8 @@ export type ElementInteraction<T extends Record<string, unknown> = Record<string
     flowId: string;
     enabled: boolean;
     when?: RuleGroup;
+    /** On a trigger only: what a firing does while this flow is still running. `skip` when absent. */
+    whileRunning?: WhileRunning;
 };
 export type ElementDefinition = {
     rootId: Element['id'];
@@ -123,7 +135,30 @@ export type Schema = {
     settings: {
         keepState?: boolean;
         stateStorage?: 'localStorage' | 'sessionStorage';
+        /**
+         * Keys of `runtime.state` that are never kept, even with `keepState` on: they are not written, not brought back,
+         * and a value one of them already holds survives the moment the rest is restored. For state that must start fresh
+         * on every visit — a demo, a panel somebody left open, a step of a walkthrough. Top-level keys, as `setState`
+         * writes them.
+         */
+        transientState?: string[];
+        /**
+         * Keys of `runtime.state` the first paint depends on — the tool a toolbar shows, a name in an avatar — kept in a
+         * cookie as well as in `stateStorage`, so the server renders with them and the page does not swap them in after
+         * hydration. Small values only: the cookie travels with every request and holds at most a few kilobytes. Needs
+         * `keepState`; a key cannot be both painted and transient. Top-level keys, as `setState` writes them.
+         */
+        paintedState?: string[];
         customCss: string;
+        /**
+         * The roles a signed-in visitor may hold in this space, each with the permissions it gives:
+         * `{ author: ['postPublish'] }`. They are what an action's `access: 'role'` and a page's `can()` are answered from
+         * — a visitor holds exactly the permissions of their roles here, never those of their account anywhere else.
+         *
+         * Declared by the space, so they are published, versioned and exported with it. WHO holds which is not: that is a
+         * list of people, kept by the platform the space runs on, and never part of a document anybody can read.
+         */
+        visitorRoles?: Record<string, string[]>;
         /** `basic` covers any HTTP+JSON backend by configuration; anything else is a name someone registered. */
         userProvider?: 'basic' | 'custom' | '' | (string & {});
         tokenStorage?: 'localStorage' | 'sessionStorage' | '';
@@ -151,6 +186,13 @@ export type Schema = {
          * session itself, which is the case whenever `loginUrl` is your own API.
          */
         sessionExchangeUrl?: string;
+        /**
+         * Where a sign-in that owed a second factor is completed: a password the backend answered with `mfaRequired` and
+         * an `mfaToken` resolves `auth.login` to `{ ok: false, reason: 'mfa', mfaToken }`, and `auth.login` with `mode:
+         * 'mfa'` posts `{ mfaToken, code }` here and adopts the session it answers with. Leave empty when the backend has
+         * no second factor.
+         */
+        mfaUrl?: string;
         /**
          * What to do on a page that requires a session while the stored one is being re-checked. `optimistic` (the
          * default) renders from the stored session and signs out if the check disagrees; `strict` waits for the answer,
@@ -167,6 +209,18 @@ export type Schema = {
          * `false` there cannot be turned around from here. Never `devMode`, which makes a deployment a development server.
          */
         debugMode?: boolean;
+        /**
+         * Values the space computes once and reads everywhere, by name: `{ xp: '{{ state.favourites|length * 10 }}' }` is
+         * read as `{{ computed.xp }}` in any binding, attribute or step. Each is a template over the global sources and the
+         * values declared before it (`computed.<earlier>`), re-evaluated when any of them changes. A template that is one
+         * `{{ expression }}` gives its value (a number, a list); anything else gives text.
+         */
+        computed?: Record<string, string>;
+        /**
+         * The realtime channels the space offers, by topic pattern: `{ 'board:{id}': { access: { mode: 'public' } } }`.
+         * A page subscribes to and publishes on a topic one of them matches, and on nothing else.
+         */
+        channels?: ChannelDeclarations;
     };
     rsc?: SchemaRsc;
     pages: Element['id'][];

package/dist/types/SchemaTypes.mjs

@@ -0,0 +1,8 @@
+//#region src/types/SchemaTypes.ts
+var e = [
+	"skip",
+	"parallel",
+	"queue"
+];
+//#endregion
+export { e as WHILE_RUNNING_MODES };

package/dist/types/ServerTypes.d.ts

@@ -1,9 +1,12 @@
-import { ActionEmailConfig, ActionEntry, ActionJobQueue, 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>;
@@ -469,6 +518,8 @@ export type ActionLookupsConfig = {
     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'. */
@@ -478,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;
     /**
@@ -539,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.
      *
@@ -555,6 +609,8 @@ 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.
@@ -650,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;
 };
@@ -676,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;
@@ -771,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 = {
@@ -800,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;
@@ -808,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. */
@@ -824,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.
@@ -849,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 —
@@ -875,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;
 };
@@ -961,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.
      *
@@ -974,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
@@ -1043,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 +
@@ -1091,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)
@@ -1107,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>;
@@ -1133,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;
 };