feat: implement Web Components SSR framework with Koa 3, DOM-Renderer, Parcel 2, and CLI

.gitignore

@@ -137,3 +137,4 @@ dist
 # Vite logs files
 vite.config.js.timestamp-*
 vite.config.ts.timestamp-*
+.webssr/

README.md

@@ -1,2 +1,87 @@
 # WebSSR
-SSR framework for Web components standard, which is based on WebCell design & infrastructure.
+
+SSR framework for Web components standard, which is based on WebCell design & infrastructure.
+
+## Overview
+
+WebSSR is a lightweight **server-side rendering framework** for the [Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) standard. It renders pages using JSX on the server via [DOM-Renderer](https://github.com/EasyWebApp/DOM-Renderer) and serialises shadow roots with the [Declarative Shadow DOM](https://developer.chrome.com/docs/css-ui/declarative-shadow-dom) standard so browsers can hydrate without JavaScript.
+
+## Requirements
+
+- **Node.js ≥ 22**
+
+## Architecture
+
+| Concern | Technology |
+|---------|------------|
+| HTTP server | [Koa](https://koajs.com/) |
+| JSX → HTML streaming | [DOM-Renderer](https://github.com/EasyWebApp/DOM-Renderer) |
+| HTML serialisation / hydration | [Declarative Shadow DOM](https://github.com/EasyWebApp/declarative-shadow-dom-polyfill) |
+| File-based routing | Next.js App Router convention (`app/**/page.tsx`) |
+| Client component bundling | Parcel 2 (custom transformer plugin) |
+
+## Getting Started
+
+```bash
+npm install
+npm start          # production
+npm run dev        # development (auto-restarts on file changes)
+```
+
+The server listens on port **3000** by default. Override with the `PORT` environment variable.
+
+## File-Based Routing
+
+Pages live under the `app/` directory and follow the Next.js App Router naming convention:
+
+```
+app/
+  page.tsx              →  GET /
+  about/
+    page.tsx            →  GET /about
+  users/
+    [id]/
+      page.tsx          →  GET /users/:id
+```
+
+Each `page.tsx` must export an **async default function** that returns JSX:
+
+```tsx
+// app/page.tsx
+import type { PageProps } from '../source/types.js';
+
+export default async function HomePage({ params, searchParams }: PageProps) {
+  return <h1>Hello, {searchParams.name ?? 'World'}!</h1>;
+}
+```
+
+## Client Components
+
+Mark a module as a *client component* using the import attribute `with { runtime: 'client' }`:
+
+```tsx
+import { MyButton } from './MyButton' with { runtime: 'client' };
+```
+
+The **Parcel 2 transformer plugin** (`source/parcel-plugin/index.ts`) intercepts these imports:
+
+- **Server build** – replaces the import with a lightweight stub object so that the SSR renderer can emit the right custom-element tag without executing browser-only code.
+- **Client build** – leaves the import unchanged so Parcel bundles the real component code for the browser.
+
+## Project Structure
+
+```
+source/
+  server.ts           Koa HTTP server entry point
+  router.ts           File-based routing (scans app/**/page.tsx)
+  renderer.ts         JSX → HTML via DOMRenderer (static + streaming)
+  polyfill.ts         happy-dom DOM environment setup for SSR
+  types.ts            Shared TypeScript types (PageProps, PageComponent)
+  parcel-plugin/
+    index.ts          Parcel 2 Transformer for client component boundaries
+
+app/
+  page.tsx            Example home page  (GET /)
+  about/
+    page.tsx          Example about page (GET /about)
+```

package.json

@@ -0,0 +1,52 @@
+{
+    "name": "web-ssr",
+    "version": "0.1.0",
+    "description": "SSR framework for Web Components based on Declarative Shadow DOM",
+    "keywords": [
+        "web-components",
+        "ssr",
+        "server-side-rendering",
+        "declarative-shadow-dom",
+        "koa",
+        "jsx"
+    ],
+    "license": "LGPL-3.0-or-later",
+    "packageManager": "pnpm@10.33.0",
+    "type": "module",
+    "engines": {
+        "node": ">=22"
+    },
+    "bin": {
+        "webssr": "./dist/cli.js"
+    },
+    "exports": {
+        ".": "./dist/index.js",
+        "./parcel-plugin": "./dist/parcel-plugin/index.js"
+    },
+    "scripts": {
+        "start": "node --import tsx/esm --import ./source/polyfill.ts source/server.ts",
+        "dev": "node --watch --import tsx/esm --import ./source/polyfill.ts source/server.ts",
+        "build": "tsc",
+        "test": "node --import tsx/esm --import ./source/polyfill.ts --test 'test/**/*.test.ts' 'test/**/*.test.tsx'"
+    },
+    "dependencies": {
+        "@koa/router": "^15.4.0",
+        "@parcel/core": "^2.16.4",
+        "commander-jsx": "^0.7.3",
+        "dom-renderer": "^2.6.4",
+        "happy-dom": "^20.8.9",
+        "koa": "^3.2.0",
+        "koa-static": "^5.0.0"
+    },
+    "overrides": {
+        "happy-dom": "^20.8.9"
+    },
+    "devDependencies": {
+        "@parcel/plugin": "^2.16.4",
+        "@types/koa": "^3.0.2",
+        "@types/koa-static": "^4.0.4",
+        "@types/node": "^22.0.0",
+        "tsx": "^4.19.3",
+        "typescript": "^5.8.3"
+    }
+}