@portel/photon 1.9.0 → 1.11.0

package/README.md

@@ -3,9 +3,7 @@
 
 <img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/photon-logo.png" alt="Photon" width="500">
 
-**Simplify the creation of CLI tools, MCP servers, and web applications.**
-
-A framework, runtime, and ecosystem. Batteries included.
+**Software for humans and AI. Written once.**
 
 [![npm version](https://img.shields.io/npm/v/@portel/photon?color=cb3837&label=npm)](https://www.npmjs.com/package/@portel/photon)
 [![npm downloads](https://img.shields.io/npm/dm/@portel/photon?color=cb3837)](https://www.npmjs.com/package/@portel/photon)
@@ -14,140 +12,146 @@ A framework, runtime, and ecosystem. Batteries included.
 [![Node](https://img.shields.io/badge/node-%3E%3D18-43853d.svg)](https://nodejs.org)
 [![MCP](https://img.shields.io/badge/MCP-compatible-7c3aed.svg)](https://modelcontextprotocol.io)
 
-[Quick Start](#quick-start) · [Why Photon](#why-did-we-build-this) · [Beam UI](#beam) · [How It Works](#how-it-works) · [Docs](#documentation)
-
-[![Watch: Why Photon? (2 min)](https://img.youtube.com/vi/FI0M8s6ZKv4/maxresdefault.jpg)](https://www.youtube.com/watch?v=FI0M8s6ZKv4)
-
 </div>
 
 ---
 
-## What Is This Thing?
-
-So, here is the situation. You write a single TypeScript file. Just one. And somehow, through some dark magic I don't fully understand either, you get three things at once:
+Your tools have two kinds of consumers now. Humans who open a dashboard and explore. AI agents that call your methods through a protocol. Until now, you've been building for one or the other, or building everything twice.
 
-1.  **An MCP server** (so Claude or Cursor can use your tools).
-2.  **A CLI tool** (so you can run it from the terminal like a normal human).
-3.  **A web application** (a visual dashboard called "Beam" that makes forms for you).
+Photon is built around a different premise: **write what you mean, and let both consumers figure it out from that**.
 
-It looks like this:
+You write a TypeScript class. Methods are your capabilities. Types describe what's valid. Comments explain the intent. That's it. Photon reads all of it and generates a web UI for human exploration, a CLI for scripting, and an MCP server for AI agents. Same logic. Same validation. Same data. Three interfaces from one file.
 
 ```
-  analytics.photon.ts  →  MCP Server  |  CLI Tool  |  Web UI
+analytics.photon.ts  →  Web UI (Beam)  ·  CLI  ·  MCP Server for AI
 ```
 
-You just write the logic. Photon deals with the protocols, schemas, and the boring stuff that usually makes you question your life choices.
+The code stays simple, almost embarrassingly simple, because the complexity isn't in what you write. It's in what Photon derives from it.
 
-### Who Is This For?
+<div align="center">
 
-*   **Developers** who want to give AI access to their database but are too lazy to write a full server.
-*   **Teams** who want to share tools without emailing zip files.
-*   **Anyone** who wants a CLI and a web UI without writing the boilerplate.
+<a href="https://www.youtube.com/watch?v=FI0M8s6ZKv4">
+  <img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/video-preview.png" alt="Watch: Why Photon? (2 min)" width="100%">
+</a>
 
-You don't need to know what "MCP" actually stands for. If you can write a TypeScript class, you are qualified.
+</div>
 
 ---
 
-## Why did we build this?
+## Quick Start
 
-Three reasons, if you want the short version. ([Read the longer version](./WHY-PHOTON.md))
+```bash
+npm install -g @portel/photon
+photon maker new my-tool      # Create a photon
+photon                        # Open Beam, the web UI
+```
 
-**MCP is personal.** The best MCP is the one built for exactly one use case. Yours. Your team's. Your company's. When you stop building for everyone, the code gets absurdly simple. One file. Twelve lines. Not twelve hundred.
+Or without installing:
 
-**Solve once, run forever.** If an LLM figured out your workflow the first time, why ask it to re-derive the same answer from scratch every time? Photon lets you keep the answer. No middleman, no tokens, no latency.
+```bash
+npx @portel/photon maker new my-tool
+npx @portel/photon
+```
 
-**Same door, every key.** AI calls it through MCP. You call it through CLI. You open it in Beam. Same methods, same data, same result. And half the time, you don't need AI at all. You just need the data.
+> Requires [Node.js 18+](https://nodejs.org). TypeScript is compiled internally; no `tsconfig.json` needed.
 
 ---
 
-## Quick Start
+## What You Actually Write
 
-If you are the type who likes to just run commands and see what happens:
+Here is a complete, working photon:
 
-```bash
-npm install -g @portel/photon
-photon maker new my-tool       # Makes a new photon
-photon                         # Opens the Beam UI
+```typescript
+export default class Analytics {
+  async report(params: { period: string }) {
+    return await db.query(`SELECT * FROM events WHERE period = $1`, [params.period]);
+  }
+}
 ```
 
-Or if you don't want to install anything (I get it):
+From this, Photon generates:
+- A web form in Beam with a `period` text input
+- `photon cli analytics report --period 2024-Q4`
+- An MCP tool that Claude or Cursor can invoke
 
-```bash
-npx @portel/photon maker new my-tool
-npx @portel/photon
-```
+No decorators. No registration. No server boilerplate. You wrote the logic. Photon derived the rest.
 
-> **Note:** You need [Node.js 18+](https://nodejs.org). Also, TypeScript helps, but Photon handles the compiling, so you don't have to fight with `tsconfig.json`.
+The more you express, the more Photon understands.
 
 ---
 
-## Beam
+## Everything You Add Becomes Something Useful
+
+Photon reads your TypeScript as **intent**. Every construct you'd write anyway carries meaning it can act on.
 
-Beam is the dashboard. It's where you go to poke your tools and see if they work before you let an AI loose on them.
+| What you write | What Photon derives |
+|---|---|
+| Method signatures | Tool definitions: names, inputs, outputs |
+| Type annotations | Input validation rules, UI field types |
+| JSDoc comments | Documentation for AI clients and human users |
+| Constructor parameters | Config UI, environment variable mapping |
+| `@tags` | Validation, formatting, scheduling, webhooks |
 
-Run `photon`. That's it.
+So when you add a `@param city {@pattern ^[a-zA-Z\s]+$}` annotation you were going to write anyway, Beam automatically validates it in the form, the CLI validates it before running, and the MCP schema enforces it for the AI. One annotation. Three consumers.
 
 <div align="center">
-<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/beam-dashboard.png" alt="Beam Dashboard" width="100%">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/photon-ecosystem.png" alt="Photon: one file, three surfaces" width="100%">
 </div>
 
 ---
 
-## Connecting to AI
+## Beam: Human Exploration
+
+Beam is the web dashboard. Every photon becomes an interactive form. Run `photon`. That's the whole command.
 
-If you want to use this with Claude or Cursor, you need the config.
+<div align="center">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/beam-dashboard.png" alt="Beam Dashboard" width="100%">
+</div>
+
+The UI is **fully auto-generated** from your method signatures: field types, validation, defaults, layouts. You never write frontend code. When you add a `{@choice a,b,c}` tag to a parameter, Beam renders a dropdown. When you mark a string as `{@format email}`, the field validates email format. The UI evolves as your code does.
+
+When forms aren't the right interface for what you're building, you can replace Beam's auto-generated view with your own HTML. The custom UI receives tool results via `window.photon.onResult()`, a thin bridge with no framework required.
+
+> Custom UIs follow the [MCP Apps Extension (SEP-1865)](https://github.com/nicolo-ribaudo/modelcontextprotocol/blob/nicolo/sep-1865/docs/specification/draft/extensions/apps.mdx) standard and work across compatible hosts. See the [Custom UI Guide](./docs/guides/CUSTOM-UI.md).
+
+---
+
+## AI Agents: Machine Invocation
 
 ```bash
-photon info weather --mcp
+photon info analytics --mcp
 ```
 
-It spits out some JSON:
-
 ```json
 {
   "mcpServers": {
-    "weather": {
+    "analytics": {
       "command": "photon",
-      "args": ["mcp", "weather"]
+      "args": ["mcp", "analytics"]
     }
   }
 }
 ```
 
-Copy that. Paste it into your AI client's config file. Done.
+Paste into your AI client's config. Your photon is now an MCP server. Claude can call your methods. Cursor can call your methods. Any MCP-compatible host can call your methods.
 
-Works with [Claude Desktop](https://claude.ai/download), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Cursor](https://cursor.com), and any [MCP-compatible client](https://modelcontextprotocol.io).
+The AI sees the same thing a human sees in Beam: the method names, the parameter descriptions from your JSDoc, the validation rules from your types. The JSDoc comment you wrote to document the tool for yourself is what Claude reads to decide when and how to call it.
 
----
-
-## Marketplace
+The MCP tools themselves work with [Claude Desktop](https://claude.ai/download), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Cursor](https://cursor.com), and any MCP-compatible client.
 
-We also have a marketplace. 35 photons and counting.
+When your photon has a custom UI, clients that support the [MCP Apps Extension](https://github.com/nicolo-ribaudo/modelcontextprotocol/blob/nicolo/sep-1865/docs/specification/draft/extensions/apps.mdx) render it natively, no separate app needed. The photon below is running inside Claude Desktop, same UI, same data as Beam.
 
 <div align="center">
-<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/beam-marketplace.png" alt="Marketplace" width="100%">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/claude-desktop.png" alt="Photon running as an MCP App with custom UI inside Claude Desktop" width="100%">
 </div>
 
-```bash
-photon search postgres
-photon add postgres
-```
-
-Browse the full catalog and documentation in the [official photons repository](https://github.com/portel-dev/photons).
-
-You can also make a private marketplace for your team, so internal tools stay off the public internet.
-
 ---
 
-## How It Works
+## The Progression
 
-A photon is just a TypeScript class. The **public methods become tools**. Photon reads your code, looks at the types, reads your comments, and then generates everything else.
+Here is how a photon grows. Each step adds one thing and gets multiple capabilities from it.
 
-I'll show you.
-
-### Step 1: The Bare Minimum
-
-Here is a class with one method. This is a valid photon.
+### Bare method: three interfaces from five lines
 
 ```typescript
 export default class Weather {
@@ -157,47 +161,34 @@ export default class Weather {
 }
 ```
 
-**What happens:** Beam sees this and makes a form with a text box labeled "city". You click a button, and it runs.
-
-**What you get:**
-*   `photon mcp weather` (The server for Claude)
-*   `photon cli weather forecast --city Paris` (The command line tool)
-*   `photon` (The web UI)
+A text input in Beam. A `--city` flag in the CLI. An MCP input schema. From five lines.
 
 <div align="center">
-<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-1.png" alt="Step 1 — Bare method in Beam" width="100%">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-1.png" alt="Step 1" width="100%">
 </div>
 
-### Step 2: Adding Descriptions
-
-If you add JSDoc comments, they show up as descriptions.
+### Add comments: AI understands your intent
 
 ```typescript
 /**
  * Weather - Check weather forecasts worldwide
- *
- * Provides current conditions.
  */
 export default class Weather {
   /**
-   * Get the weather forecast
+   * Get the weather forecast for a city
    * @param city City name (e.g., "London")
    */
-  async forecast(params: { city: string }) {
-    return `Weather for ${params.city}: Sunny, 72°F`;
-  }
+  async forecast(params: { city: string }) { ... }
 }
 ```
 
-**What happens:** Now the UI has helpful text. Also, the AI client reads this to understand what the tool does.
+The class description becomes how AI clients introduce the tool to users. The `@param` description is what the AI reads before deciding what value to pass. Same comments. Human help text and AI contract at once.
 
 <div align="center">
-<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-2.png" alt="Step 2 — JSDoc descriptions in Beam" width="100%">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-2.png" alt="Step 2" width="100%">
 </div>
 
-### Step 3: Configuration (The clever bit)
-
-If you need an API key, put it in the constructor.
+### Add a constructor: configuration appears
 
 ```typescript
 export default class Weather {
@@ -207,163 +198,137 @@ export default class Weather {
   ) {}
 
   async forecast(params: { city: string }) {
-    const res = await fetch(
-      `https://api.openweathermap.org/data/2.5/weather?q=${params.city}&appid=${this.apiKey}&units=${this.units}`
-    );
+    const res = await fetch(`...?appid=${this.apiKey}&units=${this.units}`);
     return await res.json();
   }
 }
 ```
 
-**What happens:** Beam creates a settings panel. `apiKey` becomes a password field. It also maps to environment variables like `WEATHER_API_KEY`. It just works.
+`apiKey` becomes a password field in the Beam settings panel and maps to the `WEATHER_API_KEY` environment variable. `units` gets a text input with `'metric'` pre-filled. You declared what you need. Photon built the configuration surface.
 
 <div align="center">
-<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-3.png" alt="Step 3 — Configuration panel in Beam" width="100%">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-3.png" alt="Step 3" width="100%">
 </div>
 
-### Step 4: Validation (Stop bad inputs)
-
-You can add tags to valid inputs.
+### Add tags: behavior extends across all surfaces
 
 ```typescript
 /**
- * Weather - Check weather forecasts worldwide
  * @dependencies node-fetch@^3.0.0
  */
 export default class Weather {
-  constructor(
-    private apiKey: string,
-    private units: string = 'metric'
-  ) {}
-
   /**
-   * Get the weather forecast for a city
    * @param city City name {@example London} {@pattern ^[a-zA-Z\s]+$}
    * @param days Number of days {@min 1} {@max 7}
    * @format table
    */
-  async forecast(params: { city: string; days?: number }) {
-    // fetch and return forecast data...
-  }
+  async forecast(params: { city: string; days?: number }) { ... }
 }
 ```
 
-**What happens:**
-*   The `city` input validates the regex.
-*   The `days` input becomes a number spinner (1-7).
-*   The result is formatted as a table.
-*   `@dependencies` makes Photon install `node-fetch` automatically. You don't even run `npm install`.
+`@dependencies` installs `node-fetch` automatically on first run, no `npm install` needed. The `{@pattern}` validates in the form, the CLI, and the MCP schema simultaneously. `days` becomes a number spinner with bounds. `@format table` renders the result as a table in Beam. One annotation, three surfaces.
 
-#### System CLI Dependencies
+<div align="center">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-4.png" alt="Step 4" width="100%">
+</div>
 
-If your photon wraps a command-line tool (e.g. `ffmpeg`, `git`, `docker`), declare it with `@cli`. Photon checks for the tool at load time and refuses to load if it's missing.
+### System CLI dependencies
+
+If your photon wraps a command-line tool, declare it and Photon enforces it at load time:
 
 ```typescript
 /**
- * Video processor
  * @cli ffmpeg - https://ffmpeg.org/download.html
- * @cli imagemagick - https://imagemagick.org/script/download.php
  */
 export default class VideoProcessor {
   async convert({ input, format }: { input: string; format: string }) {
-    // ffmpeg is guaranteed to exist if this method runs
+    // ffmpeg is guaranteed to exist when this runs
   }
 }
 ```
 
-If `ffmpeg` is not installed, the photon won't load and the user sees:
+<div align="center">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-5.png" alt="Step 5" width="100%">
+</div>
 
-```
-VideoProcessor requires the following CLI tools to be installed:
-  - ffmpeg: Install from https://ffmpeg.org/download.html
-```
+---
 
-> See the full [Tag Reference](./docs/reference/DOCBLOCK-TAGS.md) for all available tags. There are 30+ covering validation, UI hints, scheduling, webhooks, and more.
+## What Comes for Free
 
-<div align="center">
-<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-4.png" alt="Step 4 — Validation and formatting in Beam" width="100%">
-</div>
+Things you don't build because Photon handles them:
+
+| | |
+|---|---|
+| **Auto-UI** | Forms, field types, validation, layouts generated from your signatures |
+| **Stateful instances** | Multiple named instances of the same photon, each with isolated state |
+| **Persistent memory** | `this.memory` gives your photon per-instance key-value storage, no database needed |
+| **Scheduled execution** | `@scheduled` runs any method on a cron schedule |
+| **Webhooks** | `@webhook` exposes any method as an HTTP endpoint |
+| **OAuth** | Built-in OAuth 2.0 flows for Google, GitHub, Microsoft |
+| **Distributed locks** | `@locked` serializes access: one caller at a time, across processes |
+| **Cross-photon calls** | `this.call()` invokes another photon's methods |
+| **Real-time events** | `this.emit()` fires named events to the browser UI with zero wiring |
+| **Dependency management** | `@dependencies` auto-installs npm packages on first run |
+
+---
+
+## Coordination: Locks + Events
 
-### Step 5: Custom UI (When you want to be fancy)
+Two primitives. Together they unlock a class of things that are surprisingly hard to build today.
 
-If the auto-generated form is too boring, you can write your own HTML.
+**Locks** serialize access. When a method is marked `@locked`, only one caller can execute at a time, whether that caller is a human in Beam, a CLI script, or an AI agent. Everyone else waits their turn.
+
+**Events** push state changes to any browser UI in real time. `this.emit('name', data)` in your method fires `window.photon.on('name', handler)` in your custom UI. No WebSockets to configure. No polling. The data marshalling and delivery is handled by the system.
+
+Together: **turn-based coordination with live state**.
 
 ```typescript
-/**
- * Weather - Check weather forecasts worldwide
- * @dependencies node-fetch@^3.0.0
- * @ui dashboard ./ui/weather.html
- */
-export default class Weather {
-  constructor(private apiKey: string, private units: string = 'metric') {}
+export default class Chess {
+  /** Make a move. Locks ensure human and AI alternate turns. */
+  /** @locked */
+  async move(params: { from: string; to: string }) {
+    const result = await this.applyMove(params.from, params.to);
 
-  /**
-   * Get the weather forecast for a city
-   * @ui dashboard
-   * @format table
-   */
-  async forecast(params: { city: string; days?: number }) {
-    // returns structured weather data
+    // Browser UI updates instantly, no polling needed
+    this.emit('board-updated', result.board);
+    this.emit('turn-changed', { next: result.nextPlayer });
+
+    return result;
   }
 }
 ```
 
-```html
-<!-- ui/weather.html -->
-<div id="weather-app">
-  <div id="forecast"></div>
-</div>
-<script>
-  window.photon.onResult(data => {
-    document.getElementById('forecast').innerHTML = renderWeather(data);
-  });
-</script>
+```javascript
+// In your custom UI (ui/chess.html)
+window.photon.on('board-updated', board => renderBoard(board));
+window.photon.on('turn-changed', ({ next }) => showTurn(next));
 ```
 
-**What changes in Beam:** Instead of the auto-generated table, results render inside your custom HTML (a weather dashboard with icons, charts, or any visualization you build). The `window.photon` API bridges your UI to the tool system.
+A human moves through Beam. Claude is configured with the MCP server. The lock ensures they truly alternate. Events keep the board live on both sides. That's a fully functional turn-based chess game, human vs AI, in about 50 lines of application logic.
 
-> Custom UIs follow the [MCP Apps Extension (SEP-1865)](https://github.com/nicolo-ribaudo/modelcontextprotocol/blob/nicolo/sep-1865/docs/specification/draft/extensions/apps.mdx) standard and work across compatible hosts. See the [Custom UI Guide](./docs/guides/CUSTOM-UI.md).
+The same pattern applies beyond games: approval workflows where a human reviews before AI continues, collaborative tools where edits from any source appear instantly, simulations where steps must execute in strict sequence, any system where **who acts next matters**.
 
-<div align="center">
-<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-5.png" alt="Step 5 — Custom UI result in Beam" width="100%">
-</div>
+---
 
-### In Summary
+## Marketplace
 
-| Step | You write | Photon generates |
-|------|---------|-----------------|
-| **1. Methods** | A function | Tools, CLI commands, Forms |
-| **2. JSDoc** | Comments | Descriptions for AI and Humans |
-| **3. Constructor** | Arguments | Config UI, Env vars |
-| **4. Tags** | `@tags` | Validation, Installers, Formatting |
-| **5. Custom UI** | HTML | A custom app |
+32 photons ready to install: databases, APIs, developer tools, and more.
 
 <div align="center">
-<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/photon-ecosystem.png" alt="Photon Ecosystem" width="100%">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/beam-marketplace.png" alt="Marketplace" width="100%">
 </div>
 
----
-
-## The Basics
-
-If you are just skimming, here is what you need to know:
+```bash
+photon search postgres
+photon add postgres
+```
 
-| Concept | What it is | Learn more |
-|---------|-----------|------------|
-| **MCP** | A way for AI to use your tools. It's a standard. | [modelcontextprotocol.io](https://modelcontextprotocol.io/introduction) |
-| **Photon file** | A `.photon.ts` file. You define tools as methods in a class. | [Guide](./docs/GUIDE.md) |
-| **Beam** | A web dashboard. It shows your tools as forms. | [Beam UI](#beam) |
-| **Marketplace** | A way to get other people's photons. | [Marketplace](#marketplace) |
-| **Daemon** | A background thing that handles messages and jobs. | [Daemon Pub/Sub](./docs/core/DAEMON-PUBSUB.md) |
-| **Tags** | JSDoc comments that tell Photon what to do. | [Tag Reference](./docs/reference/DOCBLOCK-TAGS.md) |
-| **Custom UI** | When the auto-generated forms aren't enough. | [Custom UI Guide](./docs/guides/CUSTOM-UI.md) |
+Browse the full catalog in the [official photons repository](https://github.com/portel-dev/photons). You can also host a private marketplace for your team: internal tools that stay off the public internet.
 
 ---
 
 ## Commands
 
-A few commands you might use:
-
 ```bash
 # Run
 photon                            # Open Beam UI
@@ -376,7 +341,7 @@ photon maker new <name>           # Scaffold a new photon
 
 # Manage
 photon info                       # List all photons
-photon info <name> --mcp          # Get MCP client config (paste into Claude/Cursor)
+photon info <name> --mcp          # Get MCP client config
 photon maker validate <name>      # Check for errors
 
 # Marketplace
@@ -391,15 +356,13 @@ photon test                       # Run tests
 
 ---
 
-## Tag Reference (Quick Overview)
-
-Tags are JSDoc annotations that control how Photon processes your code. Here are the most commonly used ones:
+## Tag Reference
 
 | Tag | Where | What it does |
-|-----|-------|-------------|
+|---|---|---|
 | `@dependencies` | Class | Auto-install npm packages on first run |
-| `@cli` | Class | Declare system CLI tool dependencies, checked at load time |
-| `@format` | Method | Control result rendering (table, list, markdown, code, etc.) |
+| `@cli` | Class | Declare system CLI dependencies, checked at load time |
+| `@format` | Method | Result rendering (table, list, markdown, code, etc.) |
 | `@param ... {@choice a,b,c}` | Param | Dropdown selection in Beam |
 | `@param ... {@format email}` | Param | Input validation and field type |
 | `@param ... {@min N} {@max N}` | Param | Numeric range constraints |
@@ -411,7 +374,7 @@ Tags are JSDoc annotations that control how Photon processes your code. Here are
 | `@mcp` | Class | Inject another MCP server as a dependency |
 | `@icon` | Class/Method | Set emoji icon |
 
-> This is a subset. See the full [Tag Reference](./docs/reference/DOCBLOCK-TAGS.md) for all 30+ tags with examples.
+> See the full [Tag Reference](./docs/reference/DOCBLOCK-TAGS.md) for all 30+ tags with examples.
 
 ---
 
@@ -420,7 +383,7 @@ Tags are JSDoc annotations that control how Photon processes your code. Here are
 **Start here:**
 
 | Guide | |
-|-------|-|
+|---|---|
 | [Getting Started](./docs/GUIDE.md) | Create your first photon, step by step |
 | [Tag Reference](./docs/reference/DOCBLOCK-TAGS.md) | Complete JSDoc tag reference with examples |
 | [Naming Conventions](./docs/guides/NAMING-CONVENTIONS.md) | How to name methods so they read naturally as CLI commands |
@@ -429,9 +392,9 @@ Tags are JSDoc annotations that control how Photon processes your code. Here are
 **Build more:**
 
 | Topic | |
-|-------|-|
+|---|---|
 | [Custom UI](./docs/guides/CUSTOM-UI.md) | Build rich interactive interfaces with `window.photon` |
-| [OAuth](./docs/guides/AUTH.md) | Built-in OAuth 2.1 with Google, GitHub, Microsoft |
+| [OAuth](./docs/guides/AUTH.md) | Built-in OAuth 2.0 with Google, GitHub, Microsoft |
 | [Daemon Pub/Sub](./docs/core/DAEMON-PUBSUB.md) | Real-time cross-process messaging |
 | [Webhooks](./docs/reference/WEBHOOKS.md) | HTTP endpoints for external services |
 | [Locks](./docs/reference/LOCKS.md) | Distributed locks for exclusive access |
@@ -441,7 +404,7 @@ Tags are JSDoc annotations that control how Photon processes your code. Here are
 **Operate:**
 
 | Topic | |
-|-------|-|
+|---|---|
 | [Security](./SECURITY.md) | Best practices and audit checklist |
 | [Marketplace Publishing](./docs/guides/MARKETPLACE-PUBLISHING.md) | Create and share team marketplaces |
 | [Best Practices](./docs/guides/BEST-PRACTICES.md) | Patterns for production photons |
@@ -453,18 +416,8 @@ Tags are JSDoc annotations that control how Photon processes your code. Here are
 
 ## Contributing
 
-If you find a bug, or if my code offends you, feel free to open an issue or a PR. See [CONTRIBUTING.md](./CONTRIBUTING.md).
+Open an issue or a PR. See [CONTRIBUTING.md](./CONTRIBUTING.md).
 
 ## License
 
-[MIT](./LICENSE). Do what you want with it.
-
----
-
-<div align="center">
-
-*Singular focus. Precise target.*
-
-Made by [Portel](https://github.com/portel-dev)
-
-</div>
+[MIT](./LICENSE).

package/dist/async/dedup-map.d.ts

@@ -0,0 +1,40 @@
+/**
+ * DedupMap — Map with deduplication for concurrent async creation.
+ *
+ * When multiple callers request the same key concurrently, only one
+ * factory call runs — all callers share the same inflight promise.
+ *
+ * Usage:
+ *   const map = new DedupMap<string, Connection>();
+ *   const conn = await map.getOrCreate('redis', () => connect('redis://...'));
+ */
+export declare class DedupMap<K, V> {
+    private _values;
+    private _inflight;
+    /** Number of resolved entries. */
+    get size(): number;
+    /** Check if a resolved value exists for key. */
+    has(key: K): boolean;
+    /** Get a resolved value (undefined if not yet created). */
+    get(key: K): V | undefined;
+    /** Set a value directly (bypasses factory). */
+    set(key: K, value: V): void;
+    /**
+     * Get existing value or create one. Concurrent calls for the same
+     * key join the same inflight promise instead of spawning duplicates.
+     */
+    getOrCreate(key: K, factory: () => Promise<V>): Promise<V>;
+    /** Delete a key (cancels inflight if pending). */
+    delete(key: K): boolean;
+    /** Clear all entries and inflight promises. */
+    clear(): void;
+    /** Iterate over resolved entries. Returns a snapshot (safe across await). */
+    entries(): [K, V][];
+    /** Iterate over resolved keys. Returns a snapshot. */
+    keys(): K[];
+    /** Iterate over resolved values. Returns a snapshot. */
+    values(): V[];
+    /** Iterate resolved entries via for...of. Returns snapshot array. */
+    [Symbol.iterator](): IterableIterator<[K, V]>;
+}
+//# sourceMappingURL=dedup-map.d.ts.map

package/dist/async/dedup-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedup-map.d.ts","sourceRoot":"","sources":["../../src/async/dedup-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,qBAAa,QAAQ,CAAC,CAAC,EAAE,CAAC;IACxB,OAAO,CAAC,OAAO,CAAmB;IAClC,OAAO,CAAC,SAAS,CAA4B;IAE7C,kCAAkC;IAClC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,gDAAgD;IAChD,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IAIpB,2DAA2D;IAC3D,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAI1B,+CAA+C;IAC/C,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAK3B;;;OAGG;IACG,WAAW,CAAC,GAAG,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAuBhE,kDAAkD;IAClD,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IAKvB,+CAA+C;IAC/C,KAAK,IAAI,IAAI;IAKb,6EAA6E;IAC7E,OAAO,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE;IAInB,sDAAsD;IACtD,IAAI,IAAI,CAAC,EAAE;IAIX,wDAAwD;IACxD,MAAM,IAAI,CAAC,EAAE;IAIb,qEAAqE;IACrE,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CAG9C"}