# atproto-wc — agent reference

Framework-agnostic custom elements for rendering ATProto content. 34 elements, ~12KB gzipped, zero runtime dependencies. Works in plain HTML, Astro, Next, Vite, Svelte, Lit, or any environment where custom elements work.

This file is self-contained: install, import, the full element catalog with attributes, styling tokens and shadow-part names, programmatic API, framework integration, and the conventions every element shares. If you're an agent writing code against atproto-wc, you should not need to fetch anything else.

## What this library is and isn't

- **Is**: a set of `<atproto-*>` custom elements that read content directly from the authoring PDS and engagement from the Constellation backlink index.
- **Is**: lexicon-agnostic — `<atproto-record-list>` will paginate any collection; `<atproto-backlinks>` will list every collection+path linking to a target, including custom lexicons.
- **Isn't**: a Bluesky AppView client. Moderation labels, algorithmic feeds, and the denormalized timeline shapes live in the AppView and are out of scope. For a bsky.app-identical embed, use the official widget.
- **Isn't**: React components. These are native custom elements that render into Shadow DOM. They work with React (pass attributes as props, mark the importing file as client), but they aren't React components.

## Installation

CDN (auto-registers every element):

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/atproto-wc/dist/browser.js"></script>
```

npm:

```sh
bun add atproto-wc
# or: npm i atproto-wc
```

Package exports:

- `atproto-wc` — programmatic API + `registerX` functions + `defineAll()`. Side-effect free.
- `atproto-wc/browser` — side-effecting import that registers every `<atproto-*>` element.

## Registering elements

Three patterns, pick one:

```ts
// 1. Auto-register everything (side-effecting import — what the CDN tag does).
import "atproto-wc/browser";

// 2. Side-effect-free import, explicit registration call (nicer for tree-shakers).
import { defineAll } from "atproto-wc";
defineAll();

// 3. Only the elements you actually render — each has a `register*` function.
import { registerPost, registerProfile } from "atproto-wc";
registerPost();
registerProfile();
```

## The `src` attribute — three shapes, auto-detected

Every element that fetches content takes a `src`:

- **AT-URI** — `at://did:plc:abc.../app.bsky.feed.post/3m...`
- **bsky.app URL** — `https://bsky.app/profile/<handle-or-did>/post/<rkey>`, parsed into an AT-URI.
- **Handle** — `iammatthias.com`. Resolved via `/.well-known/atproto-did` on the handle's domain. Used by `<atproto-profile>`, `<atproto-feed>`, `<atproto-followers>`, `<atproto-blobs>`, `<atproto-repo>`, etc.

Whichever shape you pass, the element will figure out what to do. For elements that need a repo identity (a profile, a feed, a blob grid), pass a handle or DID. For elements that need a specific record (a post, a thread, a like-count), pass an AT-URI or bsky.app URL.

Some elements require a different shape — see the individual entries below.

## Shared behavior — true for every element

- Renders a skeleton while loading — no layout shift.
- Shows a retry button on transient failures (network, 5xx). Permanent failures (404, bad URI) don't offer retry.
- Aborts in-flight fetches when the element disconnects from the DOM.
- Deduplicates identical requests within a 10s window.
- Attaches clickthrough permalinks to `bsky.app` where appropriate.
- Themes via CSS custom properties and `::part()`.
- Every Constellation-backed element accepts `constellation="..."` to override the endpoint per element.

## Element catalog

Elements are grouped by tier. Required attributes are marked `*`. Unless otherwise noted, the `constellation` attribute is an optional string override.

### Content surfaces

#### `<atproto-post>`

Canonical post embed: author, facets, images, external cards, quote embeds, video, engagement counts.

- `src *` (string) — AT-URI or bsky.app post URL.
- `compact` (boolean) — trimmed chrome variant for nesting in quote embeds / thread replies.
- `no-counts` (boolean) — skip the engagement counts row (saves 4 Constellation calls).
- `constellation` (string).

#### `<atproto-profile>`

Profile card — avatar, banner, bio, follower/following/post counts.

- `src *` (string) — handle, DID, or AT-URI.
- `constellation` (string).

#### `<atproto-feed>`

Author's posts + reposts, paginated, newest-first.

- `src *` (string) — handle or DID.
- `collection` (string, default `app.bsky.feed.post`) — which collection to list.
- `limit` (number, default `10`).
- `include-replies` (boolean) — include the user's own replies (skipped by default).
- `no-reposts` (boolean) — skip the parallel `app.bsky.feed.repost` stream.

#### `<atproto-thread>`

Full reply tree for a post — ancestors, focal, descendants.

- `src *` (string) — any post in the thread; can be mid-thread, ancestors walk up.
- `depth` (number, default `2`) — nested reply branches to render.
- `constellation` (string).

#### `<atproto-comments>`

Threaded replies for a post via Constellation.

- `src *` (string) — post AT-URI.
- `depth` (number, default `1`) — recursion depth. `depth=0` shows a 'Show replies' button.
- `limit` (number, default `10`).
- `show-count` (boolean) — render the 'N replies' header.
- `constellation` (string).

#### `<atproto-repo>`

Browse a repo's every collection. Lazy-expand to records.

- `src *` (string) — handle or DID.

#### `<atproto-lexicon-viewer>`

Any record, any lexicon, as a JSON tree.

- `src *` (string) — AT-URI of any record.

#### `<atproto-record-list>`

Paginated `listRecords` for an arbitrary collection on an arbitrary repo. Custom lexicons included.

- `src *` (string) — handle or DID.
- `collection *` (string) — lexicon NSID (e.g. `com.example.myschema`).
- `limit` (number, default `10`).

#### `<atproto-list>`

Render an `app.bsky.graph.list` record with its members.

- `src *` (string) — AT-URI of the list record.
- `limit` (number, default `32`) — members shown.
- `constellation` (string).

### Backlink / engagement (Constellation-backed)

#### `<atproto-likers>`

Avatar grid of accounts that liked a post.

- `src *` (string) — post AT-URI or bsky.app URL.
- `limit` (number, default `16`).
- `constellation` (string).

#### `<atproto-reposters>`

Avatar grid of accounts that reposted.

- `src *` (string) — post AT-URI or bsky.app URL.
- `limit` (number, default `16`).
- `constellation` (string).

#### `<atproto-quoters>`

Posts that quoted the target, rendered as compact cards.

- `src *` (string) — post AT-URI or bsky.app URL.
- `limit` (number, default `10`).
- `constellation` (string).

#### `<atproto-followers>`

Avatar grid of followers.

- `src *` (string) — subject handle or DID.
- `limit` (number, default `16`).
- `constellation` (string).

#### `<atproto-mutuals>`

Intersection of two actor sets — who links both `a` and `b` via the same relation.

- `a *` (string) — first subject (handle, DID, or AT-URI).
- `b *` (string) — second subject, same shape as `a`.
- `source` (string, default `follow`) — relation key from `SOURCES`.
- `limit` (number, default `16`).
- `constellation` (string).

#### `<atproto-mentions>`

Posts that mention a subject DID.

- `src *` (string) — handle or DID.
- `limit` (number, default `16`).
- `constellation` (string).

#### `<atproto-citations>`

Records that cite a target via any `subject` field — e.g. posts that link to a given URL.

- `src *` (string) — a URL, AT-URI, or DID.
- `limit` (number, default `10`).
- `constellation` (string).

#### `<atproto-blockers>`

Accounts that have blocked a target DID. Public data; use thoughtfully.

- `src *` (string) — handle or DID.
- `limit` (number, default `16`).
- `constellation` (string).

#### `<atproto-list-memberships>`

Lists (curated `app.bsky.graph.list` records) that contain a given subject.

- `src *` (string) — handle or DID.
- `limit` (number, default `10`).
- `constellation` (string).

#### `<atproto-backlinks>`

Every collection+path linking to a target, with counts. Lexicon-agnostic — works on any record from any schema.

- `src *` (string) — target AT-URI or DID.
- `constellation` (string).

#### `<atproto-like-count>`

Live like count for a post.

- `src *` (string) — post AT-URI or bsky.app URL.
- `constellation` (string).

#### `<atproto-generic-count>`

Total record count for an arbitrary subject + source pair. The count primitive Constellation returns.

- `subject *` (string) — AT-URI, DID, or any backlink target.
- `source *` (string) — `collection:path` format (path takes no leading dot).
- `label` (string) — suffix label after the count.
- `constellation` (string).

#### `<atproto-distinct-count>`

Unique-DID count — the "how many people" twin of `generic-count`.

- `subject *` (string).
- `source *` (string) — same format as `generic-count`.
- `label` (string).
- `constellation` (string).

### Repo state

#### `<atproto-blobs>`

Paginated grid of a repo's blob CIDs. Images render inline; non-image MIME types show a badge.

- `src *` (string) — handle or DID.
- `limit` (number, default `20`).

#### `<atproto-latest-commit>`

Repo head — rev + decoded 'last activity' age.

- `src *` (string) — handle or DID.
- `show-cid` (boolean) — show the commit CID (truncated) alongside the rev.
- `hide-age` (boolean) — suppress the decoded timestamp suffix.

#### `<atproto-repo-status>`

Activation state, handle, PDS health (active / deactivated / takendown).

- `src *` (string) — handle or DID.

#### `<atproto-verification>`

`app.bsky.graph.verification` status for an account — decentralized verification claims against a DID.

- `src *` (string) — handle or DID.
- `limit` (number, default `16`).
- `constellation` (string).

#### `<atproto-gate-badge>`

Inline badge for posts with reply/quote limits.

- `src *` (string) — post AT-URI or bsky.app URL.
- `kind` (string, default `any`) — `any` | `thread` | `post`.
- `show-when-absent` (boolean) — render a muted 'open' label when there's no gate.
- `constellation` (string).

#### `<atproto-pinned-badge>`

Inline badge when a post is its author's pinned.

- `src *` (string) — post AT-URI or bsky.app URL.
- `show-when-not-pinned` (boolean) — render a muted 'not pinned' label instead of nothing.
- `constellation` (string).

### Atoms (primitives)

Composed by the larger elements. Useful on their own when you want a bare display name without the profile card, or a relative timestamp without the post embed.

#### `<atproto-avatar>`

- `src *` (string) — handle, DID, or AT-URI.
- `size` (string, default `40px`) — `24px` | `40px` | `80px`.
- `linked` (boolean) — wrap in anchor pointing at `bsky.app/profile/<handle>`.

#### `<atproto-display-name>`

- `src *` (string) — handle, DID, or AT-URI.
- `linked` (boolean).

#### `<atproto-handle>`

- `src *` (string) — handle, DID, or AT-URI.
- `linked` (boolean).
- `bare` (boolean) — skip the leading `@`.

#### `<atproto-rich-text>`

Post text with facet rendering (links, mentions, tags). No network — pure rendering.

- `text *` (string) — plain post text.
- `facets` (string) — JSON-encoded array of ATProto facets.

#### `<atproto-time>`

`<time>` element with relative formatting. No network.

- `datetime *` (string) — ISO 8601 datetime. Anything `Date` can parse.

#### `<atproto-engagement-row>`

Four parallel Constellation counts. Subset via `show`.

- `src *` (string) — post AT-URI or bsky.app URL.
- `show` (string, default `replies,reposts,quotes,likes`) — comma-separated subset.
- `constellation` (string).

## Styling

Three layers, composable:

1. **CSS custom properties** — set on the element, an ancestor, or globally.
2. **`::part()` selectors** — target internals through the Shadow DOM boundary.
3. **Plain `style=""` / `class=""`** on the host.

Tailwind-style arbitrary variants work: `class="[&::part(avatar)]:rounded-sm"`.

Dark mode is auto-detected via `prefers-color-scheme: dark`. To customize dark values, override tokens inside your own media query. To opt out, set them unconditionally.

### Design tokens (all prefixed `--atproto-`)

Colors:

- `--atproto-bg`, `--atproto-text`, `--atproto-muted`
- `--atproto-accent`, `--atproto-accent-soft`, `--atproto-accent-hover`
- `--atproto-hover-bg`, `--atproto-focus-ring`
- `--atproto-border`, `--atproto-subtle`
- `--atproto-link`, `--atproto-link-visited`
- `--atproto-error`, `--atproto-warning`, `--atproto-success`

Typography:

- `--atproto-font`, `--atproto-font-mono`
- `--atproto-font-size-xs|sm|<default>|lg|xl`
- `--atproto-line-height`, `--atproto-line-height-tight`
- `--atproto-letter-spacing-tight`
- `--atproto-font-weight`, `--atproto-font-weight-semibold`, `--atproto-font-weight-bold`

Spacing, radii, sizes:

- `--atproto-space-1..6`
- `--atproto-radius-sm|inner|<default>|lg|pill`
- `--atproto-avatar-size`, `--atproto-avatar-size-sm`, `--atproto-avatar-size-lg`
- `--atproto-max-width` (content cap, default `560px`)

Elevation + motion:

- `--atproto-shadow` (applied, default `none`), `--atproto-shadow-sm|md|lg`
- `--atproto-transition-duration`, `--atproto-transition-easing`

### Common `::part()` targets (from `<atproto-post>`)

- `article` — outer card container.
- `avatar`, `avatar-link`, `avatar-image` — avatar pieces.
- `author`, `display-name`, `handle`, `time` — header row.
- `body`, `text` — content column and rendered post text.
- `images`, `image` — image grid container and each img.
- `external`, `external-thumb`, `external-title`, `external-desc`, `external-host` — external-link card pieces.
- `video` — video embed container.
- `quote` — quote embed wrapper (contains a nested compact `atproto-post`).
- `counts`, `count` — engagement row and each span.

Other elements follow the same pattern — check `/styling` for the full per-element part reference.

### Example: cohesive theme

```css
atproto-post,
atproto-profile,
atproto-feed {
  --atproto-accent: #ea580c;
  --atproto-radius: 4px;
  --atproto-font: Georgia, serif;
}

atproto-post::part(avatar) { border-radius: 4px; }
atproto-post::part(counts) { display: none; }
```

## Constellation endpoint

Defaults to `https://constellation.microcosm.blue`. Override globally or per element:

```ts
import { setConstellationEndpoint } from "atproto-wc";
setConstellationEndpoint("https://my-constellation.example");
```

```html
<atproto-post src="at://..." constellation="https://my-constellation.example"></atproto-post>
```

## Programmatic API

Exported for use outside the components:

```ts
import {
  // AT-URI parsing
  parseAtUri,
  buildAtUri,
  isBskyPostUrl,
  parseBskyPostUrl,

  // DID / PDS resolution
  resolveHandle,
  resolveDidDocument,
  resolvePdsEndpoint,

  // PDS reads
  getRecord,
  listRecords,
  describeRepo,
  listBlobs,
  getLatestCommit,
  getRepoStatus,
  tidToDate,

  // Constellation
  getBacklinks,
  getBacklinksCount,
  getDistinctDids,
  getDistinctDidsCount,
  getManyToMany,
  getLinksAll,
  setConstellationEndpoint,
  getConstellationEndpoint,
  SOURCES,

  // Utilities
  resolvePostSource,
  safeUrl,
  clearCache,
  CacheFetchError,
} from "atproto-wc";
```

Key types exported alongside: `AtUri`, `DidDocument`, `PdsRecord`, `RepoStatus`, `BacklinkRecord`, `BacklinksPage`, `DistinctPage`, `ManyToManyPage`, `LinksAllEntry`, `RefreshContext`, `ErrorCategory`.

Data sources:

- **Records** — PDS, discovered from the DID document (`plc.directory` for `did:plc:*`, `/.well-known/did.json` for `did:web:*`), then `com.atproto.repo.getRecord` / `listRecords`.
- **Engagement** — Constellation (`https://constellation.microcosm.blue` by default).

No calls to `public.api.bsky.app`.

## Framework integration

### Astro

Astro SSRs by default; custom elements need a browser. Render markup server-side, load the script client-side:

```astro
---
const handle = "iammatthias.com";
---
<atproto-profile src={handle}></atproto-profile>
<atproto-feed src={handle} limit="20"></atproto-feed>

<script>
  import "atproto-wc/browser";
</script>
```

### Next.js (app router)

Mark the importing component as client:

```tsx
"use client";
import { useEffect } from "react";

export default function PostEmbed({ src }: { src: string }) {
  useEffect(() => {
    import("atproto-wc/browser");
  }, []);
  return <atproto-post src={src} />;
}
```

### Vite / plain ESM

```ts
import { defineAll } from "atproto-wc";
defineAll();
```

### TypeScript

Custom elements aren't in the default JSX intrinsic types. If you're using TS with React or a JSX-based framework and the compiler complains, declare the intrinsic element:

```ts
declare namespace JSX {
  interface IntrinsicElements {
    "atproto-post": { src: string; compact?: boolean; "no-counts"?: boolean };
    "atproto-profile": { src: string };
    // ...extend as you use them.
  }
}
```

## Common gotchas

- **`src="handle"` on a post-level element won't work** — posts need a specific rkey. Handles only work for repo-level elements (profile, feed, followers, repo, blobs, etc.). For posts, pass an AT-URI or bsky.app URL.
- **Engagement counts fire 4 Constellation requests per post.** If you render a long feed and don't need counts, pass `no-counts` on `<atproto-post>` — it saves `4 × N` calls.
- **Rendering across a VPN / private PDS** — handle resolution hits `/.well-known/atproto-did` on the handle's domain. If that host is private, use the DID directly (or an AT-URI) to skip the lookup.
- **Server-side rendering** — these elements do not render content during SSR; they render skeleton markup and hydrate in the browser. Plan layout around the skeleton dimensions if CLS matters.
- **React + custom element attributes** — kebab-case attributes (`no-counts`, `show-count`) pass through React as-is on string props. Boolean props: pass the empty string (`""`) or the attribute name as its own value to enable.
- **Constellation is a public service.** For high-traffic sites, host your own and point via `setConstellationEndpoint()` or the per-element `constellation="..."` attribute.
- **The elements aren't a bsky.app clone.** Moderation labels, AppView-derived feed shapes, and algorithmic recommendations aren't here — by design.

## Where to find more

- [atproto-wc.com](https://atproto-wc.com/) — homepage with every element linked to its doc page.
- [atproto-wc.com/styling](https://atproto-wc.com/styling) — tokens and parts reference plus four worked themes.
- [atproto-wc.com/atoms](https://atproto-wc.com/atoms) — composition guide for the primitives.
- [atproto-wc.com/components/{tag}](https://atproto-wc.com/components/post) — per-element doc with live demo, attributes table, and part reference. Replace `post` with any tag suffix.
- [github.com/iammatthias/atproto-wc](https://github.com/iammatthias/atproto-wc) — source, issues.
- [constellation.microcosm.blue](https://constellation.microcosm.blue) — the default backlink index.