@pablozaiden/webapp 0.0.1

package/docs/realtime.md

@@ -0,0 +1,61 @@
+# Realtime
+
+Every server has a typed `RealtimeBus`. Apps should prefer the framework event convention:
+
+```ts
+type AppEvent = ResourceRealtimeEvent;
+
+const routes = defineRoutes<AppEvent>({
+  "/api/todos": {
+    async POST(req, ctx) {
+      const todo = await createTodo(req);
+      ctx.realtime.publishEntityChanged("todos", todo.id);
+      return jsonResponse(todo);
+    },
+  },
+});
+```
+
+Standard events have `type`, `resource`, `action`, optional `id`, optional `scope` and optional `payload`:
+
+| Helper | Event |
+| --- | --- |
+| `publishChanged("todos")` | `{ type: "todos.changed", resource: "todos", action: "changed" }` |
+| `publishEntityChanged("todos", id)` | `{ type: "todos.changed", resource: "todos", action: "changed", id }` |
+| `publishDeleted("todos", id)` | `{ type: "todos.deleted", resource: "todos", action: "deleted", id }` |
+| `publishSettingsChanged()` | `{ type: "settings.changed", resource: "settings", action: "changed" }` |
+
+Frontend code can refresh declaratively:
+
+```tsx
+useRealtimeRefresh({
+  resources: ["todos", "notes"],
+  refresh: () => refreshData(),
+});
+```
+
+Or combine initial loading and realtime refresh:
+
+```tsx
+const todos = useLiveQuery({
+  load: () => api<Todo[]>("/api/todos"),
+  realtime: { resources: ["todos"] },
+});
+```
+
+For targeted delivery, clients subscribe with filters and the server publishes to matching targets:
+
+```tsx
+useRealtimeRefresh({
+  filters: { resource: "todos", scope: workspaceId },
+  resources: ["todos"],
+  scopes: [workspaceId],
+  refresh,
+});
+```
+
+```ts
+ctx.realtime.publishEntityChanged("todos", todo.id, { scope: workspaceId });
+```
+
+`ctx.realtime.publish(customEvent)` and `useRealtime({ onEvent })` still exist as low-level escape hatches. The hook reconnects with exponential backoff and uses the same origin as the page.

package/docs/release.md

@@ -0,0 +1,64 @@
+# Release and publishing
+
+## Pull requests
+
+`PR Checks` runs on every pull request:
+
+1. Install dependencies with `bun install --frozen-lockfile`.
+2. Run `bun run tsc`.
+3. Run `bun test`.
+4. Build both example apps.
+5. Start the compiled example binaries and smoke-test `/api/health` plus one app endpoint.
+
+## Main branch
+
+`Main Docker Smoke` runs after merges to `main`:
+
+1. Build Linux x64 binaries for both examples.
+2. Build Docker images from `examples/*/Dockerfile`.
+3. Run both containers.
+4. Smoke-test `/api/health` plus one app endpoint through the published container ports.
+
+## NPM releases
+
+`Release NPM Package` publishes `@pablozaiden/webapp` when a GitHub release is published. It also supports manual dispatch with a tag input, publishing with npm tag `unstable`.
+
+The workflow:
+
+1. Reads the version from the release tag, e.g. `v0.1.0` -> `0.1.0`.
+2. Checks out that tag.
+3. Updates `package.json` version in the workflow workspace.
+4. Runs install, tests and build.
+5. Publishes with npm provenance and public access.
+
+## First manual publish / trusted publishing setup
+
+For the first publish, npm may require a local manual publish before trusted publishing can be authorized for this GitHub repository.
+
+1. Log in locally:
+   ```bash
+   npm login
+   npm whoami
+   ```
+2. From a clean checkout, set the first version only in the local working tree:
+   ```bash
+   npm version 0.1.0 --no-git-tag-version
+   ```
+3. Inspect the package contents:
+   ```bash
+   npm pack --dry-run
+   ```
+4. Publish the scoped package publicly:
+   ```bash
+   npm publish --access public
+   ```
+5. Revert the local version edit if it should not be committed:
+   ```bash
+   git checkout -- package.json
+   ```
+6. In npm package settings for `@pablozaiden/webapp`, configure trusted publishing for GitHub Actions:
+   - Owner/repository: `PabloZaiden/webapp`
+   - Workflow: `release-npm-package.yml`
+   - Environment: leave empty unless an environment is added later
+7. After that, publish future versions by creating and publishing GitHub releases with tags like `v0.1.1`.
+

package/docs/server.md

@@ -0,0 +1,45 @@
+# Server API
+
+Use `createWebAppServer` with `defineRoutes`. Route patterns support exact path segments and `:params`.
+
+```ts
+const routes = defineRoutes<AppEvent>({
+  "/api/projects": {
+    GET: () => jsonResponse(projects),
+    async POST(req, ctx) {
+      const body = await parseJson<{ name: string }>(req);
+      const project = createProject(body.name);
+      ctx.realtime.publishEntityChanged("projects", project.id);
+      return jsonResponse(project);
+    },
+  },
+  "/api/projects/:id": {
+    scopes: ["projects:write"],
+    PATCH: updateProject,
+  },
+});
+```
+
+Route defaults are intentionally secure:
+
+| Setting | Default | Meaning |
+| --- | --- | --- |
+| `auth` | `required` | Requires passkey session, API key or device bearer token once auth is configured |
+| `sameOrigin` | `mutations` | Requires `Origin`/`Referer` for cookie/browser mutations |
+| `scopes` | `[]` | Checked for API keys and device tokens; `*` grants all |
+
+Set `auth: "public", sameOrigin: "never"` only for deliberate unauthenticated endpoints such as health probes, webhooks or callback receivers.
+
+Built-in endpoints include:
+
+| Endpoint | Purpose |
+| --- | --- |
+| `GET /api/health` | Health/version |
+| `GET /api/config` | Safe framework config for UI |
+| `/api/passkey-auth/*` | Passkey bootstrap/login/logout/delete |
+| `/api/api-keys` | Browser-managed API key create/list/delete |
+| `/api/auth/device`, `/api/auth/token`, `/api/auth/refresh`, `/api/auth/revoke` | Device auth and refresh-token flow |
+| `/.well-known/jwks.json`, `/.well-known/openid-configuration` | Token verification metadata |
+| `/api/preferences/theme`, `/api/preferences/log-level` | Settings persistence |
+| `/api/server/kill` | Authenticated server shutdown |
+| `/api/ws` | Realtime websocket by default |

package/docs/settings.md

@@ -0,0 +1,42 @@
+# Settings
+
+Settings is framework-owned so apps stay consistent. It includes:
+
+- Passkey logout/delete
+- API key create/list/delete when enabled
+- Theme preference: system/light/dark
+- Log-level preference unless `{PREFIX}_LOG_LEVEL` is set
+- Server kill
+- Version/about
+
+Apps can append structured custom sections:
+
+```tsx
+<WebAppRoot
+  settings={{
+    sections: [
+      {
+        id: "sync",
+        title: "Sync",
+        rows: [
+          {
+            id: "last-sync",
+            title: "Last sync",
+            description: lastSync,
+            actions: [{ id: "sync-now", label: "Sync now", onAction: syncNow }],
+          },
+          {
+            id: "disconnect",
+            title: "Disconnect",
+            description: "Stops syncing this workspace.",
+            danger: true,
+            actions: [{ id: "disconnect", label: "Disconnect", variant: "danger", onAction: disconnect }],
+          },
+        ],
+      },
+    ],
+  }}
+/>
+```
+
+`render` remains available as an escape hatch for custom controls inside a section. Prefer structured `rows` for simple settings because the framework keeps spacing, typography and danger-zone styling consistent.

package/docs/sidebar.md

@@ -0,0 +1,80 @@
+# Sidebar and routing
+
+`WebAppRoot` owns the app shell: fixed sidebar title row, top action buttons, search, scrollable tree, version footer, main title bar and mobile drawer behavior.
+
+```tsx
+<WebAppRoot
+  appName="My App"
+  homeRoute={{ view: "home" }}
+  sidebar={{
+    topActions: [
+      { id: "activity", title: "Activity", route: { view: "home" } },
+      { id: "new", title: "New item", route: { view: "new" } },
+    ],
+    getNodes: ({ search }) => buildSidebarNodes(search),
+  }}
+  routes={{
+    home: <Home />,
+    project: (route) => <ProjectView id={String(route.projectId)} />,
+  }}
+/>
+```
+
+The first two app actions are optional; settings and collapse/uncollapse are always framework-owned and always appear as the rightmost fixed actions.
+
+Sidebar nodes support:
+
+| Field | Purpose |
+| --- | --- |
+| `type` | `section` or `item` |
+| `route` | Hash route object used by `WebAppRoot` |
+| `children` | Collapsible nesting |
+| `action` | Per-section/item action such as `New` |
+| `actions` | Context menu items shown on sidebar right-click |
+| `pinnable` | Enables framework Pin/Unpin actions |
+| `pinId` | Stable pin identity when it should differ from `id` |
+| `badge` | Status/count label |
+| `defaultCollapsed` | Initial collapsed state |
+
+Search is intentionally app-defined: `getNodes({ search })` receives raw search text and returns the tree that should be rendered.
+
+Use `actions` when an entity needs a context menu in the sidebar. The same `ActionMenuItem[]` should also be returned from `header.getActions` for that entity route so right-click actions and the title-bar three-line menu stay consistent:
+
+```tsx
+const actions = projectActions(project);
+
+return {
+  type: "item",
+  id: project.id,
+  title: project.name,
+  route: { view: "project", projectId: project.id },
+  actions,
+};
+
+<WebAppRoot
+  sidebar={{
+    pinning: { sectionTitle: "Pinned" },
+    getNodes,
+  }}
+  header={{
+    getActions: ({ route }) => route.view === "project" ? projectActionsForRoute(route) : [],
+  }}
+/>
+```
+
+## Native pinning
+
+Pinning is framework-owned and persisted in browser `localStorage`. Mark route-backed items as `pinnable`; `WebAppRoot` injects `Pin to sidebar` / `Unpin from sidebar` into both the sidebar context menu and the title-bar action menu for the active route. Pinned entries reuse the original sidebar node actions, so right-clicking a pinned item shows the same contextual menu as the source item.
+
+```tsx
+{
+  type: "item",
+  id: project.id,
+  title: project.name,
+  route: { view: "project", projectId: project.id },
+  pinnable: true,
+  actions: projectActions(project),
+}
+```
+
+Disable pinning with `sidebar.pinning: false`; customize storage/title with `sidebar.pinning.storageKey` and `sidebar.pinning.sectionTitle`.

package/docs/ui-guidelines.md

@@ -0,0 +1,55 @@
+# UI guidelines
+
+The framework intentionally provides a consistent base UI:
+
+- Fixed sidebar header and main header share the same height.
+- Sidebar content scrolls independently; the title row and footer stay fixed.
+- Sidebar width is desktop-first and collapsible; mobile uses a drawer with backdrop.
+- The app title in the sidebar navigates home.
+- Settings and collapse controls are framework-owned.
+- Version is always visible at the bottom of the sidebar.
+- Main content should prefer panels, toolbars, badges and simple forms over custom one-off layouts.
+
+## Main content primitives
+
+Use these first:
+
+| Component | Use |
+| --- | --- |
+| `Toolbar` | Page title/actions inside main content |
+| `Panel` | Cards/sections; use `actions` for a top-right menu/action area |
+| `ActionMenu` | Three-line action menu for secondary surfaces; entity-level menus should usually be exposed through `WebAppRoot.header.getActions` so they render in the fixed title bar |
+| `Button` / `IconButton` | Actions |
+| `Badge` | Status/count labels |
+| `EntityHeader` | Main-content entity title/description/actions |
+| `DataList` / `DataListRow` | Lists with title, description, metadata, badge and actions |
+| `TextField`, `TextAreaField`, `SelectField` | Forms |
+| `FormGroup`, `FormActions` | Grouped forms and aligned action rows |
+| `DangerZone` | Destructive settings or entity operations |
+| `LoadingState`, `ErrorState` | Loading and failure UI |
+| `CodeValue` | Tokens, IDs, URLs and copyable code values |
+| `SegmentedControl` | Small enum settings |
+| `EmptyState` | Empty or missing content |
+| `ConfirmDialog` | Destructive confirmation |
+
+For entity actions, prefer the framework title bar: define one `ActionMenuItem[]` builder, attach it to `SidebarNode.actions` for right-click, and return the same actions from `WebAppRoot.header.getActions` for the selected route.
+
+## Visual validation captures
+
+Generated screenshots live in `artifacts/screenshots`:
+
+| Capture | Purpose |
+| --- | --- |
+| `notes-desktop-light.png` | Realistic app, desktop shell |
+| `notes-settings-desktop-light.png` | Framework settings |
+| `notes-mobile-light.png` | Mobile shell |
+| `notes-desktop-dark.png` | Dark mode |
+| `kitchen-desktop-light.png` | Kitchen sink desktop |
+| `kitchen-mobile-light.png` | Kitchen sink mobile |
+| `kitchen-sidebar-collapsed-light.png` | Collapsed sidebar title bar |
+| `kitchen-context-menu-light.png` | Sidebar context menu |
+| `kitchen-dialog-dark.png` | Confirm dialog overlay |
+
+Use `bun run screenshots` to regenerate these captures with Playwright. Browser automation and screenshot capture must stay Playwright-based and cross-platform; do not hard-code local Chrome or OS-specific browser paths.
+
+Use these captures as the manual visual baseline before changing shell, sidebar, settings or dialog styles.

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@pablozaiden/webapp",
+  "version": "0.0.1",
+  "description": "Opinionated Bun + React webapp framework for single-server apps",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PabloZaiden/webapp.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "files": [
+    "src",
+    "docs",
+    "README.md",
+    "package.json"
+  ],
+  "workspaces": [
+    "examples/*"
+  ],
+  "exports": {
+    "./server": "./src/server/index.ts",
+    "./web": "./src/web/index.ts",
+    "./web/styles.css": "./src/web/styles.css",
+    "./contracts": "./src/contracts/index.ts",
+    "./build": "./src/build/index.ts"
+  },
+  "scripts": {
+    "dev": "bun run --cwd examples/notes-todo dev",
+    "dev:kitchen-sink": "bun run --cwd examples/kitchen-sink dev",
+    "dev:notes-todo": "bun run --cwd examples/notes-todo dev",
+    "build": "bun run tsc && bun run --cwd examples/kitchen-sink build && bun run --cwd examples/notes-todo build",
+    "build:kitchen-sink": "bun run --cwd examples/kitchen-sink build",
+    "build:notes-todo": "bun run --cwd examples/notes-todo build",
+    "test": "bun test",
+    "tsc": "mkdir -p .cache/tsc && bunx tsc --noEmit --pretty false --incremental --tsBuildInfoFile .cache/tsc/build.tsbuildinfo",
+    "screenshots": "bunx playwright install chromium && bun tests/capture-screenshots.ts"
+  },
+  "dependencies": {
+    "@simplewebauthn/browser": "13.3.0",
+    "@simplewebauthn/server": "13.3.1",
+    "jose": "6.2.3",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "tailwindcss": "4.3.1",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "20.10.3",
+    "@testing-library/react": "16.3.2",
+    "@types/bun": "1.3.14",
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
+    "playwright": "1.61.0",
+    "typescript": "6.0.3"
+  }
+}

package/src/build/build-binary.ts

@@ -0,0 +1,42 @@
+import { chmodSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+export type BunCompileTarget =
+  | "bun-linux-x64"
+  | "bun-linux-arm64"
+  | "bun-darwin-x64"
+  | "bun-darwin-arm64"
+  | "bun-windows-x64";
+
+export interface BuildWebAppBinaryOptions {
+  entrypoint: string;
+  outfile: string;
+  target?: BunCompileTarget;
+  define?: Record<string, string>;
+}
+
+export function getBunCompileTargetFromArgs(argv = Bun.argv): BunCompileTarget | undefined {
+  const raw = argv.find((arg) => arg.startsWith("--target="))?.slice("--target=".length);
+  return raw as BunCompileTarget | undefined;
+}
+
+export async function buildWebAppBinary(options: BuildWebAppBinaryOptions): Promise<void> {
+  mkdirSync(dirname(options.outfile), { recursive: true });
+  const result = await Bun.build({
+    entrypoints: [options.entrypoint],
+    target: "bun",
+    minify: true,
+    sourcemap: "external",
+    define: options.define,
+    compile: options.target ? { target: options.target, outfile: options.outfile } : { outfile: options.outfile },
+  });
+  if (!result.success) {
+    for (const log of result.logs) {
+      console.error(log);
+    }
+    throw new Error("Binary build failed");
+  }
+  if (process.platform !== "win32" && !options.target?.startsWith("bun-windows")) {
+    chmodSync(options.outfile, 0o755);
+  }
+}

package/src/build/index.ts

@@ -0,0 +1 @@
+export * from "./build-binary";

package/src/contracts/index.ts

@@ -0,0 +1,86 @@
+export type LogLevelName = "trace" | "debug" | "info" | "warn" | "error";
+
+export type ThemePreference = "system" | "light" | "dark";
+
+export interface PasskeyAuthStatusResponse {
+  enabled: boolean;
+  passkeyConfigured: boolean;
+  passkeyDisabled: boolean;
+  passkeyRequired: boolean;
+  authenticated: boolean;
+}
+
+export interface ApiKeySummary {
+  id: string;
+  name: string;
+  prefix: string;
+  scopes: string[];
+  createdAt: string;
+  lastUsedAt?: string;
+  expiresAt?: string;
+}
+
+export interface CreatedApiKeyResponse {
+  key: ApiKeySummary;
+  token: string;
+}
+
+export interface DeviceAuthorizationResponse {
+  device_code: string;
+  user_code: string;
+  verification_uri: string;
+  verification_uri_complete: string;
+  expires_in: number;
+  interval: number;
+}
+
+export interface DeviceVerificationDetails {
+  userCode: string;
+  clientId: string;
+  scope: string;
+  status: "pending" | "approved" | "denied" | "consumed" | "expired";
+  expiresAt: string;
+  passkeyRequired: boolean;
+}
+
+export interface TokenResponse {
+  access_token: string;
+  refresh_token: string;
+  token_type: "Bearer";
+  expires_in: number;
+  scope: string;
+}
+
+export interface AuthSessionSummary {
+  id: string;
+  clientId: string;
+  scope: string;
+  createdAt: string;
+  updatedAt: string;
+  expiresAt: string;
+  lastUsedAt?: string;
+  revokedAt?: string;
+  active: boolean;
+}
+
+export interface WebAppConfigResponse {
+  appName: string;
+  version: string;
+  passkeyAuth: PasskeyAuthStatusResponse;
+  logLevel: {
+    level: LogLevelName;
+    fromEnv: boolean;
+  };
+  deviceAuth: {
+    enabled: boolean;
+  };
+  apiKeys: {
+    enabled: boolean;
+  };
+}
+
+export interface WebAppErrorResponse {
+  error: string;
+  message: string;
+  details?: unknown;
+}

package/src/server/auth/api-keys.ts

@@ -0,0 +1,61 @@
+import type { ApiKeySummary, CreatedApiKeyResponse } from "../../contracts";
+import type { WebAppStore } from "./store";
+import { nowIso, randomToken, sha256, secureEqual, isExpired } from "./crypto";
+import { AuthError } from "./types";
+
+function summarize(record: { tokenHash?: string } & ApiKeySummary): ApiKeySummary {
+  return {
+    id: record.id,
+    name: record.name,
+    prefix: record.prefix,
+    scopes: record.scopes,
+    createdAt: record.createdAt,
+    lastUsedAt: record.lastUsedAt,
+    expiresAt: record.expiresAt,
+  };
+}
+
+export function listApiKeys(store: WebAppStore): ApiKeySummary[] {
+  return store.listApiKeys().map(summarize);
+}
+
+export function createApiKey(store: WebAppStore, input: { name?: string; scopes?: string[]; prefix?: string; expiresAt?: string }): CreatedApiKeyResponse {
+  const prefix = input.prefix ?? "wapp";
+  const token = `${prefix}_${randomToken(32)}`;
+  const record = {
+    id: crypto.randomUUID(),
+    name: input.name?.trim() || "API key",
+    prefix,
+    tokenHash: sha256(token),
+    scopes: input.scopes?.length ? input.scopes : ["*"],
+    createdAt: nowIso(),
+    expiresAt: input.expiresAt,
+  };
+  store.saveApiKey(record);
+  return { key: summarize(record), token };
+}
+
+export function deleteApiKey(store: WebAppStore, id: string): boolean {
+  return store.deleteApiKey(id);
+}
+
+export function authenticateApiKey(store: WebAppStore, token: string): { apiKeyId: string; scopes: string[] } | undefined {
+  const tokenHash = sha256(token);
+  const record = store.getApiKeyByHash(tokenHash);
+  if (!record || !secureEqual(record.tokenHash, tokenHash) || (record.expiresAt && isExpired(record.expiresAt))) {
+    return undefined;
+  }
+  store.touchApiKey(record.id, nowIso());
+  return { apiKeyId: record.id, scopes: record.scopes };
+}
+
+export function assertScopes(actual: string[], required: string[]): void {
+  if (required.length === 0 || actual.includes("*")) {
+    return;
+  }
+  for (const scope of required) {
+    if (!actual.includes(scope)) {
+      throw new AuthError("insufficient_scope", `Missing required scope: ${scope}`, 403);
+    }
+  }
+}

package/src/server/auth/crypto.ts

@@ -0,0 +1,34 @@
+import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+
+export function randomToken(bytes = 32): string {
+  return randomBytes(bytes).toString("base64url");
+}
+
+export function sha256(value: string): string {
+  return createHash("sha256").update(value, "utf8").digest("base64url");
+}
+
+export function hmacSha256(value: string, secret: string): string {
+  return createHmac("sha256", secret).update(value, "utf8").digest("base64url");
+}
+
+export function secureEqual(left: string, right: string): boolean {
+  const leftBuffer = Buffer.from(left);
+  const rightBuffer = Buffer.from(right);
+  if (leftBuffer.length !== rightBuffer.length) {
+    return false;
+  }
+  return timingSafeEqual(leftBuffer, rightBuffer);
+}
+
+export function nowIso(): string {
+  return new Date().toISOString();
+}
+
+export function addSeconds(seconds: number): string {
+  return new Date(Date.now() + seconds * 1000).toISOString();
+}
+
+export function isExpired(iso: string): boolean {
+  return new Date(iso).getTime() <= Date.now();
+}