---
name: panel-comments
description: Integrate a self-hosted Panel Comments installation into Astro or static HTML and create a scoped host-site theme from the installation's published contracts. Use when an agent is given a Panel Comments base URL and needs to add, repair, validate, or visually match its comment embed without administering the Panel Comments server.
---

# Panel Comments Integration

Use the deployed installation as the authority. Do not rely on remembered endpoint names or styling hooks when its published resources are reachable.

## Discover the instance

1. Normalize the supplied Panel Comments base URL without inventing or removing a subfolder.
2. Fetch `<base>/llms.txt`, then `<base>/integration.php` and the linked integration and styling Markdown.
3. Use the manifest's absolute endpoints. If discovery is unavailable, report which URL failed before using the conservative `<base>/embed.js` fallback.
4. Never request Panel Comments administrator credentials. Public discovery intentionally contains everything needed for code integration.
5. Treat Cloudflare as deployment infrastructure, not an embed dependency. The public loader works through a proxied Panel Comments hostname; its owner can manage hostname-scoped cache and Rocket Loader rules under Tools → Optimization without changes to the embedding site's Cloudflare zone.

## Inspect the embedding site

Before editing, identify:

- the framework and the component or layout that owns article comments;
- the site's public origin, canonical URL behavior, and Astro view-transition usage;
- existing CSS tokens, type scale, spacing, borders, light/dark behavior, focus treatment, and responsive breakpoints;
- whether the project already loads Panel Comments.

Avoid adding the loader globally when comments belong only on article routes. Avoid loading it twice through both a layout and a page component.

## Confirm server-side prerequisites

Tell the user the exact embedding origin that must be registered in Panel Comments, including scheme, hostname, and non-default port. Examples include `http://localhost:4321` and `https://www.example.com`.

Do not attempt to register the origin through an undocumented endpoint. Do not handle Turnstile secrets, administrator sessions, or other server configuration. If the origin is not registered, implement the site-side code and clearly identify the remaining administrator action.

## Add the supported loader

For static HTML, place the manifest's embed script where comments should appear:

```html
<script data-cfasync="false" src="PANEL_COMMENTS_BASE/embed.js" defer></script>
```

For explicit placement, or for Astro, use one target and one classic inline script:

```astro
<section data-panel-comments></section>
<script
  is:inline
  data-cfasync="false"
  src="PANEL_COMMENTS_BASE/embed.js"
  data-target="[data-panel-comments]"
  defer
></script>
```

Leave page discovery automatic unless the project genuinely requires a stable `data-page-key`. Preserve a same-origin canonical URL. The supported loader already remounts on `astro:page-load`; do not build a direct API client or a second view-transition adapter.

Keep lazy loading unless immediate initialization is required; then add `data-loading="eager"`. Use `data-composer-position="top"` or `"bottom"` only for a page-specific override. Do not build separate reaction or Markdown-preview clients: article/comment reactions and the exact server-rendered editor preview are integrated into the supported widget and controlled per website.

## Choose one styling owner

Use one mode rather than mixing ownership:

- **Panel-managed:** keep the built-in stylesheet enabled and put custom CSS in the website's Panel Comments Appearance page. Host CSS cannot cross the Shadow DOM.
- **Host-managed:** ask the administrator to clear **Let Panel Comments load this stylesheet**. Add CSS to the embedding project, scope every rule beneath `panel-comments`, and use only hooks published by the deployed styling guide.

Prefer host-managed mode when the task is to match an Astro/static site's existing design and repository changes are authorized. Derive the theme from existing tokens instead of introducing an unrelated visual system. Preserve `[hidden]`; never reveal or target `.pc-honeypot` or `.pc-trap`.

Cover at least these states when they exist in the published contract: loading, empty, error, notice, comment, deleted comment, nested reply, actions, article/comment reactions, selected and disabled reaction choices, reaction picker, search result and context, paging, Load All progress/cancel, composer, inline reply/edit, Write/Preview tabs, toolbar, tables, code/copy controls, commenter account, challenge, focus, and disabled controls. Check narrow screens, light/dark schemes, and reduced motion.

Use bubbling `panel-comments:metadata` or `panel-comments:ready` only when the host needs public page/count state. Treat their `detail.schema_version` as a contract version and keep the integration functional when the optional events are ignored.

## Validate without causing side effects

1. Confirm the embed URL loads and only one `<panel-comments>` mounts in the intended location.
2. Confirm bootstrap requests use the manifest's physical API gateway and succeed from the registered exact origin.
3. Confirm canonical/current URLs resolve to the intended discussion across navigation and Astro view transitions.
4. Check keyboard focus, readable contrast, mobile layout, both supported color schemes, and all available widget states.
5. Do not submit a real comment, change server settings, or weaken anti-spam unless the user explicitly authorizes that action.

Never edit vendored Panel Comments widget assets in the embedding project, copy its private API implementation, expose secrets, override security-hidden elements, or claim successful end-to-end posting when origin registration or an authorized test is still outstanding.