@samva/markup 0.8.0 → 0.10.0

package/AGENTS.md

@@ -1,57 +1,118 @@
 # @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
-  `TEMPLATE_NAME_PATTERN`.
-- `@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/diagnostics` — `EmailDiagnostic` and `EmailCompileError`.
-- `@samva/markup/email/assets` — `isAssetPath` and `ASSET_CONTENT_TYPES`: which imported files
-  become content-addressed assets, without loading the compiler.
+Authoring entries are what a template file imports:
+
+- `@samva/markup` — `defineTemplate({ id, schema, fixtures, locale?, email?, sms?, whatsapp? })`,
+  `SmlTemplate`, `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/email` — email primitives (`Email`, `Section`, `Columns`, `Button`, and the rest of
+  its exports). They generate table layout and classic-Outlook fallbacks. Set
+  `jsxImportSource: "@samva/markup/email"`; the runtime is `@samva/markup/email/jsx-runtime`.
+- `@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/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.
 - `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.
-- `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.
 
-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`.
+Tooling entries are what a host (Vite, the CLI, the editor, the API, the template agent) imports:
+
+- `@samva/markup/compiler` — `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. `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. It also holds the
+  compiler's building blocks (`transformProject`, Tailwind, the cascade, CSS), the brand footer and
+  sample renders (`renderBrandFooter`, `renderBrandSample`), and `TEMPLATE_NAME_PATTERN`. It imports no Vite, esbuild, or Node builtins, so it runs in any
+  JavaScript host.
+- `@samva/markup/diagnostics` — source spans and line maps, the `DIAGNOSTIC_CODES` registry with
+  each code's fix and upgrade recipe, and `EmailDiagnostic`/`EmailCompileError`. It does not load
+  the compiler, so a host that only reports imports it.
+- `@samva/markup/render` — `renderIr(ir, input, { locale, timeZone })`, `renderIrSms` and
+  `renderIrWhatsApp`; the IR types and `SML_IR_VERSION`; `renderIrPreview(ir, input)`, the render an
+  editor shows, with an instance path (`INSTANCE_PATH_ATTRIBUTE`) on every element and the
+  `selections` that map each one to its TSX span; `compileEmail`, the HTML serializer and text
+  derivation; the email element table; SMS segment counts. Its import closure excludes the
+  compiler's libraries (`tests/entry-closure.test.ts`): it is the send-time security boundary and
+  what the API bundles.
+- `@samva/markup/edit` — the code transforms behind visual edits (`inspectSourceElement`,
+  `literalReplacement`, `expressionReplacement`, `classNameEdit`, `structuralReplacements`,
+  `applySourceReplacements` with a `ProfileGuard`); form reads and exact edits for the `sms` and
+  `whatsapp` channel bodies (`readSmsChannel`, `editSmsChannel`, `readWhatsAppChannel`,
+  `editWhatsAppChannel`), where text between expressions is editable and every expression,
+  conditional or element is a locked segment; and JSX source locations. Browser-safe: Babel parser
+  only.
+- `@samva/markup/brand` — brand records and their CSS model (`parseBrandCss`, `printBrandCss`), the
+  footer markers a send reads (`renderedFooterMarkers`, `withoutUnsubscribeRow`), and project
+  assets (`isAssetPath`, `ASSET_CONTENT_TYPES`, `assetUrl`): which imported files become
+  content-addressed assets. The send path imports it, so its closure holds only the css-tree parser
+  `theme.css` needs; rendering a footer compiles Tailwind and lives in `./compiler`.
+
+`tests/published-dependencies.test.ts` pins this list. The compiler's libraries (Babel, Tailwind,
+css-tree, caniemail) are dependencies, because a template project depends on this package alone and
+`samva templates check` runs its installed compiler.
+
+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. `@samva/markup/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.
-- **Using an element or attribute the serializer does not allow.** `@samva/markup/email/elements` is
+- **Using an element or attribute the serializer does not allow.** `@samva/markup/render` is
   the one table behind both the JSX intrinsic prop types and the serializer's allowlist, so an
   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.
 - **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
@@ -59,8 +120,6 @@ contracts; read those before authoring. Import only subpaths declared in `packag
   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.
-- **Treating `renderEmail` as a sandbox.** It executes the template's TypeScript in the calling
-  process. Run untrusted template source in an isolated host.
 - **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
@@ -68,27 +127,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/CHANGELOG.md

@@ -0,0 +1,345 @@
+## @samva/markup@0.10.0
+
+### Breaking: `@samva/markup` publishes 17 entries in two tiers
+
+Template files import `@samva/markup`, `@samva/markup/email`, `@samva/markup/fmt`,
+`@samva/markup/sms`, `@samva/markup/whatsapp` and `@samva/markup/input-schema`. Email components
+move from `@samva/markup/email/components` to `@samva/markup/email`, the entry `jsxImportSource`
+already names. A template that still imports the old path fails with `moved-import`, which names
+the replacement.
+
+Hosts import five tooling entries:
+
+| Entry                       | Replaces                                                                                                                   |
+| --------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `@samva/markup/compiler`    | `./compiler`, `./static`, `./template` (`TEMPLATE_NAME_PATTERN`), `./email/brand-footer`                                   |
+| `@samva/markup/diagnostics` | `./diagnostics`, `./diagnostic-codes`, `./email/diagnostics`                                                               |
+| `@samva/markup/render`      | `./ir`, `./render-ir`, `./preview`, `./email/render`, `./email/html`, `./email/text`, `./email/elements`, `./sms-segments` |
+| `@samva/markup/edit`        | `./source-edit`, `./channel-edit`, `./source-locations`                                                                    |
+| `@samva/markup/brand`       | `./email/brand`, `./email/assets`, `./theme-css`                                                                           |
+
+`@samva/markup/reference.md` replaces `@samva/markup/generated/*`. `tailwindcss`, `css-tree`,
+`caniemail` and `@babel/parser` are dependencies instead of optional peers, so a project that
+depends on `@samva/markup` alone can run `samva templates check`.
+
+## @samva/markup@0.9.0
+
+### Breaking: remove textual email SML APIs
+
+`@samva/markup` removes textual email SML components and grammar types, plus the
+`@samva/markup/candidate`, `/classes`, `/checks`, `/model`, `/ops`, `/registry`, and `/tsx-tracer`
+subpaths. Email templates use TSX `defineEmail` modules and lower directly to subject, HTML, and text
+through the email semantic tree. The structured SML language and compiler remain for SMS and
+WhatsApp.
+
+`@samva/vite` removes `darkClassCount` from the public `AuthoringValidationSummary` returned by its
+emit API. Email validation no longer reports a count derived from textual email SML classes.
+
+### Breaking: the executing template runtime and the textual SML grammar are removed
+
+A template is `defineTemplate` in the static profile, compiled to IR; nothing in `@samva/markup`
+runs a template any more.
+
+- **Removed.** `defineEmail`, `isTemplateDefinition`, `TemplateDefinition`, `TemplateRuntime`,
+  `renderEmail` and `bindStylesheets`; `compileEmailProject` and the generated entry, reset and
+  stylesheet-registry modules (`@samva/markup/email/stylesheets`); the TSX source instrumentation and
+  runtime tracing (`@samva/markup/tsx-source-instrumentation`, `@samva/markup/email/selection`); and
+  the textual structured SML grammar with its JSX runtime and components
+  (`@samva/markup/{ast,components,compile,compile-sms,compile-whatsapp,conditionals,emit,
+interpolate,jsx-runtime,jsx-dev-runtime,lexer,parser,predicate,printer,render-template,variables}`).
+  SMS and WhatsApp bodies are the `sms` and `whatsapp` fields of `defineTemplate`, written with
+  `Sms` from `@samva/markup/sms` and `WhatsApp` from `@samva/markup/whatsapp`.
+- **`@samva/markup/preview`** adds `renderIrPreview`, which renders a fixture from the IR with an
+  instance path on every element and the selection each path resolves to, taken from the source
+  spans the compiler recorded. The selection helpers that lived in `email/selection` move here.
+- **`@samva/markup/source-edit`** (moved from `email/source-edit`) is the set of code transforms behind
+  visual edits: text, attributes, `className`, and inserting, duplicating, moving and deleting
+  elements. `checkStaticProfile` in `@samva/markup/static` refuses an edit that would leave the
+  static profile. `@samva/markup/channel-edit` does the same for `sms` and `whatsapp` bodies.
+- **`TemplateInput`** reads the caller input from a template's `schema`.
+
+### Breaking: templates are `defineTemplate` in a static profile
+
+`@samva/markup` adds `defineTemplate({ id, schema, fixtures, locale?, email, sms?, whatsapp? })` at
+its root. A template is one TSX file in a static profile that the new compiler reads without running:
+text and attribute bindings, template strings, `&&`, `?:`, comparisons, `||`, `.length`, `.map`,
+`fmt.*` calls, arithmetic inside formatter arguments and conditions, partials with props and
+children, conditional class names, `.filter(condition)` before `.map` or `.length`, and
+`<Columns each per>` for grids (a `Column` without a `width` takes an equal share of its row). Everything else is a compile error with a stable code, a
+`file:line:column` location and a fix.
+
+- `@samva/markup/static` compiles a project to a versioned JSON IR (`"sml": 1`) and checks every
+  binding against the input schema: `unknown-field` with a did-you-mean, `unguarded-optional`, and
+  `fixture-invalid` per fixture. Tailwind, project CSS, brand themes, fonts and assets resolve at
+  compile time, and `checkTemplateCompatibility` locates client findings at source.
+- `@samva/markup/render-ir` renders the IR against an input as a pure, dependency-free function.
+  It escapes for text, attribute and URL contexts and rejects unsafe bound values.
+- `@samva/markup/fmt` adds the deterministic formatters `money`, `number`, `date`, `time`, `plural`
+  and `list`, which take their locale and time zone from the render.
+- `@samva/markup/sms` and `@samva/markup/whatsapp` add channel components with distinct names per
+  channel; WhatsApp bindings become Meta's positional `{{n}}` placeholders.
+- `id` is lowercase kebab-case, the rule the CLI and API slugs share. `subject` and `preheader`
+  belong to the channel; the `Email` component no longer takes a `preheader` prop.
+
+`defineEmail` remains for templates that compute over their input, and it stays outside the static
+profile.
+
+### Agents get a contract, a skill and a `templates/` root
+
+- **`@samva/markup`.** Ships `@samva/markup/contract.json` and `generated/reference.md`, generated
+  from the compiler: component props, the static-profile forms and the forms it refuses, formatters,
+  HTML elements and every diagnostic code with its fix. The `sml` skill ships in the package under
+  `skills/sml`. Every compiler finding now comes from one registry of codes
+  (`DIAGNOSTIC_CODES`). The generated `sml-*-contract.json` and `sml-*-reference.md` files are
+  replaced by these two.
+- **Entry root.** New hosted projects, the starter and the gallery use `templates/` as the entry
+  root. `emails/` is still accepted for entry paths in the API, the SDK types and the CLI
+  (`samva templates add`, `move`, `publish`).
+
+## @samva/markup@0.8.0
+
+### Breaking: `@samva/markup/presets` is `@samva/markup/starters`
+
+Every `@samva/markup/presets*` subpath is renamed to `@samva/markup/starters*`, and its exports
+follow: `presetCatalog` is `starterCatalog`, `presetProject` is `starterProject`,
+`presetEmailFixtures` is `starterEmailFixtures`, and every other `preset*` / `Preset*` name reads
+`starter*` / `Starter*`. A public gallery entry's `presetId` is `starterId`, and the corpus
+record types are `OwnedEditableStarter` and `BrandRecreationStarter`. `RECOMMENDED_THEME` and
+`showcaseProjectPaths` are removed.
+
+### Starters on theme variables
+
+Every starter styles each color and font through a theme variable, and keeps its look in its own
+`starter.css`. `@samva/markup/starters/theme` names the variables every starter defines and a
+brand sets to restyle one (`STARTER_THEME_VARIABLES`: `--color-brand`, `--color-surface`,
+`--font-body` and the rest; `starterThemeVariableNames` adds each color's `-dark` pair) and writes
+the `theme.css` a project starts with (`starterThemeCss({ brand })`), which imports `samva:brand`
+only when `brand` is true:
+
+```css
+@import "./starter.css";
+@import "samva:brand";
+@theme {
+}
+```
+
+`var()` now resolves in a `Button`'s classic Outlook shape and in a `bgcolor`, so
+`<Button backgroundColor="var(--color-brand)">` paints the theme color everywhere. Every `@theme`
+in project and brand CSS compiles as `static`, so a variable a project stylesheet reads reaches
+the inliner even when no utility class reads it.
+
+### Theme imports and brand themes
+
+A project `theme.css` layers with `@import`: another project stylesheet by relative path, then the
+organization's brand, then the project's own `@theme` overrides.
+
+```css
+@import "./starter.css";
+@import "samva:brand";
+
+@theme {
+  --color-accent: #0f766e;
+}
+```
+
+`samva:brand` names the organization's default brand and `samva:brand/<slug>` names one brand; the
+build supplies it through `compileEmailProject`'s `brand` option. `parseBrandCss` and
+`printBrandCss` (`@samva/markup/theme-css`) read and write the brand theme grammar: `@theme`
+variables in the color, font, text, leading, tracking, radius, spacing, container and shadow
+namespaces, `--color-*` variables in a `@media (prefers-color-scheme: dark)` block, and
+`@font-face` rules with https WOFF2 sources. A dark-mode color compiles to its `--color-*-dark`
+theme variable, read by `dark:` utilities.
+
+A project compiles against one brand: importing two fails with `brand-import-conflict`, and a
+`samva:brand` import the build has no brand for, or whose slug names another brand, fails with
+`brand-unavailable`. A brand theme outside the grammar fails with its `brand-css-*` finding.
+`@samva/markup/compiler` exports `parseBrandSpecifier`, `projectBrandSpecifier` and the
+`EmailBrand` types.
+
+Breaking: any other `@import` in the theme — including `@import "tailwindcss"` — now refuses the
+compile with `css-import-unresolved` instead of resolving to nothing. An `@import` with layer,
+supports or media conditions, one that imports itself, or a `.css` path outside the project is
+refused the same way. A theme with no utility class in use still compiles its `@font-face` rules.
+
+### `BrandLogo` and `BrandFooter`
+
+```tsx
+import { BrandFooter, BrandLogo } from "samva:brand";
+```
+
+`BrandLogo` renders the brand's logo and swaps to its dark logo where the client honors dark mode.
+It takes `width` (default 120), `alt`, `align` and `className`, and renders nothing when the brand
+has no logo. `BrandFooter` takes `unsubscribeLabel` and `className`.
+`BrandFooter` renders the company name, postal address, social links and an unsubscribe row; the
+send path fills the unsubscribe link per delivery and never click-tracks it, and a template that
+renders `BrandFooter` gets no appended footer. Add `"types": ["@samva/markup/samva-brand"]` to the
+project's tsconfig so `tsc` knows the module.
+
+### Breaking: token-table exports removed
+
+`@samva/markup/footer`, `@samva/markup/theme`, and `@samva/markup/tokens` are removed; a brand's
+footer renders through `BrandFooter`. `parseThemeCss` and `printThemeCss` are replaced by
+`parseBrandCss` and `printBrandCss` in `@samva/markup/theme-css`.
+
+### Local builds resolve `samva:brand`
+
+`samvaEditor()`, `buildTemplates()` and `exportEmailProject()` compile a project that imports
+`samva:brand` or `samva:brand/<slug>` against its organization's brand, resolved in this order:
+
+1. Live. With `SAMVA_API_KEY` in the environment or the project's `.env` (and `SAMVA_API_URL` for
+   another API), the brand is fetched from `/v1/brands`. Without one, the `samva` CLI on `PATH`
+   answers `samva brands get --json` with its `samva login` session; `@samva/vite` stores no
+   credential.
+2. Snapshot. `.samva/brands/<slug>.json`, written by `samva brands pull [slug]`, with a
+   `brand-offline` warning. The default brand reads the most recent snapshot pulled while it was
+   the default.
+3. Neither. The build fails with `brand-unavailable`, naming both fixes.
+
+When the live brand's digest differs from the snapshot's, the build warns with
+`brand-snapshot-stale`; run `samva brands pull` again. Warnings are build diagnostics and editor log
+lines and never fail a build. The editor and `check --watch` reuse a resolution for up to 30
+seconds. Keep `.samva` in `.gitignore`; a project that imports no brand needs no credentials.
+
+`@samva/vite/project` exports `resolveProjectBrand`, `loadBrandEnv`, `BRAND_SNAPSHOT_DIR` and the
+`BrandResolution`, `BrandSnapshot`, `BrandWarning` and `ResolvedBrand` types. The editor recompiles
+the theme when any stylesheet it imports changes.
+
+### Breaking: `exportEmailProject` themes the export
+
+`exportEmailProject` drops `tailwind` and takes `root` and `theme`. `dir` holds the templates and
+`root` (default `dir`) is the project: its `theme.css` themes the export as in `buildTemplates()`,
+`theme` names another file or `false` disables it, and only `.tsx` files under `dir` are entries.
+
+```ts
+const receipt = await exportEmailProject({ dir: "emails", root: ".", out: "dist/email" });
+```
+
+### Project fonts in `@font-face`
+
+A template project declares a webfont with ordinary CSS: an `@font-face` in `theme.css` (or any
+imported stylesheet) whose `src` names a `.woff2` file in the project, plus a `--font-*` token in
+`@theme`.
+
+```css
+@font-face {
+  font-family: "Brand Sans";
+  src: url("./fonts/brand-sans.woff2") format("woff2");
+  font-weight: 400;
+}
+@theme {
+  --font-brand: "Brand Sans", Helvetica, Arial, sans-serif;
+}
+```
+
+The compiler serves the file as a content-addressed asset, so local previews, exports and
+publications all load the same bytes, and it puts the rule in a `<style>` classic Outlook does not
+read, so Outlook uses the rest of the stack instead of Times New Roman.
+
+Breaking for projects that already declared fonts: a relative `src` that names no project file, a
+source that is not WOFF2, and an `http:` or `data:` source are compile errors, and a `font-family`
+stack that names a project font without ending in a generic family fails with
+`email-font-fallback`. `Stylesheet` gains `fontFaces`, and `@font-face` no longer appears in
+`headAtRules`.
+
+## @samva/markup@0.7.0
+
+### Breaking: WhatsApp `category="service"` removed
+
+`<WhatsApp category>` accepts `marketing`, `utility`, or `authentication`, the categories Meta
+approves templates under.
+
+## @samva/markup@0.6.0
+
+### Improve markup compilation safety
+
+Invalid or unsafe markup is now rejected earlier, preventing malformed email output. Complex styles
+and conditions also compile more reliably.
+
+### Carry the plain-text alternative on a public preview artifact
+
+`buildPublicTemplatePreviewArtifact` returns `text` alongside `html`, `subject` and `preheader`, so
+a surface that mounts a preset's published preview has the whole executed fixture rather than its
+HTML half. It is the same value `renderEmail` derived when the artifact was built; nothing is
+recomputed.
+
+## @samva/markup@0.5.0
+
+### Breaking: a template project no longer installs Effect
+
+- **A much smaller install:** `@samva/markup` has no Effect dependency and no `ajv` dependency, so a template project's lockfile and `node_modules` drop both graphs. The JSON Schema 2020-12 dialect the input validator checks against ships inside the package. Writing templates is unchanged: JSX, `defineEmail`, components, fixtures, and the input schema all work exactly as before, and you can still declare template input with an Effect, Zod, or plain JSON schema.
+- **`@samva/vite` drops Effect too:** The Vite plugin carries no Effect dependency either, so `samva email templates build`, the editor dev server, and a template project that installs both packages resolve neither graph.
+- **Breaking: compile and render results:** Everything the compiler returns is now a [better-result](https://better-result.dev) `Result`. Read a success with `Result.isOk(result)` and `result.value`, a failure with `Result.isError(result)` and `result.error`. Errors keep their names and tags — `SmlParseError`, `SmlCompileError`, `SmlOpError`, `EmailCompileError` — so code that matches on `_tag` or catches `EmailCompileError` still works.
+- **Breaking: data unions discriminate on `type`:** `EmailNode` and the editor-op, corpus and gallery unions name their variant with `type` instead of `_tag` — `node.type === "Element"`, `op.type === "setProp"`. Compiler errors are unaffected: `SmlParseError`, `SmlCompileError`, `SmlOpError` and `EmailCompileError` keep `_tag`, which is their error library's own field.
+- **Breaking: schema values are gone:** The package declares its data models as TypeScript types only. Runtime schema values such as `EmailDiagnostic`, `EmailElementSelection`, `SmlOpSchema`, and `SmlDocumentSchema` no longer exist; the types of the same name do, and the shapes are identical. If you decoded one of these at a boundary, declare the schema in your own project against the exported type.
+
+## @samva/markup@0.4.0
+
+### Faster, reliable saves in large projects
+
+- **Saves in large projects are quick again:** Saving a template no longer re-evaluates every template in the project, so previews come back in about the time one template takes to build.
+- **No false "Document changed elsewhere" banner:** Your own edits and fixture switches are recognized as yours, so the editor no longer locks the source panel and undo after a save. Edits made outside the editor are still detected.
+
+### Breaking: every email template is a complete, editable project
+
+- **28 templates rebuilt:** The 28 remaining single-file presets are rebuilt as showcase projects with their own stylesheet, drawn artwork, and `default` and `long-content` sample data. Marketing, digest, lifecycle, commerce, and notification templates are covered, authored for five fictional senders: Northwick, Kestrel, Northloop, Fernhollow, and Meridian. Template ids and their gallery pages are unchanged.
+- **Breaking: simpler template inputs:** Repeating content such as stories, deals, agenda items, checklist steps, and order lines is a list instead of numbered fields. Images are bundled with the project instead of passed as URLs, and headline and body copy is edited in the template source rather than supplied as input. Optional sections such as sponsors, gift cards, and reminders appear only when you send them. Dates, days remaining, and step numbers come from your input, so scheduled sends never depend on the clock. If you render one of these templates with your own data, move to the new input shape; each template's sample data shows it.
+- **Breaking: four presets retired:** `receipt`, `newsletter`, `promo`, and `order-delivered` are removed from the catalog, the public gallery, and the `PresetId` types. Use `order-receipt`, `product-newsletter`, and `product-launch-promo` instead.
+- **Stock photography removed:** The onboarding tour and setup checklist templates now use drawn artwork, so no template depends on third-party images.
+
+## @samva/markup@0.3.0
+
+- **Reliable project styling:** Switching between projects or preview fixtures preserves each template's styles and avoids unexpected revision changes.
+- **Better Outlook buttons:** `<Button>` sizes to its label without requiring a fixed width. Explicit widths remain supported.
+- **New editable templates:** Product newsletter, order receipt, product launch promotion, and an attributed Vercel invitation, including styles, images, and sample data.
+- **Richer template inputs:** Use lists and objects for repeating content such as newsletter stories and receipt items.
+- **Cleaner plain-text emails:** Empty table cells no longer leave unnecessary separators.
+- **For custom render integrations:** `bindStylesheets` from `@samva/markup/email/render` binds a renderer to one project's styles.
+
+## @samva/markup@0.2.0
+
+### Breaking: author email templates with typed input and executable TSX
+
+Email entries now default-export `defineEmail({ id, schema, fixtures, render })` from
+`@samva/markup/template`. Replace function-based email entries and `Variables<T>` placeholders
+with a schema and a `render(input)` function. Set `jsxImportSource` to `@samva/markup/email`,
+import email components from `@samva/markup/email/components`, and upgrade `@samva/markup` and
+`@samva/vite` together to 0.2.0. Regenerate the project's dependency lockfile before publishing.
+
+The input contract supports Standard JSON Schema, including Effect and Zod schema adapters.
+`TemplateInput<typeof template>` extracts the inferred input type. Named fixtures supply preview
+and validation inputs; rendering evaluates ordinary TSX, imported components, conditionals and
+mapped arrays against actual input. Time and randomness must come from input or fixed `runtime`
+configuration.
+
+The shared local and hosted compiler resolves CSS, Tailwind and imported assets, validates fixture
+inputs, and produces HTML, text and email-client diagnostics. Diagnostics identify known support
+constraints; they do not certify rendering in every email client.
+
+The Vite editor maps rendered instances to canonical TSX source. Literal edits preserve the
+source expression; computed or structural changes use reviewed source edits. Fixture switching,
+undo/redo, save/reopen and revision-conflict handling keep source edits tied to the preview.
+
+Published email templates pin an executable, input contract, dependency graph and runtime
+configuration. Existing email source must adopt the new contract and be republished; previously
+published HTML snapshots are not executable publications.
+
+## @samva/markup@0.1.2
+
+### Reject oversized SML templates before compilation
+
+Templates that exceed supported size, nesting, or node limits now return a validation error before
+compilation.
+
+## @samva/markup@0.1.1
+
+### Release the 0.1.1 package family
+
+`@samva/markup` publishes with the rest of the 0.1.1 family.
+
+## @samva/markup@0.1.0
+
+### Publish the Samva template authoring toolchain
+
+`@samva/markup` and `@samva/vite` are published on npm. They provide typed TSX authoring, local
+visual editing, and deterministic template builds. `samva templates push` uploads the compiled
+templates.