@plitzi/sdk-server 0.32.6 → 0.32.8

package/dist/modules/mcp/tools/render.js

@@ -0,0 +1,116 @@
+import { emptySpace } from "../helpers/space.js";
+import { RENDER_APP_URI } from "../resources/renderApp.js";
+import { operations } from "./operations/index.js";
+import { applyOperations } from "./apply/dispatch.js";
+import { defineTool } from "./shared/tool.js";
+import { validateOperations } from "./shared/validator/index.js";
+import { auditResources } from "./shared/validator/audit.js";
+import { validateSchema } from "@plitzi/sdk-schema";
+import { generateCache } from "@plitzi/sdk-style";
+//#region src/modules/mcp/tools/render.ts
+var HOST_PAGE_REF = "render";
+var seedSpace = () => {
+	const space = emptySpace();
+	space.schema.definition.name = "Widget";
+	space.schema.flat[HOST_PAGE_REF] = {
+		id: HOST_PAGE_REF,
+		idRef: HOST_PAGE_REF,
+		attributes: {
+			slug: "",
+			name: "Render",
+			default: true
+		},
+		definition: {
+			rootId: HOST_PAGE_REF,
+			label: "Page",
+			type: "page",
+			items: [],
+			styleSelectors: { base: "" }
+		}
+	};
+	space.schema.pages = [HOST_PAGE_REF];
+	return space;
+};
+var noWarnings = (warnings) => warnings.length > 0 ? warnings : void 0;
+var renderShape = { operations };
+var render = (input) => {
+	const space = seedSpace();
+	const validation = validateOperations(space, input.operations);
+	if (!validation.valid) return {
+		rendered: false,
+		errors: validation.errors,
+		warnings: noWarnings(validation.warnings)
+	};
+	const outcome = applyOperations(space, "main", input.operations);
+	if (outcome.errors.length > 0) return {
+		rendered: false,
+		errors: outcome.errors,
+		warnings: noWarnings(validation.warnings)
+	};
+	const integrity = validateSchema(space.schema);
+	if (!integrity.valid) return {
+		rendered: false,
+		errors: integrity.errors.map((error) => ({
+			path: error.elementId ? `schema.${error.elementId}` : "schema",
+			message: error.message,
+			hint: "The authored widget is structurally inconsistent (broken parent/child link or a cycle)."
+		})),
+		warnings: noWarnings(validation.warnings)
+	};
+	const audit = auditResources(space, input.operations);
+	const warnings = [...validation.warnings, ...audit.warnings];
+	if (audit.errors.length > 0) return {
+		rendered: false,
+		errors: audit.errors,
+		warnings: noWarnings(warnings)
+	};
+	space.style.cache = generateCache(space.style);
+	return {
+		rendered: true,
+		rootRef: HOST_PAGE_REF,
+		elementCount: Object.keys(space.schema.flat).length - 1,
+		offlineData: {
+			schema: space.schema,
+			style: space.style
+		},
+		warnings: noWarnings(warnings)
+	};
+};
+var toRenderResult = (res) => {
+	if (!res.rendered) return { content: [{
+		type: "text",
+		text: JSON.stringify({
+			rendered: false,
+			errors: res.errors,
+			warnings: res.warnings
+		})
+	}] };
+	const summary = {
+		rendered: true,
+		rootRef: res.rootRef,
+		elementCount: res.elementCount,
+		warnings: res.warnings
+	};
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify(summary)
+		}],
+		structuredContent: {
+			...summary,
+			offlineData: res.offlineData
+		}
+	};
+};
+var renderTool = defineTool({
+	name: "plitzi_render",
+	title: "Render widget",
+	description: "Show the user a real, rendered UI widget instead of describing one — cards, hero sections, pricing tables, forms, menus, checklists, profiles, galleries. It runs the Plitzi SDK fully offline: no backend, account, or setup. Reach for it whenever a visual layout beats prose: the user asks you to design/build/show something, OR your answer is naturally visual (a recipe → a card, a comparison → a table, steps → a checklist). Prefer showing over telling.\n\nAuthor the widget as an ordered list of `operations` that build an element tree under the pre-seeded root page \"render\". Three rules:\n1. STRUCTURE — one upsertElement builds the whole tree: set pageRef:\"render\" and give element a nested `children` array. Each element is { ref (unique), type, subType?, props?, style?, children? }; children render in order. (To attach to something you already made, use a top-level parentRef:\"<existing ref>\" instead.)\n2. STYLE — declare reusable classes with upsertDefinition { ref, desktop:{ …CSS props in kebab-case… } }, then attach via the element style:{ base:[\"<class ref>\"] }. Lay containers out with flex/grid.\n3. CONTENT — visible copy goes in props.content (text, heading, paragraph, button); heading level is the element subType (\"h1\"..\"h6\"); image/video take props.src. An unknown prop comes back as a warning naming the right one.\n\nCommon types: container, heading, paragraph, text, button, link, image, video, list, listItem, markdown (plitzi://render/types lists every built-in type with descriptions). Widgets can also be data-driven and interactive — an apiContainer fetches at runtime, upsertBinding wires data into elements, and upsertInteractionFlow makes them react to clicks (see the guide).\nREAD the resource plitzi://render/guide first — it has the element/prop table, the style model and a full worked example, and following it is the difference between a widget that renders and repeated failed calls.\nReturns a compact summary (the widget is shown to the user); on failure it returns teachable errors (path + hint) — read them and retry.",
+	inputShape: renderShape,
+	access: "read",
+	spaceless: true,
+	ui: { resourceUri: RENDER_APP_URI },
+	run: (input) => toRenderResult(render(input))
+});
+//#endregion
+export { render, renderShape, renderTool };

package/dist/modules/mcp/tools/shared/tool.js

@@ -20,6 +20,8 @@ var defineTool = (spec) => ({
 	inputShape: spec.inputShape,
 	access: spec.access,
 	requires: spec.requires,
+	spaceless: spec.spaceless,
+	ui: spec.ui,
 	execute: (args, ctx) => spec.run(z.object(spec.inputShape).parse(args), ctx)
 });
 //#endregion

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

@@ -5,5 +5,8 @@ import { SSRAdapters, SSRRequest, McpLogger } from '@plitzi/sdk-shared';
 import { IncomingMessage, ServerResponse } from 'node:http';
 export declare const readMcpBody: (req: IncomingMessage) => Promise<unknown>;
 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, logger?: McpLogger) => Promise<void>;
+export declare const handleMcp: (raw: IncomingMessage, res: ServerResponse, req: SSRRequest, adapters: SSRAdapters, preview?: PreviewClient, screenshot?: ScreenshotClient, logger?: McpLogger, renderApp?: {
+    sdkBase: string;
+    devMode?: boolean;
+}) => Promise<void>;
 export { createMcpServer };

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

@@ -9,6 +9,7 @@ export interface Space {
     catalog?: ComponentCatalog;
 }
 export declare const cloneSpace: (space: Space) => Space;
+export declare const emptySpace: () => Space;
 export declare const slugify: (value: string) => string;
 /** A value when it is a string, otherwise undefined — for the many attributes typed as `unknown` that are strings
  *  in practice (name, slug, subType, dom id…). */

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

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp';
+export declare const RENDER_APP_URI = "ui://plitzi/render.html";
+export declare const registerRenderApp: (server: McpServer, sdkBase: string, devMode: boolean) => void;

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

@@ -0,0 +1,4 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp';
+export declare const RENDER_GUIDE_URI = "plitzi://render/guide";
+export declare const RENDER_TYPES_URI = "plitzi://render/types";
+export declare const registerRenderResources: (server: McpServer) => void;

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

@@ -18,5 +18,13 @@ export interface McpServerContext {
     /** Structured request-log sink. When set, every tool call and resource read emits an McpLogEvent to it (the
      *  consumer renders them); otherwise logging falls back to the console when MCP_DEBUG=1. */
     logger?: McpLogger;
+    /** MCP Apps: the interactive render view for plitzi_render. `sdkBase` is this server's absolute origin, which
+     *  serves the Plitzi SDK bundle under /sdk-assets; the iframe imports it and renders the widget client-side.
+     *  `devMode` picks the SDK vendor bundle name (dev vs prod split) to match the served bundle. Absent → the
+     *  ui:// view is not registered (the tool still returns its text summary + offlineData). */
+    renderApp?: {
+        sdkBase: string;
+        devMode?: boolean;
+    };
 }
-export declare const createMcpServer: ({ adapters, getSpaceId, preview, screenshot, logger }: McpServerContext) => McpServer;
+export declare const createMcpServer: ({ adapters, getSpaceId, preview, screenshot, logger, renderApp }: McpServerContext) => McpServer;

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

@@ -4,6 +4,7 @@ export { validate, validateShape } from './validate';
 export { search, searchShape } from './search';
 export { read, readShape } from './read';
 export { previewShape } from './preview';
+export { render, renderShape } from './render';
 export { screenshotShape } from './screenshot';
 export { applyOperations } from './apply/dispatch';
 export { validateOperations } from './shared/validator';