@samva/markup 0.1.1 → 0.2.0

package/dist/email/html.d.ts

@@ -0,0 +1,42 @@
+import { r as EmailDiagnostic } from "../diagnostics-Djd9ckLg.js";
+import { m as EmailNode } from "../elements-DtwKlFVH.js";
+import { EmittedPosition } from "./selection.js";
+//#region src/email/html.d.ts
+/** Escape a value for element content. */
+declare const escapeText: (value: string) => string;
+/** Escape a value for a double-quoted attribute. */
+declare const escapeAttribute: (value: string) => string;
+/** camelCase to kebab-case; already-kebab names pass through unchanged. */
+declare const kebab: (property: string) => string;
+/** A bare number is pixels for every property that takes a length. */
+declare const declarationValue: (property: string, value: string | number) => string;
+interface EmailHtmlOutput {
+  readonly html: string;
+  readonly diagnostics: readonly EmailDiagnostic[];
+  /**
+   * Each emitted element's offset range and origins. A compatibility finding
+   * carries a position in the emitted document, and this is what turns that
+   * back into the authoring element the author can edit.
+   */
+  readonly positions: readonly EmittedPosition[];
+}
+/** How this document will be consumed. Delivery is the default; export is opt-in. */
+interface SerializeEmailOptions {
+  /**
+   * Accept relative references. A local export serves assets from a relative
+   * base beside the file; a delivered message has no directory to resolve one
+   * against, so this stays off for anything that will be sent.
+   */
+  readonly relativeUrls?: boolean | undefined;
+  /**
+   * Stamp every element with its instance path, so an editor preview can
+   * resolve a click in the rendered document to exactly one rendered element.
+   * A delivered message never carries it.
+   */
+  readonly instancePaths?: boolean | undefined;
+}
+/** Lower the derived tree to email HTML, reporting every unsupported construct with its origin. */
+declare const serializeEmailHtml: (node: EmailNode, options?: SerializeEmailOptions) => EmailHtmlOutput;
+//#endregion
+export { EmailHtmlOutput, SerializeEmailOptions, declarationValue, escapeAttribute, escapeText, kebab, serializeEmailHtml };
+//# sourceMappingURL=html.d.ts.map

package/dist/email/html.js

@@ -0,0 +1,266 @@
+import { EMAIL_ELEMENTS, EMAIL_GLOBAL_ATTRIBUTES, emailElement } from "./elements.js";
+import { INSTANCE_PATH_ATTRIBUTE } from "./selection.js";
+import { Predicate } from "effect";
+//#region src/email/html.ts
+/** Escape a value for element content. */
+const escapeText = (value) => value.replace(/[&<>]/g, (character) => ({
+	"&": "&amp;",
+	"<": "&lt;",
+	">": "&gt;"
+})[character] ?? character);
+/** Escape a value for a double-quoted attribute. */
+const escapeAttribute = (value) => value.replace(/[&<>"']/g, (character) => ({
+	"&": "&amp;",
+	"<": "&lt;",
+	">": "&gt;",
+	"\"": "&quot;",
+	"'": "&#39;"
+})[character] ?? character);
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/;
+const SAFE_URL_SCHEME = /^(https:\/\/|mailto:|tel:|cid:|#)/i;
+const RELATIVE_URL = /^(\.{1,2}\/|\/(?!\/))/;
+/**
+* Only references an email client will follow safely; no `javascript:`, no
+* `data:`. A relative reference is legal only for an export: a file on disk can
+* resolve one against its own directory, and a delivered message cannot resolve
+* anything but an absolute URL.
+*/
+const isSafeUrl = (value, relative) => !/^[\u0000-\u0020]/.test(value) && !CONTROL_CHARACTERS.test(value) && !value.includes("\\") && (SAFE_URL_SCHEME.test(value) || relative && RELATIVE_URL.test(value));
+const CSS_PROPERTY = /^(--[a-zA-Z0-9-]+|[a-zA-Z][a-zA-Z0-9-]*)$/;
+const CSS_UNSAFE = /[;{}<>\\]|expression\s*\(|@import|\/\*/i;
+const CSS_URL = /url\(\s*(['"]?)([^'")]*)\1\s*\)/gi;
+/** camelCase to kebab-case; already-kebab names pass through unchanged. */
+const kebab = (property) => property.startsWith("--") ? property : property.replace(/[A-Z]/g, (l) => `-${l.toLowerCase()}`);
+const UNITLESS = /* @__PURE__ */ new Set([
+	"opacity",
+	"zIndex",
+	"fontWeight",
+	"lineHeight",
+	"order",
+	"flexGrow",
+	"flexShrink",
+	"columnCount",
+	"orphans",
+	"widows",
+	"zoom",
+	"fillOpacity",
+	"strokeOpacity"
+]);
+/** A bare number is pixels for every property that takes a length. */
+const declarationValue = (property, value) => typeof value === "number" && value !== 0 && !UNITLESS.has(property) && !property.startsWith("--") ? `${value}px` : String(value);
+const report = (sink, code, message, origins, severity = "error") => {
+	sink.diagnostics.push({
+		code,
+		severity,
+		message,
+		origins
+	});
+};
+const declarations = (sink, style, origins) => {
+	const parts = [];
+	for (const [property, value] of Object.entries(style)) {
+		if (value === void 0 || value === null) continue;
+		if (!CSS_PROPERTY.test(property)) {
+			report(sink, "unsupported-style-property", `Style property ${JSON.stringify(property)} is not a CSS property name; write it in camelCase (backgroundColor) or as a custom property (--brand).`, origins);
+			continue;
+		}
+		if (typeof value !== "string" && typeof value !== "number") {
+			report(sink, "invalid-style-value", `Style ${property} must be a string or number, not ${typeof value}.`, origins);
+			continue;
+		}
+		const text = declarationValue(property, value);
+		if (CSS_UNSAFE.test(text) || CONTROL_CHARACTERS.test(text)) {
+			report(sink, "unsafe-style-value", `Style ${property} contains CSS that could break out of the declaration; remove ${JSON.stringify(text)}.`, origins);
+			continue;
+		}
+		let unsafeUrl;
+		for (const match of text.matchAll(CSS_URL)) if (!isSafeUrl(match[2] ?? "", sink.relativeUrls)) unsafeUrl = match[2] ?? "";
+		if (unsafeUrl !== void 0) {
+			report(sink, "unsafe-url", `Style ${property} points at ${JSON.stringify(unsafeUrl)}; email URLs must use https:, mailto:, tel:, cid: or a fragment${sink.relativeUrls ? ", or a relative path" : ""}.`, origins);
+			continue;
+		}
+		parts.push(`${kebab(property)}:${text}`);
+	}
+	return parts.join(";");
+};
+const attributeValue = (sink, tag, name, spec, value, origins) => {
+	if (value === void 0 || value === null || value === false) return void 0;
+	if (value === true) return "";
+	if (typeof value !== "string" && typeof value !== "number") {
+		report(sink, "invalid-attribute-value", `<${tag} ${name}> must be a string or number, not ${typeof value}.`, origins);
+		return;
+	}
+	const text = String(value);
+	if (CONTROL_CHARACTERS.test(text)) {
+		report(sink, "invalid-attribute-value", `<${tag} ${name}> contains control characters.`, origins);
+		return;
+	}
+	if (spec.values !== void 0 && !spec.values.includes(text)) {
+		report(sink, "invalid-attribute-value", `<${tag} ${name}> accepts ${spec.values.join(", ")}; received ${JSON.stringify(text)}.`, origins);
+		return;
+	}
+	if (spec.type === "number" && !/^-?\d+$/.test(text)) {
+		report(sink, "invalid-attribute-value", `<${tag} ${name}> must be an integer.`, origins);
+		return;
+	}
+	if (spec.type === "measure" && !/^\d+(\.\d+)?%?$/.test(text)) {
+		report(sink, "invalid-attribute-value", `<${tag} ${name}> must be a pixel count or a percentage.`, origins);
+		return;
+	}
+	if (spec.type === "url" && !isSafeUrl(text, sink.relativeUrls)) {
+		report(sink, "unsafe-url", sink.relativeUrls ? `<${tag} ${name}> must use https:, mailto:, tel:, cid:, a fragment, or a relative path; received ${JSON.stringify(text)}.` : `<${tag} ${name}> must use https:, mailto:, tel:, cid: or a fragment; received ${JSON.stringify(text)}. A relative path resolves only in an export, never in a delivered message.`, origins);
+		return;
+	}
+	return text;
+};
+const attributes = (sink, tag, spec, props, origins) => {
+	const emitted = [];
+	const present = /* @__PURE__ */ new Set();
+	let classes;
+	for (const [key, value] of Object.entries(props)) {
+		if (key === "key") continue;
+		const name = key === "className" ? "class" : key;
+		if (name === "class") {
+			if (value === void 0 || value === null) continue;
+			if (typeof value !== "string") {
+				report(sink, "invalid-attribute-value", `<${tag} class> must be a string.`, origins);
+				continue;
+			}
+			if (classes !== void 0) {
+				report(sink, "duplicate-attribute", `<${tag}> sets both class and className; keep one.`, origins);
+				continue;
+			}
+			classes = value;
+			emitted.push(` class="${escapeAttribute(value)}"`);
+			continue;
+		}
+		if (name === "style") {
+			if (value === void 0 || value === null) continue;
+			if (!Predicate.isObject(value) || Array.isArray(value)) {
+				report(sink, "invalid-style", `<${tag} style> must be a property object, for example style={{ backgroundColor: "#fff" }}.`, origins);
+				continue;
+			}
+			const css = declarations(sink, value, origins);
+			if (css !== "") emitted.push(` style="${escapeAttribute(css)}"`);
+			continue;
+		}
+		if (/^on/i.test(name)) {
+			report(sink, "event-handler", `<${tag} ${name}> is an event handler; email clients strip scripting and Samva refuses it.`, origins);
+			continue;
+		}
+		if (/^(data|aria)-[a-z0-9-]+$/.test(name)) {
+			const text = attributeValue(sink, tag, name, { type: "string" }, value, origins);
+			if (text !== void 0) emitted.push(` ${name}="${escapeAttribute(text)}"`);
+			continue;
+		}
+		const attribute = EMAIL_GLOBAL_ATTRIBUTES[name] ?? spec.attributes[name];
+		if (attribute === void 0) {
+			const supported = [
+				...Object.keys(EMAIL_GLOBAL_ATTRIBUTES),
+				...Object.keys(spec.attributes),
+				"class",
+				"style"
+			].sort().join(", ");
+			report(sink, "unsupported-attribute", `<${tag}> does not support the ${name} attribute. Supported: ${supported}, plus data-* and aria-*.`, origins);
+			continue;
+		}
+		present.add(name);
+		const text = attributeValue(sink, tag, name, attribute, value, origins);
+		if (text !== void 0) emitted.push(` ${name}="${escapeAttribute(text)}"`);
+	}
+	for (const [name, attribute] of Object.entries(spec.attributes)) if (attribute.required === true && !present.has(name)) report(sink, "missing-attribute", `<${tag}> requires the ${name} attribute.`, origins);
+	return emitted.join("");
+};
+/** Fragments are transparent to a content model; raw compatibility markup is not content. */
+const contentChildren = (children) => children.flatMap((child) => child._tag === "Fragment" ? contentChildren(child.children) : [child]);
+const checkContentModel = (sink, tag, spec, children, origins) => {
+	if (spec.content === "void") {
+		if (contentChildren(children).length > 0) report(sink, "void-element-children", `<${tag}> cannot have children.`, origins);
+		return;
+	}
+	if (spec.content === "text" || spec.content === "raw") {
+		for (const child of contentChildren(children)) if (child._tag !== "Text") report(sink, "invalid-content", `<${tag}> accepts text only.`, child._tag === "Element" ? child.origins : origins);
+		return;
+	}
+	if (spec.childElements === void 0) return;
+	for (const child of contentChildren(children)) {
+		if (child._tag === "Raw") continue;
+		if (child._tag === "Text") {
+			if (child.value.trim() !== "") report(sink, "invalid-content", `<${tag}> cannot contain text directly; put it inside <${spec.childElements[0]}>.`, origins);
+			continue;
+		}
+		if (child._tag === "Element" && !spec.childElements.includes(child.tag)) report(sink, "invalid-content", `<${tag}> accepts only ${spec.childElements.map((name) => `<${name}>`).join(", ")}; found <${child.tag}>.`, child.origins);
+	}
+};
+/** Every write goes through here so `sink.written` stays the emitted offset. */
+const emit = (sink, text) => {
+	sink.written += text.length;
+	return text;
+};
+const serialize = (sink, node, parentPath, counter) => {
+	switch (node._tag) {
+		case "Text": return emit(sink, escapeText(node.value));
+		case "Raw": return emit(sink, node.html);
+		case "Fragment": return node.children.map((child) => serialize(sink, child, parentPath, counter)).join("");
+		case "Element": {
+			const start = sink.written;
+			const index = counter.next++;
+			const path = parentPath === "" ? String(index) : `${parentPath}.${index}`;
+			const own = { next: 0 };
+			const stamp = sink.instancePaths ? ` ${INSTANCE_PATH_ATTRIBUTE}="${path}"` : "";
+			const spec = emailElement(node.tag);
+			if (spec === void 0) {
+				report(sink, "unsupported-element", `<${node.tag}> is not part of the supported email vocabulary. Supported elements: ${Object.keys(EMAIL_ELEMENTS).join(", ")}.`, node.origins);
+				return "";
+			}
+			checkContentModel(sink, node.tag, spec, node.children, node.origins);
+			if (spec.content === "raw") {
+				const css = node.children.map((child) => child._tag === "Text" ? child.value : "").join("");
+				if (/<\/|<!--/i.test(css)) {
+					report(sink, "unsafe-raw-text", `<${node.tag}> content cannot contain markup.`, node.origins);
+					return "";
+				}
+				const rawAttrs = attributes(sink, node.tag, spec, node.props, node.origins);
+				const raw = css === "" ? "" : `<${node.tag}${rawAttrs}${stamp}>${css}</${node.tag}>`;
+				return record(sink, start, node, path, emit(sink, raw));
+			}
+			const attrs = attributes(sink, node.tag, spec, node.props, node.origins);
+			if (spec.content === "void") return record(sink, start, node, path, emit(sink, `<${node.tag}${attrs}${stamp} />`));
+			const open = emit(sink, `<${node.tag}${attrs}${stamp}>`);
+			const children = node.children.map((child) => serialize(sink, child, path, own)).join("");
+			const close = emit(sink, `</${node.tag}>`);
+			return record(sink, start, node, path, `${open}${children}${close}`);
+		}
+	}
+};
+/** Record an element's emitted range once its content is written. */
+const record = (sink, start, node, instancePath, text) => {
+	sink.positions.push({
+		start,
+		end: sink.written,
+		origins: node.origins,
+		instancePath,
+		tag: node.tag,
+		authored: node.authored
+	});
+	return text;
+};
+/** Lower the derived tree to email HTML, reporting every unsupported construct with its origin. */
+const serializeEmailHtml = (node, options = {}) => {
+	const sink = {
+		diagnostics: [],
+		positions: [],
+		written: 0,
+		relativeUrls: options.relativeUrls === true,
+		instancePaths: options.instancePaths === true
+	};
+	return {
+		html: serialize(sink, node, "", { next: 0 }),
+		diagnostics: sink.diagnostics,
+		positions: sink.positions
+	};
+};
+//#endregion
+export { declarationValue, escapeAttribute, escapeText, kebab, serializeEmailHtml };
+
+//# sourceMappingURL=html.js.map

package/dist/email/jsx-dev-runtime.d.ts

@@ -0,0 +1,26 @@
+import { i as JsxSourceLocation, r as JsxSource } from "../source-locations-BCJQnIfU.js";
+import { g as JSX, h as Fragment, m as EmailNode, p as EmailComponent } from "../elements-DtwKlFVH.js";
+//#region src/email/jsx-dev-runtime.d.ts
+/** Development JSX retains compiler-provided origins directly on the semantic tree. */
+declare const jsxDEV: (type: string | EmailComponent<Record<string, unknown>> | typeof Fragment, props: Record<string, unknown> | null, _key?: unknown, _staticChildren?: boolean, source?: JsxSource) => {
+  readonly _tag: "Element";
+  readonly tag: string;
+  readonly props: Readonly<Record<string, unknown>>;
+  readonly children: readonly EmailNode[];
+  readonly origins: readonly JsxSourceLocation[];
+  readonly authored: boolean;
+} | {
+  readonly _tag: "Fragment";
+  readonly children: readonly EmailNode[];
+} | {
+  readonly _tag: "Raw";
+  readonly html: string;
+  readonly text: string;
+  readonly origins: readonly JsxSourceLocation[];
+} | {
+  readonly _tag: "Text";
+  readonly value: string;
+};
+//#endregion
+export { Fragment, type JSX, jsxDEV };
+//# sourceMappingURL=jsx-dev-runtime.d.ts.map

package/dist/email/jsx-dev-runtime.js

@@ -0,0 +1,12 @@
+import { JSX_SOURCE_LOCATION_PROP } from "../source-locations.js";
+import { Fragment, jsx } from "./jsx-runtime.js";
+//#region src/email/jsx-dev-runtime.ts
+/** Development JSX retains compiler-provided origins directly on the semantic tree. */
+const jsxDEV = (type, props, _key, _staticChildren, source) => jsx(type, {
+	...props,
+	[JSX_SOURCE_LOCATION_PROP]: props?.["__samva_source_location"] ?? source
+});
+//#endregion
+export { Fragment, jsxDEV };
+
+//# sourceMappingURL=jsx-dev-runtime.js.map

package/dist/email/jsx-runtime.d.ts

@@ -0,0 +1,2 @@
+import { C as reportEmailDiagnostic, S as rawMarkup, _ as currentEmailOrigins, b as jsxs, f as EmailChild, g as JSX, h as Fragment, m as EmailNode, p as EmailComponent, v as drainEmailDiagnostics, x as normalizeChildren, y as jsx } from "../elements-DtwKlFVH.js";
+export { EmailChild, EmailComponent, EmailNode, Fragment, JSX, currentEmailOrigins, drainEmailDiagnostics, jsx, jsxs, normalizeChildren, rawMarkup, reportEmailDiagnostic };

package/dist/email/jsx-runtime.js

@@ -0,0 +1,60 @@
+import { JSX_SOURCE_LOCATION_PROP, completeJsxSourceLocation } from "../source-locations.js";
+import { Data, Predicate } from "effect";
+//#region src/email/jsx-runtime.ts
+const EmailNode = Data.taggedEnum();
+const Fragment = Symbol.for("@samva/markup/email/Fragment");
+const callSites = [];
+/** Call sites enclosing the element being built, innermost first. */
+const currentEmailOrigins = () => [...callSites].reverse();
+const reported = [];
+/** Record a finding from inside a compiler primitive, located at the authoring call site. */
+const reportEmailDiagnostic = (diagnostic) => {
+	reported.push({
+		...diagnostic,
+		origins: currentEmailOrigins()
+	});
+};
+/** Take and clear the findings primitives reported during a render. */
+const drainEmailDiagnostics = () => reported.splice(0);
+/** Normalize actual values without interpolation or recording proxies. */
+const normalizeChildren = (input) => {
+	if (input === null || input === void 0 || typeof input === "boolean") return [];
+	if (typeof input === "string") return [EmailNode.Text({ value: input })];
+	if (typeof input === "number" && Number.isFinite(input)) return [EmailNode.Text({ value: String(input) })];
+	if (Array.isArray(input)) return input.flatMap(normalizeChildren);
+	if (Predicate.isTagged(input, "Text") || Predicate.isTagged(input, "Element") || Predicate.isTagged(input, "Fragment") || Predicate.isTagged(input, "Raw")) return [input];
+	throw new TypeError("Email children must be synchronous text, finite numbers, elements, or arrays");
+};
+/** Compatibility markup emitted by a compiler primitive, with the text it stands for. */
+const rawMarkup = (html, text = "") => EmailNode.Raw({
+	html,
+	text,
+	origins: currentEmailOrigins()
+});
+/** Automatic JSX factory for ordinary HTML and synchronous imported components. */
+const jsx = (type, props) => {
+	const { children, [JSX_SOURCE_LOCATION_PROP]: source, ...attributes } = props ?? {};
+	const origin = completeJsxSourceLocation(source);
+	if (type === Fragment) return EmailNode.Fragment({ children: normalizeChildren(children) });
+	if (typeof type === "string") return EmailNode.Element({
+		tag: type,
+		props: attributes,
+		children: normalizeChildren(children),
+		origins: origin === void 0 ? currentEmailOrigins() : [origin, ...currentEmailOrigins()],
+		authored: origin !== void 0
+	});
+	if (origin !== void 0) callSites.push(origin);
+	try {
+		return EmailNode.Fragment({ children: normalizeChildren(type({
+			...attributes,
+			children
+		})) });
+	} finally {
+		if (origin !== void 0) callSites.pop();
+	}
+};
+const jsxs = jsx;
+//#endregion
+export { EmailNode, Fragment, currentEmailOrigins, drainEmailDiagnostics, jsx, jsxs, normalizeChildren, rawMarkup, reportEmailDiagnostic };
+
+//# sourceMappingURL=jsx-runtime.js.map

package/dist/email/render.d.ts

@@ -0,0 +1,36 @@
+import { r as EmailDiagnostic } from "../diagnostics-Djd9ckLg.js";
+import { m as EmailNode } from "../elements-DtwKlFVH.js";
+import { EmittedPosition } from "./selection.js";
+import { SerializeEmailOptions } from "./html.js";
+import { r as TemplateDefinition } from "../template-Dy5yOPyp.js";
+//#region src/email/render.d.ts
+/** Classic Outlook lays a document out correctly only under a transitional doctype. */
+declare const EMAIL_DOCTYPE = "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\">";
+interface EmailCompileOutput {
+  readonly html: string;
+  readonly text: string;
+  /** Findings that did not block the compile; blocking findings throw. */
+  readonly diagnostics: readonly EmailDiagnostic[];
+  /**
+   * Each emitted element's offset range and origins. Compatibility checks run
+   * in the host over the emitted document, and this is what lets a finding name
+   * the authoring element rather than a character offset.
+   */
+  readonly positions: readonly EmittedPosition[];
+}
+/** Lower the derived tree to HTML and its plain-text alternative. */
+declare const compileEmail: (node: EmailNode, options?: SerializeEmailOptions) => EmailCompileOutput;
+interface RenderedEmail {
+  readonly subject: string;
+  readonly preheader: string | undefined;
+  readonly html: string;
+  readonly text: string;
+  readonly tree: EmailNode;
+  readonly diagnostics: readonly EmailDiagnostic[];
+  readonly positions: readonly EmittedPosition[];
+}
+/** Render one validated input through the template's only content function. Host isolation is required for untrusted source. */
+declare const renderEmail: <Input>(template: TemplateDefinition<Input>, data: unknown, options?: SerializeEmailOptions) => RenderedEmail;
+//#endregion
+export { EMAIL_DOCTYPE, EmailCompileOutput, RenderedEmail, compileEmail, renderEmail };
+//# sourceMappingURL=render.d.ts.map

package/dist/email/render.js

@@ -0,0 +1,6 @@
+import { n as compileEmail, r as renderEmail, t as EMAIL_DOCTYPE } from "../render-Cddsy_XF.js";
+import "./html.js";
+import "./diagnostics.js";
+import "./stylesheets.js";
+import "./text.js";
+export { EMAIL_DOCTYPE, compileEmail, renderEmail };

package/dist/email/selection.d.ts

@@ -0,0 +1,102 @@
+import { i as JsxSourceLocation } from "../source-locations-BCJQnIfU.js";
+import { Schema } from "effect";
+//#region src/email/selection.d.ts
+/**
+ * The attribute a preview stamps so a click in a rendered document resolves to
+ * exactly one rendered element. A delivered message never carries it.
+ */
+declare const INSTANCE_PATH_ATTRIBUTE = "data-samva-instance";
+/** Where one element sits in the emitted document, with the authoring that produced it. */
+declare const EmittedPosition: Schema.Struct<{
+  readonly start: Schema.Int;
+  readonly end: Schema.Int;
+  readonly origins: Schema.$Array<Schema.Struct<{
+    readonly fileName: Schema.String;
+    readonly lineNumber: Schema.Int;
+    readonly columnNumber: Schema.Int;
+  }>>;
+  /**
+   * Dot-separated element indices from the document root, assigned as the
+   * document is written. It is the identity of one rendered instance.
+   */
+  readonly instancePath: Schema.String;
+  readonly tag: Schema.String;
+  /** False when a compiler primitive generated this element. */
+  readonly authored: Schema.Boolean;
+}>;
+interface EmittedPosition extends Schema.Schema.Type<typeof EmittedPosition> {}
+/** One rendered element, and the authoring it came from. */
+declare const EmailElementSelection: Schema.Struct<{
+  /**
+   * Dot-separated element indices from the document root. It is the identity
+   * of one rendered instance, which is what tells two iterations of the same
+   * authored element apart: their origins are identical.
+   */
+  readonly instancePath: Schema.String;
+  readonly tag: Schema.String;
+  /**
+   * The authored JSX element first, then each enclosing component call site,
+   * innermost first. Empty when the compiler generated this element with no
+   * authoring on the stack — the hidden preheader block, for instance.
+   */
+  readonly origins: Schema.$Array<Schema.Struct<{
+    readonly fileName: Schema.String;
+    readonly lineNumber: Schema.Int;
+    readonly columnNumber: Schema.Int;
+  }>>;
+  /**
+   * False when a compiler primitive generated this element. `origins[0]` is
+   * then the authoring element that asked for it rather than this element
+   * itself, so the wrapper selects the primitive the author wrote.
+   */
+  readonly authored: Schema.Boolean;
+  /** 1-based position among the rendered elements sharing this origin chain and tag. */
+  readonly occurrence: Schema.Int;
+  /**
+   * How many rendered elements share that chain and tag. Above one, one piece
+   * of authoring produced several rendered elements — a loop over a component,
+   * or a primitive that generates a repeated cell — so an edit there changes
+   * all of them.
+   */
+  readonly occurrences: Schema.Int;
+  /** Absent for the document root. */
+  readonly parentPath: Schema.optionalKey<Schema.String>;
+  /** Offset range in the rendered HTML this selection was taken from. */
+  readonly start: Schema.Int;
+  readonly end: Schema.Int;
+}>;
+interface EmailElementSelection extends Schema.Schema.Type<typeof EmailElementSelection> {}
+/**
+ * Turn one render's emitted positions into selections, in document order.
+ *
+ * The serializer records an element once its content is written, so positions
+ * arrive innermost-first; document order is what an outline and an ancestry
+ * walk both need.
+ */
+declare const emailSelections: (positions: readonly EmittedPosition[]) => readonly EmailElementSelection[];
+/** Look selections up by the instance path a rendered document carries. */
+declare const emailSelectionIndex: (selections: readonly EmailElementSelection[]) => ReadonlyMap<string, EmailElementSelection>;
+/**
+ * The authoring element a selection edits. For an authored element that is the
+ * element itself; for a generated wrapper it is the primitive that asked for
+ * it. Undefined only where the compiler generated markup with no authoring on
+ * the stack, which nothing can edit in place.
+ */
+declare const emailAuthoringTarget: (selection: EmailElementSelection) => JsxSourceLocation | undefined;
+/** Root-first ancestry of a selection, itself last. */
+declare const emailSelectionAncestry: (index: ReadonlyMap<string, EmailElementSelection>, instancePath: string) => readonly EmailElementSelection[];
+/**
+ * Every rendered instance produced through the same call site, in document
+ * order. One entry means the call ran once; several mean it repeated.
+ */
+declare const emailSelectionSiblings: (selections: readonly EmailElementSelection[], selection: EmailElementSelection) => readonly EmailElementSelection[];
+/**
+ * Every rendered instance of the same authored element, across every call site
+ * that reaches it. A shared component edited at its definition changes all of
+ * these; edited at one call site it changes only `emailSelectionSiblings`. A
+ * control has to say which of the two it is doing before it applies.
+ */
+declare const emailDefinitionInstances: (selections: readonly EmailElementSelection[], selection: EmailElementSelection) => readonly EmailElementSelection[];
+//#endregion
+export { EmailElementSelection, EmittedPosition, INSTANCE_PATH_ATTRIBUTE, emailAuthoringTarget, emailDefinitionInstances, emailSelectionAncestry, emailSelectionIndex, emailSelectionSiblings, emailSelections };
+//# sourceMappingURL=selection.d.ts.map