deckjsx 0.6.0 → 0.7.0

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { a as diagnostic, c as SemanticGraphDiagnosticError, d as formatDiagnostics, i as createDiagnostics, l as StyleDiagnosticError, n as EMU_PER_INCH, o as CompositionDiagnosticError, r as POINTS_PER_INCH, s as DeckDiagnosticError, t as pptxgenjs, u as formatDiagnostic } from "./adapter-BbtteJ7s.mjs";
-import { a as isContentNode, c as Shape, d as View, f as isAuthorNodeValue, h as isAuthoredTag, i as isAuthorNode, l as Slide, m as isAuthorTreeNode, n as createElement, o as isSlideNode, p as toAuthorJsxNode, s as Image, t as Fragment, u as Text } from "./jsx-C671yNZa.mjs";
+import { a as diagnostic, c as SemanticGraphDiagnosticError, d as formatDiagnostics, i as createDiagnostics, l as StyleDiagnosticError, n as EMU_PER_INCH, o as CompositionDiagnosticError, r as POINTS_PER_INCH, s as DeckDiagnosticError, t as pptxgenjs, u as formatDiagnostic } from "./adapter-rS3mWdi0.mjs";
+import { a as isContentNode, c as Shape, d as isAuthorNodeValue, f as toAuthorJsxNode, h as isAuthoredTag, i as isAuthorNode, l as Text, m as isAuthorTreeNode, n as createElement, o as isSlideNode, p as createAuthorElement, s as Image, t as Fragment, u as View } from "./jsx-DetoUfLm.mjs";
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 //#region src/composition/types.ts
@@ -20,6 +20,226 @@ function stageSummary(stage, diagnostics, artifact) {
 		artifact
 	};
 }
+const DEFAULT_FONT_SIZE_PT = 16 / 96 * 72;
+const CH_WIDTH_RATIO = .5;
+const DECK_LENGTH_PATTERN = /^[-+]?(?:\d+|\d*\.\d+)(?:in|pt|px|%|em|rem|vh|vw|ch)$/i;
+const DECK_POINT_LENGTH_PATTERN = /^[-+]?(?:\d+|\d*\.\d+)(?:pt|in|px|em|rem|vh|vw|ch)$/i;
+function pointsToEmu(value) {
+	return value / 72 * EMU_PER_INCH;
+}
+function parsePercentage$1(value) {
+	const trimmed = value.trim();
+	if (!trimmed.endsWith("%")) return;
+	return Number.parseFloat(trimmed.slice(0, -1));
+}
+function resolvePointUnitBase(context) {
+	return context?.fontSizePt ?? DEFAULT_FONT_SIZE_PT;
+}
+function isDeckLengthString(value) {
+	return DECK_LENGTH_PATTERN.test(value.trim());
+}
+function isDeckPointLengthString(value) {
+	return DECK_POINT_LENGTH_PATTERN.test(value.trim());
+}
+function parseLengthToken(value, baseEmu, fallback = 0, context) {
+	const trimmed = value.trim();
+	if (trimmed === "0") return 0;
+	if (!isDeckLengthString(trimmed)) throw new Error(`Unsupported length value: ${value}`);
+	return parseLength(trimmed, baseEmu, fallback, context);
+}
+function parsePointToken(value, fallback = 0, context) {
+	const trimmed = value.trim();
+	if (trimmed === "0") return 0;
+	if (!isDeckPointLengthString(trimmed)) throw new Error(`Unsupported point value: ${value}`);
+	return parsePointValue(trimmed, fallback, context);
+}
+function parsePointValue(value, fallback = 0, context) {
+	if (value === void 0) return fallback;
+	if (typeof value === "number") return value;
+	if (value.endsWith("pt")) return Number.parseFloat(value.slice(0, -2));
+	if (value.endsWith("in")) return Number.parseFloat(value.slice(0, -2)) * 72;
+	if (value.endsWith("px")) return Number.parseFloat(value.slice(0, -2)) / 96 * 72;
+	if (value.endsWith("rem")) return Number.parseFloat(value.slice(0, -3)) * DEFAULT_FONT_SIZE_PT;
+	if (value.endsWith("em")) return Number.parseFloat(value.slice(0, -2)) * resolvePointUnitBase(context);
+	if (value.endsWith("ch")) return Number.parseFloat(value.slice(0, -2)) * resolvePointUnitBase(context) * CH_WIDTH_RATIO;
+	if (value.endsWith("vw")) {
+		const viewportWidthEmu = context?.viewportWidthEmu;
+		if (viewportWidthEmu === void 0) throw new Error(`Unsupported viewport point value without viewport context: ${value}`);
+		return viewportWidthEmu * Number.parseFloat(value.slice(0, -2)) / 100 / EMU_PER_INCH * 72;
+	}
+	if (value.endsWith("vh")) {
+		const viewportHeightEmu = context?.viewportHeightEmu;
+		if (viewportHeightEmu === void 0) throw new Error(`Unsupported viewport point value without viewport context: ${value}`);
+		return viewportHeightEmu * Number.parseFloat(value.slice(0, -2)) / 100 / EMU_PER_INCH * 72;
+	}
+	throw new Error(`Unsupported point value: ${value}`);
+}
+function parseStrokeWidth(value, fallback = 0, context) {
+	if (value === void 0) return fallback;
+	if (typeof value === "number") return value;
+	if (value.endsWith("pt")) return Number.parseFloat(value.slice(0, -2));
+	if (value.endsWith("in")) return Number.parseFloat(value.slice(0, -2)) * 72;
+	if (value.endsWith("px")) return Number.parseFloat(value.slice(0, -2)) / 96 * 72;
+	if (value.endsWith("rem")) return Number.parseFloat(value.slice(0, -3)) * DEFAULT_FONT_SIZE_PT;
+	if (value.endsWith("em")) return Number.parseFloat(value.slice(0, -2)) * resolvePointUnitBase(context);
+	if (value.endsWith("ch")) return Number.parseFloat(value.slice(0, -2)) * resolvePointUnitBase(context) * CH_WIDTH_RATIO;
+	if (value.endsWith("vw")) {
+		const viewportWidthEmu = context?.viewportWidthEmu;
+		if (viewportWidthEmu === void 0) throw new Error(`Unsupported viewport stroke width without viewport context: ${value}`);
+		return viewportWidthEmu * Number.parseFloat(value.slice(0, -2)) / 100 / EMU_PER_INCH * 72;
+	}
+	if (value.endsWith("vh")) {
+		const viewportHeightEmu = context?.viewportHeightEmu;
+		if (viewportHeightEmu === void 0) throw new Error(`Unsupported viewport stroke width without viewport context: ${value}`);
+		return viewportHeightEmu * Number.parseFloat(value.slice(0, -2)) / 100 / EMU_PER_INCH * 72;
+	}
+	throw new Error(`Unsupported stroke width: ${value}`);
+}
+function parseLength(value, baseEmu, fallback = 0, context) {
+	if (value === void 0) return fallback;
+	if (typeof value === "number") return value * EMU_PER_INCH;
+	if (value.endsWith("%")) return baseEmu * Number.parseFloat(value.slice(0, -1)) / 100;
+	if (value.endsWith("in")) return Number.parseFloat(value.slice(0, -2)) * EMU_PER_INCH;
+	if (value.endsWith("pt")) return Number.parseFloat(value.slice(0, -2)) / 72 * EMU_PER_INCH;
+	if (value.endsWith("px")) return Number.parseFloat(value.slice(0, -2)) / 96 * EMU_PER_INCH;
+	if (value.endsWith("rem")) return Number.parseFloat(value.slice(0, -3)) * DEFAULT_FONT_SIZE_PT * EMU_PER_INCH / 72;
+	if (value.endsWith("em")) return Number.parseFloat(value.slice(0, -2)) * resolvePointUnitBase(context) * EMU_PER_INCH / 72;
+	if (value.endsWith("ch")) return Number.parseFloat(value.slice(0, -2)) * resolvePointUnitBase(context) * CH_WIDTH_RATIO * EMU_PER_INCH / 72;
+	if (value.endsWith("vw")) {
+		const viewportWidthEmu = context?.viewportWidthEmu;
+		if (viewportWidthEmu === void 0) throw new Error(`Unsupported viewport length without viewport context: ${value}`);
+		return viewportWidthEmu * Number.parseFloat(value.slice(0, -2)) / 100;
+	}
+	if (value.endsWith("vh")) {
+		const viewportHeightEmu = context?.viewportHeightEmu;
+		if (viewportHeightEmu === void 0) throw new Error(`Unsupported viewport length without viewport context: ${value}`);
+		return viewportHeightEmu * Number.parseFloat(value.slice(0, -2)) / 100;
+	}
+	throw new Error(`Unsupported length value: ${value}`);
+}
+//#endregion
+//#region src/templates.ts
+const TEMPLATE_AREA_REF = Symbol("deckjsx.templateAreaRef");
+/**
+* Create the runtime template handle passed to a templated slide factory.
+*
+* @param templates - Deck-local Slide Template set.
+* @param name - Selected Slide Template name.
+* @returns A handle exposing `$name` and typed Template Area References for the selected template.
+*/
+function createTemplateHandle(templates, name) {
+	const template = templates[name];
+	const handle = { $name: name };
+	if (template && isRecord$2(template.areas)) Object.keys(template.areas).forEach((area) => {
+		handle[area] = createTemplateAreaRef(name, area);
+	});
+	return handle;
+}
+/**
+* Create an internal Template Area Reference object for a template handle property.
+*
+* @param template - Slide Template name that owns the area.
+* @param area - Template Area name within the template.
+* @returns A branded Template Area Reference accepted by the `area` JSX prop.
+*/
+function createTemplateAreaRef(template, area) {
+	return {
+		type: "deckjsx.templateAreaRef",
+		template,
+		area,
+		[TEMPLATE_AREA_REF]: true
+	};
+}
+/**
+* Return whether a value is a deckjsx-created Template Area Reference.
+*
+* @param value - Unknown runtime value to test.
+* @returns `true` when the value carries deckjsx's Template Area Reference runtime brand.
+*/
+function isTemplateAreaRef(value) {
+	return isRecord$2(value) && value.type === "deckjsx.templateAreaRef" && value[TEMPLATE_AREA_REF] === true && typeof value.template === "string" && typeof value.area === "string";
+}
+/**
+* Extract the serializable template and area names from a Template Area Reference.
+*
+* @param value - Template Area Reference produced by a template handle.
+* @returns The template and area names used by graph construction and diagnostics.
+*/
+function templateRefValue(value) {
+	return {
+		template: value.template,
+		area: value.area
+	};
+}
+/**
+* Validate a Deck-local Slide Template set and return author-facing diagnostics.
+*
+* @param templates - Deck-local Slide Template set to validate.
+* @param path - Diagnostic path prefix used in labels.
+* @returns Diagnostics for malformed templates, areas, frames, or reserved names.
+*/
+function validateSlideTemplates(templates, path = "templates") {
+	if (templates === void 0) return [];
+	if (!isRecord$2(templates)) return [templateDiagnostic("E_TEMPLATE_SET_INVALID", "invalid slide templates", path)];
+	const diagnostics = [];
+	Object.entries(templates).forEach(([templateName, template]) => {
+		const templatePath = `${path}.${templateName}`;
+		if (invalidName(templateName)) diagnostics.push(templateDiagnostic("E_TEMPLATE_RESERVED_NAME", "reserved slide template name", templatePath, `Slide Template name "${templateName}" is invalid.`, ["Template names must not be empty or start with deckjsx-reserved \"$\"."]));
+		if (!isRecord$2(template)) {
+			diagnostics.push(templateDiagnostic("E_TEMPLATE_INVALID", "invalid slide template", templatePath));
+			return;
+		}
+		if (!isRecord$2(template.areas)) {
+			diagnostics.push(templateDiagnostic("E_TEMPLATE_AREAS_INVALID", "invalid template areas", `${templatePath}.areas`));
+			return;
+		}
+		Object.entries(template.areas).forEach(([areaName, area]) => {
+			const areaPath = `${templatePath}.areas.${areaName}`;
+			if (invalidName(areaName)) diagnostics.push(templateDiagnostic("E_TEMPLATE_AREA_RESERVED_NAME", "reserved template area name", areaPath, `Template Area name "${areaName}" is invalid.`, ["Template Area names must not be empty or start with deckjsx-reserved \"$\"."]));
+			if (!isRecord$2(area)) {
+				diagnostics.push(templateDiagnostic("E_TEMPLATE_AREA_INVALID", "invalid area", areaPath));
+				return;
+			}
+			diagnostics.push(...validateFrame(area.frame, `${areaPath}.frame`));
+		});
+	});
+	return diagnostics;
+}
+function validateFrame(value, path) {
+	if (!isRecord$2(value)) return [templateDiagnostic("E_TEMPLATE_AREA_FRAME_INVALID", "invalid area frame", path)];
+	const diagnostics = [];
+	[
+		"x",
+		"y",
+		"width",
+		"height"
+	].forEach((key) => {
+		if (!validLength(value[key])) diagnostics.push(templateDiagnostic("E_TEMPLATE_AREA_FRAME_INCOMPLETE", "template area frame is incomplete", `${path}.${key}`, `Template Area frame must define a valid ${key} value.`));
+	});
+	return diagnostics;
+}
+function invalidName(value) {
+	return value.trim().length === 0 || value.startsWith("$");
+}
+function validLength(value) {
+	return typeof value === "number" && Number.isFinite(value) || typeof value === "string" && isDeckLengthString(value);
+}
+function isRecord$2(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function templateDiagnostic(code, title, path, message = "Slide Template definitions must be an object keyed by template and area names.", help) {
+	return diagnostic({
+		severity: "error",
+		code,
+		title,
+		message,
+		labels: [{
+			path,
+			message
+		}],
+		...help ? { help } : {}
+	});
+}
 //#endregion
 //#region src/composition/resolve.ts
 const MAX_COMPOSITION_DEPTH = 64;
@@ -60,13 +280,10 @@ function validateSourceKey(sourceKey) {
 }
 function describeInvalidRoot(value) {
 	if (isAuthorNodeValue(value)) return "Slide factory returned an AuthorNode value instead of an Author Tree node.";
-	if (isAuthorTreeNode(value)) return "Slide factory returned an author tree node that is not a <Slide /> root.";
+	if (isAuthorTreeNode(value)) return "Slide factory returned an Author Tree node that cannot be used as slide content.";
 	if (value === null) return "Slide factory returned null.";
 	return `Slide factory returned ${typeof value}.`;
 }
-function isSlideRoot(value) {
-	return value.kind === "element" && value.source.kind === "component" && value.source.component === "Slide";
-}
 function isPromiseLike(value) {
 	return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
 }
@@ -158,6 +375,7 @@ function resolveSource(source, context) {
 	let slideCount = 0;
 	const sourceKeys = /* @__PURE__ */ new Set();
 	const slotOrigins = collectSourceSlots(effectiveContext, context);
+	validateSlideTemplates(sourceState.templates, `${context.sourcePath} > templates`).forEach((item) => addDiagnostic$1(context, item));
 	const nextContextBase = {
 		diagnostics: context.diagnostics,
 		stack: [...context.stack, sourceState.cycleId],
@@ -168,6 +386,7 @@ function resolveSource(source, context) {
 			entries.push({
 				kind: "slide",
 				factory: entry.factory,
+				...entry.options ? { options: entry.options } : {},
 				path: `${context.sourcePath} > slideFactory[${index}]`
 			});
 			slideCount += 1;
@@ -219,6 +438,7 @@ function resolveSource(source, context) {
 		sourceIdentityMaterial: context.sourceIdentityMaterial,
 		stylesheets: sourceState.stylesheets,
 		...activeTheme ? { theme: activeTheme } : {},
+		...sourceState.templates ? { templates: sourceState.templates } : {},
 		context: effectiveContext,
 		entries,
 		slideCount,
@@ -245,13 +465,26 @@ function flattenPlan(plan, deckTotalSlides, deckSlideIndex, roots, diagnostics)
 			context: plan.context.value,
 			composition
 		} : { composition };
-		const root = entry.factory(input);
-		if (!isAuthorTreeNode(root) || !isSlideRoot(root)) diagnostics.push(compositionDiagnostic({
+		const slideTemplate = entry.options?.template;
+		const factoryInput = typeof slideTemplate === "string" && plan.templates ? {
+			...input,
+			template: createTemplateHandle(plan.templates, slideTemplate)
+		} : input;
+		const content = entry.factory(factoryInput);
+		const root = content === null || content === void 0 || typeof content === "boolean" || isAuthorTreeNode(content) || Array.isArray(content) || typeof content !== "object" ? createAuthorElement({
+			source: {
+				kind: "component",
+				component: "Slide"
+			},
+			props: entry.options ?? {},
+			children: [content]
+		}) : content;
+		if (!isAuthorTreeNode(root) || root.kind !== "element") diagnostics.push(compositionDiagnostic({
 			code: "E_COMPOSITION_INVALID_ROOT",
-			title: "slide factory must return a <Slide /> root",
+			title: "slide factory must return slide content",
 			path: entry.path,
 			message: describeInvalidRoot(root),
-			help: ["Return <Slide>...</Slide> from the slide factory passed to deck.add()."]
+			help: ["Return JSX content from the factory passed to deck.slide()."]
 		}));
 		else roots.push({
 			root,
@@ -259,6 +492,7 @@ function flattenPlan(plan, deckTotalSlides, deckSlideIndex, roots, diagnostics)
 			sourceIdentityMaterial: plan.sourceIdentityMaterial,
 			stylesheets: plan.stylesheets,
 			...plan.theme ? { theme: plan.theme } : {},
+			...plan.templates ? { templates: plan.templates } : {},
 			path: entry.path,
 			composition,
 			slotOrigins: plan.slotOrigins
@@ -299,7 +533,7 @@ function appendIndexValue(index, key, value) {
 	values.push(value);
 	index.set(key, values);
 }
-function sourceKeyFor$2(source) {
+function sourceKeyFor$3(source) {
 	return !source || source.kind === "root" ? ROOT_SOURCE_ARTIFACT_KEY$1 : source.sourceIdentity;
 }
 function projectionShapeDiagnostics(projection) {
@@ -377,7 +611,7 @@ function safeProjectionParts(projection) {
 function partsBySourceKey(parts) {
 	const index = /* @__PURE__ */ new Map();
 	parts.forEach((part) => {
-		appendIndexValue(index, sourceKeyFor$2(part.origin?.source), part.id);
+		appendIndexValue(index, sourceKeyFor$3(part.origin?.source), part.id);
 	});
 	return index;
 }
@@ -1307,13 +1541,13 @@ function themeDiagnostics(theme) {
 }
 //#endregion
 //#region src/style/resolve.ts
-function sourceKeyFor$1(source) {
+function sourceKeyFor$2(source) {
 	return !source || source.kind === "root" ? "root" : source.sourceIdentity;
 }
 function classesBySource(roots) {
 	const stylesheets = /* @__PURE__ */ new Map();
 	roots.forEach((root) => {
-		const key = sourceKeyFor$1(root.source);
+		const key = sourceKeyFor$2(root.source);
 		if (!stylesheets.has(key)) stylesheets.set(key, root.stylesheets);
 	});
 	return stylesheets;
@@ -1322,7 +1556,7 @@ function themesBySource(roots) {
 	const themes = /* @__PURE__ */ new Map();
 	roots.forEach((root) => {
 		if (!root.theme) return;
-		themes.set(sourceKeyFor$1(root.source), root.theme);
+		themes.set(sourceKeyFor$2(root.source), root.theme);
 	});
 	return themes;
 }
@@ -1411,7 +1645,7 @@ function resolveStyles(graph, roots) {
 	});
 	graph.nodes.forEach((node) => {
 		if (!isStyleCapableNode(node)) return;
-		const sourceKey = sourceKeyFor$1(node.origin.source);
+		const sourceKey = sourceKeyFor$2(node.origin.source);
 		const entity = node.styleRef ? graph.styles.get(node.styleRef) : void 0;
 		let registry = registries.get(sourceKey);
 		if (!registry) {
@@ -1431,7 +1665,7 @@ const ROOT_SOURCE_ARTIFACT_KEY = "deck:root";
 function combineDiagnostics$1(...diagnostics) {
 	return createDiagnostics(diagnostics.flatMap((item) => item.items));
 }
-function sourceKeyFor(source) {
+function sourceKeyFor$1(source) {
 	return !source || source.kind === "root" ? ROOT_SOURCE_ARTIFACT_KEY : source.sourceIdentity;
 }
 var PipelineArtifactCollection = class {
@@ -1476,7 +1710,7 @@ var PipelineArtifactCollection = class {
 		}
 		const rootsBySourceKey = /* @__PURE__ */ new Map();
 		roots.forEach((root) => {
-			const sourceKey = sourceKeyFor(root.source);
+			const sourceKey = sourceKeyFor$1(root.source);
 			const current = rootsBySourceKey.get(sourceKey);
 			if (current) {
 				current.rootCount += 1;
@@ -1537,13 +1771,13 @@ var PipelineArtifactCollection = class {
 		const sourceByKey = /* @__PURE__ */ new Map();
 		sourceByKey.set(ROOT_SOURCE_ARTIFACT_KEY, { kind: "root" });
 		input.roots.forEach((root) => {
-			sourceByKey.set(sourceKeyFor(root.source), root.source);
+			sourceByKey.set(sourceKeyFor$1(root.source), root.source);
 		});
 		const nodesBySourceKey = /* @__PURE__ */ new Map();
 		const stylesBySourceKey = /* @__PURE__ */ new Map();
 		const assetsBySourceKey = /* @__PURE__ */ new Map();
 		input.graph.nodes.forEach((node) => {
-			const sourceKey = sourceKeyFor(node.origin.source);
+			const sourceKey = sourceKeyFor$1(node.origin.source);
 			sourceByKey.set(sourceKey, node.origin.source ?? { kind: "root" });
 			const nodeIds = nodesBySourceKey.get(sourceKey) ?? [];
 			nodeIds.push(node.id);
@@ -1772,9 +2006,12 @@ function classRefsFor(value) {
 	}));
 }
 function directStyleProps(props) {
-	const { children: _children, className: _className, data: _data, name: _name, shape: _shape, src: _src, style: _style, ...directStyle } = props;
+	const { children: _children, className: _className, data: _data, area: _area, name: _name, shape: _shape, src: _src, style: _style, template: _template, ...directStyle } = props;
 	return Object.keys(directStyle).length === 0 ? void 0 : directStyle;
 }
+function sourceKeyFor(source) {
+	return !source || source.kind === "root" ? "root" : source.sourceIdentity;
+}
 function mergedAuthoredStyle(props) {
 	const directStyle = directStyleProps(props);
 	const inlineStyle = props.style;
@@ -1840,6 +2077,7 @@ function assetForImage(state, idMaterial, props, path) {
 }
 function semanticBase(state, node, id, kind, path, material, context) {
 	const styleRef = styleRefFor(state, material, kind, node.props);
+	const templateAreaRef = templateAreaRefFor(state, node.props.area, path, context);
 	return {
 		id,
 		kind,
@@ -1848,9 +2086,88 @@ function semanticBase(state, node, id, kind, path, material, context) {
 		...node.source.kind === "component" ? { authoredComponent: node.source.component } : {},
 		...node.key !== void 0 ? { key: node.key } : {},
 		...nodeRole(node) ? { role: nodeRole(node) } : {},
-		...styleRef ? { styleRef } : {}
+		...styleRef ? { styleRef } : {},
+		...templateAreaRef ? { templateAreaRef } : {}
 	};
 }
+function templateAreaDiagnostic(input) {
+	return diagnostic({
+		severity: "error",
+		code: input.code,
+		title: input.title,
+		message: input.message,
+		labels: [{
+			path: input.path,
+			message: input.message
+		}],
+		...input.help ? { help: input.help } : {}
+	});
+}
+function templateAreaRefFor(state, value, path, context) {
+	if (value === void 0) return;
+	if (!isTemplateAreaRef(value)) {
+		addDiagnostic(state, templateAreaDiagnostic({
+			code: "E_TEMPLATE_AREA_REF_INVALID",
+			title: "template area reference is invalid",
+			path,
+			message: "The area prop must receive a Template Area Reference from the slide factory.",
+			help: ["Use area={template.areaName} inside deck.slide({ template }, ...)."]
+		}));
+		return;
+	}
+	const ref = templateRefValue(value);
+	if (!context.activeSlideTemplate) {
+		addDiagnostic(state, templateAreaDiagnostic({
+			code: "E_TEMPLATE_AREA_WITHOUT_TEMPLATE",
+			title: "template area used without active template",
+			path,
+			message: `Template area "${ref.area}" was used on a slide without an active Slide Template.`
+		}));
+		return;
+	}
+	if (ref.template !== context.activeSlideTemplate) {
+		addDiagnostic(state, templateAreaDiagnostic({
+			code: "E_TEMPLATE_AREA_REF_MISMATCH",
+			title: "template area belongs to another template",
+			path,
+			message: `Template area "${ref.area}" belongs to Slide Template "${ref.template}", but the active Slide Template is "${context.activeSlideTemplate}".`,
+			help: ["Use the template handle passed to this slide factory."]
+		}));
+		return;
+	}
+	if (!context.directSlideChild) {
+		addDiagnostic(state, templateAreaDiagnostic({
+			code: "E_TEMPLATE_AREA_NESTED",
+			title: "template area is nested",
+			path,
+			message: `Template area "${ref.area}" must be attached to a direct slide child.`,
+			help: ["Place the area prop on a slide direct child, or wrap nested content in a container."]
+		}));
+		return;
+	}
+	if (!(context.activeSlideTemplates?.[ref.template])?.areas?.[ref.area]) {
+		addDiagnostic(state, templateAreaDiagnostic({
+			code: "E_TEMPLATE_AREA_NOT_FOUND",
+			title: "template area was not found",
+			path,
+			message: `Template area "${ref.area}" does not exist in Slide Template "${ref.template}".`
+		}));
+		return;
+	}
+	const existing = context.usedTemplateAreas?.get(ref.area);
+	if (existing) {
+		addDiagnostic(state, templateAreaDiagnostic({
+			code: "E_TEMPLATE_AREA_DUPLICATE",
+			title: "template area is used more than once",
+			path,
+			message: `Template area "${ref.area}" is already used by ${existing}.`,
+			help: ["Wrap multiple elements in a single container that carries the area prop."]
+		}));
+		return;
+	}
+	context.usedTemplateAreas?.set(ref.area, path);
+	return ref;
+}
 function buildTextRunFromLeaf(state, leaf, context, index) {
 	const text = typeof leaf.value === "string" ? leaf.value : String(leaf.value);
 	if (text.trim().length === 0) return;
@@ -1921,7 +2238,8 @@ function buildTextLikeNode(state, node, id, path, material, context) {
 				parentId: id,
 				parentMaterial: material,
 				path,
-				inline: true
+				inline: true,
+				directSlideChild: false
 			}, index);
 			if (run) inlineChildren.push(run.id);
 			return;
@@ -1932,7 +2250,8 @@ function buildTextLikeNode(state, node, id, path, material, context) {
 				parentId: id,
 				parentMaterial: material,
 				path,
-				inline: true
+				inline: true,
+				directSlideChild: false
 			});
 			const segment = `fragment:${keySegment(child.key, index)}`;
 			inlineChildren.push(...buildChildren(state, child.children, {
@@ -1948,7 +2267,8 @@ function buildTextLikeNode(state, node, id, path, material, context) {
 				parentId: id,
 				parentMaterial: material,
 				path,
-				inline: true
+				inline: true,
+				directSlideChild: false
 			}, index);
 			if (built) inlineChildren.push(built.id);
 			return;
@@ -2034,6 +2354,14 @@ function buildNode(state, node, context, index) {
 			kind: "shape"
 		};
 	}
+	const slideTemplateName = kind === "slide" && typeof node.props.template === "string" ? node.props.template : void 0;
+	const slideTemplates = kind === "slide" ? state.templates.get(sourceKeyFor(sourceFor(nodeContext))) : void 0;
+	if (kind === "slide" && slideTemplateName && !slideTemplates?.[slideTemplateName]) addDiagnostic(state, templateAreaDiagnostic({
+		code: "E_TEMPLATE_NOT_FOUND",
+		title: "slide template was not found",
+		path,
+		message: `Slide Template "${slideTemplateName}" is not defined for this Deck source.`
+	}));
 	const childIds = buildChildren(state, node.children, {
 		parentId: id,
 		parentMaterial: material,
@@ -2041,12 +2369,17 @@ function buildNode(state, node, context, index) {
 		inline: false,
 		source: sourceFor(nodeContext),
 		slotOrigins: nodeContext.slotOrigins,
-		activeSlot: nodeContext.activeSlot
+		activeSlot: nodeContext.activeSlot,
+		activeSlideTemplate: slideTemplateName ?? nodeContext.activeSlideTemplate,
+		activeSlideTemplates: kind === "slide" ? slideTemplates : nodeContext.activeSlideTemplates,
+		directSlideChild: kind === "slide",
+		usedTemplateAreas: kind === "slide" ? /* @__PURE__ */ new Map() : nodeContext.usedTemplateAreas
 	});
 	state.nodes.set(id, {
 		...semanticBase(state, node, id, kind, path, material, nodeContext),
 		kind,
 		...kind === "slide" && typeof node.props.name === "string" ? { name: node.props.name } : {},
+		...kind === "slide" && slideTemplateName ? { templateRef: { name: slideTemplateName } } : {},
 		children: childIds
 	});
 	return {
@@ -2080,11 +2413,13 @@ function buildSemanticAuthorGraph(roots) {
 		nodes: /* @__PURE__ */ new Map(),
 		styles: /* @__PURE__ */ new Map(),
 		assets: /* @__PURE__ */ new Map(),
+		templates: /* @__PURE__ */ new Map(),
 		diagnostics: []
 	};
 	const slideIds = [];
 	roots.forEach((root, index) => {
 		const composed = "root" in root ? root : asComposedRoot(root, index);
+		if (composed.templates) state.templates.set(sourceKeyFor(composed.source), composed.templates);
 		const built = buildNode(state, composed.root, {
 			parentId: documentId,
 			parentMaterial: [
@@ -2095,7 +2430,10 @@ function buildSemanticAuthorGraph(roots) {
 			path: composed.path,
 			inline: false,
 			source: composed.source,
-			slotOrigins: composed.slotOrigins
+			slotOrigins: composed.slotOrigins,
+			activeSlideTemplate: void 0,
+			activeSlideTemplates: void 0,
+			directSlideChild: false
 		}, composed.composition.slideIndex);
 		if (built) slideIds.push(built.id);
 	});
@@ -2117,108 +2455,12 @@ function buildSemanticAuthorGraph(roots) {
 			documentId,
 			nodes: state.nodes,
 			styles: state.styles,
-			assets: state.assets
+			assets: state.assets,
+			templates: state.templates
 		},
 		diagnostics
 	};
 }
-const DEFAULT_FONT_SIZE_PT = 16 / 96 * 72;
-const CH_WIDTH_RATIO = .5;
-const DECK_LENGTH_PATTERN = /^[-+]?(?:\d+|\d*\.\d+)(?:in|pt|px|%|em|rem|vh|vw|ch)$/i;
-const DECK_POINT_LENGTH_PATTERN = /^[-+]?(?:\d+|\d*\.\d+)(?:pt|in|px|em|rem|vh|vw|ch)$/i;
-function pointsToEmu(value) {
-	return value / 72 * EMU_PER_INCH;
-}
-function parsePercentage$1(value) {
-	const trimmed = value.trim();
-	if (!trimmed.endsWith("%")) return;
-	return Number.parseFloat(trimmed.slice(0, -1));
-}
-function resolvePointUnitBase(context) {
-	return context?.fontSizePt ?? DEFAULT_FONT_SIZE_PT;
-}
-function isDeckLengthString(value) {
-	return DECK_LENGTH_PATTERN.test(value.trim());
-}
-function isDeckPointLengthString(value) {
-	return DECK_POINT_LENGTH_PATTERN.test(value.trim());
-}
-function parseLengthToken(value, baseEmu, fallback = 0, context) {
-	const trimmed = value.trim();
-	if (trimmed === "0") return 0;
-	if (!isDeckLengthString(trimmed)) throw new Error(`Unsupported length value: ${value}`);
-	return parseLength(trimmed, baseEmu, fallback, context);
-}
-function parsePointToken(value, fallback = 0, context) {
-	const trimmed = value.trim();
-	if (trimmed === "0") return 0;
-	if (!isDeckPointLengthString(trimmed)) throw new Error(`Unsupported point value: ${value}`);
-	return parsePointValue(trimmed, fallback, context);
-}
-function parsePointValue(value, fallback = 0, context) {
-	if (value === void 0) return fallback;
-	if (typeof value === "number") return value;
-	if (value.endsWith("pt")) return Number.parseFloat(value.slice(0, -2));
-	if (value.endsWith("in")) return Number.parseFloat(value.slice(0, -2)) * 72;
-	if (value.endsWith("px")) return Number.parseFloat(value.slice(0, -2)) / 96 * 72;
-	if (value.endsWith("rem")) return Number.parseFloat(value.slice(0, -3)) * DEFAULT_FONT_SIZE_PT;
-	if (value.endsWith("em")) return Number.parseFloat(value.slice(0, -2)) * resolvePointUnitBase(context);
-	if (value.endsWith("ch")) return Number.parseFloat(value.slice(0, -2)) * resolvePointUnitBase(context) * CH_WIDTH_RATIO;
-	if (value.endsWith("vw")) {
-		const viewportWidthEmu = context?.viewportWidthEmu;
-		if (viewportWidthEmu === void 0) throw new Error(`Unsupported viewport point value without viewport context: ${value}`);
-		return viewportWidthEmu * Number.parseFloat(value.slice(0, -2)) / 100 / EMU_PER_INCH * 72;
-	}
-	if (value.endsWith("vh")) {
-		const viewportHeightEmu = context?.viewportHeightEmu;
-		if (viewportHeightEmu === void 0) throw new Error(`Unsupported viewport point value without viewport context: ${value}`);
-		return viewportHeightEmu * Number.parseFloat(value.slice(0, -2)) / 100 / EMU_PER_INCH * 72;
-	}
-	throw new Error(`Unsupported point value: ${value}`);
-}
-function parseStrokeWidth(value, fallback = 0, context) {
-	if (value === void 0) return fallback;
-	if (typeof value === "number") return value;
-	if (value.endsWith("pt")) return Number.parseFloat(value.slice(0, -2));
-	if (value.endsWith("in")) return Number.parseFloat(value.slice(0, -2)) * 72;
-	if (value.endsWith("px")) return Number.parseFloat(value.slice(0, -2)) / 96 * 72;
-	if (value.endsWith("rem")) return Number.parseFloat(value.slice(0, -3)) * DEFAULT_FONT_SIZE_PT;
-	if (value.endsWith("em")) return Number.parseFloat(value.slice(0, -2)) * resolvePointUnitBase(context);
-	if (value.endsWith("ch")) return Number.parseFloat(value.slice(0, -2)) * resolvePointUnitBase(context) * CH_WIDTH_RATIO;
-	if (value.endsWith("vw")) {
-		const viewportWidthEmu = context?.viewportWidthEmu;
-		if (viewportWidthEmu === void 0) throw new Error(`Unsupported viewport stroke width without viewport context: ${value}`);
-		return viewportWidthEmu * Number.parseFloat(value.slice(0, -2)) / 100 / EMU_PER_INCH * 72;
-	}
-	if (value.endsWith("vh")) {
-		const viewportHeightEmu = context?.viewportHeightEmu;
-		if (viewportHeightEmu === void 0) throw new Error(`Unsupported viewport stroke width without viewport context: ${value}`);
-		return viewportHeightEmu * Number.parseFloat(value.slice(0, -2)) / 100 / EMU_PER_INCH * 72;
-	}
-	throw new Error(`Unsupported stroke width: ${value}`);
-}
-function parseLength(value, baseEmu, fallback = 0, context) {
-	if (value === void 0) return fallback;
-	if (typeof value === "number") return value * EMU_PER_INCH;
-	if (value.endsWith("%")) return baseEmu * Number.parseFloat(value.slice(0, -1)) / 100;
-	if (value.endsWith("in")) return Number.parseFloat(value.slice(0, -2)) * EMU_PER_INCH;
-	if (value.endsWith("pt")) return Number.parseFloat(value.slice(0, -2)) / 72 * EMU_PER_INCH;
-	if (value.endsWith("px")) return Number.parseFloat(value.slice(0, -2)) / 96 * EMU_PER_INCH;
-	if (value.endsWith("rem")) return Number.parseFloat(value.slice(0, -3)) * DEFAULT_FONT_SIZE_PT * EMU_PER_INCH / 72;
-	if (value.endsWith("em")) return Number.parseFloat(value.slice(0, -2)) * resolvePointUnitBase(context) * EMU_PER_INCH / 72;
-	if (value.endsWith("ch")) return Number.parseFloat(value.slice(0, -2)) * resolvePointUnitBase(context) * CH_WIDTH_RATIO * EMU_PER_INCH / 72;
-	if (value.endsWith("vw")) {
-		const viewportWidthEmu = context?.viewportWidthEmu;
-		if (viewportWidthEmu === void 0) throw new Error(`Unsupported viewport length without viewport context: ${value}`);
-		return viewportWidthEmu * Number.parseFloat(value.slice(0, -2)) / 100;
-	}
-	if (value.endsWith("vh")) {
-		const viewportHeightEmu = context?.viewportHeightEmu;
-		if (viewportHeightEmu === void 0) throw new Error(`Unsupported viewport length without viewport context: ${value}`);
-		return viewportHeightEmu * Number.parseFloat(value.slice(0, -2)) / 100;
-	}
-	throw new Error(`Unsupported length value: ${value}`);
-}
 //#endregion
 //#region src/layout/frame.ts
 function intersectClipRect(frame, clipRect) {
@@ -6182,7 +6424,7 @@ function compileNode(child, parentFrame, idGenerator, placement, clipRect, conte
 	}
 }
 function compileSlide(root, context, slideFrame, idGenerator, lengthContext, resolutionOptions) {
-	if (!isSlideNode(root)) throw new Error(`Slide factory at index ${context.slideIndex} must return a <Slide /> root.`);
+	if (!isSlideNode(root)) throw new Error(`Slide factory at index ${context.slideIndex} must resolve to a slide node.`);
 	const slideProps = normalizeSlideProps(root.props);
 	const backgroundBoxFrames = resolveBackgroundBoxFrames(slideFrame);
 	const backgroundFill = resolveBackgroundLayers(slideProps.backgroundColor ?? slideProps.backgroundImage ?? slideProps.background, slideProps.backgroundTransparency, {
@@ -6246,6 +6488,28 @@ function resolvedPropsFor(node, resolvedStyles) {
 	if (!resolved) return {};
 	return Object.fromEntries(Object.entries(resolved.properties).filter(([, property]) => property.source.layer !== "default").map(([key, property]) => [key, property.value]));
 }
+function sourceKeyForOrigin(source) {
+	return !source || source.kind === "root" ? "root" : source.sourceIdentity;
+}
+function propsWithTemplateAreaFrame(resolvedStyles, node, templates) {
+	const props = resolvedPropsFor(node, resolvedStyles);
+	const ref = node.templateAreaRef;
+	if (!ref) return props;
+	const frame = templates?.[ref.template]?.areas?.[ref.area]?.frame;
+	if (!frame) return props;
+	const resolved = resolvedStyles.get(node.id);
+	const merged = { ...props };
+	[
+		"x",
+		"y",
+		"width",
+		"height"
+	].forEach((key) => {
+		if (resolved?.properties[key]?.source.layer === "style") return;
+		merged[key] = frame[key];
+	});
+	return merged;
+}
 function pushDefined(values, value) {
 	if (value !== void 0) values.push(value);
 }
@@ -6294,22 +6558,25 @@ function textChildrenFromGraph(graph, resolvedStyles, childIds, origins) {
 		return [];
 	});
 }
-function contentChildrenFromGraph(graph, resolvedStyles, childIds, origins) {
+function contentChildrenFromGraph(graph, resolvedStyles, childIds, origins, templates) {
 	return childIds.flatMap((childId) => {
 		const child = graph.nodes.get(childId);
 		if (!child) return [];
-		const node = layoutAuthorNodeFromGraph(graph, resolvedStyles, child, origins);
+		const node = layoutAuthorNodeFromGraph(graph, resolvedStyles, child, origins, templates);
 		return node ? [node] : [];
 	});
 }
-function layoutAuthorNodeFromGraph(graph, resolvedStyles, node, origins) {
-	const props = resolvedPropsFor(node, resolvedStyles);
+function layoutAuthorNodeFromGraph(graph, resolvedStyles, node, origins, templates) {
+	const props = propsWithTemplateAreaFrame(resolvedStyles, node, templates);
 	switch (node.kind) {
-		case "slide": return rememberOrigin(layoutNode("slide", {
-			...props,
-			name: node.name
-		}, contentChildrenFromGraph(graph, resolvedStyles, node.children, origins)), layoutOriginFor(graph, node), origins);
-		case "container": return rememberOrigin(layoutNode("view", props, contentChildrenFromGraph(graph, resolvedStyles, node.children, origins)), layoutOriginFor(graph, node), origins);
+		case "slide": {
+			const slideTemplates = graph.templates.get(sourceKeyForOrigin(node.origin.source));
+			return rememberOrigin(layoutNode("slide", {
+				...props,
+				name: node.name
+			}, contentChildrenFromGraph(graph, resolvedStyles, node.children, origins, slideTemplates)), layoutOriginFor(graph, node), origins);
+		}
+		case "container": return rememberOrigin(layoutNode("view", props, contentChildrenFromGraph(graph, resolvedStyles, node.children, origins, templates)), layoutOriginFor(graph, node), origins);
 		case "text": return rememberOrigin(layoutNode("text", props, textChildrenFromGraph(graph, resolvedStyles, node.inlineChildren, origins)), layoutOriginFor(graph, node), origins);
 		case "image": {
 			const asset = node.assetRef ? graph.assets.get(node.assetRef) : void 0;
@@ -7793,9 +8060,23 @@ function projectedArtifactStatus(value, diagnostics) {
 	if (value === void 0) return "missing";
 	return diagnostics.hasErrors ? "partial" : "available";
 }
+/**
+* A Deck with Source Context already bound.
+*
+* Bound sources can be mounted, compiled, projected, or rendered, but they are not an authoring
+* registration surface. Use `Deck#withSource(...)` when a child Deck requires Source Context and
+* should be executed as a standalone source.
+*
+* @typeParam TSourceContext - The Source Context type already bound to this source.
+* @typeParam TTemplates - The Deck-local Slide Template set owned by the source Deck.
+*/
 var BoundSource = class {
 	#source;
 	#sourceContext;
+	/**
+	* @param source - The Deck whose Source Context should be bound.
+	* @param sourceContext - The Source Context value used whenever this source is composed.
+	*/
 	constructor(source, sourceContext) {
 		this.#source = source;
 		this.#sourceContext = sourceContext;
@@ -7806,6 +8087,7 @@ var BoundSource = class {
 			entries: source.entries,
 			stylesheets: source.stylesheets,
 			...source.theme ? { theme: source.theme } : {},
+			...source.templates ? { templates: source.templates } : {},
 			cycleId: source.cycleId,
 			boundContext: {
 				present: true,
@@ -7813,15 +8095,31 @@ var BoundSource = class {
 			}
 		};
 	}
+	/**
+	* Compile this bound source into a Semantic Author Graph and resolved style inspection data.
+	*
+	* @returns A compile result with diagnostics, stage summaries, and graph artifacts when available.
+	*/
 	compile() {
 		return compileSource(this);
 	}
+	/**
+	* Project this bound source into the configured output document model.
+	*
+	* @returns A project result with diagnostics, stage summaries, and the projected model when valid.
+	*/
 	project() {
 		return projectSource({
 			source: this,
 			options: this.#source.options
 		});
 	}
+	/**
+	* Render this bound source with the default writer adapter or an explicit Writer Adapter.
+	*
+	* @param config - Render options for the default adapter, or an explicit Writer Adapter.
+	* @returns A Promise resolving to render diagnostics, stage summaries, and an artifact when render succeeds.
+	*/
 	render(config) {
 		return renderSource({
 			source: this,
@@ -7830,12 +8128,26 @@ var BoundSource = class {
 		});
 	}
 };
+/**
+* The main authoring object for a deckjsx document.
+*
+* A Deck owns slide declarations, source-local stylesheets, optional Theme configuration, and
+* Deck-local Slide Templates. It compiles JSX authoring into the Semantic Author Graph, projects
+* that graph into an output document model, and renders the projected model through a writer.
+*
+* @typeParam TSourceContext - Source Context required by this Deck's slide factories.
+* @typeParam TTemplates - Deck-local Slide Template set inferred from `new Deck({ templates })`.
+*/
 var Deck = class {
 	#options;
 	#entries = [];
 	#stylesheets = [];
 	#artifacts = new PipelineArtifactCollection();
+	/** Bind Source Context to this Deck so it can be compiled, projected, rendered, or mounted. */
 	withSource;
+	/**
+	* @param options - Deck configuration, including layout, metadata, Theme, output format, and Deck Templates.
+	*/
 	constructor(options) {
 		this.#options = options;
 		this.withSource = ((sourceContext) => new BoundSource(this, sourceContext));
@@ -7848,19 +8160,30 @@ var Deck = class {
 			entries: this.#entries,
 			stylesheets: this.#stylesheets,
 			...this.#options.theme ? { theme: this.#options.theme } : {},
+			...this.#options.templates ? { templates: this.#options.templates } : {},
 			cycleId: this,
 			boundContext: { present: false }
 		};
 	}
+	/**
+	* Register a source-local StyleSheet for CSS-like `className` resolution.
+	*
+	* @param stylesheet - The StyleSheet to apply to slides declared by this Deck source.
+	* @returns This Deck, for fluent authoring.
+	*/
 	useStyles(stylesheet) {
 		this.#stylesheets.push(stylesheet);
 		this.#artifacts.invalidateFromSource();
 		return this;
 	}
-	add(slide) {
+	slide(optionsOrFactory, maybeFactory) {
+		const options = typeof optionsOrFactory === "function" ? void 0 : optionsOrFactory;
+		const factory = typeof optionsOrFactory === "function" ? optionsOrFactory : maybeFactory;
+		if (!factory) throw new Error("deck.slide() requires a slide factory.");
 		this.#entries.push({
 			kind: "slide",
-			factory: slide
+			...options ? { options } : {},
+			factory
 		});
 		this.#artifacts.invalidateFromSource();
 		return this;
@@ -7876,10 +8199,22 @@ var Deck = class {
 		this.#artifacts.invalidateFromSource();
 		return this;
 	}
+	/**
+	* Replace the current compiled graph artifact before calling `project()` or `render()`.
+	*
+	* @param graph - The Semantic Author Graph to use as this Deck's compiled state.
+	* @returns This Deck, for fluent pipeline editing.
+	*/
 	defineGraph(graph) {
 		this.#artifacts.replaceGraphArtifact(this, graph);
 		return this;
 	}
+	/**
+	* Replace the current projected document model artifact before calling `render()`.
+	*
+	* @param projection - The projected PPTX Package Model to use as this Deck's projection state.
+	* @returns This Deck, for fluent pipeline editing.
+	*/
 	defineProjection(projection) {
 		this.#artifacts.replaceProjectionArtifact(projection);
 		return this;
@@ -7897,6 +8232,11 @@ var Deck = class {
 		}
 		return compileSource(this, this.#artifacts);
 	}
+	/**
+	* Project this root Deck into the configured output document model.
+	*
+	* @returns A project result with diagnostics, stage summaries, and the projected model when valid.
+	*/
 	project() {
 		return projectSource({
 			source: this,
@@ -7906,6 +8246,12 @@ var Deck = class {
 			artifacts: this.#artifacts
 		});
 	}
+	/**
+	* Render this root Deck with the default writer adapter or an explicit Writer Adapter.
+	*
+	* @param config - Render options for the default adapter, or an explicit Writer Adapter.
+	* @returns A Promise resolving to render diagnostics, stage summaries, and an artifact when render succeeds.
+	*/
 	render(config) {
 		return renderSource({
 			source: this,
@@ -7918,4 +8264,4 @@ var Deck = class {
 	}
 };
 //#endregion
-export { CompositionDiagnosticError, Deck, DeckDiagnosticError, EMU_PER_INCH, Fragment, Image, POINTS_PER_INCH, SemanticGraphDiagnosticError, Shape, Slide, StyleDiagnosticError, StyleSheet, Text, Theme, View, createElement, formatDiagnostic, formatDiagnostics };
+export { CompositionDiagnosticError, Deck, DeckDiagnosticError, EMU_PER_INCH, Fragment, Image, POINTS_PER_INCH, SemanticGraphDiagnosticError, Shape, StyleDiagnosticError, StyleSheet, Text, Theme, View, createElement, formatDiagnostic, formatDiagnostics };