# Threetopia

> Creator platform for reusable Three.js assets and fixed-tile world packages. The public shared world is currently a map preview, not a released playable world.

A world package requires a tile selected and reserved BEFORE creation. Threetopia owns the immutable host tile. Every world requires detailed world content, simplified map content and overview content. CLI and server enforce actual geometry, budgets, tile ownership and the canonical contract. Authenticate through email and browser-approved CLI login. Do not invent package names or assume npm publication.

## Start here
- [Your first package](https://docs.threetopia.com/quickstart.md)
- [Accounts and CLI authentication](https://docs.threetopia.com/accounts.md)
- [Your creator studio](https://docs.threetopia.com/creators.md)
- [Fixed tiles and shared edges](https://docs.threetopia.com/tiles.md)
- [World package contract](https://docs.threetopia.com/world-packages.md)
- [Preview before publishing](https://docs.threetopia.com/preview.md)
- [Geometry and performance budgets](https://docs.threetopia.com/validation.md)
- [Versions, states and changelogs](https://docs.threetopia.com/publishing.md)
- [CLI reference](https://docs.threetopia.com/cli.md)
- [Registry API](https://docs.threetopia.com/api.md)

## Reusable packages — consult before generating assets
- [Package installation and reuse](https://docs.threetopia.com/packages.md): exact versions, exports, dependency locks, recorded installations.
- [Live reusable asset catalog](https://creators.threetopia.com/api/packages?kind=asset): query real published packages; never guess names.
- [Original Threetopia beacon](https://creators.threetopia.com/api/resolve?name=%40threetopia%2Fbeacon&version=1.0.0): MIT example with map and world exports.
- [Creator package browser](https://creators.threetopia.com/catalog)

## Contracts and tools
- [Package JSON schema](https://docs.threetopia.com/schema/package.json)
- [Current tile positions and 144 variants](https://creators.threetopia.com/api/tiles)
- [Standalone CLI v0.2.3](https://docs.threetopia.com/downloads/threetopia-cli-0.2.3.tgz): install with npm install -g URL; not yet on npm registry.
- [SDK v0.2.2](https://docs.threetopia.com/downloads/threetopia-sdk-0.2.2.tgz): canonical terrain and geometry validator.
- [Full documentation](https://docs.threetopia.com/llms-full.txt)


# Build a piece of Threetopia

Create reusable assets. Give your world a place in the shared map. Build with other creators’ packages.

Threetopia has two package types: **asset packages** contain reusable models, textures, materials or code. **World packages** fill the protected content slot of a Threetopia tile. Every world package must contain a world GLB, a lightweight map GLB and an overview GLB.

The public site at [world.threetopia.com](https://world.threetopia.com) is a **map preview**. A shared playable world is not released yet. Publishing a world package places its map content on the shared map; it does not make it a playable online world.

## Start with your place

1. [Sign in to your creator studio](https://creators.threetopia.com).
2. Choose your permanent creator handle.
3. [Choose a tile](https://creators.threetopia.com/tiles), explore its terrain variations, and reserve it.
4. Create a world package for that reservation.
5. Clone it with the CLI, replace the starter content, preview and validate.
6. Push a private version. Publish it when ready.

For reusable assets, start with **New asset**. You do not need a tile.

[Follow the quickstart →](/quickstart)

## Build together

[Explore reusable packages](https://creators.threetopia.com/catalog) or query the [public package catalog](https://creators.threetopia.com/api/packages?kind=asset). The CLI downloads exact versions, checks every file’s SHA-256, resolves dependencies, and records the installation under your public creator handle.

```sh
threetopia search beacon
threetopia install @threetopia/beacon@1.0.0
```

## For AI coding agents

Start with [llms.txt](/llms.txt). Read [the world package contract](/world-packages.md), [validation rules](/validation.md) and [reusable packages](/packages.md) before generating content. Choose a tile before creating a world package. Do not alter the host geometry or invent package names.


---

# Your first package

You need Node.js **22.13 or later**, a browser, and an email address you can access.

## Install and sign in

```sh
npm install -g https://docs.threetopia.com/downloads/threetopia-cli-0.2.3.tgz
threetopia login
```

The CLI opens a browser. Sign in with your email code, choose your creator handle, and approve the code shown in your terminal. It does not ask for your password. Only approve a login you initiated.

The CLI is distributed as a versioned tarball from this documentation site. It is not yet published in the npm registry. Do not use `npx @threetopia/cli` without checking npm availability.

## Choose a tile first

Open [Choose a tile](https://creators.threetopia.com/tiles). Select an available position surrounding the existing worlds, switch terrain families and variants, and reserve the tile. Click **Create a world package**, give it a title and name, then copy the clone command from its page.

```sh
threetopia clone @your-handle/coral-garden
cd coral-garden
threetopia preview
```

The preview opens at `http://127.0.0.1:5195/`. Switch between World, Map and Overview. Refresh after editing.

You can also reserve from the CLI:

```sh
threetopia tiles
threetopia reserve -1,0 --variant oasis-03
threetopia create coral-garden --kind world --tile RESERVATION_ID
```

Use the actual available coordinate and returned reservation ID. The example coordinate may already be occupied.

## Fill your slot

The starter contains `content/world.glb`, `content/map.glb`, `content/overview.glb`, `tile.lock.json`, and `threetopia.json`.

Replace the GLBs with your work. Use metres for world content and map units for map content. The scale is **0.03**: one map unit represents 33⅓ world metres. The simplified map asset should be one recognisable component from your world, such as a treehouse, temple or boat.

Keep the host tile fixed. Model your content above local y=0, centred within the protected slot. The host adds its own terrain and positions your content at the slot’s floor.

```sh
threetopia check
threetopia push
```

Push uploads and validates a **private version**. Open its preview in your studio. When ready:

```sh
threetopia publish
```

## Make a reusable asset instead

```sh
threetopia create coastal-rocks --kind asset
cd coastal-rocks
threetopia preview
```

Replace the starter model, declare exported files in `threetopia.json`, and update the license and changelog. Asset packages do not reserve tiles.


---

# Accounts and CLI authentication

Your creator account is shared by the website and the CLI. Sign in at [creators.threetopia.com](https://creators.threetopia.com) using an eight-digit email code. Codes expire after ten minutes and can be used once. There are five verification attempts per code, with delivery rate limits.

Your **display name** can change. Your **handle** cannot: it identifies your package namespace, for example `@river-maker/water-lilies`. Handles contain 3–30 lowercase letters, numbers and hyphens, beginning with a letter.

Your email is private. Your handle and display name are public when you publish a package or install one. Package owners can see which creators currently have their package installed through the CLI, including exact versions and number of installations. They cannot see your email, source code, or private project names.

## Connect a terminal

```sh
threetopia login
threetopia whoami
```

The CLI uses browser approval. Compare the eight-character code in your terminal with the browser page before approving. Browser sessions last seven days; CLI tokens last 90 days.

Credentials are stored in `~/.config/threetopia/credentials.json` with file permissions `0600`. Tokens are keyed by registry origin. Set `THREETOPIA_HOME` to choose a different configuration directory.

```sh
threetopia logout
```

Logout revokes that terminal’s token. You can also revoke connected terminals under **CLI & account** in your studio. Signing out of the browser does not revoke other devices.

## Development

A local registry accepts `--registry http://127.0.0.1:55020`. HTTP is accepted only on loopback hosts. Production uses HTTPS. Development sign-in codes are returned only when the server explicitly enables local auth and the request host is loopback; production never returns a code.


---

# Your creator studio

[creators.threetopia.com](https://creators.threetopia.com) is the home for your account and packages.

## My packages

See your asset and world packages, newest version, state and installation count. Open a package to inspect every version, its changelog, server validation report and preview. Only your account can see your unpublished work.

A ready version can be published directly from its card. For a world, **Publish to this tile** releases its map content on the bound tile. The tile cannot be swapped underneath an existing package.

## Choose a tile

The studio embeds the actual Three.js map, including the existing Lagoon, Tidewater, Sakura and Punk showcase worlds. Available positions and the next expansion ring surround them. Click an available coordinate on the map or use the coordinate buttons.

The inspector lets you switch among twelve terrain families and twelve variations per family. Its 3D preview shows the exact procedural host geometry. Reserve the position and variant, then create your world package. The host terrain and slot dimensions are fixed from that point onward.

## Explore packages

Browse published packages, inspect their versions and changelogs, and copy the install command. Prefer reusable components over rebuilding them independently. Use the CLI to install exact versions into your project.

## Installed by creators

Your package page lists creators with active CLI installations, the version they use and the number of installations. These records update when a creator installs, updates or uninstalls. They are not browser analytics and do not expose private source code, project names or email addresses.

## CLI & account

Install the CLI, connect your terminal, and revoke device access. Your browser session and each CLI token are separate credentials.


---

# Fixed tiles and shared edges

Threetopia owns the host tile. Creators own the content inside its slot. The same canonical terrain recipe is used by the world preview and the map preview, scaled by 0.03.

## 144 terrain variants

The catalog contains twelve families with twelve variations each: Dunes, Oasis, Coast, Pine coast, Meadow, Highland, Volcanic, Canyon, Tundra, Blossom, Wetland and Basalt.

Variants change ridge arrangement, relief, orientation and terrain color inside the host’s terrain band. They preserve the protected slot and boundary profiles. All 144 variants can fit an available coordinate; you can inspect the actual geometry before reserving.

The four original worlds are hand-authored map scenes. Boundary profiles along their edges were sampled from the real terrain. New tiles use these profiles where they meet the original worlds; neighboring new tiles share the same edge profile. The catalog is versioned so a future terrain update does not silently change a creator’s contract.

## Coordinates and growth

Positions use axial hex coordinates `(q, r)`. The six neighbors are `(q+1,r)`, `(q,r+1)`, `(q-1,r+1)`, `(q-1,r)`, `(q,r-1)`, `(q+1,r-1)`.

Growth starts at the centre. Only the **first incomplete ring** is available. The following ring appears as a preview and opens after the inner ring is published. A reservation does not count as a published tile.

The initial occupied coordinates are Lagoon `(0,0)`, Tidewater `(1,0)`, Sakura `(0,-1)`, and Punk `(1,-1)`. The ocean surrounds the shared island.

## Reserve before creating a world

A reservation is exclusive and tied to your account. Unused reservations last seven days, with at most two unused reservations per account. Creating a world package keeps its tile reserved for that package. Another creator cannot claim or upload to it.

A world package is bound to exactly one tile. A tile can hold one world package. The selected variant is locked once reserved. To choose another variant, delete an unpublished package if necessary, release the unused reservation, and reserve again.

Published packages and their tile contracts cannot be deleted or rewritten. Publish a new content version for updates.

## The contract

`tile.lock.json` contains coordinates, variant ID, version, radius, slot dimensions, boundary profiles, recipe and SHA-256 hash. The CLI and server derive the canonical contract and reject any modification. Editing both the file and its hash does not bypass this check.

| Dimension | World | Map |
| --- | --- | --- |
| Tile corner radius | 300 m | 9 units |
| Protected content radius | 190 m | 5.7 units |
| Maximum content height | 480 m | 14.4 units |
| Host slot floor | 24 m | 0.72 units |

Content GLBs use a **local** origin at the slot floor: minimum y=0. Do not add the host floor elevation to the exported model. The host positions it for you.


---

# World package contract

A world package needs a reserved tile and **three self-contained GLBs**:

- **World content:** your detailed scene, in metres, fitting the fixed world slot.
- **Map content:** one recognisable simplified component or composition that represents your world.
- **Overview content:** a cheaper version used when viewing many tiles together.

World and map content may share source assets, but their exported size, geometry and budgets differ. Do not substitute an AI illustration for required 3D map content. Do not include the Threetopia terrain shell, ocean, sky, camera, lights or renderer in your content.

## Project manifest

The CLI creates `threetopia.json` after authenticating and checking your tile reservation. The important fields are:

```json
{
  "registry": "https://creators.threetopia.com",
  "packageId": "SERVER_ASSIGNED_ID",
  "projectId": "PROJECT_UUID",
  "manifest": {
    "schemaVersion": 1,
    "name": "@your-handle/coral-garden",
    "version": "0.1.0",
    "kind": "world",
    "title": "Coral garden",
    "description": "Treehouses around a sheltered lagoon.",
    "license": "MIT",
    "changelog": "Initial world and simplified map component.",
    "dependencies": {},
    "content": {
      "world": "content/world.glb",
      "map": "content/map.glb",
      "overview": "content/overview.glb"
    }
  },
  "files": ["content/world.glb", "content/map.glb", "content/overview.glb"]
}
```

The actual scaffold also contains the complete canonical `manifest.tile`. The CLI reads the authoritative local copy from `tile.lock.json` when checking or pushing, and the server compares it with your reservation. Do not invent IDs or generate tile contracts independently when creating a project.

Every distributed file must appear in the top-level `files` list. The CLI computes sizes and SHA-256 hashes for the upload manifest. External texture URLs and separate glTF buffers are not allowed.

## Export requirements

Use glTF 2.0 binary `.glb`, one scene, Y up, embedded PNG/JPEG textures, standard metallic/roughness materials or unlit materials. Apply transforms or export them as ordinary scene nodes. Opaque and alpha-mask materials are supported.

The first package format accepts **static exported geometry**. Skins, animations, morph targets, GPU instancing, Draco, meshopt compression, KTX2/Basis textures and custom shader extensions are rejected. Existing hand-integrated showcase worlds have their own animation adapters; that does not mean arbitrary package runtime code is executed in the shared map.

Reusable JavaScript can be distributed in asset packages and imported by developers in their own projects. The creator preview never executes uploaded package code. See [packages](/packages) and [validation](/validation).


---

# Reusable packages

An **asset package** is a versioned collection of reusable files with named exports. It can include GLB models, textures, material definitions or JavaScript. A **world package** fills an immutable host tile and must include world, map and overview content.

Find real packages in the [creator catalog](https://creators.threetopia.com/catalog), with the CLI, or through the [public asset API](https://creators.threetopia.com/api/packages?kind=asset).

```sh
threetopia search beacon
threetopia install @threetopia/beacon@1.0.0
```

`@threetopia/beacon` is an original, MIT-licensed Threetopia example. Its `model` export fits a map slot; its `world` export is scaled for world coordinates. It is an example building block, not an asset copied from a showcase creator.

## Asset manifest

```json
{
  "schemaVersion": 1,
  "name": "@your-handle/coastal-rocks",
  "version": "1.0.0",
  "kind": "asset",
  "title": "Coastal rocks",
  "description": "Low-poly rocks for coastal worlds.",
  "license": "MIT",
  "changelog": "First release of the rock collection.",
  "exports": { "model": "assets/rocks.glb" },
  "dependencies": {}
}
```

Put this object in `threetopia.json` under `manifest`, and list every file under the project’s top-level `files`. The CLI scaffold includes the server-assigned package and project IDs.

## Installation

Run installation inside a Threetopia project. World packages can also be installed for inspection, but only asset packages can be declared as reusable dependencies. The CLI:

1. Resolves exact published versions and transitive dependencies.
2. Downloads to a staging folder and verifies every file’s size and SHA-256.
3. Writes files under `threetopia_modules/creator/package/`.
4. Saves `threetopia-lock.json` and exact direct dependencies in your project manifest.
5. Records the successful installation in the registry.

Commit your lockfile. Package versions are immutable. Installing a newer version is explicit; existing projects do not silently update.

The package creator sees your public handle, the installed version and the number of project installations. A project uses a random ID; private project names and source code are not sent. Downloading files directly from the API does not count as a CLI installation.

```sh
threetopia uninstall @threetopia/beacon
```

Uninstall removes the dependency, local package directory and active installation record. It does not delete assets you already copied into your world. Transitive dependencies can be removed once nothing else depends on them.

## Use an installed model

```sh
threetopia use @threetopia/beacon --export model --as map
threetopia use @threetopia/beacon --export model --as overview
threetopia use @threetopia/beacon --export world --as world
threetopia check
```

`use` checks the actual geometry against the selected role before copying it into your world’s content file. For a larger composition, import installed GLBs in your modelling or build tools, then export the combined scene. Its combined geometry must fit the slot and budget.

For code exports, import the installed file in your own application or bundler. Installation does not execute package scripts, and uploaded JavaScript never runs automatically on the creator website.


---

# Preview before publishing

## Local preview

```sh
threetopia preview
threetopia preview ./coral-garden --port 5196
```

The local server binds to `127.0.0.1`. It serves only declared package files and the bundled preview runtime. Switch between World, Map and Overview; drag to orbit and scroll to zoom. Refresh after replacing your models. Validation runs before the server starts and when it loads your content.

The world preview scales the full-size scene down by 0.03 to show it inside the same tile geometry used for the map. The map preview uses your exported map units directly. The white ring marks the protected content slot; it is absent from the public map.

The host controls the ocean, terrain, camera and light. Preview water is deliberately simpler than the shared map’s animated ocean; the content and host tile geometry are the same.

## Private online preview

```sh
threetopia push
```

Push stages the files and asks the server to validate them independently. A passing version becomes **ready** and gets an owner-only preview at the creator website. It does not appear in the public catalog or shared map until published.

Private preview links require the owner’s account. They are not anonymous sharing links. The package page lets you switch representations, inspect geometry counts and see validation errors.

## Portable preview

```sh
threetopia build
```

This creates `dist-threetopia/` with the models, manifest, validation report and bundled Three.js viewer. Serve that directory over HTTP with any static server. This is a local build, not an automatic upload or public release.


---

# Geometry and performance budgets

The CLI and registry share a validator. The server reads the uploaded bytes and checks actual transformed vertices; it does not trust the CLI’s report or the bounds declared in a GLB accessor.

| Representation | Triangles | Draw calls | GLB bytes | Textures | Decoded texture memory |
| --- | ---: | ---: | ---: | ---: | ---: |
| World | 500,000 | 160 | 32 MiB | 24 | 128 MiB |
| Map | 36,000 | 4 | 768 KiB | 2 | 2 MiB |
| Overview | 24,000 | 3 | 512 KiB | 2 | 2 MiB |
| Asset GLB | 500,000 | 160 | 32 MiB | 24 | 128 MiB |

Each triangle primitive counts as a draw call. Repeated nodes count toward total drawn triangles and calls. Texture memory includes an estimated full mip chain. Embedded textures are limited to 4096 × 4096, and the decoded-memory limit still applies.

A package can contain at most 128 files, 32 MiB per file and 64 MiB total. Accounts currently allow 50 packages, 500 stored versions and 2 GiB of declared package storage. These limits apply to drafts too; remove unused unpublished versions to free space.

## Fit the slot

World content stays inside a horizontal radius of **190 metres**, above local y=0 and below y=480. Map and overview content stay inside radius **5.7**, above y=0 and below y=14.4.

The slot is intentionally smaller than the host tile. The outer terrain band and boundary profiles belong to Threetopia. A tall building that fits the triangle budget can still fail the bounds check.

## Common failures

- **“Host tile is immutable”**: restore `tile.lock.json` from your reservation or clone the package again. Do not edit its hash.
- **“Geometry leaves its slot”**: centre and scale the component, apply/export transforms, and check the lowest vertex.
- **“Map exceeds draw calls”**: merge meshes/materials and bake shared textures. One component can contain several recognizable objects, but it still has to fit the combined budget.
- **“Use a self-contained GLB”**: embed textures and buffers; do not reference external URLs.
- **“Compressed or instanced accessors”**: export an uncompressed validation-compatible GLB.
- **Missing map/overview**: both are mandatory for a world package, even if your detailed world already renders well.

Run `threetopia check` before upload. The server repeats the checks on `threetopia push`. A rejected draft is never publicly served as a published package.


---

# Versions, states and changelogs

Each package has a stable owner, name and kind. World packages also have a stable tile binding. Each uploaded version has its own manifest, changelog, file hashes and validation report.

| State | Meaning | Visibility |
| --- | --- | --- |
| Draft package | Package exists without uploaded content | Owner |
| Uploading | Manifest accepted; files are being uploaded | Owner |
| Rejected | Server validation failed | Owner |
| Ready | Geometry and files validated successfully | Owner preview |
| Published | Released explicitly by the owner | Public |

## Push, review, publish

Edit `manifest.version` and `manifest.changelog` in `threetopia.json`. Versions use `major.minor.patch`, for example `1.2.0`; prerelease tags and version ranges are not accepted yet. Changelogs are required, plain text and at most 8,000 characters.

```sh
threetopia check
threetopia push
```

Open the private preview from the returned link. Then publish from the package’s version card or your terminal:

```sh
threetopia publish
```

Publishing a world package makes its tile occupied and its map content available to the shared map. The package remains tied to the selected host tile. The public site is still a map preview, not a playable world release.

## Updating a package

Published files are immutable. Increase the version and write a new changelog before pushing. Existing installations remain pinned until their creators explicitly update.

Unpublished versions can be deleted from the studio and uploaded again. An interrupted upload appears as **uploading**; remove that draft in the studio and push again. Published packages and versions cannot be deleted because existing installations must remain reproducible.

The studio shows every owned package, exact versions, states, changelogs, geometry reports and active installing creators. Public catalog pages expose published versions only.


---

# CLI reference

Install the [0.2.1 release](/downloads/threetopia-cli-0.2.3.tgz) with Node.js 22.13 or later:

```sh
npm install -g https://docs.threetopia.com/downloads/threetopia-cli-0.2.3.tgz
```

## Account

| Command | Purpose |
| --- | --- |
| `threetopia login` | Browser approval and secure local CLI token |
| `threetopia login --no-open` | Print the URL without opening a browser |
| `threetopia whoami` | Show the authenticated account |
| `threetopia logout` | Revoke the current CLI token |

## Tiles and project creation

| Command | Purpose |
| --- | --- |
| `threetopia tiles [--json]` | List the current grid and tile variants |
| `threetopia reserve q,r --variant coast-01` | Reserve an available coordinate and immutable terrain |
| `threetopia create dir --kind world --tile ID` | Create a world for your existing reservation |
| `threetopia create dir --kind asset` | Create a reusable asset package |
| `threetopia clone @creator/package [dir]` | Clone one of your own packages and its fixed tile |

Creation accepts `--name @your-handle/package` and `--title "My title"`. Without these, the directory supplies the name. Existing directories are never overwritten. Use **Choose a tile** in the studio for a visual selection.

## Development and release

| Command | Purpose |
| --- | --- |
| `threetopia check [dir]` | Validate files, actual geometry, budgets and tile integrity |
| `threetopia preview [dir] [--port 5195]` | Interactive loopback preview; refresh after editing |
| `threetopia build [dir]` | Export a portable preview to `dist-threetopia/` |
| `threetopia push [dir]` | Upload and independently validate a private version |
| `threetopia publish [dir]` | Release a version that is already ready |

Checking, previewing and building an existing local project work offline. Registry operations require login. Push does not publish automatically.

## Reuse

```sh
threetopia search rocks
threetopia install @creator/package@1.2.0
threetopia use @creator/package --export model --as map
threetopia uninstall @creator/package
```

Run install, use and uninstall in the project directory. `use` accepts `--as world`, `--as map` or `--as overview`; it copies a GLB after checking it against that role’s bounds and budget. Installation without a version resolves the highest published numeric version and then locks it.

## Registry and files

All commands accept `--registry ORIGIN`. `THREETOPIA_REGISTRY` sets the default; production is `https://creators.threetopia.com`. Only HTTPS or HTTP loopback origins are accepted. A project cannot silently switch registries.

`threetopia.json` contains editable metadata, file paths and package/project IDs. `tile.lock.json` contains the immutable world tile. `threetopia-lock.json` records installed files and versions. `threetopia_modules/` contains downloaded reusable packages.

Run `threetopia help` for the installed command list. The previous local-only image/scene CLI is an internal legacy tool and is not the creator registry workflow.


---

# Registry API

Base URL: `https://creators.threetopia.com/api`. JSON endpoints return `{ "message": "…" }` on error, sometimes with a `details` array. Use the CLI unless you need a direct integration.

## Authentication

Browser authentication uses a host-only, HttpOnly, Secure, SameSite=Lax cookie. Browser mutations require the same Origin. CLI authentication uses `Authorization: Bearer TOKEN`. Never put a token in a URL or package file.

| Method and path | Purpose |
| --- | --- |
| `GET /health` | Registry version and docs |
| `POST /auth/start` | Request code: `{email}`; browser same-origin |
| `POST /auth/verify` | Verify `{challenge,code}` and set session cookie |
| `GET /me` | Current creator or null |
| `PATCH /profile` | `{handle,displayName}`; handle is permanent |
| `POST /auth/logout` | Revoke current credential |
| `POST /auth/device` | Start CLI device flow; empty JSON object |
| `POST /auth/device/poll` | `{deviceCode}`; pending returns 202 |
| `POST /auth/device/approve` | Browser only: `{userCode,approve:true}` |
| `GET /tokens` | List current creator’s CLI credentials |
| `DELETE /tokens/:id` | Revoke own CLI credential |

Device flow returns `deviceCode`, `userCode`, `verificationUri`, `expiresIn`, and `interval`. Poll at that interval; approval returns `accessToken`. The device code is confidential and is not the public user code.

## Tiles

| Method and path | Purpose |
| --- | --- |
| `GET /tiles` | Original worlds, current slots, published/reserved tiles, 144 variants |
| `POST /tiles/reserve` | `{q,r,variant}`; returns ID and canonical contract |
| `GET /tiles/:id` | Own reservation and full contract |
| `DELETE /tiles/:id` | Release own unused reservation |

Reservations are atomically unique by coordinate. World creation requires an owned reservation; upload requires its exact canonical contract.

## Packages

| Method and path | Purpose |
| --- | --- |
| `GET /packages?kind=asset&q=beacon` | Public published catalog |
| `GET /packages?mine=1` | Authenticated creator’s packages and states |
| `POST /packages` | `{name,kind,title,description,tileId?}` |
| `GET /packages/:id` | Metadata, versions; own page includes installers |
| `GET /resolve?name=@creator/name&version=1.0.0` | Public exact version, manifest and file hashes |
| `DELETE /packages/:id` | Delete own unpublished package |

Omit version or use `latest` to resolve the highest published numeric version. Use exact versions in dependency manifests.

## Upload lifecycle

1. `POST /packages/:id/versions` with the full [package manifest](/schema/package.json), including file paths, byte lengths and SHA-256 hashes.
2. `PUT /packages/:id/versions/:version/files?path=…` with each file’s raw bytes.
3. `POST /packages/:id/versions/:version/validate` with `{}`. The server measures uploaded geometry; a valid version becomes ready.
4. Review the owner-only preview.
5. `POST /packages/:id/versions/:version/publish` with `{}` to publish.

`GET /packages/:id/versions/:version/files?path=…` serves bytes. Ready and draft files require the owner’s credential. Published files are public and immutable. Uploaded HTML/JavaScript is served as an attachment with a restrictive CSP and is not executed by the site.

`DELETE /packages/:id/versions/:version` removes an unpublished draft. Published versions cannot be changed or deleted.

## Installations

After verifying and writing all files, the CLI calls `POST /packages/:id/install` with `{version,projectId}`. `projectId` is a random project UUID, not its name or path. `DELETE` at the same endpoint with `{projectId}` removes that active installation.

These records describe CLI-reported installations, not arbitrary downloads or proof that a package is actively rendered. Package owners see public creator handles and versions; no private project data.