@lengkapp/edge 0.0.43 → 0.0.44

package/README.md

@@ -1,881 +1,820 @@
 # @lengkapp/edge
 
-A minimal, high-performance framework for Cloudflare Workers with built-in server-side rendering, routing, caching, and a declarative client-side partial-update library.
+A minimal, high-performance framework for Cloudflare Workers with built-in server-side rendering, routing, caching, compression, and a declarative client-side partial-update library.
 
-Inspired by Hono, `@lengkapp/edge` aims for the same class of performance while shipping with zero runtime dependencies.
-
-**Security:** The server is hardened against the OWASP Top 10:2025 and ASVS 5.0 Layer 1 controls — prototype-safe params, cookies, JSON bodies and JSX attributes; CSP-friendly response headers; fail-closed middleware; strict CORS allowlist; and structured security logging. See [Security](#security-controls).
-
----
+Inspired by [Hono](https://hono.dev), `@lengkapp/edge` targets the same class of performance while shipping with **zero runtime dependencies**.
 
 ## Table of Contents
 
 - [Features](#features)
 - [Installation](#installation)
+- [Project Setup](#project-setup)
 - [Quick Start](#quick-start)
-- [Server API](#server-api)
-- [JSX Support](#jsx-support)
-- [Full Example](#full-example)
-- [Client (Declarative Partial Updates)](#client-declarative-partial-updates)
-- [Device Fingerprint](#device-fingerprint)
-- [CSRF Protection](#csrf-protection)
-- [Security Controls](#security-controls)
-- [OWASP 2025 Coverage](#owasp-2025-coverage)
-- [Scheduled Tasks](#scheduled-tasks)
-- [Configuration](#configuration)
-- [Performance](#performance)
-- [Security Posture Summary](#security-posture-summary)
+- [Routing](#routing)
+- [Context API](#context-api)
+- [JSX & Server-Side Rendering](#jsx--server-side-rendering)
+- [Route Options](#route-options)
+- [Caching](#caching)
+- [Compression](#compression)
+- [CORS](#cors)
+- [Security](#security)
+- [Scheduled Handler](#scheduled-handler)
+- [Client-Side Partial Updates](#client-side-partial-updates)
+- [Complete Example](#complete-example)
 - [License](#license)
 
----
-
 ## Features
 
-### Server
+| | Feature | Description |
+|---|---|---|
+| ⚡ | **Fast router** | Static routes in a `Map`, dynamic routes in a trie — O(1) for static, O(segments) for params |
+| 🧩 | **Async JSX SSR** | `renderToString` supports async function components and streams nothing it doesn't need |
+| 🔒 | **Secure by default** | `nosniff`, `DENY` framing, strict referrer policy, permissions policy, URL/attribute sanitisation |
+| 🗄️ | **Edge caching** | `caches.default` integration with `ttl` and `stale-while-revalidate` |
+| 🗜️ | **Compression** | gzip / deflate via `CompressionStream`, content-type aware |
+| 🌐 | **CORS** | Per-route, wildcard / allow-list / exact-match |
+| 🍪 | **Cookies** | Lazy parsing, safe keys, full `Set-Cookie` option support |
+| 🪶 | **Client runtime** | ~2 KB IIFE: fetch + swap HTML from HTML attributes. No build step |
+| 📦 | **Zero deps** | Nothing but the platform |
 
-- **Trie-based routing** – static & dynamic routes (`/users/:id`)
-- **JSX support** – pass JSX straight to `ctx.html(<Card />)`; no build step, no manual `renderToString` call
-- **Middleware** – CORS, logging, caching, compression, validation
-- **Cookie helpers** with validation
-- **Scheduled tasks** via Cron triggers
-- **Zero dependencies**
+## Installation
 
-### Client
+```bash
+npm install @lengkapp/edge
+```
 
-- **Declarative partial updates** via `_get` / `_post` and the placement modes `_in`, `_out`, `_before`, `_after`
-- **Client-side navigation** via `_go` (same tab) and `_open` (new tab) — no fetch, no loader
-- **Opt-in device fingerprint** via `_id` — Canvas, WebGL, Audio, font probe, and basic navigator signals, hashed once per page; sent as `X-DeviceId` on `_get` / `_post` and as `?_did=` on `_go` / `_open`
-- **Event, load, and visibility triggers** – `click` (default), `load`, `visible`, or any DOM event name
-- **JSON and form bodies** – `_json="a,b,c"` or `_form="#signup"`
-- **Built-in loading and error states** – deferred spinner, skeleton loader, abortable requests, one-click retry
-- **View Transitions aware** – swaps run inside `document.startViewTransition` when available
-- **Zero dependencies**
+The package is ESM-only (`"type": "module"`).
 
-### Security
+## Project Setup
 
-- **Prototype-pollution safe** – route params, cookies, JSON bodies, JSX attributes
-- **XSS-hardened JSX** – no `on*` attributes, no `javascript:` URLs, no malformed tag names
-- **Structured security logging** – throttled JSON events for validation and handler failures
-- **Fail-closed middleware** – validation and handler errors deny by default
-- **Strict CORS allowlist** – per-origin reflection with `Vary: Origin`
+**`wrangler.toml`**
 
----
+```toml
+name = 'my-edge-app'
+main = 'index.js'
+compatibility_date = "2026-08-31"
+```
 
-## Installation
+**`package.json`**
 
-```bash
-npm install @lengkapp/edge
+```json
+{
+  "name": "my-edge-app",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy --minify"
+  },
+  "devDependencies": {
+    "@lengkapp/edge": "^0.0.40",
+    "wrangler": "^4.129.0"
+  }
+}
 ```
 
 ## Quick Start
 
-`worker.js`:
+**`index.js`**
 
-```ts
-import { Edge } from '@lengkapp/edge';
+```jsx
+/** @jsx jsx */
+/** @jsxFrag Fragment */
+import { Edge, jsx, Fragment } from '@lengkapp/edge';
 
 const app = new Edge();
 
-app.get('/', (ctx) => ctx.text('Hello World!'));
-app.get('/users/:id', (ctx) => ctx.json({ id: ctx.params.id }));
+app.get('/', (c) =>
+  c.page(
+    <html lang="en">
+      <head>
+        <meta charset="utf-8" />
+        <title>Hello Edge</title>
+      </head>
+      <body>
+        <h1>Hello, {c.query.get('name') || 'world'}!</h1>
+      </body>
+    </html>
+  )
+);
 
 export default app;
 ```
 
-Or, if you will use JSX, `worker.tsx`:
+```bash
+npm run dev      # http://localhost:8787
+npm run deploy
+```
 
-```tsx
-import { Edge, jsx, Fragment } from '@lengkapp/edge';
+> **Why `export default app`?**
+> The `Edge` instance exposes a `fetch(request, env, executionCtx)` method, which is exactly the Workers module-syntax contract.
 
-const app = new Edge();
+### JSX pragma
 
-const Card = () => (
-  <div>card</div>
-);
+The framework uses the classic JSX transform. Add these two comments at the top of every file that contains JSX:
 
-const LandingPage = () => (
-  <>
-    <h1>hello world</h1>
-    <Card />
-  </>
-);
-
-app.get('/', () => <LandingPage />);
-
-export default app;
+```js
+/** @jsx jsx */
+/** @jsxFrag Fragment */
+import { jsx, Fragment } from '@lengkapp/edge';
 ```
 
-If you use TypeScript, `tsconfig.json`:
+That's all the configuration required — no Babel, no tsconfig, no plugin.
 
-```json
-{
-  "compilerOptions": {
-    "jsx": "react",
-    "jsxFactory": "jsx",
-    "jsxFragmentFactory": "Fragment",
-    "paths": { "@/*": ["./src/*"] },
-    "types": ["@cloudflare/workers-types"],
-    "target": "ESNext",
-    "module": "ESNext",
-    "moduleResolution": "Bundler",
-    "strict": true,
-    "skipLibCheck": true,
-    "lib": ["ESNext", "WebWorker"]
-  }
-}
+## Routing
+
+```js
+app.get(path, [options], handler);
+app.post(path, [options], handler);
+app.put(path, [options], handler);
+app.delete(path, [options], handler);
+app.patch(path, [options], handler);
+app.options(path, [options], handler);
+app.head(path, [options], handler);
 ```
 
-`wrangler.jsonc`:
+`options` may be omitted entirely, or passed as the second argument:
 
-```jsonc
-{
-  "$schema": "./node_modules/wrangler/config-schema.json",
-  "name": "my-edge-app",
-  "main": "worker.js",
-  "compatibility_date": "2026-09-06"
-}
+```js
+app.get('/health', (c) => c.text('ok'));
+app.get('/api/users/:id', { cache: { ttl: 60 } }, (c) => c.json({ id: c.params.id }));
 ```
 
-Or `wrangler.toml`:
+### Static vs. dynamic paths
 
-```toml
-name = "my-edge-app"
-main = "worker.js"
-compatibility_date = "2026-09-14"
+```js
+app.get('/about', handler);                    // static  → Map lookup
+app.get('/users/:id', handler);                // dynamic → trie walk
+app.get('/users/:id/posts/:postId', handler);
 ```
 
-Deploy:
+- Trailing slashes are normalised: `/about/` and `/about` are the same route.
+- Static segments always win over a param at the same position.
+- Params are collected into `ctx.params` (a null-prototype object).
 
-```bash
-wrangler deploy
+```js
+app.get('/users/:id', (c) => {
+  return c.json({ id: c.params.id });   // GET /users/42 → {"id":"42"}
+});
 ```
 
-## Server API
-
-### Context
+Unmatched requests receive `404 Not Found` as `text/plain`.
 
-| Member | Description |
-|---|---|
-| `ctx.req` | Incoming Request |
-| `ctx.env` | Environment bindings |
-| `ctx.executionCtx` | ExecutionContext |
-| `ctx.params` | Prototype-safe route params object |
-| `ctx.status` | Default response status (200) |
-| `ctx.headers` | Response Headers |
-| `ctx.query` | URLSearchParams |
-| `ctx.url` | Parsed URL object |
-| `ctx.getCookie(name)` | Read a cookie |
-| `ctx.setCookie(name, value, options)` | Set a cookie (name validated) |
-| `ctx.deleteCookie(name, options)` | Delete a cookie |
-| `ctx.text(data, status?, headers?)` | Plain-text response |
-| `ctx.json(data, status?, headers?)` | JSON response |
-| `ctx.html(data, status?, headers?)` | HTML response — accepts a raw string, a JSX element, or an array of JSX elements |
-| `ctx.redirect(location, status?)` | Redirect (default 302), preserving headers already set on the context |
+## Context API
 
-Every response carries `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin`, and a restrictive `Permissions-Policy`.
+Every handler receives a `Context` instance.
 
-### Route Options
+### Properties
 
-```ts
-app.get('/cached',  { cache: { ttl: 60 } }, handler);
-app.get('/api',     { cors: true }, handler);
-app.get('/gzip',    { compress: true }, handler);
-app.get('/logged',  { log: true }, handler);
-app.post('/submit', { validate: (ctx) => /* ... */ true }, handler);
+| Property | Type | Description |
+|---|---|---|
+| `c.req` | `Request` | The incoming request |
+| `c.env` | `object` | Worker bindings / environment |
+| `c.executionCtx` | `ExecutionContext` | For `waitUntil()` |
+| `c.params` | `object` | Route parameters |
+| `c.url` | `URL` | Parsed request URL |
+| `c.query` | `URLSearchParams` | `c.url.searchParams` |
+| `c.headers` | `Headers` | Response headers, pre-filled with security defaults |
+| `c.status` | `number` | Default status used by `text`/`json`/`html`/`page` (default `200`) |
+
+### Response helpers
+
+```js
+c.text('hello', 200, { 'X-Foo': 'bar' });     // text/plain; charset=utf-8
+c.json({ ok: true });                          // application/json; charset=utf-8
+await c.html(<div>hi</div>);                   // text/html; charset=utf-8
+await c.page(<html>…</html>);                  // same, but prepends <!DOCTYPE html> if missing
+c.redirect('/login', 302);
+c.redirect('https://example.com', 301);
 ```
 
-**Cache:** `{ ttl, staleWhileRevalidate }` — TTL in seconds, default 3600; only applied to GET responses with status 200. `Set-Cookie` is stripped from cached responses.
+`html()` and `page()` accept:
 
-**CORS:** The default is `origin: '*'`. For production, use a strict allowlist:
+- a string (passed through)
+- a JSX node or array of nodes (rendered with `renderToString`)
+- anything else (`String(data)`)
 
-```ts
-app.defaults.cors.origin = ['https://app.example.com'];
-```
+Both are async because component trees may contain async components.
 
-**Compress:** Negotiates gzip or deflate from `Accept-Encoding` using the native `CompressionStream`.
+### Headers
 
-**Log:** Logs `METHOD URL - STATUS` to the console.
+`c.headers` is a `Headers` instance already containing the base security headers. Mutate it directly before returning a response:
 
-**Validate:** Receives the Context; return `true` to allow or `false` / a falsy value to reject with `400 Validation failed`. Async validators are awaited. Thrown errors are logged and treated as a rejection.
+```js
+app.get('/custom', (c) => {
+  c.headers.set('X-Custom', '1');
+  return c.text('ok');
+});
+```
 
-## JSX Support
+Or pass per-response overrides as the third argument:
 
-`ctx.html()` accepts JSX directly — it detects JSX nodes and arrays and renders them automatically. Raw strings are passed through untouched, so you can still serve pre-rendered HTML.
+```js
+c.json(data, 200, { 'Cache-Control': 'no-store' });
+```
 
-```tsx
-function Card({ title }) {
-  return <div class="card"><h2>{title}</h2></div>;
-}
+### Cookies
+
+```js
+// Read
+const session = c.getCookie('session');   // string | null
+
+// Write
+c.setCookie('session', token, {
+  path: '/',
+  httpOnly: true,
+  secure: true,
+  sameSite: 'Lax',
+  maxAge: 3600,
+  domain: 'example.com',
+  expires: new Date(Date.now() + 3600_000),
+});
 
-// Pass JSX straight to ctx.html — no manual renderToString needed.
-app.get('/card',    (ctx) => ctx.html(<Card title="Hello" />));
-app.get('/heading', (ctx) => ctx.html(<h1>hello</h1>));
-app.get('/list',    (ctx) => ctx.html([<Card title="A" />, <Card title="B" />]));
+// Delete
+c.deleteCookie('session', { path: '/' });
 
-// Raw strings still work as before.
-app.get('/raw',     (ctx) => ctx.html('<p>pre-rendered</p>'));
+return c.text('done');
 ```
 
-Returning a JSX element directly from a handler is also supported — it is treated as an HTML response:
+Cookie names are validated against `__proto__`, `constructor`, `prototype`, and CRLF / `;` / `=` injection.
 
-```tsx
-app.get('/', () => <LandingPage />);
-```
+## JSX & Server-Side Rendering
 
-`renderToString` is still exported for advanced use cases (for example, embedding rendered HTML inside another response body or email template):
+### `renderToString(node, ctx?)`
 
-```tsx
+```js
 import { renderToString } from '@lengkapp/edge';
 
-const html = renderToString(<Card title="Hello" />);
-```
-
-**`renderToString` hardening:**
-
-- Tag names must match `^[A-Za-z][A-Za-z0-9-]*$`.
-- Attribute names must match `^[A-Za-z_:][A-Za-z0-9_:.-]*$`.
-- `on*` attributes never serialize.
-- `href` / `src` / `action` / `formaction` / `xlink:href` values beginning with `javascript:`, `vbscript:`, or `data:text/html` are stripped.
-- Prototype keys (`__proto__`, `constructor`, `prototype`) are rejected.
-- All string values are HTML-escaped.
-- **Style objects.** `style={{ backgroundColor: 'tomato', padding: 12 }}` is emitted as `style="background-color:tomato;padding:12px"`. Numeric values are suffixed with `px` unless the property is unitless (`opacity`, `lineHeight`, `zIndex`, `flex`, …).
-- **Aliases.** `className` → `class`, `htmlFor` → `for`.
-- **Boolean attributes.** `checked`, `disabled`, `required`, `readonly`, `multiple`, etc. emit as bare attributes when `true` and are dropped when `false`.
-- **`dangerouslySetInnerHTML`.** Supported via `dangerouslySetInnerHTML={{ __html: '…' }}` — the value is inserted verbatim and is not escaped. Only use it with trusted content.
-
-## Full Example
-
-A single file that exercises every server feature.
-
-```tsx
-// sample.tsx
-//
-// Demonstrates every feature of @lengkapp/edge:
-//   - static & dynamic routes, all HTTP methods
-//   - params, query, cookies (get/set/delete)
-//   - ctx.text / ctx.json / ctx.html / ctx.redirect
-//   - JSX rendering (elements, Fragments, function components, arrays)
-//   - style objects, boolean attributes, void elements,
-//     className/htmlFor aliases, dangerouslySetInnerHTML
-//   - route options: cors, cache, compress, log, validate
-//   - security.extraHeaders, security.logSecurityEvents
-//   - scheduled handler
-//   - returning JSX directly from a handler
-
-import {
-  Edge,
-  Context,
-  Fragment,
-  renderToString,
-  type JSXNode,
-  type RouteOptions,
-} from '@lengkapp/edge';
+const html = await renderToString(<div>Hello</div>);
+```
 
-/* ------------------------------------------------------------------ *
- *  Small helper components (JSX function components)                 *
- * ------------------------------------------------------------------ */
+Accepts `null`, `undefined`, booleans (rendered as `''`), strings, numbers, promises/thenables, arrays, and JSX nodes. All text and attribute values are HTML-escaped.
 
-function Layout(props: { title: string; children?: any }) {
-  return (
-    <html lang="en">
-      <head>
-        <meta charset="utf-8" />
-        <meta name="viewport" content="width=device-width, initial-scale=1" />
-        <title>{props.title}</title>
-      </head>
-      <body>
-        <header>
-          <nav>
-            <a href="/">Home</a>{' · '}
-            <a href="/about">About</a>{' · '}
-            <a href="/users/42">User 42</a>{' · '}
-            <a href="/dashboard">Dashboard</a>
-          </nav>
-        </header>
-        <main>{props.children}</main>
-        <footer>© {new Date().getFullYear()}</footer>
-      </body>
-    </html>
-  );
-}
+### Components
 
-function UserCard(props: { id: string; name: string; admin?: boolean }) {
+```jsx
+function Card({ title, children }) {
   return (
-    <div class="card" data-id={props.id}>
-      <h2>{props.name}</h2>
-      {props.admin && <span class="badge">admin</span>}
+    <div className="card">
+      <h2>{title}</h2>
+      {children}
     </div>
   );
 }
 
-function TodoList(props: { items: string[] }) {
-  return (
-    <ul>
-      {props.items.map((item, i) => (
-        <li key={i}>{item}</li>
-      ))}
-    </ul>
-  );
+app.get('/', (c) => c.page(
+  <Card title="Welcome">
+    <p>Body text</p>
+  </Card>
+));
+```
+
+### Fragments
+
+```jsx
+<>
+  <li>One</li>
+  <li>Two</li>
+</>
+```
+
+### Async components
+
+```jsx
+async function Weather({ city }) {
+  const r = await fetch(`https://api.example.com/weather?q=${city}`);
+  const data = await r.json();
+  return <span>{data.temp}°C</span>;
 }
 
-/* ------------------------------------------------------------------ *
- *  App                                                               *
- * ------------------------------------------------------------------ */
+app.get('/', (c) => c.page(
+  <div>It is <Weather city="Jakarta" /></div>
+));
+```
 
-const app = new Edge();
+`renderToString` awaits every node recursively.
 
-// ---- Security: global extra headers + keep security logging on ------
-app.security.logSecurityEvents = true;
-app.security.extraHeaders = {
-  'Strict-Transport-Security': 'max-age=31536000; includeSubDomains',
-  'X-Custom-Powered-By': 'edge-server',
-};
+### `useCtx()`
 
-/* ================================================================== *
- *  Basic routes                                                      *
- * ================================================================== */
+Call synchronously at the top of a component (before any `await`) to read the active `Context`:
 
-// Plain text
-app.get('/health', (ctx) => ctx.text('ok'));
+```jsx
+import { useCtx } from '@lengkapp/edge';
 
-// JSON with a custom status
-app.get('/api/time', (ctx) =>
-  ctx.json({ now: new Date().toISOString() }, 200)
-);
+function UserBadge() {
+  const c = useCtx();
+  return <span>Route param: {c.params.id}</span>;
+}
+```
 
-// Returning JSX directly from a handler → automatically becomes
-// a text/html Response.
-app.get('/', () => (
-  <Layout title="Home">
-    <h1>Hello from edge-server</h1>
-    <p>This page was rendered from JSX.</p>
-    <TodoList items={['Write routes', 'Render JSX', 'Ship it']} />
-  </Layout>
-));
+```jsx
+async function UserBadge() {
+  const c = useCtx();                 // ✅ before await
+  const data = await loadUser(c.params.id);
+  // const c2 = useCtx();             // ❌ throws — not available after await
+  return <span>{data.name}</span>;
+}
+```
 
-// Explicit ctx.html with a JSX tree
-app.get('/about', (ctx) =>
-  ctx.html(
-    <Layout title="About">
-      <h1>About</h1>
-      <p>
-        Fragments, components, arrays — all supported.
-      </p>
-      {/* Array of JSX is allowed inside a fragment */}
-      <Fragment>
-        <UserCard id="1" name="Ada" admin />
-        <UserCard id="2" name="Grace" />
-      </Fragment>
-    </Layout>
-  )
-);
+The context stack is pushed immediately before a function component is invoked and popped immediately after its synchronous portion returns. JS cannot preempt running synchronous code, so this window is atomic per isolate — no other request can observe a torn stack.
 
-// ctx.html also accepts a raw HTML string (passes through unchanged)
-app.get('/raw', (ctx) =>
-  ctx.html('<h1>Raw HTML</h1><p>Not escaped.</p>')
-);
+> **Note:** Do not call `useCtx()` from async continuations; capture `c` into a local variable instead.
 
-/* ================================================================== *
- *  Params, query, cookies                                            *
- * ================================================================== */
+### Prop → attribute mapping
 
-// Dynamic route: /users/:id
-app.get('/users/:id', (ctx) => {
-  const { id } = ctx.params;
-  return ctx.html(
-    <Layout title={`User ${id}`}>
-      <UserCard id={id} name={`User #${id}`} />
-    </Layout>
-  );
-});
+| Prop | Rendered as |
+|---|---|
+| `className` / `class` | `class` |
+| `htmlFor` / `for` | `for` |
+| `style={{ fontSize: 12, lineHeight: 1.5 }}` | `style="font-size:12px;line-height:1.5"` |
+| `key`, `ref` | skipped |
+| `children` | skipped (rendered separately) |
+| `on*` (e.g. `onClick`) | skipped — no event handlers in SSR output |
+| boolean attrs (`disabled`, `required`, `checked`, …) | rendered bare when `true`, omitted when `false` |
+| `null` / `undefined` / `false` | omitted |
 
-// Multiple params: /posts/:year/:slug
-app.get('/posts/:year/:slug', (ctx) => {
-  const { year, slug } = ctx.params;
-  return ctx.json({ year, slug });
-});
+Numeric style values automatically get `px` appended unless the property is unitless (`opacity`, `z-index`, `line-height`, `flex`, …).
 
-// Query strings: /search?q=hello&limit=10
-app.get('/search', (ctx) => {
-  const q = ctx.query.get('q') ?? '';
-  const limit = Number(ctx.query.get('limit') ?? '10');
-  return ctx.json({ q, limit });
-});
+### Raw HTML
 
-// Cookies: read, write, delete
-app.get('/login', (ctx) => {
-  ctx.setCookie('session', 'abc123', {
-    path: '/',
-    httpOnly: true,
-    secure: true,
-    sameSite: 'Lax',
-    maxAge: 3600,
-  });
-  return ctx.redirect('/dashboard');
-});
+```jsx
+<div dangerouslySetInnerHTML={{ __html: trustedHtml }} />
+```
 
-app.get('/logout', (ctx) => {
-  ctx.deleteCookie('session', { path: '/' });
-  return ctx.redirect('/');
-});
+This bypasses escaping. **Only use it with content you fully control.**
 
-app.get('/dashboard', (ctx) => {
-  const session = ctx.getCookie('session');
-  if (!session) return ctx.redirect('/login');
-  return ctx.html(
-    <Layout title="Dashboard">
-      <h1>Dashboard</h1>
-      <p>Session: {session}</p>
-    </Layout>
-  );
-});
+### Sanitisation
 
-/* ================================================================== *
- *  All HTTP methods                                                  *
- * ================================================================== */
+- Text and attributes are escaped (`& < > " '`).
+- Tag names must match `[A-Za-z][A-Za-z0-9-]*`.
+- Attribute names are validated; `on*` handlers are stripped.
+- `href`, `src`, `xlink:href`, `action`, `formaction` are rejected if they resolve to `javascript:`, `vbscript:`, or `data:text/html` (whitespace and control characters are stripped before the check).
+- Props named `__proto__`, `constructor`, or `prototype` are ignored.
+
+## Route Options
+
+```js
+app.get('/path', {
+  cors: true,
+  validate: async (c) => true,
+  cache: { ttl: 300, staleWhileRevalidate: 60 },
+  compress: true,
+  log: true,
+}, handler);
+```
 
-app.post('/api/echo', async (ctx) => {
-  const body = await ctx.req.json().catch(() => null);
-  return ctx.json({ received: body }, 201);
+| Option | Type | Description |
+|---|---|---|
+| `cors` | `boolean \| object` | Enable CORS. `true` uses the global default (`origin: '*'`). |
+| `validate` | `async (c) => boolean` | Runs before the handler. Returning falsy yields `400 Validation failed`. |
+| `cache` | `boolean \| { ttl, staleWhileRevalidate }` | Cache successful GET responses in `caches.default`. Defaults: `ttl = 3600`, `swr = 0`. |
+| `compress` | `boolean` | gzip / deflate the response when the client accepts it. |
+| `log` | `boolean` | Log `METHOD URL - STATUS` to the console. |
+
+### `validate` example
+
+```js
+app.post('/api/items', {
+  validate: async (c) => {
+    const auth = c.req.headers.get('Authorization');
+    return auth === `Bearer ${c.env.API_TOKEN}`;
+  },
+}, async (c) => {
+  const body = await c.req.json();
+  return c.json({ created: true, body }, 201);
 });
+```
 
-app.put('/api/items/:id', async (ctx) => {
-  const body = await ctx.req.json().catch(() => null);
-  return ctx.json({ updated: ctx.params.id, body });
+A thrown error inside `validate` is treated as a failure (and logged as a security event).
+
+## Caching
+
+```js
+app.get('/expensive', { cache: { ttl: 600, staleWhileRevalidate: 120 } }, async (c) => {
+  const data = await computeSomethingSlow();
+  return c.json(data);
 });
+```
 
-app.patch('/api/items/:id', (ctx) =>
-  ctx.json({ patched: ctx.params.id })
-);
+- Only `GET` requests are cached.
+- Only `200` responses are stored.
+- The cache key is the full `Request` (URL + method).
+- `Set-Cookie` is stripped from the cached response.
+- A `Cache-Control: max-age=<ttl>[, stale-while-revalidate=<swr>]` header is written.
+- Writes happen in `ctx.executionCtx.waitUntil(...)`, so they never block the response.
+- On a hit, the stored response is returned directly (with CORS and log processing still applied).
 
-app.delete('/api/items/:id', (ctx) =>
-  ctx.json({ deleted: ctx.params.id }, 200)
-);
+## Compression
 
-app.options('/api/items', (ctx) => ctx.text('', 204));
+```js
+app.get('/big', { compress: true }, (c) => c.html(hugeMarkup));
+```
 
-app.head('/api/items', (ctx) => ctx.text('', 200));
+- Skipped when `Content-Type` is not compressible (`text/*`, `application/json`, `application/xml`, `application/javascript`, `application/xhtml`, `application/ld+json`, `application/manifest+json`, `image/svg*`).
+- Skipped when `Content-Length` is known and `< 1024`.
+- Chooses `gzip` first, then `deflate`, based on `Accept-Encoding`.
+- Sets `Content-Encoding` and `Vary: Accept-Encoding`, removes `Content-Length`.
 
-/* ================================================================== *
- *  Route options: cors, cache, compress, log, validate               *
- * ================================================================== */
+## CORS
 
-// CORS with a wildcard origin
-app.get(
-  '/cors-open',
-  { cors: true, log: true },
-  (ctx) => ctx.json({ cors: 'wildcard' })
-);
+Global default (used when `cors: true`):
 
-// CORS with an allow-list + credentials
-app.get(
-  '/cors-restricted',
-  {
-    cors: {
-      origin: ['https://app.example.com', 'https://admin.example.com'],
-      methods: 'GET, POST',
-      headers: 'Content-Type, X-CSRF-Token',
-    },
-  },
-  (ctx) => ctx.json({ cors: 'restricted' })
-);
+```js
+app.defaults.cors = {
+  origin: '*',
+  methods: 'GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD',
+};
+```
 
-// Caching: cache the GET response for 60s, revalidate in background
-app.get(
-  '/cached',
-  {
-    cache: { ttl: 60, staleWhileRevalidate: 30 },
-    log: true,
-  },
-  (ctx) => ctx.json({ generatedAt: Date.now() })
-);
+Per-route:
 
-// Compression (gzip / deflate based on Accept-Encoding)
-app.get(
-  '/big',
-  { compress: true },
-  (ctx) => ctx.html(`<pre>${'x'.repeat(5000)}</pre>`)
-);
+```js
+app.get('/api/public', { cors: true }, handler);
 
-// Request validation — return false to get a 400 automatically
-app.post(
-  '/admin',
-  {
-    validate: (ctx) => {
-      const token = ctx.req.headers.get('X-Admin-Token');
-      return token === 'let-me-in';
-    },
+app.get('/api/private', {
+  cors: {
+    origin: ['https://app.example.com', 'https://admin.example.com'],
+    methods: 'GET, POST',
+    headers: 'Content-Type, Authorization',
   },
-  (ctx) => ctx.json({ ok: true })
-);
-
-// Everything combined
-const everythingOptions: RouteOptions = {
-  cors: { origin: '*' },
-  cache: { ttl: 120, staleWhileRevalidate: 60 },
-  compress: true,
-  log: true,
-  validate: async (ctx) => ctx.req.method === 'GET',
-};
+}, handler);
 
-app.get('/everything', everythingOptions, (ctx) =>
-  ctx.html(
-    <Layout title="Everything">
-      <h1>All options at once</h1>
-    </Layout>
-  )
-);
+app.get('/api/exact', { cors: { origin: 'https://example.com' } }, handler);
+```
 
-/* ================================================================== *
- *  JSX feature gallery                                               *
- * ================================================================== */
-
-app.get('/jsx/gallery', (ctx) =>
-  ctx.html(
-    <Layout title="JSX Gallery">
-      {/* Style objects → kebab-cased, numbers get px added */}
-      <div
-        style={{
-          backgroundColor: 'tomato',
-          padding: 12,
-          opacity: 0.9,
-          lineHeight: 1.4, // unitless, stays as-is
-        }}
-      >
-        Styled box
-      </div>
+| `origin` value | Result |
+|---|---|
+| `'*'` | `Access-Control-Allow-Origin: *` |
+| `string` | Echoes the request origin only if it matches exactly, plus `Vary: Origin` and `Allow-Credentials: true` |
+| `string[]` | Echoes the request origin only if it is in the list, plus `Vary: Origin` and `Allow-Credentials: true` |
 
-      {/* className and htmlFor are aliased to class / for */}
-      <label className="lbl" htmlFor="name">
-        Name
-      </label>
-      <input id="name" type="text" required disabled={false} />
+`Access-Control-Max-Age: 86400` is always set. Remember to register an `OPTIONS` route if you need preflight handling.
 
-      {/* Boolean attributes: true emits the bare attribute */}
-      <input type="checkbox" checked readOnly />
-      <button disabled>Nope</button>
+## Security
 
-      {/* Void elements self-close */}
-      <img src="/logo.png" alt="logo" />
-      <br />
-      <hr />
+### Base headers (always applied)
 
-      {/* dangerouslySetInnerHTML */}
-      <div dangerouslySetInnerHTML={{ __html: '<b>trusted</b>' }} />
+```text
+X-Content-Type-Options: nosniff
+X-Frame-Options: DENY
+Referrer-Policy: strict-origin-when-cross-origin
+Permissions-Policy: geolocation=(), microphone=(), camera=()
+```
 
-      {/* Fragments */}
-      <>
-        <p>Fragment child A</p>
-        <p>Fragment child B</p>
-      </>
+### Extra headers
 
-      {/* Arrays of JSX */}
-      {[<span key="a">A</span>, <span key="b">B</span>, <span key="c">C</span>]}
+```js
+app.security.extraHeaders = {
+  'Strict-Transport-Security': 'max-age=31536000; includeSubDomains',
+  'Content-Security-Policy': "default-src 'self'",
+};
+```
 
-      {/* Escaping: user-supplied strings are escaped */}
-      <p>{'<script>alert(1)</script>'}</p>
+### Security event logging
 
-      {/* Dangerous URLs are dropped */}
-      <a href="javascript:alert(1)">nope</a>
-      <a href="https://example.com">ok</a>
+Enabled by default. Events are sampled to at most one per `(event, ip, path)` per 60 seconds.
 
-      {/* Numbers are stringified and escaped */}
-      <p>Count: {42}</p>
+```js
+app.security.logSecurityEvents = false;   // disable
+```
 
-      {/* null / undefined / booleans render nothing */}
-      <p>{null}{undefined}{false}{true}</p>
-    </Layout>
-  )
-);
+Logged events: `validation_error`, `handler_error`. Each entry is a JSON line containing timestamp, event, detail, IP (`CF-Connecting-IP`), method, path, and user agent.
 
-/* ================================================================== *
- *  renderToString() standalone                                       *
- * ================================================================== */
+## Scheduled Handler
 
-app.get('/jsx/string', (ctx) => {
-  const html = renderToString(
-    <section>
-      <h1>Rendered manually</h1>
-      <p>Via renderToString()</p>
-    </section>
-  );
-  return ctx.html(html);
-});
+The `Edge` class stores a cron handler via `app.scheduled(fn)`. Because the default export must expose `scheduled` as a function, wrap the instance:
 
-/* ================================================================== *
- *  Scheduled handler                                                 *
- * ================================================================== */
+```js
+const app = new Edge();
 
 app.scheduled(async (event, env, ctx) => {
-  console.log('cron fired at', new Date(event.scheduledTime).toISOString());
-  // e.g. warm a cache, prune KV entries, etc.
+  console.log('cron fired at', event.scheduledTime);
 });
 
-/* ================================================================== *
- *  Cloudflare Workers entry points                                   *
- * ================================================================== */
-
 export default {
-  fetch: (req: Request, env: any, ctx: ExecutionContext) =>
-    app.fetch(req, env, ctx),
-  scheduled: (event: ScheduledEvent, env: any, ctx: ExecutionContext) =>
-    app.scheduledHandler?.(event, env, ctx),
+  fetch: (request, env, executionCtx) => app.fetch(request, env, executionCtx),
+  scheduled: (event, env, executionCtx) => app.scheduledHandler(event, env, executionCtx),
 };
 ```
 
-### Feature → route cheat-sheet
+## Client-Side Partial Updates
 
-| Feature | Route / location |
-|---|---|
-| `ctx.text` | `GET /health` |
-| `ctx.json` | `GET /api/time`, `POST /api/echo`, … |
-| `ctx.html` with JSX | `GET /` |
-| `ctx.html` with string | `GET /raw` |
-| Returning JSX directly | `GET /` |
-| `ctx.redirect` | `GET /login`, `GET /logout`, `GET /dashboard` |
-| `ctx.params` | `GET /users/:id`, `GET /posts/:year/:slug` |
-| `ctx.query` | `GET /search` |
-| `ctx.getCookie` / `setCookie` / `deleteCookie` | `/login`, `/logout`, `/dashboard` |
-| All HTTP verbs | `/api/echo` (POST), `/api/items/:id` (PUT/PATCH/DELETE), `/api/items` (OPTIONS/HEAD) |
-| `cors` | `/cors-open`, `/cors-restricted`, `/everything` |
-| `cache` | `/cached`, `/everything` |
-| `compress` | `/big`, `/everything` |
-| `log` | `/cors-open`, `/cached`, `/everything` |
-| `validate` | `POST /admin`, `/everything` |
-| `security.extraHeaders` | set once near the top |
-| `security.logSecurityEvents` | set once near the top |
-| Fragments | `GET /about`, `GET /jsx/gallery` |
-| Function components | `Layout`, `UserCard`, `TodoList` |
-| Style objects | `GET /jsx/gallery` |
-| Boolean attrs / void elements | `GET /jsx/gallery` |
-| `dangerouslySetInnerHTML` | `GET /jsx/gallery` |
-| `renderToString()` standalone | `GET /jsx/string` |
-| `scheduled()` | bottom of file |
-
-## Client (Declarative Partial Updates)
+The framework ships a tiny IIFE (`edge.client.js`) that turns HTML attributes into fetch-and-swap behaviour. No build step, no framework, no hydration.
+
+### Including it
+
+Serve it as a static asset:
 
 ```html
-<script src="https://cdn.example.com/edge-client.min.js"></script>
+<script src="/edge.client.js" defer></script>
+```
+
+…or inline it at the end of `<body>`:
+
+```html
+<script>/* contents of edge.client.js */</script>
 ```
 
 ### Attributes
 
-| Attribute | Description |
-|---|---|
-| `_get` / `_post` | Request URL and HTTP method. Only GET and POST are supported. |
-| `_go` | Navigate the current tab to the URL (`location.assign`). |
-| `_open` | Open the URL in a new tab (`noopener,noreferrer`). |
-| `_id` | Opt in to the device fingerprint for this element. See [Device Fingerprint](#device-fingerprint). |
-| `_in` | Replace the target's children with the response. |
-| `_out` | Replace the target element itself. |
-| `_before` | Insert the response before the target. |
-| `_after` | Insert the response after the target. |
-| `_toast` | Insert the response non 2xx to toast element if any. |
-| `_trigger` | `click` (default), `load`, `visible`, or any DOM event name. |
-| `_form` | CSS selector or element ID of a form to serialize as the body. |
-| `_json` | Comma-separated field names to send as a JSON body. |
-| `_loader` | `spinner` (default), `skeleton`, or `none` / `off` / `false` to disable. |
-| `_timeout` | Request timeout in milliseconds (default 20000). |
-
-**Targets.** Exactly one placement attribute (`_in`, `_out`, `_before`, `_after`) should be present. Its value is a CSS selector, the literal string `this`, or empty — the last two both resolve to the element that carries the attribute.
-
-**Field scope.** `_json` reads values from the closest enclosing `<form>`, or from the document if there is none. It also accepts fields by `id` first, then by `name` (grouped radio/checkbox inputs are handled).
+| Attribute | Value | Description |
+|---|---|---|
+| `_get` | URL | Perform a `GET` request to this URL. |
+| `_post` | URL | Perform a `POST` request to this URL. |
+| `_trigger` | `load` \| `visible` \| `click` \| `submit` \| `change` \| `input` \| `keyup` \| `dblclick` | When to fire. Default: `submit` on a `<form>`, `click` on anything else. |
+| `_in` | CSS selector | Element whose `innerHTML` receives the response. Default: the element itself. |
+| `_form` | CSS selector | A `<form>` whose `FormData` becomes the URL-encoded POST body. |
+| `_json` | CSS selector | A `<form>` or input whose values become a JSON POST body. |
+| `_error` | CSS selector | Element that receives the response body when the status is not 2xx. |
+
+Exactly one of `_get` / `_post` is required on an element for it to be "active".
+
+### Triggers
+
+- **`click`** (default for non-forms) — fires on click.
+- **`submit`** (default for `<form>`) — fires on submit; `preventDefault()` is called automatically.
+- **`load`** — fires as soon as the element is scanned (page load or injected into the DOM).
+- **`visible`** — fires when the element scrolls into the viewport (`IntersectionObserver`), then unobserves.
+- **`change` / `input` / `keyup` / `dblclick`** — must be opted into explicitly with `_trigger="…"`.
+
+Events are attached in the capture phase on `document`, so they survive DOM replacement and work with dynamically added content.
 
 ### Examples
 
+**Refresh a fragment**
+
 ```html
-<!-- replace the children of #posts with the response -->
-<button _get="/more-posts" _in="#posts">Load More</button>
+<button _get="/api/time" _in="#clock">Refresh</button>
+<div id="clock">—</div>
+```
+
+```js
+app.get('/api/time', (c) => c.html(<span>{new Date().toISOString()}</span>));
+```
 
-<!-- replace this element with the response -->
-<div _get="/user-profile" _out="this"></div>
+**Submit a form and replace a list**
 
-<!-- POST JSON built from form fields, replace the children of #status -->
-<button _post="/login" _json="username,password" _in="#status">Login</button>
+```html
+<form id="add-form" _post="/todos" _form="#add-form" _in="#todo-list" _error="#form-error">
+  <input name="text" required />
+  <button>Add</button>
+</form>
+<p id="form-error"></p>
+
+<ul id="todo-list">
+  <li>Existing item</li>
+</ul>
+```
 
-<!-- POST a whole form -->
-<form id="signup">…</form>
-<button _post="/signup" _form="#signup" _in="#result">Sign up</button>
+```js
+app.post('/todos', async (c) => {
+  const fd = await c.req.formData();
+  const text = String(fd.get('text') || '').trim();
+  if (!text) return c.text('<em>Text is required</em>', 422);
+  return c.html(<li>{text}</li>);
+});
+```
 
-<!-- fetch lazily when the element scrolls into view -->
-<div _get="/lazy" _in="this" _trigger="visible"></div>
+**POST JSON from a single input**
 
-<!-- skeleton loader with a 5-second timeout -->
-<div _get="/feed" _in="this" _loader="skeleton" _timeout="5000"></div>
+```html
+<input id="q" name="q" _post="/api/search" _json="#q" _trigger="keyup" _in="#results" />
+<div id="results"></div>
+```
 
-<!-- _toast if non 2xx -->
-<div _get="/feed-error" _in="this" _toast="#toast"></div>
+**Load on scroll into view**
 
-<!-- same-tab navigation with a device id -->
-<a href="/dashboard" _go _id>Dashboard</a>
+```html
+<div _get="/api/feed/page/2" _trigger="visible" _in="this">
+  Loading…
+</div>
+```
 
-<!-- new-tab navigation -->
-<a href="/docs" _open>Docs</a>
+**Fire on page load**
 
-<!-- POST with X-DeviceId header -->
-<button _post="/like" _id _in="#card-3">Like</button>
+```html
+<div _get="/api/notifications" _trigger="load" _in="#bell"></div>
 ```
 
-### Triggers
+### Request headers
 
-- `click` (default) — handled by a single delegated document listener.
-- `load` / `visible` — the element is observed with `IntersectionObserver` (300px root margin) and the request fires the first time it enters the viewport.
-- Any other value — treated as a DOM event name. The listener is attached the first time the element becomes visible, then fires normally.
+Every request automatically includes:
 
-### How Content Is Inserted
+| Header | Source |
+|---|---|
+| `x-csrf-token` | `<meta name="_csrf" content="…">` |
+| `x-auth-token` | `<meta name="_auth" content="…">` |
 
-- The request is sent with `credentials: 'same-origin'` and `X-Requested-With: XMLHttpRequest`.
-- When the triggering element carries `_id`, the request includes an `X-DeviceId` header (see [Device Fingerprint](#device-fingerprint)).
-- For `_post`, the body is JSON (`_json`), a `FormData` object (`_form`), or empty.
-- The response text is parsed into a `<template>`.
-- Any `<script>` elements are lifted out, then re-created and appended to `<head>` so the browser executes them. External scripts are de-duplicated by absolute URL.
-- Newly inserted `[_get]` / `[_post]` elements are scanned and bound.
-- Placement depends on the target mode:
-  - `_in` — the target's existing children are removed, then the fragment is appended.
-  - `_out` — the target itself is replaced.
-  - `_before` / `_after` — the fragment is inserted adjacent to the target.
+```html
+<meta name="_csrf" content="<%= csrfToken %>" />
+<meta name="_auth" content="<%= authToken %>" />
+```
 
-> **Note:** No content-type check, HTML sanitization, or CSRF token is applied by the client — it trusts the server's response and inserts it as-is. Treat the partial-HTML endpoints you point `_get` / `_post` at as part of your trusted surface.
+Missing metas simply produce empty strings.
 
-### Loader & Error States
+### Body encoding
 
-- The loader is deferred by 100ms: if the response lands before then, no loader is shown at all.
-- Once shown, the loader stays for at least 240ms before the content swaps in, so it never flashes.
-- `_loader="spinner"` (default), `_loader="skeleton"` for a shimmering skeleton, or `_loader="none"` to disable.
-- A new request on the same element aborts the previous one via `AbortController`.
-- On failure — non-2xx, network error, or `_timeout` — the loader is replaced in place by an error box with a retry button that re-issues the request.
-- Loaders and error states use `role="status"` / `role="alert"` with `aria-busy` set on the target while in flight.
+- `_form` → `application/x-www-form-urlencoded` (built from `FormData`)
+- `_json` with a `<form>` → JSON object of all fields
+- `_json` with a single input → `{ "<name|id>": value }`
+- Neither → no body
 
-### View Transitions
+### Response handling
 
-When `document.startViewTransition` is available, loader → content and loader → error swaps are wrapped in a view transition. The injected stylesheet disables the animation under `prefers-reduced-motion: reduce`.
+- `response.ok` → swap `_in` target with the response text
+- `!response.ok` and `_error` present → swap `_error` target with the response text
+- `!response.ok` and no `_error` → the response is silently discarded
 
-## Device Fingerprint
+After a swap, any `<script>` and `<style>` elements in the inserted HTML are cloned and re-inserted so they execute/apply, then the new subtree is scanned for active elements. A `MutationObserver` on `document.documentElement` does the same for any DOM added by other means.
 
-Add `_id` to any `_get` / `_post` / `_go` / `_open` element to attach a stable device identifier.
+### Auto IDs
 
-**Signals.** `navigator.userAgent`, `navigator.language`, screen dimensions, color depth, timezone offset, `hardwareConcurrency`, `deviceMemory`, plus Canvas, WebGL renderer, an offline Audio context, and a 10-font width probe. Combined and SHA-256 hashed.
+When an element uses the default `_in` (itself) and has no `id`, the runtime assigns one (`_g1`, `_g2`, …) so the swap target can be resolved.
 
-**Cost.** Computed lazily once per page and cached for the document lifetime; warmed at boot if any `[_id]` element is in the DOM. Adds ~0.9 KB gzipped to the client bundle and a few milliseconds on the first call.
+## Complete Example
 
-**Delivery.**
+**`index.js`**
 
-- `_get` / `_post` → sent as the `X-DeviceId` request header (no body, no URL change).
-- `_go` / `_open` → appended to the URL as `?_did=<hash>` (headers cannot be set on `location.assign` / `window.open`).
+```jsx
+/** @jsx jsx */
+/** @jsxFrag Fragment */
+import { Edge, jsx, Fragment, useCtx } from '@lengkapp/edge';
 
-**Fallback.** If `crypto.subtle` is unavailable (non-secure context), a djb2 hash of the same signals is used, with lower collision resistance.
+const app = new Edge();
 
-Without `_id`, no fingerprint is computed, no header is set, and no URL parameter is added.
+/* ------------------------------------------------------------------ *
+ *  Data                                                              *
+ * ------------------------------------------------------------------ */
+let seq = 0;
+const todos = new Map();
 
-## CSRF Protection
+function addTodo(text) {
+  const id = String(++seq);
+  todos.set(id, { id, text, done: false });
+  return todos.get(id);
+}
 
-The client does not attach a CSRF token automatically. Include the token as a form field or as part of the JSON payload built by `_json`, then validate it on the server with a `validate` option:
+addTodo('Read the docs');
+addTodo('Deploy to production');
 
-```ts
-app.post('/submit', {
-  validate: async (ctx) => {
-    const body = await ctx.req.json().catch(() => ({}));
-    return body.csrf_token && body.csrf_token === ctx.getCookie('csrf_token');
-  }
-}, handler);
-```
+/* ------------------------------------------------------------------ *
+ *  Components                                                        *
+ * ------------------------------------------------------------------ */
+function Layout({ title, children }) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charset="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <meta name="_csrf" content="demo-csrf-token" />
+        <title>{title}</title>
+        <style>{`
+          body { font-family: system-ui, sans-serif; max-width: 40rem; margin: 3rem auto; }
+          li { padding: .25rem 0; }
+        `}</style>
+      </head>
+      <body>
+        <nav><a href="/">Home</a> · <a href="/todos">Todos</a></nav>
+        <main>{children}</main>
+        <script src="/edge.client.js" defer></script>
+      </body>
+    </html>
+  );
+}
 
-For `_form`-based submissions, read the field from the parsed form data using the same pattern.
+function TodoItem({ todo }) {
+  return <li id={'todo-' + todo.id}>{todo.text}</li>;
+}
 
-## Security Controls
+function TodoList() {
+  return <>{[...todos.values()].map((t) => <TodoItem todo={t} />)}</>;
+}
 
-```ts
-const app = new Edge();
+/* ------------------------------------------------------------------ *
+ *  Routes                                                            *
+ * ------------------------------------------------------------------ */
+app.get('/', (c) =>
+  c.page(
+    <Layout title="Home">
+      <h1>Hello{nameSuffix(c)}</h1>
+      <p>This page was rendered on the edge in {(0.01).toFixed(2)} ms.</p>
 
-app.defaults.cors.origin = ['https://app.example.com'];
+      <button _get="/api/time" _in="#clock">Refresh time</button>
+      <p id="clock">—</p>
 
-app.security.logSecurityEvents = true; // structured JSON events (default on)
-app.security.extraHeaders = {
-  'Strict-Transport-Security': 'max-age=63072000; includeSubDomains; preload',
-  'Cross-Origin-Opener-Policy': 'same-origin',
-  'Cross-Origin-Resource-Policy': 'same-origin',
-};
-```
+      <div _get="/api/greeting" _trigger="visible" _in="this">
+        Scroll-triggered content loading…
+      </div>
+    </Layout>
+  )
+);
 
-## OWASP 2025 Coverage
+function nameSuffix(c) {
+  const n = c.query.get('name');
+  return n ? `, ${n}` : '';
+}
 
-| Category | Mitigation |
-|---|---|
-| A01 Broken Access Control | Strict CORS allowlist, strict target resolution, no implicit trust |
-| A02 Security Misconfiguration | Safe default headers, strict CORS allowlist, `Vary: Origin` |
-| A03 Supply Chain | Zero deps |
-| A04 Crypto Failures | Standard Web Crypto only; no home-grown crypto |
-| A05 Injection / XSS | Prototype-safe objects, JSX attribute sanitization |
-| A06 Insecure Design | Fail-closed validation, explicit response modes |
-| A07 Auth Failures | Validation errors are surfaced, not swallowed |
-| A08 Data Integrity | Prototype-safe JSON, `Set-Cookie` stripped from cache |
-| A09 Logging | Structured JSON security events with 60s dedupe |
-| A10 Exceptional Conditions | Fail-closed middleware, no internal leakage |
-
-## Scheduled Tasks
-
-```ts
-app.scheduled(async (event, env, ctx) => {
-  console.log('Cron executed:', event.cron);
-});
+app.get('/api/time', (c) => c.html(<strong>{new Date().toISOString()}</strong>));
 
-export default {
-  fetch: (req, env, ctx) => app.fetch(req, env, ctx),
-  scheduled: (event, env, ctx) => app.scheduledHandler?.(event, env, ctx),
-};
-```
+app.get('/api/greeting', (c) =>
+  c.html(<p>👋 Loaded lazily when it became visible.</p>)
+);
 
-## Configuration
+app.get('/todos', (c) =>
+  c.page(
+    <Layout title="Todos">
+      <h1>Todos</h1>
 
-The `Edge` constructor takes no arguments. Behaviour is configured through public properties and route options:
+      <form id="add" _post="/todos" _form="#add" _in="#list" _error="#err">
+        <input name="text" placeholder="What needs doing?" required />
+        <button>Add</button>
+      </form>
+      <p id="err"></p>
 
-| Property | Type | Default |
-|---|---|---|
-| `app.defaults.cors` | `{ origin, methods }` | `origin: '*'`, `methods: 'GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD'` |
-| `app.security.logSecurityEvents` | `boolean` | `true` |
-| `app.security.extraHeaders` | `Record<string, string> \| null` | `null` |
-| `app.security.trustedProxies` | `string[] \| null` | `null` |
+      <ul id="list">
+        <TodoList />
+      </ul>
+    </Layout>
+  )
+);
 
-```ts
-app.defaults.cors = { origin: ['https://app.example.com'], methods: 'GET, POST' };
-app.security.extraHeaders = {
-  'Strict-Transport-Security': 'max-age=63072000; includeSubDomains',
-};
-```
+app.post('/todos', async (c) => {
+  const fd = await c.req.formData();
+  const text = String(fd.get('text') || '').trim();
+  if (!text) return c.text('<em>Please enter some text.</em>', 422);
+  addTodo(text);
+  return c.html(<TodoList />);
+});
+
+/* Dynamic params + JSON + caching */
+app.get(
+  '/api/todos/:id',
+  { cache: { ttl: 30, staleWhileRevalidate: 300 }, cors: true, log: true },
+  (c) => {
+    const todo = todos.get(c.params.id);
+    if (!todo) return c.json({ error: 'Not found' }, 404);
+    return c.json(todo);
+  }
+);
+
+/* Cookie round-trip */
+app.get('/theme/:name', (c) => {
+  c.setCookie('theme', c.params.name, {
+    path: '/',
+    httpOnly: true,
+    secure: true,
+    sameSite: 'Lax',
+    maxAge: 60 * 60 * 24 * 365,
+  });
+  return c.redirect('/');
+});
 
-## Performance
+app.get('/api/theme', (c) => c.json({ theme: c.getCookie('theme') || 'light' }));
 
-Zero runtime dependencies. On a local `wrangler dev` benchmark with `autocannon` (10 connections, 10s per route), throughput sits in the same tier as `hono` / `hono/tiny` / a native worker:
+/* Compressed, validated, cached API */
+app.get(
+  '/api/large',
+  {
+    compress: true,
+    cache: { ttl: 120 },
+    validate: async (c) => c.req.headers.get('X-Api-Key') === c.env.API_KEY,
+  },
+  (c) => c.json({ items: Array.from({ length: 500 }, (_, i) => ({ i })) })
+);
 
-| Framework | /text req/s | /json req/s |
-|---|---|---|
-| @lengkapp/edge | 503 | 500 |
-| Hono | 506 | 495 |
-| Hono (tiny) | 505 | 498 |
-| Native Workers | 498 | 500 |
+/* ------------------------------------------------------------------ *
+ *  Export                                                            *
+ * ------------------------------------------------------------------ */
+export default {
+  fetch: (request, env, executionCtx) => app.fetch(request, env, executionCtx),
+  scheduled: (event, env, executionCtx) =>
+    app.scheduledHandler?.(event, env, executionCtx),
+};
+```
 
-The security hardening adds only cheap operations to the request path: prototype-safe objects, two regex checks per JSX attribute, and a throttled logger. No new async boundaries, no added dependencies, no hashing on the hot path.
+## License
 
-The JSX renderer itself is tuned for throughput: single-pass escaping (`charCodeAt` scan with a fast no-op path), direct string concatenation instead of intermediate arrays, cached camelCase → kebab-case conversions for style objects, and a Set-based URL-attribute lookup on the hot path. `ctx.html(<Card />)` skips the redundant string-identity check that a manual `renderToString(<Card />)` call would still hit.
+```text
+LengkApp Edge License
 
-The client is equally lean: it injects a single stylesheet, binds each element exactly once via a `WeakSet`, and uses one delegated click listener for all `_trigger="click"` elements. An in-flight request on an element is aborted when a new one starts, and the loader is deferred by 100ms / held for at least 240ms so fast endpoints never flash UI.
+Copyright (c) LengkApp — Yasir Haris
+Contact: yh@lengk.app / yasir.haris@gmail.com
 
-The device fingerprint is opt-in per element (`_id`) and cached for the document lifetime; it is warmed during boot when any `[_id]` element exists, so the first click is not delayed by the ~5–15 ms of Canvas / Audio work.
+Permission is granted to use, copy, and distribute this software free of charge,
+including for commercial purposes, provided that:
 
-## Security Posture Summary
+1. The Software may not be modified, adapted, or altered in any way without
+   prior written permission from the copyright holder.
 
-| Layer | Mechanism |
-|---|---|
-| HTML insertion (client) | Response text parsed into a `<template>`; placement driven by `_in` / `_out` / `_before` / `_after` |
-| Script execution (client) | Extracted `<script>` elements re-created and appended to `<head>`; external scripts de-duplicated by absolute URL |
-| Request hygiene (client) | `credentials: 'same-origin'`, `X-Requested-With: XMLHttpRequest`, optional `X-DeviceId` (only when `_id` is present), abortable via `AbortController`, `_timeout` (default 20s) |
-| Cookies | `credentials: 'same-origin'`; names validated on the server |
-| Server response headers | `nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy`, `Permissions-Policy` |
-| Server middleware | Fail-closed validation; structured security logs; strict CORS allowlist |
-| Prototype pollution | `Object.create(null)` + forbidden-key filtering in params, cookies, JSON, JSX (server) |
-| Build | Reserved exports/properties, `keep_quoted: "strict"`, per-bundle post-minification self-test |
+2. Redistribution, in whole or in part, must retain the unmodified LICENSE file
+   and the copyright notice above.
 
-## License
+3. No right is granted to use the LengkApp name, brand, or trademarks without
+   separate written permission.
 
-MIT — see [LICENSE](./LICENSE) for the full text.  
-© LengkApp — Yasir Haris
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. IN NO EVENT SHALL THE AUTHOR OR COPYRIGHT HOLDER BE LIABLE FOR ANY
+CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH
+THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+```