@lutrin/core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Julien Riel
+
+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,154 @@
+# @lutrin/core — the compiler
+
+The engine behind [Lutrin](../../README.md): enriched Markdown (a DSL) →
+PowerPoint `.pptx` or standalone HTML, with the page layout decided by the
+engine. It provides the `lutrin` CLI, and serves as a library for the editor
+hosts (VS Code extension, Obsidian plugin).
+
+Neither output format is privileged: both renderers consume the **same**
+geometric **scene**, in pixels on a 1280 × 720 grid.
+
+## Installation
+
+The package is not published on npm yet. From a clone of the repository:
+
+```bash
+npm install                 # at the root of the monorepo
+npx lutrin --help
+
+npm link -w lutrin          # to call "lutrin" from anywhere
+```
+
+Node ≥ 22 (`engines.node`). The sources are executed as they are (ESM) — no
+build step.
+
+## CLI
+
+```bash
+lutrin build <deck.md> [-o output.pptx|output.html] [--kit <ref>] [--vendor-assets] [--force] [--verbose]
+lutrin preview <deck.md> [--port 4321] [--kit <ref>]
+lutrin validate <deck.md> [--json] [--kit <ref>]
+lutrin vendor <deck.md> [--kit <ref>]
+lutrin inspect <deck.md> [--kit <ref>]
+lutrin config [--kit <ref>] [--unset]
+lutrin kit install <file.deckkit|https://…> [--force] [--name <name>]
+lutrin kit list | remove <name> | create <directory> [-o <file.deckkit>]
+lutrin capabilities [<deck.md>] [--kit <ref>] [--json]
+```
+
+The output format is deduced from the extension of `-o`. `--kit` takes
+precedence over the deck's frontmatter; a bare name designates an installed
+kit, everything else is a path resolved against the current directory.
+
+**`build` does not deliver a deck in error.** If validation returns at least
+one diagnostic of severity `error` — unknown directive, non-existent layout,
+kit requested EXPLICITLY (`--kit` or the frontmatter's `kit:`) but
+unresolvable — the command prints the errors, exits with **exit code 1** and
+writes no file. `--force` compiles anyway, errors on screen, and exits with
+code 0: that is for a draft one wants to see. A kit coming from an
+**implicit** default (project, user, host) and not found stays a mere
+warning, and does not prevent compilation.
+
+Exit codes: `0` success; `1` error — invalid argument or flag, input file not
+found, explicit kit unresolvable, deck carrying `error` diagnostics (except
+`build --force`). `validate` exits with 1 as soon as one `error` remains;
+`inspect`, `vendor` and `capabilities` do not open the deck's diagnostics and
+exit with 0 — with the one reservation that an explicit unresolvable kit
+stops them too, with 1.
+
+The DSL is documented in [docs/dsl.md](../../docs/dsl.md). `lutrin
+capabilities` reports as JSON what the **installed** engine actually supports
+(layouts, parameters, directives, chart types, diagnostic codes): it is the
+source to query rather than to guess at.
+
+Its scope depends on what it is given:
+
+| Form | What is published |
+|---|---|
+| `lutrin capabilities` | the **bare** engine — built-in layouts and the official catalog; `userLayouts` always empty |
+| `lutrin capabilities <deck.md>` | in addition: the frontmatter's `kit:` honoured, its layouts, and the `layouts/*.json` next to the deck |
+| `lutrin capabilities --kit <ref>` | the catalog of that brand, with the current directory serving as the base |
+
+`--kit` takes precedence over the frontmatter's `kit:`, as it does for every
+other command (`--theme` remains a deprecated alias). A kit requested
+explicitly and unresolvable exits with **exit code 1** without writing
+anything to stdout — never a generic catalog delivered in silence. A
+`layouts/*.json` that could not be read produces a warning on **stderr**:
+stdout stays pure JSON, usable by `jq`. `--json` is the explicit form of the
+default, and has no effect.
+
+## API
+
+The package is ESM and exposes subpath entry points:
+
+```js
+import { compileHtml } from '@lutrin/core/html';
+
+const { html, stats } = await compileHtml(markdown, { baseDir });
+// { fragment: true } → { slides, css, fontsCss, … } for a webview
+```
+
+| Subpath | Contents |
+|---|---|
+| `@lutrin/core`, `/html` | `renderDeckHtml`, `compileHtml` — standalone HTML or fragment |
+| `/pptx` | `renderDeck` — writing the `.pptx` |
+| `/parse` | `parseDeck` — Markdown → IR |
+| `/layout` | `buildScenes`, `blockHeight`, the layout registry |
+| `/validate` | `validateDeck`, `capabilities` |
+| `/context` | `prepareDeckContext` — kit + layouts, to be called before `buildScenes` |
+| `/theme` | `resolveTheme`, `applyTheme`, WCAG contrast |
+| `/tokens` | the living design tokens |
+
+Mandatory call order for a host: `parseDeck` →
+`prepareDeckContext(meta, { baseDir, themePath, defaultTheme })` →
+`buildScenes` → renderer. The tokens and the layout registry are module state
+mutated in place; `prepareDeckContext` resets them on every compilation,
+which makes a warm process (worker, preview server) safe between two decks.
+
+## The pipeline
+
+```text
+Markdown → AST (markdown-it) → IR → layout engine → scene → renderer
+```
+
+| File | Role |
+|---|---|
+| `src/deck/parse.mjs` | Markdown → IR (`deck → slides → sections → blocks`, with the source line) |
+| `src/deck/layout.mjs` | layout inference, placement in regions, pagination; the layout registry |
+| `src/deck/validate.mjs` | positioned diagnostics (`validateDeck`) and `capabilities()` |
+| `src/deck/context.mjs` | the single insertion point for the kit and the layouts |
+| `src/deck/theme.mjs` | resolution and validation of a theme, WCAG contrast |
+| `src/deck/kit.mjs` | the `kit.json` manifest — reading, validation, internal paths |
+| `src/deck/tokens.mjs` | design tokens of the generic design (mirror of `design/themes/default.json`) |
+| `src/deck/chart.mjs` | `chart` blocks → SVG in the theme's style |
+| `src/deck/assets.mjs` | remote images, Lucide icons, LaTeX, Mermaid (cache `~/.cache/lutrin/`) |
+| `src/deck/highlight.mjs` | syntax highlighting of code blocks |
+| `src/deck/suggest.mjs` | did you mean…? (edit distance) |
+| `src/pptx/render.mjs` | scene → PptxGenJS |
+| `src/pptx/fonts.mjs` | embedding the theme's TTFs into the `.pptx` |
+| `src/pptx/anim.mjs` | native animations (`<p:timing>`, one effect per block type) |
+| `src/pptx/morph.mjs` | Morph transition of "(cont.)" slides |
+| `src/html/render.mjs` | scene → standalone HTML document (+ fragment mode) |
+| `src/kit/archive.mjs` | `.deckkit` archives — package, download, install |
+| `src/worker/worker.mjs` | IPC worker of the editor hosts (types in `protocol.d.ts`) |
+| `src/vendor.mjs` | `lutrin vendor` — freezing the deck's external dependencies |
+| `design/themes/default.json` | canonical mirror of the default theme, a template to copy |
+| `design/layouts/*.json` | the catalog of the ten official layouts |
+
+`src/deck/` is the core: it knows no output format and imports no backend
+library — `test/boundary.test.mjs` verifies it.
+
+## Tests
+
+```bash
+npm test -w @lutrin/core
+UPDATE_GOLDEN=1 npm test    # from the root, after an intended engine change
+```
+
+A `node:test` harness, with no test dependency. See
+[CONTRIBUTING.md](https://github.com/julien-riel/lutrin/blob/main/CONTRIBUTING.md).
+
+## License
+
+MIT. Third-party dependencies:
+[THIRD-PARTY-NOTICES.md](https://github.com/julien-riel/lutrin/blob/main/THIRD-PARTY-NOTICES.md).

package/design/layouts/before-after.json

@@ -0,0 +1,6 @@
+{
+  "name": "before-after",
+  "base": "comparison",
+  "sections": { "min": 2, "max": 2 },
+  "description": "Current state, understated, on the left; target highlighted on the right."
+}

package/design/layouts/funnel.json

@@ -0,0 +1,6 @@
+{
+  "name": "funnel",
+  "base": "layers",
+  "shape": "funnel",
+  "description": "Volumes narrowing step by step — conversion, request triage."
+}

package/design/layouts/journey.json

@@ -0,0 +1,5 @@
+{
+  "name": "journey",
+  "base": "steps",
+  "description": "The path of a request or a user: steps joined by arrows."
+}

package/design/layouts/key-message.json

@@ -0,0 +1,5 @@
+{
+  "name": "key-message",
+  "base": "focus",
+  "description": "A single message: one large figure or key sentence, full frame, context underneath."
+}

package/design/layouts/portfolio.json

@@ -0,0 +1,8 @@
+{
+  "name": "portfolio",
+  "base": "grid",
+  "cols": 3,
+  "sections": { "min": 2, "max": 6 },
+  "headed": true,
+  "description": "Projects or services as a mosaic — one header per card."
+}

package/design/layouts/priority-matrix.json

@@ -0,0 +1,7 @@
+{
+  "name": "priority-matrix",
+  "base": "grid",
+  "sections": { "min": 4, "max": 4 },
+  "cols": 2,
+  "description": "A 2 × 2 effort / impact matrix — trade-offs in four quadrants."
+}

package/design/layouts/pros-cons.json

@@ -0,0 +1,6 @@
+{
+  "name": "pros-cons",
+  "base": "comparison",
+  "panels": ["success", "danger"],
+  "description": "Weighing a decision: arguments for (green panel) / against (red panel)."
+}

package/design/layouts/pyramid.json

@@ -0,0 +1,6 @@
+{
+  "name": "pyramid",
+  "base": "layers",
+  "shape": "pyramid",
+  "description": "A hierarchy from apex to foundations — bands growing wider."
+}

package/design/layouts/risk-map.json

@@ -0,0 +1,8 @@
+{
+  "name": "risk-map",
+  "base": "grid",
+  "sections": { "min": 4, "max": 4 },
+  "cols": 2,
+  "kinds": ["success", "warning", "warning", "danger"],
+  "description": "Probability / severity: tinted quadrants, from green (low) to red (critical)."
+}

package/design/layouts/roadmap.json

@@ -0,0 +1,6 @@
+{
+  "name": "roadmap",
+  "base": "timeline",
+  "orientation": "vertical",
+  "description": "Dated milestones of a plan, in a column — axis on the left, dates and content on the right."
+}

package/design/themes/default.json

@@ -0,0 +1,159 @@
+{
+  "name": "Slate (generic default theme)",
+  "colors": {
+    "primary": "1D4ED8",
+    "primaryLighter": "60A5FA",
+    "primaryDarker": "1E3A8A",
+    "brand": "1D4ED8",
+    "brandBlack": "111827",
+    "neutralPrimary": "212529",
+    "neutralSecondary": "637381",
+    "neutralTertiary": "ADB2BD",
+    "neutralStroke": "CED4DA",
+    "underground1": "F8F9FA",
+    "underground2": "DEE2E6",
+    "ground": "FFFFFF",
+    "highlightLight": "EFF6FF",
+    "highlightStrong": "DBEAFE",
+    "informative": "0079C4",
+    "informativeDark": "004B7B",
+    "informativeLight": "E6F5F9",
+    "positive": "0DA566",
+    "positiveDark": "025D29",
+    "positiveLight": "E7F6F0",
+    "warning": "FFB833",
+    "warningDark": "6C4600",
+    "warningLight": "FEFAE6",
+    "negative": "D3310A",
+    "negativeDark": "851A00",
+    "negativeLight": "FFEBE6"
+  },
+  "fonts": {
+    "body": "Arial",
+    "mono": "Courier New"
+  },
+  "type": {
+    "coverTitle": 40,
+    "coverSubtitle": 20,
+    "sectionTitle": 32,
+    "slideTitle": 26,
+    "sectionHeading": 16,
+    "lead": 16,
+    "body": 14,
+    "bullet": 14,
+    "bulletNested": 13,
+    "small": 11,
+    "caption": 9,
+    "code": 11,
+    "metricValue": 44,
+    "metricLabel": 12,
+    "quote": 22,
+    "tableBody": 12,
+    "tableHeader": 12
+  },
+  "space": {
+    "xs": 8,
+    "sm": 16,
+    "md": 24,
+    "lg": 32,
+    "xl": 40,
+    "xxl": 48
+  },
+  "page": {
+    "margin": 48,
+    "gutter": 24,
+    "titleHeight": 96,
+    "footerHeight": 32
+  },
+  "rounded": {
+    "sm": 2,
+    "md": 4,
+    "lg": 8,
+    "pill": 64
+  },
+  "chrome": {
+    "cover": {
+      "barY": 280,
+      "barW": 96,
+      "barH": 6,
+      "titleY": 304,
+      "titleH": 120,
+      "subtitleY": 424,
+      "subtitleH": 72,
+      "bylineBottom": 80,
+      "bylineH": 32,
+      "logoH": 44
+    },
+    "section": {
+      "titleY": 288,
+      "titleH": 144,
+      "logoH": 32
+    },
+    "title": {
+      "accentW": 64,
+      "accentH": 4
+    },
+    "footer": {
+      "textW": 600,
+      "h": 24,
+      "numW": 64
+    }
+  },
+  "chartColors": [
+    "0A8A76",
+    "B87F00",
+    "0079C4",
+    "D3310A",
+    "005E99",
+    "8A5C00"
+  ],
+  "layerShades": [
+    {
+      "fill": "1E3A8A",
+      "ink": "FFFFFF"
+    },
+    {
+      "fill": "1D4ED8",
+      "ink": "FFFFFF"
+    },
+    {
+      "fill": "60A5FA",
+      "ink": "212529"
+    },
+    {
+      "fill": "DBEAFE",
+      "ink": "1E3A8A"
+    },
+    {
+      "fill": "EFF6FF",
+      "ink": "1E3A8A"
+    }
+  ],
+  "trendInk": {
+    "positive": "025D29",
+    "negative": "851A00",
+    "neutral": "637381"
+  },
+  "semantic": {
+    "info": {
+      "fill": "E6F5F9",
+      "text": "004B7B",
+      "label": "Info"
+    },
+    "success": {
+      "fill": "E7F6F0",
+      "text": "025D29",
+      "label": "Key point"
+    },
+    "warning": {
+      "fill": "FEFAE6",
+      "text": "6C4600",
+      "label": "Caution"
+    },
+    "danger": {
+      "fill": "FFEBE6",
+      "text": "851A00",
+      "label": "Important"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@lutrin/core",
+  "version": "1.0.0",
+  "description": "Markdown → PowerPoint / HTML presentation compiler, themable: a generic default theme, organization brand kits distributed as .deckkit archives.",
+  "type": "module",
+  "scripts": {
+    "test": "node --import ./test/setup.mjs --test \"test/*.test.mjs\""
+  },
+  "files": ["src", "design", "README.md"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/html/render.mjs",
+    "./cli": "./src/cli.mjs",
+    "./html": "./src/html/render.mjs",
+    "./parse": "./src/deck/parse.mjs",
+    "./layout": "./src/deck/layout.mjs",
+    "./pptx": "./src/pptx/render.mjs",
+    "./validate": "./src/deck/validate.mjs",
+    "./tokens": "./src/deck/tokens.mjs",
+    "./theme": "./src/deck/theme.mjs",
+    "./context": "./src/deck/context.mjs"
+  },
+  "dependencies": {
+    "@resvg/resvg-js": "^2.6.2",
+    "jszip": "^3.10.1",
+    "lucide-static": "^1.24.0",
+    "markdown-it": "^14.3.0",
+    "markdown-it-container": "^4.0.0",
+    "mathjax-full": "^3.2.1",
+    "pptxgenjs": "4.0.1"
+  },
+  "peerDependencies": {
+    "@mermaid-js/mermaid-cli": "^11.16.0"
+  },
+  "peerDependenciesMeta": {
+    "@mermaid-js/mermaid-cli": {
+      "optional": true
+    }
+  },
+  "keywords": ["markdown", "powerpoint", "pptx", "slides", "presentation", "deck", "html"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/julien-riel/lutrin.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/julien-riel/lutrin/issues"
+  },
+  "homepage": "https://github.com/julien-riel/lutrin#readme",
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "author": "Julien Riel"
+}