@plitzi/sdk-shared 0.32.4 → 0.32.6

package/dist/store/tracing/preview.mjs

@@ -19,7 +19,7 @@ var e = (e) => {
 	if (Object.is(e, t)) return !0;
 	if (e === null || t === null || typeof e != "object" || typeof t != "object" || Array.isArray(e) !== Array.isArray(t)) return !1;
 	let n = Object.keys(e), r = Object.keys(t);
-	return n.length === r.length ? n.every((n) => Object.is(e[n], t[n])) : !1;
+	return n.length === r.length && n.every((n) => Object.is(e[n], t[n]));
 }, r = (e, r) => {
 	if (!e) return [];
 	let i = [], a = /* @__PURE__ */ new Set([...Object.keys(e), ...Object.keys(r)]);

package/dist/style/styleConstants.mjs

@@ -108,21 +108,25 @@ var e = {
 	TEXT_OVERFLOW: "text-overflow",
 	TEXT_SHADOW: "text-shadow"
 }, n = [
-	t.TEXT_DECORATION,
-	t.LINE_HEIGHT,
-	t.LETTER_SPACING,
-	t.COLOR,
-	t.DIRECTION,
 	t.FONT_FAMILY,
-	t.FONT_WEIGHT,
 	t.FONT_SIZE,
+	t.FONT_STYLE,
+	t.FONT_WEIGHT,
+	t.COLOR,
+	t.LINE_HEIGHT,
+	t.LETTER_SPACING,
 	t.TEXT_ALIGN,
+	t.TEXT_DECORATION,
 	t.TEXT_INDENT,
 	t.TEXT_SHADOW,
 	t.TEXT_TRANSFORM,
-	t.WHITE_SPACE,
 	t.TEXT_WRAP,
-	t.TEXT_OVERFLOW
+	t.TEXT_OVERFLOW,
+	t.WHITE_SPACE,
+	t.DIRECTION,
+	t.CURSOR,
+	t.LIST_STYLE,
+	t.LIST_STYLE_TYPE
 ], r = Object.values(t).map((e) => ({
 	path: e,
 	label: e

package/dist/types/CommonTypes.d.ts

@@ -8,9 +8,7 @@ export type Server<T extends Record<string, unknown> = Record<string, unknown>>
     host?: string;
     domain?: string;
     requestUrl?: string;
-    nodeServer: string;
-    aiServer: string;
-    graphqlServer: string;
+    serverUrl: string;
     websocketServer: string;
     subscriptionServer: string;
     location?: Location;

package/dist/types/EventBridgeTypes.d.ts

@@ -2,4 +2,4 @@ export type EventBridgeContextValue<T = any> = {
     eventBridge: T;
 };
 export type EventBridgeModule = 'main' | 'builder' | 'segment' | 'template' | 'interaction' | 'element';
-export type EventBridgeEvent = 'schemaAddPage' | 'schemaHomePage' | 'schemaUpdatePage' | 'schemaRemovePage' | 'schemaAddPageFolder' | 'schemaUpdatePageFolder' | 'schemaRemovePageFolder' | 'schemaUpdateSettings' | 'schemaUpdate' | 'schemaAddElement' | 'schemaUpdateElement' | 'schemaRemoveElement' | 'schemaMoveElement' | 'schemaCloneElement' | 'schemaAddVariable' | 'schemaUpdateVariable' | 'schemaRemoveVariable' | 'schemaAddTemplate' | 'styleUpdate' | 'styleAddSelector' | 'styleUpdateSelector' | 'styleRemoveSelector' | 'styleAddSelectorVariable' | 'styleUpdateSelectorVariable' | 'styleRemoveSelectorVariable' | 'styleAddVariable' | 'styleUpdateVariable' | 'styleRemoveVariable' | 'styleAddTemplate' | 'styleUpdateSettings' | 'builderSetBaseContext' | 'builderSetSelected' | 'builderSetHovered';
+export type EventBridgeEvent = 'schemaAddPage' | 'schemaHomePage' | 'schemaUpdatePage' | 'schemaRemovePage' | 'schemaAddPageFolder' | 'schemaUpdatePageFolder' | 'schemaRemovePageFolder' | 'schemaUpdateSettings' | 'schemaUpdate' | 'schemaAddElement' | 'schemaUpdateElement' | 'schemaUpdateElements' | 'schemaRemoveElement' | 'schemaMoveElement' | 'schemaCloneElement' | 'schemaAddVariable' | 'schemaUpdateVariable' | 'schemaRemoveVariable' | 'schemaAddTemplate' | 'styleUpdate' | 'styleAddSelector' | 'styleUpdateSelector' | 'styleRemoveSelector' | 'styleRemoveSelectors' | 'styleAddSelectorVariable' | 'styleUpdateSelectorVariable' | 'styleRemoveSelectorVariable' | 'styleAddVariable' | 'styleUpdateVariable' | 'styleRemoveVariable' | 'styleAddTemplate' | 'styleUpdateSettings' | 'builderSetBaseContext' | 'builderSetSelected' | 'builderSetHovered';

package/dist/types/InteractionTypes.d.ts

@@ -68,6 +68,7 @@ export type InteractionCallback<T extends Record<string, unknown> = Record<strin
     title: string;
     type: InteractionCallbackType;
     enabled?: boolean;
+    unreferenced?: boolean;
     params: Record<keyof T, InteractionCallbackParam<T>> | ((params: InteractionCallbackParamValues<T>) => Record<keyof T, InteractionCallbackParam<T>>);
     callback?: (params: InteractionCallbackParamValues<T>) => unknown;
     postCallback?: InteractionPostCallback<T>;
@@ -92,7 +93,7 @@ export type Subscriptor<T extends Record<string, unknown> = Record<string, unkno
 export type InteractionsContextValue<TManager = any> = {
     interactionsManager: TManager;
     useInteractions: <T extends Record<string, unknown> = Record<string, unknown>>(props: {
-        id: string;
+        id?: string;
         interactions?: Record<string, ElementInteraction>;
         triggers?: Record<string, InteractionCallback<T>>;
         callbacks?: Record<string, InteractionCallback<T>>;

package/dist/types/McpTypes/index.d.ts

@@ -1,28 +1,6 @@
 import { AiContext, AiMode, PromptRole } from '../AITypes';
-import { StyleVariableCategory, StyleVariableValue } from '../StyleTypes';
-import { McpAdapters } from './McpAdapters';
 import { ToolAnnotations } from '@modelcontextprotocol/sdk/types';
 import { ZodType } from 'zod';
-export * from './McpAdapters';
-export type McpPlugin = {
-    name: string;
-    version?: string;
-    description?: string;
-};
-export type McpStyleVariable = {
-    category: StyleVariableCategory;
-    name: string;
-    value: StyleVariableValue;
-};
-export type McpSegment = {
-    id?: string;
-    identifier: string;
-    definition: {
-        name: string;
-        description: string;
-        baseElementId: string;
-    };
-};
 export type ToolOperationType = 'read' | 'write';
 export type McpPromptHandlerResult = {
     messages: {
@@ -34,27 +12,18 @@ export type McpPromptHandlerResult = {
     }[];
 };
 export type McpPromptHandler = (args: Record<string, any>, ctx: AiContext) => Promise<McpPromptHandlerResult>;
-export type McpPrompt = {
-    name: string;
-    definition: {
-        title: string;
-        description: string;
-        argsSchema?: Record<string, any>;
-    };
-    handler: McpPromptHandler;
+export type McpTextContent = {
+    type: 'text';
+    text: string;
 };
-export type McpResource = {
-    uri: string;
-    name: string;
-    description: string;
+export type McpImageContent = {
+    type: 'image';
+    data: string;
     mimeType: string;
-    content: string;
 };
+export type McpContent = McpTextContent | McpImageContent;
 export type McpToolHandlerResult = {
-    content: {
-        type: 'text';
-        text: string;
-    }[];
+    content: McpContent[];
     data?: unknown;
     structuredContent?: Record<string, unknown>;
     isError?: true;
@@ -83,14 +52,9 @@ export type McpTool = {
     definition: {
         allowedModes: AiMode[];
     };
-    adapterName?: keyof McpAdapters;
     handler?: McpToolHandler;
 };
 export type McpServerConfig = {
     enabled?: boolean;
     path?: string;
-    adapters: Partial<McpAdapters>;
-    tools?: McpTool[];
-    prompts?: McpPrompt[];
-    resources?: McpResource[];
 };

package/dist/types/SchemaTypes.d.ts

@@ -13,21 +13,17 @@ export type SchemaRsc = {
 export type DropPosition = 'top' | 'bottom' | 'left' | 'right' | 'inside' | 'custom';
 export type BindingCategory = 'attributes' | 'style' | 'initialState';
 export type BindingTransformer = {
-    type: 'utility' | 'unknown';
     action: string;
-    params: {
-        valueType: string;
-        value: string;
-    };
+    params: Record<string, string>;
+    enabled?: boolean;
 };
 export type ElementBinding = {
     id: string;
     source: string;
-    fromPath?: string;
     transformers?: BindingTransformer[];
     when?: RuleGroup;
     enabled?: boolean;
-    toPath: string;
+    to: string;
 };
 export type ElementInteraction<T extends Record<keyof InteractionCallback['params'], unknown> = Record<string, unknown>> = {
     id: string;
@@ -36,7 +32,7 @@ export type ElementInteraction<T extends Record<keyof InteractionCallback['param
     action: string;
     params: InteractionCallbackParamValues<T>;
     preview: Record<string, unknown>;
-    elementId: Element['id'];
+    elementId: Element['id'] | null;
     beforeNode: string;
     afterNode: string;
     flowId: string;
@@ -68,6 +64,7 @@ export type ElementDefinition = {
 };
 export type Element<TAttributes extends Record<string, unknown> = Record<string, unknown>> = {
     id: string;
+    idRef?: string;
     attributes: TAttributes & {
         subType?: string;
     };
@@ -125,6 +122,7 @@ export type SchemaContextValue = {
     schemaUpdate?: (newSchema: SchemaRaw, fromSubscriptions?: boolean) => void;
     schemaAddElement?: (to: string, data: Element, dropPosition?: DropPosition, initialItems?: Record<string, Element>, variables?: SchemaVariable[], fromSubscriptions?: boolean) => void;
     schemaUpdateElement?: (element: Element, fromSubscriptions?: boolean) => void;
+    schemaUpdateElements?: (elements: Element[], fromSubscriptions?: boolean) => void;
     schemaMoveElement?: (from: string, to: string, elementId: string, dropPosition?: DropPosition, fromSubscriptions?: boolean) => void;
     schemaCloneElement?: (elementId: string, targetId?: string, fromSubscriptions?: boolean) => void;
     schemaRemoveElement?: (elementId: string, fromSubscriptions?: boolean) => void;

package/dist/types/ServerTypes.d.ts

@@ -1,6 +1,8 @@
 import { Environment } from './CommonTypes';
 import { McpServerConfig } from './McpTypes';
+import { Schema } from './SchemaTypes';
 import { OfflineDataRaw } from './SdkTypes';
+import { Style } from './StyleTypes';
 import { IncomingHttpHeaders } from 'node:http';
 import { FC } from 'react';
 export type ServerEnvironment = 'development' | 'production' | 'staging' | 'local';
@@ -120,9 +122,61 @@ export type SSRRscData = {
     /** Per-element server data keyed by schema element ID. Each element reads its own slice via its id prop. */
     serverData?: Record<string, unknown>;
 };
+/** Semantic + machine-readable metadata for one element type, so the MCP can tell an agent what the type DOES
+ *  (not just that it exists) AND validate against it. `category` groups it (e.g. provider, structure, media);
+ *  `custom` marks a plugin-provided type. The MCP keys strict-vs-lenient validation off `custom`: a `custom:false`
+ *  (default sdk-elements) type is authoritative — an unknown attribute/setState key on it is an error — while a
+ *  `custom:true` (plugin) type is best-effort (warnings only), since its metadata is a manifest snapshot. */
+export type ComponentCatalogEntry = {
+    label?: string;
+    description?: string;
+    category?: string;
+    custom?: boolean;
+    /** The type's attribute/prop keys — the authoritative set for a default type (setState `key` when
+     *  category="attribute", and type-prop validation). Absent when unknown (e.g. a plugin with no manifest). */
+    attributes?: string[];
+    /** The type's `definition.styleSelectors` keys (slots) — setState `key` when category="state" is
+     *  `visibility` or `styleSelectors.<selector>`. */
+    styleSelectors?: string[];
+    /** The type's intrinsic base default CSS (its `defaultStyle.style.base.default`) — the declarations the element
+     *  renders with before any class is attached, e.g. `text` defaults to `{ display: 'inline' }`. The MCP surfaces
+     *  it so an agent styles against the real starting point instead of assuming `display: block`. */
+    defaultStyle?: Record<string, string>;
+    /** Binding targets the type exposes, from the plugin manifest's `defaultStyle.bindingsAllowed`. */
+    bindingsAllowed?: {
+        attributes?: string[];
+        initialState?: string[];
+    };
+};
+/** Element type → its semantic metadata, keyed by the `type` string used in the schema. Covers BOTH the default
+ *  sdk-elements types (custom:false, authoritative) and the plugin (custom:true) element types installed on a
+ *  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>;
+    /** 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>;
+    /** 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>;
+    /** Read the full style document (with `platform`/`mode`, which the MCP definitions resource requires). */
+    getStyle?: (spaceId: number, environment: Environment) => Promise<Style | undefined>;
+    /** Read the semantic catalog of the space's PLUGIN (custom) element types — label/description/category from
+     *  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>;
+    /** 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>;
     getUser?: (req: SSRRequest) => Promise<SSRUser | undefined>;
     onLogin?: (req: SSRRequest, res: SSRResponseHelpers) => Promise<boolean>;
     onLogout?: (req: SSRRequest, res: SSRResponseHelpers) => Promise<void>;
@@ -139,6 +193,27 @@ export type SSRRscConfig = {
     /** Server-side cache TTL for RSC responses in milliseconds. Defaults to 30 000. Set to 0 to disable. */
     cacheTtlMs?: number;
 };
+/** A structured log event the MCP server emits for each tool call and resource read, so a CONSUMER can render its
+ *  own request log (dev tooling, a dashboard, structured logging). Wire a sink via `SSRServerConfig.mcpLogger`;
+ *  without one the server prints to the console only when `MCP_DEBUG=1`. */
+export type McpLogEvent = {
+    /** 'tool' for a plitzi_* tool call, 'resource' for a plitzi:// resource read. */
+    kind: 'tool' | 'resource';
+    /** The tool name (e.g. 'plitzi_apply') or the resource URI that was read. */
+    name: string;
+    /** Wall-clock duration of the handler, in milliseconds. */
+    durationMs: number;
+    /** Whether the handler completed without throwing. */
+    ok: boolean;
+    /** The error message when `ok` is false. */
+    error?: string;
+    /** A compact, truncated JSON summary of the tool arguments (tool events only). */
+    argsSummary?: string;
+    /** ISO-8601 timestamp of when the event was emitted. */
+    timestamp: string;
+};
+/** A sink the consumer provides to receive every MCP {@link McpLogEvent} (see `SSRServerConfig.mcpLogger`). */
+export type McpLogger = (event: McpLogEvent) => void;
 export type SSRServerConfig = {
     port?: number;
     host?: string;
@@ -176,10 +251,62 @@ export type SSRServerConfig = {
     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.
+     *  When enabled, requests to the MCP path serve the AI-native server instead. */
+    mcpAi?: {
+        enabled?: boolean;
+        path?: string;
+    };
+    /** Receives a structured {@link McpLogEvent} for every MCP tool call and resource read, so the consumer can
+     *  render its own request log (e.g. in dev mode). Without it, the MCP server logs to the console only when
+     *  `MCP_DEBUG=1`. */
+    mcpLogger?: McpLogger;
     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). The per-service presets (createSSRServer / createMCPServer) pin these flags for you. */
+    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;
+    };
     /** 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;
 };
+export type ServerServices = {
+    ssr?: boolean;
+    rsc?: boolean;
+    mcp?: boolean;
+    ai?: boolean;
+};
 export type PluginRegistry = {
     register: (name: string, source: PluginSource) => void;
     invalidate: (name?: string, version?: string) => Promise<void>;
@@ -206,3 +333,23 @@ export type SSRServer = {
     readonly cache: CacheManager | null;
     readonly plugins: PluginRegistry;
 };
+/** A short-TTL, one-shot store for unsaved draft offline-data behind a preview token. The SDK ships an
+ *  in-memory default (fine for a single replica); a multi-replica deployment injects a shared (e.g. Redis)
+ *  implementation so a preview URL resolves on whichever replica the browser lands on. `take` consumes the
+ *  token so a preview URL is not replayable. */
+export type DraftStore = {
+    put: (token: string, data: OfflineDataRaw, ttlMs: number) => void | Promise<void>;
+    take: (token: string) => (OfflineDataRaw | undefined) | Promise<OfflineDataRaw | undefined>;
+};
+/** Draft-preview config for the MCP visual-preview tools. When enabled, an internal endpoint at `path`
+ *  (guarded by `secret`) applies unsaved edits to a clone, stashes the resulting offline-data under a
+ *  one-shot token, and the render path serves it back at `?__pt=<token>`. Off by default. */
+export type SSRPreviewConfig = {
+    enabled?: boolean;
+    /** Internal endpoint path that mints a preview token. Default '/__preview'. */
+    path?: string;
+    /** Shared secret required in the `x-preview-secret` header; requests without it are rejected. */
+    secret?: string;
+    /** Token time-to-live in milliseconds. Default 60000. */
+    ttlMs?: number;
+};

package/dist/types/StyleTypes.d.ts

@@ -48,6 +48,7 @@ export type StyleContextValue = {
     styleAddSelector?: unknown;
     styleUpdateSelector?: unknown;
     styleRemoveSelector?: unknown;
+    styleRemoveSelectors?: unknown;
     styleAddSelectorVariable?: unknown;
     styleUpdateSelectorVariable?: unknown;
     styleRemoveSelectorVariable?: unknown;