@samva/markup 0.1.0

package/dist/interpolate.d.ts

@@ -0,0 +1,27 @@
+import { Schema } from "effect";
+//#region src/interpolate.d.ts
+declare const DocumentVariableTypeSchema: Schema.Literals<readonly ["string", "number", "boolean", "date", "array", "object"]>;
+type DocumentVariableType = typeof DocumentVariableTypeSchema.Type;
+/** One entry of a template's declared variable schema. */
+declare const DocumentVariableSchema: Schema.Struct<{
+  readonly name: Schema.String;
+  readonly type: Schema.Literals<readonly ["string", "number", "boolean", "date", "array", "object"]>;
+  readonly required: Schema.Boolean;
+  readonly default: Schema.optional<Schema.Unknown>;
+  readonly description: Schema.optional<Schema.String>;
+}>;
+interface DocumentVariable extends Schema.Schema.Type<typeof DocumentVariableSchema> {}
+declare const variableReferencePattern: RegExp;
+declare const getVariableValue: (variables: Record<string, unknown>, variableSchema: ReadonlyArray<DocumentVariable>, name: string) => unknown;
+declare const stringifyVariable: (value: unknown) => string;
+interface InterpolationResult {
+  readonly rendered: string;
+  /** Required variables that resolved to nothing (no value, no default). */
+  readonly missing: ReadonlySet<string>;
+}
+declare const interpolate: (text: string, variables: Record<string, unknown>, variableSchema: ReadonlyArray<DocumentVariable>) => InterpolationResult;
+declare const variableReferences: (text: string) => Set<string>;
+declare const addVariableReferences: (target: Set<string>, text: string) => void;
+//#endregion
+export { DocumentVariable, DocumentVariableSchema, DocumentVariableType, DocumentVariableTypeSchema, InterpolationResult, addVariableReferences, getVariableValue, interpolate, stringifyVariable, variableReferencePattern, variableReferences };
+//# sourceMappingURL=interpolate.d.ts.map

package/dist/interpolate.js

@@ -0,0 +1,61 @@
+import { Schema } from "effect";
+//#region src/interpolate.ts
+const limitedString = (maxLength) => Schema.String.check(Schema.isMaxLength(maxLength));
+const DocumentVariableTypeSchema = Schema.Literals([
+	"string",
+	"number",
+	"boolean",
+	"date",
+	"array",
+	"object"
+]);
+/** One entry of a template's declared variable schema. */
+const DocumentVariableSchema = Schema.Struct({
+	name: limitedString(128),
+	type: DocumentVariableTypeSchema,
+	required: Schema.Boolean,
+	default: Schema.optional(Schema.Unknown),
+	description: Schema.optional(limitedString(512))
+});
+const variableReferencePattern = /\$\{\s*\/?([\w.]+)\s*\}|\{\{\s*([\w.]+)\s*\}\}/g;
+const getVariableValue = (variables, variableSchema, name) => {
+	const schema = variableSchema.find((item) => item.name === name);
+	const value = variables[name];
+	if (value !== void 0 && value !== null) return value;
+	return schema?.default;
+};
+const stringifyVariable = (value) => {
+	if (value === void 0 || value === null) return "";
+	if (value instanceof Date) return value.toISOString();
+	if (Array.isArray(value)) return value.join(", ");
+	if (typeof value === "object") return JSON.stringify(value);
+	return String(value);
+};
+const interpolate = (text, variables, variableSchema) => {
+	const missing = /* @__PURE__ */ new Set();
+	const substitute = (name) => {
+		const value = getVariableValue(variables, variableSchema, name);
+		const schema = variableSchema.find((item) => item.name === name);
+		if ((value === void 0 || value === null) && schema?.required) missing.add(name);
+		return stringifyVariable(value);
+	};
+	return {
+		rendered: text.replace(variableReferencePattern, (_match, dollarName, braceName) => substitute(dollarName ?? braceName ?? "")),
+		missing
+	};
+};
+const variableReferences = (text) => {
+	const names = /* @__PURE__ */ new Set();
+	for (const match of text.matchAll(variableReferencePattern)) {
+		const name = match[1] ?? match[2];
+		if (name !== void 0 && name !== "") names.add(name);
+	}
+	return names;
+};
+const addVariableReferences = (target, text) => {
+	variableReferences(text).forEach((name) => target.add(name));
+};
+//#endregion
+export { DocumentVariableSchema, DocumentVariableTypeSchema, addVariableReferences, getVariableValue, interpolate, stringifyVariable, variableReferencePattern, variableReferences };
+
+//# sourceMappingURL=interpolate.js.map

package/dist/interpolate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interpolate.js","names":[],"sources":["../src/interpolate.ts"],"sourcesContent":["import { Schema } from \"effect\";\n\n// Send-time `{{name}}` / `${name}` interpolation. Originally ported from\n// @samva/document (variables.ts); now a single left-to-right pass over both\n// syntaxes (see `variableReferencePattern`) so a substituted value is never\n// re-scanned — a variable whose value itself contains `{{x}}`/`${x}` is emitted\n// literally instead of being recursively interpolated. Channel-agnostic: it\n// runs over compiled email artifacts, sms bodies, and whatsapp component text\n// alike, always AFTER resolveArtifactConditionals has selected branches and\n// stripped markers.\n\nconst limitedString = (maxLength: number) => Schema.String.check(Schema.isMaxLength(maxLength));\n\nexport const DocumentVariableTypeSchema = Schema.Literals([\n  \"string\",\n  \"number\",\n  \"boolean\",\n  \"date\",\n  \"array\",\n  \"object\",\n]);\n\nexport type DocumentVariableType = typeof DocumentVariableTypeSchema.Type;\n\n/** One entry of a template's declared variable schema. */\nexport const DocumentVariableSchema = Schema.Struct({\n  name: limitedString(128),\n  type: DocumentVariableTypeSchema,\n  required: Schema.Boolean,\n  default: Schema.optional(Schema.Unknown),\n  description: Schema.optional(limitedString(512)),\n});\n\nexport interface DocumentVariable extends Schema.Schema.Type<typeof DocumentVariableSchema> {}\n\nexport const variableReferencePattern = /\\$\\{\\s*\\/?([\\w.]+)\\s*\\}|\\{\\{\\s*([\\w.]+)\\s*\\}\\}/g;\n\nexport const getVariableValue = (\n  variables: Record<string, unknown>,\n  variableSchema: ReadonlyArray<DocumentVariable>,\n  name: string,\n): unknown => {\n  const schema = variableSchema.find((item) => item.name === name);\n  const value = variables[name];\n  if (value !== undefined && value !== null) return value;\n  return schema?.default;\n};\n\nexport const stringifyVariable = (value: unknown): string => {\n  if (value === undefined || value === null) return \"\";\n  if (value instanceof Date) return value.toISOString();\n  if (Array.isArray(value)) return value.join(\", \");\n  if (typeof value === \"object\") return JSON.stringify(value);\n  return String(value);\n};\n\nexport interface InterpolationResult {\n  readonly rendered: string;\n  /** Required variables that resolved to nothing (no value, no default). */\n  readonly missing: ReadonlySet<string>;\n}\n\nexport const interpolate = (\n  text: string,\n  variables: Record<string, unknown>,\n  variableSchema: ReadonlyArray<DocumentVariable>,\n): InterpolationResult => {\n  const missing = new Set<string>();\n  const substitute = (name: string): string => {\n    const value = getVariableValue(variables, variableSchema, name);\n    const schema = variableSchema.find((item) => item.name === name);\n    if ((value === undefined || value === null) && schema?.required) missing.add(name);\n    return stringifyVariable(value);\n  };\n  // One pass over the combined pattern: group 1 is the `${…}` name, group 2 the\n  // `{{…}}` name; exactly one is set per match. `replace` resets the shared\n  // pattern's lastIndex, so sharing it with `variableReferences` is safe.\n  const rendered = text.replace(\n    variableReferencePattern,\n    (_match, dollarName: string | undefined, braceName: string | undefined) =>\n      substitute(dollarName ?? braceName ?? \"\"),\n  );\n  return { rendered, missing };\n};\n\nexport const variableReferences = (text: string): Set<string> => {\n  const names = new Set<string>();\n  for (const match of text.matchAll(variableReferencePattern)) {\n    const name = match[1] ?? match[2];\n    if (name !== undefined && name !== \"\") names.add(name);\n  }\n  return names;\n};\n\nexport const addVariableReferences = (target: Set<string>, text: string): void => {\n  variableReferences(text).forEach((name) => target.add(name));\n};\n"],"mappings":";;AAWA,MAAM,iBAAiB,cAAsB,OAAO,OAAO,MAAM,OAAO,YAAY,SAAS,CAAC;AAE9F,MAAa,6BAA6B,OAAO,SAAS;CACxD;CACA;CACA;CACA;CACA;CACA;AACF,CAAC;;AAKD,MAAa,yBAAyB,OAAO,OAAO;CAClD,MAAM,cAAc,GAAG;CACvB,MAAM;CACN,UAAU,OAAO;CACjB,SAAS,OAAO,SAAS,OAAO,OAAO;CACvC,aAAa,OAAO,SAAS,cAAc,GAAG,CAAC;AACjD,CAAC;AAID,MAAa,2BAA2B;AAExC,MAAa,oBACX,WACA,gBACA,SACY;CACZ,MAAM,SAAS,eAAe,MAAM,SAAS,KAAK,SAAS,IAAI;CAC/D,MAAM,QAAQ,UAAU;CACxB,IAAI,UAAU,KAAA,KAAa,UAAU,MAAM,OAAO;CAClD,OAAO,QAAQ;AACjB;AAEA,MAAa,qBAAqB,UAA2B;CAC3D,IAAI,UAAU,KAAA,KAAa,UAAU,MAAM,OAAO;CAClD,IAAI,iBAAiB,MAAM,OAAO,MAAM,YAAY;CACpD,IAAI,MAAM,QAAQ,KAAK,GAAG,OAAO,MAAM,KAAK,IAAI;CAChD,IAAI,OAAO,UAAU,UAAU,OAAO,KAAK,UAAU,KAAK;CAC1D,OAAO,OAAO,KAAK;AACrB;AAQA,MAAa,eACX,MACA,WACA,mBACwB;CACxB,MAAM,0BAAU,IAAI,IAAY;CAChC,MAAM,cAAc,SAAyB;EAC3C,MAAM,QAAQ,iBAAiB,WAAW,gBAAgB,IAAI;EAC9D,MAAM,SAAS,eAAe,MAAM,SAAS,KAAK,SAAS,IAAI;EAC/D,KAAK,UAAU,KAAA,KAAa,UAAU,SAAS,QAAQ,UAAU,QAAQ,IAAI,IAAI;EACjF,OAAO,kBAAkB,KAAK;CAChC;CASA,OAAO;EAAE,UALQ,KAAK,QACpB,2BACC,QAAQ,YAAgC,cACvC,WAAW,cAAc,aAAa,EAAE,CAE5B;EAAG;CAAQ;AAC7B;AAEA,MAAa,sBAAsB,SAA8B;CAC/D,MAAM,wBAAQ,IAAI,IAAY;CAC9B,KAAK,MAAM,SAAS,KAAK,SAAS,wBAAwB,GAAG;EAC3D,MAAM,OAAO,MAAM,MAAM,MAAM;EAC/B,IAAI,SAAS,KAAA,KAAa,SAAS,IAAI,MAAM,IAAI,IAAI;CACvD;CACA,OAAO;AACT;AAEA,MAAa,yBAAyB,QAAqB,SAAuB;CAChF,mBAAmB,IAAI,CAAC,CAAC,SAAS,SAAS,OAAO,IAAI,IAAI,CAAC;AAC7D"}

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

@@ -0,0 +1,10 @@
+import { a as JsxResult, i as JSX, n as Fragment, t as Component } from "./jsx-runtime-fSxcvlx4.js";
+//#region src/jsx-dev-runtime.d.ts
+interface JsxDevProps {
+  readonly children?: unknown;
+  readonly [key: string]: unknown;
+}
+declare const jsxDEV: (type: Component<JsxDevProps> | typeof Fragment, props: JsxDevProps) => JsxResult;
+//#endregion
+export { Fragment, type JSX, jsxDEV };
+//# sourceMappingURL=jsx-dev-runtime.d.ts.map

package/dist/jsx-dev-runtime.js

@@ -0,0 +1,7 @@
+import { Fragment, jsx } from "./jsx-runtime.js";
+//#region src/jsx-dev-runtime.ts
+const jsxDEV = (type, props) => jsx(type, props);
+//#endregion
+export { Fragment, jsxDEV };
+
+//# sourceMappingURL=jsx-dev-runtime.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"jsx-dev-runtime.js","names":[],"sources":["../src/jsx-dev-runtime.ts"],"sourcesContent":["import type { Component } from \"./jsx-runtime\";\nimport { Fragment, jsx, type JsxResult } from \"./jsx-runtime\";\n\n// Development JSX runtime. The dev transform emits `jsxDEV(...)` with extra\n// debug arguments (key, isStaticChildren, source, self) that we don't need —\n// SML has no runtime reconciliation, only build-time construction. We forward to\n// the production `jsx`. Fragment + the JSX namespace re-export so tooling that\n// imports the dev runtime sees the same types.\n\nexport { Fragment } from \"./jsx-runtime\";\nexport type { JSX } from \"./jsx-runtime\";\n\ninterface JsxDevProps {\n  readonly children?: unknown;\n  readonly [key: string]: unknown;\n}\n\nexport const jsxDEV = (\n  type: Component<JsxDevProps> | typeof Fragment,\n  props: JsxDevProps,\n): JsxResult => jsx(type, props);\n"],"mappings":";;AAiBA,MAAa,UACX,MACA,UACc,IAAI,MAAM,KAAK"}

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

@@ -0,0 +1,57 @@
+import { T as SmlNode, m as ElementNode, n as Attribute } from "./ast-DAhnAvQN.js";
+import { s as VariableRef } from "./variables-3NGLpNTB.js";
+//#region src/jsx-runtime.d.ts
+/** A component is a plain function of its props that returns a draft node. */
+type Component<P> = (props: P) => SmlNode;
+/**
+ * What may appear in a component's `children`. Booleans/null/undefined are
+ * skipped (so `{cond && <X/>}` and `{cond ? <A/> : null}` are BUILD-TIME
+ * conditionals that evaluate away); strings/numbers become text; VariableRefs
+ * become `{{interpolation}}` nodes; arrays flatten; nested nodes nest. Anything
+ * else is a typed authoring error.
+ */
+type SmlChild = SmlNode | FragmentDraft | VariableRef<unknown> | string | number | boolean | null | undefined | ReadonlyArray<SmlChild>;
+type SmlChildren = SmlChild | ReadonlyArray<SmlChild>;
+/** Fragment children pass through un-wrapped — a Fragment is not an element. */
+interface FragmentDraft {
+  readonly kind: "fragment";
+  readonly children: ReadonlyArray<SmlNode>;
+}
+type JsxResult = SmlNode | FragmentDraft;
+/**
+ * Flattens and normalizes a component's raw `children` prop into AST child
+ * nodes. Fragments splice their children in; booleans/null/undefined drop out.
+ */
+declare const normalizeChildren: (children: unknown) => Array<SmlNode>;
+/**
+ * Builds an element draft from a tag, attribute list (already in authored
+ * order), and normalized children. Kept here so the runtime owns the AST shape;
+ * ./components maps typed props onto attributes and calls this.
+ */
+declare const elementDraft: (tag: ElementNode["tag"], attributes: ReadonlyArray<Attribute>, children: ReadonlyArray<SmlNode>) => ElementNode;
+interface JsxProps {
+  readonly children?: unknown;
+  readonly [key: string]: unknown;
+}
+/**
+ * The automatic-runtime entry point. `type` is always one of our typed
+ * component functions (or `Fragment`); we invoke it with its props. The JSX
+ * transform routes single-child elements here and multi-child elements to
+ * `jsxs` — behaviour is identical for us (components normalize their own
+ * children), so `jsxs` re-exports this.
+ */
+declare const jsx: (type: Component<JsxProps> | typeof Fragment, props: JsxProps) => JsxResult;
+declare const jsxs: (type: Component<JsxProps> | typeof Fragment, props: JsxProps) => JsxResult;
+/** Groups children without an element wrapper. Its children splice into the parent. */
+declare const Fragment: unique symbol;
+declare namespace JSX {
+  type Element = JsxResult;
+  type ElementType = Component<never> | typeof Fragment;
+  interface ElementChildrenAttribute {
+    readonly children: object;
+  }
+  type IntrinsicElements = Record<string, never>;
+}
+//#endregion
+export { JsxResult as a, elementDraft as c, normalizeChildren as d, JSX as i, jsx as l, Fragment as n, SmlChild as o, FragmentDraft as r, SmlChildren as s, Component as t, jsxs as u };
+//# sourceMappingURL=jsx-runtime-fSxcvlx4.d.ts.map

package/dist/jsx-runtime.d.ts

@@ -0,0 +1,2 @@
+import { a as JsxResult, c as elementDraft, d as normalizeChildren, i as JSX, l as jsx, n as Fragment, o as SmlChild, r as FragmentDraft, s as SmlChildren, t as Component, u as jsxs } from "./jsx-runtime-fSxcvlx4.js";
+export { Component, Fragment, FragmentDraft, JSX, JsxResult, SmlChild, SmlChildren, elementDraft, jsx, jsxs, normalizeChildren };

package/dist/jsx-runtime.js

@@ -0,0 +1,102 @@
+import { VARIABLE_REF, isVariableRef } from "./variables.js";
+import { Predicate } from "effect";
+//#region src/jsx-runtime.ts
+const PLACEHOLDER_SPAN = {
+	start: 0,
+	end: 0
+};
+const isFragmentDraft = (value) => Predicate.hasProperty(value, "kind") && value.kind === "fragment";
+const isSmlNode = (value) => {
+	if (!Predicate.hasProperty(value, "kind")) return false;
+	const kind = value.kind;
+	return kind === "element" || kind === "text" || kind === "interpolation";
+};
+const textNode = (value) => ({
+	kind: "text",
+	id: "",
+	value,
+	span: PLACEHOLDER_SPAN
+});
+const interpolationNode = (ref) => ({
+	kind: "interpolation",
+	id: "",
+	name: ref[VARIABLE_REF].path,
+	syntax: "curly",
+	span: PLACEHOLDER_SPAN
+});
+/**
+* Flattens and normalizes a component's raw `children` prop into AST child
+* nodes. Fragments splice their children in; booleans/null/undefined drop out.
+*/
+const normalizeChildren = (children) => {
+	const out = [];
+	const push = (child) => {
+		if (child === null || child === void 0 || typeof child === "boolean") return;
+		if (typeof child === "string") {
+			out.push(textNode(child));
+			return;
+		}
+		if (typeof child === "number") {
+			out.push(textNode(String(child)));
+			return;
+		}
+		if (Array.isArray(child)) {
+			for (const item of child) push(item);
+			return;
+		}
+		if (isVariableRef(child)) {
+			out.push(interpolationNode(child));
+			return;
+		}
+		if (isFragmentDraft(child)) {
+			for (const node of child.children) out.push(node);
+			return;
+		}
+		if (isSmlNode(child)) {
+			out.push(child);
+			return;
+		}
+		throw new TypeError(`invalid SML child: ${describe(child)} — children may be text, numbers, variables, elements, arrays of these, or false/null/undefined (which are skipped)`);
+	};
+	push(children);
+	return out;
+};
+const describe = (value) => {
+	if (typeof value === "function") return "a function (did you pass a component instead of an element?)";
+	if (typeof value === "object") return `an object (${JSON.stringify(value)})`;
+	return `${typeof value} (${JSON.stringify(value)})`;
+};
+/**
+* Builds an element draft from a tag, attribute list (already in authored
+* order), and normalized children. Kept here so the runtime owns the AST shape;
+* ./components maps typed props onto attributes and calls this.
+*/
+const elementDraft = (tag, attributes, children) => ({
+	kind: "element",
+	id: "",
+	tag,
+	attributes,
+	children,
+	span: PLACEHOLDER_SPAN
+});
+/**
+* The automatic-runtime entry point. `type` is always one of our typed
+* component functions (or `Fragment`); we invoke it with its props. The JSX
+* transform routes single-child elements here and multi-child elements to
+* `jsxs` — behaviour is identical for us (components normalize their own
+* children), so `jsxs` re-exports this.
+*/
+const jsx = (type, props) => {
+	if (type === Fragment) return {
+		kind: "fragment",
+		children: normalizeChildren(props.children)
+	};
+	return type(props);
+};
+const jsxs = jsx;
+/** Groups children without an element wrapper. Its children splice into the parent. */
+const Fragment = Symbol.for("@samva/markup/Fragment");
+//#endregion
+export { Fragment, elementDraft, jsx, jsxs, normalizeChildren };
+
+//# sourceMappingURL=jsx-runtime.js.map

package/dist/jsx-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsx-runtime.js","names":[],"sources":["../src/jsx-runtime.ts"],"sourcesContent":["import { Predicate } from \"effect\";\n\nimport type { Attribute, ElementNode, InterpolationNode, SmlNode, TextNode } from \"./ast\";\nimport { isVariableRef, VARIABLE_REF, type VariableRef } from \"./variables\";\n\n// Automatic-runtime JSX factory for the TSX authoring layer (design brief §7b).\n//\n// This is EVALUATION, not parsing: `template.tsx` runs at the user's build time,\n// its JSX transforms to jsx()/jsxs() calls, and those construct M1 AST drafts.\n// We never statically analyse TSX — any TypeScript that runs is accepted and the\n// OUTPUT is validated against the closed grammar (print → parse in renderTemplate).\n//\n// Drafts are real `SmlNode` shapes with placeholder id/span: the canonical path\n// is print → parse, so parse assigns the authoritative ids and spans and runs the\n// full content-model validation. Nothing here re-implements the grammar; the\n// typed components in ./components restrict what callers can construct, and the\n// parser is the backstop for hand-assembled or dynamically-built trees.\n\nconst PLACEHOLDER_SPAN = { start: 0, end: 0 } as const;\n\n/** A component is a plain function of its props that returns a draft node. */\nexport type Component<P> = (props: P) => SmlNode;\n\n/**\n * What may appear in a component's `children`. Booleans/null/undefined are\n * skipped (so `{cond && <X/>}` and `{cond ? <A/> : null}` are BUILD-TIME\n * conditionals that evaluate away); strings/numbers become text; VariableRefs\n * become `{{interpolation}}` nodes; arrays flatten; nested nodes nest. Anything\n * else is a typed authoring error.\n */\nexport type SmlChild =\n  | SmlNode\n  | FragmentDraft\n  | VariableRef<unknown>\n  | string\n  | number\n  | boolean\n  | null\n  | undefined\n  | ReadonlyArray<SmlChild>;\n\nexport type SmlChildren = SmlChild | ReadonlyArray<SmlChild>;\n\n/** Fragment children pass through un-wrapped — a Fragment is not an element. */\nexport interface FragmentDraft {\n  readonly kind: \"fragment\";\n  readonly children: ReadonlyArray<SmlNode>;\n}\n\nexport type JsxResult = SmlNode | FragmentDraft;\n\nconst isFragmentDraft = (value: unknown): value is FragmentDraft =>\n  Predicate.hasProperty(value, \"kind\") && value.kind === \"fragment\";\n\nconst isSmlNode = (value: unknown): value is SmlNode => {\n  if (!Predicate.hasProperty(value, \"kind\")) return false;\n  const kind = value.kind;\n  return kind === \"element\" || kind === \"text\" || kind === \"interpolation\";\n};\n\nconst textNode = (value: string): TextNode => ({\n  kind: \"text\",\n  id: \"\",\n  value,\n  span: PLACEHOLDER_SPAN,\n});\n\nconst interpolationNode = (ref: VariableRef<unknown>): InterpolationNode => ({\n  kind: \"interpolation\",\n  id: \"\",\n  name: ref[VARIABLE_REF].path,\n  // TSX authoring uses curly syntax exclusively; `${name}` is a source-only\n  // alternate the parser still accepts, never emitted from code.\n  syntax: \"curly\",\n  span: PLACEHOLDER_SPAN,\n});\n\n/**\n * Flattens and normalizes a component's raw `children` prop into AST child\n * nodes. Fragments splice their children in; booleans/null/undefined drop out.\n */\nexport const normalizeChildren = (children: unknown): Array<SmlNode> => {\n  const out: Array<SmlNode> = [];\n  const push = (child: unknown): void => {\n    if (child === null || child === undefined || typeof child === \"boolean\") return;\n    if (typeof child === \"string\") {\n      out.push(textNode(child));\n      return;\n    }\n    if (typeof child === \"number\") {\n      out.push(textNode(String(child)));\n      return;\n    }\n    if (Array.isArray(child)) {\n      for (const item of child) push(item);\n      return;\n    }\n    if (isVariableRef(child)) {\n      out.push(interpolationNode(child));\n      return;\n    }\n    if (isFragmentDraft(child)) {\n      for (const node of child.children) out.push(node);\n      return;\n    }\n    if (isSmlNode(child)) {\n      out.push(child);\n      return;\n    }\n    // oxlint-disable-next-line samva/no-try-catch-or-throw, samva/no-error-constructor -- User-build authoring boundary: this runs in the user's TSX build (not Effect domain); an invalid child is a programmer error that must fail their build loudly, not become a typed Effect failure.\n    throw new TypeError(\n      `invalid SML child: ${describe(child)} — children may be text, numbers, variables, elements, arrays of these, or false/null/undefined (which are skipped)`,\n    );\n  };\n  push(children);\n  return out;\n};\n\nconst describe = (value: unknown): string => {\n  if (typeof value === \"function\")\n    return \"a function (did you pass a component instead of an element?)\";\n  if (typeof value === \"object\") return `an object (${JSON.stringify(value)})`;\n  return `${typeof value} (${JSON.stringify(value)})`;\n};\n\n// ── Element draft builder (used by ./components) ────────────────────────────────\n\n/**\n * Builds an element draft from a tag, attribute list (already in authored\n * order), and normalized children. Kept here so the runtime owns the AST shape;\n * ./components maps typed props onto attributes and calls this.\n */\nexport const elementDraft = (\n  tag: ElementNode[\"tag\"],\n  attributes: ReadonlyArray<Attribute>,\n  children: ReadonlyArray<SmlNode>,\n): ElementNode => ({\n  kind: \"element\",\n  id: \"\",\n  tag,\n  attributes,\n  children,\n  span: PLACEHOLDER_SPAN,\n});\n\n// ── jsx / jsxs / Fragment (automatic runtime contract) ──────────────────────────\n\ninterface JsxProps {\n  readonly children?: unknown;\n  readonly [key: string]: unknown;\n}\n\n/**\n * The automatic-runtime entry point. `type` is always one of our typed\n * component functions (or `Fragment`); we invoke it with its props. The JSX\n * transform routes single-child elements here and multi-child elements to\n * `jsxs` — behaviour is identical for us (components normalize their own\n * children), so `jsxs` re-exports this.\n */\nexport const jsx = (type: Component<JsxProps> | typeof Fragment, props: JsxProps): JsxResult => {\n  if (type === Fragment) {\n    return { kind: \"fragment\", children: normalizeChildren(props.children) };\n  }\n  return (type as Component<JsxProps>)(props);\n};\n\nexport const jsxs = jsx;\n\n/** Groups children without an element wrapper. Its children splice into the parent. */\nexport const Fragment = Symbol.for(\"@samva/markup/Fragment\");\n\n// ── JSX namespace (automatic runtime contract) ──────────────────────────────────\n//\n// With `jsxImportSource: \"@samva/markup\"` the TSX transform resolves types from\n// this module's `JSX` namespace. Our vocabulary is all capitalized components\n// (functions from ./components), so there are no lowercase intrinsics — a `<div>`\n// simply has no component and fails to resolve, which is the closed grammar\n// enforced at the type level. Every element evaluates to an `SmlNode`.\n\nexport namespace JSX {\n  export type Element = JsxResult;\n  export type ElementType = Component<never> | typeof Fragment;\n  export interface ElementChildrenAttribute {\n    readonly children: object;\n  }\n  // No lowercase host elements: the grammar is closed and component-only, so\n  // `<div>` has no matching intrinsic and fails to type-resolve.\n  export type IntrinsicElements = Record<string, never>;\n}\n"],"mappings":";;;AAkBA,MAAM,mBAAmB;CAAE,OAAO;CAAG,KAAK;AAAE;AAiC5C,MAAM,mBAAmB,UACvB,UAAU,YAAY,OAAO,MAAM,KAAK,MAAM,SAAS;AAEzD,MAAM,aAAa,UAAqC;CACtD,IAAI,CAAC,UAAU,YAAY,OAAO,MAAM,GAAG,OAAO;CAClD,MAAM,OAAO,MAAM;CACnB,OAAO,SAAS,aAAa,SAAS,UAAU,SAAS;AAC3D;AAEA,MAAM,YAAY,WAA6B;CAC7C,MAAM;CACN,IAAI;CACJ;CACA,MAAM;AACR;AAEA,MAAM,qBAAqB,SAAkD;CAC3E,MAAM;CACN,IAAI;CACJ,MAAM,IAAI,aAAa,CAAC;CAGxB,QAAQ;CACR,MAAM;AACR;;;;;AAMA,MAAa,qBAAqB,aAAsC;CACtE,MAAM,MAAsB,CAAC;CAC7B,MAAM,QAAQ,UAAyB;EACrC,IAAI,UAAU,QAAQ,UAAU,KAAA,KAAa,OAAO,UAAU,WAAW;EACzE,IAAI,OAAO,UAAU,UAAU;GAC7B,IAAI,KAAK,SAAS,KAAK,CAAC;GACxB;EACF;EACA,IAAI,OAAO,UAAU,UAAU;GAC7B,IAAI,KAAK,SAAS,OAAO,KAAK,CAAC,CAAC;GAChC;EACF;EACA,IAAI,MAAM,QAAQ,KAAK,GAAG;GACxB,KAAK,MAAM,QAAQ,OAAO,KAAK,IAAI;GACnC;EACF;EACA,IAAI,cAAc,KAAK,GAAG;GACxB,IAAI,KAAK,kBAAkB,KAAK,CAAC;GACjC;EACF;EACA,IAAI,gBAAgB,KAAK,GAAG;GAC1B,KAAK,MAAM,QAAQ,MAAM,UAAU,IAAI,KAAK,IAAI;GAChD;EACF;EACA,IAAI,UAAU,KAAK,GAAG;GACpB,IAAI,KAAK,KAAK;GACd;EACF;EAEA,MAAM,IAAI,UACR,sBAAsB,SAAS,KAAK,EAAE,oHACxC;CACF;CACA,KAAK,QAAQ;CACb,OAAO;AACT;AAEA,MAAM,YAAY,UAA2B;CAC3C,IAAI,OAAO,UAAU,YACnB,OAAO;CACT,IAAI,OAAO,UAAU,UAAU,OAAO,cAAc,KAAK,UAAU,KAAK,EAAE;CAC1E,OAAO,GAAG,OAAO,MAAM,IAAI,KAAK,UAAU,KAAK,EAAE;AACnD;;;;;;AASA,MAAa,gBACX,KACA,YACA,cACiB;CACjB,MAAM;CACN,IAAI;CACJ;CACA;CACA;CACA,MAAM;AACR;;;;;;;;AAgBA,MAAa,OAAO,MAA6C,UAA+B;CAC9F,IAAI,SAAS,UACX,OAAO;EAAE,MAAM;EAAY,UAAU,kBAAkB,MAAM,QAAQ;CAAE;CAEzE,OAAQ,KAA6B,KAAK;AAC5C;AAEA,MAAa,OAAO;;AAGpB,MAAa,WAAW,OAAO,IAAI,wBAAwB"}

package/dist/lexer.d.ts

@@ -0,0 +1,60 @@
+//#region src/lexer.d.ts
+declare const TokenKind: {
+  readonly EndOfFile: 0;
+  /** `<` opening a start tag (text mode). */
+  readonly LessThan: 1;
+  /** `</` opening a close tag (text mode). */
+  readonly LessThanSlash: 2;
+  readonly GreaterThan: 3;
+  readonly SlashGreaterThan: 4;
+  readonly Identifier: 5;
+  readonly Equals: 6;
+  /** Quoted attribute value; getStringValue decodes entities. */
+  readonly String: 7;
+  readonly OpenBrace: 8;
+  readonly CloseBrace: 9;
+  /** Unsigned integer inside a brace attribute value. */
+  readonly Number: 10;
+  /** Raw text run; getTextValue decodes entities. */
+  readonly Text: 11;
+  /** `{{name}}` or `${name}`; name/syntax carried on the token. */
+  readonly Interpolation: 12;
+  /** Lexically invalid input; error carried on the token. */
+  readonly Unknown: 13;
+};
+type TokenKind = (typeof TokenKind)[keyof typeof TokenKind];
+interface TokenError {
+  readonly code: string;
+  readonly message: string;
+}
+interface Token {
+  readonly kind: TokenKind;
+  readonly start: number;
+  readonly end: number;
+  /** Interpolation only. */
+  readonly name?: string | undefined;
+  /** Interpolation only. */
+  readonly syntax?: "curly" | "dollar" | undefined;
+  /** Unknown only. */
+  readonly error?: TokenError | undefined;
+}
+/** Decodes entities in text that already passed `scanEntity` validation. */
+declare const decodeEntities: (raw: string) => string;
+interface Lexer {
+  /** Current scan position (start of the next token). */
+  readonly position: () => number;
+  /** Scan one token in text mode (between tags). */
+  readonly scanTextToken: () => Token;
+  /** Scan one token in tag mode (inside `<...>`), skipping whitespace. */
+  readonly scanTagToken: () => Token;
+  /** Lazy raw source slice for a token. */
+  readonly getText: (token: Token) => string;
+  /** Entity-decoded value of a Text token. */
+  readonly getTextValue: (token: Token) => string;
+  /** Entity-decoded contents of a String token (without quotes). */
+  readonly getStringValue: (token: Token) => string;
+}
+declare const createLexer: (source: string) => Lexer;
+//#endregion
+export { Lexer, Token, TokenError, TokenKind, createLexer, decodeEntities };
+//# sourceMappingURL=lexer.d.ts.map

package/dist/lexer.js

@@ -0,0 +1,269 @@
+//#region src/lexer.ts
+const CHAR_TAB = 9;
+const CHAR_LINE_FEED = 10;
+const CHAR_CARRIAGE_RETURN = 13;
+const CHAR_SPACE = 32;
+const CHAR_BANG = 33;
+const CHAR_DOUBLE_QUOTE = 34;
+const CHAR_HASH = 35;
+const CHAR_DOLLAR = 36;
+const CHAR_AMPERSAND = 38;
+const CHAR_SINGLE_QUOTE = 39;
+const CHAR_SLASH = 47;
+const CHAR_SEMICOLON = 59;
+const CHAR_LESS_THAN = 60;
+const CHAR_EQUALS = 61;
+const CHAR_GREATER_THAN = 62;
+const CHAR_OPEN_BRACE = 123;
+const CHAR_CLOSE_BRACE = 125;
+const CHAR_DOT = 46;
+const CHAR_UNDERSCORE = 95;
+const CHAR_0 = 48;
+const CHAR_9 = 57;
+const CHAR_UPPER_A = 65;
+const CHAR_UPPER_Z = 90;
+const CHAR_LOWER_A = 97;
+const CHAR_LOWER_X = 120;
+const CHAR_LOWER_Z = 122;
+const TokenKind = {
+	EndOfFile: 0,
+	/** `<` opening a start tag (text mode). */
+	LessThan: 1,
+	/** `</` opening a close tag (text mode). */
+	LessThanSlash: 2,
+	GreaterThan: 3,
+	SlashGreaterThan: 4,
+	Identifier: 5,
+	Equals: 6,
+	/** Quoted attribute value; getStringValue decodes entities. */
+	String: 7,
+	OpenBrace: 8,
+	CloseBrace: 9,
+	/** Unsigned integer inside a brace attribute value. */
+	Number: 10,
+	/** Raw text run; getTextValue decodes entities. */
+	Text: 11,
+	/** `{{name}}` or `${name}`; name/syntax carried on the token. */
+	Interpolation: 12,
+	/** Lexically invalid input; error carried on the token. */
+	Unknown: 13
+};
+const isWhitespace = (code) => code === CHAR_SPACE || code === CHAR_TAB || code === CHAR_LINE_FEED || code === CHAR_CARRIAGE_RETURN;
+const isDigit = (code) => code >= CHAR_0 && code <= CHAR_9;
+const isLetter = (code) => code >= CHAR_UPPER_A && code <= CHAR_UPPER_Z || code >= CHAR_LOWER_A && code <= CHAR_LOWER_Z;
+const isNameChar = (code) => isLetter(code) || isDigit(code) || code === CHAR_UNDERSCORE || code === CHAR_DOT;
+const NAMED_ENTITIES = {
+	amp: "&",
+	lt: "<",
+	gt: ">",
+	quot: "\"",
+	apos: "'",
+	nbsp: "\xA0"
+};
+/**
+* Validates the entity starting at `offset` (which points at `&`).
+* Returns the end offset (past `;`) or -1 when malformed.
+*/
+const scanEntity = (source, offset) => {
+	let index = offset + 1;
+	if (source.charCodeAt(index) === CHAR_HASH) {
+		index++;
+		const hex = source.charCodeAt(index) === CHAR_LOWER_X;
+		if (hex) index++;
+		const digitsStart = index;
+		while (index < source.length) {
+			const code = source.charCodeAt(index);
+			if (!(isDigit(code) || hex && (code >= 97 && code <= 102 || code >= 65 && code <= 70))) break;
+			index++;
+		}
+		if (index === digitsStart) return -1;
+		return source.charCodeAt(index) === CHAR_SEMICOLON ? index + 1 : -1;
+	}
+	const nameStart = index;
+	while (index < source.length && isLetter(source.charCodeAt(index))) index++;
+	if (!(source.slice(nameStart, index) in NAMED_ENTITIES)) return -1;
+	return source.charCodeAt(index) === CHAR_SEMICOLON ? index + 1 : -1;
+};
+/** Decodes entities in text that already passed `scanEntity` validation. */
+const decodeEntities = (raw) => {
+	if (!raw.includes("&")) return raw;
+	let result = "";
+	let index = 0;
+	while (index < raw.length) {
+		const ampersand = raw.indexOf("&", index);
+		if (ampersand === -1) {
+			result += raw.slice(index);
+			break;
+		}
+		result += raw.slice(index, ampersand);
+		const semicolon = raw.indexOf(";", ampersand);
+		if (semicolon === -1) {
+			result += raw.slice(ampersand);
+			break;
+		}
+		const body = raw.slice(ampersand + 1, semicolon);
+		if (body.startsWith("#x") || body.startsWith("#X")) result += String.fromCodePoint(Number.parseInt(body.slice(2), 16));
+		else if (body.startsWith("#")) result += String.fromCodePoint(Number.parseInt(body.slice(1), 10));
+		else result += NAMED_ENTITIES[body];
+		index = semicolon + 1;
+	}
+	return result;
+};
+const createLexer = (source) => {
+	let position = 0;
+	const length = source.length;
+	const token = (kind, start, extra) => {
+		return {
+			kind,
+			start,
+			end: position,
+			...extra
+		};
+	};
+	const unknown = (start, code, message) => {
+		if (position === start) position = Math.min(start + 1, length);
+		return token(TokenKind.Unknown, start, { error: {
+			code,
+			message
+		} });
+	};
+	const scanInterpolation = (start, syntax) => {
+		position = start + 2;
+		while (position < length && isWhitespace(source.charCodeAt(position))) position++;
+		if (syntax === "dollar" && source.charCodeAt(position) === CHAR_SLASH) position++;
+		const nameStart = position;
+		while (position < length && isNameChar(source.charCodeAt(position))) position++;
+		const name = source.slice(nameStart, position);
+		while (position < length && isWhitespace(source.charCodeAt(position))) position++;
+		const closed = syntax === "curly" ? source.charCodeAt(position) === CHAR_CLOSE_BRACE && source.charCodeAt(position + 1) === CHAR_CLOSE_BRACE : source.charCodeAt(position) === CHAR_CLOSE_BRACE;
+		if (name.length === 0 || !closed) {
+			position = start;
+			return unknown(start, "invalid-interpolation", `malformed interpolation — write ${syntax === "curly" ? "{{variableName}}" : "${variableName}"} using letters, digits, underscore, or dot`);
+		}
+		position += syntax === "curly" ? 2 : 1;
+		return token(TokenKind.Interpolation, start, {
+			name,
+			syntax
+		});
+	};
+	const scanTextToken = () => {
+		const start = position;
+		if (position >= length) return token(TokenKind.EndOfFile, start);
+		const first = source.charCodeAt(position);
+		if (first === CHAR_LESS_THAN) {
+			const next = source.charCodeAt(position + 1);
+			if (next === CHAR_SLASH) {
+				position += 2;
+				return token(TokenKind.LessThanSlash, start);
+			}
+			if (isLetter(next)) {
+				position += 1;
+				return token(TokenKind.LessThan, start);
+			}
+			if (next === CHAR_BANG) return unknown(start, "comment-not-supported", source.startsWith("<!--", position) ? "comments are not part of SML — remove the <!-- ... --> block" : "unexpected <! — SML has no doctype or declaration syntax; remove it");
+			return unknown(start, "stray-angle-bracket", "stray < in text — escape it as &lt;");
+		}
+		if (first === CHAR_OPEN_BRACE && source.charCodeAt(position + 1) === CHAR_OPEN_BRACE) return scanInterpolation(start, "curly");
+		if (first === CHAR_DOLLAR && source.charCodeAt(position + 1) === CHAR_OPEN_BRACE) return scanInterpolation(start, "dollar");
+		while (position < length) {
+			const code = source.charCodeAt(position);
+			if (code === CHAR_LESS_THAN) break;
+			if (code === CHAR_OPEN_BRACE && source.charCodeAt(position + 1) === CHAR_OPEN_BRACE) break;
+			if (code === CHAR_DOLLAR && source.charCodeAt(position + 1) === CHAR_OPEN_BRACE) break;
+			if (code === CHAR_AMPERSAND) {
+				const entityEnd = scanEntity(source, position);
+				if (entityEnd === -1) {
+					if (position > start) return token(TokenKind.Text, start);
+					return unknown(start, "bare-ampersand", "bare & in text — escape it as &amp; (or use a supported entity like &lt;)");
+				}
+				position = entityEnd;
+				continue;
+			}
+			position++;
+		}
+		return token(TokenKind.Text, start);
+	};
+	const scanTagToken = () => {
+		while (position < length && isWhitespace(source.charCodeAt(position))) position++;
+		const start = position;
+		if (position >= length) return token(TokenKind.EndOfFile, start);
+		const code = source.charCodeAt(position);
+		switch (code) {
+			case CHAR_GREATER_THAN:
+				position++;
+				return token(TokenKind.GreaterThan, start);
+			case CHAR_SLASH:
+				if (source.charCodeAt(position + 1) === CHAR_GREATER_THAN) {
+					position += 2;
+					return token(TokenKind.SlashGreaterThan, start);
+				}
+				return unknown(start, "unexpected-character", "unexpected / inside tag — write /> to self-close");
+			case CHAR_EQUALS:
+				position++;
+				return token(TokenKind.Equals, start);
+			case CHAR_OPEN_BRACE:
+				position++;
+				return token(TokenKind.OpenBrace, start);
+			case CHAR_CLOSE_BRACE:
+				position++;
+				return token(TokenKind.CloseBrace, start);
+			case CHAR_DOUBLE_QUOTE:
+			case CHAR_SINGLE_QUOTE:
+				position++;
+				while (position < length) {
+					const current = source.charCodeAt(position);
+					if (current === code) break;
+					if (current === CHAR_AMPERSAND) {
+						const entityEnd = scanEntity(source, position);
+						if (entityEnd === -1) return unknown(position, "bare-ampersand", "bare & in attribute value — escape it as &amp;");
+						position = entityEnd;
+						continue;
+					}
+					if (current === CHAR_LESS_THAN || current === CHAR_LINE_FEED) break;
+					position++;
+				}
+				if (source.charCodeAt(position) !== code) {
+					const quote = String.fromCharCode(code);
+					return {
+						kind: TokenKind.Unknown,
+						start,
+						end: position,
+						error: {
+							code: "unterminated-string",
+							message: `unterminated attribute value — add a closing ${quote}`
+						}
+					};
+				}
+				position++;
+				return token(TokenKind.String, start);
+			default:
+				if (isLetter(code)) {
+					position++;
+					while (position < length) {
+						const current = source.charCodeAt(position);
+						if (!isLetter(current) && !isDigit(current)) break;
+						position++;
+					}
+					return token(TokenKind.Identifier, start);
+				}
+				if (isDigit(code)) {
+					position++;
+					while (position < length && isDigit(source.charCodeAt(position))) position++;
+					return token(TokenKind.Number, start);
+				}
+				return unknown(start, "unexpected-character", `unexpected character ${JSON.stringify(String.fromCharCode(code))} inside tag`);
+		}
+	};
+	return {
+		position: () => position,
+		scanTextToken,
+		scanTagToken,
+		getText: (t) => source.slice(t.start, t.end),
+		getTextValue: (t) => decodeEntities(source.slice(t.start, t.end)),
+		getStringValue: (t) => decodeEntities(source.slice(t.start + 1, t.end - 1))
+	};
+};
+//#endregion
+export { TokenKind, createLexer, decodeEntities };
+
+//# sourceMappingURL=lexer.js.map