@plitzi/sdk-server 0.32.4 → 0.32.6

package/dist/modules/ssr/preview.js

@@ -0,0 +1,106 @@
+import { computeVersion } from "../mcp/helpers/computeVersion.js";
+import { cloneSpace, findPageByRef, getPageElements } from "../mcp/helpers/space.js";
+import { applyOperations } from "../mcp/tools/apply/dispatch.js";
+import { validateOperations } from "../mcp/tools/shared/validator/index.js";
+import { PREVIEW_TOKEN_PARAM } from "../mcp/constants.js";
+import { buildBody } from "./buildBody.js";
+import { randomUUID } from "node:crypto";
+//#region src/modules/ssr/preview.ts
+/** In-memory one-shot draft store — the default when the consumer injects none. Fine for a single replica;
+*  a multi-replica deployment must inject a shared store so a preview URL resolves on any replica. */
+var createMemoryDraftStore = () => {
+	const store = /* @__PURE__ */ new Map();
+	return {
+		put(token, data, ttlMs) {
+			store.set(token, {
+				data,
+				expiresAt: Date.now() + ttlMs
+			});
+		},
+		take(token) {
+			const hit = store.get(token);
+			if (!hit) return;
+			store.delete(token);
+			return hit.expiresAt > Date.now() ? hit.data : void 0;
+		}
+	};
+};
+/** Consume the draft override for a render, if the request carries a valid preview token. Returns undefined on
+*  a normal request (renders persisted state) or when the token is unknown/expired (one-shot / TTL). */
+var takeDraftOverride = async (req, config) => {
+	const token = req.query[PREVIEW_TOKEN_PARAM];
+	if (!token || !config.draftStore) return;
+	return config.draftStore.take(token);
+};
+var resolvePagePath = (schema, pageRef) => {
+	const pages = getPageElements(schema);
+	const page = pageRef ? findPageByRef(schema, pageRef) : pages.find((p) => p.attributes.default) ?? pages[0];
+	const slug = page && typeof page.attributes.slug === "string" ? page.attributes.slug : "";
+	return slug.startsWith("/") ? slug : `/${slug}`;
+};
+var syntheticRequest = (pagePath) => ({
+	method: "GET",
+	path: pagePath,
+	search: "",
+	url: pagePath,
+	hostname: "localhost",
+	protocol: "https",
+	headers: {},
+	query: {},
+	ctx: {}
+});
+/** Build a preview of a page: apply any unsaved `operations` to a clone (never persisted), render the resulting
+*  draft to full HTML via the SSR pipeline, and stash the draft under a one-shot token so a browser can fetch
+*  the exact same render at `?__pt=<token>` (for screenshots). With no operations it previews persisted state. */
+var createPreview = async (body, config, renderFn, pluginManager, caches) => {
+	const env = body.env ?? "main";
+	const revision = 0;
+	const offlineData = await config.adapters.getOfflineData(body.spaceId, env, revision);
+	if (!offlineData) return {
+		ok: false,
+		error: "NO_DATA",
+		message: `No offline data for space ${body.spaceId} (${env}).`
+	};
+	let draftOffline = offlineData;
+	if (body.operations && body.operations.length > 0) {
+		const draft = cloneSpace({
+			schema: offlineData.schema,
+			style: offlineData.style
+		});
+		const validation = validateOperations(draft, body.operations);
+		if (!validation.valid) return {
+			ok: false,
+			error: "INVALID_OPERATIONS",
+			message: "The operations did not validate.",
+			errors: validation.errors
+		};
+		const outcome = applyOperations(draft, env, body.operations);
+		if (outcome.errors.length > 0) return {
+			ok: false,
+			error: "APPLY_FAILED",
+			message: "The operations could not be applied.",
+			errors: outcome.errors
+		};
+		draftOffline = {
+			...offlineData,
+			schema: draft.schema,
+			style: draft.style
+		};
+	}
+	const pagePath = resolvePagePath(draftOffline.schema, body.pageRef);
+	const { body: html } = await buildBody(syntheticRequest(pagePath), config, body.spaceId, env, revision, renderFn, pluginManager, caches.offlineData, void 0, draftOffline);
+	let token;
+	if (config.draftStore) {
+		token = randomUUID();
+		await config.draftStore.put(token, draftOffline, config.preview?.ttlMs ?? 6e4);
+	}
+	return {
+		ok: true,
+		token,
+		pagePath,
+		html: html ?? "",
+		stateVersion: computeVersion(draftOffline)
+	};
+};
+//#endregion
+export { PREVIEW_TOKEN_PARAM, createMemoryDraftStore, createPreview, takeDraftOverride };

package/dist/modules/ssr/registerExternalPlugins.js

@@ -1,6 +1,6 @@
-import path from "node:path";
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
+import path from "node:path";
 //#region src/modules/ssr/registerExternalPlugins.ts
 var MANIFEST_TTL_MS = 600 * 1e3;
 var manifestCache = /* @__PURE__ */ new Map();

package/dist/modules/ssr/streamBody.js

@@ -1,13 +1,13 @@
-import { applySSRResult } from "./applySSRResult.js";
 import Component from "./Component.js";
 import { prepareRender } from "./prepareRender.js";
+import { applySSRResult } from "./applySSRResult.js";
 import { renderToPipeableStream } from "react-dom/server";
 import { jsx } from "react/jsx-runtime";
 import { Writable } from "node:stream";
 //#region src/modules/ssr/streamBody.tsx
 var SSR_SENTINEL = "<!--SSR_CONTENT-->";
-var streamBody = async (req, res, config, spaceId, environment, revision, renderFn, pluginManager, offlineDataCache, htmlCache, cacheKey, metrics) => {
-	const prep = await prepareRender(req, config, spaceId, environment, revision, pluginManager, offlineDataCache, metrics);
+var streamBody = async (req, res, config, spaceId, environment, revision, renderFn, pluginManager, offlineDataCache, htmlCache, cacheKey, metrics, offlineDataOverride) => {
+	const prep = await prepareRender(req, config, spaceId, environment, revision, pluginManager, offlineDataCache, metrics, offlineDataOverride);
 	const templateStart = metrics ? performance.now() : 0;
 	const fullTemplate = renderFn({
 		...prep.templateParams,

package/dist/modules/ssr/template.js

@@ -1,6 +1,6 @@
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 import fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import ejs from "ejs";
 //#region src/modules/ssr/template.ts
 var __dirname = path.dirname(fileURLToPath(import.meta.url));

package/dist/modules/ssr/views/template.ejs

@@ -10,6 +10,7 @@
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://cdn.plitzi.com" />
 
+    <% if (!locals.ssrOnly) { %>
     <link rel="modulepreload" href="<%= locals.react || '' %>" crossorigin />
     <link rel="modulepreload" href="<%= locals.reactDom || '' %>" crossorigin />
 
@@ -25,6 +26,7 @@
         }
       }
     </script>
+    <% } %>
 
     <link
       rel="preload"

package/dist/plugins/compile.js

@@ -1,5 +1,5 @@
-import path from "node:path";
 import fs from "node:fs/promises";
+import path from "node:path";
 import esbuild from "esbuild";
 //#region src/plugins/compile.ts
 var EXTERNAL = [

package/dist/plugins/copy.js

@@ -1,5 +1,5 @@
-import path from "node:path";
 import fs from "node:fs/promises";
+import path from "node:path";
 //#region src/plugins/copy.ts
 var copyPlugin = async (src, destDir, filename) => {
 	const dest = path.join(destDir, filename);

package/dist/plugins/manager.js

@@ -1,8 +1,8 @@
 import { compilePlugin } from "./compile.js";
 import { copyPlugin } from "./copy.js";
 import { detectAction, isComponentSource } from "./detect.js";
-import path from "node:path";
 import fs from "node:fs/promises";
+import path from "node:path";
 //#region src/plugins/manager.ts
 var META_FILE = "meta.json";
 var DEFAULT_TTL_MS = 10080 * 60 * 1e3;

package/dist/server.js

@@ -1,20 +1,33 @@
-import { createSSRServer } from "./core/createServer.js";
+import { createSSRServer } from "./core/server/ssrServer.js";
 import path from "node:path";
+import { readFileSync, writeFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { readFileSync } from "node:fs";
 //#region src/standalone/server.ts
 var PORT = parseInt(process.env.SSR_PORT ?? "3002", 10);
 var HOST = process.env.SSR_HOST ?? "0.0.0.0";
+var spacePath = () => path.resolve(__dirname, "schemas/basic", "space.json");
+var stylePath = () => path.resolve(__dirname, "schemas/basic", "style.json");
+var readSchema = () => JSON.parse(readFileSync(spacePath(), "utf-8")).schema;
+var readStyle = () => JSON.parse(readFileSync(stylePath(), "utf-8"));
 var getOfflineData = () => {
-	const fileSchema = JSON.parse(readFileSync(path.resolve(__dirname, "schemas/basic", "space.json"), "utf-8"));
-	const style = JSON.parse(readFileSync(path.resolve(__dirname, "schemas/basic", "style.json"), "utf-8"));
 	const offlineData = {
-		schema: fileSchema.schema,
-		style
+		schema: readSchema(),
+		style: readStyle()
 	};
 	console.warn("[SSR] getOfflineData: using stub adapter — returning spaceId=1");
 	return Promise.resolve(offlineData);
 };
+var getSpaceId = () => Promise.resolve(1);
+var getSchema = () => Promise.resolve(readSchema());
+var getStyle = () => Promise.resolve(readStyle());
+var saveSchema = (_spaceId, _environment, schema) => {
+	writeFileSync(spacePath(), JSON.stringify({ schema }, null, 2));
+	return Promise.resolve();
+};
+var saveStyle = (_spaceId, _environment, style) => {
+	writeFileSync(stylePath(), JSON.stringify(style, null, 2));
+	return Promise.resolve();
+};
 var getSpaceDeployment = () => {
 	console.warn("[SSR] getSpaceDeployment: using stub adapter — returning spaceId=1");
 	return Promise.resolve({
@@ -45,13 +58,24 @@ var getRscData = async (_req, _spaceId, _environment, _revision, user, ids) => {
 	};
 	return { serverData: ids?.length ? Object.fromEntries(ids.filter((id) => id in all).map((id) => [id, all[id]])) : all };
 };
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = path.dirname(__filename);
+var saveOfflineData = (_spaceId, _environment, data) => {
+	writeFileSync(spacePath(), JSON.stringify({ schema: data.schema }, null, 2));
+	writeFileSync(stylePath(), JSON.stringify(data.style, null, 2));
+	return Promise.resolve();
+};
 var adapters = {
 	getOfflineData,
 	getSpaceDeployment,
-	getRscData
+	getRscData,
+	saveOfflineData,
+	getSpaceId,
+	getSchema,
+	getStyle,
+	saveSchema,
+	saveStyle
 };
-var __filename = fileURLToPath(import.meta.url);
-var __dirname = path.dirname(__filename);
 createSSRServer({
 	port: PORT,
 	host: HOST,
@@ -59,6 +83,7 @@ createSSRServer({
 	devMode: false,
 	static: { "/sdk-assets": path.resolve(process.cwd(), "../sdk/dist") },
 	httpVersion: 1,
+	mcpAi: { enabled: true },
 	plugins: {
 		serverInfo: {
 			js: path.resolve(__dirname, "plugins/ServerInfo.tsx"),

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

@@ -1,2 +1,6 @@
 import { SSRServer, SSRServerConfig } from '@plitzi/sdk-shared';
-export declare const createSSRServer: (config: SSRServerConfig) => SSRServer;
+export { createSSRServer } from './server/ssrServer';
+export { createMCPServer } from './server/mcpServer';
+export { resolveServices } from './services/resolve';
+export type { ResolvedServices } from './services/resolve';
+export declare const createServer: (config: SSRServerConfig) => SSRServer;

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

@@ -0,0 +1,10 @@
+export type HealthCheckApp = {
+    get: (path: string, handler: (...args: any[]) => void) => void;
+};
+export interface HealthIdentity {
+    role: string;
+    name?: string;
+    version?: string;
+}
+export declare const buildHealthPayload: (identity?: Partial<HealthIdentity>) => Record<string, unknown>;
+export declare const registerHealthCheck: (app: HealthCheckApp, identity: HealthIdentity) => void;

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

@@ -0,0 +1,7 @@
+import { BaseContext, Stage } from './types';
+import { RawResponse } from '../../helpers/buildResponseHelpers';
+import { Handler } from '../transports';
+import { SSRRequest, SSRResponseHelpers } from '@plitzi/sdk-shared';
+import { IncomingMessage } from 'node:http';
+export type BuildContext<C extends BaseContext> = (raw: IncomingMessage, rawRes: RawResponse, req: SSRRequest, res: SSRResponseHelpers) => C;
+export declare const makeHandler: <C extends BaseContext>(label: string, buildContext: BuildContext<C>, stages: Stage<C>[]) => Handler;

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

@@ -0,0 +1,2 @@
+import { SSRResponseHelpers, SSRServerConfig } from '@plitzi/sdk-shared';
+export declare const applySecurityHeaders: (res: SSRResponseHelpers, config: SSRServerConfig, port: number) => void;

package/dist/src/core/http/stages/authRoutes.d.ts

@@ -0,0 +1,4 @@
+import { Stage } from '../types';
+export declare const loginStage: Stage;
+export declare const logoutStage: Stage;
+export declare const authRoutesStages: Stage[];

package/dist/src/core/http/stages/health.d.ts

@@ -0,0 +1,2 @@
+import { Stage } from '../types';
+export declare const healthStage: Stage;

package/dist/src/core/http/stages/middlewares.d.ts

@@ -0,0 +1,2 @@
+import { Stage } from '../types';
+export declare const middlewaresStage: Stage;

package/dist/src/core/http/stages/pluginAssets.d.ts

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

package/dist/src/core/http/stages/static.d.ts

@@ -0,0 +1,5 @@
+import { Stage } from '../types';
+export declare const builtinPublicStage: Stage;
+export declare const publicDirStage: Stage;
+export declare const wellKnownStage: Stage;
+export declare const configStaticStage: Stage;

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, buildAgentGuide, 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/catalogs/builtinCallbacks.d.ts

@@ -0,0 +1,23 @@
+import { ParamSpec } from './paramSpec';
+export interface BuiltinGlobalCallback {
+    source: string;
+    title: string;
+    strictParams: boolean;
+    params: ParamSpec;
+}
+export declare const BUILTIN_GLOBAL_CALLBACKS: Record<string, BuiltinGlobalCallback>;
+/** The built-in globalCallback for an action, or undefined when the action is not a known built-in (a plugin
+ *  callback whose source/schema is not knowable here). */
+export declare const getGlobalCallback: (action: string) => BuiltinGlobalCallback | undefined;
+/** Report the param keys the agent supplied that are not valid for a built-in callback: only for CLOSED
+ *  (`strictParams`) callbacks; open ones (collection) accept arbitrary field keys so nothing is unknown. Returns []
+ *  for an unknown action (a plugin callback whose schema is not known here). */
+export declare const unknownBuiltinParams: (action: string, params: Record<string, unknown>) => string[];
+/** Resolve a `globalCallback` action against the built-in catalog: returns the module id it is registered under
+ *  (`source`) and the params reconciled to the callback's schema — unknown keys dropped for a closed callback, then
+ *  missing defaults filled. An action the catalog does not know (e.g. a plugin callback) yields no source and
+ *  unchanged params, so the caller keeps its own behavior for it. */
+export declare const applyBuiltinCallback: (action: string, params: Record<string, unknown>) => {
+    source?: string;
+    params: Record<string, unknown>;
+};

package/dist/src/modules/mcp/catalogs/builtinComponents.d.ts

@@ -0,0 +1,4 @@
+import { ComponentCatalogEntry } from '@plitzi/sdk-shared';
+type BuiltinComponent = Required<Pick<ComponentCatalogEntry, 'label' | 'description' | 'category'>>;
+export declare const BUILTIN_COMPONENTS: Partial<Record<string, BuiltinComponent>>;
+export {};

package/dist/src/modules/mcp/catalogs/builtinElementCallbacks.d.ts

@@ -0,0 +1,20 @@
+import { ParamSpec } from './paramSpec';
+export interface BuiltinElementCallback {
+    title: string;
+    strictParams: boolean;
+    params: ParamSpec;
+}
+export declare const BUILTIN_ELEMENT_CALLBACKS: Record<string, BuiltinElementCallback>;
+/** The built-in element callback for an action, or undefined when the action is not a known built-in (an
+ *  element-type-specific/plugin callback whose schema is not knowable here). */
+export declare const getElementCallback: (action: string) => BuiltinElementCallback | undefined;
+/** Param keys the agent supplied that are not valid for a built-in element callback (only for CLOSED sets). []
+ *  for an unknown action (a plugin/element-specific callback whose schema is not known here). */
+export declare const unknownElementCallbackParams: (action: string, params: Record<string, unknown>) => string[];
+/** Reconcile a `callback` action against the element-callback catalog: unknown keys dropped for a closed callback,
+ *  then missing defaults filled (category:"attribute", revertOnFinish:false). An unknown action yields unchanged
+ *  params, so a plugin/element-specific callback keeps whatever the agent passed. */
+export declare const applyElementCallback: (action: string, params: Record<string, unknown>) => {
+    known: boolean;
+    params: Record<string, unknown>;
+};

package/dist/src/modules/mcp/catalogs/builtinTransformers.d.ts

@@ -0,0 +1,28 @@
+import { ParamSpec } from './paramSpec';
+export interface BuiltinTransformer {
+    title: string;
+    description: string;
+    strictParams: boolean;
+    params: ParamSpec;
+}
+export declare const BUILTIN_TRANSFORMERS: Record<string, BuiltinTransformer>;
+/** The built-in transformer for an action, or undefined when the action is not a known built-in transformer. */
+export declare const getTransformer: (action: string) => BuiltinTransformer | undefined;
+/** The closest known transformer action to a mistyped one (substring match either way), so a wrong action like
+ *  "template" teaches "twigTemplate". Undefined when nothing is close. */
+export declare const suggestTransformer: (action: string) => string | undefined;
+export interface TransformerInfo {
+    action: string;
+    title: string;
+    description: string;
+    params: {
+        name: string;
+        type: string;
+        description: string;
+        default?: string | number | boolean;
+        options?: string[];
+    }[];
+}
+/** The transformer catalog projected for the data-sources resource / primer, so the agent knows the exact action
+ *  names and params up front (the real fix for the "agent can't write transformers" problem). */
+export declare const transformerCatalog: () => TransformerInfo[];

package/dist/src/modules/mcp/catalogs/builtinUtilities.d.ts

@@ -0,0 +1,18 @@
+import { ParamSpec } from './paramSpec';
+export interface BuiltinUtility {
+    title: string;
+    strictParams: boolean;
+    params: ParamSpec;
+}
+export declare const BUILTIN_UTILITIES: Record<string, BuiltinUtility>;
+/** The built-in utility for an action, or undefined when the action is not a known built-in utility. */
+export declare const getUtility: (action: string) => BuiltinUtility | undefined;
+/** Param keys the agent supplied that are not valid for a built-in utility (only for CLOSED sets). [] for an unknown
+ *  action (a utility whose schema is not known here). */
+export declare const unknownUtilityParams: (action: string, params: Record<string, unknown>) => string[];
+/** Reconcile a `utility` action against the utility catalog: unknown keys dropped for a closed utility, then missing
+ *  defaults filled. An unknown action yields unchanged params. */
+export declare const applyUtility: (action: string, params: Record<string, unknown>) => {
+    known: boolean;
+    params: Record<string, unknown>;
+};

package/dist/src/modules/mcp/catalogs/cssCatalog.d.ts

@@ -0,0 +1,14 @@
+import { CssProps } from '../types';
+/** Every kebab-case CSS property Plitzi's style engine understands. Values written to a definition
+ *  must use these exact keys — camelCase or unknown keys are rejected by the validator. */
+export declare const cssProperties: string[];
+export declare const isCssProperty: (key: string) => boolean;
+/** If a camelCase key maps to a known kebab-case property, return it — used to teach the agent the correct key. */
+export declare const suggestCssProperty: (key: string) => string | undefined;
+export declare const COMPOUND_SHORTHANDS: Record<string, string[]>;
+/** The atomic longhands to write instead of a compound shorthand, or undefined when the key is not a compound
+ *  shorthand. `flex` layout in particular is NOT `display` + `flex-direction` (those are their own properties). */
+export declare const compoundLonghands: (key: string) => string[] | undefined;
+/** Expand supported CSS shorthands to their longhand keys. Explicit longhands in the same map win over any
+ *  expansion (so `{ padding: 8, padding-left: 0 }` keeps padding-left: 0). Unrecognized keys pass through. */
+export declare const expandShorthand: (css: CssProps) => CssProps;

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

@@ -0,0 +1,9 @@
+export * from './paramSpec';
+export * from './builtinCallbacks';
+export * from './builtinElementCallbacks';
+export * from './builtinUtilities';
+export * from './builtinTransformers';
+export * from './builtinComponents';
+export * from './cssCatalog';
+export * from './observed';
+export * from './registry';

package/dist/src/modules/mcp/catalogs/observed.d.ts

@@ -0,0 +1,48 @@
+import { TransformerInfo } from './builtinTransformers';
+import { AIInteractionNodeType } from '../types';
+import { Schema } from '@plitzi/sdk-shared';
+export interface BuiltinParamInfo {
+    name: string;
+    type: string;
+    description: string;
+    default?: string | number | boolean;
+    options?: string[];
+    conditional?: boolean;
+}
+export interface BuiltinGlobalCallbackInfo {
+    action: string;
+    source: string;
+    title: string;
+    strictParams: boolean;
+    params: BuiltinParamInfo[];
+}
+export interface BuiltinActionInfo {
+    action: string;
+    title: string;
+    strictParams: boolean;
+    params: BuiltinParamInfo[];
+}
+export interface InteractionCatalog {
+    note: string;
+    actions: Record<string, string[]>;
+    globalCallbacksNote: string;
+    globalCallbacks: BuiltinGlobalCallbackInfo[];
+    elementCallbacksNote: string;
+    elementCallbacks: BuiltinActionInfo[];
+    utilitiesNote: string;
+    utilities: BuiltinActionInfo[];
+    flowCount: number;
+}
+export interface DataSourceCatalog {
+    note: string;
+    scopeNote: string;
+    sources: string[];
+    targets: Record<string, string[]>;
+    transformersNote: string;
+    transformers: TransformerInfo[];
+}
+export declare const buildInteractionCatalog: (schema: Schema) => InteractionCatalog;
+export declare const buildDataSourceCatalog: (schema: Schema) => DataSourceCatalog;
+export declare const observedInteractionActions: (schema: Schema) => Set<string>;
+export declare const observedDataSources: (schema: Schema) => Set<string>;
+export declare const INTERACTION_NODE_TYPES: AIInteractionNodeType[];