@omerdlw/base-framework 1.0.0 → 1.0.1

package/docs/modules/result.md

@@ -0,0 +1,135 @@
+# Result — `@omerdlw/base-framework/result`
+
+> **Read this first if you need to:** write a Server Action (or any function that crosses the network), handle success/failure without `try/catch`, validate input in one place, or understand how failures reach the user.
+
+## 1. At a glance
+
+|                 |                                                                                                                                                                   |
+| :-------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Import**      | `import { ok, err, type Result, createSafeAction } from "@omerdlw/base-framework/result"`                                                                                          |
+| **Layer**       | `src/core` foundation. **Server-safe**: no React, no `next/*`; imports only `@omerdlw/base-framework/utils` (`UserError`, `toUserMessage`, `report`).                              |
+| **Enforced by** | [Rule 6](../architecture-and-rules.md#rule-6-result-pattern-returns): Server Actions (`"use server"`) must return `Result<T, E>`. Never throw across the network. |
+| **Tests**       | `tests/core/result.test.ts`                                                                                                                                       |
+
+## 2. Why
+
+Next.js serializes thrown errors poorly and strips their details in production. A returned `Result` arrives intact and forces the caller to handle both branches:
+
+```ts
+type Result<T, E = string> =
+  | { success: true; data: T; code?: string }
+  | { success: false; error: E; code?: string };
+```
+
+`data` exists only on success and `error` only on failure (`never` on the other branch), so TypeScript narrows on `result.success`.
+
+## 3. Quick start
+
+```ts
+"use server";
+import { ok, err, type Result } from "@omerdlw/base-framework/result";
+import { UserError, toUserMessage } from "@omerdlw/base-framework/utils";
+import { createServerSupabaseClient } from "@/infrastructure/supabase/server";
+
+export async function renameProjectAction(
+  id: string,
+  name: string,
+): Promise<Result<{ id: string }>> {
+  if (!name.trim()) return err("Name is required", "VALIDATION");
+  try {
+    const supabase = await createServerSupabaseClient();
+    const { error } = await supabase
+      .from("projects")
+      .update({ name })
+      .eq("id", id);
+    if (error) throw new UserError("Couldn't rename this project"); // shown as written
+    return ok({ id });
+  } catch (e) {
+    return err(toUserMessage(e, { fallback: "Couldn't rename this project" })); // never e.message
+  }
+}
+```
+
+```ts
+// Same guarantees, less boilerplate
+export const renameProject = createSafeAction(
+  async (input: { id: string; name: string }) => updateProject(input), // may throw; may return a Result or a plain value
+  { schema: RenameSchema, errorCode: "RENAME_FAILED" },
+);
+```
+
+```tsx
+// Client: branch explicitly, or let toast.fromResult handle feedback
+const result = await renameProjectAction(id, name);
+if (isErr(result)) return; // result.error is user-safe text
+toast.fromResult(result, { success: "Project renamed successfully!" }); // see notification.md
+```
+
+## 4. API
+
+| Export                                                        | Signature                                    | Description                                                                                                                                          |
+| :------------------------------------------------------------ | :------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Result<T, E = string>`, `SuccessResult<T>`, `ErrorResult<E>` | types                                        | `readonly` fields; both carry an optional `code`.                                                                                                    |
+| `ok(data, code?)`                                             | `→ SuccessResult<T>`                         | `code` is included only when given.                                                                                                                  |
+| `err(error, code?)`                                           | `→ ErrorResult<E>`                           |                                                                                                                                                      |
+| `isResult(value)`                                             | `(unknown) → value is Result`                | True for objects with a boolean `success` **and** a matching `data` (success) / `error` (failure) key. Used by `toast.promise` and `toast.fromResult`.  |
+| `isOk(r)`, `isErr(r)`                                         | type guards                                  |                                                                                                                                                      |
+| `unwrap(r)`                                                   | `→ T`                                        | Returns `data`, or **throws** (the error itself if it is an `Error`, otherwise `new Error(String(error))`). Trusted internal code only.              |
+| `unwrapOr(r, fallback)`                                       | `→ T`                                        | `data` or the fallback.                                                                                                                              |
+| `map(r, fn)`, `mapErr(r, fn)`                                 | `→ Result`                                   | Transform one branch; `code` is preserved.                                                                                                           |
+| `match(r, { ok, err })`                                       | `→ R`                                        | Branch handling returning a value.                                                                                                                   |
+| `tryCatch(promiseOrFn, mapError?)`                            | `→ Promise<Result<T, E>>`                    | Awaits a promise (or an async function); thrown/rejected → `err(...)`.                                                                               |
+| `createSafeAction(handler, options?)`                         | `→ (...args) => Promise<Result<TOutput, E>>` | See below.                                                                                                                                           |
+
+### 4.1 How thrown errors become messages
+
+`tryCatch` and `createSafeAction` convert a caught error with `mapError(error)` if you pass one, otherwise `toUserMessage(error)`:
+
+- a `UserError`, a string, or a 4xx payload from our own API is used **as written**;
+- anything else maps to a fixed sentence from `USER_MESSAGES` (`generic`, `network`, `timeout`, `unauthorized`, `forbidden`, `notFound`, `rateLimited`, `server`) so database/SDK wording never reaches the UI;
+- unless it is a `UserError`, the original error is **reported** via `report("Result", error)` (see [error-boundary.md](./error-boundary.md#7-user-facing-messages-and-report)).
+
+### 4.2 `createSafeAction(handler, options)`
+
+| Option              | Meaning                                                                                                                                                                                                                     |
+| :------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `schema`            | Anything with `safeParse(input)` (e.g. Zod). Applied to the **first argument**; on success the parsed value replaces it. Failure → `err(firstIssueMessage \| message \| "Invalid input", errorCode ?? "VALIDATION_ERROR")`. |
+| `validate(...args)` | Extra synchronous check on the (parsed) args. Return an `ErrorResult` to fail with it, `false` → `"Validation failed"`, a non-empty string → that message, anything else passes.                                            |
+| `mapError(error)`   | Maps both validation messages and thrown errors to your error type `E`.                                                                                                                                                     |
+| `errorCode`         | `code` set on failures (validation default: `"VALIDATION_ERROR"`).                                                                                                                                                          |
+
+The handler may return a `Result` (returned as is), or a plain value (wrapped in `ok(value)`), or throw (→ `err`). The wrapper itself never throws.
+
+## 5. Where Results flow
+
+| Consumer                             | Behaviour                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| :----------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `toast.fromResult` / `toast.promise` | Toasts `success(data)` or `error` (falling back to `toUserMessage`).                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| Notification module                  | Shows `APP_ERROR` / `STATE_CHANGE` events that have `notify: true`.                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| Dock                                 | Shows **every** `APP_ERROR` as its error status card (regardless of `notify`).                                                                                                                                                                                                                                                                                                                                                                                                          |
+
+So a failed `useServerAction` produces a dock error card, plus a toast if you passed `toast: true`.
+
+## 6. Recipes and gotchas
+
+| I want to…                   | Do this                                                                                               |
+| :--------------------------- | :---------------------------------------------------------------------------------------------------- |
+| Return a validation error    | `return err("Name is required", "VALIDATION")`.                                                       |
+| Show server text to the user | Throw `new UserError("…")` (or return `err("…")`) with text you wrote; never forward `error.message`. |
+| Custom error shape           | `Result<T, MyError>` and pass `mapError` to `createSafeAction` / `tryCatch`.                          |
+| Narrow in TypeScript         | `if (r.success) r.data else r.error`, or `isOk` / `isErr`.                                            |
+| Chain transformations        | `map(r, fn)` / `mapErr(r, fn)`.                                                                       |
+
+- A Server Action must return plain serializable data: do not put `Error` instances, class instances or functions in a `Result` that crosses the network.
+- `unwrap` throws: never use it in a `"use server"` function's return path.
+- `createSafeAction`'s `schema` validates only the **first** argument.
+- `isResult` requires the matching data/error key: `{ success: true }` without `data` is **not** a Result (use `ok(undefined)`).
+
+## 7. File map
+
+A single file, `src/core/result.ts`. It depends only on `./utils/user-message` and `./utils/report`, so it is safe on both server and client (and is one of the server-safe core entries that must not import React or `next/*`).
+
+## 8. Dependencies
+
+- **Uses:** `@omerdlw/base-framework/utils` (`UserError`, `toUserMessage`, `report`) only.
+- **Used by:** every `server/actions.ts` in `src/features/**`, `@omerdlw/base-framework/hooks` (`useServerAction`, `useAsyncAction`), `@omerdlw/base-framework/modules/notification` (`isResult` for `toast.fromResult` / `promise`), and route-level helpers that return `Result`.

package/docs/testing.md

@@ -0,0 +1,160 @@
+# Testing Guide
+
+> **Read this first if you need to:** run package tests, understand the test harness (`happy-dom`, `renderHook`, `Themed`), write tests for new modules, or test downstream components that consume `@omerdlw/base-framework`.
+>
+> **Stack:** Node's built-in test runner (`node:test`) + `node:assert/strict`, TypeScript executed directly through a resolver hook (`register.mjs`), `happy-dom` for React components and hooks, zero external framework overhead.
+
+---
+
+## 1. Running Tests
+
+| Command | Purpose |
+| :--- | :--- |
+| `npm test` | Runs the full 520+ test suite (`tests/**/*.test.ts`) in ~1 second. |
+| `npm run test:coverage` | Runs the suite with complete line, branch, and function coverage reporting for `src/**`. |
+| `npm run type-check` | Full TypeScript compiler validation (`tsc --noEmit`). |
+| `npm run check:architecture` | Static AST validation checking for 0 circular dependencies and verified `uses` peer declarations. |
+| `node --import ./tests/support/register.mjs --test tests/core/kernel.test.ts` | Run a single test file. |
+| `node --import ./tests/support/register.mjs --test --test-name-pattern="surface" tests/modules/dock.test.ts` | Run tests matching a specific pattern. |
+
+**Pre-flight Verification:**  
+`npm run type-check && npm run lint && npm run check:architecture && npm test && npm run build`
+
+---
+
+## 2. Test Suite Layout
+
+Tests mirror the package's architecture, **one TypeScript test file per unit**:
+
+```
+tests/
+  architecture.test.ts     Layer boundaries, module contracts, barrel exports, cyclical imports
+  core/                    Microkernel, error handling, hooks, atoms, tokens, utils, events, result, theme
+  modules/                 ambient, background, context-menu, controls, dock, loading, media, modal, notification
+  support/                 Test harness: happy-dom, render, themed wrapper, stubs (§3)
+  tsconfig.json            TypeScript compilation rules for tests
+```
+
+---
+
+## 3. Test Harness (`tests/support`)
+
+| File | Provides |
+| :--- | :--- |
+| `register.mjs` | Node module loader hook: resolves `@omerdlw/base-framework` imports on the fly and transpiles TypeScript. |
+| `dom.ts` | Configures a **`happy-dom`** browser environment (`window`, `document`, `matchMedia`, observers) for React component and hook testing. |
+| `render.ts` | React 19 testing primitives: `render(element)`, `renderHook(hook, { wrapper })`, `flush()`. Automatically unmounts trees after every test to prevent leaks. |
+| `themes.ts` | `Themed` (`ThemeProvider` loaded with test themes) and `withThemes()`. Required when testing any module view or atom that consumes theme slots. |
+| `registry.ts` | Test registry with `builtInModules` for microkernel and module integration testing. |
+
+---
+
+## 4. Testing Patterns
+
+### 4.1 Testing Pure Utils & Math
+
+Import the utility directly and assert deterministic behavior:
+
+```ts
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { clamp, toFiniteNumber } from "@omerdlw/base-framework/utils";
+
+describe("math utils", () => {
+  test("clamp restricts numbers within min and max boundaries", () => {
+    assert.equal(clamp(5, 0, 10), 5);
+    assert.equal(clamp(-5, 0, 10), 0);
+    assert.equal(clamp(15, 0, 10), 10);
+  });
+
+  test("toFiniteNumber handles non-numeric fallbacks", () => {
+    assert.equal(toFiniteNumber("123"), 123);
+    assert.equal(toFiniteNumber(NaN, 0), 0);
+  });
+});
+```
+
+### 4.2 Testing Hooks & Subscriptions
+
+Render hooks inside `Themed` or `CoreProvider` using `renderHook`:
+
+```ts
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { renderHook } from "../support/render.ts";
+import { useGlobalEvent } from "@omerdlw/base-framework/hooks";
+import { globalEvents, EVENT_TYPES } from "@omerdlw/base-framework/events";
+
+describe("useGlobalEvent", () => {
+  test("receives published event payloads", () => {
+    let received = null;
+    const { unmount } = renderHook(() => {
+      useGlobalEvent(EVENT_TYPES.STATE_CHANGE, (payload) => {
+        received = payload;
+      });
+    });
+
+    globalEvents.publish(EVENT_TYPES.STATE_CHANGE, { key: "auth", value: true });
+    assert.deepEqual(received, { key: "auth", value: true });
+
+    unmount();
+  });
+});
+```
+
+### 4.3 Testing Diagnostics & Error Reports
+
+Install an ephemeral report sink with `setReportSink` and release it in cleanup:
+
+```ts
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { report, setReportSink } from "@omerdlw/base-framework/utils";
+
+describe("error reporter", () => {
+  test("routes diagnostic messages to the configured sink", () => {
+    const logs: any[] = [];
+    const release = setReportSink((scope, err, level) => {
+      logs.push({ scope, err, level });
+    });
+
+    report("dock", new Error("Invalid surface state"), "warning");
+    release();
+
+    assert.equal(logs.length, 1);
+    assert.equal(logs[0].scope, "dock");
+    assert.equal(logs[0].level, "warning");
+  });
+});
+```
+
+---
+
+## 5. Testing Downstream Applications
+
+When testing Next.js components or pages that consume `@omerdlw/base-framework`:
+
+1. **Wrapping with `CoreProvider`:** Provide a test wrapper with the required modules:
+   ```tsx
+   import { CoreProvider } from "@omerdlw/base-framework/provider";
+   import { dockModule } from "@omerdlw/base-framework/modules/dock";
+   import { notificationModule } from "@omerdlw/base-framework/modules/notification";
+
+   export function TestProviders({ children }: { children: React.ReactNode }) {
+     return <CoreProvider modules={[dockModule, notificationModule]}>{children}</CoreProvider>;
+   }
+   ```
+2. **Testing Declarative Routes (`usePage`):** Since `usePage()` accepts a static or reactive configuration object, verify that components invoke `usePage()` with the expected metadata, loading flags, or dock card configs.
+3. **Asserting Server Action Results:** Verify that Server Actions return `Result<T, E>` (`ok()` or `err()`) rather than throwing raw unhandled exceptions.
+
+---
+
+## 6. What the Suite Protects
+
+| Layer | Enforced Invariants |
+| :--- | :--- |
+| **Architecture** | 0 circular dependencies, downward-only imports, clean barrel exports |
+| **Microkernel** | Registry ordering, topological provider nesting, `usePage` atomic reconciliation |
+| **Modules** | Dock flows/surfaces/guards/status, modal stack order, context-menu scoring, controls rails, notification queues, media sessions |
+| **Atoms** | Accessibility contracts (ARIA), keyboard navigation, deterministic `cn()` class merging |
+| **Tokens & Theme** | GPU-accelerated motion presets, OKLCH token boundaries, Z-index hierarchy |

package/docs/theming.md

@@ -0,0 +1,185 @@
+# Theming System Guide — `@omerdlw/base-framework/theme`
+
+> **Read this first if you need to:** customize the visual design of any first-party module (`dock`, `modal`, `notification`, etc.), supply custom Tailwind styles, or understand the theme slot contract.
+
+---
+
+## 1. Philosophy: Logic Decoupled from Aesthetics
+
+`@omerdlw/base-framework` enforces a strict rule: **Modules own interaction mechanics, accessibility, and state machines; consumer applications own visual design.**
+
+Modules ship with **zero hardcoded visual Tailwind colors or aesthetic choices**. Instead, each module declares a typed **Theme Spec** defining required "slots" (e.g. `card`, `backdrop`, `header`, `item`).
+
+If a required theme is not provided to `<ThemeProvider>`, `useTheme()` throws an informative error at mount time:
+```
+Theme "dock" is missing. Add its theme configuration to your ThemeProvider.
+```
+
+---
+
+## 2. The Theme API
+
+Import the theming primitives from `@omerdlw/base-framework/theme`:
+
+```ts
+import {
+  defineThemeSpec,
+  defineTheme,
+  ThemeProvider,
+  useTheme,
+  type ThemeSpec,
+  type ThemeConfig,
+  type ThemeEntry,
+} from "@omerdlw/base-framework/theme";
+```
+
+### 2.1 `defineThemeSpec<Slots>(id)`
+Used by module authors to define the contract:
+```ts
+export type DockThemeSlot = "card" | "header" | "title" | "description" | "icon" | "surface";
+export const dockTheme = defineThemeSpec<DockThemeSlot>("dock");
+```
+
+### 2.2 `defineTheme(spec, { slots, styles? })`
+Used by application developers to implement the styling contract. TypeScript enforces that **every required slot** is provided:
+```ts
+export const dockThemeConfig = defineTheme(dockTheme, {
+  slots: {
+    card: "rounded-[28px] bg-neutral-900/80 backdrop-blur-xl border border-white/10 shadow-2xl p-4",
+    header: "flex items-center gap-3",
+    title: "text-sm font-medium text-white",
+    description: "text-xs text-white/50",
+    icon: "text-white/80",
+    surface: "rounded-3xl bg-neutral-900 border border-white/10 p-6",
+  },
+  styles: {
+    // Optional inline CSS styles (e.g. tokenized Z-Index)
+    card: { zIndex: 100 },
+  },
+});
+```
+
+### 2.3 `ThemeProvider({ themes, children })`
+Wraps your application or `CoreProvider` to supply the theme map:
+```tsx
+<ThemeProvider themes={[dockThemeConfig, modalThemeConfig, notificationThemeConfig]}>
+  <CoreProvider modules={modules}>
+    {children}
+  </CoreProvider>
+</ThemeProvider>
+```
+
+### 2.4 `useTheme(spec)`
+Consumed internally by module overlays to read the active slots:
+```tsx
+const { slots, styles } = useTheme(dockTheme);
+return <div className={slots.card} style={styles.card} />;
+```
+
+---
+
+## 3. Module Theme Slot Reference
+
+Below is the complete reference of theme specs exported by the 9 first-party modules:
+
+| Module | Spec Export | Import Path | Primary Slots |
+| :--- | :--- | :--- | :--- |
+| **Dock** | `dockTheme` | `@omerdlw/base-framework/modules/dock` | `card`, `header`, `title`, `description`, `icon`, `surface`, `status` |
+| **Modal** | `modalTheme` | `@omerdlw/base-framework/modules/modal` | `backdrop`, `dialog`, `header`, `title`, `body`, `footer`, `close` |
+| **Notification** | `notificationTheme` | `@omerdlw/base-framework/modules/notification` | `viewport`, `toast`, `title`, `description`, `icon`, `action`, `close` |
+| **Ambient** | `ambientTheme` | `@omerdlw/base-framework/modules/ambient` | `container`, `canvas` |
+| **Background** | `backgroundTheme` | `@omerdlw/base-framework/modules/background` | `layer`, `overlay`, `fades` |
+| **Controls** | `controlsTheme` | `@omerdlw/base-framework/modules/controls` | `rail`, `button`, `icon` |
+| **Loading** | `loadingTheme` | `@omerdlw/base-framework/modules/loading` | `overlay`, `spinner`, `message` |
+| **Context Menu** | `contextMenuTheme` | `@omerdlw/base-framework/modules/context-menu` | `menu`, `item`, `separator`, `label`, `shortcut` |
+| **Error Boundary** | `errorTheme` | `@omerdlw/base-framework/error` | `boundary`, `card`, `title`, `message`, `retryButton` |
+
+---
+
+## 4. Complete Starter Theme Configuration
+
+Create a theme definitions file in your project (e.g. `src/config/themes.ts`):
+
+```ts
+import { defineTheme } from "@omerdlw/base-framework/theme";
+import { dockTheme } from "@omerdlw/base-framework/modules/dock";
+import { modalTheme } from "@omerdlw/base-framework/modules/modal";
+import { notificationTheme } from "@omerdlw/base-framework/modules/notification";
+import { loadingTheme } from "@omerdlw/base-framework/modules/loading";
+import { errorTheme } from "@omerdlw/base-framework/error";
+
+export const appThemes = [
+  defineTheme(dockTheme, {
+    slots: {
+      card: "rounded-[24px] bg-neutral-900/90 backdrop-blur-2xl border border-white/10 shadow-2xl p-4 text-white",
+      header: "flex items-center gap-3",
+      title: "text-sm font-semibold tracking-tight",
+      description: "text-xs text-white/50",
+      icon: "text-white/80",
+      surface: "rounded-3xl bg-neutral-900/95 border border-white/10 p-6 backdrop-blur-3xl",
+      status: "rounded-xl bg-white/5 px-3 py-1.5 text-xs text-white/70",
+    },
+  }),
+
+  defineTheme(modalTheme, {
+    slots: {
+      backdrop: "fixed inset-0 bg-black/60 backdrop-blur-sm",
+      dialog: "rounded-2xl bg-neutral-900 border border-white/10 shadow-2xl p-6 text-white max-w-lg w-full",
+      header: "mb-4",
+      title: "text-lg font-bold",
+      body: "text-sm text-white/80",
+      footer: "mt-6 flex justify-end gap-3",
+      close: "size-8 center rounded-full hover:bg-white/10 text-white/60 hover:text-white",
+    },
+  }),
+
+  defineTheme(notificationTheme, {
+    slots: {
+      viewport: "fixed bottom-6 right-6 flex flex-col gap-2 z-50 pointer-events-none",
+      toast: "pointer-events-auto flex items-center gap-3 rounded-xl bg-neutral-900 border border-white/10 shadow-xl px-4 py-3 text-sm text-white",
+      title: "font-medium text-white",
+      description: "text-xs text-white/60",
+      icon: "shrink-0",
+      action: "text-xs font-semibold text-sky-400 hover:text-sky-300",
+      close: "text-white/40 hover:text-white",
+    },
+  }),
+
+  defineTheme(loadingTheme, {
+    slots: {
+      overlay: "center fixed inset-0 h-screen w-screen bg-black/40 backdrop-blur-xs",
+      spinner: "animate-spin text-white/80",
+      message: "text-xs font-medium text-white/60 mt-3",
+    },
+  }),
+
+  defineTheme(errorTheme, {
+    slots: {
+      boundary: "center min-h-[300px] w-full p-6",
+      card: "rounded-2xl bg-red-950/20 border border-red-500/20 p-6 max-w-md text-center",
+      title: "text-base font-semibold text-red-400",
+      message: "text-xs text-red-200/70 mt-2",
+      retryButton: "mt-4 inline-flex h-8 items-center px-3 rounded-lg bg-red-500/20 text-red-300 text-xs font-medium hover:bg-red-500/30",
+    },
+  }),
+];
+```
+
+Then in `src/app/providers.tsx`:
+
+```tsx
+"use client";
+
+import { ThemeProvider } from "@omerdlw/base-framework/theme";
+import { CoreProvider } from "@omerdlw/base-framework/provider";
+import { appThemes } from "@/config/themes";
+import { modules } from "@/config/modules";
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <ThemeProvider themes={appThemes}>
+      <CoreProvider modules={modules}>{children}</CoreProvider>
+    </ThemeProvider>
+  );
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omerdlw/base-framework",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Microkernel engine and first-party declarative UI modules for app-like Next.js products.",
   "type": "module",
   "main": "./dist/index.js",
@@ -74,6 +74,8 @@
   },
   "files": [
     "dist",
+    "docs",
+    "templates",
     "README.md",
     "LICENSE"
   ],

package/templates/AGENTS.md

@@ -0,0 +1,165 @@
+# Base Framework — AI Agent & Developer Mastery Guide
+
+> **This project is powered by `@omerdlw/base-framework`.**  
+> Read this file first before reading or modifying any code. It contains the exact architectural boundaries, rules, patterns, and code recipes you must follow without exception.
+
+---
+
+## 1. Quick Tech Stack & Foundations
+
+- **Engine:** Next.js 16 (App Router), React 19
+- **Core Framework:** `@omerdlw/base-framework` (Microkernel & Declarative UI Modules)
+- **Styling:** Tailwind CSS v4 (`@theme`, OKLCH semantic color tokens, `.center`, `.skeleton-block`)
+- **Motion:** Motion (v13) with hardware GPU acceleration (`translate3d`, `scale`)
+- **Icons:** `@iconify-icon/react` via `<Icon icon="solar:..." />`
+
+---
+
+## 2. The 4-Layer Architectural Hierarchy
+
+Code in this project strictly follows a four-layer dependency hierarchy:
+
+```
+Layer 4: src/app (Routing, Next.js page composition & layout orchestration)
+   ↓ imports
+Layer 3: src/features (Domain capabilities: auth, account, social, checkout)
+   ↓ imports
+Layer 2: src/infrastructure (Adapters: database, HTTP client, proxy, rate limiting)
+   ↓ imports
+Layer 1: @omerdlw/base-framework (Microkernel, first-party modules, atoms, tokens, result)
+```
+
+### Strict Architectural Boundaries:
+- `src/features/*` must **never** import from `src/app/*`.
+- `src/infrastructure/*` must **never** import from `src/features/*` or `src/app/*`.
+- Every feature in `src/features/` **must** have an `index.ts` barrel export.
+- Server database and adapter files **must** begin with `import "server-only";`.
+- Server Actions **must** begin with `"use server";` and return `Result<T, E>` (`ok()` or `err()`).
+
+---
+
+## 3. The 5 Golden Rules of Base Framework
+
+### Rule 1: Declarative Chrome (`usePage`)
+**Never** build custom top navigation bars, ad-hoc sticky headers, or scattered floating buttons.  
+All route-level visual state (title, dock card, loading state, background, modals) **must** be declared using `usePage()` from `@omerdlw/base-framework/kernel`:
+
+```tsx
+"use client";
+
+import { usePage } from "@omerdlw/base-framework/kernel";
+
+export default function MyPage() {
+  const page = usePage({
+    title: "Dashboard",
+    dock: {
+      description: "Project metrics and activity",
+      icon: "solar:widget-bold",
+    },
+    loading: false,
+  });
+
+  return <main>...</main>;
+}
+```
+
+### Rule 2: Result Pattern for All Async Operations
+Never return raw unchecked errors or throw unhandled exceptions from server actions or infrastructure operations. Always wrap return values with `Result<T, E>` from `@omerdlw/base-framework/result`:
+
+```tsx
+"use server";
+
+import "server-only";
+import { ok, err, type Result } from "@omerdlw/base-framework/result";
+
+export async function updateProfile(username: string): Promise<Result<{ id: string }, string>> {
+  if (!username) return err("Username is required");
+  // Save to DB...
+  return ok({ id: "user_123" });
+}
+```
+
+### Rule 3: Bridge Server Actions to Feedback with `toast.fromResult`
+When consuming Server Actions in the UI, do not write manual `try/catch` and `if (res.error)` blocks. Use `toast.fromResult()`:
+
+```tsx
+"use client";
+
+import { useToast } from "@omerdlw/base-framework/modules/notification";
+import { updateProfile } from "@/features/account/actions";
+
+export function ProfileForm() {
+  const { toast } = useToast();
+
+  const handleSubmit = async (name: string) => {
+    const result = await updateProfile(name);
+    toast.fromResult(result, {
+      success: "Profile updated successfully!",
+    });
+  };
+
+  return <form>...</form>;
+}
+```
+
+### Rule 4: Subpath Imports Only
+Always import from the exact subpaths exposed by `@omerdlw/base-framework`:
+
+| What you need | Where to import it |
+| :--- | :--- |
+| `usePage`, `defineModule` | `@omerdlw/base-framework/kernel` |
+| `CoreProvider` | `@omerdlw/base-framework/provider` |
+| `ok`, `err`, `isResult`, `type Result` | `@omerdlw/base-framework/result` |
+| `globalEvents`, `EVENT_TYPES` | `@omerdlw/base-framework/events` |
+| `useToast` | `@omerdlw/base-framework/modules/notification` |
+| `useDockActions`, `useDockStatus` | `@omerdlw/base-framework/modules/dock` |
+| `useModal`, `useModalContext` | `@omerdlw/base-framework/modules/modal` |
+| `useAmbientTheme` | `@omerdlw/base-framework/modules/ambient` |
+| `cn`, `report`, `createStore` | `@omerdlw/base-framework/utils` |
+| `useClickOutside`, `useGlobalEvent` | `@omerdlw/base-framework/hooks` |
+| `Button`, `Icon`, `Spinner`, `Tooltip` | `@omerdlw/base-framework/atoms` |
+
+### Rule 5: Modals and Surfaces Must Be Declared or Scoped
+Do not create floating unmanaged `fixed z-50` dialog div wrappers.
+- For sheets/drawers sliding up from the dock: use `useDockActions().openSurface(...)`.
+- For standard dialogs: register them in `usePage({ modal: { ... } })` or trigger with `useModal().openModal(...)`.
+
+---
+
+## 4. Standard Next.js Root Layout Recipe
+
+In `src/app/providers.tsx`:
+
+```tsx
+"use client";
+
+import { CoreProvider } from "@omerdlw/base-framework/provider";
+import { dockModule } from "@omerdlw/base-framework/modules/dock";
+import { modalModule } from "@omerdlw/base-framework/modules/modal";
+import { notificationModule } from "@omerdlw/base-framework/modules/notification";
+import { ambientModule } from "@omerdlw/base-framework/modules/ambient";
+import { backgroundModule } from "@omerdlw/base-framework/modules/background";
+import { controlsModule } from "@omerdlw/base-framework/modules/controls";
+import { loadingModule } from "@omerdlw/base-framework/modules/loading";
+
+const modules = [
+  dockModule,
+  modalModule,
+  notificationModule,
+  ambientModule,
+  backgroundModule,
+  controlsModule,
+  loadingModule,
+];
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return <CoreProvider modules={modules}>{children}</CoreProvider>;
+}
+```
+
+In `src/app/globals.css`:
+
+```css
+@import "tailwindcss";
+@source "../node_modules/@omerdlw/base-framework";
+```