@samva/vite 0.5.0 → 0.7.0

package/AGENTS.md

@@ -1,88 +1,87 @@
-# 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.
 
-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.

package/README.md

@@ -152,5 +152,3 @@ Export writes `templates/<id>/<fixture>.html` and `.txt`, content-addressed file
 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.