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

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)
+```

app/about/page.tsx

@@ -0,0 +1,25 @@
+import type { PageProps } from '../../source/types.js';
+
+/**
+ * About page – `app/about/page.tsx` maps to the `/about` route.
+ */
+export default async function AboutPage(_props: PageProps) {
+    return (
+        <main>
+            <h1>About WebSSR</h1>
+            <p>
+                WebSSR is a lightweight server-side rendering framework for
+                Web Components.  It follows the{' '}
+                <a href="https://developer.chrome.com/docs/css-ui/declarative-shadow-dom">
+                    Declarative Shadow DOM
+                </a>{' '}
+                standard for HTML serialisation and DOM hydration, uses Koa
+                for the HTTP layer, and leverages Parcel 2 for client-side
+                bundling.
+            </p>
+            <nav>
+                <a href="/">Home</a>
+            </nav>
+        </main>
+    );
+}

app/page.tsx

@@ -0,0 +1,29 @@
+import type { PageProps } from '../source/types.js';
+
+/**
+ * Home page – `app/page.tsx` maps to the `/` route.
+ *
+ * This is an async server component: it may perform data-fetching before
+ * returning JSX.  The JSX is serialised to a declarative-shadow-DOM HTML
+ * string by the WebSSR renderer.
+ */
+export default async function HomePage({ searchParams }: PageProps) {
+    const name = searchParams['name'] ?? 'World';
+
+    return (
+        <main>
+            <h1>Hello, {name}!</h1>
+            <p>
+                Welcome to <strong>WebSSR</strong> – a Web Components
+                server-side rendering framework built on{' '}
+                <a href="https://github.com/EasyWebApp/DOM-Renderer">
+                    DOM-Renderer
+                </a>{' '}
+                and Declarative Shadow DOM.
+            </p>
+            <nav>
+                <a href="/about">About</a>
+            </nav>
+        </main>
+    );
+}