Author a Site Extension

A Site Pack is a declarative JSON manifest. It describes where Ophel may run, which page elements represent chat roles, and which capabilities are safe to expose. It cannot execute JavaScript or load remote code. You can start from either:

the in-product site adapter setup flow (Create an adapter for this site)
the repository example at registry/examples/site-pack.example.json

This guide follows the published Duck.ai pack and the current runtime validator.

Path A: Site adapter setup

On an unsupported HTTPS page, open the launcher (Create an adapter for this site). The wizard walks through:

message input
send button
conversation container
user message
AI response
optional conversation list item
optional new-chat button
live outline preview and capability summary
save / download / open a prefilled GitHub contribution flow

Useful wizard behaviors grounded in the current product:

pick elements on the page, or edit selectors manually
optional AI selector draft helper that only copies a sanitized prompt when you choose to
local save requires HTTPS
saving may request host permission; denial leaves the saved pack disabled
after a successful local save, reload the page so adapter modules start from a clean lifecycle

The wizard is a drafting tool. Review every selector and capability before publishing.

Path B: hand-written JSON

Copy the example pack to registry/sites/<id>.json, or export a local draft from the wizard. Do not add a $schema property inside the manifest. The repository maps Site Pack JSON files to the editor schema externally, while the runtime rejects unknown keys.

Identity and compatibility

{
  "schemaVersion": 1,
  "id": "duck-ai",
  "version": 1,
  "minAppVersion": "1.1.8"
}

Field	Rule
`schemaVersion`	Currently `1`
`id`	Globally unique, `^[a-z0-9-]{2,40}$`, must not collide with a built-in site ID
`version`	Positive integer. Published registry versions are immutable; the publish build can derive the final number from content
`minAppVersion`	Earliest Ophel SemVer that understands the fields you verified

Name and description

{
  "name": "Duck.ai",
  "nameI18n": { "en": "Duck.ai", "zh-CN": "Duck.ai" },
  "description": "Adds Ophel outlines, export, generation controls, layout tools, and prompt insertion to Duck.ai.",
  "descriptionI18n": {
    "en": "Adds Ophel outlines, export, generation controls, layout tools, and prompt insertion to Duck.ai."
  }
}

name / description are fallbacks. nameI18n / descriptionI18n override them for matching languages. Registry contributions that change user-facing metadata should provide all eleven project languages used by Ophel.

Match the target site

{
  "matches": ["https://duck.ai/*"]
}

Rules:

at most ten HTTPS extension match patterns
no global matches or top-level host wildcards
no overlaps with built-in sites or existing packs
self-hosted packs may use matches: [] and activate only after the user binds an exact HTTPS origin

Declare capabilities honestly

{
  "capabilities": [
    "outline",
    "outline-user-queries",
    "export-basic",
    "generation-detect",
    "new-chat",
    "stop-generation",
    "width",
    "zen",
    "prompt-insert"
  ]
}

Each capability requires supporting fields. See the capabilities reference. If a feature is not verified, omit the capability.

Select chat elements

{
  "selectors": {
    "textarea": ["textarea[name='user-prompt']"],
    "submitButton": ["[data-testid='duckai-chat-input'] button[type='submit']"],
    "responseContainer": "section:has([data-testid='duckai-chat-input'])",
    "userQuery": "[data-testid='user-message']",
    "assistantResponse": "[data-activeresponse='true'] > :nth-child(2)",
    "newChatButton": ["[data-testid='duckai-sidebar'] > div > div:has([role='search']) + div button[type='button']"],
    "stopButton": ["[data-testid='duckai-chat-input'] div:has(> button[type='submit']) + div > button[type='button']"]
  }
}

Selector guidance:

prefer stable data-testid, stable IDs, semantic attributes, and short structural relationships
avoid generated hashes, utility-only classes, and translated visible text when a stable attribute exists
treat positional selectors such as :nth-child() as a last resort and document the real-browser evidence in the pull request

Configure common groups

Input

{
  "input": {
    "mode": "textarea",
    "submitKey": "Enter"
  }
}

Generation

{
  "generating": {
    "existsSelectors": [
      "[data-testid='duckai-chat-input'] div:has(> button[type='submit']) + div > button[type='button']"
    ]
  }
}

Export

{
  "export": {
    "userQuerySelector": "[data-testid='user-message']",
    "assistantResponseSelector": "[data-activeresponse='true'] > :nth-child(2)",
    "turnSelector": null,
    "useShadowDOM": false
  }
}

Zen mode

{
  "zenMode": {
    "hide": ["[data-testid='duckai-sidebar']", "[data-testid='duckai-top-toolbar']"]
  }
}

Width

{
  "widthSelectors": [
    {
      "selector": "section:has([data-testid='duckai-chat-input']) div:has(> [data-testid='user-message'])",
      "property": "max-width",
      "extraCss": "width: 100% !important; box-sizing: border-box !important;"
    }
  ]
}

Optional extraCss is still filtered by the restricted CSS-value validator. Remote resource functions, imports, expressions, and JavaScript URLs are rejected after decoding and normalization.

Panel avoidance and theme sync

panel-avoidance requires a verified panelAvoidance block. At minimum, provide non-empty widthSelectors. Optional fields include scopeSelector, obstacleSelectors, insetSelectors, gap, and width thresholds. themeSync is optional and is not a capability id. Use it only for sites that switch theme through explicit localStorage writes and optional <html> class toggles. See Capabilities.

Security constraints while authoring

serialized Site Pack JSON must stay within 64 KiB
ordinary arrays are capped at 50 items
regexes are length-limited and checked with safe-regex2
same-origin path templates must start with a single /
never include tokens, cookies, account data, internal URLs, or user content
never use a Site Pack to override a built-in site
never add scripts, expressions, remote resources, or destructive automation fields

Validate and contribute

From the ophel repository:

pnpm registry:validate
pnpm registry:build

registry:build generates a local unsigned build for testing. The signed distribution used by the registry publish workflow is produced by pnpm registry:build:signed. Then verify the declared capabilities on the real site, including:

cold reload
idle and generating states
outline / export / prompt insertion if declared
panel open and closed, for width or panel-avoidance packs

Submit the JSON with the SitePack pull request template and follow the review checklist. Editor JSON Schema help:

registry/schema/site-pack.schema.json

Runtime authority:

src/adapters/declarative/validate.ts

Get Started

Core Features

Enhancements

Customization

Sync & Backup

Privacy & Permissions

Help

Changelog

Author a Site Extension

Path A: Site adapter setup

Path B: hand-written JSON

Identity and compatibility

Name and description

Match the target site

Declare capabilities honestly

Select chat elements

Configure common groups

Panel avoidance and theme sync

Security constraints while authoring

Validate and contribute

​Path A: Site adapter setup

​Path B: hand-written JSON

​Identity and compatibility

​Name and description

​Match the target site

​Declare capabilities honestly

​Select chat elements

​Configure common groups

​Panel avoidance and theme sync

​Security constraints while authoring

​Validate and contribute

​Related pages

Path A: Site adapter setup

Path B: hand-written JSON

Identity and compatibility

Name and description

Match the target site

Declare capabilities honestly

Select chat elements

Configure common groups

Panel avoidance and theme sync

Security constraints while authoring

Validate and contribute

Related pages