@samva/vite 0.6.0 → 0.8.0

package/AGENTS.md

@@ -1,88 +1,92 @@
-# Samva Vite consumer guide
+# @samva/vite agent guide
 
-Install `@samva/markup`, `@samva/vite`, and the Vite peer in the template project. Add
-`samvaEditor()` to `vite.config.ts` for the visual editor. Use `@samva/vite/build` only for
-programmatic template builds and `@samva/vite/emit` only for module-preview integration.
+`@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
+here: they are ordinary Git plus `samva templates publish` from `@samva/cli` (see
+`samva templates --help`).
 
-The CLI loads `@samva/vite/build` from the current project. Keep these authoring dependencies in the
-project lockfile so local preview, check, and build use the same compiler version as the project.
+## Entry points
 
-This package is plain TypeScript like `@samva/markup`, and adds no runtime framework of its own to
-a template project. `@samva/vite/build` and the preview surfaces answer with discriminated results
-carrying an `ok` field, and `@samva/vite/emit` passes the compiler's better-result `Result`
-through. A missing `vite`, or an entry that does not default-export a template definition, throws.
+- `@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.
 
-Hosted synchronization is ordinary Git. A CLI-created project has a repository-local Samva
-credential helper, and `samva templates publish` accepts only a clean exact commit reachable from
-the fetched `origin` default branch. Publish creates an immutable receipt; it does not push or
-rewrite history.
+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.
 
-Template discovery is `.tsx` only. The local email editor writes the canonical TSX entry with a
-revision check and a fresh comparison against disk; SMS and WhatsApp stay read-only. A change
-published without a client is what the editor reads as a foreign edit, so nothing the editor itself
-did may reach it that way. A save and a fixture switch both run in the store's mutation queue, so no
-rebuild can straddle one and publish the difference anonymously; the editor's write comes back
-through the file watcher like any other edit, and a changed file that still holds the bytes its
-entry was built from re-evaluates nothing. Watcher events arrive in bursts and one rebuild re-reads
-the whole project, so a rebuild that has not started yet covers every event queued before it. Every discovered entry is imported once through the dev
-server's own SSR graph, and a default export that is a template definition takes the email lane —
-compiled and rendered through `compileEmailProject`, so a local render cannot drift from a published
-one. Email requires an executable definition. Structured SMS/WhatsApp entries emit SML, and
-for SMS and WhatsApp an invalid current TSX keeps and visibly labels the last successful emission
-while the same file remains discovered; deleting the file removes it.
+## How you hurt yourself here
 
-The email document is one executed render of one declared fixture: the fixture names the template
-declares, the fixture being viewed, the render stamped with `data-samva-instance`, and the compile
-and client findings taken from rendering every declared fixture as it will be delivered. An entry
-that does not build keeps its place with a null render and the findings that stopped it. Its
-revision is a digest of authored source and what the declared fixtures render, so source locations
-cannot stay pinned after a formatting-only edit. It stays put when only the viewed fixture changes. The dev server is not an https origin, so a local
-render points at the editor's own asset route by path — every render here is a preview or the input
-to a finding, and the base a publication serves from is a build input rather than authored.
+- **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.
+- **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
+  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`.
 
-Object email projects compile through `@samva/vite/email`. It is an adapter: the whole compile step
-is `@samva/markup/compiler`'s `compileEmailProject`, the same call the hosted build makes, and this
-package owns only module resolution and evaluation. The asset base is an explicit input, so a
-build and an export can address the same content from different origins. Both entry points evaluate
-the compiler's generated wrapper rather than the authored entry: the render has to happen inside the
-graph the project's stylesheets registered into.
+## Rules
 
-`createEmailRenderer` keeps one evaluator across renders, as a dev server does, and gives each
-project its own id namespace so their modules coexist. Anything the compiler rewrote into
-JavaScript — a stylesheet, an imported asset — is served under a `.js` id; its authored extension
-would be claimed by Vite's CSS or asset pipeline. A caller that reloads the same project passes a
-stable `namespace` so ids survive the reload and `invalidate()` is what makes changed source take
-effect; omitting it takes a fresh namespace, which is what isolates unrelated projects.
+- **Template entries are `.tsx`.** Discovery ignores every other extension.
+- **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.
+- **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.
 
-`@samva/vite/project` is the folder-of-templates surface. A project holds many definitions with
-shared components and CSS between them; which `.tsx` files are templates is decided by evaluating
-the compiler's generated wrapper and asking whether the default export is a template definition, so
-an ordinary helper module needs no marker and no exclusion list. Identity is the id the definition
-declares, never its path, and two definitions declaring one id is a reported error. Fixtures are
-validated against the template's own schema before they render, so a bad fixture is a source defect
-the author sees locally.
+## Proving your setup
 
-`exportEmailProject` renders in the compiler's export mode (`relativeUrls: true`). It writes one
-page at `templates/<id>/<fixture>.html` and every asset once under `assets/`, so its default
-`../../assets` base is the path from a page's own directory to those bytes. Delivery keeps
-refusing a relative reference — an inbox has no directory to resolve one against — so an export
-destined for sending names the https origin it will be served from instead. Either way the export
-writes each asset under its content address and records the base, so the manifest is the whole
-mapping.
-
-A refused render reports against the one fixture rather than throwing at the caller: one template
-that cannot render must not take the rest of the catalog with it.
-
-The evaluator roots itself at this package's own directory and refuses an ambient Vite config.
-Virtual ids have no directory, so bare imports resolve against the server root; rooting here is what
-makes `@samva/markup` resolve under a per-package install as well as a hoisted one.
-
-A golden-digest test in `tests/email-parity.test.ts` pins this adapter's output against the same
-value the hosted build asserts in `apps/agents/tests/workerd/email-parity.test.ts`.
-
-## Verification
-
-`bun run --filter @samva/vite test:browser` builds the plugin and embedded editor, then runs the
-Chromium source-editing integration tests. `test:browser:cross` runs Chromium, Firefox, and WebKit.
-These tests own temporary template projects and plugin servers; the editor library's browser suite
-tests its standalone host separately.
+- `samva templates check --dir <templates-dir>` executes 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
+  `catalog.json` with the asset mapping and findings, without Samva credentials unless the project
+  imports `samva:brand` and has no snapshot.

package/README.md

@@ -102,7 +102,9 @@ client-specific proof.
 
 ## Theme, check, and publish
 
-A root `theme.css` uses Tailwind v4 `@theme` syntax. Theme changes recompile
+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.
 
@@ -118,7 +120,27 @@ per rebuild and `--json` is one-shot. A successful fixture check does not prove
 input branch.
 
 Imported email assets require `assetBase` in `buildTemplates()` or `--asset-base` in CLI checks
-and builds, naming their actual HTTPS serving base. No credentials are needed for local work.
+and builds, naming their actual HTTPS serving base.
+
+## 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:
+
+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.
+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.
 
 For a hosted project, commit and push the checked TSX tree with ordinary Git, then publish one exact
 commit:
@@ -145,12 +167,14 @@ publication by default; later source edits do not change that publication.
 ```ts
 import { exportEmailProject } from "@samva/vite/project";
 
-const receipt = await exportEmailProject({ dir: ".", out: "dist/email" });
+const receipt = await exportEmailProject({ dir: "emails", 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.
+
 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.
-
-The runnable `examples/email-starter` workspace exercises the authoring setup.

package/dist/build.js

@@ -1,7 +1,7 @@
-import { n as resolveThemePath, r as discoverTemplateFiles, t as readProjectThemeCss } from "./theme-CBF6Czjm.js";
+import { c as projectThemePath, f as brandDiagnostics, i as isTemplateDefinition, l as readProjectThemeCss, m as loadBrandEnv, o as readEmailProject, p as createBrandResolver, s as renderEmailFixtures, u as resolveThemePath } from "./project-RON2Ei7d.js";
+import { t as discoverTemplateFiles } from "./discovery-D2eR-rzi.js";
 import { COMPILER_VERSION, emitModulePreview } from "./emit.js";
 import { createEmailRenderer } from "./email.js";
-import { isTemplateDefinition, readEmailProject, renderEmailFixtures } from "./project.js";
 import { dirname, parse, relative, resolve, sep } from "node:path";
 //#region src/build.ts
 /** Execute each email definition's fixtures; compile structured SMS/WhatsApp through their channel compiler. */
@@ -38,17 +38,30 @@ const createTemplateBuildSession = async (dir, options = {}) => {
 	let closed = false;
 	let emailRenderer;
 	let previousTheme;
+	let previousBrand;
+	const brands = createBrandResolver({
+		root,
+		env: await loadBrandEnv(root)
+	});
 	const build = async () => {
 		server.moduleGraph.invalidateAll();
 		const themeCss = await readProjectThemeCss(themePath);
-		if (emailRenderer !== void 0 && themeCss !== previousTheme) {
+		const files = await discoverTemplateFiles(templatesDir);
+		const sourceFiles = await readEmailProject(root);
+		const themeFile = themePath === void 0 ? void 0 : projectThemePath(root, themePath);
+		const brandResolution = await brands.resolve(themeFile === void 0 || themeCss === void 0 ? sourceFiles : {
+			...sourceFiles,
+			[themeFile]: themeCss
+		}, themeFile);
+		const brand = brandResolution.ok ? brandResolution.brand : void 0;
+		const brandFindings = brandDiagnostics(brandResolution);
+		if (emailRenderer !== void 0 && (themeCss !== previousTheme || brand?.digest !== previousBrand)) {
 			await emailRenderer.close();
 			emailRenderer = void 0;
 		}
 		previousTheme = themeCss;
+		previousBrand = brand?.digest;
 		emailRenderer?.invalidate();
-		const files = await discoverTemplateFiles(templatesDir);
-		const sourceFiles = await readEmailProject(root);
 		const entries = [];
 		const emailIds = /* @__PURE__ */ new Map();
 		for (const file of files) {
@@ -84,7 +97,11 @@ const createTemplateBuildSession = async (dir, options = {}) => {
 				const preview = await (async () => {
 					emailRenderer ??= await createEmailRenderer({
 						assetBase: options.assetBase ?? "",
-						...themeCss === void 0 ? {} : { tailwind: { css: themeCss } }
+						...themeCss === void 0 || themeFile === void 0 ? {} : { tailwind: {
+							css: themeCss,
+							cssPath: themeFile
+						} },
+						...brand === void 0 ? {} : { brand }
 					});
 					const loaded = await emailRenderer.load(sourceFiles, entryPath, entryPath);
 					const template = loaded.template;
@@ -106,7 +123,7 @@ const createTemplateBuildSession = async (dir, options = {}) => {
 						},
 						diagnostics: fixture.diagnostics
 					}));
-					const diagnostics = [...loaded.compiled.diagnostics];
+					const diagnostics = [...brandFindings, ...loaded.compiled.diagnostics];
 					if (fixtures.length === 0) diagnostics.push(emailFinding("missing-fixtures", `${template.id} must declare at least one fixture for check and build.`));
 					if (loaded.compiled.assets.length > 0 && options.assetBase === void 0) diagnostics.push(emailFinding("missing-asset-base", "Imported email assets require --asset-base with their HTTPS serving origin."));
 					if (loaded.compiled.assets.length > 0 && options.assetBase !== void 0 && !/^https:\/\//i.test(options.assetBase)) diagnostics.push(emailFinding("invalid-asset-base", "Email check and build require an HTTPS --asset-base; relative URLs belong to templates export."));
@@ -126,7 +143,13 @@ const createTemplateBuildSession = async (dir, options = {}) => {
 							fixtures
 						}]
 					};
-				})().catch(emailFailure);
+				})().catch((cause) => {
+					const failure = emailFailure(cause);
+					return {
+						...failure,
+						diagnostics: [...brandFindings, ...failure.diagnostics]
+					};
+				});
 				entries.push({
 					id: file.id,
 					kind: file.kind,

package/dist/{theme-CBF6Czjm.js → discovery-D2eR-rzi.js}

@@ -1,5 +1,5 @@
-import { readFile, readdir } from "node:fs/promises";
-import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { readdir } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
 //#region src/discovery.ts
 const isTemplateFile = (name) => name.endsWith(".tsx");
 const toPosix = (value) => sep === "/" ? value : value.split(sep).join("/");
@@ -29,22 +29,7 @@ const discoverTemplateFiles = async (dir) => {
 	await walk(dir);
 	return found.sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
 };
-/**
-* Resolves the `theme` plugin option to an absolute path, or `undefined` when
-* theming is explicitly disabled (`theme: false`). A string is taken relative to
-* `root` (absolute strings pass through); the default is `<root>/theme.css`.
-*/
-const resolveThemePath = (root, option) => {
-	if (option === false) return void 0;
-	const file = option ?? "theme.css";
-	return isAbsolute(file) ? file : resolve(root, file);
-};
-/** Read authored Tailwind CSS verbatim; the email compiler validates its syntax. */
-const readProjectThemeCss = async (path) => path === void 0 ? void 0 : readFile(path, "utf8").catch((cause) => {
-	if (cause.code === "ENOENT") return void 0;
-	throw cause;
-});
 //#endregion
-export { resolveThemePath as n, discoverTemplateFiles as r, readProjectThemeCss as t };
+export { discoverTemplateFiles as t };
 
-//# sourceMappingURL=theme-CBF6Czjm.js.map
+//# sourceMappingURL=discovery-D2eR-rzi.js.map