npm package: @openverb/stdlib
Description: OpenVerb Standard Library — starter verb definitions for AI-app interaction (theme, navigation, search, modals, forms, sessions)
Author: sgthancel
Latest version: 0.1.0

# OpenVerb Standard Library

[![CI](https://github.com/sgthancel/openverb-stdlib/actions/workflows/ci.yml/badge.svg)](https://github.com/sgthancel/openverb-stdlib/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Verbs](https://img.shields.io/badge/verbs-19-blue.svg)](docs/website-starter-verbs.md)
[![Families](https://img.shields.io/badge/families-7-blue.svg)](docs/website-starter-verbs.md)

A starter set of verb definitions that every app should have — theme, navigation, search, modals, toasts, forms, and sessions. These are the common baseline. Your app defines its own verb libraries for domain-specific actions on top of these.

> **The verbs every app needs. Your app adds the rest.**

## What This Is

This is **not** a complete list of all possible verbs — OpenVerb is designed so developers create their own verb libraries for their own domains. This stdlib gives you the **starter verbs** that virtually every app needs, so an AI agent can immediately:

- Switch themes
- Navigate pages
- Search content
- Show notifications
- Open modals
- Fill and submit forms
- Check who's logged in

## Verb Families

### Level 0: Website UI Starter

| Family         | Verbs                              | Purpose                      |
| -------------- | ---------------------------------- | ---------------------------- |
| `ui.theme`     | `get`, `set`                       | Theme (light/dark/system)    |
| `ui.nav`       | `list_pages`, `go`, `back`         | Navigation & route discovery |
| `ui.search`    | `query`, `open_result`             | On-site search               |
| `ui.toast`     | `show`, `dismiss`                  | Notifications & feedback     |
| `ui.modal`     | `open`, `close`, `list`            | Modal dialogs                |
| `ui.form`      | `list`, `fill`, `submit`, `reset`  | Form interaction             |
| `user.session` | `get`, `logout`, `get_preferences` | User session & preferences   |

**7 starter families, 19 starter verbs.** Your app adds its own verb libraries on top of these.

### Future Levels

| Level | Name                   | Examples                              |
| ----- | ---------------------- | ------------------------------------- |
| 1     | App Operations Starter | CRUD, table filters, export, settings |
| 2     | Domain Packs           | GIS, Pantry, CAD, etc.                |

## Part of the OpenVerb Ecosystem

This is the **standard library** for the [OpenVerb](https://github.com/sgthancel/openverb) framework — an open, text-first standard for describing what actions an AI is allowed to perform inside an application.

| Package            | Registry                                                                                   | Description                                        |
| ------------------ | ------------------------------------------------------------------------------------------ | -------------------------------------------------- |
| `openverb`         | [npm](https://www.npmjs.com/package/openverb) / [PyPI](https://pypi.org/project/openverb/) | Core framework — load & validate verb libraries    |
| `@openverb/stdlib` | npm (this repo)                                                                            | Standard verb definitions for common UI operations |

## Quick Start

### 1. Install

```bash
# Install the core framework + standard library
npm install openverb @openverb/stdlib
```

Or with Python:

```bash
pip install openverb
# Then copy manifests/ from this repo into your project
```

### 2. Use the manifests

The JSON verb definitions live in `manifests/`:

```
manifests/
  ui.theme.json
  ui.nav.json
  ui.search.json
  ui.toast.json
  ui.modal.json
  ui.form.json
  user.session.json
```

### 3. Implement handlers

Use one of the reference implementations or write your own:

- **Vanilla JS** — `reference/vanilla/verbs.js`
- **React** — `reference/react/useOpenVerb.ts`
- **Next.js** — `reference/nextjs/verbs.ts`

### 4. Wire up your AI

When your AI receives a verb call, dispatch it to your handler:

```javascript
const result = executeVerb("ui.nav.go", { routeId: "accounting" });
// → { success: true, path: "/accounting" }
```

### 5. Apply client-side effects

Verbs return data. Your client applies the effect:

- `ui.nav.go` → call `router.push(path)`
- `ui.theme.set` → update `data-theme` attribute
- `ui.toast.show` → render a toast component

## Route Registry

For `ui.nav.list_pages` and `ui.nav.go`, maintain a route registry so the AI knows what pages exist:

```json
{
  "id": "accounting",
  "title": "Accounting",
  "path": "/accounting",
  "tags": ["billing", "invoices", "payments"],
  "requiresAuth": true
}
```

The AI uses `id` to navigate — it never guesses URLs.

## Example: The "Accounting Page" Flow

1. User: "I want to know about the accounting stuff"
2. AI calls `ui.nav.list_pages`
3. AI sees a route with tags matching "accounting"
4. AI: "There's an Accounting page. Do you want me to take you there?"
5. User: "Yes"
6. AI calls `ui.nav.go({ routeId: "accounting" })`
7. Client navigates to `/accounting`

## Repo Layout

```
openverb-stdlib/
  docs/
    website-starter-verbs.md    Full verb specs + examples
    patterns-navigation.md      Navigation patterns & anti-patterns
  manifests/
    ui.theme.json               Theme verbs manifest
    ui.nav.json                 Navigation verbs manifest
    ui.search.json              Search verbs manifest
    ui.toast.json               Toast verbs manifest
    ui.modal.json               Modal verbs manifest
    ui.form.json                Form verbs manifest
    user.session.json           Session verbs manifest
  reference/
    vanilla/verbs.js            Plain JS implementation
    react/useOpenVerb.ts        React hook implementation
    nextjs/verbs.ts             Next.js App Router wrapper
    nextjs/routeRegistry.ts     Route registry helpers
```

## Design Principles

- **Framework-agnostic core**: Manifests are JSON. Handlers are framework-specific.
- **Deterministic**: The AI uses registries (routes, modals, forms) — no guessing.
- **Auditable**: Every verb call has typed input/output. You can log, replay, and review.
- **Safe by default**: `user.session.get` never exposes tokens. `user.session.logout` requires confirmation.
- **Composable**: Verbs are small and independent. Combine them for complex flows.

## Docs

- [Website Starter Verbs](docs/website-starter-verbs.md) — Full spec for all Level 0 verbs
- [Navigation Patterns](docs/patterns-navigation.md) — Patterns, anti-patterns, and framework-specific guidance

## Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

- [Report a bug](.github/ISSUE_TEMPLATE/bug_report.md)
- [Request a feature](.github/ISSUE_TEMPLATE/feature_request.md)
- [Propose a new verb](.github/ISSUE_TEMPLATE/new_verb.md)

## License

[MIT](LICENSE) — use it however you want.