# OrbPage

OrbPage holds what editors write about your products, built from the sections your shop declares. What it does, what it leaves to you and where to start.

OrbPage is the content layer of a shop: pages, category content, templates, menus and forms. Your shop declares the sections editors build from, editors arrange them in the admin's _Content_ area, and the shop reads what they publish. Products, categories and pictures come from OrbCatalog and are never copied.

The shop reads a category's page through `@orbpage/client`, typed by the sections it declared. `env.PAGE_URL` is where OrbPage answers:

```ts
import { createClient } from "@orbpage/client";
import { sections } from "./sections";

const content = createClient({
  baseUrl: env.PAGE_URL, // where OrbPage answers, such as https://content.nordgrat.de
  sections,
});
```

```ts continues
const read = await content.categories.get("outdoor/rucksaecke", { locale: "de" });
if (read.ok) {
  read.content.slots.top; // the hero sections, typed by the declaration
  read.content.slots.main;
  read.content.template; // the template it follows
  read.content.meta.unresolved; // what was left out, such as a product no longer sold
} else {
  read.problem.code; // such as "entry_not_found", "unreachable" or "unexpected_response"
}
```

No read throws. When OrbPage cannot answer, the shop still shows the catalog's category, without the editor's slots. [Read the content](/docs/shop/content) covers pages, menus and previews.

## What OrbPage does

- **Builds pages from your sections.** The shop [declares](/docs/shop/sections) sections with typed settings and the slots they go in. The editor, drafts, publishing and delivery all check against that one declaration.
- **Shares a template across categories.** A category follows its template slot by slot until an editor makes a slot its own. A reset gives the slot back to the template.
- **Shows the draft in your shop.** The admin previews an editor's draft inside the shop's own page, in a frame. The preview reads the draft uncached, under a short-lived token.
- **Delivers JSON and Markdown.** Running text arrives as safe HTML inside JSON. A card whose product went away is left out and named in `meta.unresolved`.
- **Takes form answers.** Answers land in a separate Inbox for 180 days. Each accepted answer can send a signed `form.submitted` event.
- **Tells your systems what went live.** Configured, every publish, rollback or withdrawal sends a signed `content.published` event.
- **Lets AI agents propose drafts.** An agent proposes a page or template change over MCP, rows of columns included, a person approves it in the admin, and publishing stays a separate step.

## What OrbPage leaves to you

| OrbPage does not              | Who does                                                                                                                   |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Render or style the shop      | Your storefront. `@orbpage/react` adds the row layout and the preview marks.                                               |
| Keep products or pictures     | OrbCatalog, read at delivery, with its [media library](/docs/admin/catalog#keep-the-pictures).                                  |
| Show prices or stock on cards | Your shop. A card holds a name, an address and a picture.                                                                  |
| Send emails                   | A receiver of the signed `form.submitted` event.                                                                           |
| Run on someone else's servers | You do: one Worker in your own Cloudflare account. See [deployment](/docs/run/deployment#set-up-catalog-and-orbpage-from-code). |

## Change what you need

Everything in OrbPage changes in one of three ways, from shallow to deep.

| Depth     | You                                                                  | Example                                                                                    |
| --------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Configure | Set values in the shop's [declaration](/docs/shop/sections#declare-them). | A setting's default and help text, the palette, the menus.                                 |
| Compose   | Let editors arrange the declared sections.                           | [Rows](/docs/shop/sections#arrange-rows) in six layouts, [templates](/docs/shop/sections#templates). |
| Replace   | Render each section with your own component.                         | [A `switch` over the section's type](/docs/shop/sections#render-a-slot).                        |

## Built on OrbCatalog

OrbPage needs OrbCatalog and does not run without it. It reads products, categories and listings through `@orbcatalog/client` at delivery, and its site's languages are the ones its catalog Channel sells. OrbPage needs neither OrbCart nor OrbSearch. [Connect the products](/docs/run/connect-the-products) shows the configuration.

## Next steps

| You want to                          | Read                                                               |
| ------------------------------------ | ------------------------------------------------------------------ |
| See it run                           | [Run it locally](/docs/get-started)                                     |
| Declare the shop's sections          | [Declare sections and slots](/docs/shop/sections)                       |
| Read pages, menus and previews       | [Read the content](/docs/shop/content)                                  |
| Seed or import pages from a script   | [Write content from code](/docs/page/write-content)                     |
| Point OrbPage at the catalog         | [Connect the products](/docs/run/connect-the-products)                  |
| Set it up in your Cloudflare account | [Deployment](/docs/run/deployment#set-up-catalog-and-orbpage-from-code) |