@hirokisakabe/pom 8.2.1 → 8.4.0

package/dist/parseXml/parseXml.js

@@ -1,4 +1,5 @@
-import { arrowNodeSchema, chartNodeSchema, flowNodeSchema, iconNodeSchema, imageNodeSchema, lineNodeSchema, matrixNodeSchema, olNodeSchema, processArrowNodeSchema, pyramidNodeSchema, shapeNodeSchema, tableNodeSchema, textNodeSchema, timelineNodeSchema, treeNodeSchema, ulNodeSchema } from "../types.js";
+import { NODE_METADATA, getNodeMetadata, getNodeMetadataByTag } from "../registry/nodeMetadata.js";
+import { INLINE_BOOLEAN_FORMATS, INLINE_FORMAT_TAGS, INLINE_FORMAT_TAG_LIST, MARK_DEFAULT_HIGHLIGHT_COLOR, formatExpectedTags } from "../registry/xmlChildRules.js";
 import { CHILD_ELEMENT_COERCION_MAP, NODE_COERCION_MAP, coerceFallback, coerceWithRule, getObjectShapeFromRule, resolveMixedNotationShorthand } from "./coercionRules.js";
 import { XMLBuilder, XMLParser } from "fast-xml-parser";
 //#region src/parseXml/parseXml.ts
@@ -11,35 +12,7 @@ var ParseXmlError = class extends Error {
 		this.errors = errors;
 	}
 };
-const TAG_TO_TYPE = {
-	Text: "text",
-	Image: "image",
-	Table: "table",
-	Shape: "shape",
-	Chart: "chart",
-	Timeline: "timeline",
-	Matrix: "matrix",
-	Tree: "tree",
-	Flow: "flow",
-	ProcessArrow: "processArrow",
-	Pyramid: "pyramid",
-	Ul: "ul",
-	Ol: "ol",
-	Line: "line",
-	Arrow: "arrow",
-	VStack: "vstack",
-	HStack: "hstack",
-	Layer: "layer",
-	Icon: "icon",
-	Svg: "svg"
-};
-const TYPE_TO_TAG = Object.fromEntries(Object.entries(TAG_TO_TYPE).map(([tag, type]) => [type, tag]));
-const CONTAINER_TYPES = new Set([
-	"vstack",
-	"hstack",
-	"layer"
-]);
-const TEXT_CONTENT_NODES = new Set(["text", "shape"]);
+Object.fromEntries(NODE_METADATA.map((def) => [def.tagName, def.type]));
 const UNIVERSAL_ATTRS = new Set(["x", "y"]);
 function getKnownAttributes(nodeType) {
 	const rules = NODE_COERCION_MAP[nodeType];
@@ -73,24 +46,6 @@ function getKnownChildAttributes(tagName) {
 	if (!rules) return [];
 	return Object.keys(rules);
 }
-const leafNodeValidationSchemas = {
-	text: textNodeSchema,
-	image: imageNodeSchema,
-	table: tableNodeSchema,
-	shape: shapeNodeSchema,
-	chart: chartNodeSchema,
-	timeline: timelineNodeSchema,
-	matrix: matrixNodeSchema,
-	tree: treeNodeSchema,
-	flow: flowNodeSchema,
-	processArrow: processArrowNodeSchema,
-	pyramid: pyramidNodeSchema,
-	line: lineNodeSchema,
-	arrow: arrowNodeSchema,
-	ul: ulNodeSchema,
-	ol: olNodeSchema,
-	icon: iconNodeSchema
-};
 function formatZodIssue(issue, tagName) {
 	const path = issue.path;
 	if (path.length > 0 && path[0] === "children") return null;
@@ -120,34 +75,17 @@ function formatZodIssue(issue, tagName) {
 	if (attrName) return `<${tagName}>: Attribute "${attrName}": ${issue.message}`;
 	return `<${tagName}>: ${issue.message}`;
 }
-const CHILD_ELEMENT_PROPS = {
-	flow: new Set(["nodes", "connections"]),
-	table: new Set(["columns", "rows"]),
-	chart: new Set(["data"]),
-	timeline: new Set(["items"]),
-	matrix: new Set([
-		"axes",
-		"items",
-		"quadrants"
-	]),
-	processArrow: new Set(["steps"]),
-	pyramid: new Set(["levels"]),
-	tree: new Set(["data"]),
-	ul: new Set(["items"]),
-	ol: new Set(["items"]),
-	icon: new Set(["name"]),
-	svg: new Set(["svgContent"])
-};
 function validateLeafNode(nodeType, result, errors) {
-	const schema = leafNodeValidationSchemas[nodeType];
-	if (!schema) return;
-	const tagName = TYPE_TO_TAG[nodeType] ?? nodeType;
-	const childProps = CHILD_ELEMENT_PROPS[nodeType];
+	const def = getNodeMetadata(nodeType);
+	if (def.childPolicy.kind === "pom-children") return;
+	const schema = def.schema;
+	const tagName = def.tagName;
+	const optionalChildProps = new Set(def.childPolicy.kind === "custom" ? def.childPolicy.optionalProperties ?? [] : []);
 	const parseResult = schema.safeParse(result);
 	if (!parseResult.success) {
 		const seen = /* @__PURE__ */ new Set();
 		for (const issue of parseResult.error.issues) {
-			if (childProps && issue.path.length === 1 && childProps.has(String(issue.path[0])) && issue.code === "invalid_type" && issue.input === void 0) continue;
+			if (optionalChildProps.size > 0 && issue.path.length === 1 && optionalChildProps.has(String(issue.path[0])) && issue.code === "invalid_type" && issue.input === void 0) continue;
 			if (issue.path.length > 0 && UNIVERSAL_ATTRS.has(String(issue.path[0]))) continue;
 			const msg = formatZodIssue(issue, tagName);
 			if (msg && !seen.has(msg)) {
@@ -222,52 +160,46 @@ function getTextContent(node) {
 function getRawChildren(node) {
 	return node[getTagName(node)] ?? [];
 }
-const INLINE_FORMAT_TAGS = new Set([
-	"B",
-	"I",
-	"A",
-	"U",
-	"S",
-	"Mark",
-	"Span"
-]);
 function hasInlineFormatChildren(childElements) {
 	return childElements.length > 0 && childElements.every((el) => INLINE_FORMAT_TAGS.has(getTagName(el)));
 }
-function extractTextRuns(children, inheritBold, inheritItalic, inheritHref, inheritUnderline, inheritStrike, inheritHighlight, inheritColor, inheritFontFamily) {
+function extractTextRuns(children, inherited = {}) {
 	const runs = [];
-	for (const child of children) if (isTextNode(child)) {
-		const run = { text: child["#text"] };
-		if (inheritBold) run.bold = true;
-		if (inheritItalic) run.italic = true;
-		if (inheritUnderline) run.underline = true;
-		if (inheritStrike) run.strike = true;
-		if (inheritHighlight) run.highlight = inheritHighlight;
-		if (inheritColor) run.color = inheritColor;
-		if (inheritHref) run.href = inheritHref;
-		if (inheritFontFamily) run.fontFamily = inheritFontFamily;
-		runs.push(run);
-	} else {
+	for (const child of children) {
+		if (isTextNode(child)) {
+			runs.push({
+				text: child["#text"],
+				...inherited
+			});
+			continue;
+		}
 		const tag = getTagName(child);
 		const innerChildren = getRawChildren(child);
-		if (tag === "B") runs.push(...extractTextRuns(innerChildren, true, inheritItalic, inheritHref, inheritUnderline, inheritStrike, inheritHighlight, inheritColor, inheritFontFamily));
-		else if (tag === "I") runs.push(...extractTextRuns(innerChildren, inheritBold, true, inheritHref, inheritUnderline, inheritStrike, inheritHighlight, inheritColor, inheritFontFamily));
+		const booleanFormat = INLINE_BOOLEAN_FORMATS.find((format) => format.tag === tag);
+		if (booleanFormat) runs.push(...extractTextRuns(innerChildren, {
+			...inherited,
+			[booleanFormat.property]: true
+		}));
 		else if (tag === "A") {
-			const href = getAttributes(child).href ?? "";
-			runs.push(...extractTextRuns(innerChildren, inheritBold, inheritItalic, href, inheritUnderline, inheritStrike, inheritHighlight, inheritColor, inheritFontFamily));
-		} else if (tag === "U") runs.push(...extractTextRuns(innerChildren, inheritBold, inheritItalic, inheritHref, true, inheritStrike, inheritHighlight, inheritColor, inheritFontFamily));
-		else if (tag === "S") runs.push(...extractTextRuns(innerChildren, inheritBold, inheritItalic, inheritHref, inheritUnderline, true, inheritHighlight, inheritColor, inheritFontFamily));
-		else if (tag === "Mark") {
+			const next = { ...inherited };
+			const href = getAttributes(child).href;
+			if (href) next.href = href;
+			else delete next.href;
+			runs.push(...extractTextRuns(innerChildren, next));
+		} else if (tag === "Mark") {
 			const rawColor = getAttributes(child).color;
-			const color = rawColor && rawColor.trim() ? rawColor : "FFFF00";
-			runs.push(...extractTextRuns(innerChildren, inheritBold, inheritItalic, inheritHref, inheritUnderline, inheritStrike, color, inheritColor, inheritFontFamily));
+			const highlight = rawColor && rawColor.trim() ? rawColor : MARK_DEFAULT_HIGHLIGHT_COLOR;
+			runs.push(...extractTextRuns(innerChildren, {
+				...inherited,
+				highlight
+			}));
 		} else if (tag === "Span") {
 			const spanAttrs = getAttributes(child);
-			const rawSpanColor = spanAttrs.color;
-			const spanColor = rawSpanColor && rawSpanColor.trim() ? rawSpanColor : inheritColor;
-			const rawSpanFontFamily = spanAttrs.fontFamily;
-			const spanFontFamily = rawSpanFontFamily && rawSpanFontFamily.trim() ? rawSpanFontFamily : inheritFontFamily;
-			runs.push(...extractTextRuns(innerChildren, inheritBold, inheritItalic, inheritHref, inheritUnderline, inheritStrike, inheritHighlight, spanColor, spanFontFamily));
+			const next = { ...inherited };
+			if (spanAttrs.color && spanAttrs.color.trim()) next.color = spanAttrs.color;
+			if (spanAttrs.fontFamily && spanAttrs.fontFamily.trim()) next.fontFamily = spanAttrs.fontFamily;
+			if (spanAttrs.letterSpacing && spanAttrs.letterSpacing.trim()) next.letterSpacing = Number(spanAttrs.letterSpacing);
+			runs.push(...extractTextRuns(innerChildren, next));
 		}
 	}
 	return runs;
@@ -320,85 +252,78 @@ function coerceChildAttrs(parentTagName, tagName, attrs, errors) {
 	}
 	return result;
 }
-function convertProcessArrowChildren(childElements, result, errors) {
-	const steps = [];
-	for (const child of childElements) {
-		const tag = getTagName(child);
-		if (tag !== "ProcessArrowStep") {
-			errors.push(`Unknown child element <${tag}> inside <ProcessArrow>. Expected: <ProcessArrowStep>`);
-			continue;
-		}
-		steps.push(coerceChildAttrs("ProcessArrow", tag, getAttributes(child), errors));
-	}
-	result.steps = steps;
+function unknownChildError(childTag, parentTag, expectedTags) {
+	return `Unknown child element <${childTag}> inside <${parentTag}>. Expected: ${formatExpectedTags(expectedTags)}`;
 }
-function convertPyramidChildren(childElements, result, errors) {
-	const levels = [];
-	for (const child of childElements) {
-		const tag = getTagName(child);
-		if (tag !== "PyramidLevel") {
-			errors.push(`Unknown child element <${tag}> inside <Pyramid>. Expected: <PyramidLevel>`);
-			continue;
-		}
-		levels.push(coerceChildAttrs("Pyramid", tag, getAttributes(child), errors));
+/** element の text content / インライン装飾を attrs の text / runs へ反映する */
+function applyTextAndRuns(element, attrs) {
+	const runsResult = buildRunsAndText(element);
+	if (runsResult) {
+		attrs.runs = runsResult.runs;
+		attrs.text = runsResult.text;
+	} else {
+		const textContent = getTextContent(element);
+		if (textContent !== void 0 && !("text" in attrs)) attrs.text = textContent;
 	}
-	result.levels = levels;
 }
-function convertTimelineChildren(childElements, result, errors) {
+/** RepeatedChildRule (単一種類の child tag の繰り返し → 配列 property) の汎用 converter */
+function convertRepeatedChildren(rule, parentTag, childElements, result, errors) {
 	const items = [];
 	for (const child of childElements) {
 		const tag = getTagName(child);
-		if (tag !== "TimelineItem") {
-			errors.push(`Unknown child element <${tag}> inside <Timeline>. Expected: <TimelineItem>`);
+		if (tag !== rule.childTag) {
+			errors.push(unknownChildError(tag, parentTag, [rule.childTag]));
 			continue;
 		}
-		items.push(coerceChildAttrs("Timeline", tag, getAttributes(child), errors));
+		const attrs = coerceChildAttrs(parentTag, tag, getAttributes(child), errors);
+		if (rule.allowsItemText) applyTextAndRuns(child, attrs);
+		items.push(attrs);
 	}
-	result.items = items;
+	result[rule.property] = items;
 }
-function convertMatrixChildren(childElements, result, errors) {
+function convertMatrixChildren(rule, tagName, childElements, result, errors) {
 	const items = [];
 	for (const child of childElements) {
 		const tag = getTagName(child);
 		switch (tag) {
 			case "MatrixAxes":
-				result.axes = coerceChildAttrs("Matrix", tag, getAttributes(child), errors);
+				result.axes = coerceChildAttrs(tagName, tag, getAttributes(child), errors);
 				break;
 			case "MatrixQuadrants":
-				result.quadrants = coerceChildAttrs("Matrix", tag, getAttributes(child), errors);
+				result.quadrants = coerceChildAttrs(tagName, tag, getAttributes(child), errors);
 				break;
 			case "MatrixItem":
-				items.push(coerceChildAttrs("Matrix", tag, getAttributes(child), errors));
+				items.push(coerceChildAttrs(tagName, tag, getAttributes(child), errors));
 				break;
-			default: errors.push(`Unknown child element <${tag}> inside <Matrix>. Expected: <MatrixAxes>, <MatrixQuadrants>, or <MatrixItem>`);
+			default: errors.push(unknownChildError(tag, tagName, rule.expectedTags));
 		}
 	}
 	if (items.length > 0) result.items = items;
 }
-function convertFlowChildren(childElements, result, errors) {
+function convertFlowChildren(rule, tagName, childElements, result, errors) {
 	const nodes = [];
 	const connections = [];
 	for (const child of childElements) {
 		const tag = getTagName(child);
 		switch (tag) {
 			case "FlowNode":
-				nodes.push(coerceChildAttrs("Flow", tag, getAttributes(child), errors));
+				nodes.push(coerceChildAttrs(tagName, tag, getAttributes(child), errors));
 				break;
 			case "FlowConnection":
-				connections.push(coerceChildAttrs("Flow", tag, getAttributes(child), errors));
+				connections.push(coerceChildAttrs(tagName, tag, getAttributes(child), errors));
 				break;
-			default: errors.push(`Unknown child element <${tag}> inside <Flow>. Expected: <FlowNode> or <FlowConnection>`);
+			default: errors.push(unknownChildError(tag, tagName, rule.expectedTags));
 		}
 	}
 	if (nodes.length > 0) result.nodes = nodes;
 	if (connections.length > 0) result.connections = connections;
 }
-function convertChartChildren(childElements, result, errors) {
+function convertChartChildren(rule, tagName, childElements, result, errors) {
 	const data = [];
 	for (const child of childElements) {
 		const tag = getTagName(child);
 		if (tag !== "ChartSeries") {
-			errors.push(`Unknown child element <${tag}> inside <Chart>. Expected: <ChartSeries>`);
+			errors.push(unknownChildError(tag, tagName, rule.expectedTags));
 			continue;
 		}
 		const attrs = getAttributes(child);
@@ -410,7 +335,7 @@ function convertChartChildren(childElements, result, errors) {
 		for (const dp of getChildElements(child)) {
 			const dpTag = getTagName(dp);
 			if (dpTag !== "ChartDataPoint") {
-				errors.push(`Unknown child element <${dpTag}> inside <ChartSeries>. Expected: <ChartDataPoint>`);
+				errors.push(unknownChildError(dpTag, "ChartSeries", ["ChartDataPoint"]));
 				continue;
 			}
 			const dpAttrs = getAttributes(dp);
@@ -429,14 +354,14 @@ function convertChartChildren(childElements, result, errors) {
 	}
 	result.data = data;
 }
-function convertTableChildren(childElements, result, errors) {
+function convertTableChildren(rule, tagName, childElements, result, errors) {
 	const columns = [];
 	const rows = [];
 	for (const child of childElements) {
 		const tag = getTagName(child);
 		switch (tag) {
 			case "Col":
-				columns.push(coerceChildAttrs("Table", tag, getAttributes(child), errors));
+				columns.push(coerceChildAttrs(tagName, tag, getAttributes(child), errors));
 				break;
 			case "Tr": {
 				const rowAttrs = getAttributes(child);
@@ -444,18 +369,11 @@ function convertTableChildren(childElements, result, errors) {
 				for (const cellEl of getChildElements(child)) {
 					const cellTag = getTagName(cellEl);
 					if (cellTag !== "Td") {
-						errors.push(`Unknown child element <${cellTag}> inside <Tr>. Expected: <Td>`);
+						errors.push(unknownChildError(cellTag, "Tr", ["Td"]));
 						continue;
 					}
 					const cellAttrs = coerceChildAttrs("Tr", cellTag, getAttributes(cellEl), errors);
-					const runsResult = buildRunsAndText(cellEl);
-					if (runsResult) {
-						cellAttrs.runs = runsResult.runs;
-						cellAttrs.text = runsResult.text;
-					} else {
-						const cellText = getTextContent(cellEl);
-						if (cellText !== void 0 && !("text" in cellAttrs)) cellAttrs.text = cellText;
-					}
+					applyTextAndRuns(cellEl, cellAttrs);
 					cells.push(cellAttrs);
 				}
 				const row = { cells };
@@ -467,7 +385,7 @@ function convertTableChildren(childElements, result, errors) {
 				rows.push(row);
 				break;
 			}
-			default: errors.push(`Unknown child element <${tag}> inside <Table>. Expected: <Col> or <Tr>`);
+			default: errors.push(unknownChildError(tag, tagName, rule.expectedTags));
 		}
 	}
 	if (columns.length > 0) result.columns = columns;
@@ -483,18 +401,19 @@ function convertTreeItem(element, errors) {
 	const item = {};
 	if (attrs.label !== void 0) item.label = attrs.label;
 	if (attrs.color !== void 0) item.color = attrs.color;
+	if (attrs.textColor !== void 0) item.textColor = attrs.textColor;
 	const children = getChildElements(element);
 	if (children.length > 0) item.children = children.map((child) => {
 		const tag = getTagName(child);
 		if (tag !== "TreeItem") {
-			errors.push(`Unknown child element <${tag}> inside <TreeItem>. Expected: <TreeItem>`);
+			errors.push(unknownChildError(tag, "TreeItem", ["TreeItem"]));
 			return null;
 		}
 		return convertTreeItem(child, errors);
 	}).filter((item) => item !== null);
 	return item;
 }
-function convertTreeChildren(childElements, result, errors) {
+function convertTreeChildren(rule, tagName, childElements, result, errors) {
 	if (childElements.length !== 1) {
 		errors.push(`<Tree> must have exactly 1 <TreeItem> child element, but got ${childElements.length}`);
 		return;
@@ -502,32 +421,11 @@ function convertTreeChildren(childElements, result, errors) {
 	const child = childElements[0];
 	const tag = getTagName(child);
 	if (tag !== "TreeItem") {
-		errors.push(`Unknown child element <${tag}> inside <Tree>. Expected: <TreeItem>`);
+		errors.push(unknownChildError(tag, tagName, rule.expectedTags));
 		return;
 	}
 	result.data = convertTreeItem(child, errors);
 }
-function convertListChildren(parentTag, childElements, result, errors) {
-	const items = [];
-	for (const child of childElements) {
-		const tag = getTagName(child);
-		if (tag !== "Li") {
-			errors.push(`Unknown child element <${tag}> inside <${parentTag}>. Expected: <Li>`);
-			continue;
-		}
-		const attrs = coerceChildAttrs(parentTag, tag, getAttributes(child), errors);
-		const runsResult = buildRunsAndText(child);
-		if (runsResult) {
-			attrs.runs = runsResult.runs;
-			attrs.text = runsResult.text;
-		} else {
-			const textContent = getTextContent(child);
-			if (textContent !== void 0 && !("text" in attrs)) attrs.text = textContent;
-		}
-		items.push(attrs);
-	}
-	result.items = items;
-}
 const svgBuilder = new XMLBuilder({
 	preserveOrder: true,
 	ignoreAttributes: false,
@@ -536,7 +434,7 @@ const svgBuilder = new XMLBuilder({
 function serializeSvgElement(svgElement) {
 	return String(svgBuilder.build([svgElement]));
 }
-function convertSvgChildren(childElements, result, errors) {
+function convertSvgChildren(_rule, _tagName, childElements, result, errors) {
 	if (childElements.length !== 1) {
 		errors.push(`<Svg>: Expected exactly one <svg> child element, but found ${childElements.length} child element(s)`);
 		return;
@@ -549,11 +447,13 @@ function convertSvgChildren(childElements, result, errors) {
 	}
 	result.svgContent = serializeSvgElement(child);
 }
-function convertTextInlineChildren(childElements, result, errors, node) {
+function convertInlineRunsChildren(tagName, childElements, result, errors, node) {
 	for (const el of childElements) {
 		const tag = getTagName(el);
 		if (!INLINE_FORMAT_TAGS.has(tag)) {
-			errors.push(`<Text>: Unexpected child element <${tag}>. Only <B>, <I>, <A>, <U>, <S>, <Mark>, and <Span> are allowed inside <Text>`);
+			const allowedTags = INLINE_FORMAT_TAG_LIST.map((t) => `<${t}>`);
+			const allowedList = `${allowedTags.slice(0, -1).join(", ")}, and ${allowedTags[allowedTags.length - 1]}`;
+			errors.push(`<${tagName}>: Unexpected child element <${tag}>. Only ${allowedList} are allowed inside <${tagName}>`);
 			return;
 		}
 	}
@@ -564,13 +464,8 @@ function convertTextInlineChildren(childElements, result, errors, node) {
 		result.text = runsResult.text;
 	}
 }
-const CHILD_ELEMENT_CONVERTERS = {
-	text: convertTextInlineChildren,
-	ul: (childElements, result, errors) => convertListChildren("Ul", childElements, result, errors),
-	ol: (childElements, result, errors) => convertListChildren("Ol", childElements, result, errors),
-	processArrow: convertProcessArrowChildren,
-	pyramid: convertPyramidChildren,
-	timeline: convertTimelineChildren,
+/** NodeSpecificChildRule を持つノードの専用 converter テーブル */
+const NODE_SPECIFIC_CHILD_CONVERTERS = {
 	matrix: convertMatrixChildren,
 	flow: convertFlowChildren,
 	chart: convertChartChildren,
@@ -578,20 +473,85 @@ const CHILD_ELEMENT_CONVERTERS = {
 	tree: convertTreeChildren,
 	svg: convertSvgChildren
 };
-function convertElement(node, errors) {
+/** NodeMetadata の xmlChildRule に従って child element を変換する */
+function applyXmlChildRule(rule, nodeType, tagName, childElements, result, errors, node) {
+	if (rule.kind === "inline-runs") {
+		convertInlineRunsChildren(tagName, childElements, result, errors, node);
+		return;
+	}
+	if (rule.kind === "repeated") {
+		convertRepeatedChildren(rule, tagName, childElements, result, errors);
+		return;
+	}
+	const converter = NODE_SPECIFIC_CHILD_CONVERTERS[nodeType];
+	if (!converter) throw new Error(`No node-specific child converter registered for node type: ${nodeType}`);
+	converter(rule, tagName, childElements, result, errors);
+}
+const THEME_TOKEN_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*$/;
+const THEME_TOKEN_VALUE_PATTERN = /^[0-9A-Fa-f]{6}$/;
+const TOKEN_REF_PATTERN = /^(#?)\$([A-Za-z][A-Za-z0-9_-]*)$/;
+const TOKEN_REF_IN_GRADIENT_PATTERN = /#?\$([A-Za-z][A-Za-z0-9_-]*)/g;
+function parseThemeElement(element, tokens, errors) {
+	if (getChildElements(element).length > 0) errors.push(`<Theme>: Child elements are not supported. Declare tokens as attributes (e.g. <Theme accent="1D4ED8" />)`);
+	for (const [name, rawValue] of Object.entries(getAttributes(element))) {
+		if (!THEME_TOKEN_NAME_PATTERN.test(name)) {
+			errors.push(`<Theme>: Invalid token name "${name}". Token names must start with a letter and contain only letters, digits, "_", and "-"`);
+			continue;
+		}
+		const value = rawValue.replace(/^#/, "");
+		if (!THEME_TOKEN_VALUE_PATTERN.test(value)) {
+			errors.push(`<Theme>: Invalid color value "${rawValue}" for token "${name}". Expected 6-digit hex (e.g. "1D4ED8")`);
+			continue;
+		}
+		tokens[name] = value;
+	}
+}
+function isColorKey(key) {
+	return /colors?$/i.test(key) || key === "highlight";
+}
+function resolveThemeToken(name, hashPrefix, tokens, themeDeclared, errors) {
+	const value = tokens[name];
+	if (value !== void 0) return `${hashPrefix}${value}`;
+	if (!themeDeclared) errors.push(`Theme token "$${name}" is referenced, but no <Theme> is declared. Add a top-level <Theme ${name}="RRGGBB" /> element`);
+	else {
+		const suggestion = findClosestMatch(name, Object.keys(tokens));
+		errors.push(`Unknown theme token "$${name}"${suggestion ? `. Did you mean "$${suggestion}"?` : ""}`);
+	}
+}
+function resolveThemeTokensDeep(value, key, tokens, themeDeclared, errors) {
+	if (typeof value === "string") {
+		if (key === "backgroundGradient") return value.replace(TOKEN_REF_IN_GRADIENT_PATTERN, (matched, name) => {
+			return resolveThemeToken(name, "#", tokens, themeDeclared, errors) ?? matched;
+		});
+		if (key !== null && isColorKey(key)) {
+			const match = TOKEN_REF_PATTERN.exec(value.trim());
+			if (match) return resolveThemeToken(match[2], match[1], tokens, themeDeclared, errors) ?? value;
+		}
+		return value;
+	}
+	if (Array.isArray(value)) return value.map((item) => resolveThemeTokensDeep(item, key, tokens, themeDeclared, errors));
+	if (typeof value === "object" && value !== null) {
+		const result = {};
+		for (const [childKey, childValue] of Object.entries(value)) result[childKey] = resolveThemeTokensDeep(childValue, childKey, tokens, themeDeclared, errors);
+		return result;
+	}
+	return value;
+}
+function convertElement(node, errors, theme) {
 	const tagName = getTagName(node);
-	const nodeType = TAG_TO_TYPE[tagName];
+	const def = getNodeMetadataByTag(tagName);
 	const attrs = getAttributes(node);
 	const childElements = getChildElements(node);
 	const textContent = getTextContent(node);
-	if (nodeType) return convertPomNode(nodeType, tagName, attrs, childElements, textContent, errors, node);
+	if (def) return convertPomNode(def.type, tagName, attrs, childElements, textContent, errors, theme, node);
 	else {
 		errors.push(`Unknown tag: <${tagName}>`);
 		return null;
 	}
 }
-function convertPomNode(nodeType, tagName, attrs, childElements, textContent, errors, xmlNode) {
+function convertPomNode(nodeType, tagName, attrs, childElements, textContent, errors, theme, xmlNode) {
 	const result = { type: nodeType };
+	const def = getNodeMetadata(nodeType);
 	const { regular: regularAttrs, dotGroups } = expandDotNotation(attrs);
 	for (const [prefix, subAttrs] of Object.entries(dotGroups)) {
 		if (prefix === "type") continue;
@@ -633,14 +593,18 @@ function convertPomNode(nodeType, tagName, attrs, childElements, textContent, er
 			else errors.push(`<${tagName}>: Unknown attribute "${key}"`);
 		}
 	}
-	if (textContent !== void 0 && TEXT_CONTENT_NODES.has(nodeType)) {
-		if (!("text" in result)) result.text = textContent;
+	if (textContent !== void 0 && def.textContentProperty) {
+		if (!(def.textContentProperty in result)) result[def.textContentProperty] = textContent;
 	}
-	const childConverter = CHILD_ELEMENT_CONVERTERS[nodeType];
-	if (childConverter && childElements.length > 0) childConverter(childElements, result, errors, xmlNode);
-	else if (CONTAINER_TYPES.has(nodeType) && childElements.length > 0) result.children = childElements.map((child) => convertElement(child, errors)).filter((child) => child !== null);
-	else if (!CONTAINER_TYPES.has(nodeType) && !childConverter && childElements.length > 0) errors.push(`<${tagName}>: Unexpected child elements. <${tagName}> does not accept child elements`);
-	if (!CONTAINER_TYPES.has(nodeType)) validateLeafNode(nodeType, result, errors);
+	const childRule = def.xmlChildRule;
+	if (childRule && childElements.length > 0) applyXmlChildRule(childRule, nodeType, tagName, childElements, result, errors, xmlNode);
+	else if (def.childPolicy.kind === "pom-children" && childElements.length > 0) result.children = childElements.map((child) => convertElement(child, errors, theme)).filter((child) => child !== null);
+	else if (def.childPolicy.kind !== "pom-children" && !childRule && childElements.length > 0) errors.push(`<${tagName}>: Unexpected child elements. <${tagName}> does not accept child elements`);
+	for (const [key, value] of Object.entries(result)) {
+		if (key === "type" || key === "children") continue;
+		result[key] = resolveThemeTokensDeep(value, key, theme.tokens, theme.declared, errors);
+	}
+	if (def.childPolicy.kind !== "pom-children") validateLeafNode(nodeType, result, errors);
 	if (nodeType === "icon") {
 		if (typeof result.color === "string" && !result.color.startsWith("#")) result.color = `#${result.color}`;
 		if (typeof result.bgColor === "string" && !result.bgColor.startsWith("#")) result.bgColor = `#${result.bgColor}`;
@@ -654,9 +618,14 @@ function convertPomNode(nodeType, tagName, attrs, childElements, textContent, er
 /**
 * XML 文字列を POMNode 配列に変換する。
 *
-* 最上位は `<Slide>` 要素のみが許容される。各 `<Slide>` が 1 つのスライドに
-* 対応し、その子要素がスライドのルート POMNode となる。子要素が複数ある場合は
-* 暗黙的に VStack でラップされる。
+* 最上位は `<Slide>` 要素と `<Theme>` 要素のみが許容される。各 `<Slide>` が
+* 1 つのスライドに対応し、その子要素がスライドのルート POMNode となる。
+* 子要素が複数ある場合は暗黙的に VStack でラップされる。
+*
+* `<Theme>` は文書全体に適用されるデザイントークン（配色）の宣言で、最大 1 つ
+* 置ける。属性名がトークン名、属性値が 6 桁 hex の色値となり、各ノードの色属性
+* から `$トークン名` で参照できる。参照は parse 時に解決されるため、返される
+* POMNode には解決済みの hex 値が入る（`<Theme>` 自体はノードにならない）。
 *
 * XML タグは POM ノードタイプにマッピングされ、属性値は Zod スキーマを参照して
 * 適切な型（number, boolean, array, object）に変換される。
@@ -693,12 +662,26 @@ function parseXml(xmlString) {
 	if (!parsed || parsed.length === 0) return [];
 	const rootChildren = parsed[0]["__root__"] ?? [];
 	const errors = [];
-	const slideElements = rootChildren.filter((child) => !isTextNode(child));
+	const topLevelElements = rootChildren.filter((child) => !isTextNode(child));
+	const theme = {
+		tokens: {},
+		declared: false
+	};
+	for (const element of topLevelElements) {
+		if (getTagName(element) !== "Theme") continue;
+		if (theme.declared) {
+			errors.push(`Only one <Theme> element is allowed, but multiple were found`);
+			continue;
+		}
+		theme.declared = true;
+		parseThemeElement(element, theme.tokens, errors);
+	}
+	const slideElements = topLevelElements.filter((element) => getTagName(element) !== "Theme");
 	const nodes = [];
 	for (const slideEl of slideElements) {
 		const tagName = getTagName(slideEl);
 		if (tagName !== "Slide") {
-			errors.push(`Top-level element must be <Slide>, but got <${tagName}>. Wrap your slide content in <Slide>...</Slide>.`);
+			errors.push(`Top-level element must be <Slide> or <Theme>, but got <${tagName}>. Wrap your slide content in <Slide>...</Slide>.`);
 			continue;
 		}
 		if (Object.keys(getAttributes(slideEl)).length > 0) errors.push(`<Slide>: Attributes are not supported`);
@@ -707,7 +690,7 @@ function parseXml(xmlString) {
 			errors.push(`<Slide> must contain at least one child element`);
 			continue;
 		}
-		const converted = slideChildren.map((child) => convertElement(child, errors)).filter((c) => c !== null);
+		const converted = slideChildren.map((child) => convertElement(child, errors, theme)).filter((c) => c !== null);
 		if (converted.length === 0) continue;
 		if (converted.length === 1) nodes.push(converted[0]);
 		else nodes.push({
@@ -719,6 +702,6 @@ function parseXml(xmlString) {
 	return nodes;
 }
 //#endregion
-export { ParseXmlError, TAG_TO_TYPE, parseXml };
+export { ParseXmlError, parseXml };
 
 //# sourceMappingURL=parseXml.js.map