gina 0.4.8-alpha.1 → 0.5.0

package/CHANGELOG.md

@@ -6,6 +6,12 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 0.5.0 - 2026-06-11
+### Added
+* ESM compatibility layer (#M10): package.json now declares an "exports" map with dual CJS/ESM entry points — `import gina from 'gina'` and `import gna from 'gina/gna'` work natively in ESM projects and modern bundlers (default exports only; the gina/gna getter semantics are preserved). CJS `require()` resolution is byte-identical to before, and TypeScript declarations keep resolving via per-entry "types" conditions. The documented public surface is the bare specifier, ./gna and ./package.json; undeclared deep subpaths are no longer resolvable.
+* Extension-keyed template-engine dispatch (#M11): a single bundle can now mix swig and nunjucks — a templates.json section declaring `"ext": ".njk"` (or a `self.setTemplate(file, '.njk')` call) renders through nunjucks and `".swig"` through swig, regardless of the bundle-level `render.engine` setting; `.html` and any other extension keep following `render.engine`, so existing bundles are unchanged. Bundles with `.njk` sections get the same fail-fast NUNJUCKS_NOT_INSTALLED startup check as `render.engine: "nunjucks"` bundles.
+* Nunjucks Inspector parity (#M11): dev-mode nunjucks pages now render the Inspector statusbar (the statusbar template is rendered through nunjucks and spliced post-render with a dollar-safe function replacer) and expose the query log as `data.page.queries` alongside the already-piped flow timeline — the Inspector Queries tab no longer renders empty for nunjucks bundles. Closes the within-Inspector parity gaps against the swig render path.
+
 ## 0.4.7 - 2026-06-11
 ### Added
 * Csp plugin: new opt-in reportOnlyOmit option — an array of directive names to omit from a Content-Security-Policy-Report-Only header and emit again automatically when reportOnly flips to false, so one directive set covers both modes. Built for engine-divergent directives such as frame-ancestors (reported in report-only by Chrome and Firefox, ignored with a console warning by Safari/WebKit): a bundle can trade the Gecko/Blink report signal for a clean WebKit console as an explicit, lifecycle-managed choice. Entries are validated against the CSP Level 3 whitelist, a factory-time warning names what was dropped, and the default output is unchanged.

package/README.md

@@ -22,7 +22,7 @@ Node.js MVC framework with built-in HTTP/2, multi-bundle architecture, and scope
 | ORM / entities | EventEmitter-based entity system; SQL files auto-wired to entity methods |
 | Connectors | Couchbase, MongoDB, ScyllaDB / Cassandra, MySQL, PostgreSQL, Redis, SQLite, AI (LLM) — loaded from project `node_modules` |
 | AI connector | Any LLM provider via named protocol (`anthropic://`, `openai://`, `ollama://`, …) |
-| Template engine | [`@rhinostone/swig`](https://github.com/gina-io/swig) 2.7.2 — maintained fork with CVE-2023-25345 patched; streaming SSE/chunked via `renderStream()`. Nunjucks supported as opt-in via `render.engine = "nunjucks"` |
+| Template engine | [`@rhinostone/swig`](https://github.com/gina-io/swig) 2.7.2 — maintained fork with CVE-2023-25345 patched; streaming SSE/chunked via `renderStream()`. Nunjucks supported as opt-in via `render.engine = "nunjucks"` or per-section `"ext": ".njk"` |
 | Internationalisation | Per-bundle JSON catalogs, `t()` helper, swig + nunjucks `t` filter, CLDR plurals, ICU MessageFormat opt-in via `t.icu()` |
 | Observability | Built-in `/_gina/metrics` Prometheus endpoint (opt-in, IP-allowlisted) — Node.js process metrics + HTTP counter / duration histogram with cardinality-safe route labels |
 | Hot reload | WatcherService evicts `require.cache` only on file change — zero per-request overhead in dev |
@@ -39,12 +39,11 @@ gina bundle:start api @myproject
 open https://localhost:3100
 ```
 
-## What's in 0.4.7
+## What's in 0.5.0
 
-- **WebSocket over HTTP/2 (opt-in).** HTTP/2 bundles can serve WebSocket endpoints over the RFC 8441 extended-CONNECT transport, with a built-in dependency-free RFC 6455 framing codec — no external WebSocket library. Enable with `http2Options.enableConnectProtocol: true`, then register handlers from `onInitialize` with `app.onWebSocket(path, handler)`: each accepted stream arrives as a session with a `send`/`ping`/`close` API, automatic pong replies, payload and fragment caps, and a graceful close handshake.
-- **HTTP/2 hardening parity for h2c.** Cleartext HTTP/2 bundles (for example, backends behind a TLS-terminating reverse proxy) now receive the same hardening as `https` bundles — the stream caps, session flood defenses, and `settings.json` `http2Options` overrides all apply, where previously such bundles ran protocol defaults (effectively unlimited concurrent streams with server push enabled) and silently ignored their overrides.
-- **Graceful shutdown for live sockets.** Bundles with open WebSocket or engine.io connections no longer block SIGTERM shutdown until the hard timeout — every live socket is closed cleanly before the HTTP server closes, WebSockets with a `1001 going away` close handshake.
-- **CSP `reportOnlyOmit` (opt-in).** Omit engine-divergent directives such as `frame-ancestors` from `Content-Security-Policy-Report-Only` headers and have them restored automatically when `reportOnly` flips to `false` — one directive set across both modes, validated against the CSP Level 3 whitelist.
+- **Native ESM entry points.** `package.json` now declares an `"exports"` map with dual CJS/ESM entries — `import gina from 'gina'` and `import gna from 'gina/gna'` work natively in ESM projects and modern bundlers (default exports only; the `gina/gna` getters resolve at access time, after framework boot). CJS `require()` resolution is byte-identical to before, and TypeScript declarations keep resolving through per-entry `types` conditions. Note: with the `exports` map in place, the package's Node-resolvable surface is exactly `gina`, `gina/gna`, and `gina/package.json` — undeclared deep subpaths are no longer resolvable.
+- **Mixed template engines per bundle.** A `templates.json` section declaring `"ext": ".njk"` (or a `self.setTemplate(file, '.njk')` call) renders through nunjucks and `".swig"` through swig — regardless of the bundle-level `render.engine` setting. `.html` and any other extension keep following `render.engine`, so existing bundles are unchanged. Bundles with `.njk` sections get the same fail-fast `NUNJUCKS_NOT_INSTALLED` startup check as nunjucks-engine bundles.
+- **Nunjucks Inspector parity (dev mode).** Dev-mode nunjucks pages now render the Inspector statusbar and expose the query log as `data.page.queries` alongside the flow timeline — the Inspector Queries tab no longer renders empty for nunjucks bundles.
 
 See the full [Changelog](./CHANGELOG.md) and [Roadmap](./ROADMAP.md).
 

package/ROADMAP.md

@@ -24,7 +24,8 @@ This roadmap covers planned features, architectural improvements, new connectors
 | **Q2 2026** | `0.3.9` ✅ | Consumer-feedback batch (11 framework patches): per-request middleware dispatch isolation · Couchbase 4.x JsonTranscoder · `length` filter null safety · `process.env` mirroring · 6 nunjucks render-pipeline patches (libRef fallback · namespace prefix drop · bundle filter wraps · top-level userData · `data.data` alias · ginaLoader placeholders) · `getAssets` mid-URL `{{ }}` strip-guard anchor |
 | **Q2 2026** | `0.3.10` ✅ | FormValidator HTML5 form-reassociation hardening trilogy (`HTMLFormControlsCollection`-based `bindForm` + `unbindForm` symmetry · radio mutual-exclusion + IDL/attribute reconciliation · `defaultChecked` cache for reset) · `X-Forwarded-Prefix` reverse-proxy path-prefix awareness |
 | **Q4 2026** | `0.4.0` | AI agents (MCP) · ScyllaDB connector · Advanced tutorial · Website redesign · Docs offline ZIP · Bun investigation · Couchbase v2 removal · Trailer support · CLI Tier 2 (bundle/project status, rename, copy, protocol:remove, minions) |
-| **Q1 2027** | `0.5.0` | ESM support · Template engine migration · Structured logging · Alt-Svc · HTTP/2 priorities · WebSocket over HTTP/2 · Inspector Production · CLI Tier 3 (project:move, framework:update, backup/restore, man pages) |
+| **Q2 2026** | `0.5.0` ✅ | ESM entry points (dual CJS/ESM `exports` map) · Mixed template engines per bundle (extension-keyed `.njk` / `.swig` dispatch) · Nunjucks Inspector parity — the other items originally targeted here shipped earlier: structured logging (`0.4.5`), Alt-Svc (`0.4.2`), WebSocket over HTTP/2 (`0.4.7`), Inspector production auth (`0.4.3`) |
+| **Q1 2027** | `0.5.x` | HTTP/2 priorities (blocked on Node scheduler hooks) · CLI Tier 3 (project:move, framework:update, backup/restore, man pages) · Beemaster admin + visual translation editor |
 | **Q3 2027** | `1.0.0` | First stable release — Windows alpha compatibility is a hard gate |
 
 ---
@@ -117,8 +118,8 @@ Stub commands confirmed in source — handler files exist but are empty or comme
 
 | Status | Feature | Version | Target |
 | --- | --- | --- | --- |
-| 📋 | **ESM compatibility layer** — Dual CJS/ESM entry points via `"exports"` in `package.json`. Framework internals stay CJS; public API gets ESM re-exports. | `0.5.0` | Q1 2027 |
-| 🚧 | **Pluggable template engine** — **Partially shipped in `0.3.7`**: opt-in `render.engine = "nunjucks"` dispatch per bundle. The project installs `nunjucks` itself (no framework dep); Gina loads it via `lib/nunjucks-resolver` and routes through `controller.render-nunjucks.js`. Swig remains the default, runs unchanged. Inspector dev payload, HTTP/2 `stream.respond()` direct path, and error-page template routing all shipped in `0.3.7-alpha.2`. **Closing the parity gap on the `0.3.7` ASAP track** (see Nunjucks Parity below): filter registry port, `setResources` / `<gina>` layout placeholders, static HTML cache parity, Early Hints 103 auto-send. **Remaining `0.5.0` scope**: within-Inspector sub-items (`statusbar.html` include + flow/queries pipelines); per-template-extension dispatch so a single bundle can mix engines (`.swig` / `.njk`); optional auto-detect on `.njk` presence. Breaking syntax differences (`{% parent %}` → `{{ super() }}`, filter renames, `autoescape` default, `date` format strings, no `{% spaceless %}`) are nunjucks's own — Gina doesn't paper over them. | `0.5.0` | Q1 2027 |
+| ✅ | **ESM compatibility layer** — **Shipped**: `package.json` declares an `"exports"` map with dual CJS/ESM entry points. `import gina from 'gina'` and `import gna from 'gina/gna'` work natively in ESM projects and modern bundlers (default exports only — the `gina/gna` getters resolve at access time, after framework boot, so they are passed through as a namespace rather than frozen into named exports). Framework internals stay CJS and `require()` resolution is byte-identical; TypeScript declarations resolve via per-entry `types` conditions. The documented public surface is the bare specifier, `./gna`, and `./package.json` — undeclared deep subpaths are no longer resolvable. | `0.5.0` | 2026-06-11 |
+| ✅ | **Pluggable template engine** — **Complete**: opt-in `render.engine = "nunjucks"` dispatch per bundle shipped in `0.3.7` (the project installs `nunjucks` itself — no framework dep; Gina loads it via `lib/nunjucks-resolver` and routes through `controller.render-nunjucks.js`; swig remains the default and runs unchanged), followed by the four-session parity track (filter registry, `setResources` / `<gina>` layout placeholders, static HTML cache, Early Hints 103) and the `0.3.9` consumer-feedback patches. **The `0.5.0` scope shipped 2026-06-11**: per-template-extension dispatch — a templates.json section declaring `"ext": ".njk"` (or a `self.setTemplate(file, '.njk')` call) renders through nunjucks and `".swig"` through swig regardless of the bundle-level `render.engine`, so a single bundle can mix engines with no new config keys (`.html` keeps following `render.engine`; bundles with `.njk` sections get the same fail-fast NUNJUCKS_NOT_INSTALLED startup check); nunjucks Inspector parity — the dev statusbar and the query log (`data.page.queries`) now ship alongside the flow timeline. Auto-detect on `.njk` presence was dropped: explicit per-section `ext` config covers the use case without init-time filesystem magic. Breaking syntax differences (`{% parent %}` → `{{ super() }}`, filter renames, `autoescape` default, `date` format strings, no `{% spaceless %}`) are nunjucks's own — Gina doesn't paper over them. | `0.5.0` | 2026-06-11 |
 | ✅ | **Structured logging** — **Shipped in `0.4.5`**: set `GINA_LOG_FORMAT=json` for one machine-parseable object per log line (`{ ts, level, bundle, message }`); the coloured, human-readable format stays the default, so `docker logs` is unchanged. Additive — existing consumers are unaffected. Enables log aggregation (Loki, Datadog, CloudWatch). When JSON output is on, every line emitted during a request also carries per-request `requestId` (honouring an inbound `X-Request-Id` when well-formed, else generated) and `durationMs` for correlation. | `0.4.5` | 2026-06-06 |
 | ✅ | **Research `AsyncLocalStorage` for request context** — Concluded (2026-06-06): a full `local`→`AsyncLocalStorage` migration was evaluated and **declined** (per-request isolation already exists via per-request controller instances; the hot closure paths get *more* fragile under `getStore()`). The one win — a narrow always-on `{ requestId, startMs }` context — shipped in `0.4.5` as the substrate for the per-request log fields above. | `0.4.5` | 2026-06-06 |
 

package/framework/v0.5.0/VERSION

@@ -0,0 +1 @@
+0.5.0

package/framework/{v0.4.8-alpha.1 → v0.5.0}/core/controller/controller.js

@@ -1199,6 +1199,41 @@ function SuperController(options) {
             }
         } catch (e) { /* fall back to default 'swig' */ }
 
+        // #M11 — extension-keyed engine dispatch. An explicit template
+        // extension is an unambiguous engine signal, so a single bundle can
+        // mix engines per section (templates.json `ext`) or per
+        // `self.setTemplate(file, ext)` call: `.njk` renders through
+        // nunjucks, `.swig` through swig. The precedence mirrors the
+        // delegates' own resolution (setTemplate override ext first, then
+        // the rule's template ext) so the dispatch can never disagree with
+        // the file the delegate resolves; the ambiguous `.html` default —
+        // and any other extension — keeps following `render.engine` above,
+        // which leaves every existing bundle byte-unchanged.
+        // initNunjucksEngine scans templates.json for `.njk` sections so a
+        // mixed bundle still fails fast at startup when the project lacks
+        // nunjucks; a pure-runtime `.njk` switch (setTemplate on a bundle
+        // with no `.njk` config at all) surfaces the resolver's explicit
+        // "get() called before load()" error instead.
+        try {
+            var _effExt = null;
+            if ( local.options && local.options._templateOverride && local.options._templateOverride.ext ) {
+                _effExt = local.options._templateOverride.ext;
+            } else if ( local.options && local.options.template && local.options.template.ext ) {
+                _effExt = local.options.template.ext;
+            }
+            if (_effExt) {
+                _effExt = String(_effExt).toLowerCase();
+                if ( !/^\./.test(_effExt) ) {
+                    _effExt = '.' + _effExt;
+                }
+                if (_effExt === '.njk') {
+                    _engine = 'nunjucks';
+                } else if (_effExt === '.swig') {
+                    _engine = 'swig';
+                }
+            }
+        } catch (e) { /* keep the settings-level engine */ }
+
         var _delegate;
         if (_engine === 'nunjucks') {
             // #TPL1 — a nunjucks bundle with a configured async loader renders

package/framework/{v0.4.8-alpha.1 → v0.5.0}/core/controller/controller.render-nunjucks.js

@@ -26,14 +26,14 @@
  *      + `<script>window.__ginaLogs = ...</script>` are injected before `</body>`
  *      in dev mode, redacted via `lib/inspector-redact`, stashed on
  *      `self.serverInstance._lastGinaData`, and emitted via
- *      `process.emit('inspector#data')`. Within this port, **statusbar.html
- *      inclusion is still deferred** — the swig template uses `{% include %}`
- *      with swig-specific syntax; a nunjucks-compatible statusbar template
- *      is a separate follow-up. `data.page.flow` (flow timeline from
- *      `local._timeline`) and `data.page.queries` (query log from
- *      `local._queryLog`) are also not yet piped into the Inspector payload
- *      — the data is computed in render-swig.js around lines 980-1040 and
- *      belongs in a shared helper before porting.
+ *      `process.emit('inspector#data')`. The within-port follow-ups shipped
+ *      with #M11: the dev statusbar.html body — a leaf with only `{% if %}`
+ *      / `{{ }}` tags, valid nunjucks — is rendered through the resolver
+ *      module's `renderString()` and spliced post-render (render-swig
+ *      inlines the same body into the layout pre-compile — #TPL2), and both
+ *      `data.page.flow` (flow timeline from `local._timeline`) and
+ *      `data.page.queries` (query log from `local._queryLog`) are piped
+ *      into the Inspector payload inside `injectInspectorScripts()`.
  *   2. ~~**HTTP/2 `stream.respond()` direct path**~~ — **shipped 2026-04-22**
  *      (commit TBD). `sendHtmlResponse` now implements the four-way branch
  *      from `class.controller.md §7b` (HEAD×stream, HEAD×HTTP1.1, body×stream,
@@ -230,12 +230,12 @@ function resolveTemplatePath(data, localOptions) {
         if (effective === localOptions.namespace) {
             effective = 'index';
         }
-        // FRAMEWORK PATCH: drop redundant `<namespace>-` prefix
-        // from the file segment when present, so `project/project-get.njk`
-        // resolves to `project/get.njk` (and `client/client-list.njk` to
+        // Drop the redundant `<namespace>-` prefix from the file segment
+        // when present, so `project/project-get.njk` resolves to
+        // `project/get.njk` (and `client/client-list.njk` to
         // `client/list.njk`). Lets route names that already carry the
         // namespace (e.g. `project-get`, `client-list`) live at the cleaner
-        // `<namespace>/<action>.njk` path. Push upstream to gina-io/gina.
+        // `<namespace>/<action>.njk` path. Upstreamed in 0.3.9.
         var nsPrefix = localOptions.namespace + '-';
         if (effective.length > nsPrefix.length && effective.indexOf(nsPrefix) === 0) {
             effective = effective.substring(nsPrefix.length);
@@ -252,10 +252,12 @@ function resolveTemplatePath(data, localOptions) {
 }
 
 /**
- * Builds the Inspector dev-payload scripts and injects them into the
- * rendered HTML just before `</body>`. Mirrors render-swig.js:1041-1128
- * but without the `statusbar.html` `{% include %}` (that template is
- * swig-specific — a nunjucks-compatible version is a follow-up).
+ * Builds the Inspector dev-payload scripts + the dev statusbar and injects
+ * them into the rendered HTML just before `</body>`. Mirrors render-swig.js
+ * (#TPL2 inlines the statusbar.html body into the layout pre-compile; here
+ * the engine pass has already happened, so the statusbar body — a leaf with
+ * only `{% if %}` / `{{ }}` tags, valid nunjucks — is rendered through the
+ * resolver module's `renderString()` and spliced as plain HTML).
  *
  * Runs only in dev mode (`self.isCacheless()`), gated by `displayInspector`:
  *
@@ -323,6 +325,13 @@ function injectInspectorScripts(html, data, self, local, displayInspector) {
         };
     }
 
+    // #M11 — Inspector Queries tab parity with render-swig: expose the raw
+    // QI query log alongside the flow-timeline fold-in above, so
+    // `__ginaData.user.queries` exists for nunjucks pages too.
+    if (local._queryLog && local._queryLog.length > 0) {
+        data.page.queries = local._queryLog;
+    }
+
     // Two deep clones — one labelled gina (metadata for the Inspector
     // sidebar), one labelled user (mirrors what application code sees).
     // JSON.parse(JSON.stringify(...)) is intentional: it drops functions,
@@ -450,10 +459,32 @@ function injectInspectorScripts(html, data, self, local, displayInspector) {
         process.emit('inspector#data', __gdPayload);
     } catch (e) { /* listener raised — not fatal to the render */ }
 
+    // #M11 — dev statusbar parity with render-swig. statusbar.html is a leaf
+    // template (only {% if page.cspNonce %} + {{ }} tags — valid nunjucks),
+    // but this helper runs AFTER the engine pass, so the body is rendered
+    // through the resolver module's renderString() and spliced as plain
+    // HTML. Read per-render so dev edits hot-reload; this path is
+    // dev/inspector-gated above, so there is no production read.
+    var _statusbarHtml = '';
+    try {
+        var _statusbarTpl = fs.readFileSync(
+            getPath('gina').core + '/asset/plugin/dist/vendor/gina/html/statusbar.html', 'utf8'
+        );
+        _statusbarHtml = require('../../lib/nunjucks-resolver').get().renderString(_statusbarTpl, data);
+    } catch (_sbErr) {
+        console.warn('[render] Inspector statusbar unavailable: ' + (_sbErr.message || _sbErr));
+    }
+
     // Inject before the first `</body>`. Case-insensitive match; the
     // surrounding newline + tab match render-swig's formatting so the
     // diff against a rendered swig-then-nunjucks page is cosmetic-only.
-    return html.replace(/<\/body>/i, '\t' + __logsScript + __gdScript + '\n\t</body>');
+    // $-safe splice (function replacer): with a STRING replacement,
+    // String.prototype.replace expands dollar patterns — the statusbar body
+    // literally contains two of them, and the JSON payloads can carry them
+    // in user data. The function form returns the text verbatim; mirrors
+    // render-swig.js's #TPL2 splice fix.
+    var _injected = '\t' + __logsScript + __gdScript + _statusbarHtml + '\n\t</body>';
+    return html.replace(/<\/body>/i, function () { return _injected; });
 }
 
 /**

package/framework/{v0.4.8-alpha.1 → v0.5.0}/core/server.js

@@ -414,8 +414,15 @@ function Server(options) {
      * throws NUNJUCKS_NOT_INSTALLED here, terminating bundle startup with
      * a clear error — rendering with a stub would mask the misconfig.
      *
-     * No-op when render.engine is unset or "swig" — the existing swig
-     * engine init handles that case via initSwigEngine below.
+     * No-op when render.engine is unset or "swig" AND no templates.json
+     * section declares a `.njk` extension — the existing swig engine init
+     * handles that case via initSwigEngine below. A bundle whose
+     * settings-level engine is swig can still mix in nunjucks-rendered
+     * sections via per-section templates.json `ext` declarations (#M11:
+     * `.njk` routes through the nunjucks delegate at dispatch time), so
+     * nunjucks is initialised for those bundles too and a missing project
+     * nunjucks install fails at startup instead of 500-ing the first
+     * `.njk` render.
      *
      * @inner
      * @private
@@ -424,7 +431,22 @@ function Server(options) {
     var initNunjucksEngine = function(conf) {
         var _settings = (conf && conf.content && conf.content.settings) || {};
         var _engine = (_settings.render && _settings.render.engine) || 'swig';
-        if (_engine !== 'nunjucks') { return; }
+        // #M11 — extension-keyed mixing: any templates.json section whose
+        // `ext` is `.njk` (or `njk`) dispatches through nunjucks even when
+        // the settings-level engine is swig, so those bundles need the
+        // same fail-fast startup init.
+        var _hasNjkSection = false;
+        try {
+            var _tpls = (conf && conf.content && conf.content.templates) || {};
+            for (var _section in _tpls) {
+                var _sectionExt = _tpls[_section] && _tpls[_section].ext;
+                if ( _sectionExt && /^\.?njk$/i.test(String(_sectionExt)) ) {
+                    _hasNjkSection = true;
+                    break;
+                }
+            }
+        } catch (e) { /* fall through — the settings-level engine decides */ }
+        if (_engine !== 'nunjucks' && !_hasNjkSection) { return; }
         var _nunjucksSettings = _settings.nunjucks || {};
         // load() throws NUNJUCKS_NOT_INSTALLED if the project does not have
         // nunjucks in its node_modules — we intentionally let that propagate

package/framework/{v0.4.8-alpha.1 → v0.5.0}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gina-framework",
-  "version": "0.4.8-alpha.1",
+  "version": "0.4.8-alpha.2",
   "dependencies": {
     "@rhinostone/swig": "^2.7.2",
     "intl-messageformat": "^11.2.4",

package/gna.js

@@ -15,14 +15,14 @@
 'use strict';
 
 // Framework core — the main gna module (lifecycle hooks, lib, etc.)
-var _gna = require('./framework/v0.4.8-alpha.1/core/gna');
+var _gna = require('./framework/v0.5.0/core/gna');
 
 // SuperController and EntitySuper — loaded from their source modules
-var SuperController = require('./framework/v0.4.8-alpha.1/core/controller');
-var EntitySuper     = require('./framework/v0.4.8-alpha.1/core/model/entity');
+var SuperController = require('./framework/v0.5.0/core/controller');
+var EntitySuper     = require('./framework/v0.5.0/core/model/entity');
 
 // uuid — from the lib registry
-var uuid = require('./framework/v0.4.8-alpha.1/lib/uuid');
+var uuid = require('./framework/v0.5.0/lib/uuid');
 
 module.exports = {
 

package/gna.mjs

@@ -0,0 +1,20 @@
+/**
+ * Gina — ESM counterpart of `require('gina/gna')` (#M10)
+ *
+ *   import gna from 'gina/gna';
+ *
+ *   // destructure AFTER framework boot — see below
+ *   const { getContext, getConfig } = gna;
+ *
+ * Default export ONLY, on purpose: the CJS module exposes getter
+ * properties that resolve at ACCESS time (after framework boot). Static
+ * named ESM re-exports would capture `undefined` before boot, so the
+ * getter namespace is passed through untouched.
+ */
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+const gnaHelpers = require('./gna.js');
+
+export default gnaHelpers;

package/index.mjs

@@ -0,0 +1,28 @@
+/**
+ * Gina — ESM entry point (#M10)
+ *
+ * Mirrors `require('gina')` for ESM consumers and modern bundlers:
+ *
+ *   import gina from 'gina';
+ *
+ *   gina.onInitialize(function (event, conf) { ... });
+ *   gina.start();
+ *
+ * Default export ONLY — the framework object is assembled at runtime by
+ * the CJS core (lifecycle hooks, lib registry, plugins), so the namespace
+ * default is the honest ESM surface; static named re-exports would freeze
+ * values at import time.
+ *
+ * The core is resolved through package.json's `main` field so this file
+ * never carries a version-pinned framework path (no version-bump coupling).
+ * Importing outside a spawned bundle child has exactly the semantics of
+ * `require('gina')` there — the framework bootstrap expects the bundle
+ * context and throws without it.
+ */
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+const gna = require(require('./package.json').main);
+
+export default gna;

package/llms.txt

@@ -951,3 +951,7 @@ Dev-mode query instrumentation captures every database query tied to the current
 168. **Never hardcode `framework/v<version>` paths in test fixtures, test harnesses, or CI workflows — derive the dir from `package.json` at runtime; enforced by `test/lib/e2e-no-version-pins.test.js`.** The framework directory is renamed at every release cut (the stable rename plus two alpha bumps), so a version-pinned path is green on every CI run between cuts and breaks exactly at the release — polluting the cut's CI signal — and the tag's tree (merged to master, which only moves via tag merges) then carries a deterministic red until the NEXT tag. Incident shape (v0.4.6): an e2e fixture linked the built stylesheet via a literal `framework/v0.4.6-alpha.2/...` href; both post-rename pushes went red with CSS-initial-value failures (`overflow: visible` where the scroll-lock expects `hidden`, `transition-property: all` where the enter transition expects `opacity`) — the diagnostic tell that the page's JS ran but its stylesheet didn't load. Fix: serve fixtures through `test/e2e/runtime-server.js`, which resolves `framework/v<version>` from `package.json` (the same idiom as the CI workflows' `FW_DIR="framework/v${VERSION}"`). The guard test sweeps `test/e2e/**`, `.github/workflows/**`, and `playwright.config.js` for `framework/v<digit>` literals in the gated suite, so a reintroduced pin fails at commit time instead of at the cut; the regex is digit-anchored so `framework/v<version>` prose, `v${VERSION}` interpolation, and `v*` glob pathspecs never match, and it carries per-directory non-empty-sweep pins so a dir move cannot hollow it into a silent always-green no-op. `gna.js` and the root `package.json` `main` field carry the literal BY DESIGN — the release scripts rewrite them atomically with the dir rename (dir name == `package.json` version at every commit), so they are maintained surfaces, deliberately not swept. A post-rename pre-publish Playwright smoke was measured and declined: with zero literals enforced, every committed tree is rename-consistent by construction, and dist staleness (the other tag-tree drift class) is the bundle-freshness gate's job. Established 2026-06-11 (commits `37281177` + `26ff8e83`).
 
 169. **WebSocket over HTTP/2 shipped (develop 2026-06-11, target `0.5.0`; commits `a1bf4d95` transport + `a5f29e5f` codec + `f6ebca90` bridge/API).** Three layers, each with a measured lesson. (1) Transport (Isaac engine): strict `=== true` opt-in `http2Options.enableConnectProtocol` — a boolean settings key must NEVER reuse the `|| default` idiom of its numeric siblings (the string `"true"` or `1` must not flip a SETTINGS advert); the key lives in the `http2Options.settings` literal, which reaches `createSecureServer` (https) and the cleartext `createServer` branches alike since the h2c flood-defense parity fix (2026-06-11 — before it, the cleartext branches passed a bare `{ allowHTTP1 }` literal, dropping the SETTINGS advert AND the session flood caps `maxSessionRejectedStreams`/`maxSessionInvalidFrames`, so h2c bundles ran protocol-default limits — effectively unlimited concurrent streams, server push enabled — and silently ignored their settings.json `http2Options` overrides; passing `http2Options` verbatim is safe because TLS material only merges under `/https/` scheme gates). **Extended-CONNECT streams must be handled on the compat `connect` event, not `session.on('stream')`** — Node's http2 compat layer auto-responds 405 to every CONNECT stream and its internal listener is attached at session setup, before any userland session-level listener, so a stream-handler design loses the race with `ERR_HTTP2_HEADERS_SENT`. Registering a `connect` listener suppresses that auto-405 for ALL CONNECT, so every handler path must terminate the stream (an unanswered CONNECT hangs forever), including the HTTP/1.1 CONNECT signature (`(req, socket, head)`, no `request.stream`) the same event receives under `allowHTTP1`. Refusals are HTTP statuses (405 plain-CONNECT byte-parity — the compat default is just `:status`+`date`; 501 unclaimed; 404 unregistered path), not `close(NGHTTP2_REFUSED_STREAM)`: measured client-side, the RST shape yields an opaque stream error with no loggable status and carries retry semantics. With the flag off, nghttp2 rejects extended CONNECT before any app event — default-off deployments are byte-identical. (2) `lib/ws-framing`: dependency-free RFC 6455 codec (UTF-8 via core `buffer.isUtf8`; maxPayload enforced from the DECLARED frame length before buffering; close-code table mirrors the ws predicate). Write-own was chosen after measuring that ws's `exports` map blocks deep-requiring its internals and that conforming vendoring is whole-tarball-only — which would ship a second copy of a package that is already a framework dependency. The maturity gap is covered by a differential oracle in the tests: ws's root export exposes `Receiver`/`Sender` publicly, so frames are cross-checked in both directions and both parsers must refuse unmasked client frames. (3) `lib/ws-session` + `app.onWebSocket(path, handler)`: `onInitialize`'s `app` IS the raw engine server, so the registration API needs zero routing-layer changes; the dispatcher installs lazily (zero registrations keep the 501-unclaimed refusal); handler exceptions are contained (1011 close, never an uncaughtException); sessions register a closer in the SIGTERM drain registry so shutdown sends `1001 going away` instead of blocking the drain — and since the WS shutdown-drain fix (2026-06-11) the pre-existing engine.io and `/_gina/agent` WS sockets register there too (engine.io with a graceful `socket.close()` — its API takes no status code; the agent WS with `ws.close(1001, 'server shutting down')`), each closer added at socket setup and removed in the socket's own close handler, so no live socket surface blocks SIGTERM until the hard timeout anymore. A routing.json-declared WS surface was measured and deferred: the route matcher's allowed-methods list and exact-method gate sit on the hot path and reject CONNECT, and controller dispatch is render-lifecycle-only — every streaming endpoint bypasses routing, and so does this one. Established 2026-06-11.
+
+170. **ESM compatibility layer shipped (#M10, develop 2026-06-11, commit `58bd2570`): strict `exports` map + default-export-only `.mjs` wrappers; four design constraints worth keeping.** (1) The map is STRICT — `.`, `./gna`, `./package.json` only — because a measured survey found nothing else Node-resolved against the package (client-side RequireJS IDs like `gina/validator` are not Node subpaths and are untouched by `exports`); a `"./*"` wildcard would NOT have preserved legacy behaviour anyway, since exports-pattern resolution disables extension-adding and directory-index resolution. (2) Each entry carries a `types` condition FIRST: once `exports` exists, TypeScript's node16/bundler resolution ignores `typesVersions`, so omitting the conditions would silently break declaration resolution for TS consumers. (3) Both wrappers are default-export-only ON PURPOSE — `gna.js` (the `gina/gna` helper module) exposes getter properties that resolve at ACCESS time after framework boot, and static named ESM re-exports would freeze `undefined` pre-boot; `index.mjs` resolves the core via `require(require('./package.json').main)` (createRequire), so it carries no version-pinned path and is NOT a bump-chain member, while the version-pinned `exports['.'].require` IS kept in lockstep with `main` by both bump scripts (prepare_version.js + post_publish.js set it explicitly — package.json is rewritten as a parsed object there, so a generic content-regex never covers it) and the lockstep is test-pinned (`exports['.'].require === main + '.js'`). (4) Test design: `require('gina')` boots the framework and throws outside a spawned bundle child, so the behavioural ESM test stubs the CJS `require.cache` at the resolved core path before `import('gina')` (the wrapper's createRequire shares the global cache); and only the NEGATIVE assertion (`ERR_PACKAGE_PATH_NOT_EXPORTED` on an undeclared subpath) proves the map is active — positive resolutions also succeed via the legacy node_modules walk + `main`.
+
+171. **Per-template-extension engine dispatch + nunjucks Inspector parity shipped (#M11, develop 2026-06-11, commits `18cd093a` + `b2f652cd`).** (1) Dispatch: the effective extension (setTemplate override ext → templates.json section `ext` → the `.html` default — the delegates' OWN precedence, deliberately with no filename sniffing, so the dispatch can never disagree with the file the delegate resolves) keys the engine at `controller.js` `this.render`: `.njk`→nunjucks, `.swig`→swig, anything else follows the bundle-level `render.engine`; one bundle mixes engines with zero new config keys, and existing bundles are byte-unchanged because `.html` follows the setting. `initNunjucksEngine` also runs when any templates.json section declares a `.njk` ext (dotted/dotless/case-insensitive), keeping the boot-time NUNJUCKS_NOT_INSTALLED fail-fast for mixed bundles; a pure-runtime `setTemplate('.njk')` on a bundle with no `.njk` config surfaces the resolver's explicit get()-before-load() error. Auto-detect-on-`.njk`-presence was measured and DROPPED — with ext-keyed dispatch its only residual value was magic ext-defaulting, which explicit per-section `ext` config covers. (2) Inspector parity: `data.page.queries` is piped from `local._queryLog` (same gate shape as render-swig) and the dev statusbar ships for nunjucks — statusbar.html is a LEAF template valid in both engines, but the nunjucks injection point runs AFTER the engine pass, so the body is rendered through the resolver module's `renderString()` and spliced before `</body>` with a $-safe FUNCTION replacer; converting that splice also fixed the latent dollar-expansion hazard the old string-replacement form shared with the pre-#TPL2 swig splice (`$'`/`$\``/`$n` in statusbar source or user-data JSON would splice document fragments into the script). `data.page.flow` had already shipped (#FI) — the roadmap row and the delegate's own header comment claiming otherwise were both stale; verify-before-inheriting caught them.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gina",
-  "version": "0.4.8-alpha.1",
+  "version": "0.5.0",
   "description": "Node.js MVC framework with built-in HTTP/2, multi-bundle architecture, and scope-based data isolation — no Express dependency",
   "keywords": [
     "nodejs",
@@ -72,7 +72,20 @@
     "gina-container": "bin/gina-container",
     "gina-init": "bin/gina-init"
   },
-  "main": "./framework/v0.4.8-alpha.1/core/gna",
+  "main": "./framework/v0.5.0/core/gna",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./index.mjs",
+      "require": "./framework/v0.5.0/core/gna.js"
+    },
+    "./gna": {
+      "types": "./types/gna.d.ts",
+      "import": "./gna.mjs",
+      "require": "./gna.js"
+    },
+    "./package.json": "./package.json"
+  },
   "types": "./types/index.d.ts",
   "typesVersions": {
     "*": {

package/schema/settings.json

@@ -258,7 +258,7 @@
       "properties": {
         "engine": {
           "type": "string",
-          "description": "Template engine for self.render() HTML output. \"swig\" (default) uses @rhinostone/swig via controller.render-swig.js; \"nunjucks\" uses the project-installed nunjucks package via controller.render-nunjucks.js. When set to \"nunjucks\", bundle startup fails with NUNJUCKS_NOT_INSTALLED if the package is absent from the project's node_modules.",
+          "description": "Bundle-level template engine for self.render() HTML output. \"swig\" (default) uses @rhinostone/swig via controller.render-swig.js; \"nunjucks\" uses the project-installed nunjucks package via controller.render-nunjucks.js. When set to \"nunjucks\", bundle startup fails with NUNJUCKS_NOT_INSTALLED if the package is absent from the project's node_modules. An explicit template extension overrides this per render: a section whose templates.json `ext` is \".njk\" (or a self.setTemplate(file, '.njk') call) renders through nunjucks, \".swig\" through swig — so a single bundle can mix engines; \".html\" and any other extension follow this setting.",
           "enum": ["swig", "nunjucks"],
           "default": "swig"
         }

package/framework/v0.4.8-alpha.1/VERSION

@@ -1 +0,0 @@
-0.4.8-alpha.1