feat: transform entrypoint. (#88)

Author: knightedcodemonkey

README.md

@@ -68,39 +68,52 @@ const button = jsx`
 document.body.append(button)
 ```
 
-### Source transpilation (`transpileJsxSource`)
+### Source transpilation (`transpileJsxSource` + `transformJsxSource`)
 
-Need to transform raw JSX source text (e.g. code typed in an editor) without Babel? Use `transpileJsxSource`:
+Need to transform raw JSX source text (for example, code typed in an editor) without Babel?
+Use one of these subpath exports:
+
+- `@knighted/jsx/transpile` for code-only output (`{ code, changed }`).
+- `@knighted/jsx/transform` for code plus parser-backed import metadata and diagnostics
+  (`{ code, changed, imports, diagnostics }`).
 
 ```ts
 import { transpileJsxSource } from '@knighted/jsx/transpile'
+import { transformJsxSource } from '@knighted/jsx/transform'
 
 const input = `
-const App = () => {
-  return <button>click me</button>
-}
+import React from 'react'
+const App = () => <button>click me</button>
 `
 
-const { code } = transpileJsxSource(input)
-// -> const App = () => { return React.createElement("button", null, "click me") }
+const transpiled = transpileJsxSource(input)
+// -> { code, changed }
+
+const transformed = transformJsxSource(input, { typescript: 'strip' })
+// -> { code, changed, imports, diagnostics }
 ```
 
-By default this emits `React.createElement(...)` and `React.Fragment`. Override them when needed:
+Both entrypoints emit `React.createElement(...)` and `React.Fragment` by default. Override
+them when needed:
 
 ```ts
 transpileJsxSource(input, {
   createElement: '__jsx',
   fragment: '__fragment',
 })
+
+transformJsxSource(input, {
+  createElement: '__jsx',
+  fragment: '__fragment',
+})
 ```
 
-By default, TypeScript syntax is preserved in the output. If your source needs to run directly
-as JavaScript (for example, code entered in an editor), enable type stripping:
+By default, TypeScript syntax is preserved in output. If your source needs to run directly as
+JavaScript, enable type stripping:
 
 ```ts
-transpileJsxSource(input, {
-  typescript: 'strip',
-})
+transpileJsxSource(input, { typescript: 'strip' })
+transformJsxSource(input, { typescript: 'strip' })
 ```
 
 Supported `typescript` modes:
@@ -109,6 +122,13 @@ Supported `typescript` modes:
 - `'strip'`: remove type-only declarations and erase inline type syntax (`: T`, `as T`,
   `satisfies T`, non-null assertions, and type assertions) while still transpiling JSX.
 
+Environment note:
+
+- Both APIs are ESM-first and work in Node.
+- For direct browser usage of `@knighted/jsx/transform`, use a CDN/runtime that can resolve
+  `oxc-transform` for the browser build (for example, modern ESM CDNs that bundle or map
+  WASM/native bindings automatically).
+
 ### React runtime (`reactJsx`)
 
 Need to compose React elements instead of DOM nodes? Import the dedicated helper from the `@knighted/jsx/react` subpath (React 18+ and `react-dom` are still required to mount the tree):

docs/next-steps.md

@@ -6,4 +6,4 @@ A few focused improvements will give @knighted/jsx a more polished, batteries-in
 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. **Diagnostics UX polish** – Build on the new `enableJsxDebugDiagnostics` helper by surfacing template codeframes, component names, and actionable remediation steps. Ship CLI toggles / README callouts so CDN demos and starters enable debug mode automatically in development while keeping production bundles pristine.
 4. **Bundle-size trims** – With debug helpers moved to opt-in paths, refocus on analyzer-driven trims (property-information lookups, node bootstrap reuse, shared helper chunks). Validate the new floor across lite + standard builds with `npm run sizecheck` and document any remaining hotspots so future releases keep shrinking.
-5. **TypeScript transform strategy** – Evaluate replacing (or augmenting) manual TS syntax erasure in `transpileJsxSource` with `oxc-transform` for `typescript: 'strip'` mode. Build a fixture matrix (annotations, interfaces/type aliases, `as`, `satisfies`, non-null assertions, generics) and compare output correctness, runtime behavior, and bundle impact before deciding whether to adopt `oxc-transform` as the default implementation.
+5. **CLI init support for transform browser runtime** – Extend `@knighted/jsx init` so browser-oriented projects can opt into the `@knighted/jsx/transform` runtime path with the required `oxc-transform` browser/WASM setup (and clear install guidance for bundler vs CDN flows). Define a small contract for what init configures, then validate with fixture projects that call `transformJsxSource` in browser builds and confirm both successful execution and actionable failure diagnostics when bindings are missing.