@plitzi/sdk-server 0.32.4 → 0.32.6

package/dist/modules/mcp/helpers/opResult.js

@@ -0,0 +1,18 @@
+//#region src/modules/mcp/helpers/opResult.ts
+var empty = () => ({
+	created: 0,
+	updated: 0,
+	deleted: 0,
+	staleResources: []
+});
+var fail = (path, message, hint, validValues) => ({
+	...empty(),
+	errors: [{
+		path,
+		message,
+		hint,
+		validValues
+	}]
+});
+//#endregion
+export { empty, fail };

package/dist/modules/mcp/helpers/space.js

@@ -0,0 +1,262 @@
+//#region src/modules/mcp/helpers/space.ts
+var cloneSpace = (space) => ({
+	schema: structuredClone(space.schema),
+	style: structuredClone(space.style),
+	...space.catalog ? { catalog: space.catalog } : {}
+});
+var slugify = (value) => value.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "";
+/** 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…). */
+var strOr = (value) => typeof value === "string" ? value : void 0;
+/** Display name of a page or element: its `name` attribute when set, otherwise its definition label. */
+var nameOf = (el) => strOr(el.attributes.name) ?? el.definition.label;
+/** Stable, human-readable ref for a page: its idRef, then slug, then a slugified label. A page without an idRef is
+*  still addressable — unlike a data source, a page ref has meaningful fallbacks the agent can read off the tree. */
+var pageRefOf = (el) => {
+	if (el.idRef) return el.idRef;
+	const slug = strOr(el.attributes.slug)?.trim();
+	if (slug) return slugify(slug);
+	if (el.attributes.default === true) return "home";
+	return slugify(nameOf(el)) || el.id;
+};
+/** Stable ref for ADDRESSING a non-page element in the tree: its idRef when present, otherwise the opaque id so an
+*  element without one is still reachable — the agent needs to name it to give it an idRef in the first place.
+*  This is not the wiring key: the runtime wires interactions and data sources by idRef only, so an element
+*  addressed here by its id alone publishes no source and takes no interactions (see `getSourceName`). */
+var elementRefOf = (el) => el.idRef ?? el.id;
+var buildIndex = (schema) => {
+	const flat = schema.flat;
+	const lookup = (id) => flat[id];
+	const pageIds = new Set(schema.pages);
+	for (const el of Object.values(flat)) if (el.definition.type === "page") pageIds.add(el.id);
+	const pageElements = [];
+	const pageByRef = /* @__PURE__ */ new Map();
+	const elementByRef = /* @__PURE__ */ new Map();
+	for (const el of Object.values(flat)) if (pageIds.has(el.id)) {
+		pageElements.push(el);
+		const ref = pageRefOf(el);
+		if (!pageByRef.has(ref)) pageByRef.set(ref, el);
+		if (!pageByRef.has(el.id)) pageByRef.set(el.id, el);
+	} else {
+		const ref = elementRefOf(el);
+		if (!elementByRef.has(ref)) elementByRef.set(ref, el);
+		if (!elementByRef.has(el.id)) elementByRef.set(el.id, el);
+	}
+	const pageOf = /* @__PURE__ */ new Map();
+	for (const page of pageElements) {
+		pageOf.set(page.id, page.id);
+		const stack = [...page.definition.items ?? []];
+		while (stack.length > 0) {
+			const id = stack.pop();
+			if (id === void 0 || pageOf.has(id)) continue;
+			const el = lookup(id);
+			if (!el) continue;
+			pageOf.set(id, page.id);
+			for (const childId of el.definition.items ?? []) stack.push(childId);
+		}
+	}
+	return {
+		pageIds,
+		pageElements,
+		pageByRef,
+		elementByRef,
+		pageOf,
+		detailCache: /* @__PURE__ */ new Map()
+	};
+};
+var indexCache = /* @__PURE__ */ new WeakMap();
+/** The index for a schema, built once and memoized on the schema object. */
+var spaceIndex = (schema) => {
+	let index = indexCache.get(schema);
+	if (!index) {
+		index = buildIndex(schema);
+		indexCache.set(schema, index);
+	}
+	return index;
+};
+var cachedIndex = (schema) => indexCache.get(schema);
+/** A new non-page element was created under `pageId`. */
+var indexAddElement = (schema, el, pageId) => {
+	const index = cachedIndex(schema);
+	if (!index) return;
+	index.elementByRef.set(el.id, el);
+	if (el.idRef) index.elementByRef.set(el.idRef, el);
+	index.pageOf.set(el.id, pageId);
+	index.detailCache.clear();
+};
+/** These non-page elements were deleted (an element and its descendants). */
+var indexRemoveElements = (schema, els) => {
+	const index = cachedIndex(schema);
+	if (!index) return;
+	for (const el of els) {
+		index.elementByRef.delete(el.id);
+		if (el.idRef) index.elementByRef.delete(el.idRef);
+		index.pageOf.delete(el.id);
+	}
+	index.detailCache.clear();
+};
+/** An existing element was just given an idRef (it had none), so it becomes addressable by that ref. */
+var indexReRefElement = (schema, el) => {
+	const index = cachedIndex(schema);
+	if (!index) return;
+	if (el.idRef) index.elementByRef.set(el.idRef, el);
+	index.detailCache.clear();
+};
+/** A new page element was created. */
+var indexAddPage = (schema, page) => {
+	const index = cachedIndex(schema);
+	if (!index) return;
+	index.pageIds.add(page.id);
+	index.pageElements.push(page);
+	index.pageByRef.set(page.id, page);
+	index.pageByRef.set(pageRefOf(page), page);
+	index.pageOf.set(page.id, page.id);
+	index.detailCache.clear();
+};
+/** A page and its `descendants` (its non-page elements) were deleted. */
+var indexRemovePage = (schema, page, descendants) => {
+	const index = cachedIndex(schema);
+	if (!index) return;
+	index.pageIds.delete(page.id);
+	const at = index.pageElements.findIndex((p) => p.id === page.id);
+	if (at >= 0) index.pageElements.splice(at, 1);
+	index.pageByRef.delete(page.id);
+	index.pageByRef.delete(pageRefOf(page));
+	index.pageOf.delete(page.id);
+	for (const el of descendants) {
+		index.elementByRef.delete(el.id);
+		if (el.idRef) index.elementByRef.delete(el.idRef);
+		index.pageOf.delete(el.id);
+	}
+	index.detailCache.clear();
+};
+/** A page's slug/name/default changed; re-key its pageByRef entry if that changed its ref. `oldRef` is the ref
+*  computed BEFORE the attribute change. */
+var indexReRefPage = (schema, page, oldRef) => {
+	const index = cachedIndex(schema);
+	if (!index) return;
+	const newRef = pageRefOf(page);
+	if (newRef !== oldRef) {
+		index.pageByRef.delete(oldRef);
+		index.pageByRef.set(newRef, page);
+		index.detailCache.clear();
+	}
+};
+/** A move reparented an element within its page: the ref/page maps are unchanged, but the moved element's
+*  parentRef and both parents' childRefs did change, so their memoized detail must be dropped. */
+var indexInvalidateDetails = (schema) => {
+	cachedIndex(schema)?.detailCache.clear();
+};
+var isPageElement = (schema, el) => spaceIndex(schema).pageIds.has(el.id) || el.definition.type === "page";
+var getPageElements = (schema) => spaceIndex(schema).pageElements;
+/** Finds a page by its semantic ref (idRef/slug/…) or its raw id, so legacy schemas without an idRef still resolve. */
+var findPageByRef = (schema, pageRef) => spaceIndex(schema).pageByRef.get(pageRef);
+/** Find any non-page element by its semantic ref (idRef) or raw id, across the whole space. */
+var findElementByRef = (schema, ref) => spaceIndex(schema).elementByRef.get(ref);
+var pageFoldersOf = (schema) => {
+	schema.pageFolders ??= [];
+	return schema.pageFolders;
+};
+/** Resolve a folder by its id, or (for agent convenience) by an exact name or slug when that is unambiguous. */
+var findFolderByRef = (schema, ref) => {
+	const folders = pageFoldersOf(schema);
+	const byId = folders.find((f) => f.id === ref);
+	if (byId) return byId;
+	const byName = folders.filter((f) => f.name === ref);
+	if (byName.length === 1) return byName[0];
+	const bySlug = folders.filter((f) => f.slug === ref);
+	return bySlug.length === 1 ? bySlug[0] : void 0;
+};
+/** 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. */
+var sortFolders = (folders) => {
+	const byId = new Map(folders.map((f) => [f.id, f]));
+	const placed = /* @__PURE__ */ new Set();
+	const result = [];
+	const visit = (folder, ancestry) => {
+		if (placed.has(folder.id)) return;
+		const parent = folder.parentId ? byId.get(folder.parentId) : void 0;
+		if (parent && !ancestry.has(parent.id)) visit(parent, new Set(ancestry).add(folder.id));
+		if (!placed.has(folder.id)) {
+			placed.add(folder.id);
+			result.push(folder);
+		}
+	};
+	for (const folder of folders) visit(folder, /* @__PURE__ */ new Set([folder.id]));
+	return result;
+};
+/** 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. */
+var folderAncestorIds = (folders, startParentId) => {
+	const byId = new Map(folders.map((f) => [f.id, f]));
+	const chain = [];
+	const seen = /* @__PURE__ */ new Set();
+	let current = startParentId ? byId.get(startParentId) : void 0;
+	while (current && !seen.has(current.id)) {
+		seen.add(current.id);
+		chain.push(current.id);
+		current = current.parentId ? byId.get(current.parentId) : void 0;
+	}
+	return chain;
+};
+/** 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. */
+var slugRouteParams = (slug) => {
+	const params = [];
+	for (const segment of slug.split("/")) if (segment.startsWith(":")) params.push(segment.slice(1).replace(/[*+?]+$/, ""));
+	return params;
+};
+/** Every route param bound by any page slug in the space (union), so {{name}} validation does not false-flag a
+*  page-scoped dynamic binding. */
+var routeParamNames = (schema) => {
+	const params = /* @__PURE__ */ new Set();
+	for (const page of getPageElements(schema)) {
+		const slug = typeof page.attributes.slug === "string" ? page.attributes.slug : "";
+		for (const param of slugRouteParams(slug)) params.add(param);
+	}
+	return [...params];
+};
+/** Indexed lookup that reflects the runtime reality: a flat id may be dangling (rsc placeholders, stale items). */
+var elementById = (schema, id) => schema.flat[id];
+/** All element ids belonging to a page subtree (excluding the page root). */
+var collectDescendants = (schema, rootId, acc) => {
+	const el = elementById(schema, rootId);
+	if (!el) return;
+	const childIds = el.definition.items ?? [];
+	for (const childId of childIds) if (elementById(schema, childId)) {
+		acc.push(childId);
+		collectDescendants(schema, childId, acc);
+	}
+};
+var descendantIds = (schema, pageRootId) => {
+	const acc = [];
+	collectDescendants(schema, pageRootId, acc);
+	return acc;
+};
+/** Resolve a ref to a concrete element within a page subtree (or the page root itself). Accepts either the
+*  semantic ref (idRef) or the raw element id, so schemas predating idRef keep working through their ids. */
+var resolveRef = (schema, page, ref) => {
+	if (elementRefOf(page) === ref || pageRefOf(page) === ref || page.id === ref) return page;
+	const index = spaceIndex(schema);
+	const el = index.elementByRef.get(ref);
+	return el && index.pageOf.get(el.id) === page.id ? el : void 0;
+};
+/** Ordered children of an element, honoring definition.items and skipping dangling ids. */
+var orderedChildren = (schema, el) => {
+	return (el.definition.items ?? []).map((id) => schema.flat[id]).filter((child) => Boolean(child));
+};
+/** The page ref an element belongs to. 'unknown' when it has no page ancestor. */
+var pageRefOfElement = (schema, el) => {
+	const pageId = spaceIndex(schema).pageOf.get(el.id);
+	const page = pageId ? schema.flat[pageId] : void 0;
+	return page ? pageRefOf(page) : "unknown";
+};
+/** Total number of descendant elements under a subtree (excluding the root). */
+var descendantCount = (schema, rootId) => descendantIds(schema, rootId).length;
+var emptySpaceMessage = "Space data not available";
+var unauthorizedSpaceMessage = "This tool/resource needs a space, but no spaceId could be resolved from the Authorization token";
+var generateObjectId = () => {
+	return `${Math.floor(Date.now() / 1e3).toString(16).padStart(8, "0")}${Array.from({ length: 16 }, () => Math.floor(Math.random() * 16).toString(16)).join("")}`;
+};
+//#endregion
+export { cloneSpace, descendantCount, descendantIds, elementById, elementRefOf, emptySpaceMessage, findElementByRef, findFolderByRef, findPageByRef, folderAncestorIds, generateObjectId, getPageElements, indexAddElement, indexAddPage, indexInvalidateDetails, indexReRefElement, indexReRefPage, indexRemoveElements, indexRemovePage, isPageElement, nameOf, orderedChildren, pageFoldersOf, pageRefOf, pageRefOfElement, resolveRef, routeParamNames, slugRouteParams, slugify, sortFolders, spaceIndex, strOr, unauthorizedSpaceMessage };

package/dist/modules/mcp/helpers/uris.js

@@ -0,0 +1,44 @@
+//#region src/modules/mcp/helpers/uris.ts
+var guideUri = "plitzi://guide";
+var typesUri = "plitzi://types";
+var cssPropertiesUri = "plitzi://css-properties";
+var primerUri = (env) => `plitzi://primer/${env}`;
+var pagesUri = (env) => `plitzi://schema/${env}/pages`;
+var pageUri = (env, ref) => `plitzi://schema/${env}/pages/${ref}`;
+var elementUri = (env, ref) => `plitzi://schema/${env}/elements/${ref}`;
+var schemaVarsUri = (env) => `plitzi://schema-variables/${env}`;
+var settingsUri = (env) => `plitzi://settings/${env}`;
+var interactionsUri = (env) => `plitzi://interactions/${env}`;
+var dataSourcesUri = (env) => `plitzi://data-sources/${env}`;
+var foldersUri = (env) => `plitzi://folders/${env}`;
+var folderUri = (env, ref) => `plitzi://folders/${env}/${ref}`;
+var defsUri = (env) => `plitzi://definitions/${env}`;
+var defUri = (env, ref) => `plitzi://definitions/${env}/${ref}`;
+var globalsUri = (env) => `plitzi://global-styles/${env}`;
+var globalUri = (env, componentType) => `plitzi://global-styles/${env}/${componentType}`;
+var idsUri = (env) => `plitzi://id-styles/${env}`;
+var idUri = (env, targetId) => `plitzi://id-styles/${env}/${targetId}`;
+var styleVarsUri = (env) => `plitzi://style-variables/${env}`;
+var styleVarUri = (env, category) => `plitzi://style-variables/${env}/${category}`;
+var aliasedRoots = [
+	"definitions",
+	"global-styles",
+	"id-styles",
+	"style-variables",
+	"schema-variables",
+	"folders"
+];
+var itemTemplates = (env) => [
+	pageUri(env, "{ref}"),
+	elementUri(env, "{ref}"),
+	defUri(env, "{ref}"),
+	globalUri(env, "{componentType}"),
+	idUri(env, "{targetId}"),
+	styleVarUri(env, "{category}"),
+	folderUri(env, "{ref}")
+];
+/** The remainder of `uri` after `prefix`, or undefined when it does not start with it — so a resolver matches a
+*  family and extracts its ref in one step, without repeating the prefix string for both the startsWith and slice. */
+var afterPrefix = (uri, prefix) => uri.startsWith(prefix) ? uri.slice(prefix.length) : void 0;
+//#endregion
+export { afterPrefix, aliasedRoots, cssPropertiesUri, dataSourcesUri, defUri, defsUri, elementUri, folderUri, foldersUri, globalUri, globalsUri, guideUri, idUri, idsUri, interactionsUri, itemTemplates, pageUri, pagesUri, primerUri, schemaVarsUri, settingsUri, styleVarUri, styleVarsUri, typesUri };

package/dist/modules/mcp/previewClient.js

@@ -0,0 +1,31 @@
+//#region src/modules/mcp/previewClient.ts
+/** 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. */
+var createHttpPreviewClient = ({ url, secret, fetchImpl = fetch }) => ({ async render(body) {
+	let res;
+	try {
+		res = await fetchImpl(url, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				...secret ? { "x-preview-secret": secret } : {}
+			},
+			body: JSON.stringify(body)
+		});
+	} catch (err) {
+		return {
+			ok: false,
+			error: "PREVIEW_UNREACHABLE",
+			message: `Preview endpoint unreachable: ${String(err)}`
+		};
+	}
+	if (!res.ok && res.status !== 422) return {
+		ok: false,
+		error: "PREVIEW_REQUEST_FAILED",
+		message: `Preview endpoint returned ${res.status}.`
+	};
+	return await res.json();
+} });
+//#endregion
+export { createHttpPreviewClient };

package/dist/modules/mcp/resources/canonical.js

@@ -0,0 +1,30 @@
+import { afterPrefix, aliasedRoots, itemTemplates, primerUri } from "../helpers/uris.js";
+//#region src/modules/mcp/resources/canonical.ts
+var canonicalUri = (env, uri) => {
+	const rest = afterPrefix(uri, `plitzi://schema/${env}/`);
+	if (rest === void 0) return uri;
+	for (const root of aliasedRoots) {
+		if (rest === root) return `plitzi://${root}/${env}`;
+		if (rest.startsWith(`${root}/`)) return `plitzi://${root}/${env}/${rest.slice(root.length + 1)}`;
+	}
+	return uri;
+};
+/** 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. */
+var resourceErrorMessage = (env, uri) => {
+	const canonical = canonicalUri(env, uri);
+	if (itemTemplates(env).some((tpl) => canonical.startsWith(tpl.slice(0, tpl.lastIndexOf("/") + 1)))) return JSON.stringify({
+		error: "NOT_FOUND",
+		message: `No resource at '${uri}'. Its shape is valid but the ref does not resolve.`,
+		hint: "It may have been deleted or your URI is stale. Re-list the parent resource (pages/definitions) to refresh."
+	});
+	return JSON.stringify({
+		error: "MALFORMED_URI",
+		message: `'${uri}' matches no resource template.`,
+		hint: "Do not hand-build element URIs — take the ready-made uri from plitzi_search or a write response.",
+		validTemplates: [primerUri(env), ...itemTemplates(env)]
+	});
+};
+//#endregion
+export { canonicalUri, resourceErrorMessage };

package/dist/modules/mcp/resources/core.js

@@ -0,0 +1,15 @@
+import { cssProperties } from "../catalogs/cssCatalog.js";
+import { buildTypeRegistry } from "../catalogs/registry.js";
+import "../helpers/uris.js";
+import { guideText } from "../helpers/guide.js";
+import { envelope } from "./envelope.js";
+//#region src/modules/mcp/resources/core.ts
+/** 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. */
+var readCoreResource = (space, uri) => {
+	if (uri === "plitzi://guide") return envelope(guideText);
+	if (uri === "plitzi://types") return envelope(buildTypeRegistry(space.schema, space.catalog));
+	if (uri === "plitzi://css-properties") return envelope(cssProperties);
+};
+//#endregion
+export { readCoreResource };

package/dist/modules/mcp/resources/envelope.js

@@ -0,0 +1,14 @@
+import { computeVersion } from "../helpers/computeVersion.js";
+//#region src/modules/mcp/resources/envelope.ts
+/** Wrap any read projection with the version its optimistic-concurrency checks key on. */
+var envelope = (data) => ({
+	stateVersion: computeVersion(data),
+	data
+});
+var jsonContents = (uri, data) => ({ contents: [{
+	uri,
+	mimeType: "application/json",
+	text: JSON.stringify(data)
+}] });
+//#endregion
+export { envelope, jsonContents };

package/dist/modules/mcp/resources/primer.js

@@ -0,0 +1,30 @@
+import { cssProperties } from "../catalogs/cssCatalog.js";
+import { buildDataSourceCatalog, buildInteractionCatalog } from "../catalogs/observed.js";
+import { buildTypeRegistry } from "../catalogs/registry.js";
+import { guideQuickstart } from "../helpers/guide.js";
+import { envelope } from "./envelope.js";
+import { definitionRefs, styleVariablesToAI } from "../tools/operations/style/translator.js";
+import { foldersToAI, pageSummariesToAI, schemaVariablesToAI, settingsToAI } from "../tools/operations/schema/translator.js";
+//#region src/modules/mcp/resources/primer.ts
+/** 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. Carries the condensed `guideQuickstart` (not the full guideText, which the agent reads on demand at
+*  plitzi://guide) to keep the bundle small. Returns undefined when the URI is not the primer. */
+var readPrimerResource = (space, env, uri) => {
+	if (uri !== `plitzi://primer/${env}`) return;
+	return envelope({
+		guide: guideQuickstart,
+		types: buildTypeRegistry(space.schema, space.catalog),
+		cssProperties,
+		pages: pageSummariesToAI(space.schema),
+		folders: foldersToAI(space.schema),
+		definitions: definitionRefs(space.style),
+		styleVariables: styleVariablesToAI(space.style),
+		schemaVariables: schemaVariablesToAI(space.schema, false),
+		settings: settingsToAI(space.schema),
+		interactions: buildInteractionCatalog(space.schema),
+		dataSources: buildDataSourceCatalog(space.schema)
+	});
+};
+//#endregion
+export { readPrimerResource };

package/dist/modules/mcp/resources/register.js

@@ -0,0 +1,174 @@
+import { cssProperties } from "../catalogs/cssCatalog.js";
+import { guideText } from "../helpers/guide.js";
+import { resourceErrorMessage } from "./canonical.js";
+import { envelope, jsonContents } from "./envelope.js";
+import { readResource } from "./router.js";
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp";
+//#region src/modules/mcp/resources/register.ts
+/** 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. */
+var registerResources = (server, getSpace, env, log) => {
+	const emit = async (uri) => {
+		const start = performance.now();
+		try {
+			const result = readResource(await getSpace(), env, uri);
+			if (!result) throw new Error(resourceErrorMessage(env, uri));
+			log.resourceRead(uri, performance.now() - start);
+			return jsonContents(uri, result);
+		} catch (error) {
+			log.resourceRead(uri, performance.now() - start, error);
+			throw error;
+		}
+	};
+	server.registerResource("Guide", "plitzi://guide", {
+		description: "How to read and write this space with mcp-ai",
+		mimeType: "text/markdown"
+	}, () => ({ contents: [{
+		uri: "plitzi://guide",
+		mimeType: "text/markdown",
+		text: guideText
+	}] }));
+	server.registerResource("CSS properties", "plitzi://css-properties", {
+		description: "Valid kebab-case CSS property keys",
+		mimeType: "application/json"
+	}, () => jsonContents("plitzi://css-properties", envelope(cssProperties)));
+	const fixed = [
+		[
+			"Primer",
+			`plitzi://primer/${env}`,
+			"Read this FIRST. Cold-start bundle in one call: guide, types, css-properties and SUMMARIES of pages, definitions and variables — summaries only, never full page/element trees, so it stays small even on a large space. Open a page or element on demand afterwards."
+		],
+		[
+			"Element types",
+			"plitzi://types",
+			"Observed element types with props, slots and subTypes"
+		],
+		[
+			"Pages",
+			`plitzi://schema/${env}/pages`,
+			"Page summaries (ref, label, elementCount) — no element trees"
+		],
+		[
+			"Folders",
+			`plitzi://folders/${env}`,
+			"Page folders (the sidebar tree): ref, name, slug, parentId"
+		],
+		[
+			"Style definitions",
+			`plitzi://definitions/${env}`,
+			"Style definition refs (names)"
+		],
+		[
+			"Global styles",
+			`plitzi://global-styles/${env}`,
+			"Element types that have a site-wide global style"
+		],
+		[
+			"Id styles",
+			`plitzi://id-styles/${env}`,
+			"DOM ids that have an id rule (#id) targeting a single element"
+		],
+		[
+			"Style variables",
+			`plitzi://style-variables/${env}`,
+			"Design tokens by category"
+		],
+		[
+			"Schema variables",
+			`plitzi://schema-variables/${env}`,
+			"Space-level values referenced via {{name}}"
+		],
+		[
+			"Settings",
+			`plitzi://settings/${env}`,
+			"Space-level settings: global customCss and state/auth configuration"
+		],
+		[
+			"Interactions catalog",
+			`plitzi://interactions/${env}`,
+			"Interaction actions (observed, grouped by node type) plus the built-in vocabularies — globalCallbacks (with their source module), element callbacks and utilities — each with its full param schema, the vocabulary for upsertInteractionFlow"
+		],
+		[
+			"Data sources catalog",
+			`plitzi://data-sources/${env}`,
+			"Data-source paths and binding targets observed in this space — the vocabulary for upsertBinding"
+		],
+		[
+			"Style definitions (schema alias)",
+			`plitzi://schema/${env}/definitions`,
+			"Alias of plitzi://definitions/{env}"
+		],
+		[
+			"Style variables (schema alias)",
+			`plitzi://schema/${env}/style-variables`,
+			"Alias of plitzi://style-variables/{env}"
+		],
+		[
+			"Schema variables (schema alias)",
+			`plitzi://schema/${env}/schema-variables`,
+			"Alias of plitzi://schema-variables/{env}"
+		]
+	];
+	for (const [name, uri, description] of fixed) server.registerResource(name, uri, {
+		description,
+		mimeType: "application/json"
+	}, () => emit(uri));
+	const templates = [
+		[
+			"Page",
+			`plitzi://schema/${env}/pages/{ref}`,
+			"One page as a skeleton tree (ref/type/label/children), no props"
+		],
+		[
+			"Page styles",
+			`plitzi://schema/${env}/pages/{ref}/styles`,
+			"Every style a page uses in one read: class definitions its elements attach (with CSS) + global styles"
+		],
+		[
+			"Element",
+			`plitzi://schema/${env}/elements/{ref}`,
+			"One element in full detail (props, style) by ref or id"
+		],
+		[
+			"Folder",
+			`plitzi://folders/${env}/{ref}`,
+			"One page folder (name, slug, parentId) by folder id"
+		],
+		[
+			"Style definition",
+			`plitzi://definitions/${env}/{ref}`,
+			"One style definition (CSS) by class ref"
+		],
+		[
+			"Global style",
+			`plitzi://global-styles/${env}/{componentType}`,
+			"The site-wide CSS applied to every element of one type"
+		],
+		[
+			"Id style",
+			`plitzi://id-styles/${env}/{targetId}`,
+			"The CSS of an id rule (#id) targeting a single element"
+		],
+		[
+			"Style variables by category",
+			`plitzi://style-variables/${env}/{category}`,
+			"Design tokens for one category"
+		],
+		[
+			"Style definition (schema alias)",
+			`plitzi://schema/${env}/definitions/{ref}`,
+			"Alias of plitzi://definitions/{env}/{ref}"
+		],
+		[
+			"Style variables by category (schema alias)",
+			`plitzi://schema/${env}/style-variables/{category}`,
+			"Alias of plitzi://style-variables/{env}/{category}"
+		]
+	];
+	for (const [name, tpl, description] of templates) server.registerResource(name, new ResourceTemplate(tpl, { list: void 0 }), {
+		description,
+		mimeType: "application/json"
+	}, (uri) => emit(uri.href));
+};
+//#endregion
+export { registerResources };

package/dist/modules/mcp/resources/router.js

@@ -0,0 +1,25 @@
+import { canonicalUri } from "./canonical.js";
+import { readCoreResource } from "./core.js";
+import { readPrimerResource } from "./primer.js";
+import { readSchemaResource } from "./schema.js";
+import { readStyleResource } from "./style.js";
+//#region src/modules/mcp/resources/router.ts
+var resolvers = [
+	(space, _env, uri) => readCoreResource(space, uri),
+	readPrimerResource,
+	readSchemaResource,
+	readStyleResource
+];
+/** Resolve a resource URI to its versioned envelope, or null if unknown / not found. */
+var readResource = (space, env, rawUri) => {
+	const uri = canonicalUri(env, rawUri);
+	for (const resolve of resolvers) {
+		const result = resolve(space, env, uri);
+		if (result !== void 0) return result;
+	}
+	return null;
+};
+/** Current version of a resource, for optimistic-concurrency checks. Null when the URI is unknown. */
+var resourceVersion = (space, env, uri) => readResource(space, env, uri)?.stateVersion ?? null;
+//#endregion
+export { readResource, resourceVersion };