From 1c39e3d9e6d5494f16f0929e38bc7491ea4715df Mon Sep 17 00:00:00 2001 From: Arthur Tkachenko Date: Mon, 12 Oct 2026 01:27:39 +0300 Subject: [PATCH 1/2] docs: add AGENTS.md with string-only part contract and ecosystem boundaries --- AGENTS.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..1b1bdb2 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,32 @@ +# Agent notes for render-template + +`@llazyemail/render-template` is the low-level deterministic part/compose renderer. Parts return strings. The package is stateless. It is the foundation under `@llazyemail/template-runtime-display`. + +## String-only contract + +Every part `render` function must return a string (or null/undefined, which become `''`). Returning a Lit `TemplateResult`, a Promise, or any other non-string is an error. This is the most common source of problems when mixing this runtime with Lit SSR. + +Consumers that author with Lit must convert the Lit result to a string *before* handing HTML to a part or to `compose`. Do not put Lit templates inside parts. + +## Ecosystem + +- This package owns the part execution, traces, and error modes (`throw` / `collect`). +- `@llazyemail/template-runtime-display` adds email shell fragments and re-exports the runtime helpers. +- `@llazyemail/generate-template` owns catalogs, payloads, and disk writes. Do not add generation logic here. + +## Commands + +```bash +npm install +npm run build +npm test +npm run typecheck +``` + +Node >= 22. CI runs on 22 and 24. + +## Layout + +See README.md for the tree. Public surface is `src/index.ts`. + +Do not add Lit as a dependency. Do not add I/O. Keep the package free of template catalogs. From 4f48a85ef7af6635cdda502e6960ddb6694d51ee Mon Sep 17 00:00:00 2001 From: Arthur Tkachenko Date: Mon, 12 Oct 2026 01:27:48 +0300 Subject: [PATCH 2/2] docs: emphasize string-only parts and add agent pointer --- README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/README.md b/README.md index c737b40..d8c404c 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,11 @@ returns the final HTML. optional `error`. - **Two error modes** — fail fast (`'throw'`) or collect-and-continue (`'collect'`). +- **String parts only** — each part must return a string. Lit `TemplateResult`s, + Promises, or other non-strings are errors. Convert Lit output to a string + before it reaches a part. + +Working on this repo with an AI agent? Start at [AGENTS.md](./AGENTS.md). ## Install @@ -76,6 +81,9 @@ All public types are re-exported from the package root: - `template-runtime-display` — email shell helpers (`defineEmailTemplate`, `renderEmail`) on top of this runtime. +- `generate-template` — catalog, payload resolution, and disk writes. Consumers + should inject their render functions into `createGenerator` rather than + reimplementing generation logic. ## License