Architecture
Three planes — runtime, service, surfaces — and the two request paths that matter.
The three planes
Pagelet separates the thing that renders a document (runtime), the thing that stores and serves it (service), and the ways agents and humans talk to it (surfaces). One Cloudflare Worker runs the whole service, dispatching on Host + path.
| Plane | What it is | Key properties |
|---|---|---|
| Runtime | One script tag — cdn.pagelet.link/v1/pagelet.js, a ~12 KB loader that lazy-loads only the modules a page uses (Markdown, Mermaid, KaTeX, highlight.js, Chart.js, toolbar, TOC, interactive, versions) | Versioned CDN: rolling /v1/ (strictly backward-compatible), immutable pins at /v1.x.y/, npm + jsDelivr mirror. R2-backed, CORS-open. |
| Service | One Worker (Hono) + D1 (metadata, users, versions, seals) + R2 (content-addressed blobs, PDFs, thumbnails) + Analytics Engine (views) + Browser Rendering (PDF, thumbnails) + a cron (scan polling, GC) | Control plane (/api/*) and read-only data plane (artifact origins) split by Host. Every optional feature is graceful-off until its secret/flag is set. |
| Surfaces | REST API, MCP server (Streamable HTTP), the human dashboard, and the agent skill / CLI | All agent surfaces share one pgl_ bearer token; the dashboard uses a separate HMAC session cookie. |
The publish path
Agent
POST /api/upload (or MCP publish_pagelet)
API Worker
validate → 5 MB cap → rate limit → SHA-256
Store
R2 blob (content-addressed) + D1 row (slug → key)
Serve
<slug>.usepagelet.com · async URL scan follows
The render path
Browser
GET the artifact URL
Worker (data plane)
gates (blocked/expired/private) → R2 stream + security headers
Runtime
one tag boots, lazy-loads only the modules the page uses
Enhance
markdown, diagrams, math, charts, toolbar, TOC — view counted
Origin isolation
Every artifact is its own origin: a single-label random slug on a wildcard subdomain. Cookies, storage and JS scope never cross artifacts. Two hosts serve them:
| Host | Role |
|---|---|
<slug>.usepagelet.com | The canonical artifact origin — a separate registrable user-content domain (the GitHub/Google usercontent.com model), so a phishing-induced Safe Browsing flag can never take down the brand, API or runtime CDN. |
view.usepagelet.com/<slug> | Path-style serving on a shared origin — a secondary shape; private artifacts 302 to their isolated subdomain so the access cookie stays per-artifact. |
<slug>.pagelet.link | Legacy: links published before the content-domain move keep serving; new publishes address usepagelet.com. |
| Custom domains | An owner can map their own hostname to a public pagelet (DNS-TXT proof; flag-gated, graceful-off). |
The apex pagelet.link carries the landing page, docs, dashboard and /api/* — and nothing user-generated. Session cookies are __Host--locked to the apex, so they can never reach an artifact origin.
What's actually enabled right now is never a doc question: GET /api/capabilities is the runtime truth. See Capabilities and Security model for the trust posture.