acrylblends 0.6.4 → 0.7.0

package/README.md

@@ -275,10 +275,10 @@ See [Node.js](https://github.com/acryldev/acryl/blob/main/docs/framework/getting
 | `acrylblends/cache`, `acrylblends/mount` | the cache middleware and mounting another framework's fetch handler |
 | `acrylblends/ssg` | static site generation: `toSSG` writes every route as a file ([SSG helper](https://github.com/acryldev/acryl/blob/main/docs/framework/helpers/ssg.md)) |
 | `acrylblends/proxy`, `acrylblends/dev` | the proxy helper and the dev helpers (`showRoutes`, `inspectRoutes`, `getRouterName`) |
-| `acrylblends/jsx` | JSX on the server: `jsxImportSource: 'acrylblends/jsx'`, with `jsx/streaming`, and `acrylblends/jsx-renderer` for a layout behind `c.render` ([JSX guide](https://github.com/acryldev/acryl/blob/main/docs/framework/guides/jsx.md)) |
+| `acrylblends/jsx` | JSX on the server: `jsxImportSource: 'acrylblends/jsx'`, `.tsx` files run on Node with `node --import acrylblends/node-server/register`, with `jsx/streaming`, and `acrylblends/jsx-renderer` for a layout behind `c.render` ([JSX guide](https://github.com/acryldev/acryl/blob/main/docs/framework/guides/jsx.md)) |
 | `acrylblends/jsx/dom` | JSX in the browser: hooks and `render` (needs the DOM library) ([client components](https://github.com/acryldev/acryl/blob/main/docs/framework/guides/jsx-dom.md)) |
 | `acrylblends/css` | CSS in JSX: `css`, `cx`, `keyframes`, `Style` ([CSS helper](https://github.com/acryldev/acryl/blob/main/docs/framework/helpers/css.md)) |
-| `acrylblends/node-server` | `serve`, `createAdaptorServer`, `getRequestListener`; with `node-server/serve-static` and `node-server/conninfo` |
+| `acrylblends/node-server` | `serve`, `createAdaptorServer`, `getRequestListener`; with `node-server/serve-static`, `node-server/conninfo`, and `node-server/register` (compiles `.tsx` with the app's `typescript`) |
 
 Every subpath is listed in the package's `exports`. The adapters of other runtimes are being ported. The docs mark them "not yet available" until they ship
 ([FAQ](https://github.com/acryldev/acryl/blob/main/docs/framework/guides/faq.md)).

package/docs/framework/UPSTREAM.md

@@ -1,3 +1,3 @@
 # Generated copy
 
-This folder is a copy of `docs/framework` of acryldev/acryl at commit `fd1f7dcaaff8b757c0562294002c0d32d6e0a893`, made by `scripts/sync-framework.mjs`. Do not edit it here: change the text in ACRYL and sync again. `pnpm run verify:framework` fails when a page differs from the recorded digest.
+This folder is a copy of `docs/framework` of acryldev/acryl at commit `7bba3ed0420d87e61d8256fa60614d22af734c8f`, made by `scripts/sync-framework.mjs`. Do not edit it here: change the text in ACRYL and sync again. `pnpm run verify:framework` fails when a page differs from the recorded digest.

package/docs/framework/guides/jsx.md

@@ -4,30 +4,6 @@ You can write HTML with JSX syntax with `acrylblends/jsx`.
 
 Although `acrylblends/jsx` works on the client, you will probably use it most often when rendering content on the server side. Here are some things related to JSX that are common to both server and client.
 
-## Node.js runs `jsx()`, not JSX syntax
-
-The apps `npm create acrylblends@latest` makes run their TypeScript on Node.js by stripping the types (no build step). That does **not** compile JSX: a `.tsx` file does not load. Either compile the file first (`tsc`
-or a bundler, with the settings below), or write the call that JSX compiles to. `jsx(tag, props, ...children)` takes the children after the props, and a node renders with `toString()`:
-
-```ts
-import { Acryl } from 'acrylblends'
-import { jsx } from 'acrylblends/jsx'
-import type { PropsWithChildren } from 'acrylblends/jsx'
-
-const Layout = (props: PropsWithChildren<{ title: string }>) =>
-  jsx('html', { lang: 'en' }, jsx('head', null, jsx('title', null, props.title)), jsx('body', null, props.children))
-
-const About = () =>
-  jsx(Layout, { title: 'About' }, jsx('h1', null, 'About'), jsx('p', { class: 'lead' }, 'Rendered on the server.'))
-
-const app = new Acryl()
-app.get('/about', (c) => c.html(jsx(About, null).toString()))
-
-export default app
-```
-
-Pass the children as arguments after the props. A `children` entry inside the props object is not rendered by this form.
-
 ## Settings
 
 To use JSX, modify the `tsconfig.json`:
@@ -50,9 +26,34 @@ Alternatively, use the pragma directives:
 /** @jsxImportSource acrylblends/jsx */
 ```
 
+## Run `.tsx` on Node.js
+
+Node.js strips TypeScript's types but does not compile JSX, so a `.tsx` file needs one flag: `--import acrylblends/node-server/register`.
+It compiles each `.tsx` (and `.jsx`) module as Node.js loads it, with your app's own `typescript` (a development dependency) and the
+`jsxImportSource` of your `tsconfig.json` (`acrylblends/jsx` without one); every other module runs exactly as before. Stack traces point at
+the `.tsx` lines.
+
+`package.json`:
+
+```json
+{
+  "scripts": {
+    "dev": "node --watch --import acrylblends/node-server/register src/index.tsx",
+    "start": "node --import acrylblends/node-server/register src/index.tsx",
+    "test": "node --import acrylblends/node-server/register --test \"src/**/*.test.{ts,tsx}\""
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3"
+  }
+}
+```
+
+`node --test` looks only for `.js` and `.ts` test files on its own, so the `test` script names the `.tsx` ones with a pattern. Without `typescript` in the app, the first `.tsx` module stops with a message that says to install it. Bun compiles JSX itself and needs
+no flag.
+
 ## Usage
 
-> **Note.** If you are coming straight from the [Quick Start](../README.md#quick-start), the main file has a `.ts` extension - you need to change it to `.tsx` - otherwise you will not be able to run the application at all. You should additionally modify the `package.json` (or `deno.json` if you are using Deno) to reflect that change (e.g. instead of having `bun run --hot src/index.ts` in dev script, you should have `bun run --hot src/index.tsx`).
+> **Note.** If you are coming straight from the [Quick Start](../README.md#quick-start), the main file has a `.ts` extension - you need to change it to `.tsx` - otherwise you will not be able to run the application at all. Change the scripts in `package.json` to match: on Node.js, as [above](#run-tsx-on-nodejs); on Bun, `bun run --hot src/index.tsx` instead of `bun run --hot src/index.ts`.
 
 `index.tsx`:
 
@@ -93,6 +94,31 @@ app.get('/', (c) => {
 export default app
 ```
 
+## Without compiling: `jsx()`
+
+A `.ts` file can build the same nodes without JSX syntax and without the register flag: write the call that JSX compiles to.
+`jsx(tag, props, ...children)` takes the children after the props, and a node renders with `toString()`. The `` html`...` `` template
+from `acrylblends/html` is the other build-free choice.
+
+```ts
+import { Acryl } from 'acrylblends'
+import { jsx } from 'acrylblends/jsx'
+import type { PropsWithChildren } from 'acrylblends/jsx'
+
+const Layout = (props: PropsWithChildren<{ title: string }>) =>
+  jsx('html', { lang: 'en' }, jsx('head', null, jsx('title', null, props.title)), jsx('body', null, props.children))
+
+const About = () =>
+  jsx(Layout, { title: 'About' }, jsx('h1', null, 'About'), jsx('p', { class: 'lead' }, 'Rendered on the server.'))
+
+const app = new Acryl()
+app.get('/about', (c) => c.html(jsx(About, null).toString()))
+
+export default app
+```
+
+Pass the children as arguments after the props. A `children` entry inside the props object is not rendered by this form.
+
 ## Metadata hoisting
 
 You can write document metadata tags such as `<title>`, `<link>`, and `<meta>` directly inside your components. These tags will be automatically hoisted to the `<head>` section of the document. This is especially useful when the `<head>` element is rendered far from the component that determines the appropriate metadata.

package/docs/framework/upstream.json

@@ -2,8 +2,8 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "docs/framework",
-    "commit": "fd1f7dcaaff8b757c0562294002c0d32d6e0a893"
+    "commit": "7bba3ed0420d87e61d8256fa60614d22af734c8f"
   },
   "files": 88,
-  "digest": "sha256:5e6989c7fe1b3006f8917926d8cc3e84e14c2af03440682c18d22bec0045c3d2"
+  "digest": "sha256:1f7e213ee1fd287a98b5bead17a0b197311fcd75013ddf5912ca4a476657cece"
 }

package/lib/{base-ddiVmiE7.js → base-NSN_SNv-.js}

@@ -1,5 +1,6 @@
 import { escapeToBuffer, raw, resolveCallbackSync, stringBufferToString } from "./utils/html.js";
 import { i as DOM_RENDERER, n as DOM_INTERNAL_TAG, o as PERMALINK, r as DOM_MEMO, t as DOM_ERROR_HANDLER } from "./constants-BR9jM9BC.js";
+import "node:module";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
 var __exportAll = (all, no_symbols) => {

package/lib/{components-DdI7-ns7.js → components-JXVm45kK.js}

@@ -1,5 +1,5 @@
 import { t as DOM_ERROR_HANDLER } from "./constants-BR9jM9BC.js";
-import { t as Fragment } from "./jsx-dev-runtime-D18Y35TI.js";
+import { t as Fragment } from "./jsx-dev-runtime-CWLRA2F3.js";
 import "./jsx/dom/jsx-runtime.js";
 //#region ../../plugins/acryl-router/src/core/jsx/dom/components.ts
 const ErrorBoundary = (({ children, fallback, fallbackRender, onError }) => {

package/lib/{components-0o0CBYNv.js → components-cEW3ovK0.js}

@@ -1,8 +1,8 @@
-import { C as captureRenderContext, E as useContext, d as renderUntrustedObject, i as isUntrustedObject, n as JSXNode, o as jsx, t as Fragment, u as renderChildren, w as createContext } from "./base-ddiVmiE7.js";
+import { C as captureRenderContext, E as useContext, d as renderUntrustedObject, i as isUntrustedObject, n as JSXNode, o as jsx, t as Fragment, u as renderChildren, w as createContext } from "./base-NSN_SNv-.js";
 import { HtmlEscapedCallbackPhase, raw, resolveCallback } from "./utils/html.js";
 import { a as DOM_STASH, i as DOM_RENDERER } from "./constants-BR9jM9BC.js";
-import { x as buildDataStack } from "./hooks-BMw6BAyP.js";
-import { n as Suspense$1, t as ErrorBoundary$1 } from "./components-DdI7-ns7.js";
+import { x as buildDataStack } from "./hooks-w72iLeFR.js";
+import { n as Suspense$1, t as ErrorBoundary$1 } from "./components-JXVm45kK.js";
 //#region ../../plugins/acryl-router/src/core/jsx/streaming.ts
 /**
 * @module

package/lib/{hooks-BMw6BAyP.js → hooks-w72iLeFR.js}

@@ -1,4 +1,4 @@
-import { D as createContext, E as useContext, T as globalContexts, _ as toArray, h as styleObjectForEach, m as normalizeIntrinsicElementKey } from "./base-ddiVmiE7.js";
+import { D as createContext, E as useContext, T as globalContexts, _ as toArray, h as styleObjectForEach, m as normalizeIntrinsicElementKey } from "./base-NSN_SNv-.js";
 import { a as DOM_STASH, i as DOM_RENDERER, n as DOM_INTERNAL_TAG, r as DOM_MEMO, t as DOM_ERROR_HANDLER } from "./constants-BR9jM9BC.js";
 //#region ../../plugins/acryl-router/src/core/jsx/dom/render.ts
 const ACRYL_PORTAL_ELEMENT = "_hp";

package/lib/jsx/dom/client.js

@@ -1,4 +1,4 @@
-import { D as renderNode, S as buildNode, _ as useState } from "../../hooks-BMw6BAyP.js";
+import { D as renderNode, S as buildNode, _ as useState } from "../../hooks-w72iLeFR.js";
 //#region ../../plugins/acryl-router/src/core/jsx/dom/client.ts
 /**
 * Create a root object for rendering

package/lib/jsx/dom/jsx-dev-runtime.js

@@ -1,2 +1,2 @@
-import { n as jsxDEV, t as Fragment } from "../../jsx-dev-runtime-D18Y35TI.js";
+import { n as jsxDEV, t as Fragment } from "../../jsx-dev-runtime-CWLRA2F3.js";
 export { Fragment, jsxDEV };

package/lib/jsx/dom/jsx-runtime.js

@@ -1,2 +1,2 @@
-import { n as jsxDEV, t as Fragment } from "../../jsx-dev-runtime-D18Y35TI.js";
+import { n as jsxDEV, t as Fragment } from "../../jsx-dev-runtime-CWLRA2F3.js";
 export { Fragment, jsxDEV as jsx, jsxDEV as jsxs };

package/lib/jsx/dom/server.js

@@ -1,5 +1,5 @@
-import { u as renderChildren } from "../../base-ddiVmiE7.js";
-import { i as renderToReadableStream$1 } from "../../components-0o0CBYNv.js";
+import { u as renderChildren } from "../../base-NSN_SNv-.js";
+import { i as renderToReadableStream$1 } from "../../components-cEW3ovK0.js";
 import dom_default from "../dom.js";
 //#region ../../plugins/acryl-router/src/core/jsx/dom/server.ts
 const prepareRoot = (element) => typeof element === "string" || Array.isArray(element) ? renderChildren([element]) : element;

package/lib/jsx/dom.js

@@ -1,9 +1,9 @@
-import { D as createContext, E as useContext, a as isValidElement, f as shallowEqual, g as Children, l as reactAPICompatVersion } from "../base-ddiVmiE7.js";
+import { D as createContext, E as useContext, a as isValidElement, f as shallowEqual, g as Children, l as reactAPICompatVersion } from "../base-NSN_SNv-.js";
 import { r as DOM_MEMO } from "../constants-BR9jM9BC.js";
-import { C as createPortal, E as render, _ as useState, a as use, b as useViewTransition, c as useDeferredValue, d as useImperativeHandle, f as useInsertionEffect, g as useRef, h as useReducer, i as startViewTransition, l as useEffect, m as useMemo, n as forwardRef, o as useCallback, p as useLayoutEffect, r as startTransition, s as useDebugValue, t as createRef, u as useId, v as useSyncExternalStore, w as flushSync, y as useTransition } from "../hooks-BMw6BAyP.js";
-import { a as useOptimistic, i as useFormStatus, n as jsxDEV, r as useActionState, t as Fragment } from "../jsx-dev-runtime-D18Y35TI.js";
+import { C as createPortal, E as render, _ as useState, a as use, b as useViewTransition, c as useDeferredValue, d as useImperativeHandle, f as useInsertionEffect, g as useRef, h as useReducer, i as startViewTransition, l as useEffect, m as useMemo, n as forwardRef, o as useCallback, p as useLayoutEffect, r as startTransition, s as useDebugValue, t as createRef, u as useId, v as useSyncExternalStore, w as flushSync, y as useTransition } from "../hooks-w72iLeFR.js";
+import { a as useOptimistic, i as useFormStatus, n as jsxDEV, r as useActionState, t as Fragment } from "../jsx-dev-runtime-CWLRA2F3.js";
 import "./dom/jsx-runtime.js";
-import { n as Suspense, t as ErrorBoundary } from "../components-DdI7-ns7.js";
+import { n as Suspense, t as ErrorBoundary } from "../components-JXVm45kK.js";
 //#region ../../plugins/acryl-router/src/core/jsx/dom/index.ts
 /**
 * @module

package/lib/jsx/jsx-dev-runtime.js

@@ -1,4 +1,4 @@
-import { s as jsxFn, t as Fragment } from "../base-ddiVmiE7.js";
+import { s as jsxFn, t as Fragment } from "../base-NSN_SNv-.js";
 //#region ../../plugins/acryl-router/src/core/jsx/jsx-dev-runtime.ts
 function jsxDEV(tag, props, key) {
 	let node;

package/lib/jsx/jsx-runtime.js

@@ -1,4 +1,4 @@
-import { h as styleObjectForEach, p as isValidAttributeName, t as Fragment } from "../base-ddiVmiE7.js";
+import { h as styleObjectForEach, p as isValidAttributeName, t as Fragment } from "../base-NSN_SNv-.js";
 import { escapeToBuffer, raw, stringBufferToString } from "../utils/html.js";
 import { html } from "../html.js";
 import { jsxDEV } from "./jsx-dev-runtime.js";

package/lib/jsx/streaming.js

@@ -1,2 +1,2 @@
-import { i as renderToReadableStream, n as StreamingContext, r as Suspense } from "../components-0o0CBYNv.js";
+import { i as renderToReadableStream, n as StreamingContext, r as Suspense } from "../components-cEW3ovK0.js";
 export { StreamingContext, Suspense, renderToReadableStream };

package/lib/{jsx-dev-runtime-D18Y35TI.js → jsx-dev-runtime-CWLRA2F3.js}

@@ -1,6 +1,6 @@
-import { D as createContext, E as useContext, O as __exportAll, S as shouldDeDupeByKey, b as domRenderers, v as dataPrecedenceAttr, x as isStylesheetLinkWithPrecedence, y as deDupeKeyMap } from "./base-ddiVmiE7.js";
+import { D as createContext, E as useContext, O as __exportAll, S as shouldDeDupeByKey, b as domRenderers, v as dataPrecedenceAttr, x as isStylesheetLinkWithPrecedence, y as deDupeKeyMap } from "./base-NSN_SNv-.js";
 import { o as PERMALINK } from "./constants-BR9jM9BC.js";
-import { C as createPortal, T as getNameSpaceContext, _ as useState, a as use, m as useMemo, o as useCallback } from "./hooks-BMw6BAyP.js";
+import { C as createPortal, T as getNameSpaceContext, _ as useState, a as use, m as useMemo, o as useCallback } from "./hooks-w72iLeFR.js";
 //#region ../../plugins/acryl-router/src/core/jsx/dom/hooks/index.ts
 /**
 * Provide hooks used only in jsx/dom

package/lib/jsx-renderer.js

@@ -1,7 +1,7 @@
-import { E as useContext, o as jsx, t as Fragment, w as createContext } from "./base-ddiVmiE7.js";
+import { E as useContext, o as jsx, t as Fragment, w as createContext } from "./base-NSN_SNv-.js";
 import { raw } from "./utils/html.js";
 import { html } from "./html.js";
-import { i as renderToReadableStream } from "./components-0o0CBYNv.js";
+import { i as renderToReadableStream } from "./components-cEW3ovK0.js";
 import "./jsx.js";
 //#region ../../plugins/acryl-router/src/core/middleware/jsx-renderer/index.ts
 const RequestContext = createContext(null);

package/lib/jsx.js

@@ -1,7 +1,7 @@
-import { E as useContext, a as isValidElement, c as memo, g as Children, l as reactAPICompatVersion, o as jsx, r as cloneElement, t as Fragment, w as createContext } from "./base-ddiVmiE7.js";
-import { _ as useState, a as use, b as useViewTransition, c as useDeferredValue, d as useImperativeHandle, f as useInsertionEffect, g as useRef, h as useReducer, i as startViewTransition, l as useEffect, m as useMemo, n as forwardRef, o as useCallback, p as useLayoutEffect, r as startTransition, s as useDebugValue, t as createRef, u as useId, v as useSyncExternalStore, y as useTransition } from "./hooks-BMw6BAyP.js";
-import { a as useOptimistic, r as useActionState } from "./jsx-dev-runtime-D18Y35TI.js";
-import { r as Suspense, t as ErrorBoundary } from "./components-0o0CBYNv.js";
+import { E as useContext, a as isValidElement, c as memo, g as Children, l as reactAPICompatVersion, o as jsx, r as cloneElement, t as Fragment, w as createContext } from "./base-NSN_SNv-.js";
+import { _ as useState, a as use, b as useViewTransition, c as useDeferredValue, d as useImperativeHandle, f as useInsertionEffect, g as useRef, h as useReducer, i as startViewTransition, l as useEffect, m as useMemo, n as forwardRef, o as useCallback, p as useLayoutEffect, r as startTransition, s as useDebugValue, t as createRef, u as useId, v as useSyncExternalStore, y as useTransition } from "./hooks-w72iLeFR.js";
+import { a as useOptimistic, r as useActionState } from "./jsx-dev-runtime-CWLRA2F3.js";
+import { r as Suspense, t as ErrorBoundary } from "./components-cEW3ovK0.js";
 //#region ../../plugins/acryl-router/src/core/jsx/index.ts
 /**
 * @module

package/lib/node-server/register.d.ts

@@ -0,0 +1 @@
+export { };

package/lib/node-server/register.js

@@ -0,0 +1,73 @@
+import { createRequire, registerHooks } from "node:module";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+//#region ../../plugins/acryl-node-server/src/register.ts
+/**
+* JSX files on Node: `node --import acrylblends/node-server/register src/index.ts`. Node strips TypeScript's types but does not compile JSX, so a
+* `.tsx` (or `.jsx`) module does not load on its own. This module registers a load hook that compiles exactly those files with the app's own
+* `typescript` (react-jsx, the `jsxImportSource` of the app's nearest tsconfig.json, `acrylblends/jsx` without one) and leaves every other
+* module to Node untouched. The output carries an inline source map and source maps are switched on, so a stack trace names the `.tsx` line.
+*
+* `typescript` is loaded from the app, on the first JSX file only; the framework itself has no dependencies.
+*/
+/** The JSX runtime the docs set up; an app's tsconfig.json (or a file's own `@jsxImportSource` pragma) chooses another. */
+const DEFAULT_IMPORT_SOURCE = "acrylblends/jsx";
+const JSX_FILE = /\.[jt]sx$/u;
+const compilers = /* @__PURE__ */ new Map();
+const importSources = /* @__PURE__ */ new Map();
+/** The app's own `typescript`, resolved from the JSX file, so each app compiles with the version it pinned. */
+function compilerFor(file) {
+	let path;
+	try {
+		path = createRequire(file).resolve("typescript");
+	} catch {
+		throw new Error(`acrylblends: ${file} contains JSX, and compiling it needs the typescript package in this app: npm install --save-dev typescript`);
+	}
+	let compiler = compilers.get(path);
+	if (compiler === void 0) {
+		compiler = createRequire(path)(path);
+		compilers.set(path, compiler);
+	}
+	return compiler;
+}
+/** `jsxImportSource` of the tsconfig.json nearest to the file (following `extends`), read once per config. */
+function importSourceFor(file, ts) {
+	const config = ts.findConfigFile(dirname(file), (path) => existsSync(path));
+	if (config === void 0) return DEFAULT_IMPORT_SOURCE;
+	let source = importSources.get(config);
+	if (source === void 0) {
+		const { config: json } = ts.readConfigFile(config, (path) => ts.sys.readFile(path));
+		source = ts.parseJsonConfigFileContent(json ?? {}, ts.sys, dirname(config)).options.jsxImportSource ?? DEFAULT_IMPORT_SOURCE;
+		importSources.set(config, source);
+	}
+	return source;
+}
+/** A JSX module compiled to JavaScript, with its source map inline. */
+function compileJsx(file, text) {
+	const ts = compilerFor(file);
+	return ts.transpileModule(text, {
+		fileName: file,
+		compilerOptions: {
+			module: "esnext",
+			target: "es2022",
+			jsx: "react-jsx",
+			jsxImportSource: importSourceFor(file, ts),
+			allowImportingTsExtensions: true,
+			inlineSourceMap: true,
+			inlineSources: true
+		}
+	}).outputText;
+}
+process.setSourceMapsEnabled(true);
+registerHooks({ load(url, context, nextLoad) {
+	if (!url.startsWith("file:") || !JSX_FILE.test(new URL(url).pathname)) return nextLoad(url, context);
+	const file = fileURLToPath(url);
+	return {
+		format: "module",
+		source: compileJsx(file, readFileSync(file, "utf8")),
+		shortCircuit: true
+	};
+} });
+//#endregion
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acrylblends",
-  "version": "0.6.4",
+  "version": "0.7.0",
   "description": "The Acryl web framework (import { Acryl } from \"acrylblends\") and the acrylblends command that scaffolds Cordis apps.",
   "license": "MIT",
   "type": "module",
@@ -382,6 +382,10 @@
       "types": "./lib/node-server/conninfo.d.ts",
       "default": "./lib/node-server/conninfo.js"
     },
+    "./node-server/register": {
+      "types": "./lib/node-server/register.d.ts",
+      "default": "./lib/node-server/register.js"
+    },
     "./package.json": "./package.json",
     "./cli": {
       "types": "./dist/index.d.ts",

package/plugins/acryl-inspect/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-inspect",
-    "commit": "fd1f7dcaaff8b757c0562294002c0d32d6e0a893"
+    "commit": "7bba3ed0420d87e61d8256fa60614d22af734c8f"
   },
   "vendored": [
     "src",

package/plugins/acryl-node-server/src/register.ts

@@ -0,0 +1,86 @@
+/**
+ * JSX files on Node: `node --import acrylblends/node-server/register src/index.ts`. Node strips TypeScript's types but does not compile JSX, so a
+ * `.tsx` (or `.jsx`) module does not load on its own. This module registers a load hook that compiles exactly those files with the app's own
+ * `typescript` (react-jsx, the `jsxImportSource` of the app's nearest tsconfig.json, `acrylblends/jsx` without one) and leaves every other
+ * module to Node untouched. The output carries an inline source map and source maps are switched on, so a stack trace names the `.tsx` line.
+ *
+ * `typescript` is loaded from the app, on the first JSX file only; the framework itself has no dependencies.
+ */
+
+import { createRequire, registerHooks } from 'node:module'
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** The JSX runtime the docs set up; an app's tsconfig.json (or a file's own `@jsxImportSource` pragma) chooses another. */
+const DEFAULT_IMPORT_SOURCE = 'acrylblends/jsx'
+const JSX_FILE = /\.[jt]sx$/u
+
+/** The part of the TypeScript compiler API the hook uses. */
+interface Compiler {
+  transpileModule(input: string, options: { fileName: string, compilerOptions: Record<string, unknown> }): { outputText: string }
+  findConfigFile(searchPath: string, fileExists: (path: string) => boolean): string | undefined
+  readConfigFile(path: string, readFile: (path: string) => string | undefined): { config?: unknown }
+  parseJsonConfigFileContent(json: unknown, host: unknown, basePath: string): { options: { jsxImportSource?: string } }
+  sys: { fileExists(path: string): boolean, readFile(path: string): string | undefined }
+}
+
+const compilers = new Map<string, Compiler>()
+const importSources = new Map<string, string>()
+
+/** The app's own `typescript`, resolved from the JSX file, so each app compiles with the version it pinned. */
+function compilerFor(file: string): Compiler {
+  let path: string
+  try {
+    path = createRequire(file).resolve('typescript')
+  } catch {
+    throw new Error(`acrylblends: ${file} contains JSX, and compiling it needs the typescript package in this app: npm install --save-dev typescript`)
+  }
+  let compiler = compilers.get(path)
+  if (compiler === undefined) {
+    compiler = createRequire(path)(path) as Compiler
+    compilers.set(path, compiler)
+  }
+  return compiler
+}
+
+/** `jsxImportSource` of the tsconfig.json nearest to the file (following `extends`), read once per config. */
+function importSourceFor(file: string, ts: Compiler): string {
+  const config = ts.findConfigFile(dirname(file), path => existsSync(path))
+  if (config === undefined) return DEFAULT_IMPORT_SOURCE
+  let source = importSources.get(config)
+  if (source === undefined) {
+    const { config: json } = ts.readConfigFile(config, path => ts.sys.readFile(path))
+    source = ts.parseJsonConfigFileContent(json ?? {}, ts.sys, dirname(config)).options.jsxImportSource ?? DEFAULT_IMPORT_SOURCE
+    importSources.set(config, source)
+  }
+  return source
+}
+
+/** A JSX module compiled to JavaScript, with its source map inline. */
+function compileJsx(file: string, text: string): string {
+  const ts = compilerFor(file)
+  return ts.transpileModule(text, {
+    fileName: file,
+    compilerOptions: {
+      module: 'esnext',
+      target: 'es2022',
+      jsx: 'react-jsx',
+      jsxImportSource: importSourceFor(file, ts),
+      allowImportingTsExtensions: true,
+      inlineSourceMap: true,
+      inlineSources: true,
+    },
+  }).outputText
+}
+
+process.setSourceMapsEnabled(true)
+
+registerHooks({
+  load(url, context, nextLoad) {
+    // Every other module goes straight to Node: the hook's whole cost for them is this test.
+    if (!url.startsWith('file:') || !JSX_FILE.test(new URL(url).pathname)) return nextLoad(url, context)
+    const file = fileURLToPath(url)
+    return { format: 'module', source: compileJsx(file, readFileSync(file, 'utf8')), shortCircuit: true }
+  },
+})

package/plugins/acryl-node-server/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-node-server",
-    "commit": "fd1f7dcaaff8b757c0562294002c0d32d6e0a893"
+    "commit": "7bba3ed0420d87e61d8256fa60614d22af734c8f"
   },
   "vendored": [
     "src",
@@ -10,8 +10,10 @@
     "LICENSE"
   ],
   "rewrittenSpecifiers": 28,
-  "digest": "sha256:2adaa64028c1f2a40ed94c0eacf64d32c8c3b8171b52338cb02bfae2fd56ab7c",
-  "testsNotRun": {},
+  "digest": "sha256:9dc4cca51f5a3d8416750c0392135128a0787947f473cff2e00bdb12fe5a63e1",
+  "testsNotRun": {
+    "tests/register.spec.ts": "links typescript from the plugin's own node_modules (ACRYL's workspace layout); the hook is exercised here by the templates' own .tsx tests and verify:scaffolder"
+  },
   "notice": [
     "LICENSE"
   ]

package/plugins/acryl-router/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-router",
-    "commit": "fd1f7dcaaff8b757c0562294002c0d32d6e0a893"
+    "commit": "7bba3ed0420d87e61d8256fa60614d22af734c8f"
   },
   "vendored": [
     "src",

package/plugins/acryl-router-http/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-router-http",
-    "commit": "fd1f7dcaaff8b757c0562294002c0d32d6e0a893"
+    "commit": "7bba3ed0420d87e61d8256fa60614d22af734c8f"
   },
   "vendored": [
     "src",

package/plugins/acryl-state/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-state",
-    "commit": "fd1f7dcaaff8b757c0562294002c0d32d6e0a893"
+    "commit": "7bba3ed0420d87e61d8256fa60614d22af734c8f"
   },
   "vendored": [
     "src",

package/plugins/desktop/main.ts

@@ -10,7 +10,8 @@ import { mkdirSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { app, BrowserWindow, shell } from 'electron'
-import { type App, createApp } from '../../app.ts'
+import type { App } from '../../app.ts'
+import '../acryl-node-server/src/register.ts'
 import { selectInstance } from '../instance/index.ts'
 import { createDesktopShutdown, installShutdownRequests } from './shutdown.ts'
 import { resolveDesktopUserDataOverride } from './user-data.ts'
@@ -63,6 +64,8 @@ if (!app.requestSingleInstanceLock()) {
   })
 
   void app.whenReady().then(async () => {
+    // The hook above is registered before the app's modules are loaded, so the app may have .tsx pages: they are loaded here, not as a static import.
+    const { createApp } = await import('../../app.ts')
     running = await createApp(chosen)
     const origin = new URL(running.url).origin
     window = new BrowserWindow(windowOptions({ title: chosen.name }))

package/plugins/desktop/upstream.json

@@ -5,7 +5,7 @@
       "apps/acryl-desktop/src/shell/desktop-user-data.ts": "user-data.ts",
       "apps/acryl-desktop/src/shell/shutdown.ts": "shutdown.ts"
     },
-    "commit": "fd1f7dcaaff8b757c0562294002c0d32d6e0a893"
+    "commit": "7bba3ed0420d87e61d8256fa60614d22af734c8f"
   },
   "rewrittenSpecifiers": 0,
   "digest": "sha256:7dfe960a8bbb476c35540d2202a7aaa62b33492c2ac3e34314e2ecfca45f32f2"

package/plugins/desktop-web/main.ts

@@ -12,7 +12,7 @@ import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { serve } from 'acrylblends/node-server'
 import { app, BrowserWindow, shell } from 'electron'
-import acrylApp from '../../app.ts'
+import 'acrylblends/node-server/register'
 import { createDesktopShutdown, installShutdownRequests } from './shutdown.ts'
 import { resolveDesktopUserDataOverride } from './user-data.ts'
 import { windowOptions } from './window.ts'
@@ -66,6 +66,8 @@ if (!app.requestSingleInstanceLock()) {
   })
 
   void app.whenReady().then(async () => {
+    // The hook above is registered before the app's modules are loaded, so the app may have .tsx pages: they are loaded here, not as a static import.
+    const { default: acrylApp } = await import('../../app.ts')
     const port = await new Promise<number>((resolve) => {
       server = serve(
         { fetch: acrylApp.fetch, port: 0, hostname: '127.0.0.1' },

package/plugins/desktop-web/upstream.json

@@ -5,7 +5,7 @@
       "apps/acryl-desktop/src/shell/desktop-user-data.ts": "user-data.ts",
       "apps/acryl-desktop/src/shell/shutdown.ts": "shutdown.ts"
     },
-    "commit": "fd1f7dcaaff8b757c0562294002c0d32d6e0a893"
+    "commit": "7bba3ed0420d87e61d8256fa60614d22af734c8f"
   },
   "rewrittenSpecifiers": 0,
   "digest": "sha256:7dfe960a8bbb476c35540d2202a7aaa62b33492c2ac3e34314e2ecfca45f32f2"

package/shared/AGENTS.core.md

@@ -17,8 +17,7 @@ The docs write `import { Acryl } from 'acrylblends'` and `from 'acrylblends/<sub
 - `./plugins/acryl-router/src/helpers/index.ts` for the helpers and validators (`streamSSE`, `schemaValidator`, `validator`, cookies, `testClient`, ...).
 - `./plugins/acryl-router/src/core/jsx/index.ts` for `acrylblends/jsx` (`jsx`, `Fragment`, the types), and `.../core/jsx/streaming.ts` for `acrylblends/jsx/streaming`.
 
-**JSX syntax does not run here.** Node runs this app by stripping TypeScript types, which does not compile JSX (a `.tsx` file will not load). Write the call JSX compiles to instead: `jsx('h1', { class: 'title' }, 'Hello')`, children after the props as further arguments
-(`jsx(tag, props, ...children)`); render with `.toString()` and return it with `c.html(...)`. A component is a function from props to a `jsx(...)` node.
+**JSX: write `.tsx`.** The scripts in `package.json` run Node.js with `--import ./src/plugins/acryl-node-server/src/register.ts`, which compiles `.tsx` files with this app's own `typescript`; `tsconfig.json` sets `jsx: react-jsx` and `jsxImportSource: #acryl-jsx`, which `package.json`'s `imports` maps to the vendored runtime in `src/plugins/acryl-router`. See `src/about.tsx` (blank template) for a page and `test/app.test.ts` for how it is tested. Render a component with `.toString()` and return it with `c.html(...)`; import `jsx`, `Fragment` and the types from `./plugins/acryl-router/src/core/jsx/index.ts` when you need them. A command that starts the app without those scripts (a bare `node src/main.ts`) cannot load a `.tsx` file. Without a build step you can write the call JSX compiles to instead: `jsx('h1', { class: 'title' }, 'Hello')`, children after the props.
 
 A plugin written into `extensions/` while the app runs may use the docs' own names instead: `acrylblends` and `acrylblends/<subpath>` resolve to the same files. `App` is the
 deprecated name of `Acryl`.

package/templates/agent/package.json

@@ -3,13 +3,17 @@
   "version": "0.1.0",
   "private": true,
   "type": "module",
+  "imports": {
+    "#acryl-jsx/jsx-runtime": "./src/plugins/acryl-router/src/core/jsx/jsx-runtime.ts",
+    "#acryl-jsx/jsx-dev-runtime": "./src/plugins/acryl-router/src/core/jsx/jsx-dev-runtime.ts"
+  },
   "engines": {
     "node": ">=22.19.0"
   },
   "scripts": {
-    "start": "node src/main.ts",
-    "dev": "node --watch src/main.ts",
-    "test": "node --test",
+    "start": "node --import ./src/plugins/acryl-node-server/src/register.ts src/main.ts",
+    "dev": "node --watch --import ./src/plugins/acryl-node-server/src/register.ts src/main.ts",
+    "test": "node --import ./src/plugins/acryl-node-server/src/register.ts --test \"test/**/*.test.{ts,tsx}\"",
     "check": "tsc --noEmit",
     "lock": "node src/plugins/manifest/lock.ts",
     "save": "node src/plugins/save/cli.ts",

package/templates/agent/tsconfig.json

@@ -62,7 +62,9 @@
         "./src/plugins/acryl-router/src/core/jsx/jsx-dev-runtime.ts"
       ],
       "acrylblends/jsx/streaming": ["./src/plugins/acryl-router/src/core/jsx/streaming.ts"]
-    }
+    },
+    "jsx": "react-jsx",
+    "jsxImportSource": "#acryl-jsx"
   },
   "include": ["src", "test", "extensions"]
 }

package/templates/blank/package.json

@@ -3,13 +3,17 @@
   "version": "0.1.0",
   "private": true,
   "type": "module",
+  "imports": {
+    "#acryl-jsx/jsx-runtime": "./src/plugins/acryl-router/src/core/jsx/jsx-runtime.ts",
+    "#acryl-jsx/jsx-dev-runtime": "./src/plugins/acryl-router/src/core/jsx/jsx-dev-runtime.ts"
+  },
   "engines": {
     "node": ">=22.19.0"
   },
   "scripts": {
-    "start": "node src/main.ts",
-    "dev": "node --watch src/main.ts",
-    "test": "node --test",
+    "start": "node --import ./src/plugins/acryl-node-server/src/register.ts src/main.ts",
+    "dev": "node --watch --import ./src/plugins/acryl-node-server/src/register.ts src/main.ts",
+    "test": "node --import ./src/plugins/acryl-node-server/src/register.ts --test \"test/**/*.test.{ts,tsx}\"",
     "check": "tsc --noEmit",
     "lock": "node src/plugins/manifest/lock.ts",
     "save": "node src/plugins/save/cli.ts",

package/templates/blank/src/about.tsx

@@ -0,0 +1,14 @@
+/** A page written in JSX: the scripts in package.json run Node.js with the vendored register hook (src/plugins/acryl-node-server/src/register.ts), which compiles .tsx with this app's own typescript. */
+const About = () => (
+  <main>
+    <h1>About</h1>
+    <p>Rendered on the server with the JSX runtime in src/plugins/acryl-router.</p>
+  </main>
+)
+
+export const aboutPage = (): string => (<About />).toString()
+
+/** Throws on purpose: the template's test checks that the stack names this file, so a failure in your own pages points at the .tsx line. */
+export const failingPage = (): string => {
+  throw new Error('a page failed')
+}

package/templates/blank/src/routes.ts

@@ -1,4 +1,5 @@
 import type { Context } from '@deepseek-ai/cordis'
+import { aboutPage } from './about.tsx'
 import { Acryl } from './plugins/acryl-router/src/index.ts'
 
 export const APP_NAME = '__APP_NAME__'
@@ -11,6 +12,7 @@ export const routes = {
     const app = new Acryl()
       .get('/', (c) => c.json({ app: APP_NAME, ok: true }))
       .get('/health', (c) => c.json({ ok: true }))
+      .get('/about', (c) => c.html(aboutPage()))
     ctx.router.route('/', app)
   },
 }

package/templates/blank/test/app.test.ts

@@ -29,6 +29,21 @@ test('serves the index route', () =>
     assert.deepEqual(await response.json(), { app: APP_NAME, ok: true })
   }))
 
+test('renders a .tsx page, and an error in it names the .tsx line', () =>
+  withApp(async (app) => {
+    const response = await fetch(`${app.url}/about`)
+    assert.equal(response.status, 200)
+    assert.match(await response.text(), /<main><h1>About<\/h1>/)
+    const { failingPage } = await import('../src/about.tsx')
+    let stack = ''
+    try {
+      failingPage()
+    } catch (error) {
+      stack = String((error as Error).stack)
+    }
+    assert.match(stack, /about\.tsx:\d+/)
+  }))
+
 test('answers health checks and 404 for unknown paths', () =>
   withApp(async (app) => {
     assert.equal((await fetch(`${app.url}/health`)).status, 200)

package/templates/blank/tsconfig.json

@@ -11,7 +11,9 @@
     "allowImportingTsExtensions": true,
     "noEmit": true,
     "skipLibCheck": true,
-    "types": ["node"]
+    "types": ["node"],
+    "jsx": "react-jsx",
+    "jsxImportSource": "#acryl-jsx"
   },
   "include": ["src", "test"]
 }

package/templates/todo/package.json

@@ -3,13 +3,17 @@
   "version": "0.1.0",
   "private": true,
   "type": "module",
+  "imports": {
+    "#acryl-jsx/jsx-runtime": "./src/plugins/acryl-router/src/core/jsx/jsx-runtime.ts",
+    "#acryl-jsx/jsx-dev-runtime": "./src/plugins/acryl-router/src/core/jsx/jsx-dev-runtime.ts"
+  },
   "engines": {
     "node": ">=22.19.0"
   },
   "scripts": {
-    "start": "node src/main.ts",
-    "dev": "node --watch src/main.ts",
-    "test": "node --test",
+    "start": "node --import ./src/plugins/acryl-node-server/src/register.ts src/main.ts",
+    "dev": "node --watch --import ./src/plugins/acryl-node-server/src/register.ts src/main.ts",
+    "test": "node --import ./src/plugins/acryl-node-server/src/register.ts --test \"test/**/*.test.{ts,tsx}\"",
     "check": "tsc --noEmit",
     "lock": "node src/plugins/manifest/lock.ts",
     "save": "node src/plugins/save/cli.ts",

package/templates/todo/tsconfig.json

@@ -11,7 +11,9 @@
     "allowImportingTsExtensions": true,
     "noEmit": true,
     "skipLibCheck": true,
-    "types": ["node"]
+    "types": ["node"],
+    "jsx": "react-jsx",
+    "jsxImportSource": "#acryl-jsx"
   },
   "include": ["src", "test"]
 }

package/templates/todo/upstream.json

@@ -5,7 +5,7 @@
       "examples/acryl-todo/src/index.ts": "src/todo.ts",
       "examples/acryl-todo/src/page.ts": "src/page.ts"
     },
-    "commit": "fd1f7dcaaff8b757c0562294002c0d32d6e0a893"
+    "commit": "7bba3ed0420d87e61d8256fa60614d22af734c8f"
   },
   "rewrittenSpecifiers": 4,
   "digest": "sha256:9093704776563001f7f472f94cc5c2fdd79206342c1cb59c11fce62aa74df3ed"