feat: better dom support and cli init. (#45)

Author: knightedcodemonkey

.github/workflows/ci.yml

@@ -33,6 +33,8 @@ jobs:
         with:
           name: npm-debug-log-${{ hashFiles('package-lock.json') }}
           path: npm-debug.log
+      - name: Check Cycles
+        run: npm run cycles
       - name: Check Types
         run: npm run check-types
       - name: Test

.github/workflows/publish.yml

@@ -3,6 +3,12 @@ name: Publish
 on:
   release:
     types: [published]
+  workflow_dispatch:
+    inputs:
+      branch:
+        description: Branch to publish from (defaults to main)
+        required: false
+        default: main
 
 permissions:
   id-token: write
@@ -13,8 +19,22 @@ jobs:
     if: contains('["knightedcodemonkey"]', github.actor)
     runs-on: ubuntu-latest
     steps:
+      - name: Determine ref
+        id: publish-ref
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            ref="${{ github.event.inputs.branch }}"
+            if [ -z "$ref" ]; then
+              ref="main"
+            fi
+          else
+            ref="${{ github.ref }}"
+          fi
+          echo "ref=$ref" >> "$GITHUB_OUTPUT"
       - name: Checkout
         uses: actions/checkout@v4.2.2
+        with:
+          ref: ${{ steps.publish-ref.outputs.ref }}
       - name: Setup Node
         uses: actions/setup-node@v4.3.0
         with:

.husky/pre-push

@@ -4,5 +4,6 @@ if (set -o pipefail) 2>/dev/null; then :; fi
 
 npm run prettier:check
 npm run lint
+npm run cycles
 npm run check-types
 npm test

README.md

@@ -99,7 +99,7 @@ The React runtime shares the same template semantics as `jsx`, except it returns
 
 - `style` accepts either a string or an object. Object values handle CSS custom properties (`--token`) automatically.
 - `class` and `className` both work and can be strings or arrays.
-- Event handlers use the `on<Event>` naming convention (e.g. `onClick`).
+- Event handlers use the `on<Event>` naming convention (e.g. `onClick`), support capture-phase variants via `on<Event>Capture`, and allow custom events with the `on:custom-event` syntax (descriptor objects with `{ handler, once, capture }` are also accepted).
 - `ref` supports callback refs as well as mutable `{ current }` objects.
 - `dangerouslySetInnerHTML` expects an object with an `__html` field, mirroring React.
 
@@ -286,6 +286,26 @@ import { reactJsx as nodeReactJsx } from '@knighted/jsx/node/react/lite'
 
 Each lite subpath ships the same API as its standard counterpart but is pre-minified and scoped to just that runtime (DOM, React, Node DOM, or Node React). Swap them in when you want the smallest possible bundles; otherwise the default exports keep working as-is.
 
+## Common gotchas
+
+### DocumentFragment reuse (DOM helper)
+
+`jsx` returns actual DOM nodes, so fragments compile down to real `DocumentFragment` instances. The browser treats those fragments as one-time transport containers: append them to a parent, and the fragment empties itself as it moves its children. Unlike VDOM libraries (React, Preact, Solid), we do not clone fragments on your behalf, so storing a fragment and reusing it later will not work the way a React developer might expect.
+
+```ts
+const header = jsx`
+  <>
+    <h1>Title</h1>
+    <p>Reusable? Only if you clone.</p>
+  </>
+`
+
+document.querySelector('header')!.append(header)
+document.querySelector('footer')!.append(header) // footer stays empty
+```
+
+When you need multiple copies, call the template again, wrap it in a helper (`const makeHeader = () => jsx`<...>`; makeHeader()`), or clone the fragment before reusing it (`footer.append(header.cloneNode(true))`). Components that return fragments are unaffected because every invocation produces a fresh fragment.
+
 ## Limitations
 
 - Requires a DOM-like environment (it throws when `document` is missing).

codecov.yml

@@ -8,3 +8,8 @@ coverage:
       default:
         target: 80.0
         threshold: 2.0
+      cli:
+        target: 55.0
+        threshold: 5.0
+        paths:
+          - src/cli/

docs/cli.md

@@ -10,7 +10,7 @@ npx @knighted/jsx init
 
 What it does by default:
 
-- Installs `@oxc-parser/binding-wasm32-wasi` plus runtime helpers (`@napi-rs/wasm-runtime`, `@emnapi/runtime`, `@emnapi/core`).
+- Installs `@oxc-parser/binding-wasm32-wasi` that matches the library's bundled `oxc-parser` version plus runtime helpers (`@napi-rs/wasm-runtime`, `@emnapi/runtime`, `@emnapi/core`).
 - Records the binding in `optionalDependencies` so the version is visible in your project.
 - Verifies the binding can be imported and reports the resolved path.
 - Skips loader config changes (prompted only when you opt in).
@@ -19,6 +19,7 @@ What it does by default:
 
 - `--package-manager`, `--pm <npm|pnpm|yarn|bun>`: override detection.
 - `--wasm-package <spec>`: install a different binding spec (or set `WASM_BINDING_PACKAGE`).
+- `--wasm-version <semver>`: override the default bundled version when using the standard binding package.
 - `--config`: prompt for loader help (no automatic edits yet; shows guidance only).
 - `--skip-config`: skip loader help (default).
 - `--dry-run`: print what would happen without executing.
@@ -40,12 +41,16 @@ npx @knighted/jsx init --pm npm
 # Prompt for loader guidance after install
 npx @knighted/jsx init --config
 
-# Use a custom binding build
-WASM_BINDING_PACKAGE=@oxc-parser/binding-wasm32-wasi@^0.100.0 npx @knighted/jsx init
+# Install a specific binding version
+npx @knighted/jsx init --wasm-version 0.100.0
+
+# Use a custom binding spec entirely
+WASM_BINDING_PACKAGE=@oxc-parser/binding-wasm32-wasi@beta npx @knighted/jsx init
 ```
 
 ## Notes
 
+- The default binding install always matches the `oxc-parser` version bundled with `@knighted/jsx`; use `--wasm-version`, `--wasm-package`, or `WASM_BINDING_PACKAGE` when you intentionally need a different build.
 - The command uses `npm pack` internally to pull the WASM binding even when it is marked for `cpu: ["wasm32"]`.
 - Loader configuration is opt-in and requires a prompt. No config files are modified unless you request help.
 - If verification fails, rerun with `--verbose` to see the resolved binding path and error details.

docs/how-it-compares.md

@@ -11,21 +11,21 @@ Use this quick matrix to see how `@knighted/jsx` stacks up against other tagged-
 | SSR / Node                 | `@knighted/jsx/node` bootstraps `linkedom`/`jsdom` automatically; fixtures cover Next.js, Lit + React hybrids, and plain Node usage. | Depends on the hyperscript target/framework to provide SSR.                                                         | Provides DOM-focused SSR utilities but no automatic shims or React interop. |
 | TypeScript support         | First-class typings for DOM + React runtimes, loader options, and Node helpers.                                                      | Community types only for the tag factory.                                                                           | Minimal typings; templates rely on generic DOM types.                       |
 | Component interoperability | Mix DOM helpers, React components, Lit roots, and loader-transformed calls in one file.                                              | Primarily a JSX stand-in for Preact or hyperscript.                                                                 | Focused on DOM updates, pairs with `uhtml/async` or low-level renderers.    |
-| Approx. size               | DOM: ~8.8 kB raw / ~2.3 kB min+gzip. Lite DOM: ~5.7 kB raw / ~2.5 kB min+gzip.                                                       | ~1 kB min+gzip.                                                                                                     | ~7 kB min+gzip.                                                             |
+| Approx. size               | DOM: ~14.3 kB raw / ~3.3 kB min+gzip. Lite DOM: ~7.8 kB raw / ~3.3 kB min+gzip.                                                      | ~1 kB min+gzip.                                                                                                     | ~7 kB min+gzip.                                                             |
 
 > `htm` and `uhtml` remain excellent when you only need lightweight hyperscript or DOM templating. `@knighted/jsx` trades a slightly larger runtime for full JSX semantics, React parity, loaders, and SSR tooling.
 
 > [!NOTE]
-> `@knighted/jsx` sizes were measured by gzipping `dist/jsx.js` (default runtime) and `dist/lite/index.js` from the latest build. The lite build is raw-smaller, but its minified output uses fewer repeated tokens, so gzip has a little less to compress (hence the slightly higher min+gzip size).
+> `@knighted/jsx` sizes were measured by gzipping `dist/jsx.js` (default runtime) and `dist/lite/index.js` from the latest build. The lite build stays raw-smaller, while gzip now lands within a few bytes of the default runtime because all helpers live in one bundle.
 
 ## Detailed size breakdown
 
-| Entry point                                   | Raw size (bytes)                                                             | Min+gzip size (bytes) | Lite raw size (bytes)                   | Lite min+gzip size (bytes) | Notes                                                                                                           |
-| --------------------------------------------- | ---------------------------------------------------------------------------- | --------------------- | --------------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| DOM runtime (`@knighted/jsx`)                 | 9,054 (`dist/jsx.js`)                                                        | 2,291                 | 5,790 (`dist/lite/index.js`)            | 2,512                      | Lite bundle packs everything into one file, so gzip sees fewer repeated tokens despite the smaller raw payload. |
-| React runtime (`@knighted/jsx/react`)         | 5,133 (`dist/react/react-jsx.js`)                                            | 1,445                 | 4,146 (`dist/lite/react/index.js`)      | 1,885                      | Same trade-off as DOM: raw-lite wins, gzip-lite is slightly larger because it inlines all helpers.              |
-| Node DOM entry (`@knighted/jsx/node`)         | 9,197 combined (`dist/jsx.js` + `dist/node/bootstrap.js` via dynamic import) | ≈3,205                | 6,954 (`dist/lite/node/index.js`)       | 3,007                      | Lite bundle already includes the bootstrap shim, so both raw and gzipped footprints shrink end-to-end.          |
-| Node React entry (`@knighted/jsx/node/react`) | 7,559 combined (`dist/react/react-jsx.js` + `dist/node/bootstrap.js`)        | ≈2,359                | 4,146 (`dist/lite/node/react/index.js`) | 1,885                      | Lite variant bundles React + bootstrap, cutting both raw and gzipped sizes.                                     |
+| Entry point                                   | Raw size (bytes)                                                              | Min+gzip size (bytes) | Lite raw size (bytes)                   | Lite min+gzip size (bytes) | Notes                                                                                                          |
+| --------------------------------------------- | ----------------------------------------------------------------------------- | --------------------- | --------------------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| DOM runtime (`@knighted/jsx`)                 | 14,580 (`dist/jsx.js`)                                                        | 3,384                 | 7,959 (`dist/lite/index.js`)            | 3,351                      | Lite bundle packs everything into one file, so gzip results now sit within a few bytes of the default runtime. |
+| React runtime (`@knighted/jsx/react`)         | 5,166 (`dist/react/react-jsx.js`)                                             | 1,454                 | 4,556 (`dist/lite/react/index.js`)      | 2,076                      | Lite React remains raw-smaller but pays a small gzip premium because it inlines helper code.                   |
+| Node DOM entry (`@knighted/jsx/node`)         | 17,006 combined (`dist/jsx.js` + `dist/node/bootstrap.js` via dynamic import) | ≈4,298                | 9,131 (`dist/lite/node/index.js`)       | 3,847                      | Lite bundle already includes the bootstrap shim, so both raw and gzipped footprints shrink end-to-end.         |
+| Node React entry (`@knighted/jsx/node/react`) | 7,592 combined (`dist/react/react-jsx.js` + `dist/node/bootstrap.js`)         | ≈2,368                | 4,556 (`dist/lite/node/react/index.js`) | 2,076                      | Lite variant bundles React + bootstrap, cutting both raw and gzipped sizes.                                    |
 
 > [!TIP]
 > Numbers were captured using `gzip -c <file> | wc -c`. “Combined” entries include every file the non-lite entry loads at runtime so you can compare end-to-end costs.

docs/next-steps.md

@@ -2,16 +2,7 @@
 
 A few focused improvements will give @knighted/jsx a more polished, batteries-included feel across editors, runtimes, and testing workflows.
 
-## 1. Type-level ergonomics
-
-- Provide opt-in helper wrappers (for example `jsx.el<'button'>`) that return concrete `HTMLElement` types, plus richer React intrinsic typing for `reactJsx` so attribute completion matches native elements.
-- Clearly explain how to mix these helpers with existing components to keep type safety predictable across DOM and React runtimes.
-
-## 2. Starter templates
-
-- Publish StackBlitz/CodeSandbox starters (DOM only, React, Lit + React) and link them from the docs so newcomers can experiment without cloning the repo.
-- Include scripts that demonstrate the CDN-only workflow alongside bundler-driven builds.
-
-## 3. Runtime diagnostics
-
-- Add a development flag that logs friendly warnings for common pitfalls (missing `key`, passing plain strings instead of nodes, etc.) to shorten the feedback loop while prototyping.
+1. **Type-level ergonomics** – Explore opt-in helpers like `jsx.el<'button'>` (or richer intrinsic maps) so DOM nodes return concrete element types, and tighten the React intrinsic typing to match native attributes. Document how these helpers compose with existing components so the DX stays predictable.
+2. **Starter templates** – Ship StackBlitz/CodeSandbox starters (DOM-only, React, Lit + React) that highlight CDN flows and bundler builds. Link them in the README/docs so developers can experiment without cloning the repo.
+3. **Runtime diagnostics** – Add an optional dev flag that surfaces friendly warnings for common pitfalls (missing `key`, fragment reuse, string refs, etc.) to shorten debugging cycles without bloating production bundles.
+4. **Bundle-size trims** – Audit shared helpers/metadata for duplication, experiment with feature flags (opt-out of advanced descriptors), and run esbuild/rollup analyzers to find dead code so the next releases can claw back some of the new bytes.

eslint.config.js

@@ -1,9 +1,12 @@
 import js from '@eslint/js'
 import pluginN from 'eslint-plugin-n'
 import playwright from 'eslint-plugin-playwright'
+import unicorn from 'eslint-plugin-unicorn'
+import vitest from '@vitest/eslint-plugin'
 import tseslint from 'typescript-eslint'
 
 const playwrightConfig = playwright.configs['flat/recommended']
+const filenameCaseIgnore = ['^README(?:\\..+)?$']
 
 export default [
   {
@@ -62,13 +65,44 @@ export default [
       '@typescript-eslint/no-explicit-any': 'off',
     },
   },
+  {
+    plugins: {
+      unicorn,
+    },
+    rules: {
+      'unicorn/filename-case': [
+        'error',
+        {
+          cases: {
+            kebabCase: true,
+          },
+          ignore: filenameCaseIgnore,
+        },
+      ],
+    },
+  },
+  {
+    ...vitest.configs.recommended,
+    files: ['test/**/*.test.{js,jsx,ts,tsx}', 'test/**/*.spec.{js,jsx,ts,tsx}'],
+  },
   {
     files: ['src/jsx-runtime.ts'],
     rules: {
       '@typescript-eslint/no-unused-vars': 'off',
       '@typescript-eslint/no-namespace': 'off',
     },
   },
+  {
+    files: ['src/jsx-runtime.ts', 'test/jsx.test.ts'],
+    rules: {
+      'n/no-unsupported-features/node-builtins': [
+        'error',
+        {
+          ignores: ['CustomEvent'],
+        },
+      ],
+    },
+  },
   {
     ...playwrightConfig,
     files: ['playwright/**/*.{ts,tsx,js}'],

examples/esm-demo.html

@@ -491,29 +491,29 @@ <h1>@knighted/jsx + esm.sh</h1>
         {
           entry: '@knighted/jsx/lite',
           context: 'DOM runtime helpers',
-          raw: '~5.7 kB raw',
-          gzip: '~2.5 kB min+gzip',
+          raw: '~7.8 kB raw',
+          gzip: '~3.3 kB min+gzip',
           note: 'Great for browser demos or DOM-like shims without bundlers.',
         },
         {
           entry: '@knighted/jsx/react/lite',
           context: 'React runtime helpers',
-          raw: '~4.1 kB raw',
-          gzip: '~1.9 kB min+gzip',
+          raw: '~4.6 kB raw',
+          gzip: '~2.1 kB min+gzip',
           note: 'Emits React elements so hooks and React 19 streaming just work.',
         },
         {
           entry: '@knighted/jsx/node/lite',
           context: 'Node DOM entry',
-          raw: '~6.9 kB raw',
-          gzip: '~3.0 kB min+gzip',
+          raw: '~9.1 kB raw',
+          gzip: '~3.8 kB min+gzip',
           note: 'Bundles the DOM shim bootstrap for headless SSR scripts.',
         },
         {
           entry: '@knighted/jsx/node/react/lite',
           context: 'Node React entry',
-          raw: '~4.1 kB raw',
-          gzip: '~1.9 kB min+gzip',
+          raw: '~4.6 kB raw',
+          gzip: '~2.1 kB min+gzip',
           note: jsx`<span>Combines the <code>reactJsx</code> helper with the DOM shim for hybrid SSR pipelines.</span>`,
         },
       ]