@samva/vite 0.8.0 → 0.10.0

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 { Email, Section } from "@samva/markup/email/components";
-import { defineEmail } from "@samva/markup/template";
+import { defineTemplate } from "@samva/markup";
+import { Email, Section } from "@samva/markup/email";
+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 { EmailDiagnostic } from "@samva/markup/email/diagnostics";
+import { _ as TemplateChannel, a as ProjectOptions } from "./project-CRqjs-wV.js";
+import { RenderedIrEmail, RenderedIrWhatsApp, TemplateIr } from "@samva/markup/render";
+import { EmailDiagnostic } from "@samva/markup/diagnostics";
 //#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