refactored to packages

Author: srdjan

CLAUDE.md

@@ -19,7 +19,13 @@ deno run --allow-net --allow-read examples/todos/server.ts
 
 ## Architecture
 
-**JSX Transform Pipeline:**
+HSX is a monorepo with two packages:
+
+**Packages:**
+- `@srdjan/hsx` (packages/hsx/) - Core JSX renderer, `render()`, `renderHtml()`, `route()`, `id()`, `Fragment`, `hsxComponent()`, `hsxPage()`
+- `@srdjan/hsx-styles` (packages/hsx-styles/) - `hsxStyles`, `hsxStylesDark`, `HSX_STYLES_PATH`
+
+**JSX Transform Pipeline (packages/hsx/):**
 1. `jsx-runtime.ts` - Minimal JSX runtime producing VNode tree
 2. `render.ts` - Walks VNode tree, normalizes HSX props per element type, auto-injects HTMX script before `</body>` when needed
 3. `hsx-normalize.ts` - Maps HSX attributes → `hx-*` attributes, tracks HTMX usage via RenderContext
@@ -36,12 +42,15 @@ deno run --allow-net --allow-read examples/todos/server.ts
 
 **Safety:** `script`/`style` children are emitted verbatim (no escaping); never pass user input there.
 
-**Entry Points (Modular):**
-- `index.ts` (`.`) - Everything: `render`, `renderHtml`, `route`, `id`, `Fragment`, `hsxComponent`, `hsxPage`
-- `core.ts` (`./core`) - Core rendering: `render`, `renderHtml`, `route`, `id`, `Fragment`, types
-- `component-model.ts` (`./component-model`) - Higher-level: `hsxComponent`, `hsxPage`
-- `styles.ts` (`./styles`) - Optional CSS: `hsxStyles`, `hsxStylesDark`, `HSX_STYLES_PATH`
-- `jsx-runtime.ts` (`./jsx-runtime`) - JSX compiler requirement (not for direct import)
+**Imports (Workspace-aware):**
+```ts
+import { render, id, route, Fragment, hsxComponent, hsxPage } from "@srdjan/hsx";
+import { hsxStyles, hsxStylesDark, HSX_STYLES_PATH } from "@srdjan/hsx-styles";
+```
+
+**Legacy exports** are maintained for backward compatibility via root deno.json:
+- `./core` → `packages/hsx/mod.ts`
+- `./styles` → `packages/hsx-styles/mod.ts`
 
 ## Key Patterns
 
@@ -85,6 +94,14 @@ const ids = { list: id("todo-list") };  // Type: Id<"todo-list"> = "#todo-list"
 
 ## JSX Configuration
 
-Files using JSX need either:
-- Pragma: `/** @jsxImportSource ./src */` at file top
-- Or rely on `deno.json` compilerOptions (already configured)
+Files using JSX rely on root `deno.json` compilerOptions (already configured):
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "hsx"
+  }
+}
+```
+
+The workspace `imports` map resolves `hsx/jsx-runtime` to `packages/hsx/jsx-runtime.ts`.

README.md

@@ -1,10 +1,14 @@
 # HSX
 
-SSR-only JSX/TSX renderer for Deno that compiles HTMX-style attributes to `hx-*`
-on the server.
+First things, first... What the hack does HSX stand for? I'll say it's '**H**TML
+for **S**erver-Side e**X**tensions'. :0
+
+But, silently, I prefer: **H**TML **S**laps **X**tremely :)
+
+SSR-only JSX/TSX renderer for Deno that hides HTMX-style attributes away during the rendering process, and compiles them to `hx-*` attributes.
 
 > Disclaimer: this was a quick hack in my free time, held together by vibe
-> coding and espresso. I like it a lot, but consider it an early release.
+> coding and espresso. I like it a lot, but consider it an early release. I feel it is getting better (a lot)
 
 ## TL;DR: : Like JSX, but for SSR HTML + HTMX.
 
@@ -35,30 +39,40 @@ Or import directly:
 import { id, render, route } from "jsr:@srdjan/hsx";
 ```
 
-### Selective Imports (Tree-Shaking)
+### Separate Packages
 
-HSX supports modular imports for smaller bundles:
+HSX is a monorepo with two packages:
 
 ```ts
-// Core only - rendering + type-safe routes (excludes hsxComponent/hsxPage)
-import { render, route, id, Fragment } from "jsr:@srdjan/hsx/core";
+// Core - JSX rendering, type-safe routes, hsxComponent, hsxPage
+import { Fragment, hsxComponent, hsxPage, id, render, route } from "jsr:@srdjan/hsx";
 
-// Component model only - higher-level abstractions
-import { hsxComponent, hsxPage } from "jsr:@srdjan/hsx/component-model";
+// Styles - ready-to-use CSS with theming support
+import { HSX_STYLES_PATH, hsxStyles } from "jsr:@srdjan/hsx-styles";
+```
 
-// Everything (default)
-import { render, route, hsxComponent, hsxPage } from "jsr:@srdjan/hsx";
+Install individually:
 
-// Optional styles - ready-to-use CSS with theming support
-import { hsxStyles, HSX_STYLES_PATH } from "jsr:@srdjan/hsx/styles";
+```bash
+deno add jsr:@srdjan/hsx
+deno add jsr:@srdjan/hsx-styles
+```
+
+### Legacy Exports (Backward Compatible)
+
+For backward compatibility, subpath exports still work:
+
+```ts
+import { Fragment, id, render, route } from "jsr:@srdjan/hsx/core";
+import { HSX_STYLES_PATH, hsxStyles } from "jsr:@srdjan/hsx/styles";
 ```
 
 ### From Source
 
-Clone and import:
+Clone and import using workspace package names:
 
 ```ts
-import { id, render, route } from "./src/index.ts";
+import { hsxComponent, hsxPage, id, render, route } from "@srdjan/hsx";
 ```
 
 ## Quick Start (Low-Level API)
@@ -67,8 +81,7 @@ import { id, render, route } from "./src/index.ts";
 > the [hsxComponent pattern](#hsx-component-pattern-recommended) below instead.
 
 ```tsx
-/** @jsxImportSource ./src */
-import { id, render, route } from "./src/index.ts";
+import { id, render, route } from "@srdjan/hsx";
 
 const routes = {
   todos: route("/todos", () => "/todos"),
@@ -346,7 +359,11 @@ if (url.pathname === "/static/htmx.js") {
 HSX includes an optional CSS module with a default theme and dark variant:
 
 ```ts
-import { hsxStyles, hsxStylesDark, HSX_STYLES_PATH } from "jsr:@srdjan/hsx/styles";
+import {
+  HSX_STYLES_PATH,
+  hsxStyles,
+  hsxStylesDark,
+} from "jsr:@srdjan/hsx-styles";
 
 // Serve the styles
 if (url.pathname === HSX_STYLES_PATH) {
@@ -356,23 +373,24 @@ if (url.pathname === HSX_STYLES_PATH) {
 }
 
 // In your page head
-<link rel="stylesheet" href={HSX_STYLES_PATH} />
+<link rel="stylesheet" href={HSX_STYLES_PATH} />;
 ```
 
 **Exports:**
+
 - `hsxStyles` - Default light theme (indigo accent)
 - `hsxStylesDark` - Dark theme variant
 - `HSX_STYLES_PATH` - Default path: `/static/hsx.css`
 
 **Customization:** Override CSS variables in your page:
 
 ```tsx
-<style>{`:root { --hsx-accent: #10b981; --hsx-bg: #f0fdf4; }`}</style>
+<style>{`:root { --hsx-accent: #10b981; --hsx-bg: #f0fdf4; }`}</style>;
 ```
 
-Available variables: `--hsx-accent`, `--hsx-bg`, `--hsx-surface`, `--hsx-border`,
-`--hsx-text`, `--hsx-muted`, `--hsx-error`, `--hsx-success`, spacing (`--hsx-space-*`),
-and radius (`--hsx-radius-*`).
+Available variables: `--hsx-accent`, `--hsx-bg`, `--hsx-surface`,
+`--hsx-border`, `--hsx-text`, `--hsx-muted`, `--hsx-error`, `--hsx-success`,
+spacing (`--hsx-space-*`), and radius (`--hsx-radius-*`).
 
 ## API Reference
 
@@ -483,34 +501,34 @@ Run examples with `deno task`:
 ## Project Structure
 
 ```
-src/
-  index.ts          # Main entry - exports everything
-  core.ts           # Core module - render, route, id, Fragment, types
-  component-model.ts # Component module - hsxComponent, hsxPage
-  styles.ts         # Optional CSS module with themes
-  jsx-runtime.ts    # Minimal JSX runtime (compiler requirement)
-  render.ts         # SSR renderer with HTMX injection
-  hsx-normalize.ts  # HSX to hx-* attribute mapping
-  hsx-component.ts  # hsxComponent factory (route + handler + render)
-  hsx-page.ts       # hsxPage guardrail for full-page layouts
-  hsx-types.ts      # Route, Id, HsxSwap, HsxTrigger types
-  hsx-jsx.d.ts      # JSX type declarations
+packages/
+  hsx/                   # Core package (@srdjan/hsx)
+    mod.ts               # Main entry point
+    jsx-runtime.ts       # Minimal JSX runtime (compiler requirement)
+    render.ts            # SSR renderer with HTMX injection
+    hsx-normalize.ts     # HSX to hx-* attribute mapping
+    hsx-types.ts         # Route, Id, HsxSwap, HsxTrigger types
+    hsx-jsx.d.ts         # JSX type declarations
+    hsx-component.ts     # hsxComponent factory (route + handler + render)
+    hsx-page.ts          # hsxPage guardrail for full-page layouts
+  hsx-styles/            # Styles package (@srdjan/hsx-styles)
+    mod.ts               # Main entry point (CSS themes)
 examples/
-  todos/            # Full todo app example
-  active-search/    # Search example
-  lazy-loading/     # Lazy load example
-  form-validation/  # Form validation example
-  polling/          # Polling example
-  tabs-modal/       # Tabs and modal example
-  hsx-components/   # HSX Component pattern example
-  hsx-page/         # hsxPage full-page guardrail example
-  low-level-api/    # Manual render/renderHtml without hsxPage/hsxComponent
+  todos/                 # Full todo app example
+  active-search/         # Search example
+  lazy-loading/          # Lazy load example
+  form-validation/       # Form validation example
+  polling/               # Polling example
+  tabs-modal/            # Tabs and modal example
+  hsx-components/        # HSX Component pattern example
+  hsx-page/              # hsxPage full-page guardrail example
+  low-level-api/         # Manual render/renderHtml without hsxPage/hsxComponent
 vendor/htmx/
-  htmx.js           # Vendored HTMX v4 (alpha)
+  htmx.js                # Vendored HTMX v4 (alpha)
 docs/
-  USER_GUIDE.md     # Comprehensive user guide
-  HSX_OVERVIEW.md   # Architecture overview
-  HTMX_INTEGRATION.md # HTMX integration details
+  USER_GUIDE.md          # Comprehensive user guide
+  HSX_OVERVIEW.md        # Architecture overview
+  HTMX_INTEGRATION.md    # HTMX integration details
 ```
 
 ## License

deno.json

@@ -1,16 +1,20 @@
 {
-  "name": "@srdjan/hsx",
-  "version": "0.6.0",
+  "workspace": [
+    "./packages/hsx",
+    "./packages/hsx-styles"
+  ],
   "exports": {
-    ".": "./src/index.ts",
-    "./jsx-runtime": "./src/jsx-runtime.ts",
-    "./core": "./src/core.ts",
-    "./component-model": "./src/component-model.ts",
-    "./styles": "./src/styles.ts"
+    ".": "./packages/hsx/mod.ts",
+    "./jsx-runtime": "./packages/hsx/jsx-runtime.ts",
+    "./core": "./packages/hsx/mod.ts",
+    "./component-model": "./packages/hsx/mod.ts",
+    "./styles": "./packages/hsx-styles/mod.ts"
   },
   "license": "MIT",
   "imports": {
-    "hsx/jsx-runtime": "./src/jsx-runtime.ts"
+    "@srdjan/hsx": "./packages/hsx/mod.ts",
+    "@srdjan/hsx-styles": "./packages/hsx-styles/mod.ts",
+    "hsx/jsx-runtime": "./packages/hsx/jsx-runtime.ts"
   },
   "compilerOptions": {
     "jsx": "react-jsx",
@@ -19,8 +23,8 @@
     "strict": true
   },
   "tasks": {
-    "test": "deno test src/ --allow-read",
-    "check": "deno check src/index.ts",
+    "test": "deno test packages/ --allow-read",
+    "check": "deno check packages/hsx/mod.ts packages/hsx-styles/mod.ts",
     "example:todos": "deno run --allow-net --allow-read examples/todos/server.tsx",
     "example:active-search": "deno run --allow-net --allow-read examples/active-search/server.tsx",
     "example:lazy-loading": "deno run --allow-net --allow-read examples/lazy-loading/server.tsx",

examples/active-search/ids.ts

@@ -3,7 +3,7 @@
  *
  * Demonstrates type-safe element IDs for HTMX targeting.
  */
-import { id } from "../../src/hsx-types.ts";
+import { id } from "@srdjan/hsx";
 
 export const ids = {
   results: id("search-results"),

examples/active-search/server.tsx

@@ -9,8 +9,9 @@
  * - `vals` for passing additional data
  * - CSS indicator class for loading states
  */
-import { hsxComponent, hsxPage, id } from "../../src/index.ts";
-import { hsxStyles, HSX_STYLES_PATH } from "../../src/styles.ts";
+import { hsxComponent, hsxPage } from "@srdjan/hsx";
+import { id } from "@srdjan/hsx";
+import { hsxStyles, HSX_STYLES_PATH } from "@srdjan/hsx-styles";
 
 // =============================================================================
 // Sample Data

examples/form-validation/components.tsx

@@ -1,7 +1,7 @@
 /**
  * Shared UI wrapper components for cleaner JSX
  */
-import type { HsxSwap, Urlish } from "../../src/hsx-types.ts";
+import type { HsxSwap, Urlish } from "@srdjan/hsx";
 
 export function Subtitle(props: { children: string }) {
   return (

examples/form-validation/ids.ts

@@ -1,7 +1,7 @@
 /**
  * Form Validation Example - Branded IDs
  */
-import { id } from "../../src/hsx-types.ts";
+import { id } from "@srdjan/hsx";
 
 export const ids = {
   usernameError: id("username-error"),

examples/form-validation/server.tsx

@@ -1,5 +1,5 @@
-import { hsxComponent, hsxPage } from "../../src/index.ts";
-import { hsxStyles, HSX_STYLES_PATH } from "../../src/styles.ts";
+import { hsxComponent, hsxPage } from "@srdjan/hsx";
+import { hsxStyles, HSX_STYLES_PATH } from "@srdjan/hsx-styles";
 import { Card, Subtitle } from "./components.tsx";
 import { ids } from "./ids.ts";
 

examples/hsx-components/server.tsx

@@ -5,8 +5,9 @@
  * component are co-located in a single definition with type-safe
  * enforcement between handler output and component props.
  */
-import { hsxComponent, hsxPage, id } from "../../src/index.ts";
-import { hsxStyles, HSX_STYLES_PATH } from "../../src/styles.ts";
+import { hsxComponent, hsxPage } from "@srdjan/hsx";
+import { id } from "@srdjan/hsx";
+import { hsxStyles, HSX_STYLES_PATH } from "@srdjan/hsx-styles";
 
 // =============================================================================
 // Types & Data

examples/hsx-page/server.tsx

@@ -1,5 +1,6 @@
-import { hsxComponent, hsxPage, id, render } from "../../src/index.ts";
-import { hsxStylesDark, HSX_STYLES_PATH } from "../../src/styles.ts";
+import { hsxComponent, hsxPage } from "@srdjan/hsx";
+import { id } from "@srdjan/hsx";
+import { hsxStylesDark, HSX_STYLES_PATH } from "@srdjan/hsx-styles";
 
 // ---------------------------------------------------------------------------
 // Data (in-memory for demo)