@samva/markup 0.1.2 → 0.3.0

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/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