From 812bf9738d1637678410c9b03f3d0d4f5215c31f Mon Sep 17 00:00:00 2001 From: Arthur Tkachenko Date: Mon, 12 Oct 2026 01:27:15 +0300 Subject: [PATCH 1/2] docs: note Lit adapter pattern and render-template dependency caveats --- README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/README.md b/README.md index eb59165..c413f75 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,14 @@ Requires **Node.js 24+**. No runtime dependencies. No template registry. Strings - Full API: [llms-full.txt](./llms-full.txt) - Sample: [examples/compose.ts](./examples/compose.ts) +## Package ecosystem and Lit + +This package builds on `@llazyemail/render-template` (currently pinned via GitHub ref in `package.json`). Parts must return **strings**. Lit `TemplateResult`s are not supported inside parts. + +Consumers that still use Lit SSR (e.g. `_playing_with_lit`) keep a thin local adapter (`renderEmailBody` + `stripLitMarkers`) that turns a Lit result into a string, then pass that string into `document` / `renderTemplate` / `renderEmail`. Do not try to put Lit templates directly into a part `render` function — that is a known source of runtime errors. + +Generation/catalog/write logic belongs in `@llazyemail/generate-template`, not here. + ## Install Published to GitHub Packages. Copy [`.npmrc.example`](./.npmrc.example) to `.npmrc` in the consuming project. `GITHUB_TOKEN` needs `read:packages`. From 47fad95b8eea5ee9b5c89f16929060d1c1708518 Mon Sep 17 00:00:00 2001 From: Arthur Tkachenko Date: Mon, 12 Oct 2026 01:27:33 +0300 Subject: [PATCH 2/2] docs(agents): document Lit adapter requirement and render-template string contract --- AGENTS.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 550cef6..8ca9d38 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,6 +4,12 @@ The package is stateless, so loading the ESM and CJS builds in one process is safe. +## Lit and render-template notes + +Parts must return strings. The package depends on `@llazyemail/render-template` (see `package.json`). Lit `TemplateResult` objects cannot be returned from a part `render` function. Consumers that still author with Lit keep a local `renderEmailBody` / `stripLitMarkers` step that produces a string, then feed that string into the shell helpers or `renderTemplate`. + +Do not vendor or reimplement the part/compose runtime; use the re-exports from this package or from `render-template` directly. Generation logic belongs in `@llazyemail/generate-template`. + ## Commands ```bash