# Customex

Customex is an open protocol for safe, AI-assisted website customisation.
A website publishes a machine-readable visual contract in the form of a manifest. 
A user can then describe how they want the site to look or what content they want in view. 
The AI proposes a constrained patch, the user reviews it, and the extension applies it atomically, with history and undo.

*Note that Customex is presentation-layer infrastructure.*
*It stays away from authenticated server actions, account mutations, arbitrary DOM scripting, and credentials.*
*This is intentional and distinguishes it from protocols such as MCP.*

This repository includes a runnable reference demo site and a reference Chrome client extension.

## Reference implementation

- `protocol/` - manifest schema, architecture diagram, protocol specification, and guidance for community-made "recipes".
- `sdk/` - a toy browser SDK that publishes the manifest as shared DOM JSON.
- `extension/` - a Chrome (Manifest v3) side-panel extension that uses the built-in AI's Prompt API. Customex is the protocol. This Chrome extension is just a reference client.
- `demo-site/` - a reference dashboard visual "pulseboard", with a JSON feed.
- `docs/` - docs webpages for the Customex protocol itself.

## Run the demos

1. Start a local server from the repository root:

   ```bash
   python -m http.server 8000
   ```

2. Open any of these URLs (do not open the HTML files directly):

   - `http://localhost:8000/demo-site/index.html`
   - `http://localhost:8000/demo-site/feed.html`
   - `http://localhost:8000/docs/`

3. In Chrome, open `chrome://extensions`, enable Developer mode, choose **Load unpacked**, and select the `extension/` directory.

4. Refresh the demo tab after loading or reloading the extension, then open the Customex side panel from the extension toolbar button.

Chrome's built-in Prompt API must be available on the device. The extension uses the browser's on-device model.

## What to try

### Pulseboard dashboard

- Choose **Focus mode** under Publisher views.
- Review the proposed patch and click **Apply**.
- Hover a component in **Inspect site manifest** to highlight the affected page section.
- Open patch history and click an earlier patch to reset to that point.
- Try `Make this a calmer focus workspace`, then Undo.

### JSON-backed feed

- Choose **Design and operations** to show only those topics in a spacious reading layout.
- Try `Show only design and operations posts`.
- Try `Make this calmer`; generic style language changes presentation but does not hide feed items.
- Open **Inspect site manifest** to see declared capabilities, allowed values, and policy boundaries.

## Architecture diagram

See [`protocol/ARCHITECTURE.md`](protocol/ARCHITECTURE.md) for the full component/responsibility map and request flow.

```mermaid
flowchart LR
  U[User intent] --> C[Chrome extension client]
  C --> A[On-device AI planner]
  A --> P[Structured patch]
  P --> V[Manifest validator]
  V -->|Apply / Undo| W[Website DOM and CSS]
  M[Publisher manifest] -. shared DOM JSON .-> C
  M -. policy .-> V
``` 

## The Protocol

A publisher declares components, selectors, visual capabilities, allowed values, optional named views, metadata, and protected components. The SDK serializes that manifest into:

```html
<script id="customex-manifest" type="application/customex+json">…</script>
```

The extension reads this shared DOM element, avoiding `window` access across Chrome's isolated-world boundary.

Core reference capabilities include `visibility`, `density`, `theme`, and `layout`.
**The manifest is extensible: publishers may declare arbitrary capability names, allowed values, and a `constraints.classes` mapping.**
The extension validates those values and applies publisher-declared CSS classes generically.
It does not execute arbitrary site or recipe JavaScript.

The safety pipeline is:

1. Read the live manifest and component state.
2. Ask the on-device model for a structured patch.
3. Apply deterministic topic-filter logic where metadata is available.
4. Show a human-readable proposal.
5. Validate every action again in the content script.
6. Apply atomically, record history, and support Undo or reset-to-history.

## Design profiles and recipes

Users can paste or upload a `DESIGN.md` profile as a context for visual preference.
Community recipes are advisory JSON documents.
They may name components and values but cannot contain JavaScript, selectors, credentials, or permissions.
In essence, recipes can describe a desired view, but cannot expand what the site has explicitly authorised.
See [`protocol/COMMUNITY.md`](protocol/COMMUNITY.md) and [`protocol/recipe.schema.json`](protocol/recipe.schema.json).

## Why use AI

Named views are useful without AI too. But, AI becomes valuable when a user asks for an unanticipated composition of declared primitives, such as:

> Give me a quiet morning workspace with the sidebar hidden, a spacious reading layout, and only design and operations posts.

The manifest is the policy contract. AI is the natural-language planner operating inside that contract, mapping user's intent to available modifications.
I hope this utility becomes clearer with future contributions from the web development community. 
New ideas are always appreciated! Both for the protocol itself and what is possible to do with it.

## Current boundary and future scope

At present, Customex changes how a website looks and which read-only content is shown.
In the future, it could support features like:
- Grouping tasks by status or topic
- Sorting items by priority or date
- Enabling high-contrast or large-text modes
- Creating mobile-friendly layouts
- Showing only posts from selected topics
- Applying a site’s custom colours, spacing, and typography
- Helping developers generate manifests automatically

Authenticated server-side actions remain outside the current Customex core as that is more in the ambit of MCP.

## Publisher-owned view handlers

Customex is not limited to mere CSS changes.
A publisher may eventually ship its own JavaScript renderer for a richer local view change, such as grouping cards, switching a chart mode, or changing a component's internal layout.
The publisher code remains part of the website.
The manifest only declares a typed handler name and its allowed values.

```json
{
  "id": "feed",
  "capabilities": ["grouping"],
  "constraints": {
    "values": { "grouping": ["topic", "author", "none"] }
  },
  "handler": "feed.setGrouping"
}
```

A compatible future client could invoke that already-shipped publisher handler with a declared value.
AI and community recipes may request only those declared values. 
They cannot include JavaScript, selectors, credentials, or new permissions.

This remains within Customex when the handler changes the local rendered view. API calls, account mutations, external side effects, or other authenticated operations belong to a separate action protocol rather than the Customex presentation core.
## Notes for the "OpenAI Build Week" Hackathon

This project was cooked up for the [OpenAI Build Week](https://openai.devpost.com/) by using Codex with GPT 5.6.
Customex was built with Codex and Chrome's built-in Prompt API using GPT-5.6-era tooling.
Codex helped build the SDK, extension, demos, safety checks, and documentation.
Key design decisions were to ensure the website remains in control (through a declared manifest), require explicit Apply, preserve atomic rollback, and keep Customex distinct from MCP.

## License

MIT. See [LICENSE](LICENSE).