@formfeed/engine 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Philipp Staudt IT-Dienstleistungen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# @formfeed/engine
+
+The template engine behind [Formfeed](https://formfeed.dev): Jinja2, Liquid and Handlebars templates
+with one set of helpers, compiled and rendered to a complete HTML document. The same package runs
+the web editor's preview, the `formfeed` CLI and Formfeed's render servers, so what it produces
+locally is what the API renders. It works in browsers and Node 22+ and uses no Node-only APIs.
+
+Most projects need the [CLI](https://www.npmjs.com/package/formfeed) and
+[`@formfeed/testing`](https://www.npmjs.com/package/@formfeed/testing) rather than this package. Use
+it to embed template compilation in your own tools, such as a custom preview.
+
+```bash
+npm install @formfeed/engine
+```
+
+```ts
+import { getEngine, defaultHelpers, defaultLimits, assembleDocument } from '@formfeed/engine';
+
+const engine = getEngine('liquid');
+const compiled = engine.compile('<h1>{{ title | upper }}</h1>', {});
+const analysis = engine.analyze('<h1>{{ title | upper }}</h1>');
+// analysis.variables → [{ path: ['title'], ... }], analysis.diagnostics → []
+
+const html = await engine.render(compiled, { title: 'Hello' }, {
+  locale: 'de-DE', timezone: 'Europe/Berlin', currency: 'EUR',
+  partials: async () => null, helpers: defaultHelpers(), limits: defaultLimits,
+});
+
+const document = assembleDocument({ html, css: '', head: '', settings: { paper: { format: 'A4' } }, kind: 'pdf' });
+```
+
+The supported surface is the `Engine` interface (`compile`, `analyze`, `render`) returned by
+`getEngine`, the `defaultHelpers()` registry and `defaultLimits`, plus `assembleDocument`,
+`renderVersion` and `inferSchema`. `compile` throws `EngineSyntaxError` with `line` and `column`.
+
+## What is inside
+
+| Module | Contents |
+|---|---|
+| `engines/` | `jinja2` (Nunjucks with a Python compatibility layer), `liquid` (LiquidJS), `handlebars`, each implementing `Engine` |
+| `helpers/` | One helper registry for all three dialects: formatting (`money`, `date`, `number`, `numToWords`, `t`), text, collections, codes (`qrcode`, `barcode`, `epcQr`), document (`asset`, `pageBreak`, `image`, `chart`) |
+| `analysis/` | Block pairing and sample-data checks behind every `analyze()` |
+| `schema.ts` | `inferSchema(sample)` to JSON Schema 2020-12 |
+| `assemble.ts` | Template settings, print reset, `assembleDocument()` and `renderVersion()` (body, header, footer, title) |
+| `import/` | `importApitemplate()`: converts apitemplate.io templates |
+
+## Documentation
+
+- [Engine package](https://docs.formfeed.dev/devkit/engine-package)
+- [Template languages](https://docs.formfeed.dev/templates/languages) and [helpers](https://docs.formfeed.dev/templates/helpers)
+
+## Licence
+
+MIT