@samva/vite 0.8.0 → 0.9.0

package/AGENTS.md

@@ -1,92 +1,96 @@
 # @samva/vite agent guide
 
 `@samva/vite` is the local authoring toolchain for Samva templates written with `@samva/markup`: a
-Vite plugin that serves the visual editor, and programmatic entry points that build, render, and
-export a template project. It compiles nothing itself; every render goes through
-`@samva/markup/compiler`'s `compileEmailProject`, the same compile step a hosted Samva build runs, so
-a local render does not drift from a published one. Publishing and hosted synchronization are not
+Vite plugin that serves the visual editor, a config-free dev server, and programmatic entry points
+that build, render, and export a template project. A template is one TSX file in a static profile,
+and nothing here runs it: every check, render and preview is `compileTemplate` from
+`@samva/markup/static` followed by `renderIr`, the same two steps a hosted Samva build takes, so a
+local render does not drift from a published one. Publishing and hosted synchronization are not
 here: they are ordinary Git plus `samva templates publish` from `@samva/cli` (see
 `samva templates --help`).
 
 ## Entry points
 
-- `@samva/vite` — `samvaEditor()`, the plugin you add to `vite.config.ts`. Options are typed by
-  `SamvaEditorPluginOptions`; the README lists them.
-- `@samva/vite/build` — `buildTemplates()` and `createTemplateBuildSession()` for programmatic
-  checks and builds. The `samva` CLI loads this module from your project, not from its own bundle.
-- `@samva/vite/project` — the folder-of-templates surface: `loadEmailCatalog()`,
-  `renderEmailFixtures()`, `createEmailProjectSession()`, `exportEmailProject()`.
-- `@samva/vite/email` — `createEmailRenderer()` and `renderEmailProject()` for rendering one email
-  project from source.
-- `@samva/vite/emit` — module-preview integration for structured SMS and WhatsApp entries.
+- `@samva/vite` — `samvaEditor()`, the plugin you add to `vite.config.ts` when the defaults do not
+  cover your setup. Options are typed by `SamvaEditorPluginOptions`; the README lists them.
+- `@samva/vite/dev` — `startDevServer({ root, dir?, port?, host?, open? })`: a Vite server with no
+  config file, `samvaEditor()`, and defaults. It is what `samva templates dev` starts.
+- `@samva/vite/build` — `buildTemplates(options)` and `createTemplateBuildSession(options)` for
+  programmatic checks and builds. The `samva` CLI loads this module from your project, not from its
+  own bundle.
+- `@samva/vite/render` — `renderTemplate()` and `renderChannel()`: one template and fixture to a
+  plain JSON result.
+- `@samva/vite/project` — the folder-of-templates surface: `loadProject()`, `compileProject()`,
+  `createProjectSession()`, `exportProject()` and the render helpers over a compiled entry.
 
 Install `@samva/markup`, `@samva/vite`, and the `vite` peer as dev dependencies of the template
-project and keep them in its lockfile. The CLI's `templates check`, `templates build`, and the
-editor all resolve these packages from the project, so the lockfile is what pins the compiler
-version your previews, checks, and builds use.
+project and keep them in its lockfile. The CLI's `templates check`, `templates build`,
+`templates render` and the editor all resolve these packages from the project, so the lockfile is
+what pins the compiler version your previews, checks, and builds use.
 
 ## How you hurt yourself here
 
-- **Expecting your Vite config to apply to email rendering.** Every email render, in the editor,
-  the CLI, and the programmatic entry points, runs in an evaluator this package roots at its own
-  directory with no config file, so your `vite.config.ts` aliases and plugins never reach an email
-  template. Bare imports resolve from the package root, which is what makes `@samva/markup` resolve
-  under both hoisted and per-package installs. Import shared helpers by relative path; an alias that
-  works elsewhere in your app fails here.
-- **Side effects at module scope.** Discovery imports every `.tsx` under the templates directory
-  and asks whether its default export is a template definition, and a rebuild re-reads the whole
-  project. Top-level code in every module, helpers included, runs whenever the project is
-  evaluated; keep it free of I/O and mutable global state.
+- **Expecting a template module to run.** The compiler reads the file and never executes it, so
+  top-level code, imports of constants, and helper calls do nothing. A value a template needs is
+  input data, a fixture literal, or an import the static profile allows (a partial, a stylesheet,
+  an asset). `samva templates check` reports what the profile refuses, with a location and a fix.
+- **Expecting your Vite config to apply to templates.** Nothing about a template goes through
+  Vite's module graph, so your `vite.config.ts` aliases and plugins never reach one. Import
+  partials by relative path.
+- **Putting templates where the project root cannot see them.** Files are addressed relative to
+  the project root, which holds `theme.css`, shared imports and `.samva/`. A templates directory
+  outside it is refused rather than half-read. Set `projectRoot` (plugin) or `root` (entry points)
+  to a folder that contains both.
+- **Scanning the wrong directories.** With no `dir`, `templates/` and `emails/` are both scanned,
+  whichever exist. Setting `dir` scans only that one, so a project that keeps templates in both
+  and sets `dir` loses the other.
 - **Relying on a file path as template identity.** Identity is the `id` the definition declares.
   Two definitions declaring one id is a reported error, and moving a file does not change its id.
-  Helper modules need no marker or exclusion list: a module is a template only if its default export
-  is a definition.
-- **Exporting for delivery with the default asset base.** `exportEmailProject` renders with relative
+  Helper modules need no marker or exclusion list: a module is a template only if its default
+  export is `defineTemplate`. An editor document is a template's path plus its channel.
+- **A broken file elsewhere in the project.** The compiler reads an entry and the files it imports.
+  A file it cannot parse is a finding that names the file, and it stops the templates that import
+  it; the others keep their render.
+- **Exporting for delivery with the default asset base.** `exportProject` renders with relative
   URLs and writes each page at `templates/<id>/<fixture>.html` beside a content-addressed `assets/`
   directory, so its default base, `DEFAULT_EXPORT_ASSET_BASE`, only works when those files are
-  browsed from disk. An inbox has no directory to resolve a relative URL against, so delivery refuses
-  one. For an export you will send, pass the https origin that will serve the assets.
-- **Reusing a renderer without a stable namespace.** `createEmailRenderer` keeps one evaluator
-  across renders, as a dev server does, and gives each project its own module-id namespace. Omit
-  `namespace` and every `load` takes a fresh one, which isolates unrelated projects but grows the
-  graph on every reload. A watch loop over one project passes the same `namespace` each time so its
-  ids stay stable. Each `load` re-evaluates its own namespace's modules; `invalidate()` also drops
-  the modules namespaces share. `close()` releases the evaluator.
-- **Expecting the email editor to overwrite concurrent edits.** The editor writes back to the
-  entry's canonical `.tsx` source after checking that the file on disk is still the revision it
-  read, so a change you saved elsewhere is not overwritten; reload the entry and retry. SMS and
-  WhatsApp entries are read-only in the editor.
-- **Committing or hand-editing `.samva/brands`.** `samva:brand` resolves live first and falls
-  back to the snapshot `samva brands pull` writes there, warning when it is older than the live
-  brand. The API owns the brand, so the directory is gitignored and refreshed with `pull`; a
-  project with neither credentials nor a snapshot fails with `brand-unavailable`.
+  browsed from disk. An inbox has no directory to resolve a relative URL against, so delivery
+  refuses one. For an export you will send, pass the https origin that will serve the assets.
+- **Expecting the editor to overwrite concurrent edits.** The editor writes back to the entry's
+  `.tsx` source after checking that the file on disk is still the revision it read, so a change you
+  saved elsewhere is not overwritten; reload the entry and retry.
+- **Committing or hand-editing `.samva/`.** `.samva/` holds files this package generates. It is
+  gitignored, like `.next/` and `.tanstack/`, and changes inside it never recompile templates.
+  `samva:brand` resolves live first, refreshes `.samva/brands/<slug>.json` from every live answer,
+  and falls back to that copy, warning when it is used or was older than the live brand. The API
+  owns the brand; a project with neither credentials nor a cached copy fails with
+  `brand-unavailable`.
 
 ## Rules
 
-- **Template entries are `.tsx`.** Discovery ignores every other extension.
+- **Template entries are `.tsx`.** Discovery ignores every other extension, hidden folders and
+  `node_modules`.
 - **Template ids and fixture keys match `TEMPLATE_NAME_PATTERN`** from `@samva/markup/template`,
   because both are written into export paths. Code that builds a path from them imports that
   pattern instead of restating it.
 - **Fixtures are validated against the template's own schema before they render.** A bad fixture is
   a finding on that template, not a runtime surprise at send time.
 - **One failure stays with its template.** A refused render reports against its fixture, and an
-  email entry that does not build stays in the catalog with a null render and the findings that
-  stopped it. SMS and WhatsApp entries that stop compiling keep their last successful preview,
-  labeled stale, until the file compiles again or is deleted.
-- **Results are values.** `@samva/vite/build` and the preview surfaces return discriminated results
-  with an `ok` field, and `@samva/vite/emit` passes through the compiler's better-result `Result`. A
-  missing `vite` peer, or an entry whose default export is not a template definition where one is
-  required, throws.
+  entry that does not compile stays in the catalog with a null render and the findings that
+  stopped it; an editor document whose file stops compiling keeps its place the same way.
+- **Results are values.** `buildTemplates`, `renderTemplate` and `renderChannel` return
+  discriminated results with an `ok` field and never throw for a finding about your source. A
+  missing `vite` peer, or a templates directory outside the project root, throws.
 - **The asset base is a build input, not authored source.** The same content can be built for one
   origin and exported for another. The dev server is not an https origin, so editor previews
   reference assets through the editor's own route by path.
 
 ## Proving your setup
 
-- `samva templates check --dir <templates-dir>` executes every declared fixture and reports
+- `samva templates check` compiles every template, renders every declared fixture, and reports
   findings; `--watch` keeps it running while you edit.
-- `vite` with `samvaEditor()` configured serves the editor at the configured `route`; every entry
-  should appear with its fixtures.
-- `exportEmailProject({ dir, out })` writes browsable HTML and text for every fixture and a
+- `samva templates dev`, or `vite` with `samvaEditor()` configured, serves the editor at the
+  configured `route`; every template should appear with its fixtures, one document per channel.
+- `exportProject({ root, out })` writes browsable HTML and text for every fixture and a
   `catalog.json` with the asset mapping and findings, without Samva credentials unless the project
-  imports `samva:brand` and has no snapshot.
+  imports `samva:brand` and has no cached copy.

package/README.md

@@ -1,31 +1,39 @@
 # @samva/vite
 
-The unified local editor for Samva email, SMS, and WhatsApp templates. One Vite
-plugin discovers `.tsx` files, evaluates them through the Samva JSX runtime,
-applies the project theme, and serves the full visual editor with HMR.
+The local editor, dev server and build for Samva templates. A template is one TSX file that
+`@samva/markup` compiles without running it; this package serves the visual editor over the
+compiled templates, and checks, builds, renders and exports them, so what you preview is what a
+publication renders.
 
-## Install
+## Start
 
-Keep the authoring library and editor in the project, with Vite provided as the editor's peer:
+`samva templates dev` bundles the dev server with sensible defaults, so most projects configure
+nothing and need no `vite.config.ts`:
 
 ```sh
-npm install --save-dev @samva/markup @samva/vite vite
+samva templates dev
 ```
 
-`samva templates init` creates a project from the canonical starter, which contains these
-dependencies and an equivalent `vite.config.ts`. Existing project scripts remain untouched.
+`samva templates init` creates a project from the canonical starter. Templates live in `templates/`,
+and `emails/` is also recognized. `@samva/vite` stays a public, configurable plugin for setups
+those defaults cannot cover: templates in another folder, a monorepo, or a Vite server that also
+runs your other plugins.
+
+```sh
+npm install --save-dev @samva/markup @samva/vite vite
+```
 
 ```ts
 import { samvaEditor } from "@samva/vite";
 import { defineConfig } from "vite";
 
 export default defineConfig({
-  plugins: [samvaEditor({ templatesDir: "emails" })],
+  plugins: [samvaEditor()],
 });
 ```
 
-Run `vite` and open `http://localhost:5173/`. The default assumes this dev server
-exists only for Samva authoring:
+Run `vite` and open `http://localhost:5173/`. The default assumes this dev server exists only for
+Samva authoring:
 
 - editor UI: `/`
 - editor API and event streams: `/api/*`
@@ -34,113 +42,153 @@ exists only for Samva authoring:
 To share a Vite server with another app, choose a route:
 
 ```ts
-samvaEditor({ templatesDir: "emails", route: "/__samva" });
+samvaEditor({ route: "/__samva" });
 ```
 
-That mounts the UI at `/__samva/`, the API at `/__samva/api/*`, and the bundled
-assets at `/__samva/assets/*`. Requests outside the configured route pass through
-to the rest of the Vite middleware stack.
+That mounts the UI at `/__samva/`, the API at `/__samva/api/*`, and the bundled assets at
+`/__samva/assets/*`. Requests outside the configured route pass through to the rest of the Vite
+middleware stack.
+
+## Options
+
+| Option         | Type              | Default                    | Description                                                                                                       |
+| -------------- | ----------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `templatesDir` | `string`          | `templates/` and `emails/` | The one directory to scan for `.tsx` templates, relative to the project root. Unset scans whichever exist.        |
+| `projectRoot`  | `string`          | the Vite root              | The folder holding `theme.css`, shared imports and `.samva/`, relative to the Vite root. Contains `templatesDir`. |
+| `route`        | `string`          | `"/"`                      | Absolute editor UI route; API and assets are mounted beneath it.                                                  |
+| `theme`        | `string \| false` | `"theme.css"`              | Project theme file relative to the project root, or `false` to compile without one.                               |
+
+For templates in another folder of a monorepo, set `projectRoot` to a folder that contains both the
+templates and the files they import; a templates directory outside the project root is an error.
 
 ## Authoring files
 
-Email `.tsx` entries default-export `defineEmail({ id, schema, fixtures, render })` from
-`@samva/markup/template`. Use the `@samva/markup/email` JSX runtime and primitives from
-`@samva/markup/email/components`. Ordinary synchronous helpers, conditions and loops execute
-against actual validated JSON. Shared helper modules are excluded from the template catalog;
-ids are stable independently of paths and must be unique within the project.
+A template default-exports `defineTemplate` from `@samva/markup` and is written in the static
+profile: ordinary JSX, HTML and Tailwind that the compiler reads and never executes. The editor
+previews every declared fixture, offers source-aware edits where the source intent is unambiguous,
+and saves them to the file.
 
 ```tsx
-/** @jsxImportSource @samva/markup/email */
-import { Schema } from "effect";
+import { defineTemplate } from "@samva/markup";
 import { Email, Section } from "@samva/markup/email/components";
-import { defineEmail } from "@samva/markup/template";
+import { jsonSchema } from "@samva/markup/input-schema";
 
-export default defineEmail({
+export default defineTemplate({
   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: (
+  schema: jsonSchema<{ firstName: string }>({
+    type: "object",
+    required: ["firstName"],
+    properties: { firstName: { type: "string" } },
+    additionalProperties: false,
+  }),
+  fixtures: { basic: { firstName: "Ada" } },
+  email: {
+    subject: (input) => `Welcome, ${input.firstName}`,
+    preheader: () => "Your account is ready",
+    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>
       </Email>
     ),
-  }),
+  },
 });
 ```
 
-The email editor previews declared fixtures and offers source-aware edits where the source intent
-is unambiguous. Source is canonical. Failed email entries remain visible with diagnostics and a
-null render. SMS and WhatsApp remain read-only structured previews; an invalid edit retains their
-last successful emission and labels it stale. Deleting an entry removes its preview.
-
-The browser canvas is a structural preview of Samva's modern and Outlook-safe
-compiler output. It does not emulate the exact Gmail, Outlook, Apple Mail, or
-Yahoo rendering engines. Use compatibility findings and inbox tests for
-client-specific proof.
-
-## Options
+Any other `.tsx` module in the templates directory (a partial, a component) is an ordinary module
+that templates import; a module is a template only if its default export is `defineTemplate`.
+Identity is the `id` the definition declares, unique within the project. A template that declares
+`sms` or `whatsapp` beside `email` shows one editor document per channel over the same file.
 
-| Option         | Type              | Default       | Description                                                      |
-| -------------- | ----------------- | ------------- | ---------------------------------------------------------------- |
-| `templatesDir` | `string`          | `"emails"`    | Recursive `.tsx` template directory.                             |
-| `route`        | `string`          | `"/"`         | Absolute editor UI route; API and assets are mounted beneath it. |
-| `theme`        | `string \| false` | `"theme.css"` | Project theme file, or `false` to disable discovery.             |
+The browser canvas is a structural preview of Samva's modern and Outlook-safe compiler output. It
+does not emulate the exact Gmail, Outlook, Apple Mail, or Yahoo rendering engines. Use
+compatibility findings and inbox tests for client-specific proof.
 
 ## Theme, check, and publish
 
 A root `theme.css` uses Tailwind v4 `@theme` syntax and may `@import` other project `.css` files
-and `samva:brand`; any other import is a compile error. Changes to the theme or a stylesheet it
-imports recompile
-local previews while preserving the last valid theme when an edit is temporarily
-invalid.
+and `samva:brand`; any other import is a compile error. A change to the theme, a partial, or an
+imported stylesheet recompiles every template that reads it.
+
+`samva templates check` and `buildTemplates()` compile every template, render every declared
+fixture through each channel the template declares, and check the email output against the client
+matrix. `buildTemplates()` returns `files`, one per template entry, with `ok`, the template's IR,
+input schema, each fixture's rendered output, and structured diagnostics; helper modules have no
+entry. A template requires at least one fixture.
+
+```ts
+import { buildTemplates } from "@samva/vite/build";
+
+const result = await buildTemplates({ root: ".", assetBase: "https://assets.example.com/p" });
+```
+
+`buildTemplates(options)` and `createTemplateBuildSession(options)` take `root`, `dir`, `theme`,
+`assetBase` and `offline`. Imported email assets require an HTTPS `assetBase`, which names where
+their bytes are served in delivered messages. `createTemplateBuildSession` also reports file
+changes for `check --watch`.
+
+`samva templates build --out dist/templates.json` writes the CLI's local artifact. Check writes no
+files. A successful fixture check does not prove every possible input branch.
+
+## Render one fixture
+
+`samva templates render` runs this package's `render` entry from your project, so it uses the
+compiler version your lockfile pins. The results are plain JSON.
+
+```ts
+import { renderChannel, renderTemplate } from "@samva/vite/render";
+
+const email = await renderTemplate({ root: ".", template: "welcome", fixture: "basic" });
+// { ok: true, subject, preheader?, html, text, diagnostics } or { ok: false, diagnostics }
+
+const sms = await renderChannel({ root: ".", template: "order", fixture: "first", channel: "sms" });
+```
+
+`template` is a template id or the project-relative path of its entry. `locale` and `timeZone`
+override the formatters' defaults.
 
-`samva templates check` and `buildTemplates()` execute every email fixture and validate its
-actual input. `buildTemplates()` returns `files`, each with a `preview.kind` discriminator:
-`email` contains input schema, compiled module graph, actual fixture subject/HTML/text and
-structured diagnostics; `structured` contains the SMS/WhatsApp preview. Helper modules have no
-file entry. An email requires at least one fixture.
+## Dev server without a config file
 
-`samva templates build --dir emails --out dist/templates.json` writes the CLI's version 2 local
-artifact. Check writes no files. `check --watch` observes changes; `--jsonl` emits one observation
-per rebuild and `--json` is one-shot. A successful fixture check does not prove every possible
-input branch.
+```ts
+import { startDevServer } from "@samva/vite/dev";
+
+const server = await startDevServer({ root: ".", port: 5173, open: true });
+console.log(server.url);
+await server.close();
+```
 
-Imported email assets require `assetBase` in `buildTemplates()` or `--asset-base` in CLI checks
-and builds, naming their actual HTTPS serving base.
+`startDevServer` creates a Vite server with `configFile: false` and `samvaEditor()`, which is what
+`samva templates dev` does.
 
 ## The organization brand
 
 A project that imports `samva:brand` (the default brand) or `samva:brand/<slug>` compiles against
-its organization's brand. The editor, `buildTemplates()`, and `exportEmailProject()` resolve it in
-this order:
+its organization's brand. The platform brand record is the source of truth; each publication pins
+the brand version it was built with. The editor, `buildTemplates()`, and `exportProject()` resolve
+it 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 directly. Without one, the `samva` CLI on `PATH` is asked
    (`samva brands get --json`) and answers with your `samva login` session, which stays in the
-   operating-system keyring the CLI owns.
-2. **Snapshot.** `.samva/brands/<slug>.json`, written by `samva brands pull [slug]`, with a
-   `brand-offline` warning.
+   operating-system keyring the CLI owns. A live answer refreshes the cached copy.
+2. **Cached copy.** `.samva/brands/<slug>.json`, written by every live fetch and by
+   `samva brands pull [slug]`, with a `brand-offline` warning.
 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; they never fail a build. The editor and `check --watch` reuse a resolution briefly,
-so a brand edited elsewhere arrives within seconds rather than on the next save. Keep `.samva` in
-`.gitignore`. A project that imports no brand needs no credentials for local work.
+When the live brand's digest differs from the cached copy's, the build warns with
+`brand-snapshot-stale` and refreshes the copy. Warnings are build diagnostics and editor log lines;
+they never fail a build. The editor and `check --watch` reuse a resolution briefly, so a brand
+edited elsewhere arrives within seconds rather than on the next save. A project that imports no
+brand needs no credentials for local work.
+
+## The `.samva/` folder
+
+`.samva/` holds files this package generates in your project, the way `.next/` and `.tanstack/`
+do. Keep it in `.gitignore`. It is not part of the project's source, so changes inside it never
+recompile templates.
+
+## Publish
 
 For a hosted project, commit and push the checked TSX tree with ordinary Git, then publish one exact
 commit:
@@ -156,25 +204,23 @@ The CLI's repository-local credential helper obtains a short-lived Artifact cred
 Samva's credential protocol when Git needs one. It validates the repository host/path and does not
 store the token in Git config or the remote URL. `templates publish` requires a clean worktree and
 an exact commit reachable from the fetched `origin` default branch; it creates an immutable
-publication receipt and does not push or rewrite history.
-
-Hosted builds consume the committed Bun text lockfile version 2 or npm lockfile version 3.
-Keep dependencies and the supported lockfile in the project. Sending selects an exact immutable
+publication receipt and does not push or rewrite history. Sending selects an exact immutable
 publication by default; later source edits do not change that publication.
 
 ## Local export
 
 ```ts
-import { exportEmailProject } from "@samva/vite/project";
+import { exportProject } from "@samva/vite/project";
 
-const receipt = await exportEmailProject({ dir: "emails", root: ".", out: "dist/email" });
+const receipt = await exportProject({ root: ".", out: "dist/email" });
 ```
 
-`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
-`samva:brand` resolves as described above.
+`root` is the project: its `theme.css` themes the export, as in `buildTemplates()`; `dir` narrows
+the templates directory, `theme` names another file or `false` disables it, and `samva:brand`
+resolves as described above.
 
-Export writes `templates/<id>/<fixture>.html` and `.txt`, content-addressed files under `assets/`,
-and `catalog.json` with the asset mapping and findings. The default `../../assets` base resolves
-from each exported page. For delivery, supply the actual HTTPS `assetBase` and serve those bytes
-there; relative URLs are for local export. External HTTPS images stay external references.
+Export writes `templates/<id>/<fixture>.html` and `.txt`, plus `.sms.txt` and `.whatsapp.json` for
+those channels, content-addressed files under `assets/`, and `catalog.json` with the asset mapping
+and findings. The default `../../assets` base resolves from each exported page. For delivery,
+supply the actual HTTPS `assetBase` and serve those bytes there; relative URLs are for local
+export. External HTTPS images stay external references.

package/dist/build.d.ts

@@ -1,61 +1,66 @@
-import { ModulePreview } from "./emit.js";
-import { CompiledEmailProject } from "@samva/markup/compiler";
+import { _ as TemplateChannel, a as ProjectOptions } from "./project-CiUuzKsC.js";
 import { EmailDiagnostic } from "@samva/markup/email/diagnostics";
+import { RenderedIrEmail, RenderedIrWhatsApp, TemplateIr } from "@samva/markup/ir";
 //#region src/build.d.ts
-/** One declared input rendered through executable email source. */
-interface EmailFixtureBuild {
+/** The compiler a build ran, as a publication records it. */
+declare const COMPILER: string;
+/** One declared input rendered through every channel the template declares. */
+interface FixtureBuild {
   readonly name: string;
   readonly input: unknown;
   readonly ok: boolean;
-  readonly subject?: string | undefined;
-  readonly preheader?: string | undefined;
-  readonly html?: string | undefined;
-  readonly text?: string | undefined;
+  readonly email?: Pick<RenderedIrEmail, "subject" | "preheader" | "html" | "text"> | undefined;
+  readonly sms?: string | undefined;
+  readonly whatsapp?: RenderedIrWhatsApp | undefined;
   readonly diagnostics: readonly EmailDiagnostic[];
 }
-/** Executable email artifacts retain their input contract, module graph and actual fixture output. */
-interface EmailBuildPreview {
-  readonly kind: "email";
+/** A template's IR, its input contract, and what each declared fixture rendered. */
+interface TemplateBuild {
+  /** The id the definition declares. */
+  readonly template: string;
+  readonly channels: readonly TemplateChannel[];
   readonly ok: boolean;
-  readonly compilerVersion: string;
+  /** Project-relative source of the entry. */
+  readonly source: string;
+  readonly inputSchema: Readonly<Record<string, unknown>>;
+  readonly ir: TemplateIr;
+  readonly fixtures: readonly FixtureBuild[];
+  /** Compile findings, brand findings and asset-base findings. */
   readonly diagnostics: readonly EmailDiagnostic[];
-  readonly templates: readonly {
-    readonly name: string;
-    readonly channel: "email";
-    readonly ok: boolean;
-    readonly source: string;
-    readonly inputSchema: Readonly<Record<string, unknown>>;
-    readonly compiled: CompiledEmailProject;
-    readonly fixtures: readonly EmailFixtureBuild[];
-  }[];
+  /** Target-client findings across the email fixtures. */
+  readonly compatibility: readonly EmailDiagnostic[];
 }
-type TemplateBuildPreview = EmailBuildPreview | (ModulePreview & {
-  readonly kind: "structured";
-});
-interface BuildTemplatesResult {
-  /** Authored entry paths, sorted; helper modules have no entry here. */
-  readonly files: ReadonlyArray<{
-    readonly id: string;
-    readonly kind: "tsx";
-    readonly preview: TemplateBuildPreview;
-  }>;
+/** One template entry of the project. `template` is absent when the entry did not compile. */
+interface BuildFile {
+  /** Project-relative path of the entry. */
+  readonly id: string;
+  readonly kind: "tsx";
+  readonly ok: boolean;
+  readonly template?: TemplateBuild | undefined;
+  readonly diagnostics: readonly EmailDiagnostic[];
 }
-interface BuildTemplatesOptions {
-  /** Project root containing shared imports and theme.css; defaults to the parent of dir. */
-  readonly root?: string | undefined;
-  readonly theme?: string | false | undefined;
-  /** Required for imported email assets. Must be their actual HTTPS serving base. */
-  readonly assetBase?: string | undefined;
+interface BuildTemplatesResult {
+  readonly compilerVersion: string;
+  /** Template entries, sorted by path; helper modules have no entry here. */
+  readonly files: readonly BuildFile[];
+  /** Findings about the project as a whole: the brand, a duplicate id. */
+  readonly diagnostics: readonly EmailDiagnostic[];
+  readonly ok: boolean;
 }
+interface BuildTemplatesOptions extends ProjectOptions {}
 interface TemplateBuildSession {
   readonly build: () => Promise<BuildTemplatesResult>;
   readonly subscribe: (listener: (path: string) => void) => () => void;
   readonly close: () => Promise<void>;
 }
-/** Execute each email definition's fixtures; compile structured SMS/WhatsApp through their channel compiler. */
-declare const buildTemplates: (dir: string, options?: BuildTemplatesOptions) => Promise<BuildTemplatesResult>;
-/** A watcher and module evaluator over the project's installed authoring toolchain. */
-declare const createTemplateBuildSession: (dir: string, options?: BuildTemplatesOptions) => Promise<TemplateBuildSession>;
+/**
+ * Compile every template in a project and render every fixture it declares
+ * through each of its channels, then check the email fixtures against the
+ * client matrix. Nothing is evaluated.
+ */
+declare const buildTemplates: (options?: BuildTemplatesOptions) => Promise<BuildTemplatesResult>;
+/** A watcher and compiler over a project, for `check --watch`. */
+declare const createTemplateBuildSession: (options?: BuildTemplatesOptions) => TemplateBuildSession;
 //#endregion
-export { BuildTemplatesOptions, BuildTemplatesResult, EmailBuildPreview, EmailFixtureBuild, TemplateBuildPreview, TemplateBuildSession, buildTemplates, createTemplateBuildSession };
+export { BuildFile, BuildTemplatesOptions, BuildTemplatesResult, COMPILER, FixtureBuild, TemplateBuild, TemplateBuildSession, buildTemplates, createTemplateBuildSession };
 //# sourceMappingURL=build.d.ts.map