@samva/markup 0.1.1 → 0.2.0

package/dist/source-locations-BCJQnIfU.d.ts

@@ -0,0 +1,89 @@
+import { E as SmlNode, m as ElementNode } from "./ast-63I-VLQx.js";
+import { Schema } from "effect";
+//#region src/source-locations.d.ts
+/**
+ * The source payload emitted by the JSX development transform. The transform
+ * may omit any field for synthetic calls; only a complete payload can identify
+ * a source origin safely.
+ */
+interface JsxSource {
+  readonly fileName?: string | undefined;
+  readonly lineNumber?: number | undefined;
+  readonly columnNumber?: number | undefined;
+}
+/** A complete, normalized source origin for a JSX element. */
+interface JsxSourceLocation {
+  readonly fileName: string;
+  readonly lineNumber: number;
+  readonly columnNumber: number;
+}
+/** JSON-safe source location shape shared by preview and editor contracts. */
+declare const JsxSourceLocation: Schema.Struct<{
+  readonly fileName: Schema.String;
+  readonly lineNumber: Schema.Int;
+  readonly columnNumber: Schema.Int;
+}>;
+/** Reasons a preview cannot safely expose an authored source map. */
+declare const SourceLocationUnavailableReason: Schema.Literals<readonly ["no-source-metadata", "structure-mismatch", "duplicate-source-origin", "render-failed", "stale-preview"]>;
+/**
+ * Runtime-only carrier for JSX source metadata. It is global so separately
+ * bundled `jsx-dev-runtime` and `render-template` entries still agree on the
+ * sidecar key, and it is a Symbol so it cannot enter SML, HTML, or JSON.
+ */
+declare const JSX_SOURCE_LOCATION: unique symbol;
+/** Internal JSX prop used only by an editor preview source transform. */
+declare const JSX_SOURCE_LOCATION_PROP: "__samva_source_location";
+/**
+ * A source map is useful only when it is trustworthy. Production `jsx`/`jsxs`
+ * currently provide no source metadata, so that path reports a typed absence
+ * rather than guessing from output order.
+ */
+type SourceLocationUnavailableReason = typeof SourceLocationUnavailableReason.Type;
+type UnboundTemplateSourceLocations = {
+  readonly kind: "available";
+  /** Parsed SML node id → the JSX origin that produced that element. */
+  readonly byNodeId: Readonly<Record<string, JsxSourceLocation>>;
+} | {
+  readonly kind: "unavailable";
+  readonly reason: SourceLocationUnavailableReason;
+};
+/** Revision-fenced source map exposed by a mutable workspace preview. */
+type TemplateSourceLocations = {
+  readonly kind: "available";
+  readonly revision: string;
+  /** Parsed SML node id → the JSX origin that produced that element. */
+  readonly byNodeId: Readonly<Record<string, JsxSourceLocation>>;
+} | {
+  readonly kind: "unavailable";
+  readonly reason: SourceLocationUnavailableReason;
+};
+/** JSON-safe schema for a parsed-node-id → JSX-origin map. */
+declare const TemplateSourceLocationsSchema: Schema.Union<readonly [Schema.Struct<{
+  readonly kind: Schema.Literal<"available">;
+  readonly revision: Schema.String;
+  readonly byNodeId: Schema.$Record<Schema.String, Schema.Struct<{
+    readonly fileName: Schema.String;
+    readonly lineNumber: Schema.Int;
+    readonly columnNumber: Schema.Int;
+  }>>;
+}>, Schema.Struct<{
+  readonly kind: Schema.Literal<"unavailable">;
+  readonly reason: Schema.Literals<readonly ["no-source-metadata", "structure-mismatch", "duplicate-source-origin", "render-failed", "stale-preview"]>;
+}>]>;
+/** Normalize the optional payload accepted by `jsxDEV`. */
+declare const completeJsxSourceLocation: (source: JsxSource | null | undefined) => JsxSourceLocation | undefined;
+/** Attach a source origin without changing the serialized draft shape. */
+declare const attachJsxSourceLocation: (node: ElementNode, source: JsxSourceLocation) => void;
+/** Read the ephemeral origin, if this draft element has one. */
+declare const jsxSourceLocationOf: (node: SmlNode) => JsxSourceLocation | undefined;
+/**
+ * Pair a draft tree with its parsed SML tree by element preorder. Text nodes
+ * are intentionally ignored: the SML parser normalizes inline whitespace, so
+ * only the element structure is stable enough to be a source-map contract.
+ */
+declare const mapJsxSourceLocations: (draft: ElementNode, parsed: ElementNode) => UnboundTemplateSourceLocations;
+/** Compare source-map statuses for the emission determinism guard. */
+declare const sameTemplateSourceLocations: (left: UnboundTemplateSourceLocations, right: UnboundTemplateSourceLocations) => boolean;
+//#endregion
+export { SourceLocationUnavailableReason as a, UnboundTemplateSourceLocations as c, jsxSourceLocationOf as d, mapJsxSourceLocations as f, JsxSourceLocation as i, attachJsxSourceLocation as l, JSX_SOURCE_LOCATION_PROP as n, TemplateSourceLocations as o, sameTemplateSourceLocations as p, JsxSource as r, TemplateSourceLocationsSchema as s, JSX_SOURCE_LOCATION as t, completeJsxSourceLocation as u };
+//# sourceMappingURL=source-locations-BCJQnIfU.d.ts.map

package/dist/source-locations.d.ts

@@ -0,0 +1,2 @@
+import { a as SourceLocationUnavailableReason, c as UnboundTemplateSourceLocations, d as jsxSourceLocationOf, f as mapJsxSourceLocations, i as JsxSourceLocation, l as attachJsxSourceLocation, n as JSX_SOURCE_LOCATION_PROP, o as TemplateSourceLocations, p as sameTemplateSourceLocations, r as JsxSource, s as TemplateSourceLocationsSchema, t as JSX_SOURCE_LOCATION, u as completeJsxSourceLocation } from "./source-locations-BCJQnIfU.js";
+export { JSX_SOURCE_LOCATION, JSX_SOURCE_LOCATION_PROP, JsxSource, JsxSourceLocation, SourceLocationUnavailableReason, TemplateSourceLocations, TemplateSourceLocationsSchema, UnboundTemplateSourceLocations, attachJsxSourceLocation, completeJsxSourceLocation, jsxSourceLocationOf, mapJsxSourceLocations, sameTemplateSourceLocations };

package/dist/source-locations.js

@@ -0,0 +1,125 @@
+import { Predicate, Schema } from "effect";
+//#region src/source-locations.ts
+/** JSON-safe source location shape shared by preview and editor contracts. */
+const JsxSourceLocation = Schema.Struct({
+	fileName: Schema.String,
+	lineNumber: Schema.Int.check(Schema.isGreaterThanOrEqualTo(1)),
+	columnNumber: Schema.Int.check(Schema.isGreaterThanOrEqualTo(1))
+});
+/** Reasons a preview cannot safely expose an authored source map. */
+const SourceLocationUnavailableReason = Schema.Literals([
+	"no-source-metadata",
+	"structure-mismatch",
+	"duplicate-source-origin",
+	"render-failed",
+	"stale-preview"
+]);
+/**
+* Runtime-only carrier for JSX source metadata. It is global so separately
+* bundled `jsx-dev-runtime` and `render-template` entries still agree on the
+* sidecar key, and it is a Symbol so it cannot enter SML, HTML, or JSON.
+*/
+const JSX_SOURCE_LOCATION = Symbol.for("@samva/markup/jsx-source-location");
+/** Internal JSX prop used only by an editor preview source transform. */
+const JSX_SOURCE_LOCATION_PROP = "__samva_source_location";
+/** JSON-safe schema for a parsed-node-id → JSX-origin map. */
+const TemplateSourceLocationsSchema = Schema.Union([Schema.Struct({
+	kind: Schema.Literal("available"),
+	revision: Schema.String,
+	byNodeId: Schema.Record(Schema.String, JsxSourceLocation)
+}), Schema.Struct({
+	kind: Schema.Literal("unavailable"),
+	reason: SourceLocationUnavailableReason
+})]);
+/** Normalize the optional payload accepted by `jsxDEV`. */
+const completeJsxSourceLocation = (source) => {
+	if (source?.fileName === void 0 || source.lineNumber === void 0 || source.columnNumber === void 0) return;
+	return Object.freeze({
+		fileName: source.fileName,
+		lineNumber: source.lineNumber,
+		columnNumber: source.columnNumber
+	});
+};
+/** Attach a source origin without changing the serialized draft shape. */
+const attachJsxSourceLocation = (node, source) => {
+	if (Object.hasOwn(node, JSX_SOURCE_LOCATION)) return;
+	Object.defineProperty(node, JSX_SOURCE_LOCATION, {
+		configurable: false,
+		enumerable: false,
+		value: source,
+		writable: false
+	});
+};
+const isJsxSourceLocation = (value) => Predicate.hasProperty(value, "fileName") && typeof value.fileName === "string" && Predicate.hasProperty(value, "lineNumber") && typeof value.lineNumber === "number" && Number.isInteger(value.lineNumber) && Predicate.hasProperty(value, "columnNumber") && typeof value.columnNumber === "number" && Number.isInteger(value.columnNumber);
+/** Read the ephemeral origin, if this draft element has one. */
+const jsxSourceLocationOf = (node) => {
+	if (node.kind !== "element") return void 0;
+	const value = Object.getOwnPropertyDescriptor(node, JSX_SOURCE_LOCATION)?.value;
+	return isJsxSourceLocation(value) ? value : void 0;
+};
+const elementChildren = (node) => node.children.filter((child) => child.kind === "element");
+const sourceOriginKey = (source) => JSON.stringify([
+	source.fileName,
+	source.lineNumber,
+	source.columnNumber
+]);
+/**
+* Pair a draft tree with its parsed SML tree by element preorder. Text nodes
+* are intentionally ignored: the SML parser normalizes inline whitespace, so
+* only the element structure is stable enough to be a source-map contract.
+*/
+const mapJsxSourceLocations = (draft, parsed) => {
+	const byNodeId = {};
+	const origins = /* @__PURE__ */ new Set();
+	let duplicateOrigin = false;
+	const visit = (draftNode, parsedNode) => {
+		if (draftNode.tag !== parsedNode.tag) return false;
+		const source = jsxSourceLocationOf(draftNode);
+		if (source !== void 0) {
+			const origin = sourceOriginKey(source);
+			if (origins.has(origin)) duplicateOrigin = true;
+			origins.add(origin);
+			if (Object.hasOwn(byNodeId, parsedNode.id)) return false;
+			byNodeId[parsedNode.id] = source;
+		}
+		const draftChildren = elementChildren(draftNode);
+		const parsedChildren = elementChildren(parsedNode);
+		if (draftChildren.length !== parsedChildren.length) return false;
+		for (let index = 0; index < draftChildren.length; index++) if (!visit(draftChildren[index], parsedChildren[index])) return false;
+		return true;
+	};
+	if (!visit(draft, parsed)) return {
+		kind: "unavailable",
+		reason: "structure-mismatch"
+	};
+	if (duplicateOrigin) return {
+		kind: "unavailable",
+		reason: "duplicate-source-origin"
+	};
+	if (Object.keys(byNodeId).length === 0) return {
+		kind: "unavailable",
+		reason: "no-source-metadata"
+	};
+	return {
+		kind: "available",
+		byNodeId: Object.freeze(byNodeId)
+	};
+};
+/** Compare source-map statuses for the emission determinism guard. */
+const sameTemplateSourceLocations = (left, right) => {
+	if (left.kind !== right.kind) return false;
+	if (left.kind === "unavailable") return right.kind === "unavailable" && left.reason === right.reason;
+	if (right.kind === "unavailable") return false;
+	const leftEntries = Object.entries(left.byNodeId);
+	const rightEntries = Object.entries(right.byNodeId);
+	if (leftEntries.length !== rightEntries.length) return false;
+	for (const [nodeId, source] of leftEntries) {
+		const other = right.byNodeId[nodeId];
+		if (other === void 0 || other.fileName !== source.fileName || other.lineNumber !== source.lineNumber || other.columnNumber !== source.columnNumber) return false;
+	}
+	return true;
+};
+//#endregion
+export { JSX_SOURCE_LOCATION, JSX_SOURCE_LOCATION_PROP, JsxSourceLocation, SourceLocationUnavailableReason, TemplateSourceLocationsSchema, attachJsxSourceLocation, completeJsxSourceLocation, jsxSourceLocationOf, mapJsxSourceLocations, sameTemplateSourceLocations };
+
+//# sourceMappingURL=source-locations.js.map

package/dist/stylesheets-oDRAnYA3.d.ts

@@ -0,0 +1,94 @@
+import "./source-locations-BCJQnIfU.js";
+import { r as EmailDiagnostic } from "./diagnostics-Djd9ckLg.js";
+import { m as EmailNode } from "./elements-DtwKlFVH.js";
+import "css-tree";
+//#region src/email/selectors.d.ts
+type EmailElementNode = Extract<EmailNode, {
+  _tag: "Element";
+}>;
+interface AttributeTest {
+  readonly name: string;
+  readonly operator?: string | undefined;
+  readonly value?: string | undefined;
+}
+interface Compound {
+  readonly tag?: string | undefined;
+  readonly id?: string | undefined;
+  readonly classes: readonly string[];
+  readonly attributes: readonly AttributeTest[];
+  /** A compound the matcher cannot evaluate — a pseudo-class, say — never matches. */
+  readonly opaque: boolean;
+}
+type Combinator = "descendant" | "child" | "adjacent" | "sibling";
+interface CompiledSelector {
+  /** Document order, left to right; each part names the combinator that follows it. */
+  readonly parts: readonly {
+    readonly compound: Compound;
+    readonly after?: Combinator;
+  }[];
+}
+/** An element together with the ancestors and preceding siblings a combinator needs. */
+interface Ancestry {
+  readonly element: EmailElementNode;
+  readonly parent: Ancestry | undefined;
+  readonly previous: readonly EmailElementNode[];
+}
+declare const classListOf: (element: EmailElementNode) => readonly string[];
+/** Match a compiled selector against one element in its tree position. */
+declare const matchesSelector: (selector: CompiledSelector | undefined, ancestry: Ancestry) => boolean;
+//#endregion
+//#region src/email/css.d.ts
+interface CssDeclaration {
+  /** Kebab-case property name, as authored. */
+  readonly property: string;
+  readonly value: string;
+  readonly important: boolean;
+}
+/** Specificity as the CSS triple (id, class/attribute/pseudo-class, type). */
+type Specificity = readonly [number, number, number];
+interface CssRule {
+  /** Exactly one selector; a selector list is split into one rule each. */
+  readonly selector: string;
+  /** Decoded class identifiers mentioned by this selector, including nested pseudo selectors. */
+  readonly classes: readonly string[];
+  readonly specificity: Specificity;
+  readonly declarations: readonly CssDeclaration[];
+  /** Position across every stylesheet, in the order they were imported. */
+  readonly order: number;
+  /** Declared `@layer` index; unlayered declarations sort above every layer. */
+  readonly layer: number;
+  /** Enclosing conditional at-rule preludes, outermost first. */
+  readonly conditions: readonly string[];
+  /** Unconditional and pseudo-free rules are the only ones that can become an inline style. */
+  readonly inlinable: boolean;
+  /** Compiled at build time so the render lane needs no CSS parser. */
+  readonly matcher: CompiledSelector | undefined;
+}
+interface Stylesheet {
+  readonly rules: readonly CssRule[];
+  /** `@font-face` and other at-rules kept verbatim in `<head>`. */
+  readonly headAtRules: readonly string[];
+  /** Unconditional custom properties, for resolving `var()` before inlining. */
+  readonly variables: Readonly<Record<string, string>>;
+  readonly diagnostics: readonly EmailDiagnostic[];
+}
+/** Compile a selector into the plain-data matcher the render lane uses. */
+declare const compileSelector: (selector: string) => CompiledSelector | undefined;
+/** Parse one stylesheet into rules, keeping layer, order and conditions. */
+declare const parseStylesheet: (source: string, options?: {
+  readonly origin?: string;
+  readonly startOrder?: number;
+}) => Stylesheet;
+//#endregion
+//#region src/email/stylesheets.d.ts
+/** Called by a compiler-generated stylesheet module at import time. */
+declare const registerStylesheet: (sheet: Stylesheet) => void;
+/** Drop every registration. The render entry calls this before a render. */
+declare const resetStylesheets: () => void;
+/** Every registered sheet flattened into one, with order preserved across sheets. */
+declare const collectStylesheets: () => Stylesheet;
+/** True when a template registered no styles at all, so the render can skip the pass. */
+declare const hasStylesheets: () => boolean;
+//#endregion
+export { CssDeclaration as a, Stylesheet as c, Ancestry as d, CompiledSelector as f, matchesSelector as h, resetStylesheets as i, compileSelector as l, classListOf as m, hasStylesheets as n, CssRule as o, Compound as p, registerStylesheet as r, Specificity as s, collectStylesheets as t, parseStylesheet as u };
+//# sourceMappingURL=stylesheets-oDRAnYA3.d.ts.map

package/dist/template-Dy5yOPyp.d.ts

@@ -0,0 +1,60 @@
+import { m as EmailNode } from "./elements-DtwKlFVH.js";
+import { r as InputSchema } from "./input-schema-BIfzI63B.js";
+import { StandardJSONSchemaV1 } from "effect/StandardSchema";
+//#region src/template.d.ts
+/** One actual-input render owns all of a message's authored content. */
+interface EmailContent {
+  readonly subject: string;
+  readonly preheader?: string;
+  readonly body: EmailNode;
+  readonly text?: string;
+}
+/**
+ * Fixed ambient values a template declares. Rendering has no clock and no entropy source: reading
+ * the current instant or a random value throws unless the matching value is declared here, so a
+ * message either takes time and randomness from its input or states them once as configuration.
+ */
+interface TemplateRuntime {
+  readonly now?: number;
+  readonly randomSeed?: number;
+}
+/** Explicit template identity distinguishes entries from imported helper modules. */
+interface TemplateDefinition<Input> {
+  readonly id: string;
+  readonly schema: InputSchema<Input>;
+  readonly fixtures: Readonly<Record<string, Input>>;
+  readonly render: (input: Input) => EmailContent;
+  readonly runtime?: TemplateRuntime;
+}
+/** Classify an evaluated module export without executing helpers as templates. */
+declare const isTemplateDefinition: (value: unknown) => value is TemplateDefinition<unknown>;
+/**
+ * The one naming contract for a template id and a fixture key: a letter, a digit or `_` first,
+ * then those plus `.`, `_` and `-`.
+ *
+ * Both names are written into file paths — a local export writes one page at
+ * `templates/<id>/<fixture>.html` — so each has to be a single plain path segment. The rule lives
+ * at the declaration, so a project that could not be exported is refused where the name is
+ * written rather than at the end of a build. Consumers that resolve a path from these names
+ * import this pattern; they do not restate it.
+ */
+declare const TEMPLATE_NAME_PATTERN: RegExp;
+/**
+ * Define an email template with caller-input inference from a Standard JSON Schema converter. The
+ * helper is named for its channel because its render result is email content; `TemplateDefinition`
+ * and `TemplateInput` stay channel-neutral.
+ */
+declare const defineEmail: <S extends StandardJSONSchemaV1>(definition: {
+  readonly id: string;
+  readonly schema: S;
+  readonly fixtures: Readonly<Record<string, NoInfer<StandardJSONSchemaV1.InferInput<S>>>>;
+  readonly render: (input: NoInfer<StandardJSONSchemaV1.InferInput<S>>) => EmailContent;
+  readonly runtime?: TemplateRuntime;
+}) => TemplateDefinition<StandardJSONSchemaV1.InferInput<S>>;
+/** Caller input for generated references and separate authoring consumers. */
+type TemplateInput<T extends {
+  readonly render: (input: never) => EmailContent;
+}> = Parameters<T["render"]>[0];
+//#endregion
+export { TemplateRuntime as a, TemplateInput as i, TEMPLATE_NAME_PATTERN as n, defineEmail as o, TemplateDefinition as r, isTemplateDefinition as s, EmailContent as t };
+//# sourceMappingURL=template-Dy5yOPyp.d.ts.map

package/dist/template.d.ts

@@ -0,0 +1,2 @@
+import { a as TemplateRuntime, i as TemplateInput, n as TEMPLATE_NAME_PATTERN, o as defineEmail, r as TemplateDefinition, s as isTemplateDefinition, t as EmailContent } from "./template-Dy5yOPyp.js";
+export { EmailContent, TEMPLATE_NAME_PATTERN, TemplateDefinition, TemplateInput, TemplateRuntime, defineEmail, isTemplateDefinition };

package/dist/template.js

@@ -0,0 +1,37 @@
+import { inputSchema } from "./input-schema.js";
+import { Predicate } from "effect";
+//#region src/template.ts
+/** Classify an evaluated module export without executing helpers as templates. */
+const isTemplateDefinition = (value) => Predicate.isObject(value) && typeof value.id === "string" && typeof value.render === "function" && Predicate.isObject(value.schema);
+/**
+* The one naming contract for a template id and a fixture key: a letter, a digit or `_` first,
+* then those plus `.`, `_` and `-`.
+*
+* Both names are written into file paths — a local export writes one page at
+* `templates/<id>/<fixture>.html` — so each has to be a single plain path segment. The rule lives
+* at the declaration, so a project that could not be exported is refused where the name is
+* written rather than at the end of a build. Consumers that resolve a path from these names
+* import this pattern; they do not restate it.
+*/
+const TEMPLATE_NAME_PATTERN = /^[A-Za-z0-9_][A-Za-z0-9._-]*$/;
+const checkTemplateName = (kind, value) => {
+	if (TEMPLATE_NAME_PATTERN.test(value)) return;
+	throw new TypeError(`${kind} ${JSON.stringify(value)} is not one path segment. A template id and a fixture key are written into file paths, so each must start with a letter, a digit or "_" and continue with letters, digits, ".", "_" or "-".`);
+};
+/**
+* Define an email template with caller-input inference from a Standard JSON Schema converter. The
+* helper is named for its channel because its render result is email content; `TemplateDefinition`
+* and `TemplateInput` stay channel-neutral.
+*/
+const defineEmail = (definition) => {
+	checkTemplateName("Template id", definition.id);
+	for (const fixture of Object.keys(definition.fixtures)) checkTemplateName("Fixture key", fixture);
+	return {
+		...definition,
+		schema: inputSchema(definition.schema)
+	};
+};
+//#endregion
+export { TEMPLATE_NAME_PATTERN, defineEmail, isTemplateDefinition };
+
+//# sourceMappingURL=template.js.map

package/dist/tsx-source-instrumentation.d.ts

@@ -0,0 +1,23 @@
+//#region src/tsx-source-instrumentation.d.ts
+declare const TsxSourceInstrumentationError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "TsxSourceInstrumentationError";
+} & Readonly<A>;
+declare class TsxSourceInstrumentationError extends TsxSourceInstrumentationError_base<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+/**
+ * Add ephemeral source-origin props to one known TSX entry before a hosted
+ * editor preview is bundled. The returned source is a build input only: the
+ * caller must never persist it or expose it as authored source.
+ *
+ * Every JSX element is marked, including custom components. The markup runtime
+ * strips the marker and keeps an inner element's sidecar when a custom
+ * component renders JSX of its own. JSX fragments have no element output and
+ * are therefore intentionally skipped. Pass a null import source to preserve
+ * authored JSX pragmas in executable email builds.
+ */
+declare const instrumentTsxSourceForPreview: (source: string, fileName: string, token?: string, jsxImportSource?: string | null) => string;
+//#endregion
+export { TsxSourceInstrumentationError, instrumentTsxSourceForPreview };
+//# sourceMappingURL=tsx-source-instrumentation.d.ts.map

package/dist/tsx-source-instrumentation.js

@@ -0,0 +1,97 @@
+import { JSX_SOURCE_LOCATION_PROP } from "./source-locations.js";
+import { buildLineMap, lineColumn } from "./diagnostics.js";
+import { Data, Predicate } from "effect";
+import { parse } from "@babel/parser";
+//#region src/tsx-source-instrumentation.ts
+var TsxSourceInstrumentationError = class extends Data.TaggedError("TsxSourceInstrumentationError") {};
+const isRecord = (value) => Predicate.isObject(value) && !Array.isArray(value);
+const isAstNode = (value) => isRecord(value) && typeof value.type === "string" && typeof value.start === "number" && typeof value.end === "number";
+const walkAst = (value, visit) => {
+	if (Array.isArray(value)) {
+		for (const item of value) walkAst(item, visit);
+		return;
+	}
+	if (!isRecord(value)) return;
+	if (isAstNode(value)) visit(value);
+	for (const [key, child] of Object.entries(value)) {
+		if (key === "loc" || key === "extra" || key === "comments" || key === "tokens") continue;
+		walkAst(child, visit);
+	}
+};
+const jsxIdentifier = (value) => {
+	if (!isAstNode(value) || value.type !== "JSXIdentifier") return void 0;
+	return typeof value.name === "string" ? value.name : void 0;
+};
+const parseErrorMessage = (error) => isRecord(error) && typeof error.message === "string" ? error.message : "The authored TSX could not be parsed for preview instrumentation.";
+const marker = (fileName, source, offset, token) => {
+	const position = lineColumn(buildLineMap(source), offset);
+	return ` ${JSX_SOURCE_LOCATION_PROP}={${JSON.stringify({
+		fileName,
+		lineNumber: position.line,
+		columnNumber: position.column,
+		...token === void 0 ? {} : { token }
+	})}}`;
+};
+/**
+* Add ephemeral source-origin props to one known TSX entry before a hosted
+* editor preview is bundled. The returned source is a build input only: the
+* caller must never persist it or expose it as authored source.
+*
+* Every JSX element is marked, including custom components. The markup runtime
+* strips the marker and keeps an inner element's sidecar when a custom
+* component renders JSX of its own. JSX fragments have no element output and
+* are therefore intentionally skipped. Pass a null import source to preserve
+* authored JSX pragmas in executable email builds.
+*/
+const instrumentTsxSourceForPreview = (source, fileName, token, jsxImportSource = "@samva/preview-runtime") => {
+	let parsed;
+	try {
+		parsed = parse(source, {
+			plugins: ["typescript", "jsx"],
+			sourceType: "module"
+		});
+	} catch (error) {
+		throw new TsxSourceInstrumentationError({
+			cause: error,
+			message: parseErrorMessage(error)
+		});
+	}
+	const edits = [];
+	for (const comment of jsxImportSource === null ? [] : parsed.comments ?? []) {
+		const commentStart = comment.start;
+		const commentEnd = comment.end;
+		if (commentStart === void 0 || commentEnd === void 0) continue;
+		const commentSource = source.slice(commentStart, commentEnd);
+		for (const match of commentSource.matchAll(/@jsxImportSource\s+[^\s*]+/gu)) {
+			if (match.index === void 0) continue;
+			edits.push({
+				start: commentStart + match.index,
+				end: commentStart + match.index + match[0].length,
+				value: `@jsxImportSource ${jsxImportSource}`
+			});
+		}
+	}
+	walkAst(parsed.program, (node) => {
+		if (node.type !== "JSXElement") return;
+		const openingElement = node.openingElement;
+		if (!isAstNode(openingElement)) return;
+		const attributes = openingElement.attributes;
+		if (Array.isArray(attributes)) for (const attribute of attributes) {
+			if (!isAstNode(attribute) || attribute.type !== "JSXAttribute") continue;
+			if (jsxIdentifier(attribute.name) === "__samva_source_location") throw new TsxSourceInstrumentationError({ message: `The reserved JSX prop ${JSX_SOURCE_LOCATION_PROP} cannot be authored directly.` });
+		}
+		const closingLength = source.slice(openingElement.end - 2, openingElement.end) === "/>" ? 2 : 1;
+		edits.push({
+			start: openingElement.end - closingLength,
+			end: openingElement.end - closingLength,
+			value: marker(fileName, source, openingElement.start, token)
+		});
+	});
+	let instrumented = source;
+	for (const edit of edits.toSorted((left, right) => right.start - left.start)) instrumented = instrumented.slice(0, edit.start) + edit.value + instrumented.slice(edit.end);
+	return instrumented;
+};
+//#endregion
+export { TsxSourceInstrumentationError, instrumentTsxSourceForPreview };
+
+//# sourceMappingURL=tsx-source-instrumentation.js.map

package/dist/tsx-tracer.d.ts

@@ -0,0 +1,116 @@
+import { s as Span } from "./diagnostics-oveE-laV.js";
+import { SmlOp } from "./ops.js";
+import { Result } from "effect";
+//#region src/tsx-tracer.d.ts
+/** The closed set of reasons a rendered heading cannot be mapped safely. */
+type TsxHeadingDiagnosticCode = "tsx-invalid-authored-source" | "tsx-invalid-emitted-source" | "tsx-target-not-found" | "tsx-unsupported-target" | "tsx-ambiguous-target" | "tsx-dynamic-target";
+interface TsxHeadingDiagnostic {
+  readonly code: TsxHeadingDiagnosticCode;
+  readonly message: string;
+  readonly span: Span;
+}
+declare const TsxHeadingTraceError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "TsxHeadingTraceError";
+} & Readonly<A>;
+declare class TsxHeadingTraceError extends TsxHeadingTraceError_base<{
+  readonly diagnostics: ReadonlyArray<TsxHeadingDiagnostic>;
+}> {}
+/**
+ * Source metadata attached to a rendered JSX node by the development JSX
+ * transform, or an equivalent exact source span from a host.
+ *
+ * `lineNumber`/`columnNumber` use the JSX transform convention: both are
+ * one-based and identify the opening `<` of the element. A span locator is
+ * useful to hosts that already have absolute offsets and must match the whole
+ * JSX element span exactly.
+ */
+type TsxSourceLocator = {
+  readonly fileName: string;
+  readonly lineNumber: number;
+  readonly columnNumber: number;
+} | {
+  readonly fileName: string;
+  readonly span: Span;
+};
+/**
+ * How an authored static text child spells itself. `jsx-text` is bare text
+ * between tags; `string-literal` is a `{"…"}` expression container holding a
+ * string literal, or a template literal with no expressions. An edit writes a
+ * child back in the form it already had.
+ */
+type StaticTextForm = "jsx-text" | "string-literal";
+/** A source range containing only the text bytes that an edit is allowed to replace. */
+interface TsxHeadingSourceTarget {
+  readonly nodeId: string;
+  readonly text: string;
+  readonly span: Span;
+  /** The spelling to preserve when the range is rewritten. */
+  readonly form: StaticTextForm;
+}
+interface TraceTsxHeadingInput {
+  /** The canonical TSX entry file path. */
+  readonly authoredFile: string;
+  /** The canonical TSX entry file. */
+  readonly authoredSource: string;
+  /** The last-good SML preview derived from that entry file. */
+  readonly emittedSource: string;
+  /** The selected semantic SML node id. */
+  readonly nodeId: string;
+  /** Exact runtime/source-map provenance for the selected JSX node. */
+  readonly sourceLocator?: TsxSourceLocator | undefined;
+}
+interface ReplaceTsxHeadingTextInput extends TraceTsxHeadingInput {
+  readonly text: string;
+}
+type TsxHeadingTrace = Result.Result<TsxHeadingSourceTarget, TsxHeadingTraceError>;
+type TsxHeadingEdit = Result.Result<string, TsxHeadingTraceError>;
+/** Resolve one rendered Heading to one direct-literal JSX text range. */
+declare const traceTsxHeadingTarget: (input: TraceTsxHeadingInput) => TsxHeadingTrace;
+/** Replace only the mapped literal bytes; all other authored TSX stays untouched. */
+declare const replaceTsxHeadingText: (input: ReplaceTsxHeadingTextInput) => TsxHeadingEdit;
+/**
+ * The closed set of failures returned by {@link applyTsxSmlOps}. The editor
+ * deliberately treats these as a typed "not safe to edit" response: it can
+ * keep showing the preview and offer source editing without guessing at a
+ * byte range in a user's project.
+ */
+type TsxSmlDiagnosticCode = TsxHeadingDiagnosticCode | "tsx-invalid-snippet" | "tsx-unsupported-operation";
+interface TsxSmlDiagnostic {
+  readonly code: TsxSmlDiagnosticCode;
+  readonly message: string;
+  readonly span: Span;
+}
+declare const TsxSmlOpsError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "TsxSmlOpsError";
+} & Readonly<A>;
+declare class TsxSmlOpsError extends TsxSmlOpsError_base<{
+  readonly diagnostics: ReadonlyArray<TsxSmlDiagnostic>;
+}> {}
+interface ApplyTsxSmlOpsInput {
+  /** The canonical TSX entry file path. */
+  readonly authoredFile: string;
+  /** The canonical TSX entry file. */
+  readonly authoredSource: string;
+  /** The last-good SML preview derived from that entry file. */
+  readonly emittedSource: string;
+  /** Revision-fenced JSX origins for the SML ids in `emittedSource`. */
+  readonly sourceLocations: {
+    readonly byNodeId: Readonly<Record<string, TsxSourceLocator>>;
+  };
+  /** SML operations evaluated against the emitted-source id snapshot. */
+  readonly ops: ReadonlyArray<SmlOp>;
+}
+type TsxSmlOpsResult = Result.Result<string, TsxSmlOpsError>;
+/**
+ * Apply semantic editor operations to the authored TSX entry.
+ *
+ * The emitted SML document remains the validation oracle: operations are
+ * preflighted through the same markup op implementation first, then each
+ * mapped target is checked against the authored JSX AST and exact source
+ * provenance. The mutable source tree below only moves original AST nodes or
+ * inserts validated raw fragments; it never reprints the user's module.
+ */
+declare const applyTsxSmlOps: (input: ApplyTsxSmlOpsInput) => TsxSmlOpsResult;
+//#endregion
+export { ApplyTsxSmlOpsInput, ReplaceTsxHeadingTextInput, StaticTextForm, TraceTsxHeadingInput, TsxHeadingDiagnostic, TsxHeadingDiagnosticCode, TsxHeadingEdit, TsxHeadingSourceTarget, TsxHeadingTrace, TsxHeadingTraceError, TsxSmlDiagnostic, TsxSmlDiagnosticCode, TsxSmlOpsError, TsxSmlOpsResult, TsxSourceLocator, applyTsxSmlOps, replaceTsxHeadingText, traceTsxHeadingTarget };
+//# sourceMappingURL=tsx-tracer.d.ts.map