Highport orbital control

Tiles

A design somebody else built, left on the board for anyone to fill in. Everything it shows a visitor comes from bytes stored earlier, which is exactly why a stranger's is safe to dock.

A tile is a reusable, parameterized bundle of files published as a space.highport.sites.tile record. A theme, a landing page, a documentation layout. Anyone can write one and anyone can bind one to their own domain. A tile has no address of its own. It is never tied to a domain and never serves at one, and its author never touches the sites that use their work.

The files are static. There is no request-time execution anywhere in the system, so a tile is HTML, CSS, JavaScript, images and fonts, plus a declared list of things it asks the person binding it to supply. Everything it renders comes from the bytes its author published and the values a site owner filled in.

What is in the record

Field Required What it holds
name yes The display name. At most 1000 bytes and 100 graphemes
description no What it is for. At most 3000 bytes and 300 graphemes. Shown in the directory, rendered as text and never as markup
icon no A blob: image/png, image/jpeg or image/webp, at most 1 MiB
params no The parameters the tile declares. At most 32, and names are unique within a tile
content yes The manifest: the files, keyed by the path each one answers at

content is a space.highport.sites.defs#manifest, the same type a site record uses for its own inline files, and the same rules apply to both. Each entry is a path beginning /, a src blob, and optionally a contentType, a contentEncoding of gzip, br, zstd or identity, and a status of 200, 404 or 410.

Three things are true of a tile's manifest and not of a site's. It must carry a name. It must have a / entry, because every tile serves something at its root. And it has no siblings: a tile record has no redirects, no notFound, no wellKnown and no access, because those are the binding site's to decide, whatever source it uses.

The manifest's name is what the directory lists the tile under. The record's name is the fallback used only when the manifest declares none. Publishing tools set both to the same string, which is why the difference rarely shows.

The shared limits are the site limits: at most 10,000 entries, and 1 GiB of blob bytes in total.

The key is a TID

A tile's record key is a TID, a timestamp identifier and not a name you choose, so the AT-URI reads:

at://did:plc:ksqozp2qimwzivua3b4ekowe/space.highport.sites.tile/3mukf72w3nvdh
      

It is the Hello, World! tile, and it is real. Nothing in the key says anything about the tile, which means an author may publish as many as they like without ever having to invent names that do not collide. An account may hold twenty by default, and republishing an existing tile takes no new slot.

A new version is a write to the same key. Every version is indexed and stays indexed, and a site may pin any of them, not only the newest. Versions, edits and the long life of a tile covers that story.

Binding by CID

When a site binds a tile, its source becomes a com.atproto.repo.strongRef carrying a uri and a cid. The cid is the binding and the uri is provenance. There is no URI-only form, and cid is never optional. The site pins that exact version by content hash, and everything else on this page rests on that one fact.

A tile author cannot change a live site and cannot take it away from anybody. The bytes are obtained for the exact version the site named, re-hashed, and refused if they do not match. Every version that has been indexed is a permanent row, and we keep its record and its files instead of going back to the author for them.

Who may publish one

Tile storage is gated on the author's identity, and the reason is storage and not taste. We fetch a tile's blobs eagerly and keep them forever, so that a site can still bind a version after the author's account has collected the originals. An ungated collection would be free durable storage for the whole network.

Policy Who is admitted
registered (the default) An identity holding at least one claimed domain registration: pending, verifying, verified, active or failed. A suspended or released one is not a claim
verified An identity whose registration has passed verification, or is active
allowlist Only the identities the operator names
open Anyone. The quotas are then the only bound

The operator's allowlist is consulted before the policy under every setting, so an allowlisted author is admitted whichever of the four is in force. Here the policy is registered: claiming a domain is enough, and it does not have to be verified.

An author the policy excludes is refused with TileAuthorNotPermitted, at HTTP 403. Validation is the authority and answers the same name before anything is written, so you find out before you publish instead of after. See validate before you write.

Eligibility counts forward only. A tile published before its author became eligible is not picked up retroactively. It was refused when its commit went by, and nothing revisits it. Publishing a new version of it, meaning a fresh commit at the same key, is what gets it in.

The runtime contract

There is no server-side templating, so a tile does not receive its parameters as substituted text. It imports them, at runtime, from modules Highport writes alongside it on the site's own origin, at the paths the DASL Tiles Protocols reserve for a host.

Path Content type What is in it
/.well-known/web-tiles/data.js text/javascript; charset=utf-8 tp-data: the resolved parameters, keyed by the tile's declared names, delivered to the tile's handler
/.well-known/web-tiles/site.js text/javascript; charset=utf-8 getSite(): what the site is, meaning the domain, the record, and the tile and version bound
/_bard/params/{name}{pointer} The blob's own type The bytes of one blob inside a bound parameter value

All three are ordinary snapshot entries, written when the site is built. They carry an ETag of their content hash, honour Range, compress like anything else, and take the site's ordinary cache setting, which is public, max-age=60 by default. The origin cannot tell them apart from publisher files, and neither can a browser.

Both modules exist for an inline site too, with data.js delivering {}, so a tile, and anything else reading a site here, can import them unconditionally instead of branching on a 404. One further module, xrpc.js, is written by Highport's edge rather than into the snapshot; The XRPC module below has it. Any other name under /.well-known/web-tiles/ answers 404, which is how the Tiles Protocols say a host signals a protocol it does not provide, and no site or tile may ship a file there: validation refuses the key.

Import them from your own script. The security policy every site carries permits it exactly as written, with no exception needed, and building a tile has the lines that do it.

Two modules and an import. The whole runtime is that short, and the shortness is the feature.

The parameter payload

data.js delivers the site record's parameters, resolved. A record supplied by reference has been dereferenced and replaced by the record itself, and everything else is passed through as written. A parameter the owner did not supply is simply absent. There are no defaults anywhere in the system, so the tile's own code decides what to do without it, and the parameter's description is where the author says so.

Function What it does on a Highport site
addDataHandler(h) Registers h. If the payload has already been delivered, calls h with a copy straight away
removeDataHandler(h) Unregisters h
listen() On the first call, downloads the blob parameters, then calls every handler with its own copy of the payload. A later call delivers the same payload again
sendData(p) Nothing. A published site has no host to send data to

For a site binding a tile that declares a required string, an optional string, a blob and an array of strings, a handler receives:

{
        avatar: Blob { size: 86491, type: 'image/png' },
        links: ['Bluesky|https://bsky.app/profile/example.com', 'Email|mailto:hello@example.com'],
        name: 'Example Person',
        tagline: 'Builds things.',
      }
      

For an inline site, and for a bound site whose owner supplied nothing, it is exactly {}. The values are embedded in the module when the site is built, so they are a function of the record and not of when it is read, and a site republished unchanged produces the same module with the same hash.

A blob parameter's bytes

A blob arrives as a Blob holding its bytes, not as the reference the record stores. Every blob inside a resolved parameter is materialized as an entry of its own at /_bard/params/{name}{pointer}, where the pointer is the RFC 6901 JSON Pointer to that blob within the value, and listen() fetches each one from there, with the site's cookies, before the first delivery. A blob that cannot be fetched is delivered as null, with one warning in the console; listen() does not throw. The typed paths stay for HTML and CSS that name a blob with no script. Building a tile has the pointer cases, what the security policy allows a Blob to be used for, and the code that reads them.

The site module

getSite() resolves to the site's own provenance, and its field list is fixed:

{
        "builtAt": "2026-09-05T14:22:03.417Z",
        "did": "did:plc:nysigjs52ta6f2l7fdnevadv",
        "domain": "example.com",
        "parameterSources": {},
        "recordCid": "bafyreih3pwz7hzr6o65ldhhbuwb33wlvc6pn6mcflwxdqxty4e4odeugue",
        "rev": "3lrevaaaaaa2z",
        "source": {
          "kind": "tile",
          "tile": {
            "cid": "bafyreidxtoefolv2m3qauufam5zqqmg3spgennhnv4owsoshjvqtilzlfi",
            "did": "did:plc:ksqozp2qimwzivua3b4ekowe",
            "name": "Card",
            "uri": "at://did:plc:ksqozp2qimwzivua3b4ekowe/space.highport.sites.tile/3mukf72w3nvdh"
          }
        },
        "uri": "at://did:plc:nysigjs52ta6f2l7fdnevadv/space.highport.sites.site/example.com"
      }
      

(Identifiers illustrative; the shape is exact.)

parameterSources carries an entry only for a value the owner supplied by reference, keyed by its pointer, naming the record and the version pinned. An inline value is absent from it. source is {"kind": "inline"} for an unbound site, and the nested form above for a bound one. A site published from a space carries one further key, space. site.js always describes the version being served, which is the one the visitor is reading; space.highport.sites.getSite describes the active version and is what software outside the site should ask.

The XRPC module

/.well-known/web-tiles/xrpc.js calls the XRPC queries the site's host answers about itself, at /_bard/xrpc/<NSID> on the same origin, for what changes after the site was published. It is not part of the snapshot: Highport's edge writes it, the same for every site, so it is the one module that can change without the site being republished. Calls are unauthenticated, because the site's sign-in grants Highport nothing to call with on a visitor's behalf. Nothing behind /_bard/xrpc/ reaches another host, with one exception a host may turn on: the owner reads, which ask the site owner's own PDS for the owner's own records and nothing else.

Export What it does
query(nsid, params, options) A GET. params become the query string, and an array repeats its key. Resolves with { ok, status, headers, encoding, body }; rejects with an XrpcError for any status outside 200–299
procedure(nsid, input, options) A POST. The host serves no procedure, so today this always rejects with MethodNotImplemented
call({ nsid, method, params, input, encoding, headers, signal }) The general form. It resolves for any HTTP status, so check ok, and rejects only when no response arrived or the call could not be made: an invalid NSID, a method other than GET or POST, or byte input with no encoding
fetchHandler(pathname, init) A fetch handler for atproto clients that take one, such as new Client({ handler: fetchHandler }) in @atcute/client: /xrpc/<NSID>… is sent to /_bard/xrpc/<NSID>…, and the response comes back as it arrived
methods A frozen map of every NSID the host serves to 'query' or 'procedure'. Check it before offering an action that needs a method, and hide the action when the method is absent
XrpcError status, headers, and the error and message of the XRPC error body

Only content-type and accept are sent from the headers you pass; authorization, cookie, dpop and atproto-proxy are dropped, and the host refuses a call that carries them anyway. The site cookie goes with every call, because the methods that answer about the visitor read it. body is parsed JSON for application/json, a Blob for anything else, and null when empty; headers carries content-type, etag and retry-after.

error status When
MethodNotImplemented 501 The host does not serve that NSID, whatever the HTTP method
InvalidRequest 405 A query called with anything but GET or HEAD
InvalidRequest 400 Bad parameters, or an authorization, dpop or atproto-proxy header
Forbidden 403 The request came from another site's page (see below)
null 401, 402 The site's own access rules refused it, as they would refuse its pages. The body is the gate's, not an XRPC error
TransportError 0 No response: the network failed, or a gated path answered with a redirect to sign-in, which the module never follows
RateLimitExceeded 429 The calls from this reader to this site exceeded their budget. The edge sends no XRPC body, so the module names the error from the status; headers['retry-after'] says when to try again
SiteNotFound, TileNotFound 404 A directory method found nothing it may show, as highport.space answers
RecordNotFound 400 com.atproto.repo.getRecord found no record it may show, or cid is not the current version; a 400, as from a PDS
BlobNotFound 400 com.atproto.sync.getBlob was asked for an image the site owner's current records do not name, or one their PDS no longer holds
UpstreamFailure 502 An owner read could not reach the site owner's PDS. Only this call failed; nothing is cached, so asking again later can succeed
InternalError 500 The host could not read its index or its content store. Only this call failed
AbortError 0 Your AbortSignal fired

The methods answer only the site's own pages. No CORS header is ever sent, and a request whose Sec-Fetch-Site is anything but same-origin or none is refused with 403, including same-site: until highport.site is on the Public Suffix List, every address under it is one site to a browser, and one site's page must not spend another's limits. A request with no Sec-Fetch-Site at all, as from curl, is allowed. Every call passes the same gate as a file on the site, so a site that requires sign-in from its root requires it of these calls too, and each call counts toward the site's consumption like a file request.

NSID What it answers
space.highport.sites.getVisitorAccess The visitor's access to this site: member, true when the site's members-only pages admit them and false when they do not. It is absent for a reader who is not signed in, and on a site with no members-only pages, because membership is checked only where a page needs it. Never cached, and never served by highport.space, because it describes a session only this site holds
space.highport.sites.getSite, listSites, getTile, listTiles, getTileIcon, getWebTile, listWebTiles The public directory: this site or another, who is serving a tile, a tile's name, description and parameters, its icon, and the Web Tile index. The same answers highport.space gives, except that a tile's handle is never present here, so show the author's DID. getSite needs domain; pass location.hostname for the site itself, though site.js is the authority on the build being served
com.atproto.repo.getRecord, listRecords A site, tile or ing.dasl.masl record by its AT-URI parts, for a tile that already speaks atproto. Answered from Highport's index, so a record can lag its repository and only what the directory shows is found; the XRPC page has where these differ from a PDS

Each node keeps a successful directory answer for 30 seconds and tells the browser max-age=15, so a change reaches a reader within 45 seconds. Ask again when it matters rather than polling faster.

The owner reads

Where the host has turned them on, three calls read the site owner's own records live from the owner's PDS, so a page can show the owner's current profile, and their rpg.actor character, without being republished. Check methods['com.atproto.sync.getBlob']: it is present exactly where the owner reads are.

Call What it answers
com.atproto.repo.getRecord with collection app.bsky.actor.profile or actor.rpg.sprite, rkey self The owner's profile, or their rpg.actor sprite sheet's record
com.atproto.repo.getRecord or listRecords with collection actor.rpg.stats The owner's rpg.actor character sheets, one per game system's key; a page holds at most 10
com.atproto.sync.getBlob with did and cid An image those records name: the profile's avatar or banner, or the sprite's spriteSheet, as image/png, image/jpeg, image/webp or image/gif. Use the URL as an <img> source on the page; img-src 'self' permits it

repo and did must be the site owner's DID, which site.js's getSite() gives as did; anybody else's is refused with InvalidRequest. Answers are in the PDS's own shapes. Each node keeps a record for a minute and an image for an hour, and tells the browser max-age=15 for a record, so an edit to the profile shows within about a minute and a quarter. An image's URL names its CID, so the browser keeps it for a year.

const { getSite } = await import('/.well-known/web-tiles/site.js');
      const { did } = await getSite();
      if (xrpc.methods['com.atproto.sync.getBlob']) {
        const { body } = await xrpc.query('com.atproto.repo.getRecord', {
          repo: did,
          collection: 'app.bsky.actor.profile',
          rkey: 'self',
        });
        const avatar = body.value.avatar?.ref?.$link;
        if (avatar) img.src = `/_bard/xrpc/com.atproto.sync.getBlob?did=${did}&cid=${avatar}`;
      }
      
const xrpc = await import('/.well-known/web-tiles/xrpc.js');
      if (xrpc.methods['space.highport.sites.getVisitorAccess']) {
        const { body } = await xrpc.query('space.highport.sites.getVisitorAccess');
        // body.member: true or false on a site with members-only pages, absent otherwise
      }

      // The same host, through an ordinary atproto client.
      import { Client } from '@atcute/client';
      const rpc = new Client({ handler: xrpc.fetchHandler });
      const { data } = await rpc.get('com.atproto.repo.getRecord', {
        params: { repo: 'did:plc:…', collection: 'space.highport.sites.tile', rkey: '3mukf72w3nvdh' },
      });
      

On a host that answers no methods, such as a self-hosted single-site server, methods is empty and every call answers 501, so a tile that checks methods first keeps working there.

The identity module

/.well-known/web-tiles/identity.js says who is signed in on this site, for the page that imports it. Like xrpc.js it is written by Highport's edge rather than stored with the site, and it is written for each request: it is never cached, because it describes one reader.

const { getIdentity } = await import('/.well-known/web-tiles/identity.js');
      const me = await getIdentity();
      // null when nobody is signed in on this site
      // { did: 'did:plc:…', handle: 'alice.example' } when somebody is
      // handle is null when the handle does not resolve back to the same DID
      

The handle is checked in both directions before it is given to you: the DID document names it, and the handle resolves back to the same DID. A check that fails, or does not finish within two seconds, gives handle: null, so show the DID instead. The reader's session is the site's own sign-in, so a reader signed in on another site is nobody here. Sign-in and sign-out are page navigations, so the next page imports a fresh answer. On a host with no sign-in, such as a self-hosted single-site server, getIdentity() always resolves to null.

identity.js is how page code learns who is reading; getVisitorAccess through xrpc.js is how it learns whether the site's members-only pages admit them.

Before the modules: params.json and site.json

/_bard/params.json and /_bard/site.json are what tiles read before data.js and site.js existed. Both have been removed. Every site answers 404 for them, including sites built before the removal, so a tile version that still reads them renders without its parameters until its site binds a newer version. params.json was the object data.js delivers with each blob left as its reference, and site.json was getSite() plus parameterBlobs, an index of the typed paths that Blob delivery makes unnecessary.

Sign-in, if the tile wants it

A tile that needs to know who is looking imports identity.js for the signed-in reader and calls space.highport.sites.getVisitorAccess through xrpc.js for whether the site's members-only pages admit them. For a sign-in link it can include /_bard/auth/widget.js with a data-bard-auth mount. All of them are on the publisher's own hostname, so script-src 'self' and connect-src 'self' permit them as written. An anonymous reader is null from identity.js, not an error. /_bard/auth/status, which answered the same questions in one document, has been removed; read identity.js and getVisitorAccess instead. Nothing is injected into a page: the <script> tags are in the tile's own markup, so the bytes a visitor receives are the bytes the published version describes. Asking visitors to sign in is the site owner's half of it.

Everything else under the prefix

The whole /_bard/ prefix is reserved at validation time, for every record, and a manifest key or a redirect under it is refused as ReservedPathCollision. So nothing published can shadow these paths, and a request under the prefix that names no entry is a bare 404: text/plain, empty body, and never the site's notFound resource, whatever status that resource carries.

What a tile cannot do

Every response we serve carries a content security policy, and it is ours. No record field, manifest entry, header or setting reaches it, and nothing a tile publishes can loosen it. No directive in it names a remote source. A tile's scripts, styles, fonts, images and media come from the site's own origin or from a data: or blob: URL, and fetch, XHR and WebSocket reach that origin and nothing else.

It is more permissive than "nothing runs" suggests, and an author needs the real shape rather than the slogan. Inline <script> and <style> are permitted, which is what lets a single-file tile work at all. So are WebAssembly and a worker started from a blob: URL. What is refused is every address that is not the site's own: no CDN library, no tag manager, no analytics bundle, no font host, no hotlinked image, no framed third party. <object> and <embed> are refused outright, the document base URI cannot be rewritten, and a form posts to the site's own origin or nowhere. frame-ancestors is deliberately absent, so a site may be framed by others. Safety, and what cannot happen prints the policy and the three headers fixed beside it, and building a tile is the same policy from the inside, where you are the one writing against it.

Beyond the policy: nothing a tile contains is executed on our side, because there is no request-time execution on the origin. Parameters are data and never template, so every file still serves byte-identical to its hash. Nothing the origin serves is per-visitor, no cookie is read or set there, and a tile cannot show one visitor something different from another. Anything but GET or HEAD is a 405 with Allow: GET, HEAD. And Content-Type is the one response header a publisher shapes at all, through a manifest entry's contentType, re-validated as a media type when the file is served.

This is what makes a tile from a stranger safe to bind, and it is the reason anybody binds yours.

When a file is missing

If we cannot fetch one of the files a tile's record names, that version is indexed as incomplete. The record is fine, the bytes are not. It is not rejected, because "this tile does not work" and "this tile does not exist" are different answers. But the directory stops listing it, no site can bind it, and a site that tries is refused with TileInvalid and a message naming the blobs we never obtained. Nobody but the author can repair it, and only by publishing a new version. Versions, edits and the long life of a tile has the whole of that, including the icon, which is fetched beside the file set rather than inside it and so can go missing without making a version incomplete.

The states a version can hold

State What it means Can a site bind it?
pending-publication Validated and prepared. We hold the bytes; the record has not arrived from the author's account yet No. TileNotReady
ready Everything is held. Listed in the directory and the picker Yes, and it is the only one
incomplete A file could not be fetched, so the version cannot be served whole No. TileInvalid, with the missing blobs named
suspended An operator has stopped it taking new bindings. Sites already bound go on serving No. TileSuspended
deleted The author deleted the record. Sites already bound go on serving, because they hold it by hash No

space.highport.defs#tileView declares indexing and rejected as well, and nothing writes either. A version whose job has not finished has no row at all, so space.highport.sites.getTile answers TileNotFound instead of a state.

The directory and the picker list ready versions only, because offering any of the others is offering a choice that fails at publish. getTile does not filter on state, so an incomplete, suspended or deleted version still has a page of its own, and an author following a link to one gets the word instead of a blank.

Where to go next

Building a tile is the practical half: writing the files, the path rules, reading parameters at runtime, and getting the record published. Parameters is the full declaration, with the types, the constraints, and the form each one becomes for the person binding your work. Versions, edits and the long life of a tile covers publishing a new version, why bound sites do not move, and what deleting does and does not take with it.

If you are choosing a tile rather than writing one, using a tile on your site is the shorter road.

Tiles · 1 of 4