@plitzi/sdk-server 0.32.4 → 0.32.5

package/dist/src/core/http/types.d.ts

@@ -0,0 +1,19 @@
+import { RawResponse } from '../../helpers/buildResponseHelpers';
+import { ServerCaches } from '../../helpers/cache';
+import { PluginManager } from '../../plugins/manager';
+import { SSRRequest, SSRResponseHelpers, SSRServerConfig, SSRTemplateFn } from '@plitzi/sdk-shared';
+import { IncomingMessage } from 'node:http';
+export interface BaseContext {
+    raw: IncomingMessage;
+    rawRes: RawResponse;
+    req: SSRRequest;
+    res: SSRResponseHelpers;
+    config: SSRServerConfig;
+    port: number;
+}
+export interface SSRContext extends BaseContext {
+    renderFn: SSRTemplateFn;
+    caches: ServerCaches;
+    pluginManager: PluginManager;
+}
+export type Stage<C extends BaseContext = BaseContext> = (ctx: C) => boolean | Promise<boolean>;

package/dist/src/core/server/baseServer.d.ts

@@ -0,0 +1,9 @@
+import { Handler } from '../transports';
+import { CacheManager, PluginRegistry, SSRServer, SSRServerConfig } from '@plitzi/sdk-shared';
+export interface HttpServerParts {
+    label: string;
+    cache: CacheManager | null;
+    plugins: PluginRegistry;
+    onDestroy?: () => void;
+}
+export declare const createHttpServer: (config: SSRServerConfig, makeHandlerForPort: (port: number) => Handler, parts: HttpServerParts) => SSRServer;

package/dist/src/core/server/mcpServer.d.ts

@@ -0,0 +1,2 @@
+import { SSRServer, SSRServerConfig } from '@plitzi/sdk-shared';
+export declare const createMCPServer: (config: SSRServerConfig) => SSRServer;

package/dist/src/core/server/ssrServer.d.ts

@@ -0,0 +1,2 @@
+import { SSRServer, SSRServerConfig } from '@plitzi/sdk-shared';
+export declare const createSSRServer: (config: SSRServerConfig) => SSRServer;

package/dist/src/core/services/mcp.d.ts

@@ -0,0 +1,3 @@
+import { Stage } from '../http/types';
+export declare const mcpStage: Stage;
+export declare const mcpOnlyStage: Stage;

package/dist/src/core/services/preview.d.ts

@@ -0,0 +1,2 @@
+import { SSRContext, Stage } from '../http/types';
+export declare const previewStage: Stage<SSRContext>;

package/dist/src/core/services/registry.d.ts

@@ -0,0 +1,4 @@
+import { ResolvedServices } from './resolve';
+import { BaseContext, SSRContext, Stage } from '../http/types';
+export declare const buildSSRPipeline: (services: ResolvedServices) => Stage<SSRContext>[];
+export declare const buildMCPPipeline: () => Stage<BaseContext>[];

package/dist/src/core/services/resolve.d.ts

@@ -0,0 +1,3 @@
+import { ServerServices, SSRServerConfig } from '@plitzi/sdk-shared';
+export type ResolvedServices = Required<ServerServices>;
+export declare const resolveServices: (config: SSRServerConfig) => ResolvedServices;

package/dist/src/core/services/rsc.d.ts

@@ -0,0 +1,2 @@
+import { SSRContext, Stage } from '../http/types';
+export declare const rscStage: Stage<SSRContext>;

package/dist/src/core/services/ssr.d.ts

@@ -0,0 +1,3 @@
+import { SSRContext, Stage } from '../http/types';
+export declare const ssrStage: Stage<SSRContext>;
+export declare const notFoundStage: Stage;

package/dist/src/core/transports.d.ts

@@ -6,13 +6,13 @@ export type CloseableServer = {
     listen: (port: number, host: string, cb: () => void) => unknown;
 };
 export type Handler = (req: IncomingMessage, res: RawResponse) => void;
-export declare const tlsOptions: (config: SSRServerConfig) => {
+export declare const tlsOptions: (config: SSRServerConfig, label?: string) => {
     key: string | Buffer<ArrayBufferLike>;
     cert: string | Buffer<ArrayBufferLike>;
     minVersion: "TLSv1.3";
 };
 export declare const protoLabel: (version: number, hasTls: boolean) => string;
-export declare const buildTransport: (config: SSRServerConfig, handler: Handler, port: number) => {
+export declare const buildTransport: (config: SSRServerConfig, handler: Handler, port: number, label?: string) => {
     primary: CloseableServer;
     h3?: CloseableServer;
 };

package/dist/src/index.d.ts

@@ -1,5 +1,14 @@
-export { createSSRServer } from './core/createServer';
+export { createServer, createSSRServer, createMCPServer, resolveServices } from './core/createServer';
+export { registerHealthCheck, buildHealthPayload } from './core/health';
+export type { HealthCheckApp, HealthIdentity } from './core/health';
 export { createJsonAdapters } from './adapters/jsonAdapters';
-export { tools, toolResponseOk, toolResponseErr, readMcpBody, handleMcp, createMcpServer, zodToJsonSchema, getAllowedModes, bindTools, isToolActive, resolveToolHandler } from './modules/mcp';
-export { AIEngine } from './modules/ai';
+export { AIEngine, toolResponseOk, toolResponseErr, zodToJsonSchema, getAllowedModes, bindTools, isToolActive, resolveToolHandler, isCallToolResult, toolResponseFromResult } from './modules/ai';
+export { createMcpServer, handleMcp, serveMcp, readMcpBody, createHttpPreviewClient, createHttpScreenshotClient } from './modules/mcp';
+export { createPreview, createMemoryDraftStore, PREVIEW_TOKEN_PARAM } from './modules/ssr/preview';
+export { apply, search, read, validate, applyShape, searchShape, readShape, validateShape, operation, tools } from './modules/mcp/tools';
 export type { JsonAdaptersConfig } from './adapters/jsonAdapters';
+export type { ResolvedServices } from './core/createServer';
+export type { McpServerContext, PreviewClient, PreviewRequestBody, PreviewResult, HttpPreviewClientConfig, ScreenshotClient, ScreenshotImage, ScreenshotResult, Viewport, HttpScreenshotClientConfig } from './modules/mcp';
+export type { ApplyInput, SearchInput, SearchResponse, SearchHit, ReadInput, ReadResponse, ReadHit, ValidateInput, WriteResponse, WriteElement, Persisters, Operation, ToolDef, ToolContext } from './modules/mcp/tools';
+export type { Space } from './modules/mcp/helpers';
+export type { Env } from './modules/mcp/types';

package/dist/src/modules/ai/index.d.ts

@@ -1,3 +1,4 @@
 import { default as AIEngine } from './AIEngine';
 export * from './AIEngine';
+export { zodToJsonSchema, getAllowedModes, toolResponseOk, toolResponseErr, bindTools, isToolActive, resolveToolHandler, isCallToolResult, toolResponseFromResult } from './toolkit';
 export { AIEngine };

package/dist/src/modules/ai/toolkit.d.ts

@@ -0,0 +1,17 @@
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { AiMode, McpContent, McpTool, McpToolHandler, McpToolHandlerResult, ToolOperationType } from '@plitzi/sdk-shared';
+/** Convert a Zod schema to the JSON Schema an AI provider (Anthropic / OpenAI) expects in a tool definition.
+ *  Delegates to Zod v4's built-in converter — one implementation, so descriptions, literal discriminators,
+ *  enums, nested objects and recursive (z.lazy) shapes all survive and the provider sees the same contract an
+ *  MCP client does. `io: 'input'` describes what the agent must SEND; `unrepresentable: 'any'` degrades an
+ *  exotic type to an empty schema instead of throwing, so one unusual tool never breaks the whole tool list. */
+export declare const zodToJsonSchema: (schema: unknown) => Record<string, unknown>;
+export declare const firstText: (content: McpContent[]) => string | undefined;
+export declare const getAllowedModes: (operationType: ToolOperationType) => AiMode[];
+export declare const toolResponseOk: (data: unknown, agentMessage?: string) => McpToolHandlerResult;
+export declare const toolResponseErr: (error: Error | string) => McpToolHandlerResult;
+export declare const isCallToolResult: (result: unknown) => result is CallToolResult;
+export declare const toolResponseFromResult: (result: CallToolResult) => McpToolHandlerResult;
+export declare const isToolActive: (tool: McpTool) => boolean;
+export declare const resolveToolHandler: (tool: McpTool) => McpToolHandler | undefined;
+export declare const bindTools: (tools: McpTool[]) => McpTool[];

package/dist/src/modules/mcp/constants.d.ts

@@ -0,0 +1 @@
+export declare const PREVIEW_TOKEN_PARAM = "__pt";

package/dist/src/modules/mcp/handler.d.ts

@@ -1,6 +1,9 @@
-import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp';
+import { createMcpServer } from './server';
+import { PreviewClient, ScreenshotClient } from './types';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp';
-import { McpServerConfig, AiContext } from '@plitzi/sdk-shared';
+import { SSRAdapters, SSRRequest } from '@plitzi/sdk-shared';
 import { IncomingMessage, ServerResponse } from 'node:http';
 export declare const readMcpBody: (req: IncomingMessage) => Promise<unknown>;
-export declare const handleMcp: (req: IncomingMessage, res: ServerResponse, config: McpServerConfig, server?: McpServer, transport?: StreamableHTTPServerTransport, context?: AiContext) => Promise<void>;
+export declare const serveMcp: (raw: IncomingMessage, res: ServerResponse, server: McpServer) => Promise<void>;
+export declare const handleMcp: (raw: IncomingMessage, res: ServerResponse, req: SSRRequest, adapters: SSRAdapters, preview?: PreviewClient, screenshot?: ScreenshotClient) => Promise<void>;
+export { createMcpServer };

package/dist/src/modules/mcp/helpers/computeVersion.d.ts

@@ -0,0 +1 @@
+export declare const computeVersion: (data: unknown) => string;

package/dist/src/modules/mcp/helpers/guide.d.ts

@@ -0,0 +1,2 @@
+export declare const serverInstructions: string;
+export declare const guideText = "# Plitzi AI MCP \u2014 usage guide\n\nA Plitzi space is **two separate schemas** you edit together:\n- **Element schema** \u2014 the tree of pages and elements (their type, label, props, and which style classes they use).\n- **Style schema** \u2014 reusable **definitions** (CSS classes), design tokens (variables), theme.\n\nThey are stored and persisted independently, but a single `plitzi_apply` batch may touch **both atomically**.\nTo style a specific element you do two things in one batch: write a **definition** (style schema) and **attach**\nit via the element's `style.base` (element schema). Example \u2014 \"rename button X to PEPE and make it red\":\n```json\n{ \"operations\": [\n  { \"type\": \"upsertDefinition\", \"ref\": \"btn-x\", \"desktop\": { \"color\": \"red\" } },\n  { \"type\": \"upsertElement\", \"pageRef\": \"home\",\n    \"element\": { \"ref\": \"X\", \"type\": \"button\", \"label\": \"PEPE\", \"style\": { \"base\": [\"btn-x\"] } } }\n] }\n```\n\nReads are cheap by design \u2014 treat them like a filesystem: **list** to navigate, **read one item** for detail.\nNever download a whole tree you do not need.\n\n## Resources (read)\n- `plitzi://primer/{env}` \u2014 **cold-start bundle**: guide + types + css-properties + page/definition/variable\n  **summaries** in one read. Fetch this first instead of the individual resources below. Summaries only \u2014 open a\n  page skeleton or element for its tree/detail.\n- `plitzi://guide` \u2014 this guide.\n- `plitzi://types` \u2014 element types **observed in this space** (ground truth): props, slots, subTypes.\n- `plitzi://css-properties` \u2014 valid kebab-case CSS property keys.\n- `plitzi://schema/{env}/pages` \u2014 page **summaries** (ref, label, elementCount, folder). No element trees.\n- `plitzi://folders/{env}` \u2014 page **folders** (the sidebar tree): ref, name, slug, parentId. `/{ref}` for one.\n- `plitzi://schema/{env}/pages/{ref}` \u2014 one page as a **skeleton tree**: each node is `ref/type/label` **plus the\n  style classes it attaches** (`base`, and `slots` for non-base slots) \u2014 names only, no CSS. So you can map every\n  element to its class in a single page read, without opening each element just to learn which class it uses.\n- `plitzi://schema/{env}/pages/{ref}/styles` \u2014 **every style the page uses in one read**: the class definitions its\n  elements attach (deduplicated, **with full CSS**) plus the global styles affecting any element type on the page.\n  Reach for this to recolor/restyle a whole page \u2014 it needs no shared class-name prefix and no per-element reads.\n- `plitzi://schema/{env}/elements/{ref}` \u2014 one element in **full detail** (props, style, parentRef, childRefs).\n  Its `resolvedStyle` inlines the **CSS of every definition** the element attaches (keyed by class ref), so you\n  can see and edit its style without a separate definition read. Its `globalStyles` lists the **global element\n  selectors** that also affect it (the CSS equivalent of `button { \u2026 }`, keyed by the type they target) \u2014 every\n  element of that type inherits them. Edit a global only through the global-style tools (never per element).\n- `plitzi://definitions/{env}` \u2014 the **names** of every style definition.\n- `plitzi://definitions/{env}/{ref}` \u2014 one definition's CSS.\n- `plitzi://global-styles/{env}` \u2014 element **types** that have a site-wide global style. `/{componentType}` for one.\n- `plitzi://style-variables/{env}` \u2014 design tokens by category. `/{category}` for one.\n- `plitzi://schema-variables/{env}` \u2014 space-level values referenced in props as `{{name}}`.\n\nThe style resources also answer under the `plitzi://schema/{env}/\u2026` root as aliases \u2014 `plitzi://schema/{env}/definitions/{ref}`, `plitzi://schema/{env}/style-variables/{category}`, `plitzi://schema/{env}/schema-variables` \u2014 but prefer the ready-made `uri` from search / a write response over hand-building either form.\n\nData resources return `{ stateVersion, data }`. Keep `stateVersion` for optimistic concurrency.\n\n## Navigating (files analogy)\nPages and containers are folders; elements are files. **Prefer `plitzi_search` (especially with `include: \"detail\"`)\nover reading elements one by one** \u2014 it jumps straight to elements by label/type/attribute and each hit already\ncarries the element's `uri`, `stateVersion`, `pageUri`, `parentRef` and tree `path`, so you can edit it (with\noptimistic concurrency) **without a follow-up read**. `include: \"detail\"` additionally inlines each hit's props/style\n**and** its `resolvedStyle` (the CSS behind its classes) \u2014 so a search-then-edit is the efficient path and a manual\nelement read is the exception. Search also matches **pages** by name/slug (returned under `pages`, each with its uri +\nstateVersion) and returns any **style definitions** whose name matches the query, with full CSS, under `definitions`.\nWhen you do hold several refs to open (e.g. from a skeleton), read them together with `plitzi_read` rather than one at a time.\n\n## Tools (write)\n- `plitzi_validate` \u2014 check a batch, returns teachable errors/warnings. Writes nothing.\n- `plitzi_apply` \u2014 validate \u2192 apply \u2192 persist atomically. Rejects the whole batch on any error or conflict. Pass\n  `dryRun: true` to apply in memory only and get the same result back (changed versions + full element detail)\n  without persisting \u2014 inspect it, then re-run without `dryRun` to commit.\n- `plitzi_search` \u2014 find elements (and pages/definitions) across the space.\n- `plitzi_read` \u2014 read many resource **uris in one batch** (pages, elements, definitions, variables). Pass the\n  ready-made uris from search / a write response; each result is `{ uri, stateVersion, data }` or a teachable error,\n  so one bad uri never fails the batch. Use it instead of N single reads whenever you already hold several refs.\n\nWrite tools return what **changed** (`{ uri, stateVersion }`) plus counts, and the **full detail of every element\nthey created or updated** \u2014 each with its own `uri` and `stateVersion` (`elements: [...]`) so a follow-up edit of\nthe same element needs **no intermediate read**. Other resources (pages, definitions, variables) still report only\nuri+stateVersion \u2014 re-read them if you need their new content. The operation shapes are in each tool's input\nschema (discriminated by `type`).\n\n## Addressing\nRefs are a semantic `aiRef` you choose (e.g. `\"hero.cta\"`) or the element's **raw id**. Both always resolve, so\nschemas predating aiRef keep working through ids. Creating an element stores its `ref` as the aiRef.\n\n## Styling (crosses both schemas)\n- A definition lives in the **style schema**; an element's `style.base` (element schema) is the link that applies\n  it. Styling an element = upsertDefinition + upsertElement with that ref in `style.base`, in one batch.\n- CSS keys are **kebab-case** (`background-color`). camelCase is rejected \u2014 read `plitzi://css-properties`.\n- Common **shorthands are accepted** and expanded for you: `border`, `border-{side}`, `border-radius`,\n  `padding`, `margin`, `inset`, `gap` (they persist as their longhand keys).\n- CSS is grouped by breakpoint: `desktop`, `tablet`, `mobile`.\n- Reference a style variable in CSS as `var(--name)`; a schema variable in a prop as `{{name}}`.\n- `element.style.base` is a list of definition refs; other slots go under `element.style.slots`.\n- **Two kinds of style live in the style schema \u2014 do not confuse them:**\n  - **Definitions** = reusable CSS **classes** (`upsertDefinition`/`patchDefinition`/`deleteDefinition`, keyed by a\n    class `ref`). Attach one to an element via `style.base` to style **that** element (and anything else that opts in).\n  - **Global styles** = the CSS equivalent of a bare element selector like `button { \u2026 }`\n    (`upsertGlobalStyle`/`patchGlobalStyle`/`deleteGlobalStyle`, keyed by `componentType`). They style **every**\n    element of that type at once. Use these for site-wide intent \u2014 e.g. \"all buttons rounded\":\n    `{ \"type\": \"upsertGlobalStyle\", \"componentType\": \"button\", \"desktop\": { \"border-radius\": \"9999px\" } }`.\n  - The two share one name space, so a class op refuses a name held by a global and vice-versa (guards against a\n    typo silently rewriting every element of a type). If refused, you targeted the wrong kind \u2014 switch tools or\n    rename. To style one element only, never reach for a global.\n\n## Pages & folders\nPages can be grouped into **folders** (the sidebar tree). A folder is `{ ref, name, slug, parentId? }`; its `ref`\n**is its id** (there is no separate aiRef), and that id is what a page and a nested folder reference.\n- Create/rename/move a folder with `upsertFolder` (the `ref` you pass on create becomes its id \u2014 pick a stable one\n  like `\"blog\"`). Nest it under another with `parentId` (a folder ref); `parentId: null` moves it back to the root.\n- Put a page in a folder with `upsertPage`'s `folder` (a folder ref). A page's `folder` is always either **empty\n  (root)** or an **existing folder id**: `folder: null` or `folder: \"\"` moves it to the root, and any other value\n  must resolve to a folder that already exists or is created earlier in the same batch \u2014 an unknown folder is\n  rejected, never stored.\n- `deleteFolder` removes a folder and **promotes its contents up one level** \u2014 its child folders and its pages move\n  to its parent (or the root). A folder cannot be nested under itself or one of its descendants.\n\n## Semantics\n- **props are fully replaced** on `upsertElement`: send every prop you want to keep. To change only some props,\n  use **`patchElement`** \u2014 it merges `props`/`style` onto the existing element (listed keys change, `null` unsets\n  a key, everything else is preserved) and never creates. Combined with `plitzi_search` (which returns the ref +\n  stateVersion), a targeted edit is two calls with no read.\n- **definition CSS is fully replaced** on `upsertDefinition`: send every property you want to keep. To change only\n  some declarations, use **`patchDefinition`** \u2014 it merges CSS per breakpoint/state/variant/slot onto the existing\n  definition (listed keys change, `null` removes a property, everything else is preserved) and never creates.\n  Example \u2014 recolor one definition without resending it: `{ \"type\": \"patchDefinition\", \"ref\": \"btn-x\",\n  \"desktop\": { \"background-color\": \"#111\" } }`.\n- **Atomic batches**: if any operation fails, `plitzi_apply` persists nothing.\n- **Optimistic concurrency**: pass `expectedResourceVersions` (URI \u2192 the stateVersion you read). If the live data\n  drifted, apply is rejected with a conflict; re-read the reported resources and retry.\n";

package/dist/src/modules/mcp/helpers/index.d.ts

@@ -0,0 +1,4 @@
+export * from './computeVersion';
+export * from './space';
+export * from './guide';
+export * from './opResult';

package/dist/src/modules/mcp/helpers/opResult.d.ts

@@ -0,0 +1,13 @@
+import { ValidationError } from '../types';
+/** The result of one mutation handler: counts, the resource URIs it invalidated, any error, and the refs of
+ *  elements it created/updated (so the caller can return their full detail as context — never for deletes). */
+export interface OpResult {
+    errors?: ValidationError[];
+    created: number;
+    updated: number;
+    deleted: number;
+    staleResources: string[];
+    elementRefs?: string[];
+}
+export declare const empty: () => OpResult;
+export declare const fail: (path: string, message: string, hint: string, validValues?: unknown[]) => OpResult;

package/dist/src/modules/mcp/helpers/space.d.ts

@@ -0,0 +1,49 @@
+import { Element, PageFolder, Schema, Style } from '@plitzi/sdk-shared';
+/** The working view the tools read and mutate: the two Plitzi schemas (elements + style), which the platform
+ *  stores and persists as separate documents (Space model / Style model). */
+export interface Space {
+    schema: Schema;
+    style: Style;
+}
+export declare const cloneSpace: (space: Space) => Space;
+export declare const slugify: (value: string) => string;
+export declare const isPageElement: (schema: Schema, el: Element) => boolean;
+export declare const getPageElements: (schema: Schema) => Element[];
+/** Stable, human-readable ref for a page. Prefers an agent-chosen aiRef, then slug, then a slugified label. */
+export declare const pageRefOf: (el: Element) => string;
+/** Stable ref for a non-page element. An agent-chosen aiRef when present, otherwise the opaque id. */
+export declare const elementRefOf: (el: Element) => string;
+/** Finds a page by its semantic ref (aiRef/slug/…) or its raw id, so legacy schemas without an aiRef still resolve. */
+export declare const findPageByRef: (schema: Schema, pageRef: string) => Element | undefined;
+export declare const pageFoldersOf: (schema: Schema) => PageFolder[];
+/** Resolve a folder by its id, or (for agent convenience) by an exact name or slug when that is unambiguous. */
+export declare const findFolderByRef: (schema: Schema, ref: string) => PageFolder | undefined;
+/** Order folders so every parent precedes its children — the invariant the schema validator enforces on
+ *  pageFolders (a parentId must appear earlier in the array). Cycles (rejected upstream) are left in place. */
+export declare const sortFolders: (folders: PageFolder[]) => PageFolder[];
+/** Ancestor ids of a folder (following parentId), stopping on a cycle. Used to reject a parent change that would
+ *  make a folder its own ancestor. */
+export declare const folderAncestorIds: (folders: PageFolder[], startParentId: string | undefined) => string[];
+/** Route params a page's slug binds (e.g. ":spaceId/update/*" → ["spaceId"]). These are valid {{name}}
+ *  references on that page even though they are not space-level schema variables. */
+export declare const slugRouteParams: (slug: string) => string[];
+/** Every route param bound by any page slug in the space (union), so {{name}} validation does not false-flag a
+ *  page-scoped dynamic binding. */
+export declare const routeParamNames: (schema: Schema) => string[];
+/** Indexed lookup that reflects the runtime reality: a flat id may be dangling (rsc placeholders, stale items). */
+export declare const elementById: (schema: Schema, id: string) => Element | undefined;
+export declare const descendantIds: (schema: Schema, pageRootId: string) => string[];
+/** Resolve a ref to a concrete element within a page subtree (or the page root itself). Accepts either the
+ *  semantic ref (aiRef) or the raw element id, so schemas predating aiRef keep working through their ids. */
+export declare const resolveRef: (schema: Schema, page: Element, ref: string) => Element | undefined;
+/** Ordered children of an element, honoring definition.items and skipping dangling ids. */
+export declare const orderedChildren: (schema: Schema, el: Element) => Element[];
+/** The page ref an element belongs to, walking up parents. 'unknown' when it has no page ancestor. */
+export declare const pageRefOfElement: (schema: Schema, el: Element) => string;
+/** Find any non-page element by its semantic ref (aiRef) or raw id, across the whole space. */
+export declare const findElementByRef: (schema: Schema, ref: string) => Element | undefined;
+/** Total number of descendant elements under a subtree (excluding the root). */
+export declare const descendantCount: (schema: Schema, rootId: string) => number;
+export declare const emptySpaceMessage = "Space data not available";
+export declare const unauthorizedSpaceMessage = "This tool/resource needs a space, but no spaceId could be resolved from the Authorization token";
+export declare const generateObjectId: () => string;

package/dist/src/modules/mcp/index.d.ts

@@ -1,5 +1,12 @@
-import * as tools from './tools';
-export { readMcpBody, handleMcp } from './handler';
-export { createMcpServer } from './server';
-export { zodToJsonSchema, getAllowedModes, toolResponseOk, toolResponseErr, bindTools, isToolActive, resolveToolHandler } from './helpers';
-export { tools };
+export { createMcpServer, handleMcp, serveMcp, readMcpBody } from './handler';
+export { readResource, resourceVersion, registerResources, buildTypeRegistry, cssProperties } from './resources';
+export { apply, validate, search, read, validateOperations, operation, tools } from './tools';
+export { computeVersion } from './helpers';
+export { createHttpPreviewClient } from './previewClient';
+export { createHttpScreenshotClient } from './screenshotClient';
+export type { HttpPreviewClientConfig } from './previewClient';
+export type { HttpScreenshotClientConfig } from './screenshotClient';
+export type { McpServerContext } from './server';
+export type { ApplyInput, WriteResponse, Persisters, SearchInput, ReadInput, ReadResponse, ValidateInput, Operation, ToolDef, ToolContext } from './tools';
+export type { Space } from './helpers';
+export type * from './types';

package/dist/src/modules/mcp/previewClient.d.ts

@@ -0,0 +1,13 @@
+import { PreviewClient } from './types';
+export type HttpPreviewClientConfig = {
+    /** Absolute URL of the SSR `/preview` endpoint. */
+    url: string;
+    /** Shared secret sent as `x-preview-secret`; must match the SSR server's `preview.secret`. */
+    secret?: string;
+    /** Injectable fetch (tests / non-global runtimes). Defaults to the global fetch. */
+    fetchImpl?: typeof fetch;
+};
+/** Default `PreviewClient`: POSTs the preview request to the SSR `/preview` endpoint over HTTP. Used when the
+ *  MCP server is a separate process from the SSR renderer (the common case). A network/HTTP failure surfaces as
+ *  an `ok:false` result rather than throwing, so the calling tool can degrade gracefully. */
+export declare const createHttpPreviewClient: ({ url, secret, fetchImpl }: HttpPreviewClientConfig) => PreviewClient;

package/dist/src/modules/mcp/resources/canonical.d.ts

@@ -0,0 +1,7 @@
+import { Env } from '../types';
+export declare const canonicalUri: (env: Env, uri: string) => string;
+export declare const itemTemplates: (env: Env) => string[];
+/** Teachable message for a URI that read as null. Distinguishes a well-formed URI whose ref does not resolve (the
+ *  resource may be stale/deleted) from a URI whose shape matches no template at all (malformed — echo the valid
+ *  templates so the agent stops hand-building URIs). See RFC 0004 I2. */
+export declare const resourceErrorMessage: (env: Env, uri: string) => string;

package/dist/src/modules/mcp/resources/core.d.ts

@@ -0,0 +1,5 @@
+import { Space } from '../helpers';
+import { ResourceEnvelope } from '../types';
+/** Space-independent singletons: the usage guide, the observed type registry and the CSS property catalog.
+ *  Returns undefined when the URI is not one of these, so the router falls through to the next resolver. */
+export declare const readCoreResource: (space: Space, uri: string) => ResourceEnvelope<unknown> | undefined;

package/dist/src/modules/mcp/resources/envelope.d.ts

@@ -0,0 +1,10 @@
+import { ResourceEnvelope } from '../types';
+/** Wrap any read projection with the version its optimistic-concurrency checks key on. */
+export declare const envelope: <T>(data: T) => ResourceEnvelope<T>;
+export declare const jsonContents: (uri: string, data: unknown) => {
+    contents: {
+        uri: string;
+        mimeType: string;
+        text: string;
+    }[];
+};

package/dist/src/modules/mcp/resources/index.d.ts

@@ -1,10 +1,8 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp';
-import { McpResource } from '@plitzi/sdk-shared';
-export declare const registerResources: (server: McpServer, custom?: McpResource[], onRead?: (name: string, uri: string) => void) => void;
-export declare const allResources: McpResource[];
-export declare const getResourceList: () => {
-    uri: string;
-    name: string;
-    description: string;
-}[];
-export declare const getResourceByUri: (uri: string) => McpResource | undefined;
+export { readResource, resourceVersion } from './router';
+export { registerResources } from './register';
+export { resourceErrorMessage } from './canonical';
+export { buildTypeRegistry } from '../tools/operations/schema/registry';
+export type { TypeInfo, TypePropInfo, TypeRegistry } from '../tools/operations/schema/registry';
+export * from '../tools/operations/schema/translator';
+export { cssProperties, expandShorthand, isCssProperty, suggestCssProperty } from '../tools/operations/style/cssCatalog';
+export * from '../tools/operations/style/translator';

package/dist/src/modules/mcp/resources/primer.d.ts

@@ -0,0 +1,6 @@
+import { Space } from '../helpers';
+import { Env, ResourceEnvelope } from '../types';
+/** The cold-start bundle: everything the guide says to read before the first write, in one round-trip.
+ *  Summaries only — never full page/element trees (those are opened on demand), so it stays cheap even on a
+ *  large space. Returns undefined when the URI is not the primer. */
+export declare const readPrimerResource: (space: Space, env: Env, uri: string) => ResourceEnvelope<unknown> | undefined;

package/dist/src/modules/mcp/resources/register.d.ts

@@ -0,0 +1,6 @@
+import { Space } from '../helpers';
+import { Env } from '../types';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp';
+/** Register every resource on the MCP server: fixed listings plus templated per-item reads. The space is
+ *  loaded lazily via getSpace, so listing resources never touches the store — only reading one does. */
+export declare const registerResources: (server: McpServer, getSpace: () => Promise<Space>, env: Env) => void;

package/dist/src/modules/mcp/resources/router.d.ts

@@ -0,0 +1,6 @@
+import { Space } from '../helpers';
+import { Env, ResourceEnvelope } from '../types';
+/** Resolve a resource URI to its versioned envelope, or null if unknown / not found. */
+export declare const readResource: (space: Space, env: Env, rawUri: string) => ResourceEnvelope<unknown> | null;
+/** Current version of a resource, for optimistic-concurrency checks. Null when the URI is unknown. */
+export declare const resourceVersion: (space: Space, env: Env, uri: string) => string | null;

package/dist/src/modules/mcp/resources/schema.d.ts

@@ -0,0 +1,5 @@
+import { Space } from '../helpers';
+import { Env, ResourceEnvelope } from '../types';
+/** Element-schema reads: page listings/skeletons/styles, folders, single elements and schema variables. Returns
+ *  undefined when the URI belongs to another domain, null when the shape is ours but the ref does not resolve. */
+export declare const readSchemaResource: (space: Space, env: Env, uri: string) => ResourceEnvelope<unknown> | null | undefined;

package/dist/src/modules/mcp/resources/style.d.ts

@@ -0,0 +1,5 @@
+import { Space } from '../helpers';
+import { Env, ResourceEnvelope } from '../types';
+/** Style-schema reads: definitions, global (per-type) styles and design-token variables by category. Returns
+ *  undefined when the URI belongs to another domain, null when the shape is ours but the ref does not resolve. */
+export declare const readStyleResource: (space: Space, env: Env, uri: string) => ResourceEnvelope<unknown> | null | undefined;

package/dist/src/modules/mcp/screenshotClient.d.ts

@@ -0,0 +1,13 @@
+import { ScreenshotClient } from './types';
+export type HttpScreenshotClientConfig = {
+    /** Browser service that turns a URL into PNG(s): POST { url, viewports } → { images }. */
+    serviceUrl: string;
+    /** SSR base the browser navigates to; the page path and the one-shot `__pt` token are appended. */
+    renderBaseUrl: string;
+    /** Injectable fetch (tests / non-global runtimes). Defaults to the global fetch. */
+    fetchImpl?: typeof fetch;
+};
+/** Default `ScreenshotClient`: composes the navigable preview URL (renderBaseUrl + pagePath + `?__pt=token`) and
+ *  POSTs it to the browser service. Any network/HTTP failure surfaces as `ok:false` so the tool can fall back to
+ *  the HTML preview instead of hard-failing. */
+export declare const createHttpScreenshotClient: ({ serviceUrl, renderBaseUrl, fetchImpl }: HttpScreenshotClientConfig) => ScreenshotClient;

package/dist/src/modules/mcp/server.d.ts

@@ -1,4 +1,19 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp';
-import { default as AIEngine } from '../ai/AIEngine';
-import { McpAdapters, McpTool, McpPrompt, McpResource } from '@plitzi/sdk-shared';
-export declare const createMcpServer: (adapters: Partial<McpAdapters> | undefined, engine: AIEngine, tools?: McpTool[], prompts?: McpPrompt[], resources?: McpResource[]) => McpServer;
+import { PreviewClient, ScreenshotClient } from './types';
+import { SSRAdapters } from '@plitzi/sdk-shared';
+/** The MCP service is stateless: every request resolves its own `spaceId` (from the request JWT) and reads the
+ *  space fresh through the adapters — schema and style are two documents, read/written independently. Both the
+ *  spaceId and the space itself resolve lazily, so the public surface (handshake, tools-list, resources-list,
+ *  and the space-independent guide / css-properties resources) works even when the request carries no auth —
+ *  only a space-dependent tool/resource demands a spaceId, failing with `unauthorizedSpaceMessage` if none. */
+export interface McpServerContext {
+    adapters: SSRAdapters;
+    getSpaceId: () => Promise<number | undefined>;
+    /** How the visual-preview tools (plitzi_preview / plitzi_screenshot) reach the renderer. Absent → those tools
+     *  report PREVIEW_UNAVAILABLE, so an MCP-only deployment without a renderer still runs every other tool. */
+    preview?: PreviewClient;
+    /** The dedicated browser service for plitzi_screenshot. Absent → the tool is not registered (only the HTML
+     *  plitzi_preview is offered). */
+    screenshot?: ScreenshotClient;
+}
+export declare const createMcpServer: ({ adapters, getSpaceId, preview, screenshot }: McpServerContext) => McpServer;

package/dist/src/modules/mcp/tools/apply/dispatch.d.ts

@@ -0,0 +1,6 @@
+import { Space } from '../../helpers';
+import { Env, MutationOutcome } from '../../types';
+import { Operation } from '../operations';
+/** Apply operations in order to the space (mutating it). Records which schema(s) changed so the caller can
+ *  persist each independently. Stops collecting counts for a failed op but records its errors. */
+export declare const applyOperations: (space: Space, env: Env, ops: Operation[]) => MutationOutcome;