@samva/markup 0.7.0 → 0.9.0

package/AGENTS.md

@@ -1,35 +1,100 @@
 # @samva/markup agent guide
 
-`@samva/markup` is the authoring language and compiler for Samva templates. Email templates are
-TSX modules that default-export a `defineEmail` definition and render through a JSX runtime that
-lowers to email-safe HTML and plain text. SMS and WhatsApp templates use the structured SML runtime.
-The package is plain TypeScript with no application runtime; the local editor, project builds, and
-exports live in `@samva/vite`.
+`@samva/markup` is the authoring language and compiler for Samva templates. A template is one TSX
+file in a static profile that default-exports `defineTemplate`: ordinary JSX, HTML and Tailwind that
+a compiler reads without running. The compiler produces a versioned JSON IR, and a pure renderer
+turns the IR and an input into subject, preheader, HTML and text, so nothing executes at send time.
+A body that would compute over its input is a diagnostic, not a second mode: compute the value in
+the caller and send it in the payload. The package is plain TypeScript with no application runtime;
+the local editor, project builds, and exports live in `@samva/vite`.
 
 ## Entry points
 
-- `@samva/markup/template` — `defineEmail`, `TemplateDefinition`, `TemplateInput`, and
+- `@samva/markup` — `defineTemplate({ id, schema, fixtures, locale?, email?, sms?, whatsapp? })`,
+  `TemplateInput`, and `TEMPLATE_ID_PATTERN` (lowercase kebab-case, the rule the CLI and API slugs
+  share). `email` is `{ subject, preheader?, body }`; each is a function of the validated input.
+- `@samva/markup/static` — `compileTemplate`, which reads a project's files and returns the IR,
+  the fixtures, the assets and the diagnostics; `checkTemplateCompatibility` checks each fixture
+  against the client matrix and locates findings at source. It needs the optional peers Babel,
+  Tailwind, css-tree and caniemail.
+  `checkStaticProfile(source | files, entry?)` is the synchronous structural check: it runs the
+  compiler's lowering without Tailwind, a brand or the files an import names, and returns only
+  findings the source itself owns. `introducedProfileErrors(before, after)` is what a visual edit
+  is refused on.
+- `@samva/markup/source-edit` — the code transforms behind visual edits (`inspectSourceElement`,
+  `literalReplacement`, `expressionReplacement`, `classNameEdit`, `structuralReplacements`,
+  `applySourceReplacements` with a `ProfileGuard`). Browser-safe: Babel parser only.
+- `@samva/markup/channel-edit` — form reads and exact source edits for the `sms` and `whatsapp`
+  channel bodies (`readSmsChannel`, `editSmsChannel`, `readWhatsAppChannel`,
+  `editWhatsAppChannel`). Text between a body's expressions is editable; an expression,
+  conditional or element is a locked segment that no edit touches. Each edit is a list of
+  `SourceReplacement`s for `applySourceReplacements`. Browser-safe: Babel parser only.
+- `@samva/markup/render-ir` — `renderIr(ir, input, { locale, timeZone })`, plus `renderIrSms` and
+  `renderIrWhatsApp`. Dependency-free and the send-time security boundary. `@samva/markup/ir` holds
+  the IR types and `SML_IR_VERSION`.
+- `@samva/markup/fmt` — `fmt.money`, `number`, `date`, `time`, `plural` and `list`: the only
+  functions a body may call.
+- `@samva/markup/sms` and `@samva/markup/whatsapp` — the channel components (`Sms`; `WhatsApp` with
+  `WhatsApp.Header`, `Body`, `Footer`, `Buttons`, `UrlButton`, `QuickReplyButton`, `PhoneButton`,
+  `CopyCodeButton`). `whatsappTemplate` derives Meta's positional `{{n}}` text.
+- `@samva/markup/template` — `defineTemplate`, `SmlTemplate`, `TemplateInput`, and
   `TEMPLATE_NAME_PATTERN`.
+- `@samva/markup/preview` — `renderIrPreview(ir, input)`: the render an editor shows, with an
+  instance path (`INSTANCE_PATH_ATTRIBUTE`) stamped on every element and the `selections` that map
+  each one to the span of TSX that produced it.
 - `@samva/markup/email` — the JSX runtime. Set `jsxImportSource: "@samva/markup/email"` for email
   entries.
 - `@samva/markup/email/components` — email primitives (`Email`, `Section`, `Columns`, `Button`,
   and the rest of its exports). They generate table layout and classic-Outlook fallbacks.
-- `@samva/markup/email/render` — `renderEmail(template, data)`, which validates input and returns
-  subject, preheader, HTML, text, and the derived tree.
+- `@samva/markup/email/render` — `compileEmail(tree)` and `renderEmailContent`, which lower a
+  derived email tree to HTML and text.
 - `@samva/markup/email/diagnostics` — `EmailDiagnostic` and `EmailCompileError`.
+- `@samva/markup/email/assets` — `isAssetPath` and `ASSET_CONTENT_TYPES`: which imported files
+  become content-addressed assets, without loading the compiler.
 - `@samva/markup/input-schema` — `inputSchema`, which turns any Standard JSON Schema into the
   portable JSON Schema and validator a template's input is checked against.
-- `@samva/markup/compiler` — `compileEmailProject`, the bundler-agnostic compile step. It imports no
-  Vite, esbuild, or Node builtins, so it runs in any JavaScript host.
-- `jsxImportSource: "@samva/markup"` and `@samva/markup/components` — the structured SMS and
-  WhatsApp runtime and components. `parseSml` (`@samva/markup/parser`) and `compileSml` /
-  `compileSource` (`@samva/markup/compile`) work on SML source.
+- `@samva/markup/compiler` — the compiler's building blocks (`transformProject`, Tailwind, the
+  cascade, diagnostics). It imports no Vite, esbuild, or Node builtins, so it runs in any
+  JavaScript host.
+- `samva:brand` — `BrandLogo` (light logo, swapped for the dark one where the client honors dark
+  mode) and `BrandFooter` (company, postal address, social links and the unsubscribe row the send
+  path fills). The compiler binds them to the brand the build resolves; add
+  `"types": ["@samva/markup/samva-brand"]` to the project's tsconfig for `tsc`. In `theme.css`,
+  `@import "samva:brand";` layers the brand theme; `samva:brand/<slug>` names one brand.
 
-The package's `generated/` directory ships the SML and email language references and agent
-contracts; read those before authoring. Import only subpaths declared in `package.json` `exports`.
+The package ships what an agent needs to author without this repository:
+
+- `@samva/markup/contract.json` (`generated/contract.json`) — components with their props, the
+  static-profile forms and the forms it refuses, formatters, HTML elements, channel specs and every
+  diagnostic code with its fix. `generated/reference.md` renders the same contract for reading.
+  `bun run codegen:contract` writes both from the modules that own each fact (component and `Fmt`
+  interfaces, `PROFILE_FORMS`, `DIAGNOSTIC_CODES`, the element table), and a test fails when they
+  drift.
+- `skills/sml/SKILL.md` — the `sml` skill: the write, check, render, look, repair loop, the static
+  profile and the data rules, for an agent that edits a template project.
+
+Read the contract before authoring. Import only subpaths declared in `package.json` `exports`.
 
 ## How you hurt yourself here
 
+- **Computing in a body.** A body is read, not run. A call other than `fmt.*` and `.map`, a
+  statement (`const`, `if`, a loop), an import outside `@samva/markup` and the project, a hook, an
+  event handler and `dangerouslySetInnerHTML` are each a diagnostic with a code, a location and a
+  fix. Compute the value in the caller and send it in the payload. There is no escape hatch.
+- **Chunking or counting in a body.** `items.reduce`, index arithmetic and `filter` helpers are
+  calls the profile refuses. Use `<Columns each={list} per={n}>{(item) => <Column … />}</Columns>`
+  for a grid and `.filter(condition)` before `.map` or `.length`; the condition is a `&&` / `?:`
+  condition over the item.
+- **Building a class name at run time.** Tailwind reads literal classes. `className={`text-${size}`}`
+  is `dynamic-class`; choose between literal lists instead: `input.vip ? "bg-amber-100" : "bg-white"`.
+- **Reading an optional field unguarded.** Binding `input.trackingUrl` outside
+  `input.trackingUrl && …` is `unguarded-optional`; a misspelled field is `unknown-field` with the
+  nearest match; a fixture that stopped matching the schema is `fixture-invalid`.
+- **Reporting a finding without a registry entry.** `Findings.add` and the lowerer accept only
+  codes in `DIAGNOSTIC_CODES` (`src/diagnostic-codes.ts`), which holds each code's meaning and fix.
+  Add the entry with the code; the contract and the docs read it.
+- **Putting the subject or preheader on `<Email>`.** They belong to the channel (`email.subject`,
+  `email.preheader`); `<Email>` has no `preheader` prop.
 - **Passing a string where you want markup.** Nothing an author passes as a string becomes markup;
   strings render as escaped text. There is no raw-HTML escape hatch: compatibility markup comes only
   from the email primitives.
@@ -38,15 +103,15 @@ contracts; read those before authoring. Import only subpaths declared in `packag
   unsupported element or attribute fails at typecheck and again at compile with a source location.
 - **Naming a template or fixture like a path.** A template id and a fixture key are both written
   into file paths, so each must match `TEMPLATE_NAME_PATTERN`, one plain path segment.
-  `defineEmail` throws a `TypeError` where the name is declared. Code that builds a path from these
+  `defineTemplate` throws a `TypeError` where the name is declared. Code that builds a path from these
   names imports the pattern instead of restating it.
-- **Reading the clock or randomness in a template.** Samva's hosted render has no ambient clock and
-  no entropy source: reading the current instant or a random value there throws unless the
-  definition declares the fixed value in its `runtime` (`TemplateRuntime`). A local render does not
-  enforce this, so a template that reads `Date.now()` can pass locally and fail once published. Take
-  times from validated input, or declare them.
-- **Treating `renderEmail` as a sandbox.** It executes the template's TypeScript in the calling
-  process. Run untrusted template source in an isolated host.
+- **Declaring a webfont as if every client loads it.** A project font is an ordinary `@font-face`
+  in the project's CSS (usually `theme.css`) whose `src` is a `.woff2` file in the project, named
+  by a path relative to that stylesheet; the compiler serves it as a content-addressed asset and
+  hides the rule from classic Outlook. Gmail and Outlook never load it, so a `font-family` stack
+  that names a project font must end in a generic (`sans-serif`, `serif`, `monospace`) or the
+  render fails with `email-font-fallback`. Only WOFF2 is accepted; an `https:` `src` stays an
+  external reference.
 - **Expecting the schema library to do the validation.** A template's input schema is converted to
   a portable JSON Schema and validated by that document, not by the library that produced it. A
   refinement that the converter cannot export is refused, and defaults are never inserted or values
@@ -54,27 +119,29 @@ contracts; read those before authoring. Import only subpaths declared in `packag
 
 ## Rules
 
-- **Email entries default-export a `defineEmail` definition** from a `.tsx` file. The definition
-  owns a stable, project-unique `id`, an input schema, named fixtures, and a synchronous `render`
-  that receives the validated JSON input unchanged. Helper modules are ordinary imports, not
-  catalog entries.
-- **Email templates have no textual SML form.** The derived semantic tree lowers directly to HTML
-  and text through `@samva/markup/email/render`; SML is the SMS and WhatsApp language.
-- **Structured SML is a closed grammar.** `parseSml` and `compileSml` reject anything outside it
-  rather than passing it through.
-- **Failures are typed.** The SML surface returns a better-result `Result`; branch with
-  `Result.isOk` / `Result.isErr` and discriminate the `TaggedError` (`SmlParseError`,
-  `SmlCompileError`) by `_tag`. Email compilation reports `EmailDiagnostic` values: errors throw
-  `EmailCompileError`, warnings ride back on the render result. A declaration the compiler cannot
+- **Email entries default-export `defineTemplate`** from a `.tsx` file. The definition owns a
+  stable, project-unique kebab-case `id`, an input schema, at least one fixture, and one body per
+  channel. Helper modules are ordinary imports, not catalog entries; a partial is a function from
+  props (and `children`) to JSX that the compiler inlines. A fixture is data: literals, constants
+  and imported assets.
+- **The IR is the artifact.** Rendering is a pure function of the IR and the input. The renderer
+  escapes per context, applies the serializer's URL and style rules to every bound value, and
+  rejects unsafe input rather than sanitizing it.
+- **Failures are typed.** Compilation reports diagnostic values with a code, a location and a fix:
+  `compileTemplate` returns them beside the IR, and an error finding leaves no IR. A declaration the compiler cannot
   accept at all, such as an invalid name or a nonportable input schema, throws a `TypeError`.
 - **Data models are plain types.** Markup's data models are TypeScript types, not schema
   declarations, so there is no schema library to adopt to consume them. Unions discriminate on
-  `type` (an `EmailNode`, an `SmlOp`); only error classes carry `_tag`. The input schema is the one
+  `type`; only error classes carry `_tag`. The input schema is the one
   place a Standard Schema is accepted, and which library produces it is yours to choose.
 
 ## Proving your setup
 
 - `tsc --noEmit` over the template project catches unsupported elements, attributes, and props.
+- `compileTemplate` reports every static-profile, binding and fixture finding with a source
+  location, and `renderIr(compiled.ir, fixture)` proves one fixture's output without executing the
+  template.
 - `samva templates check` (from `@samva/cli`) compiles every entry and renders every fixture,
   reporting findings with source locations.
-- `renderEmail(template, fixture)` in a unit test proves one template's output without a build.
+- `renderIrPreview(compiled.ir, fixture)` returns the same document with the source spans an editor
+  selects by.

package/README.md

@@ -6,59 +6,195 @@ directly for TSX templates or together with `@samva/vite` for the visual editor
 ## Install
 
 ```sh
-npm install --save-dev @samva/markup @samva/vite vite
+npm install --save-dev @samva/markup
 ```
 
-Configure TypeScript with `jsx: "react-jsx"` and
-`jsxImportSource: "@samva/markup/email"`. Install `effect` for this schema example
-(or use a Zod 4 schema). Email entries use `.tsx` and default-export a definition:
+Configure TypeScript with `jsx: "react-jsx"` and `jsxImportSource: "@samva/markup/email"`. A
+template is one `.tsx` file that default-exports `defineTemplate`:
 
 ```tsx
-/** @jsxImportSource @samva/markup/email */
-import { Schema } from "effect";
-import { Email, Section } from "@samva/markup/email/components";
-import { defineEmail } from "@samva/markup/template";
-
-export default defineEmail({
-  id: "welcome",
-  schema: Schema.toStandardJSONSchemaV1(
-    Schema.Struct({ firstName: Schema.String, items: Schema.Array(Schema.String) }),
-  ),
-  fixtures: { basic: { firstName: "Ada", items: ["Your first project"] } },
-  render: (input) => ({
-    subject: `Welcome, ${input.firstName}`,
-    preheader: "Your account is ready",
-    body: (
+import { defineTemplate } from "@samva/markup";
+import { Button, Email, Section } from "@samva/markup/email/components";
+import { fmt } from "@samva/markup/fmt";
+import { jsonSchema } from "@samva/markup/input-schema";
+
+import { OrderRow } from "../partials/order-row";
+
+export default defineTemplate({
+  id: "order-shipped",
+  schema: jsonSchema<{
+    name: string;
+    orderId: string;
+    currency: string;
+    total: number;
+    items: { title: string; qty: number; price: number }[];
+    trackingUrl?: string;
+  }>({
+    type: "object",
+    properties: {
+      name: { type: "string" },
+      orderId: { type: "string" },
+      currency: { type: "string" },
+      total: { type: "number" },
+      items: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            title: { type: "string" },
+            qty: { type: "number" },
+            price: { type: "number" },
+          },
+          required: ["title", "qty", "price"],
+          additionalProperties: false,
+        },
+      },
+      trackingUrl: { type: "string" },
+    },
+    required: ["name", "orderId", "currency", "total", "items"],
+    additionalProperties: false,
+  }),
+  fixtures: {
+    default: {
+      name: "Ada",
+      orderId: "A-1042",
+      currency: "USD",
+      total: 84,
+      items: [{ title: "Linen shirt", qty: 2, price: 42 }],
+      trackingUrl: "https://track.example.com/A-1042",
+    },
+    "no-tracking": {
+      name: "Ada",
+      orderId: "A-1042",
+      currency: "USD",
+      total: 84,
+      items: [{ title: "Linen shirt", qty: 2, price: 42 }],
+    },
+  },
+  email: {
+    subject: (input) => `Order ${input.orderId} is on its way`,
+    preheader: (input) => `${input.items.length} items, ${fmt.money(input.total, input.currency)}`,
+    body: (input) => (
       <Email>
-        <Section>
-          <h1>Welcome, {input.firstName}</h1>
-          {input.items.length > 0 && (
-            <ul>
-              {input.items.map((item) => (
-                <li key={item}>{item}</li>
-              ))}
-            </ul>
+        <Section className="px-8 py-6">
+          <h1 className="text-2xl font-semibold">Hi {input.name}, it shipped.</h1>
+          {input.items.map((item) => (
+            <OrderRow item={item} currency={input.currency} />
+          ))}
+          <p className="mt-4 font-medium">Total {fmt.money(input.total, input.currency)}</p>
+          {input.trackingUrl && (
+            <Button href={input.trackingUrl} width={200} height={44}>
+              Track package
+            </Button>
           )}
         </Section>
       </Email>
     ),
-  }),
+  },
+});
+```
+
+A template is read, not run. `@samva/markup/static` parses the file and the project files it
+imports without evaluating them, checks every binding against the schema, resolves Tailwind and CSS
+against the markup, and produces the template's IR: JSON, versioned (`"sml": 1`), carrying the
+markup, the bindings, the conditions, the loops and the formatters. `@samva/markup/render-ir`
+renders that IR against an input. It is a pure function with no dependencies, so nothing executes
+at send time.
+
+```ts
+import { renderIr } from "@samva/markup/render-ir";
+import { compileTemplate } from "@samva/markup/static";
+
+const compiled = await compileTemplate({
+  files, // the project's files by path; binary files become content-addressed assets
+  entry: "templates/order-shipped.tsx",
+  assetBase: "https://assets.example.com",
+  tailwind: { css: files["theme.css"] },
+});
+if (compiled.ir === undefined) throw new Error(compiled.diagnostics.map(String).join("\n"));
+
+const { subject, preheader, html, text } = renderIr(compiled.ir, compiled.fixtures.default, {
+  locale: "en-US",
+  timeZone: "UTC",
 });
 ```
 
-The definition owns a stable, project-unique `id`, a portable JSON input schema, named fixtures,
-and a synchronous render function. Imported helpers are ordinary modules, not catalog entries.
-Email executes real TypeScript against validated input and lowers a semantic tree to HTML and text.
-SMS and WhatsApp keep their structured channel compiler and `@samva/markup` JSX runtime.
+### The static profile
+
+The profile is the subset of TSX the compiler reads without running it: the forms an agent already
+writes for React. Anything else is a compile error that names the fix.
+
+| Form                | Example                                                                  |
+| ------------------- | ------------------------------------------------------------------------ |
+| Text binding        | `{input.name}`                                                           |
+| Attribute binding   | `href={input.trackingUrl}`                                               |
+| Template string     | `` `Order ${input.orderId}` ``                                           |
+| Conditional         | `{input.trackingUrl && <Button … />}`                                    |
+| Either/or           | `{input.vip ? <Gold /> : <Standard />}`                                  |
+| Conditions          | `===`, `!==`, `<`, `>`, `<=`, `>=`, `!`, `&&`, `\|\|`, `.length`         |
+| Loop                | `{input.items.map((item, i) => <Row … />)}`                              |
+| Filter              | `input.steps.filter((step) => step.done).map(…)`, `.filter(…).length`    |
+| Grid                | `<Columns each={input.deals} per={2}>{(deal) => <Column … />}</Columns>` |
+| Formatter           | `fmt.money(input.total, input.currency)`                                 |
+| Partial             | `<OrderRow item={item} />`, with props and `children`                    |
+| Conditional class   | `className={input.vip ? "bg-amber-100" : "bg-white"}`                    |
+| Destructured params | `body: ({ name, items }) => …`                                           |
+| Arithmetic          | `item.price * item.qty`, inside a formatter argument or a condition      |
+
+A `.filter` callback takes the item and one condition from the same grammar as `&&` and `?:`; it
+chains before `.map(...)` or `.length`. `<Columns each per>` lays a list out in rows of `per` cells
+(one row without `per`): the child is a function from an item, and its index within the row, to a
+`Column`. A `Column` that states no `width` takes an equal share of the row, whole percent rounded
+down, and a last row with fewer items keeps that share, so it leaves empty space instead of
+stretching. Both lower to a loop in the IR, so nothing is computed at send time.
+
+Rejected, each with its own diagnostic: calls other than `fmt.*` and `.map` (`dynamic-expression`),
+statements in a body (`statement-in-body`), imports other than `@samva/markup` and project files
+(`non-project-import`), event handlers, hooks and `dangerouslySetInnerHTML`, class names built at
+run time (`dynamic-class`), and recursion (`recursive-partial`). There is no escape hatch: logic the
+profile cannot express is computed by the caller and sent in the payload.
+
+Each diagnostic has a stable `code`, the exact `file:line:column`, a one-sentence `message` and a
+`fix`. `unknown-field` names the field and suggests the nearest one, `unguarded-optional` marks an
+optional field read outside a guard, and `fixture-invalid` names the fixture that no longer matches
+the schema.
+
+Only `@samva/markup` and files inside the project can be imported, so a project has no other
+dependency to install. A fixture is data: a literal, or constants and imported assets assembled from
+literals.
+
+### Formatters
+
+`@samva/markup/fmt` is the only set of functions a body may call. Each one is deterministic `Intl`
+with the locale and time zone the render supplies; the template's `locale` is the default and an
+explicit argument overrides it.
+
+| Formatter                              | Example                                            | Output        |
+| -------------------------------------- | -------------------------------------------------- | ------------- |
+| `fmt.money(amount, currency, locale?)` | `fmt.money(84, "EUR", "de")`                       | 84,00 €       |
+| `fmt.number(n, options?, locale?)`     | `fmt.number(1234.5, { maximumFractionDigits: 0 })` | 1,235         |
+| `fmt.date(iso, style?, locale?)`       | `fmt.date(input.shippedAt, "medium")`              | Sep 29, 2026  |
+| `fmt.time(iso, style?, locale?)`       | `fmt.time(input.slot, "short")`                    | 3:30 PM       |
+| `fmt.plural(n, forms, locale?)`        | `fmt.plural(n, { one: "item", other: "items" })`   | items         |
+| `fmt.list(values, locale?)`            | `fmt.list(["Ada", "Grace"])`                       | Ada and Grace |
+
+### Channels
+
+One template carries one schema and a body for each channel it supports. `@samva/markup/sms` and
+`@samva/markup/whatsapp` export the channel components (`Sms`; `WhatsApp` with `WhatsApp.Header`,
+`.Body`, `.Footer`, `.Buttons`, `.UrlButton`, `.QuickReplyButton`, `.PhoneButton` and
+`.CopyCodeButton`). Their names are distinct per channel, so a wrong prop fails in the type checker.
+WhatsApp bindings compile to Meta's positional `{{1}}` placeholders (`whatsappTemplate`), and a
+conditional in a WhatsApp text part is refused because Meta templates cannot branch. The platform
+gates these channels.
 
 ### Explicit template inputs
 
-`@samva/markup/template` exports `defineEmail({ id, schema, fixtures, render })`, the email
-channel's authoring helper; `TemplateDefinition` and `TemplateInput` are channel-neutral.
+`@samva/markup` exports `defineTemplate` and `TemplateInput`.
 The schema must implement Standard **JSON Schema** v1; a validator-only Standard Schema is
 insufficient. `Schema.toStandardJSONSchemaV1` (Effect) and Zod 4 schemas support caller-input
-inference, including imported render functions and named fixtures. `TemplateInput<typeof template>`
-extracts the caller type. Rendering receives input unchanged.
+inference, including named fixtures. `TemplateInput<typeof template>` extracts the caller type.
+Rendering receives input unchanged.
 
 The portable profile uses JSON Schema 2020-12. Supported validation keywords are `type`, `enum`,
 `const`, `required`, numeric bounds and `multipleOf`, string lengths and `pattern`, object/array
@@ -84,22 +220,22 @@ The pinned Zod/Effect adapter rejects lazy/suspended schema nodes before executi
 author recursive contracts directly using local JSON Schema references. Custom predicate metadata
 is checked for these vendors, but a converter-supplied JSON Schema constraint remains its contract.
 
-### Actual-input email JSX
-
-Use `jsxImportSource: "@samva/markup/email"` for object template bodies. Ordinary HTML JSX,
-imported synchronous components, nested JSON, conditionals and mapped arrays lower directly to a
-semantic tree. `renderEmail(template, data)` validates unchanged input and returns subject,
-preheader, escaped HTML, explicit or derived text, and the derived tree. Development JSX preserves
-source origins and component call sites. This synchronous library call requires an isolated host
-before executing untrusted source; it is not itself a sandbox.
-
-The rendering host has no ambient clock and no entropy source. Reading the current instant or a
-random value throws unless the template declares the matching fixed value in `runtime`, which takes
-an optional `now` (epoch milliseconds) and `randomSeed` (32-bit unsigned integer). A declaration is
-recorded on the publication and applies to every render, including module initializers that capture
-a value at import. `new Date(value)` with an explicit argument always works, so a message either
-takes its time from validated input or states it once as configuration. Locale (`en-US`) and time
-zone (UTC) are publication-wide and back every `Intl` constructor and `toLocale*` call.
+### Authoring with an agent
+
+The package ships what an agent needs without any other source. `AGENTS.md` opens with the model:
+a template is TSX in the static profile that compiles to IR, and nothing runs at send time.
+`@samva/markup/contract.json` lists the components with their props, the profile's forms, the
+formatters, the HTML elements and every diagnostic code with its fix; it is generated from the
+compiler, so it matches the version you installed. `skills/sml/SKILL.md` is the `sml` skill: it
+routes an agent through write, check, render, look and repair. Run `samva templates check --json`
+for diagnostics an agent can apply.
+
+### Previewing a render
+
+`renderIrPreview(ir, input)` from `@samva/markup/preview` renders a fixture the way `renderIr` does
+and stamps `data-samva-instance` on every element. Its `selections` map each stamped element to the
+line and column of the JSX that produced it, so an editor can select an element on the canvas and
+edit the source at that span. A delivered message never carries the attribute.
 
 Portable validation uses `@cfworker/json-schema` without runtime code generation. The
 2020-12 meta-schema is checked at every supported schema position, and the explicit profile rejects

package/dist/assets-C5duwTya.d.ts

@@ -0,0 +1,40 @@
+import { r as EmailDiagnostic } from "./diagnostics-B-Gym34R.js";
+//#region src/email/assets.d.ts
+/** Files a template may import, and what they are served as. */
+declare const ASSET_CONTENT_TYPES: Readonly<Record<string, string>>;
+interface AssetEntry {
+  /** Project-relative path the template imported. */
+  readonly path: string;
+  /** SHA-256 of the exact bytes, lowercase hex. */
+  readonly digest: string;
+  readonly bytes: number;
+  readonly contentType: string;
+  /** `<digest><ext>` — the name the asset has under any base. */
+  readonly fileName: string;
+}
+interface AssetManifest {
+  /** Where these assets are served from in this build. */
+  readonly base: string;
+  readonly assets: readonly AssetEntry[];
+}
+/** True when the compiler turns this import into a content-addressed asset. */
+declare const isAssetPath: (path: string) => boolean;
+/** Address one file by its content. */
+declare const assetEntry: (path: string, bytes: Uint8Array) => Promise<AssetEntry>;
+/**
+ * The URL an asset has under a base. The base is a build input: publication
+ * passes its hosted origin, and a local export passes whatever it will serve
+ * the exported files from.
+ */
+declare const assetUrl: (entry: AssetEntry, base: string) => string;
+/** Record, but never fetch, a URL the template points at. */
+declare const isExternalAsset: (reference: string) => boolean;
+/**
+ * Reject an asset base that would produce URLs a client will not load. The
+ * relative forms are the ones a page on disk resolves against its own
+ * directory, which is what a local export writes.
+ */
+declare const checkAssetBase: (base: string) => readonly EmailDiagnostic[];
+//#endregion
+export { assetUrl as a, isExternalAsset as c, assetEntry as i, AssetEntry as n, checkAssetBase as o, AssetManifest as r, isAssetPath as s, ASSET_CONTENT_TYPES as t };
+//# sourceMappingURL=assets-C5duwTya.d.ts.map

package/dist/brand-B-0bN_Ir.d.ts

@@ -0,0 +1,88 @@
+import { m as EmailNode } from "./elements-cqldpaJt.js";
+//#region src/internal/unsubscribe-link.d.ts
+/**
+ * The per-recipient unsubscribe URL is not known at render: the send path
+ * substitutes each delivery's link for this placeholder, or removes the
+ * unsubscribe row when the send resolved no unsubscribe group.
+ */
+declare const UNSUBSCRIBE_URL_PLACEHOLDER = "%samva:unsubscribe-url%";
+//#endregion
+//#region src/email/brand.d.ts
+interface EmailBrandAddress {
+  readonly street1: string;
+  readonly street2?: string | undefined;
+  readonly city: string;
+  readonly region: string;
+  readonly postalCode: string;
+  readonly country: string;
+}
+interface EmailBrandSocialLink {
+  readonly label: string;
+  readonly url: string;
+}
+interface EmailBrandAssets {
+  readonly logoUrl?: string | undefined;
+  readonly logoDarkUrl?: string | undefined;
+  readonly iconUrl?: string | undefined;
+}
+interface EmailBrandFooter {
+  readonly companyName?: string | undefined;
+  readonly address?: EmailBrandAddress | undefined;
+  readonly socialLinks?: readonly EmailBrandSocialLink[] | undefined;
+}
+interface EmailBrand {
+  /** The brand's slug; `samva:brand/<slug>` must name it. */
+  readonly slug: string;
+  /** Brand theme CSS in the closed grammar `parseBrandCss` accepts. */
+  readonly css: string;
+  readonly assets?: EmailBrandAssets | undefined;
+  readonly footer?: EmailBrandFooter | undefined;
+}
+/** Marks the block the send path recognizes as the template's own footer. */
+declare const FOOTER_ATTRIBUTE = "data-samva-footer";
+/** Marks the footer row that carries the unsubscribe link. */
+declare const UNSUBSCRIBE_ROW_ATTRIBUTE = "data-samva-unsubscribe";
+/** Every class the brand components use, compiled for any project that imports them. */
+declare const BRAND_COMPONENT_CLASSES: readonly ["dark:hidden!", "hidden", "dark:block!", "text-xs", "text-gray-500", "text-center", "font-semibold", "underline"];
+interface BrandLogoProps {
+  /** Rendered width in pixels; the height follows the image. */
+  readonly width?: number | undefined;
+  /** Defaults to the brand footer's company name. */
+  readonly alt?: string | undefined;
+  readonly align?: "left" | "center" | "right" | undefined;
+  readonly className?: string | undefined;
+}
+interface BrandFooterProps {
+  /** Text of the unsubscribe link. */
+  readonly unsubscribeLabel?: string | undefined;
+  readonly className?: string | undefined;
+}
+interface BrandComponents {
+  readonly BrandLogo: (props: BrandLogoProps) => EmailNode | null;
+  readonly BrandFooter: (props: BrandFooterProps) => EmailNode | null;
+}
+/** Bind `BrandLogo` and `BrandFooter` to one brand. */
+declare const brandComponents: (brand: EmailBrand) => BrandComponents;
+/** What a rendered message says about the footer it carries. */
+interface RenderedFooterMarkers {
+  /** The message renders `BrandFooter` (or claims to, with the marker). */
+  readonly footer: boolean;
+  /** The message carries the unsubscribe placeholder link only `BrandFooter` can write. */
+  readonly unsubscribeLink: boolean;
+}
+/** Read the footer markers from rendered HTML. */
+declare const renderedFooterMarkers: (html: string) => RenderedFooterMarkers;
+/**
+ * Drop the unsubscribe row from a rendered message, for a send that resolved
+ * no unsubscribe group: there is no link to put there, so the row goes.
+ */
+declare const withoutUnsubscribeRow: (rendered: {
+  readonly html?: string | undefined;
+  readonly text?: string | undefined;
+}) => {
+  readonly html: string | undefined;
+  readonly text: string | undefined;
+};
+//#endregion
+export { EmailBrand as a, EmailBrandFooter as c, RenderedFooterMarkers as d, UNSUBSCRIBE_ROW_ATTRIBUTE as f, UNSUBSCRIBE_URL_PLACEHOLDER as g, withoutUnsubscribeRow as h, BrandLogoProps as i, EmailBrandSocialLink as l, renderedFooterMarkers as m, BrandComponents as n, EmailBrandAddress as o, brandComponents as p, BrandFooterProps as r, EmailBrandAssets as s, BRAND_COMPONENT_CLASSES as t, FOOTER_ATTRIBUTE as u };
+//# sourceMappingURL=brand-B-0bN_Ir.d.ts.map