@samva/markup 0.9.0 → 0.11.0

package/AGENTS.md

@@ -10,63 +10,75 @@ the local editor, project builds, and exports live in `@samva/vite`.
 
 ## Entry points
 
+Authoring entries are what a template file imports:
+
 - `@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`.
+  `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/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` — `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` — 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.
+  `@import "samva:brand";` layers the brand theme; `samva:brand/<slug>` names one brand. These are
+  Samva's brand plugin (`samvaBrandPlugin` from `@samva/markup/brand`), the default; a host that
+  delivers mail itself passes its own `BrandPlugin` as `brandPlugin` to `compileTemplate`,
+  `renderIr` and `renderBrandFooter` to rename the brand import, the footer markers, the
+  unsubscribe placeholder and the unsubscribe link's no-track marker.
+
+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. `generated/reference.md` renders the same contract for reading.
+  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.
@@ -98,7 +110,7 @@ Read the contract before authoring. Import only subpaths declared in `package.js
 - **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

package/CHANGELOG.md

@@ -0,0 +1,379 @@
+## @samva/markup@0.11.0
+
+### Breaking: `@samva/markup` reads brand and footer names from a brand plugin
+
+Templates do not change: `samva:brand`, `BrandLogo`, `BrandFooter` and the unsubscribe row work as
+before, because Samva's brand plugin is the default.
+
+A host that compiles or renders templates can pass its own `BrandPlugin` as `brandPlugin` to
+`compileTemplate`, `transformProject`, `projectBrandSpecifier`, `parseBrandSpecifier`,
+`checkStaticProfile`, `renderIr`, `compileEmail`, `renderBrandFooter`, `renderBrandSample`,
+`brandComponents`, `renderedFooterMarkers` and `withoutUnsubscribeRow`. The plugin names the brand
+import, the attributes that mark the footer and its unsubscribe row, the unsubscribe link's URL
+placeholder, and the attribute that marks that link as untracked.
+
+`BrandFooter`'s unsubscribe link now carries `data-samva-no-track` instead of SES's
+`ses:no-track`. A host that delivers mail through SES turns the marker into `ses:no-track` before it
+sends.
+
+`@samva/markup/brand` exports `samvaBrandPlugin` and the `BrandPlugin` type in place of
+`FOOTER_ATTRIBUTE`, `UNSUBSCRIBE_ROW_ATTRIBUTE` and `UNSUBSCRIBE_URL_PLACEHOLDER`; read
+`samvaBrandPlugin.footerAttribute`, `.unsubscribeRowAttribute` and `.unsubscribeUrlPlaceholder`.
+`@samva/markup/compiler` no longer exports `BRAND_SPECIFIER`; read `samvaBrandPlugin.specifier`.
+
+### Breaking: supply brand resolution to the authoring toolchain
+
+`@samva/vite` accepts `brandResolver` and `brandPlugin` on the editor plugin and its dev, project,
+build, render and export APIs. A brand import without a resolver fails with `brand-unavailable`.
+Standalone callers supply a resolver; the package does not read Samva credentials, invoke the
+Samva CLI or load Samva brand snapshots. The `offline` option and Samva snapshot helpers move to
+the CLI.
+
+`samva templates dev`, `check`, `build`, `render`, `snapshot` and `export` supply the Samva resolver
+and brand plugin, preserving live lookup, cached snapshots and brand diagnostics.
+
+## @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.

package/README.md

@@ -14,7 +14,7 @@ template is one `.tsx` file that default-exports `defineTemplate`:
 
 ```tsx
 import { defineTemplate } from "@samva/markup";
-import { Button, Email, Section } from "@samva/markup/email/components";
+import { Button, Email, Section } from "@samva/markup/email";
 import { fmt } from "@samva/markup/fmt";
 import { jsonSchema } from "@samva/markup/input-schema";
 
@@ -94,16 +94,16 @@ export default defineTemplate({
 });
 ```
 
-A template is read, not run. `@samva/markup/static` parses the file and the project files it
+A template is read, not run. `@samva/markup/compiler` 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`
+markup, the bindings, the conditions, the loops and the formatters. `@samva/markup/render`
 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";
+import { renderIr } from "@samva/markup/render";
+import { compileTemplate } from "@samva/markup/compiler";
 
 const compiled = await compileTemplate({
   files, // the project's files by path; binary files become content-addressed assets
@@ -232,7 +232,7 @@ for diagnostics an agent can apply.
 
 ### Previewing a render
 
-`renderIrPreview(ir, input)` from `@samva/markup/preview` renders a fixture the way `renderIr` does
+`renderIrPreview(ir, input)` from `@samva/markup/render` 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.