first commit

2026-07-24 12:10:10 +05:30
commit 9d0504f8c1
130 changed files with 46944 additions and 0 deletions
@@ -0,0 +1,276 @@
+# WrNexus
+
+> WrNexus is an SSR-first, **Bun-native** full-stack web framework. UI is written in
+> `.wrn` files (its own component language — NOT React/JSX/Vue). Routing is file-based.
+> This document teaches an AI how to write correct WrNexus code. It is private and
+> post-dates model training data, so rely on THIS document, not prior web-framework
+> assumptions.
+
+## Golden rules
+
+- **Pages, components, and layouts are `.wrn` files.** Do NOT write `.tsx`/`.jsx`/React
+  for UI. Do NOT use `useState`, hooks, JSX, or a client bundler.
+- **Routing is file-based** under `app/`. The filename is the route. No router config.
+- **Interactivity** lives in `state` + `{expr}` + `@event` inside `.wrn`. Components render
+  on the server and hydrate automatically — you never write client-side JS islands.
+- **Runtime is Bun only** (uses `Bun.serve`, `bun:sqlite`, `Bun.password`, …). Node is not supported.
+- To add files, prefer the CLI: `wrnexus generate page <Name>` / `component <name>` / `api <path>` / `schema <name>`.
+
+## Project layout
+
+```
+app/
+  pages/       *.wrn  → routes: index.wrn = "/", about.wrn = "/about", blog/[slug].wrn = "/blog/:slug"
+  components/  *.wrn  → reusable UI, mounted in a page/component via <div data-component="name" ...props>
+  layouts/     *.wrn  → named layouts; a page opts in with  layout = "name"
+  api/         *.ts   → HTTP handlers: export const GET/POST/PUT/PATCH/DELETE = async (ctx) => Response
+  middleware/  *.ts   → export default async (ctx, next) => next()
+  realtime/    *.ts   → export default defineRoom({ ... }) from "@wrnexus/core"  (ws://host/realtime/<name>)
+  schemas/     *.ts   → validation schemas (the `v` builder), used by forms + parseBody
+  locales/     *.json → i18n messages per language
+  db/          schema.ts, queries/*.sql, migrations/*.sql
+  styles/      global.css  → Tailwind (default) or plain CSS
+wrnexus.config.ts    → app config (AppConfig from "@wrnexus/styles")
+public/              → static assets served at /
+```
+
+## `.wrn` page
+
+```wrn
+page Home {
+  layout = "public"          // optional: a component in app/layouts/<name>.wrn ("none" to skip)
+
+  state count = 0            // optional: seeds client-reactive state (omit for pure SSR)
+
+  seo {
+    title = "Home"
+    description = "..."
+    canonical = "/"
+  }
+
+  view {
+    <h1>Hello</h1>
+    <p>Count is {count}, doubled is {count * 2}.</p>
+    <button @click="count++">Increment</button>
+    <div data-component="counter" start="5" label="Clicks"></div>
+  }
+
+  style {
+    h1 { color: var(--wire-color-text); }
+  }
+}
+```
+
+## `.wrn` component
+
+```wrn
+component Counter {
+  props {                    // props come from mount attributes; each is coerced to the
+    start = 0                // TYPE of its default (so start="5" arrives as the number 5)
+    label = "Count"
+  }
+  state count = start        // state may reference props
+  view {
+    <button @click="count++">{label}: {count}</button>
+  }
+}
+```
+
+Mount it from any page/component: `<div data-component="counter" start="0" label="Clicks"></div>`.
+Components render on the server with their props, then hydrate — no per-component JS.
+
+## The `view { }` block (plain HTML + a few directives)
+
+- `{expr}` — interpolate a JS expression. Reactive if it references `state`: `{count}`, `{count * 2}`, `{user.name}`.
+- `@event="expr"` — bind a DOM event; the expression runs in the reactive scope: `@click="count++"`, `@input="name = event.target.value"`.
+- `<div data-component="name" prop="v">` — mount a component (attrs become string props, coerced).
+- `<slot></slot>` / `<slot name="x"></slot>` — component/layout slots; fill with `<div data-slot="x">…</div>`.
+- **Server loop (DB/list/table):** `{#each <list> as <item>[, <i>]} …rows… {:empty} …fallback… {/each}` — iterates SSR data on the server and renders markup per item. `{item.field}` interpolates (HTML-escaped, XSS-safe). `<list>` is a JS expression, usually an `ssr` data binding (see "Data-driven tables" below). This is how you render a database table in `.wrn`.
+- **Server conditional:** `{#if <expr>} … {:else if <expr>} … {:else} … {/if}` — renders the first truthy branch on the server. `<expr>` can reference `ssr` data, or the `item`/`index` of an enclosing `{#each}`. Works at page level and inside loops (e.g. `{#if r.active}<span>●</span>{:else}<span>○</span>{/if}` per row). For client-side show/hide based on reactive `state`, use `data-show="expr"` instead.
+- i18n: `{t:home.title}` in text, `t:placeholder="form.name"` on attributes — resolved per request from `app/locales/`.
+- Theme: any element with `data-wire-theme-toggle` toggles light/dark; `data-wire-theme-set="dark"` sets it.
+- Void/self-closing tags are fine: `<br />`, `<img src="..." />`.
+- Only `{` and `}` are special (interpolation). Don't use a bare `}` in view text.
+
+## Data-driven tables / lists (server-rendered `.wrn`)
+
+Use an `ssr` data binding to fetch rows on the server, then `{#each}` to render them.
+This renders on the **server** (SSR-first) and is HTML-escaped by default.
+
+```wrn
+page Admin {
+  layout = "dashboard"
+
+  // Fetch on the server. The api handler at /api/contacts returns { contacts: [...] };
+  // this block's `return contacts` exposes that array (via `$data`) as the binding `rows`.
+  ssr {
+    api rows GET /api/contacts { return contacts }
+  }
+
+  view {
+    <table>
+      <tbody>
+        {#each rows as r, i}
+          <tr>
+            <td>#{i}</td>
+            <td>{r.name}</td>
+            <td><a href="mailto:{r.email}">{r.email}</a></td>
+          </tr>
+        {:empty}
+          <tr><td colspan="3">No submissions yet.</td></tr>
+        {/each}
+      </tbody>
+    </table>
+  }
+}
+```
+
+The matching API returns the array under a key the `ssr` block reads:
+
+```ts
+// app/api/contacts.ts  → GET /api/contacts
+import { getDb } from "@wrnexus/db";
+export const GET = async () => {
+  const contacts = await getDb().all("SELECT id, name, email FROM contacts ORDER BY id DESC");
+  return Response.json({ contacts });   // ssr block does `return contacts`
+};
+```
+
+**Prefer this `.wrn` + `{#each}` approach for DB-backed tables and lists.** (`.ts`/`.tsx`
+pages returning an HTML string are also supported for fully-custom programmatic rendering,
+but a `.wrn` page with `ssr` data + `{#each}` is the idiomatic, SSR-first way.)
+
+## API routes (`app/api/*.ts`)
+
+```ts
+// app/api/users/list.ts  → GET /api/users/list
+import { getDb } from "@wrnexus/db";
+
+export const GET = async (ctx) => {
+  return Response.json({ users: await ListUsers(getDb()) });
+};
+
+export const POST = async (ctx) => {
+  const body = await ctx.req.json();
+  return Response.json({ ok: true, body }, { status: 201 });
+};
+```
+
+`ctx` (the `Context` from `@wrnexus/core`) has:
+`req: Request`, `url: URL`, `params: Record<string,string>` (dynamic route params, e.g. `/users/[id]` → `ctx.params.id`),
+`lang: string`, `t(key, params?)` (i18n), `cookies` (get/set), `session` (get/set). Auth: `getUser(ctx)` after `sessionAuth`/`logIn`.
+
+When an SSO forward-auth verifier needs the URL that originally reached the gateway, use
+`@wrnexus/helpers` instead of constructing it from untrusted headers:
+
+```ts
+import { redirectToLogin } from "@wrnexus/helpers";
+
+return redirectToLogin(ctx, "/login", {
+  allowedHosts: ["admin.localhost:3000", "reports.localhost:3000"],
+});
+```
+
+The package also exports `getOriginalRequestUrl`, `getOriginalRequestOrigin`,
+`getOriginalRequestPath`, and `getOriginalRequestMethod`. Always pass `allowedHosts` when
+using forwarded gateway URLs; the helper rejects untrusted redirect destinations.
+
+## Middleware & realtime
+
+```ts
+// app/middleware/logger.ts
+export default async function logger(ctx, next) {
+  console.log(ctx.req.method, ctx.url.pathname);
+  return next();               // return a Response WITHOUT calling next() to short-circuit
+}
+```
+
+```ts
+// app/realtime/chat.ts  → ws://host/realtime/chat
+import { defineRoom } from "@wrnexus/core";
+export default defineRoom({
+  onConnect(client) { client.send({ type: "system", text: "connected" }); },
+  onMessage(client, msg) { client.room.broadcast({ type: "message", data: msg }); },
+});
+```
+Client side: a page opts in with `data-room="chat"` (handled by the realtime runtime).
+
+## Config (`wrnexus.config.ts`)
+
+```ts
+import type { AppConfig } from "@wrnexus/styles";
+const config: AppConfig = {
+  seo: { title: "App", titleTemplate: "%s | App", description: "..." },
+  styles: { entry: "app/styles/global.css", process: async ({ entryPath, mode }) => /* Tailwind */ "" },
+  fonts: { sans: '"Inter", system-ui, sans-serif', google: [{ family: "Inter", weights: [400, 600] }] },
+  theme: { default: "dark", themes: { light: { "color-primary": "#2563eb" } } },
+  i18n: { default: "en", locales: ["en", "es"] },
+  db: { driver: "sqlite", url: "file:./dev.db" },
+  security: { cors: { enabled: true, origin: ["http://localhost:5173"] } },
+  // profiles: { production: { db: { driver: "postgres", url: process.env.DATABASE_URL } } },
+};
+export default config;
+```
+
+## Database (`@wrnexus/db`)
+
+```ts
+// app/db/schema.ts
+import { v, table } from "@wrnexus/db";
+export const users = table("users", {
+  id: v.id(),
+  name: v.string(),
+  email: v.string().unique(),
+  createdAt: v.timestamp(),
+});
+```
+- Queries: write `app/db/queries/*.sql` with `-- name: ListUsers :many` blocks; `wrnexus db generate` emits typed functions.
+- Access at runtime: `import { getDb } from "@wrnexus/db"; const rows = await ListUsers(getDb());`
+- Migrations in `app/db/migrations/`; run `wrnexus db migrate` (dev auto-migrates sqlite).
+
+## Validation (`@wrnexus/validation`)
+
+```ts
+// app/schemas/login.ts
+import { v } from "@wrnexus/validation";
+export default v.object({
+  email: v.string().email(),
+  password: v.string().min(8),
+});
+```
+In an API route: `import s from "../schemas/login"; import { parseBody } from "@wrnexus/validation"; const r = await parseBody(s, ctx.req);` → `r.ok ? r.value : r.response`.
+In a form: `<form data-schema="login" action="/api/login" method="post">` + `<span data-error="email"></span>` (client + server validation wired automatically).
+
+## AI / LLM (`@wrnexus/ai`)
+
+```ts
+// app/api/ai.ts
+import { createAI } from "@wrnexus/ai";
+const ai = createAI();                     // reads ANTHROPIC_API_KEY; default model claude-opus-4-8
+export const POST = async (ctx) => {
+  const { prompt } = await ctx.req.json();
+  return ai.streamResponse(prompt);        // or: return Response.json({ text: await ai.generate(prompt) })
+};
+```
+
+## CLI
+
+```
+wrnexus dev .                 # dev server + HMR
+wrnexus build .               # production build → dist/server.js
+bun dist/server.js            # run the production server (or npm start)
+wrnexus create <name>         # scaffold a new app
+wrnexus update --latest       # deps + syntax/config migrations + verification
+wrnexus generate page <Name>  # scaffold a page   (aliases: g p)
+wrnexus generate component <name> | api <path> | schema <name>
+wrnexus db migrate | rollback | status | new [--from-models] | generate | seed
+wrnexus eject <component>     # copy a Wire UI component's .wrn into app/components to customize
+```
+
+## When asked to "create a page/component/feature"
+
+1. Create the `.wrn` file under `app/pages/` (or `app/components/`) with a `page`/`component` block — or run `wrnexus generate page <Name>`.
+2. Put markup in `view { }`, interactive bits in `state` + `{expr}` + `@event`, reusable UI as components mounted via `data-component`.
+3. For data, add an `app/api/*.ts` route and `getDb()`; for forms, add an `app/schemas/*.ts` and `data-schema`.
+4. Style with Tailwind utility classes in the view, or theme tokens (`var(--wire-*)`), or `style { }`.
+5. Never emit React/JSX, a manual router, or client-side island JS — the framework handles hydration.
@@ -0,0 +1,313 @@
+/* global AbortController, DOMParser, HTMLFormElement, HTMLInputElement, HTMLSelectElement, HTMLTextAreaElement, Node, URL, URLSearchParams, clearTimeout, document, fetch, navigator, setTimeout, window */
+
+(() => {
+  const SELECTOR = "[data-playground]";
+  const DESIGN_DEFAULTS = {
+    style: "default",
+    palette: "violet",
+    mode: "system",
+    font: "jakarta",
+    scale: "default",
+  };
+  const htmlPolicy = window.trustedTypes?.createPolicy("wrnexus-playground", {
+    createHTML: (value) => value,
+  });
+  let request;
+  let timer;
+
+  function storedDesign() {
+    const root = document.documentElement.dataset;
+    return {
+      style: root.uiStyle || DESIGN_DEFAULTS.style,
+      palette: root.uiPalette || DESIGN_DEFAULTS.palette,
+      mode: root.uiMode || DESIGN_DEFAULTS.mode,
+      font: root.uiFont || DESIGN_DEFAULTS.font,
+      scale: root.uiScale || DESIGN_DEFAULTS.scale,
+    };
+  }
+
+  function setCookie(name, value) {
+    document.cookie = `${name}=${encodeURIComponent(value)};path=/;max-age=31536000;samesite=lax`;
+  }
+
+  function applyDesign(settings, persist = true) {
+    const root = document.documentElement;
+    root.dataset.uiStyle = settings.style;
+    root.dataset.uiPalette = settings.palette;
+    root.dataset.uiMode = settings.mode;
+    root.dataset.uiFont = settings.font;
+    root.dataset.uiScale = settings.scale;
+
+    const dark =
+      settings.mode === "dark" ||
+      (settings.mode === "system" && window.matchMedia("(prefers-color-scheme: dark)").matches);
+    root.dataset.theme = dark ? "dark" : "light";
+
+    for (const control of document.querySelectorAll("[data-design-setting]")) {
+      control.value = settings[control.dataset.designSetting] || "";
+    }
+    if (persist) {
+      setCookie("wrn-ui-style", settings.style);
+      setCookie("wrn-ui-palette", settings.palette);
+      setCookie("wrn-ui-mode", settings.mode);
+      setCookie("wrn-ui-font", settings.font);
+      setCookie("wrn-ui-scale", settings.scale);
+      setCookie("wire-theme", dark ? "dark" : "light");
+    }
+  }
+
+  let design = storedDesign();
+  applyDesign(design, false);
+  for (const link of document.querySelectorAll(".docs-directory a[href]")) {
+    const target = new URL(link.href, window.location.origin);
+    if (target.pathname === window.location.pathname) link.setAttribute("aria-current", "page");
+  }
+  window.matchMedia("(prefers-color-scheme: dark)").addEventListener("change", () => {
+    if (design.mode === "system") applyDesign(design);
+  });
+
+  function sourceAttribute(value) {
+    return String(value)
+      .replaceAll("&", "&amp;")
+      .replaceAll('"', "&quot;")
+      .replaceAll("<", "&lt;")
+      .replaceAll(">", "&gt;");
+  }
+
+  function updateCode(playground) {
+    const form = playground.querySelector("[data-playground-form]");
+    const code = playground.querySelector("[data-playground-code]");
+    if (!(form instanceof HTMLFormElement) || !code) return;
+
+    const component = playground.getAttribute("data-playground-component") || "Component";
+    const publicTag = playground.getAttribute("data-playground-public-tag") === "true";
+    const hasSlot = playground.getAttribute("data-playground-has-slot") === "true";
+    const attributes = [];
+
+    for (const field of form.elements) {
+      if (
+        !(
+          field instanceof HTMLInputElement ||
+          field instanceof HTMLTextAreaElement ||
+          field instanceof HTMLSelectElement
+        ) ||
+        !field.name.startsWith("pg_")
+      )
+        continue;
+
+      const name = field.name.slice(3);
+      if (field instanceof HTMLInputElement && field.type === "checkbox") {
+        if (field.checked) attributes.push(name);
+      } else if (field.value !== "") {
+        const value = field.hasAttribute("data-playground-json")
+          ? `'${field.value.replaceAll("'", "\\'")}'`
+          : `"${field.value.replaceAll('"', '\\"')}"`;
+        attributes.push(`${name}=${value}`);
+      }
+    }
+
+    const tag = publicTag ? component : "div";
+    const mount = publicTag ? [] : [`data-component="${sourceAttribute(component)}"`];
+    const lines = [...mount, ...attributes].map((attribute) => `  ${attribute}`).join("\n");
+    const opening = lines ? `<${tag}\n${lines}` : `<${tag}`;
+    code.textContent = hasSlot
+      ? `${opening}>\n  <!-- Add slot content here -->\n</${tag}>`
+      : `${opening}\n/>`;
+  }
+
+  function valuesFrom(form) {
+    const params = new URLSearchParams();
+    let valid = true;
+
+    for (const field of form.elements) {
+      if (!(
+        field instanceof HTMLInputElement ||
+        field instanceof HTMLTextAreaElement ||
+        field instanceof HTMLSelectElement
+      ))
+        continue;
+      if (!field.name) continue;
+
+      const error = field.closest(".playground-field")?.querySelector("[data-playground-error]");
+      if (field.hasAttribute("data-playground-json")) {
+        try {
+          JSON.parse(field.value);
+          field.removeAttribute("aria-invalid");
+          if (error) error.textContent = "";
+        } catch {
+          field.setAttribute("aria-invalid", "true");
+          if (error) error.textContent = "Enter valid JSON";
+          valid = false;
+          continue;
+        }
+      }
+
+      params.set(field.name, field.type === "checkbox" ? String(field.checked) : field.value);
+    }
+
+    return valid ? params : null;
+  }
+
+  async function update(playground) {
+    const form = playground.querySelector("[data-playground-form]");
+    const preview = playground.querySelector("[data-playground-preview]");
+    const status = playground.querySelector("[data-playground-status]");
+    if (!(form instanceof HTMLFormElement) || !preview || !status) return;
+
+    const params = valuesFrom(form);
+    if (!params) {
+      status.textContent = "Fix the highlighted JSON value.";
+      return;
+    }
+
+    request?.abort();
+    request = new AbortController();
+    const url = new URL(window.location.href);
+    for (const key of [...url.searchParams.keys()]) {
+      if (key.startsWith("pg_")) url.searchParams.delete(key);
+    }
+    for (const [key, value] of params) url.searchParams.set(key, value);
+
+    playground.setAttribute("data-updating", "true");
+    status.textContent = "Updating preview…";
+
+    try {
+      const response = await fetch(url, {
+        headers: { "x-wrnexus-playground": "1" },
+        signal: request.signal,
+      });
+      if (!response.ok) throw new Error(`Preview request failed (${response.status})`);
+      const responseHtml = await response.text();
+      const parsed = new DOMParser().parseFromString(
+        htmlPolicy ? htmlPolicy.createHTML(responseHtml) : responseHtml,
+        "text/html",
+      );
+      const next = parsed.querySelector("[data-playground-preview]");
+      if (!next) throw new Error("Preview markup was not returned");
+
+      window.__wrnexusDisposeBehaviors?.(preview);
+      preview.replaceChildren(
+        ...Array.from(next.childNodes, (node) => document.importNode(node, true)),
+      );
+      window.__wrnexusHydrateScopes?.(preview);
+      window.__wrnexusHydrateCsrFetches?.(preview);
+      status.textContent = "Preview updated";
+    } catch (error) {
+      if (error?.name !== "AbortError") {
+        status.textContent = error instanceof Error ? error.message : "Unable to update preview";
+      }
+    } finally {
+      playground.removeAttribute("data-updating");
+    }
+  }
+
+  function schedule(playground) {
+    updateCode(playground);
+    clearTimeout(timer);
+    timer = setTimeout(() => update(playground), 180);
+  }
+
+  document.addEventListener("input", (event) => {
+    const playground = event.target.closest?.(SELECTOR);
+    if (playground) schedule(playground);
+  });
+
+  document.addEventListener("change", (event) => {
+    const playground = event.target.closest?.(SELECTOR);
+    if (playground) schedule(playground);
+  });
+
+  document.addEventListener("reset", (event) => {
+    const playground = event.target.closest?.(SELECTOR);
+    if (playground)
+      setTimeout(() => {
+        updateCode(playground);
+        update(playground);
+      }, 0);
+  });
+
+  document.addEventListener("click", async (event) => {
+    const designToggle = event.target.closest?.("[data-design-panel-toggle]");
+    if (designToggle) {
+      document.documentElement.toggleAttribute("data-design-panel-open");
+      return;
+    }
+
+    if (event.target.closest?.("[data-design-reset]")) {
+      design = { ...DESIGN_DEFAULTS };
+      applyDesign(design);
+      return;
+    }
+
+    const copyText = event.target.closest?.("[data-copy-text]");
+    if (copyText) {
+      try {
+        await navigator.clipboard.writeText(copyText.dataset.copyText || "");
+        copyText.setAttribute("data-copied", "true");
+        setTimeout(() => copyText.removeAttribute("data-copied"), 1200);
+      } catch {
+        // Clipboard access may be blocked in an insecure local context.
+      }
+      return;
+    }
+
+    const menuToggle = event.target.closest?.("[data-docs-menu-toggle]");
+    if (menuToggle) {
+      document.documentElement.toggleAttribute("data-docs-menu-open");
+      return;
+    }
+
+    if (event.target.closest?.("[data-docs-component-link]")) {
+      document.documentElement.removeAttribute("data-docs-menu-open");
+    }
+
+    const copy = event.target.closest?.("[data-playground-copy]");
+    if (!copy) return;
+    const playground = copy.closest(SELECTOR);
+    const code = playground?.querySelector("[data-playground-code]");
+    const status = playground?.querySelector("[data-playground-status]");
+    if (!code || !status) return;
+
+    try {
+      await navigator.clipboard.writeText(code.textContent || "");
+      status.textContent = "Component code copied";
+      const label = copy.lastChild;
+      if (label?.nodeType === Node.TEXT_NODE) label.textContent = "Copied";
+      setTimeout(() => {
+        if (label?.nodeType === Node.TEXT_NODE) label.textContent = "Copy";
+      }, 1400);
+    } catch {
+      status.textContent = "Copy failed. Select the code and copy it manually.";
+    }
+  });
+
+  document.addEventListener("input", (event) => {
+    const setting = event.target.closest?.("[data-design-setting]");
+    if (setting) {
+      design = { ...design, [setting.dataset.designSetting]: setting.value };
+      applyDesign(design);
+      return;
+    }
+    if (!event.target.matches?.("[data-docs-search]")) return;
+    const query = event.target.value.trim().toLowerCase();
+    const links = [...document.querySelectorAll("[data-docs-component-link]")];
+    let visible = 0;
+    for (const link of links) {
+      const matches = !query || link.textContent.toLowerCase().includes(query);
+      link.hidden = !matches;
+      if (matches) visible++;
+    }
+    for (const group of document.querySelectorAll(".docs-directory-group")) {
+      group.hidden = !group.querySelector("[data-docs-component-link]:not([hidden])");
+    }
+    const empty = document.querySelector("[data-docs-empty]");
+    if (empty) empty.hidden = visible > 0;
+  });
+
+  document.addEventListener("keydown", (event) => {
+    if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "k") {
+      event.preventDefault();
+      document.querySelector("[data-docs-search]")?.focus();
+    }
+  });
+})();