@lengkapp/edge 0.0.40 → 0.0.41

package/README.md

@@ -2,9 +2,11 @@
 
 A minimal, high-performance framework for Cloudflare Workers with built-in server-side rendering, routing, caching, and a declarative client-side partial-update library.
 
-Inspired by [Hono](https://hono.dev), `@lengkapp/edge` aims for the same class of performance while shipping with **zero runtime dependencies**.
+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 Controls](#security-controls).
+**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).
+
+---
 
 ## Table of Contents
 
@@ -15,21 +17,23 @@ Inspired by [Hono](https://hono.dev), `@lengkapp/edge` aims for the same class o
 - [JSX Support](#jsx-support)
 - [Full Example](#full-example)
 - [Client (Declarative Partial Updates)](#client-declarative-partial-updates)
-- [Device Identity](#device-identity)
+- [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)
-- [Build](#build)
 - [Security Posture Summary](#security-posture-summary)
 - [License](#license)
 
+---
+
 ## Features
 
 ### Server
 
-- **Trie-based routing** – static and dynamic routes (`/users/:id`)
+- **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
@@ -39,12 +43,13 @@ Inspired by [Hono](https://hono.dev), `@lengkapp/edge` aims for the same class o
 ### Client
 
 - **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)
-- **Opt-in device identity** via `_id` — attaches an `X-DeviceId` header to `_get` / `_post` requests, sourced from an optional `window.deviceId()` hook
-- **Click, load, and visibility triggers** – `click` (default), `load`, `visible`
-- **JSON and form bodies** – `_json="#a,#b"` or `_form="#signup"`
-- **Built-in loading and error states** – spinner loader, abortable requests, one-click retry
-- **Error toast host** via `_toast` — on a non-2xx response, inject the response body into a chosen element
+- **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"`
+- **Scalable Translation** – `_translate={indentifier}`, based on `html lang={lang-id}` it will look for `/t/{lang-id}/{identifier}.jon`
+- **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**
 
 ### Security
@@ -55,6 +60,8 @@ Inspired by [Hono](https://hono.dev), `@lengkapp/edge` aims for the same class o
 - **Fail-closed middleware** – validation and handler errors deny by default
 - **Strict CORS allowlist** – per-origin reflection with `Vary: Origin`
 
+---
+
 ## Installation
 
 ```bash
@@ -63,7 +70,7 @@ npm install @lengkapp/edge
 
 ## Quick Start
 
-**`worker.js`**
+`worker.js`:
 
 ```ts
 import { Edge } from '@lengkapp/edge';
@@ -76,14 +83,16 @@ app.get('/users/:id', (ctx) => ctx.json({ id: ctx.params.id }));
 export default app;
 ```
 
-Or, if you use JSX, **`worker.tsx`**:
+Or, if you will use JSX, `worker.tsx`:
 
 ```tsx
 import { Edge, jsx, Fragment } from '@lengkapp/edge';
 
 const app = new Edge();
 
-const Card = () => <div>card</div>;
+const Card = () => (
+  <div>card</div>
+);
 
 const LandingPage = () => (
   <>
@@ -97,7 +106,7 @@ app.get('/', () => <LandingPage />);
 export default app;
 ```
 
-**`tsconfig.json`** (TypeScript):
+If you use TypeScript, `tsconfig.json`:
 
 ```json
 {
@@ -117,18 +126,18 @@ export default app;
 }
 ```
 
-**`wrangler.jsonc`**
+`wrangler.jsonc`:
 
 ```jsonc
 {
   "$schema": "./node_modules/wrangler/config-schema.json",
   "name": "my-edge-app",
   "main": "worker.js",
-  "compatibility_date": "2026-09-14"
+  "compatibility_date": "2026-09-06"
 }
 ```
 
-Or **`wrangler.toml`**:
+Or `wrangler.toml`:
 
 ```toml
 name = "my-edge-app"
@@ -147,49 +156,25 @@ wrangler deploy
 ### Context
 
 | Member | Description |
-| --- | --- |
-| `ctx.req` | Incoming `Request` |
+|---|---|
+| `ctx.req` | Incoming Request |
 | `ctx.env` | Environment bindings |
-| `ctx.executionCtx` | `ExecutionContext` |
+| `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.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. Async (awaits JSX rendering). |
-| `ctx.page(data, status?, headers?)` | Same as `ctx.html`, but prepends `<!DOCTYPE html>` if the body does not already start with one. Async. |
-| `ctx.redirect(location, status?)` | Redirect (default `302`), preserving headers already set on the context |
+| `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 |
 
 Every response carries `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin`, and a restrictive `Permissions-Policy`.
 
-### Ambient Context (`useCtx`)
-
-`useCtx()` returns the `Context` of the request whose render is currently executing. It is backed by a synchronous stack — no `AsyncLocalStorage`, no compatibility flags.
-
-```tsx
-import { useCtx } from '@lengkapp/edge';
-
-async function User() {
-  // MUST be called synchronously, before any await.
-  const ctx = useCtx();
-  const res = await fetch(`https://api.example.com/users/${ctx.params.id}`);
-  const data = await res.json();
-  // After the await, use the captured local `ctx` — do not call useCtx() again.
-  return <div>{data.name}</div>;
-}
-```
-
-**Contract:**
-
-- Call `useCtx()` at the top of a component, before any `await`.
-- After an `await`, use the captured local reference.
-- Throws if called outside an active render (module top-level, `scheduled` handler, `waitUntil` callback).
-
 ### Route Options
 
 ```ts
@@ -200,20 +185,20 @@ app.get('/logged',  { log: true }, handler);
 app.post('/submit', { validate: (ctx) => /* ... */ true }, handler);
 ```
 
-| Option | Behavior |
-| --- | --- |
-| `cache` | `{ ttl, staleWhileRevalidate }` — TTL in seconds, default `3600`. Only applied to `GET` responses with status `200`. `Set-Cookie` is stripped from cached responses. |
-| `cors` | Default is `origin: '*'`. For production, use a strict allowlist (see below). |
-| `compress` | Negotiates `gzip` or `deflate` from `Accept-Encoding` using the native `CompressionStream`. |
-| `log` | Logs `METHOD URL - STATUS` to the console. |
-| `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. |
+**Cache:** `{ ttl, staleWhileRevalidate }` — TTL in seconds, default 3600; only applied to GET responses with status 200. `Set-Cookie` is stripped from cached responses.
 
-Strict CORS allowlist:
+**CORS:** The default is `origin: '*'`. For production, use a strict allowlist:
 
 ```ts
 app.defaults.cors.origin = ['https://app.example.com'];
 ```
 
+**Compress:** Negotiates gzip or deflate from `Accept-Encoding` using the native `CompressionStream`.
+
+**Log:** Logs `METHOD URL - STATUS` to the console.
+
+**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.
+
 ## JSX Support
 
 `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.
@@ -243,10 +228,10 @@ app.get('/', () => <LandingPage />);
 ```tsx
 import { renderToString } from '@lengkapp/edge';
 
-const html = await renderToString(<Card title="Hello" />);
+const html = renderToString(<Card title="Hello" />);
 ```
 
-### `renderToString` hardening
+**`renderToString` hardening:**
 
 - Tag names must match `^[A-Za-z][A-Za-z0-9-]*$`.
 - Attribute names must match `^[A-Za-z_:][A-Za-z0-9_:.-]*$`.
@@ -254,13 +239,10 @@ const html = await renderToString(<Card title="Hello" />);
 - `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.
-
-### Rendering details
-
 - **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.
+- **`dangerouslySetInnerHTML`.** Supported via `dangerouslySetInnerHTML={{ __html: '…' }}` — the value is inserted verbatim and is not escaped. Only use it with trusted content.
 
 ## Full Example
 
@@ -272,7 +254,7 @@ A single file that exercises every server feature.
 // 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.page / ctx.redirect
+//   - 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
@@ -280,14 +262,12 @@ A single file that exercises every server feature.
 //   - security.extraHeaders, security.logSecurityEvents
 //   - scheduled handler
 //   - returning JSX directly from a handler
-//   - useCtx() inside an async component
 
 import {
   Edge,
   Context,
   Fragment,
   renderToString,
-  useCtx,
   type JSXNode,
   type RouteOptions,
 } from '@lengkapp/edge';
@@ -302,7 +282,6 @@ function Layout(props: { title: string; children?: any }) {
       <head>
         <meta charset="utf-8" />
         <meta name="viewport" content="width=device-width, initial-scale=1" />
-        <meta name="_csrf" content="token-here" />
         <title>{props.title}</title>
       </head>
       <body>
@@ -340,14 +319,6 @@ function TodoList(props: { items: string[] }) {
   );
 }
 
-// Async component using useCtx() synchronously before any await.
-async function CurrentUser() {
-  const ctx = useCtx();
-  const id = ctx.params.id ?? 'me';
-  // ...fetch with ctx.env or ctx.req...
-  return <UserCard id={id} name={`User ${id}`} />;
-}
-
 /* ------------------------------------------------------------------ *
  *  App                                                               *
  * ------------------------------------------------------------------ */
@@ -358,15 +329,17 @@ const app = new Edge();
 app.security.logSecurityEvents = true;
 app.security.extraHeaders = {
   'Strict-Transport-Security': 'max-age=31536000; includeSubDomains',
-  'X-Custom-Powered-By': 'lengkapp-server',
+  'X-Custom-Powered-By': 'edge-server',
 };
 
 /* ================================================================== *
  *  Basic routes                                                      *
  * ================================================================== */
 
+// Plain text
 app.get('/health', (ctx) => ctx.text('ok'));
 
+// JSON with a custom status
 app.get('/api/time', (ctx) =>
   ctx.json({ now: new Date().toISOString() }, 200)
 );
@@ -375,7 +348,7 @@ app.get('/api/time', (ctx) =>
 // a text/html Response.
 app.get('/', () => (
   <Layout title="Home">
-    <h1>Hello from lengkapp-server</h1>
+    <h1>Hello from edge-server</h1>
     <p>This page was rendered from JSX.</p>
     <TodoList items={['Write routes', 'Render JSX', 'Ship it']} />
   </Layout>
@@ -386,7 +359,10 @@ app.get('/about', (ctx) =>
   ctx.html(
     <Layout title="About">
       <h1>About</h1>
-      <p>Fragments, components, arrays — all supported.</p>
+      <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" />
@@ -395,11 +371,6 @@ app.get('/about', (ctx) =>
   )
 );
 
-// ctx.page prepends <!DOCTYPE html> if missing
-app.get('/page', (ctx) =>
-  ctx.page(<Layout title="Page"><h1>Full document</h1></Layout>)
-);
-
 // 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>')
@@ -410,7 +381,7 @@ app.get('/raw', (ctx) =>
  * ================================================================== */
 
 // Dynamic route: /users/:id
-app.get('/users/:id', async (ctx) => {
+app.get('/users/:id', (ctx) => {
   const { id } = ctx.params;
   return ctx.html(
     <Layout title={`User ${id}`}>
@@ -419,11 +390,6 @@ app.get('/users/:id', async (ctx) => {
   );
 });
 
-// Async component + useCtx()
-app.get('/me/:id', (ctx) =>
-  ctx.html(<Layout title="Me"><CurrentUser /></Layout>)
-);
-
 // Multiple params: /posts/:year/:slug
 app.get('/posts/:year/:slug', (ctx) => {
   const { year, slug } = ctx.params;
@@ -488,42 +454,51 @@ app.delete('/api/items/:id', (ctx) =>
 );
 
 app.options('/api/items', (ctx) => ctx.text('', 204));
+
 app.head('/api/items', (ctx) => ctx.text('', 200));
 
 /* ================================================================== *
  *  Route options: cors, cache, compress, log, validate               *
  * ================================================================== */
 
+// CORS with a wildcard origin
 app.get(
   '/cors-open',
   { cors: true, log: true },
   (ctx) => ctx.json({ cors: 'wildcard' })
 );
 
+// 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, X-DeviceId',
+      headers: 'Content-Type, X-CSRF-Token',
     },
   },
   (ctx) => ctx.json({ cors: 'restricted' })
 );
 
+// Caching: cache the GET response for 60s, revalidate in background
 app.get(
   '/cached',
-  { cache: { ttl: 60, staleWhileRevalidate: 30 }, log: true },
+  {
+    cache: { ttl: 60, staleWhileRevalidate: 30 },
+    log: true,
+  },
   (ctx) => ctx.json({ generatedAt: Date.now() })
 );
 
+// Compression (gzip / deflate based on Accept-Encoding)
 app.get(
   '/big',
   { compress: true },
   (ctx) => ctx.html(`<pre>${'x'.repeat(5000)}</pre>`)
 );
 
+// Request validation — return false to get a 400 automatically
 app.post(
   '/admin',
   {
@@ -535,6 +510,7 @@ app.post(
   (ctx) => ctx.json({ ok: true })
 );
 
+// Everything combined
 const everythingOptions: RouteOptions = {
   cors: { origin: '*' },
   cache: { ttl: 120, staleWhileRevalidate: 60 },
@@ -558,6 +534,7 @@ app.get('/everything', everythingOptions, (ctx) =>
 app.get('/jsx/gallery', (ctx) =>
   ctx.html(
     <Layout title="JSX Gallery">
+      {/* Style objects → kebab-cased, numbers get px added */}
       <div
         style={{
           backgroundColor: 'tomato',
@@ -569,31 +546,44 @@ app.get('/jsx/gallery', (ctx) =>
         Styled box
       </div>
 
-      <label className="lbl" htmlFor="name">Name</label>
+      {/* className and htmlFor are aliased to class / for */}
+      <label className="lbl" htmlFor="name">
+        Name
+      </label>
       <input id="name" type="text" required disabled={false} />
 
+      {/* Boolean attributes: true emits the bare attribute */}
       <input type="checkbox" checked readOnly />
       <button disabled>Nope</button>
 
+      {/* Void elements self-close */}
       <img src="/logo.png" alt="logo" />
       <br />
       <hr />
 
+      {/* dangerouslySetInnerHTML */}
       <div dangerouslySetInnerHTML={{ __html: '<b>trusted</b>' }} />
 
+      {/* Fragments */}
       <>
         <p>Fragment child A</p>
         <p>Fragment child B</p>
       </>
 
+      {/* Arrays of JSX */}
       {[<span key="a">A</span>, <span key="b">B</span>, <span key="c">C</span>]}
 
+      {/* Escaping: user-supplied strings are escaped */}
       <p>{'<script>alert(1)</script>'}</p>
 
+      {/* Dangerous URLs are dropped */}
       <a href="javascript:alert(1)">nope</a>
       <a href="https://example.com">ok</a>
 
+      {/* Numbers are stringified and escaped */}
       <p>Count: {42}</p>
+
+      {/* null / undefined / booleans render nothing */}
       <p>{null}{undefined}{false}{true}</p>
     </Layout>
   )
@@ -603,8 +593,8 @@ app.get('/jsx/gallery', (ctx) =>
  *  renderToString() standalone                                       *
  * ================================================================== */
 
-app.get('/jsx/string', async (ctx) => {
-  const html = await renderToString(
+app.get('/jsx/string', (ctx) => {
+  const html = renderToString(
     <section>
       <h1>Rendered manually</h1>
       <p>Via renderToString()</p>
@@ -619,6 +609,7 @@ app.get('/jsx/string', async (ctx) => {
 
 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.
 });
 
 /* ================================================================== *
@@ -636,11 +627,10 @@ export default {
 ### Feature → route cheat-sheet
 
 | Feature | Route / location |
-| --- | --- |
+|---|---|
 | `ctx.text` | `GET /health` |
 | `ctx.json` | `GET /api/time`, `POST /api/echo`, … |
 | `ctx.html` with JSX | `GET /` |
-| `ctx.page` | `GET /page` |
 | `ctx.html` with string | `GET /raw` |
 | Returning JSX directly | `GET /` |
 | `ctx.redirect` | `GET /login`, `GET /logout`, `GET /dashboard` |
@@ -655,9 +645,8 @@ export default {
 | `validate` | `POST /admin`, `/everything` |
 | `security.extraHeaders` | set once near the top |
 | `security.logSecurityEvents` | set once near the top |
-| `useCtx()` | `CurrentUser` component, `GET /me/:id` |
 | Fragments | `GET /about`, `GET /jsx/gallery` |
-| Function components | `Layout`, `UserCard`, `TodoList`, `CurrentUser` |
+| Function components | `Layout`, `UserCard`, `TodoList` |
 | Style objects | `GET /jsx/gallery` |
 | Boolean attrs / void elements | `GET /jsx/gallery` |
 | `dangerouslySetInnerHTML` | `GET /jsx/gallery` |
@@ -673,23 +662,25 @@ export default {
 ### 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.href = url`). |
-| `_open` | Open the URL in a new tab (`window.open(url, '_blank', 'noopener')`). |
-| `_id` | Opt in to sending the `X-DeviceId` header on this request. See [Device Identity](#device-identity). Only meaningful on `_get` / `_post`. |
+|---|---|
+| `_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 with the response. |
+| `_out` | Replace the target element itself. |
 | `_before` | Insert the response before the target. |
 | `_after` | Insert the response after the target. |
-| `_trigger` | `click` (default), `load`, or `visible`. |
-| `_form` | CSS selector for a `<form>`; its `FormData` becomes the POST body. |
-| `_json` | Comma-separated CSS selectors; their values are collected into a JSON POST body. |
-| `_toast` | CSS selector — on a non-2xx response, inject the response body there instead of showing the inline error UI. |
+| `_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, and its value is a CSS selector. If multiple are present, the client resolves them in the order `_in`, `_out`, `_before`, `_after`.
+**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.
 
-**`_json` field scope.** Each entry is a CSS selector resolved with `document.querySelector`. The JSON key is the element's `name`, then its `id`, then the selector string. Checkbox → boolean, checked radio → value, `<select multiple>` → array of values, otherwise the element's value.
+**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).
 
 ### Examples
 
@@ -698,118 +689,99 @@ export default {
 <button _get="/more-posts" _in="#posts">Load More</button>
 
 <!-- replace this element with the response -->
-<div _get="/user-profile" _out="#profile"></div>
+<div _get="/user-profile" _out="this"></div>
 
-<!-- POST JSON built from #username and #password, replace #status -->
-<button _post="/login" _json="#username,#password" _in="#status">Login</button>
+<!-- POST JSON built from form fields, replace the children of #status -->
+<button _post="/login" _json="username,password" _in="#status">Login</button>
 
 <!-- POST a whole form -->
 <form id="signup">…</form>
 <button _post="/signup" _form="#signup" _in="#result">Sign up</button>
 
 <!-- fetch lazily when the element scrolls into view -->
-<div _get="/lazy" _in="#feed" _trigger="visible"></div>
+<div _get="/lazy" _in="this" _trigger="visible"></div>
 
-<!-- same-tab navigation -->
-<a href="/dashboard" _go>Dashboard</a>
+<!-- skeleton loader with a 5-second timeout -->
+<div _get="/feed" _in="this" _loader="skeleton" _timeout="5000"></div>
+
+<!-- _toast if non 2xx -->
+<div _get="/feed-error" _in="this" _toast="#toast"></div>
+
+<!-- same-tab navigation with a device id -->
+<a href="/dashboard" _go _id>Dashboard</a>
 
 <!-- new-tab navigation -->
 <a href="/docs" _open>Docs</a>
 
-<!-- attach the X-DeviceId header to this POST -->
+<!-- POST with X-DeviceId header -->
 <button _post="/like" _id _in="#card-3">Like</button>
-
-<!-- on error, drop the response body into a toast host -->
-<button _post="/submit" _form="#f" _toast="#toasts">Submit</button>
 ```
 
 ### Triggers
 
-- **`click`** (default) — the handler calls `event.preventDefault()` and issues the request.
-- **`load`** — the request fires as soon as the element is initialized.
-- **`visible`** — an `IntersectionObserver` fires the request the first time the element enters the viewport, then disconnects.
+- `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.
 
 ### How Content Is Inserted
 
-1. The request is sent with the browser defaults for credentials (same-origin).
-2. The `X-CSRF-Token` header is populated from `<meta name="_csrf">` (see [CSRF Protection](#csrf-protection)).
-3. When the triggering element carries `_id`, the `X-DeviceId` header is added (see [Device Identity](#device-identity)).
-4. For `_post`, the body is `FormData` from `_form`, JSON from `_json`, or empty. `_post` requires one of them; otherwise the request fails with a client-side error.
-5. The response text is parsed into a `<template>`.
-6. Any `<script>` elements inside the fragment are replaced by inert comment markers that hold their DOM position.
-7. The script-free fragment is inserted according to the placement mode (`_in`, `_out`, `_before`, `_after`).
-8. Each script is then re-created as a fresh `<script>` element at its marker and injected sequentially:
-   - Inline scripts execute synchronously.
-   - `async` external scripts are fire-and-forget.
-   - Non-async external scripts (classic and `type="module"`) are awaited via their `load` / `error` events, with a 30-second safety timeout so a stuck URL cannot wedge the queue.
-9. Newly inserted `[_get]` / `[_post]` / `[_go]` / `[_open]` elements are picked up by a `MutationObserver` on `document.documentElement`.
+- 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.
 
 > **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.
 
 ### Loader & Error States
 
-- A spinner (Lucide `loader-circle` SVG) is inserted as soon as the request starts:
-  - `_in` — the target's existing children are cleared and the spinner is placed inside.
-  - `_out` / `_before` — the spinner is inserted immediately before the target.
-  - `_after` — the spinner is inserted immediately after the target.
-- The spinner is removed when the response (or error) lands.
+- 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 client-side validation error (e.g. `_post` without `_form` / `_json`) — the spinner is replaced in place by an error box containing a message and a **Retry** button that re-issues the request.
-- On a non-2xx response, if the triggering element has a `_toast` attribute whose selector resolves, the response body is injected there (using `_in` semantics, script-aware) and no inline error box is shown.
-- The stylesheet is injected once and defines `._edge-loader`, `._edge-error`, and a `_edge-spin` keyframe.
+- 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.
 
-## Device Identity
+### View Transitions
 
-Add `_id` to any `_get` / `_post` element to attach an `X-DeviceId` header to that request.
+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`.
 
-The value is resolved by `deviceId()`, which:
+## Device Fingerprint
 
-1. Calls `window.deviceId()` if it is defined and returns a non-null value, coercing the result to a string.
-2. Otherwise returns `new Date().toString()`.
+Add `_id` to any `_get` / `_post` / `_go` / `_open` element to attach a stable device identifier.
 
-`window.deviceId` is designed as a hook so the host application can plug in its own fingerprint implementation (e.g. a client-side identifier, a cookie, or a third-party library). By default, the timestamp fallback is intentionally weak.
+**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.
 
-```ts
-// Optional: install your own stable identifier.
-declare global {
-  interface Window {
-    deviceId?: () => string;
-  }
-}
+**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.
 
-window.deviceId = () => {
-  let id = localStorage.getItem('device-id');
-  if (!id) {
-    id = crypto.randomUUID();
-    localStorage.setItem('device-id', id);
-  }
-  return id;
-};
-```
+**Delivery.**
 
-**Delivery.** The header is added only to `_get` / `_post` requests. It is not added to `_go` / `_open` navigation. Without `_id`, no device identifier is computed and no `X-DeviceId` header is sent.
+- `_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`).
 
-## CSRF Protection
+**Fallback.** If `crypto.subtle` is unavailable (non-secure context), a djb2 hash of the same signals is used, with lower collision resistance.
 
-The client automatically attaches the value of `<meta name="_csrf">` (if present) to every `_get` / `_post` request as the `X-CSRF-Token` header.
+Without `_id`, no fingerprint is computed, no header is set, and no URL parameter is added.
 
-```html
-<meta name="_csrf" content="…">
-```
+## CSRF Protection
 
-On the server, validate that header inside a `validate` option:
+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:
 
 ```ts
 app.post('/submit', {
-  validate: (ctx) => {
-    const header = ctx.req.headers.get('X-CSRF-Token') || '';
-    const cookie = ctx.getCookie('csrf_token') || '';
-    return header.length > 0 && header === cookie;
+  validate: async (ctx) => {
+    const body = await ctx.req.json().catch(() => ({}));
+    return body.csrf_token && body.csrf_token === ctx.getCookie('csrf_token');
   }
 }, handler);
 ```
 
-When the meta tag is absent, the header is sent with an empty value.
+For `_form`-based submissions, read the field from the parsed form data using the same pattern.
 
 ## Security Controls
 
@@ -826,14 +798,14 @@ app.security.extraHeaders = {
 };
 ```
 
-### OWASP 2025 Coverage
+## OWASP 2025 Coverage
 
 | Category | Mitigation |
-| --- | --- |
-| A01 Broken Access Control | Strict CORS allowlist, explicit placement modes, no implicit trust |
+|---|---|
+| 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 runtime dependencies |
-| A04 Crypto Failures | No home-grown crypto in the runtime; relies on platform primitives (`Headers`, `CompressionStream`, Web Crypto where the host uses it) |
+| 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 |
@@ -859,7 +831,7 @@ export default {
 The `Edge` constructor takes no arguments. Behaviour is configured through public properties and route options:
 
 | 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` |
@@ -874,40 +846,37 @@ app.security.extraHeaders = {
 
 ## Performance
 
-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), and a native worker:
+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:
 
-| Framework | `/text` req/s | `/json` req/s |
-| --- | --- | --- |
-| **@lengkapp/edge** | 503 | 500 |
+| Framework | /text req/s | /json req/s |
+|---|---|---|
+| @lengkapp/edge | 503 | 500 |
 | Hono | 506 | 495 |
 | Hono (tiny) | 505 | 498 |
 | Native Workers | 498 | 500 |
 
 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.
 
-The JSX renderer 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.
+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.
 
-The client is equally lean: it injects a single stylesheet and binds each element exactly once via an `el.__edgeInit` guard. An in-flight request on an element is aborted when a new one starts.
+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.
 
-## Build
-
-`build.mjs` bundles `client.js` and `server.js` with esbuild (`bundle: false`, `format: "esm"`, `target: "es2022"`, `minify: true`), then runs Terser with `module: true`, `compress.passes: 2`, and `mangle.toplevel: true` for a second pass. A `/*! … */` banner containing the LICENSE text is prepended to each file, and `client.d.ts`, `server.d.ts`, `README.md`, and `LICENSE` are copied into `dist/`.
+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.
 
 ## Security Posture Summary
 
 | Layer | Mechanism |
-| --- | --- |
+|---|---|
 | HTML insertion (client) | Response text parsed into a `<template>`; placement driven by `_in` / `_out` / `_before` / `_after` |
-| Script execution (client) | `<script>` elements lifted out, replaced by comment markers, then re-created at their original position and run in document order |
-| Request hygiene (client) | `X-CSRF-Token` from `<meta name="_csrf">`; optional `X-DeviceId` (only when `_id` is present); abortable via `AbortController`; per-element in-flight cancellation |
-| Cookies | Browser defaults (same-origin); names validated on the server |
+| 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, JSX attributes |
-| Build | LICENSE banner; esbuild + Terser double-pass minification; per-file `client.d.ts` / `server.d.ts` / `README.md` / `LICENSE` copied to `dist/` |
+| 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 |
 
 ## License
 
-MIT — see [LICENSE](./LICENSE) for the full text.
-
+MIT — see [LICENSE](./LICENSE) for the full text.  
 © LengkApp — Yasir Haris