@plitzi/sdk-shared 0.32.25 → 0.33.0

package/dist/types/ServerTypes.d.ts

@@ -1,7 +1,7 @@
 import { Environment } from './CommonTypes';
-import { McpServerConfig } from './McpTypes';
+import { ConnectorEntry } from './ConnectorTypes';
 import { Schema } from './SchemaTypes';
-import { OfflineDataRaw } from './SdkTypes';
+import { AnalyticsConfig, OfflineDataRaw } from './SdkTypes';
 import { Style } from './StyleTypes';
 import { IncomingHttpHeaders } from 'node:http';
 import { FC } from 'react';
@@ -27,8 +27,11 @@ export type SSRRequest = {
 };
 export type SSRResponseHelpers = {
     status: number;
-    headers: Record<string, string>;
-    setHeader: (name: string, value: string) => void;
+    /** Multi-valued for the headers that genuinely are, `Set-Cookie` above all — see `setHeader`. */
+    headers: Record<string, string | string[]>;
+    /** An array sets the header once per entry, which `Set-Cookie` needs: a response that grants a session writes
+     *  several, and collapsing them into one string would produce a single malformed cookie. */
+    setHeader: (name: string, value: string | string[]) => void;
     setStatus: (code: number) => void;
     send: (body: string) => void;
     write: (chunk: string | Buffer) => void;
@@ -92,8 +95,50 @@ export type SSRPlugin = {
     component: FC;
     props: Record<string, unknown>;
 };
+/** What a space token is worth. `render` is the public credential every published site embeds — it is readable
+ *  by anyone who views the page, so it may only read. `agent` is the delegated grant an MCP connector receives
+ *  after a member consents, and is the only bearer that may write without a session behind it. */
+export type SpaceScope = 'render' | 'agent';
+/** A resolved space token: which space, what the bearer may do, and (for `agent`) the member who consented.
+ *  `canWrite` is computed by the consumer from its own authorization model — the MCP never derives it. */
+export type SSRGrant = {
+    spaceId: number;
+    scope: SpaceScope;
+    userId?: number;
+    canWrite: boolean;
+};
+/**
+ * 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
+ * deployment bring its own identity source without also reimplementing cookies.
+ */
+export type SSRSession = {
+    token: string;
+    /** Unix seconds. */
+    expiresAt: number;
+    refreshToken?: string;
+    refreshExpiresAt?: number;
+};
+/**
+ * How this deployment's session cookies are named and scoped. Every field has a working default derived from the
+ * request host, so a server that says nothing still gets a correct cookie; the function forms exist for deployments
+ * whose naming varies by environment or host, which is a policy only they know.
+ */
+export type SSRAuthCookie = {
+    name?: string | ((hostname: string) => string);
+    /** Return undefined for a host-only cookie. Defaults to the registrable domain, so sibling sub-domains share it. */
+    domain?: string | ((hostname: string) => string | undefined);
+    sameSite?: 'lax' | 'none';
+    secure?: boolean;
+    /** Path the refresh credential is confined to, so it never rides along on ordinary traffic. Defaults to `/auth`. */
+    refreshPath?: string;
+    /** Suffix of the readable companion cookie that carries only expiries. Defaults to `_hint`. */
+    hintSuffix?: string;
+};
 export type SSRUser = {
     token: string;
+    /** Unix seconds the token dies at, so the rendered page can renew ahead of it rather than on a refusal. */
+    expiresAt?: number;
     id: number;
     username: string;
     email: string;
@@ -102,10 +147,25 @@ export type SSRUser = {
     roles: string[];
 };
 export type SSRSpaceDeployment = {
+    /** Who may put this space in an iframe, as CSP `frame-ancestors` sources (e.g. `'self'`, `https://acme.com`,
+     *  or `*`). Resolved per space by the consumer, because only it knows the domains that space declares — a
+     *  published space must not be framable from a site its owner never allowed. Omitted → the server's own
+     *  `frameOptions` default stands. */
+    frameAncestors?: string[];
     environment?: Environment;
     credential?: SSRCredential;
     spaceId?: number | null;
     revision?: number;
+    /**
+     * This render is an author looking at their own work — the builder's preview — rather than a visitor being
+     * served. Metering skips it: nobody should be billed for editing.
+     *
+     * It is a property of HOW the request resolved, not of the environment it renders. Those two look the same
+     * from the render's side and are not: a space's free preview sub-domain serves the live editing environment
+     * to the public, so "which environment" cannot tell an author apart from a visitor. Only the resolver knows,
+     * which is why it says so here.
+     */
+    authoring?: boolean;
     templateProps?: SSRTemplateProps;
     pluginNames?: string[];
     pluginSources?: Record<string, PluginSource>;
@@ -153,16 +213,23 @@ export type ComponentCatalogEntry = {
  *  space, so the MCP can validate types/attributes dynamically per space instead of against a hand-mirror. */
 export type ComponentCatalog = Record<string, ComponentCatalogEntry>;
 export type SSRAdapters = {
-    getOfflineData: (spaceId: number, environment: string, revision?: number) => Promise<OfflineDataRaw | undefined>;
-    getSpaceDeployment: (req: SSRRequest) => Promise<SSRSpaceDeployment>;
+    /** The space's render payload. Optional HERE and required by a page server (see {@link SSRPageAdapters}): a
+     *  dedicated MCP server renders nothing, reads schema and style through its own adapters, and had to hand this
+     *  one over anyway for the type to be satisfied — an adapter it never called. */
+    getOfflineData?: (spaceId: number, environment: string, revision?: number) => Promise<OfflineDataRaw | undefined>;
+    /** Which space, environment and revision a request resolves to. Optional here for the same reason as
+     *  `getOfflineData`: MCP resolves its space from the request token (`getGrant`), never from the host. */
+    getSpaceDeployment?: (req: SSRRequest) => Promise<SSRSpaceDeployment>;
     /** Persist a space mutated by the mcp-ai `apply` tool. Implementations must recompute derived caches
      *  (notably `style.cache`) before storing. When omitted, mcp-ai runs read/preview/validate only and
      *  `apply` reports `persisted: false`. */
     saveOfflineData?: (spaceId: number, environment: string, data: OfflineDataRaw) => Promise<void>;
-    /** Resolve the spaceId the MCP request operates on, from the verified `Authorization` bearer. The consumer
-     *  owns the JWT secret, so it decodes here; the MCP service stays stateless. Returns undefined when the
-     *  token is missing or invalid. Required for the `mcp` service to serve any request. */
-    getSpaceId?: (req: SSRRequest) => Promise<number | undefined>;
+    /** Resolve the grant the MCP request operates under, from the verified `Authorization` bearer. The consumer
+     *  owns the JWT secret and the authorization model, so it decides here; the MCP service stays stateless.
+     *  Returns undefined when the token is missing or invalid. Required for the `mcp` service to serve any
+     *  request. `canWrite` is what separates a read-only bearer from one that may change the space — the MCP
+     *  refuses every write tool without it, and never infers the answer from the token itself. */
+    getGrant?: (req: SSRRequest) => Promise<SSRGrant | undefined>;
     /** Read the element schema for the MCP tools. Separate from `getOfflineData` (which is SSR/RSC shaped and
      *  strips `style.platform`); the MCP style resource needs the full documents, so schema and style split. */
     getSchema?: (spaceId: number, environment: Environment) => Promise<Schema | undefined>;
@@ -172,18 +239,173 @@ export type SSRAdapters = {
      *  each installed plugin's manifest — so the MCP `plitzi://types` resource can explain what custom elements do.
      *  The MCP already knows the built-in types. When omitted, custom types surface with their observed label only. */
     getComponentCatalog?: (spaceId: number, environment: Environment) => Promise<ComponentCatalog | undefined>;
+    /** Read every connector configured for the space, so the MCP can list them and author provider elements against
+     *  them. Connectors are space-level (not per environment) server-side state: the manifests name endpoints and an
+     *  auth scheme, so this must never feed a browser payload. When omitted, the MCP's connector resource is empty
+     *  and a provider element cannot be checked against the connector it names. */
+    getConnectors?: (spaceId: number) => Promise<ConnectorEntry[] | undefined>;
+    /** Create or replace one connector, keyed by `entry.id`. When omitted, connector ops apply in memory only and
+     *  `apply` reports `persisted: false`. */
+    saveConnector?: (spaceId: number, entry: ConnectorEntry) => Promise<void>;
+    /** Remove one connector by its identifier. Omitted alongside `saveConnector` for a read-only deployment. */
+    deleteConnector?: (spaceId: number, connectorId: string) => Promise<void>;
     /** 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>;
     /** Persist the style document mutated by the MCP `apply` tool. Implementations must recompute `style.cache`
      *  before storing. When omitted, `apply` reports `persisted: false`. */
     saveStyle?: (spaceId: number, environment: Environment, style: Style) => Promise<void>;
+    /** 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>;
-    onLogin?: (req: SSRRequest, res: SSRResponseHelpers) => Promise<boolean>;
-    onLogout?: (req: SSRRequest, res: SSRResponseHelpers) => Promise<void>;
-    /** Called by the RSC endpoint to fetch server-side data for server components.
-     *  When `ids` is provided the adapter should return data only for those element IDs.
-     *  Omitting `ids` (initial SSR fetch or full refresh) must return data for all elements. */
-    getRscData?: (req: SSRRequest, spaceId: number, environment: Environment, revision: number, user: SSRUser | undefined, ids?: string[]) => Promise<SSRRscData>;
+    /**
+     * Verify credentials and mint a session — identity, and nothing else. The server writes the cookies, clears them,
+     * and keeps the readable hint in step, because those are properties of how sessions travel rather than of who
+     * anyone is. A deployment bringing its own user database implements this and gets the rest for free.
+     *
+     * Return undefined to refuse. Never throw for a wrong password.
+     */
+    authenticate?: (credentials: Record<string, string>, req: SSRRequest) => Promise<SSRSession | undefined>;
+    /** Revoke whatever session this request carries, at the source. The cookies are the server's to clear. */
+    endSession?: (req: SSRRequest) => Promise<void>;
+    /**
+     * Turn a credential the browser obtained from an identity provider into a session here — see the exchange stage.
+     * Everything that decides whether it is any good lives in this adapter, because only the deployment knows:
+     *
+     * - which providers it trusts, and which one the space in question actually signs people in with;
+     * - that the token was minted for **this** application. Anyone who has signed into any other site with the same
+     *   provider holds a valid token for that user, so accepting one merely because the provider recognises it lets
+     *   that site sign in here as them. A provider that cannot prove it must be refused outright.
+     */
+    exchangeCredential?: (provider: string, token: string, req: SSRRequest) => Promise<{
+        ok: true;
+        session: SSRSession;
+        user?: SSRUser;
+    } | {
+        ok: false;
+        error: string;
+        status?: number;
+        reason?: string;
+    }>;
+    /** Called by the RSC endpoint, and once per page render, to fetch server-side data for server components.
+     *  See {@link SSRRscContext} for what it is given. */
+    getRscData?: (context: SSRRscContext) => Promise<SSRRscData>;
+    /**
+     * One billable server request. This is where a deployment meters usage, because these are the moments it
+     * actually spends bandwidth on a visitor and the ones a visitor cannot reach around: the browser is told
+     * what happened, never asked. Each runs before its cache is consulted, so a cached response still counts.
+     *
+     * What comes back shapes the response — degrade the free tier, hand the browser its reporting channel — and
+     * a deployment that meters nothing simply omits the adapter. Never throw from here: a metering outage must
+     * not take a site down, so failures should degrade to "served, uncounted".
+     */
+    meter?: (event: SSRMeterEvent) => Promise<SSRMeterDecision | undefined>;
+};
+/**
+ * Which area of server work is being metered. One name per area, because that is the unit a deployment prices
+ * — a full page render does not cost what a partial data refresh costs, and both are cheaper when a cache
+ * answered them than when the origin did.
+ */
+export type MeteredKind = 'page_view' | 'rsc_query'
+/** Reserved: nothing emits this yet. Server actions are not implemented — the area exists so wiring them
+ *  later is a call site, not a schema change. */
+ | 'server_action';
+/** The request being metered, for {@link SSRAdapters.meter}. */
+export interface SSRMeterEvent {
+    kind: MeteredKind;
+    /**
+     * Whether a cache answered this instead of the origin. Reported rather than inferred: only the handler knows,
+     * it is the same fact the response puts on the wire as `X-Cache: HIT`, and what it is worth is the
+     * deployment's to decide — an area may price a hit lower, or not distinguish one at all.
+     */
+    cached: boolean;
+    req: SSRRequest;
+    spaceId: number;
+    environment: Environment;
+    revision: number;
+}
+/** What the deployment decided about this request. */
+export type SSRMeterDecision = {
+    /** This space is over the quota its plan allows and the render should say so — the "Made with Plitzi" badge
+     *  on the free tier. Paid plans accrue overage instead and never set this. */
+    degrade?: boolean;
+    /** Client reporting channel, injected into the page bootstrap. Omitted → the page reports nothing. Only a
+     *  page render has anywhere to put it; the other kinds answer data, not a document. */
+    analytics?: AnalyticsConfig;
+};
+/** What a server that RENDERS PAGES must answer: the two adapters every page request goes through, on top of the
+ *  optional rest. Stated as its own type rather than by making them required for everyone, because "required" is
+ *  a property of the surface being served and not of the adapter set — a dedicated MCP server has no page request
+ *  to resolve, and the old shape made it hand over two adapters nothing would ever call. */
+export type SSRPageAdapters = SSRAdapters & Required<Pick<SSRAdapters, 'getOfflineData' | 'getSpaceDeployment'>>;
+/**
+ * Everything an RSC read is given: which space and revision, who is asking, and which elements want data.
+ *
+ * One object rather than six positional parameters, because the reason to add to it is exactly the reason the
+ * positional form failed — `loadOfflineData` is a seventh thing to know, and nobody should have to count commas to
+ * reach it, nor rewrite their adapter when an eighth arrives.
+ */
+export interface SSRRscContext {
+    req: SSRRequest;
+    spaceId: number;
+    environment: Environment;
+    revision: number;
+    /** Whoever the request carries, already resolved. */
+    user?: SSRUser;
+    /** On a partial refresh, the only element ids that want data. Absent means every one — the initial render. */
+    ids?: string[];
+    /**
+     * The space itself, read at most once per request however many times this is called.
+     *
+     * It is here because an adapter almost always needs the schema (to know which elements are server-rendered, or
+     * whether RSC is on at all) and the server is already loading it for the page — in parallel with this very call.
+     * Without a shared handle every deployment fetched it a second time, or wrote its own in-flight dedup to avoid
+     * doing so. Awaiting this joins the read already under way; it never starts a second one.
+     */
+    loadOfflineData: () => Promise<OfflineDataRaw | undefined>;
+}
+export type SSRActionConfig = {
+    /** URL path for the write endpoint. Defaults to '/_action'. */
+    path?: string;
+    /** Connector manifest and credential lookups. Without them the endpoint stays inert: a write can only be
+     *  authorized against a manifest, and there is nothing to authorize against. Shaped as `ConnectorLookups`
+     *  in `@plitzi/sdk-server`; typed loosely here so the shared types stay free of the server's internals. */
+    lookups?: {
+        getConnector: (spaceId: number, connectorId: string) => Promise<unknown>;
+        getCredential?: (spaceId: number, identifier: string) => Promise<Record<string, string> | undefined>;
+        fetchImpl?: typeof fetch;
+    };
+};
+export type SSRHealthConfig = {
+    path?: string;
+    /** Replaces the identity payload entirely. `check` still merges over it. */
+    payload?: Record<string, unknown>;
+    name?: string;
+    version?: string;
+    role?: string;
+    /**
+     * Live state, read on every probe and merged over the payload — the stores this process depends on, a queue
+     * depth, whatever only this deployment can know. Returning `healthy: false` answers **503**, which is what turns
+     * the endpoint from a liveness check into a readiness one: an orchestrator stops routing to a replica whose
+     * database has gone, instead of sending it traffic it can only fail.
+     *
+     * A check that throws is itself an unhealthy answer, and is reported as one rather than as a 500.
+     */
+    check?: () => Record<string, unknown> | Promise<Record<string, unknown>>;
+};
+/** Response compression. Every field has a default; supply only what this deployment wants different. */
+export type SSRCompressionConfig = {
+    /**
+     * Which encodings this server will use, most preferred first — the first one the client accepts wins. Default
+     * `['br', 'gzip']`. `['gzip']` for a client or proxy that mishandles Brotli; `[]` disables compression, same as
+     * `compression: false`.
+     */
+    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. */
+    brotliQuality?: number;
+    /** Gzip level, 0–9. Default 6. */
+    gzipLevel?: number;
 };
 export type SSRRscConfig = {
     /** Whether the RSC endpoint is active. Defaults to true when adapters.getRscData is provided. */
@@ -261,10 +483,19 @@ export type SSRServerConfig = {
     publicDir?: string;
     static?: Record<string, string>;
     devMode?: boolean;
+    /** Authorizes debugging on the pages this server renders. An SSR page loads the very same SDK, so this is the
+     *  server-side face of the SDK's `debugMode` prop: the page decides, and the visitor's 'plitzi_debug' cookie can
+     *  only narrow it. Defaults to `devMode`, so a development server debugs without being told to. */
+    debugMode?: boolean;
     cacheTtlMs?: number;
     loginPath?: string | false;
     middlewares?: SSRMiddleware[];
     logoutPath?: string | false;
+    /** Where a browser-obtained credential is handed over. Defaults to `/auth/exchange`; served only when the
+     *  `exchangeCredential` adapter is supplied. */
+    exchangePath?: string | false;
+    /** Naming and scope of the session cookies this server writes. See {@link SSRAuthCookie}. */
+    authCookie?: SSRAuthCookie;
     templateFn?: SSRTemplateFn;
     plugins?: Record<string, PluginSource>;
     pluginsCacheDir?: string;
@@ -283,105 +514,64 @@ export type SSRServerConfig = {
     frameOptions?: 'DENY' | 'SAMEORIGIN' | string[] | false;
     /** RSC (React Server Components) endpoint configuration. */
     rsc?: SSRRscConfig;
-    /** MCP (Model Context Protocol) server configuration — exposes schema tools to Claude. */
-    mcp?: McpServerConfig;
-    /** AI-native MCP server — replaces the standard MCP with a zero-hallucination batch protocol. `path` is where
-     *  it answers inside a server that also serves pages (default /mcp); a dedicated MCP server (createMCPServer)
-     *  owns its whole origin and ignores it. Note that createSSRServer mounts no MCP whatever this says — a
-     *  process that serves both surfaces is built with createServer. */
-    mcpAi?: {
-        enabled?: boolean;
-        path?: string;
-        /** Whether the plitzi_render view may paint from the tool arguments while the host is still STREAMING them:
-         *  a placeholder that grows with the widget being authored, instead of the static "Rendering…" held for as
-         *  long as the model takes to write the batch. Defaults to true; hosts that stream nothing are unaffected
-         *  either way. Set false to keep every view blank until the finished widget arrives. */
-        renderStreaming?: boolean;
-        /** How a rendered widget reaches ANYTHING outside its sandbox — images, media, fonts, and the endpoints an
-         *  apiContainer fetches. A widget runs in an iframe under a CSP the host builds from the origins this server
-         *  declares on its `ui://` resource, which is read before any widget exists (and the spec allows no per-call
-         *  CSP), so the origins an agent is about to author can never be declared. With a `secret` set, every external
-         *  URL a render authored is rewritten to this server's own endpoint — which IS declared — and fetched here,
-         *  which also settles the redirects, hotlink rules and missing CORS headers a null-origin sandbox cannot. The
-         *  agent never sees this: it authors the real URL. Without a secret there is no endpoint and the URLs travel
-         *  as authored, loading only where the host allows their origin. */
-        proxy?: {
-            /** Set false to serve no endpoint even with a secret configured. */
-            enabled?: boolean;
-            /** Where the endpoint answers. Default `/__proxy`. */
-            path?: string;
-            /** Signs each grant (target + kind + expiry + the connection that minted it), so the endpoint is not an open
-             *  proxy. Required to enable it; any value stable across replicas works. */
-            secret?: string;
-            /** Absolute base for the URLs handed to widgets (`https://mcp.example.com`). Default: the origin each MCP
-             *  request arrived on — right whenever the MCP server owns its sub-domain. */
-            baseUrl?: string;
-            /** Largest response the endpoint will pass through, in bytes. Default 8 MiB. */
-            maxBytes?: number;
-            /** How long a minted URL keeps working, in seconds. Default 7 days: a widget outlives the call that made it
-             *  (it stays in the conversation), but a leaked URL should not work forever. */
-            ttl?: number;
-            /** Which MCP tools may be handed the endpoint at all. Defaults to `['plitzi_render']`, and that default is
-             *  a guard rather than a convenience: a render is a throwaway widget, so a rewritten URL lives exactly as
-             *  long as it does, while a tool that WRITES a space (plitzi_apply) would persist proxied URLs into content
-             *  the user owns — their space would then depend on this server to show its own images, and those URLs
-             *  expire. Listing a tool only makes the endpoint reachable from it; rewriting is something the tool has to
-             *  implement, and today plitzi_render is the only one that does. */
-            tools?: string[];
-        };
-    };
+    /** Write endpoint for server-driven providers. Absent means the server serves reads only. */
+    action?: SSRActionConfig;
     /** 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`). */
     logger?: ServerLogger;
+    /**
+     * 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.
+     */
+    compression?: SSRCompressionConfig | false;
+    /**
+     * What to do when the server cannot take its port. Without it the server prints what went wrong, what to do about
+     * it, and exits non-zero — because a process whose server never bound is not running, and the alternative is a raw
+     * `EADDRINUSE` stack that says nothing about which port or which server.
+     *
+     * Supply this to keep the process alive and decide for yourself: an embedder that starts several servers, a
+     * supervisor that retries, a test that asserts the failure. Handling it here replaces the exit entirely.
+     */
+    onListenError?: (error: NodeJS.ErrnoException, context: {
+        port: number;
+        host: string;
+        label: string;
+    }) => void;
     adapters: SSRAdapters;
-    /** Draft-preview endpoint for the MCP visual-preview tools (the RENDERER side). Off unless `enabled`. */
-    preview?: SSRPreviewConfig;
-    /** For an MCP server that runs separately from the renderer (the CLIENT side): where to reach the SSR
-     *  `/preview` endpoint so the visual-preview tools work. The SDK builds an HTTP preview client from this;
-     *  absent → those tools report PREVIEW_UNAVAILABLE. */
-    previewClient?: {
-        url: string;
-        secret?: string;
-    };
-    /** Dedicated headless-browser service for plitzi_screenshot (off unless set). `serviceUrl` is the browser
-     *  service that turns a URL into PNG(s); `renderBaseUrl` is the SSR base the browser navigates to (a page
-     *  path + the one-shot `__pt` token are appended). When absent, plitzi_screenshot is not registered and only
-     *  the HTML plitzi_preview is available; when the service is unreachable at call time the tool degrades to
-     *  returning the HTML preview with a warning. */
-    screenshot?: {
-        serviceUrl: string;
-        renderBaseUrl: string;
-    };
-    /** Backing store for draft-preview tokens. Defaults to an in-memory store (single replica); inject a shared
-     *  store (e.g. Redis) for multi-replica correctness. */
-    draftStore?: DraftStore;
-    /** Which request-handling services this server mounts. Each maps to an internal `create<Name>Server` unit,
-     *  so new services scale without rewriting the dispatcher. Omitted flags fall back to sensible defaults:
-     *  ssr on, rsc when `adapters.getRscData` exists, mcp from `mcpAi.enabled`. `ai` is a reserved slot (not
-     *  wired yet). Only createServer reads these as written — the surface factories pin what their name promises
-     *  (createSSRServer: no mcp; createMCPServer: mcp alone). */
+    /** 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 —
+     *  handing them over is the decision. Only createServer reads these as written; the surface factories pin what
+     *  their name promises (a page server serves pages; a dedicated MCP server serves MCP alone). */
     services?: ServerServices;
     /** Liveness/readiness endpoint for standalone servers (k8s probes). A stage always answers `path`
-     *  (default /health) with 200. The body is the generic identity payload built from `name`/`version`/`role`
-     *  ({ Server, Version, role }); pass an explicit `payload` to override it entirely. */
-    health?: {
-        path?: string;
-        payload?: Record<string, unknown>;
-        name?: string;
-        version?: string;
-        role?: string;
-    };
+     *  (default /health) with the generic identity payload built from `name`/`version`/`role`
+     *  ({ Server, Version, role }); pass an explicit `payload` to override it entirely, or `check` to add what can
+     *  only be known per request. See {@link SSRHealthConfig}. */
+    health?: SSRHealthConfig;
     /** Cache-buster appended as ?v=<assetVersion> to all default SDK asset URLs (jsPath, cssPath, react vendor). Compute from file mtime or package version at startup. */
     assetVersion?: string;
-    /** OAuth 2.1 authorization for the MCP server. Omit to keep the server anonymous — see {@link OAuthConfig}. */
-    oauth?: OAuthConfig;
+    /** The draft-preview endpoint, and the store behind it. The draft is WRITTEN by an MCP tool and RENDERED here,
+     *  so this is the one piece of that feature the page server owns: `@plitzi/sdk-mcp` carries everything else in
+     *  its own options, and a deployment that never installs it leaves both unset.
+     *
+     *  `preview` mounts the endpoint (off unless `enabled`); `draftStore` backs the tokens and defaults to an
+     *  in-memory store — inject a shared one (e.g. Redis) for multi-replica correctness. */
+    preview?: SSRPreviewConfig;
+    draftStore?: DraftStore;
+};
+/** The same config as seen by a server that serves PAGES: its adapters answer for a page request. This is what
+ *  `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. */
+export type SSRPageServerConfig = SSRServerConfig & {
+    adapters: SSRPageAdapters;
 };
+/** Which surfaces a page server mounts. Only what the page pipeline itself owns: the MCP endpoint and
+ *  draft-preview are stages a companion package hands in, so they are not flags here. */
 export type ServerServices = {
     ssr?: boolean;
     rsc?: boolean;
-    mcp?: boolean;
-    ai?: boolean;
 };
 export type PluginRegistry = {
     register: (name: string, source: PluginSource) => void;
@@ -402,6 +592,9 @@ export type SSRMiddleware = (req: SSRRequest, res: SSRResponseHelpers, next: SSR
 export type SSRContext = {
     spaceDeployment?: SSRSpaceDeployment;
     user?: SSRUser;
+    /** What {@link SSRAdapters.meter} answered for this request, so the render reads the decision instead of
+     *  asking for it a second time. */
+    meter?: SSRMeterDecision;
 };
 export type SSRServer = {
     listen: (port: number, host?: string) => void;
@@ -435,7 +628,7 @@ export type OAuthGrantTarget = {
 };
 /** What the OAuth layer cannot resolve on its own: who the user is, what they may grant, and the bearer to mint
  *  for them. The SDK owns the protocol (discovery, registration, PKCE, code exchange); the consumer owns identity
- *  and issues a token its own `adapters.getSpaceId` will accept back. */
+ *  and issues a token its own `adapters.getGrant` will accept back. */
 export type OAuthAdapters = {
     /** Verify the credentials typed into the consent screen. Return undefined to re-show the form with an error —
      *  never throw for a wrong password. */

package/dist/types/SpaceTypes.d.ts

@@ -1,5 +1,21 @@
 import { Environment } from './CommonTypes';
-export type SpaceCredentialProvider = 's3' | 'r2' | 'ssr';
+import { ConnectorManifestDraft } from './ConnectorTypes';
+export type SpaceCredentialProvider = 's3' | 'r2' | 'ssr' | 'custom';
+/**
+ * A connector manifest as the builder sees it.
+ *
+ * The manifest is server-side state — it names endpoints and an auth scheme — so this shape exists for the editor
+ * and for the API that maintains it, never for a published page. What reaches a visitor is the connector's
+ * identifier and nothing else.
+ */
+export type SpaceConnector = {
+    id: number;
+    identifier: string;
+    name: string;
+    manifest: ConnectorManifestDraft;
+    createdAt: number;
+    updatedAt: number;
+};
 export type SpaceCredential = {
     identifier: string;
     name: string;

package/dist/types/StoreTypes.d.ts

@@ -1,6 +1,10 @@
+import { SubscriptionCollaborator, SubscriptionCollaboratorPointer } from './BuilderTypes';
+import { Environment, RenderMode } from './CommonTypes';
 import { Source } from './DataSourceTypes';
+import { QueryParams, RouteParams } from './NavigationTypes';
 import { Schema, Element } from './SchemaTypes';
 import { Segment } from './SegmentTypes';
+import { SpaceConnector } from './SpaceTypes';
 import { DisplayMode, Style, StyleState } from './StyleTypes';
 export type RuntimeSourceValues = {
     variables?: Record<string, unknown>;
@@ -26,8 +30,40 @@ export type CommonState = {
         elements?: Record<string, unknown>;
     };
     sources?: Record<string, Source>;
+    rsc?: RscState;
+    render?: RenderSettings;
+    navigation: {
+        urlSearchParams?: URLSearchParams;
+        routeParams: RouteParams;
+        queryParams: QueryParams;
+        hostname: string;
+        currentPageId: string;
+        navigate: (url: string, isExternal?: boolean) => void;
+    };
+};
+/** Not document state and not server data: the surface the schema is being rendered on. `previewMode` and
+ *  `debugMode` change at runtime (the builder's preview toggle, shift+F12), so reads of these are reactive; the rest
+ *  are fixed for the life of the render. */
+export type RenderSettings = {
+    previewMode?: boolean;
+    debugMode?: boolean;
+    renderMode?: RenderMode;
+    environment?: Environment;
+    isHydrating?: boolean;
+};
+export type RscState = {
+    enabled?: boolean;
+    endpoint?: string;
+    loaded?: boolean;
+    data?: Record<string, unknown>;
 };
 export type BuilderState = CommonState & {
+    collaboration: {
+        collaborators: SubscriptionCollaborator[];
+        pointers?: Record<string, SubscriptionCollaboratorPointer>;
+    };
+    connectors: Record<string, SpaceConnector>;
+    hasServerRendering: boolean;
     displayMode: DisplayMode;
     selector?: string;
     styleSelector?: string;

package/dist/types/index.d.ts

@@ -9,6 +9,7 @@ export * from './SegmentTypes';
 export * from './BuilderTypes';
 export * from './NavigationTypes';
 export * from './CollectionTypes';
+export * from './ConnectorTypes';
 export * from './ComponentTypes';
 export * from './StateTypes';
 export * from './CommonTypes';

package/dist/websockets/RTCodec.d.ts

@@ -36,8 +36,11 @@ export type RTMessageManagedClient = {
         action: 'mouseMove';
         x: number;
         y: number;
+        dx: number;
+        dy: number;
         zoom: number;
         rootId: string;
+        anchorId?: string;
     };
 } | {
     type: RTEvent.ELEMENT;
@@ -81,9 +84,12 @@ export type RTMessageManagedServer = {
         action: 'mouseMove';
         x: number;
         y: number;
+        dx: number;
+        dy: number;
         zoom: number;
         rootId: string;
         instanceId: string;
+        anchorId?: string;
     };
 } | {
     type: RTEvent.ELEMENT;