# Inlay

[Inlay](https://inlay.at/) lets you build social UIs from components that live on the AT Protocol.

For example, here's a Bluesky post rendered as an Inlay component:

```jsx
<mov.danabra.Post uri="at://did:plc:ragtjsm2j2vknwkz3zp4oxrd/app.bsky.feed.post/3lkqvm" />
```

The host resolves `mov.danabra.Post` and expands its template into a tree of smaller components:

```jsx
<org.atsui.Stack>
  <org.atsui.Row align="center">
    <mov.danabra.AviHandle uri="did:plc:ragtjsm2j2vknwkz3zp4oxrd" />
    <org.atsui.Caption>
      <org.atsui.Timestamp value="2026-02-17T02:11:13.240Z" />
    </org.atsui.Caption>
  </org.atsui.Row>
  <org.atsui.Link uri="at://...">
    <org.atsui.Text>hey check this out</org.atsui.Text>
  </org.atsui.Link>
  <at.inlay.Maybe>
    <mov.danabra.PostEmbed uri="at://..." />
  </at.inlay.Maybe>
</org.atsui.Stack>
```

Then `AviHandle` and `PostEmbed` expand further, and so on, until everything bottoms out in `org.atsui.*` primitives that the host renders directly into HTML, React, SwiftUI, or whatever it wants.

An Inlay component like `Post` or `AviHandle` is just a name ([NSID](https://atproto.com/specs/nsid)) — anyone can publish an implementation for it, and a *host* (i.e. a browser for Inlay) picks which implementation to use, potentially taking both developer and user preferences into account.

## Packages

| Package | Description |
|---------|-------------|
| [`@inlay/core`](packages/@inlay/core) | Element trees, JSX runtime, and serialization |
| [`@inlay/render`](packages/@inlay/render) | Server-side component resolution |
| [`@inlay/cache`](packages/@inlay/cache) | Cache policy for XRPC component handlers |

## How it works

Each component is an [`at.inlay.component`](https://pdsls.dev/at://did:plc:mdg3w2kpadcyxy33pizokzf3/com.atproto.lexicon.schema/at.inlay.component#schema) record with one of three body kinds:

- **No body** — a primitive. The host renders it directly.
- **Template** — a stored element tree with Binding placeholders that get filled in with props.
- **External** — an XRPC endpoint that receives props and returns an element tree.

Each component also imports an ordered list of DIDs. When the host needs to resolve a child NSID, it walks the import list and looks up `at://{did}/at.inlay.component/{nsid}` — first match wins.

[Atsui (`org.atsui`)](https://pdsls.dev/at://did:plc:e4fjueijznwqm2yxvt7q4mba/com.atproto.lexicon.schema) is the first design system for Inlay — including `<Text>`, `<Avatar>`, `<List>`, and others. In a sense, it's like Inlay's HTML. Atsui is not a traditional component library because it solely defines *lexicons* (i.e. interfaces). Each host (an Inlay browser like [inlay.at](https://inlay.at/)) may choose which components are built-in, and how they work. A host could even decide to not implement Atsui, and instead to implement another set of primitives.

A host chooses its own tech stack. For example, you could write a host [with Hono and htmx](./proto), or [with React Server Components](./app), or even with SwiftUI and a custom server-side JSON endpoint. The resolution algorithm is shared, but each host may interpret the final tree as it wishes.

## Declaring components

There is no visual editor yet. Components are created by writing records to your PDS.

### Pick an NSID

An NSID describes *what* a component does, not *how*. If someone already defined one that fits (e.g. `com.pfrazee.BskyPost` with a `uri` prop), you can implement it yourself. Multiple implementations of the same NSID can coexist — the importer's DID list controls which one gets used.

If you're creating a new NSID, pick one under a domain you control so you can [publish a Lexicon](https://atproto.com/specs/lexicon#lexicon-publication-and-resolution) for it later.

### Component record

This is the record you write to your PDS.

#### Template

The element tree lives inside the record. Bindings are placeholders that get filled in with props at render time.

```json
{
  "$type": "at.inlay.component",
  "body": {
    "$type": "at.inlay.component#bodyTemplate",
    "node": {
      "$": "$", "type": "org.atsui.Stack", "props": {
        "gap": "small",
        "children": [
          {
            "$": "$",
            "type": "org.atsui.Text",
            "props": { "children": ["Hello, "] },
            "key": "0"
          },
          {
            "$": "$",
            "type": "org.atsui.Text",
            "props": { "children": [ { "$": "$", "type": "at.inlay.Binding", "props": { "path": ["name"] } } ] },
            "key": "1"
          }
        ]
      }
    }
  },
  "imports": [
    "did:plc:mdg3w2kpadcyxy33pizokzf3",
    "did:plc:e4fjueijznwqm2yxvt7q4mba"
  ]
}
```

The `imports` array lists the DIDs your component needs for resolution — typically the [Atsui DID](https://pdsls.dev/at/did:plc:e4fjueijznwqm2yxvt7q4mba) so you can use [`org.atsui.*` primitives](https://pdsls.dev/at://did:plc:e4fjueijznwqm2yxvt7q4mba/com.atproto.lexicon.schema). The record's rkey is the NSID it implements (e.g. `mov.danabra.Greeting`), so the full URI is `at://{your-did}/at.inlay.component/mov.danabra.Greeting`.

When [rendered](packages/@inlay/render) as `<mov.danabra.Greeting name="world" />`, this component resolves to:

```jsx
<org.atsui.Stack gap="small">
  <org.atsui.Text>Hello</org.atsui.Text>
  <org.atsui.Text>world</org.atsui.Text>
</org.atsui.Stack>
```

#### External

As an alternative to templates (which are very limited), you can declare components as [XRPC](https://atproto.com/guides/glossary#xrpc) server endpoints. Then the Inlay host will hit your endpoint to resolve the component tree.

Here's a [real external component record](https://pdsls.dev/at://did:plc:fpruhuo22xkm5o7ttr2ktxdo/at.inlay.component/mov.danabra.Greeting) for `mov.danabra.Greeting`. Notice its `body` points to a service `did` instead of an inline `node`:

```json
{
  "$type": "at.inlay.component",
  "body": {
    "$type": "at.inlay.component#bodyExternal",
    "did": "did:web:gaearon--019c954e8a7877ea8d8d19feb1d4bbbb.web.val.run"
  },
  "imports": [
    "did:plc:mdg3w2kpadcyxy33pizokzf3",
    "did:plc:e4fjueijznwqm2yxvt7q4mba"
  ]
}
```

The `did` is a `did:web`, so the host resolves it by fetching [`/.well-known/did.json`](https://gaearon--019c954e8a7877ea8d8d19feb1d4bbbb.web.val.run/.well-known/did.json) to find the service endpoint, then POSTs props to `/xrpc/mov.danabra.Greeting` and gets back `{ node, cache }`.

This particular handler runs on [Val Town](https://www.val.town/x/gaearon/greeting-jsx/code/main.tsx):

```tsx
/* @jsxImportSource npm:@inlay/core@0.0.13 */
import { component, serve } from "https://esm.town/v/gaearon/inlay/main.ts";
import { Stack, Text } from "https://lex.val.run/org.atsui.*.ts";

component("mov.danabra.Greeting", ({ name }) => (
  <Stack gap="small">
    <Text>Hello,</Text>
    <Text>{name || "stranger"}</Text>
  </Stack>
));

export default serve;
```

It's recommended to tag XRPC return values as cacheable; see [`@inlay/cache`](packages/@inlay/cache) for how to do this. In the calling code, it's recommended to wrap XRPC components into `<at.inlay.Loading fallback=...>` so that they don't block the entire page.

### Lexicon (optional)

A [Lexicon](https://atproto.com/specs/lexicon) defines the prop schema for an NSID. You don't need one to get started, but publishing one enables type checking, validation, and codegen with [`@atproto/lex`](https://www.npmjs.com/package/@atproto/lex):

```json
{
  "lexicon": 1,
  "id": "mov.danabra.Greeting",
  "defs": {
    "main": {
      "type": "procedure",
      "input": {
        "encoding": "application/json",
        "schema": {
          "type": "object",
          "required": ["name"],
          "properties": {
            "name": { "type": "string", "maxLength": 100 }
          }
        }
      },
      "output": {
        "encoding": "application/json",
        "schema": { "type": "ref", "ref": "at.inlay.defs#response" }
      }
    }
  }
}
```

See [`@inlay/core`](packages/@inlay/core) for JSX support and more ways to build element trees.

## Rendering as a host

A host walks an element tree, resolves each component through its import stack (DIDs), and maps the resulting primitives to output (HTML, React, etc).

[`@inlay/render`](packages/@inlay/render) does the resolution step — call `render()` on an element, get back the expanded tree or a primitive. The host calls it in a loop until everything is resolved. The [render README](packages/@inlay/render) has a minimal working example that turns Inlay elements into HTML.

If you're writing XRPC component handlers, [`@inlay/cache`](packages/@inlay/cache) lets you declare cache lifetime and invalidation tags (`cacheLife()`, `cacheTagRecord()`, `cacheTagLink()`). The host uses these to know when to re-render.

[`proto/`](proto/) is a prototype host built with Hono and htmx.

## Development

```bash
npm install
npm run dev         # start the Next.js dev server (Turbopack)
npm run build       # production build (Next.js)
npm run typecheck   # type-check
npm run lint        # lint
```

## Project structure

```
app/                      — Next.js app (host UI, routes, pages)
packages/@inlay/core/     — element primitives and JSX
packages/@inlay/render/   — rendering engine
packages/@inlay/cache/    — cache declarations
db/                       — database schema (Drizzle)
ingester/                 — AT Protocol firehose ingester
invalidator/              — cache invalidation service
proto/                    — prototype host server (Hono)
lexicons/                 — AT Protocol lexicon definitions
generated/                — generated TypeScript from lexicons
```

## License

MIT