# Authoring an office

An **office pack** is one JSON-shaped object describing the inside of a
building: floor slabs, walls, holes in the walls, furniture, seats, and a few
camera poses. `src/interiors/types.ts` is the contract — it is short, it is
commented, and it wins any argument with this document. `lumbridge-hq.ts` in
this directory is the small worked example — one storey, four rooms, every core
feature — and copying it is the intended way to start. `mateo-court.ts` is the
large one: two storeys, sixteen rooms, seat bindings, device declarations and a
courtyard, and it is the file to read when you want to see a feature used in
anger rather than demonstrated.

Nothing in a pack requires an account, a key or a network. If you can run the
repo you can author an office, and if you can author an office you can hand
someone the file.

## The shape of it

```ts
import type { Office } from "../interiors/types.ts";

export const ACME_HQ: Office = {
  id: "acme-hq",
  name: "Acme HQ",
  levels: [
    {
      id: "level-1",
      name: "Level 1",
      elevation: 0,      // floor height above the office origin
      wallHeight: 2.8,   // the storey's default wall top
      wallThickness: 0.12,
      wallSurface: "tera:paint.matt",
      floorplan: {
        rooms: [...],    // required
        walls: [...],    // required
        props: [...],    // optional, read as [] when absent
        deskBanks: [...],
        seats: [...],
        zones: [...],
        devices: [...],  // smart hardware; see "Devices" below
      },
    },
  ],
  viewpoints: [...],     // viewpoints[0] is where you arrive
  meta: { author: "you", license: "CC0-1.0" },
};
```

`Office` must stay **strictly JSON-serialisable**: no functions, no classes, no
`Date`, no `THREE` types. A pack you hand-write as a `.ts` module and a pack
that arrives as a `.json` body over HTTP have to be literally the same thing,
because the server (`GET /api/v1/offices/:id`) serves exactly this object inside
an `OfficeDoc`.

Helper *functions* in your source file are fine — `lumbridge-hq.ts` uses five,
and they all run at module load and return plain objects. The rule is about the
value, not the file.

## The coordinate frame

Metres, `1 unit = 1 m`. The floor is the **XZ plane** with **+Y up**, which is
three.js's convention with no conversion anywhere.

"Plan view" throughout means looking down at that plane with **+X to the right
and +Z down the page**. That is the one thing worth internalising, because +Z
going *down* is what makes the winding rule counter-intuitive:

- Outlines are **implicitly closed** — do not repeat the first point.
- Author them **counter-clockwise in plan view**, which is NW → SW → SE → NE for
  a rectangle, and which has a *negative* shoelace area over `(x, z)`.
- Get it wrong and nothing breaks: `Plan` silently re-winds a reversed polygon.

By default an office has no orientation on the earth, and calling an edge
"north" is a convenience for reading your own file. A pack with no `site` gets
no `Atmosphere`, no sun and no sky (CONTRACT.md §4); interior lighting is a
fixed rig owned by the scene, and that is a supported, permanent state — you can
author a whole building without owning a coordinate.

Say where the building stands and the convenience becomes a fact:

```ts
site: {
  lat: 37.7756,
  lng: -122.3186,
  elevation: 4,      // metres above the ground OUTSIDE, not above sea level
  heading: 0,        // compass bearing, in degrees, that the pack's −Z points along
  label: "Alameda Point",
},
```

Then the pack gets the real sun for that place at the app's clock, a sky, and a
horizon `elevation` metres below the level-0 floor. **`heading` is the field that
matters most and the easiest to leave wrong**: it is what decides which of your
walls the light actually comes through. `0` means your "north" really is north.

`elevation` is the other one worth thinking about, because it is what the horizon
is measured from — the difference between an office on the 48th floor and a shed
on an airfield is one number, and it is this one. All three shipped packs are
worked examples: `lumbridge-hq.ts` is 188 m up and rotated 205°,
`frontier-valley.ts` is 4 m up and square to the compass, and `mateo-court.ts` is
1.2 m up — a loading dock — and turned 36° onto the 1781 pueblo grid that
downtown Los Angeles still follows.

### Where the car goes

A sited building may also say where a vehicle stands outside it:

```ts
arrival: {
  levelId: "level-1",
  position: { x: 22.6, z: -3.4 },   // metres, in YOUR plan frame
  rotation: -Math.PI / 2,           // Yaw: which way the car points
  kind: "vehicle-stall",
  label: "Mateo Street kerb",
},
```

`src/engine/officeExterior.ts` builds an apron and a vehicle there. The position
is in **the pack's own frame**, the same one the walls are in — which is why a
stall on the street side of a façade authored at `z = 0` has a *negative* `z`,
and why you can see it is outside the building without converting anything.

Put it on ground that is genuinely outside: `Plan` checks the level, the kind and
that the numbers are numbers, and deliberately does **not** rule on whether the
stall is inside the footprint, because a covered undercroft and a courtyard are
things a pack might legitimately mean. `src/test/packs/arrivalAnchors.test.ts`
is where the three shipped packs assert that theirs are on the street, the
podium kerb and the apron.

One trap, and it is `lumbridge-hq`'s: a pack whose level-0 floor is 188 m above
the ground outside has no pavement to park on at all. Its stall is authored
beside its own front door because the plan frame is the only frame a pack has,
and what "outside" means *vertically* for a tower is the exterior layer's
decision. If your building is up in the air, say so in a comment where the next
person will find it.

Nothing here is geocoded and nothing can be. These are numbers you type, like
every other number in a pack — see CONTRACT.md §8 for why a coordinate's
provenance is a licensing question in this repo.

## Levels, and how somebody gets between two of them

A `Level` is a storey: an `elevation` (floor-to-**floor**, not floor-to-ceiling),
a default wall height, and its own floorplan in its own frame with its slab at
zero. `Plan` adds the elevation to every coordinate on the level exactly once, so
you author an upper floor without holding 5 m in your head.

### The way between two storeys is a `Transition`

A `Level` on its own is a place the camera can fly to. To make it a place
somebody can **walk** to, author a `Transition` on the `Office` — not on either
floorplan, because it is the one record in this format that is a fact about two
storeys at once and putting it on either would make the other one's copy a
restatement.

```ts
transitions: [{
  id: "stair",
  kind: "stair",              // or "lift"
  width: 1.2,
  surface: STEEL,
  lower: {
    levelId: "level-1",
    footprint: [/* a small patch of floor at the bottom */],
    landing: { x: 10.2, z: 9.2 },
  },
  upper: {
    levelId: "level-2",
    footprint: [/* the gap in the balustrade at the top */],
    landing: { x: 9.25, z: 10.4 },
  },
  // Optional. Absent means one straight flight between the two landings.
  legs: [
    { to: { x: 14.1, z: 9.2 }, rise: 1 },   // a flight
    { to: { x: 14.1, z: 10.4 }, rise: 0 },  // a half landing
    { to: { x: 9.25, z: 10.4 }, rise: 1 },  // and the flight back
  ],
}]
```

**Standing on a footprint is the input.** There is no key to press, which is the
single most important thing to know when you size one. A footprint the size of
your whole stair means that walking *under* the flight takes you up it; the
right size is the bottom couple of metres, and at the top, the gap you arrive
through and nothing else.

That upper footprint is doing a second job that is easy to miss. A gap in a
balustrade is an unguarded edge, and the moment an upper floor is walkable
somebody will walk off it. A footprint covering the gap catches them and sends
them downstairs, which is what the gap is for.

`rise` on a leg is that leg's **share** of the total climb, not a height. The
height is already known exactly — it is the difference between the two levels'
`elevation`s — and stating it twice is how a pack ends up with a staircase that
does not reach its own landing. A flat half landing is `rise: 0`. `Plan`
normalises the shares, so two flights written `{ rise: 1 }` and `{ rise: 1 }`
mean half each.

**You do not author treads.** `src/interiors/shell.ts` builds them from this
record: it divides each climbing leg into a whole number of ~178 mm risers and
lays a tread on each, which is why `mateo-court`'s 2.5 m flights come out at the
fourteen risers its own comment always claimed. The drawn flight and the flight
the walk controller climbs are the same list of points, so a staircase nobody
can climb is not expressible.

Three things `Plan` will refuse, all of which drop the transition **whole**
rather than in pieces — half a staircase is a hole in a collider:

- a footprint outside its own level's bounds, or with a wall running *through*
  it. A wall along its edge is fine and expected: stairs go against walls.
- a landing outside its own footprint, or pressed so close to a wall that a
  walker of the default radius could not stand on it.
- an `upper` that is not actually above `lower`.

Two things it will not do for you:

- **The treads do not collide.** `Plan` derives collision from the wall list
  alone, so like every prop in every pack, a flight can be walked through at its
  low end. That is the engine's existing physics rather than a property of this
  record.
- **It will not find a route.** A footprint you cannot walk to is a way up
  nobody reaches. Check it the way `src/test/packs/mateoContent.test.ts` does.

Still worth doing, transition or no transition: give every level a viewpoint of
its own, so nothing up there is unreachable by every means at once.

## Rooms are slabs. Walls are segments.

This is the load-bearing idea, and the thing most people get backwards on the
first attempt.

A **`Room` is a floor finish with a name and a polygon. It implies no walls.**
A **`Wall` is a separate straight segment that belongs to no room** and stands
wherever you put it. The two lists are not derived from each other.

Consequences worth stating out loud:

- An open plan is simply rooms with nothing standing between them. In the
  reference pack the lounge, the kitchen and the desk floor share three edges and
  only one of those edges carries a wall.
- A room can be a corridor, a lift lobby, a zone of different carpet. Give it an
  id if you ever want to name it.
- Rooms may overlap and may leave gaps. `Plan.roomAt` resolves *later* rooms
  first, so a room declared after another wins the lookup where they cross.
  Overlapping is legal but every shipped pack avoids it — two coplanar slabs at
  the same height is a z-fight waiting for the wrong GPU, so `mateo-court`
  notches its courtyard around the stair standing in it rather than laying one
  slab over the other.

Rooms and walls should be authored against the **same numbers**. A wall is
centred on its line and straddles the boundary between the two slabs meeting
there. If the slab edge says `10.4` and the wall line says `10.42` you get a
seam you will never find again.

### Ceilings

`ceiling` omitted gives a ceiling at the level's `wallHeight`. `ceiling: null`
means **no ceiling at all** — an atrium, a void, or a room you want to look down
into. `{ height, surface }` overrides one room.

An office you look down into from an establishing viewpoint cannot have lids on
the rooms you are trying to see, so most of both large packs declare
`ceiling: null`. The rooms that keep theirs are the ones you are never meant to
see inside — the bath and storage in the SF studio, the equipment store in the LA
one — and a ceiling is a cheap way of saying so.

`mateo-court` uses the field in a third sense that is worth knowing about: its
courtyard and its stair are `ceiling: null` because they are **outside**, and
there is nothing above them at any height. Nothing in the format had to change
for that; the field already said what was needed. One consequence is worth
carrying, though: a room with no ceiling is a room with nothing to hang a light
fitting from, and a ceiling grid over an open courtyard is a lighting plan for a
different building.

## Doors and windows are openings, not props

There is no `tera:shell.door`. A door is a 1-D interval punched out of a wall:

```ts
{ kind: "door", start: 5.6, width: 0.9, sill: 0, head: 2.1 }
```

`start` is measured **from the wall's `from` end**, along the wall, in metres.
That is the whole of the horizontal placement, which is why an opening can never
drift off its wall. It also means **the direction you write a wall in is the
direction its openings are measured in** — author every wall consistently (the
reference pack goes west-to-east and north-to-south, without exception) or you
will eventually put a door at the wrong end of a room.

`sill` and `head` are metres above the level's floor, and both are required.
There are deliberately no per-kind defaults: a contract where the numbers you
read are not the numbers you get is worse than a contract that makes you type
`sill: 0`. Typical values:

| kind | sill | head | note |
| --- | --- | --- | --- |
| `door` | 0 | 2.1 | 0.9 m wide for a single leaf, 1.8 m for a pair |
| `arch` | 0 | 2.4 | a cased opening with no leaf |
| `window` | 0.9 | 2.2 | punched window |
| `window` | 0.75 | 2.35 | ribbon glazing on a façade |

### The passability rule, which is the whole reason for this design

The pass that splits a wall around its openings has to run anyway to produce the
solid runs you can see. Running it once also produces the **walk-mode collision
segments for free**, with gaps in exactly the places you can walk through.

An opening is a way through **iff `sill <= 0` and `head >= 1.1 m`**. There is no
per-kind special-casing: a door passes, an arch passes, a window with a 0.9 m
sill does not, a serving hatch does not. Which means a glazed opening at ankle
height quietly becomes a hole in your wall that people walk through, so keep
sills honest.

`Plan.blocked(levelId, from, to, radius)` is the test to use from a walk
controller; do not re-derive the inflation yourself.

### Glass walls versus window openings

Full-height glazing is a **wall with a glass surface**, not one enormous
opening:

```ts
{ id: "ext-east", from: { x: 34, z: 0 }, to: { x: 34, z: 12.2 }, surface: "tera:glass.curtain" }
```

An opening is a hole, and a hole is something you can sometimes walk through. A
curtain wall is a solid you happen to be able to see through. Modelling one as
the other hands the collider a twelve-metre gap and puts your lounge on the
pavement.

## Desk banks

Hundreds of hand-written desk literals is not a file anybody edits twice. A
`DeskBank` is one declaration that `Plan` expands into a desk prop, a chair prop
and a seat per station:

```ts
{
  id: "eng",
  desk: "tera:desk.workstation",
  chair: "tera:seat.task-chair",
  origin: { x: 9.2, z: 1.9 },   // centre of station (1, 1), before rotation
  rotation: 0,
  columns: 6, rows: 2,
  pitch: 1.7,                   // centre-to-centre across
  rowPitch: 0.85,               // centre-to-centre down; defaults to `pitch`
  facingRows: true,
  seatOffset: 0.6,              // desk centre to seat; defaults to 0.6
  pose: "sit",                  // defaults to "sit"
  seatPrefix: undefined,        // defaults to `id`
}
```

The grid is laid out in the bank's own frame — `columns` along local +X, `rows`
along local +Z — then rotated by `rotation` about `origin`. Rotating a bank does
not move the origin to a corner of the building; the origin stays station
(1, 1). At `rotation: Math.PI` the bank's local +X is world −X, so the origin is
the *east* end of the run.

**The generated ids are contractual**, because a `Presence` binds to a seat id
and you have to be able to predict it without running anything. Stations are
numbered from 1, along each row and then down the rows, zero-padded to two:

- seat `${seatPrefix ?? id}-01`, `-02`, …
- desk prop `${id}-desk-01`, chair prop `${id}-chair-01`

So the bank above gives you `eng-01` … `eng-12`, and `eng-04` is the fourth desk
in the front row.

### Why every bench in the reference pack is two rows

`facingRows` turns the first row of each pair around so a pair shares a run of
desktop — a bench, rather than two rows of people looking at the back of each
other's heads. It does that at the bank's **single** `rowPitch`, and the pitch
that makes two rows meet back-to-back (0.85 m: a desk deep, plus a cable trough)
is nothing like the pitch you need between one bench and the next (2.4 m of
chair, aisle and chair). One bank cannot express both. **A second bench is a
second bank.** That is a real limit of the format, not an oversight.

Seat ids restart at `01` in every bank, so two banks that want to share a
numbering series cannot; give them distinct prefixes (`eng`, `ops`, `design`)
rather than trying.

A bank places a desk and a chair and **no third thing**. If you want a monitor
on every desk, do not write thirty-nine monitor props that have to be kept in
step with a bank you will move next week — register your own desk asset (see
below) that builds a desk with a monitor on it, and every station in every bank
in every pack gets one.

## Seats

```ts
{ id: "bernal-04", position: { x: 10.8, z: 14.1 }, facing: Math.PI / 2, pose: "sit" }
```

**A seat is an address, not a chair.** The chair is a separate prop that happens
to be at the same coordinate; a room with no chairs in it can still have seats,
and a chair with nobody's name on it needs no seat.

This is the most important thing in the format. A `Presence` — somebody at a
desk — binds to a **`seatId` and never to a coordinate**, and never appears in a
pack. The pack knows where `eng-04` is; a private API knows who is sitting in
it; neither knows the other. That is what lets occupancy be private data behind
authentication while the geometry stays public, open-source and copyable. If a
presence carried an `{x, z}`, publishing the building and publishing the people
would be the same act, and one of them could never be published at all.

So: **keep seat ids stable across edits**, for the same reason street numbers
survive repainting the house. Move the table 200 mm; do not renumber the seats.

`facing` is where the occupant looks. `pose` is `"sit"` or `"stand"` and is the
only thing that tells a consumer how tall to draw an occupant — people perch at
a kitchen island, so those seats are `"stand"`.

## Props, and which way things face

```ts
{ id: "lobby-monitor", kind: "tera:screen.monitor", position: { x: 3.4, z: 5.2 },
  rotation: Math.PI / 2, elevation: 0.73, scale: 1, colorKey: "accent", seat: "reception-01" }
```

`kind` is an `AssetId`. The prop registry and the asset registry are the same
registry — there is no separate table of things you are allowed to put in a
room, and an unregistered id resolves to a placeholder box rather than throwing,
so one typo does not stop the office opening.

`position` is on the floor plane; `elevation` is metres above the level's floor
and is omitted for the ninety per cent of things that stand on it. `colorKey` is
an **opaque** palette key resolved by the consuming app, exactly as
`Pin.colorKey` is — the engine will never learn that `"focus"` means a quiet
booth. `seat` binds a prop to a seat id as an address, which is what lets an
occupancy layer dim the empty chairs without knowing which mesh is which.

### The yaw convention

`Yaw` is radians about +Y. **Zero faces −Z**, and the angle increases
counter-clockwise seen from above. That is exactly `object.rotation.y`, and
nothing anywhere converts it — there is no sign flip between your file and the
scene graph. (The city's `District.gridAngle` uses degrees clockwise from north,
which reads better for a map; interiors deliberately does not.)

An asset is built with its **origin at the centre of its footprint on the
floor**, facing −Z at yaw zero, and its **working side at +Z** — drawer fronts,
the open front of a shelf, a monitor's glass, a whiteboard's writing face — with
the solid back of anything that stands against a wall at −Z.

Those combine into one rule that covers every prop:

> A prop takes the yaw of **the wall it backs onto**. A seat takes the yaw of
> **the direction the occupant looks**.

A shelf against the north wall is `0`. A locker against the east wall is
`-Math.PI / 2`. A desk against the south wall is `Math.PI`, and the person at it
is also `Math.PI`, looking south at it. This is why a `DeskBank` can hand one
`rotation` to its desk, its chair and the seat between them.

### The one exception: ceiling fixtures

`tera:light.pendant` and `tera:light.troffer` are authored with their origin at
the **mounting plane** and all their geometry below it. Write `elevation: 2.8`
and you get a fitting hanging from a 2.8 m ceiling, rather than a fitting whose
author had to know your ceiling height. Everything else, including things that
stand on a desk or hang on a wall, is authored on the floor.

Light fittings emit **no light**. The interior rig belongs to the scene
(CONTRACT.md §4).

### Wall-mounted things

A prop's origin is the centre of its footprint, so a panel hangs *on* a wall
only if you place its centre half its own depth off the wall's face:
`wallLine + thickness / 2 + depth / 2`. `tera:screen.wall-display` is 0.12 m
deep and `tera:whiteboard` is 0.10 m. Name those offsets as constants; you will
use them a dozen times.

## Devices

A pack may declare smart hardware — a mic, a speaker — on its floorplan:

```ts
devices: [
  {
    id: "la-front-mic",
    kind: "mic",
    label: "Front desk mic",
    assetId: "tera:device.mic.desk",
    anchor: { levelId: "level-1", propId: "front-mic", roomId: "lobby", seatId: "front-01" },
    capabilities: CANONICAL_CAPABILITIES.mic,
    provenance: "simulated",
    disclosure: "Simulated studio hardware. These readings are demonstration data…",
  },
],
```

`src/devices/types.ts` owns the type and is worth reading; four things about it
matter when you are authoring one.

**A device has no coordinate.** `anchor.propId` is required and it *is* the
position: the device derives its transform from that prop's, plus an optional
`offset` in the prop's own frame for the few centimetres between a desk's origin
and the top of a mic stand. Nudge the desk and the mic goes with it, because
there was never a second number to forget. Same rule `Prop.seat` follows for
chairs, and the same one a pack follows by importing its site instead of
restating the coordinates.

**The anchor prop is the hardware.** Its `kind` is the device asset —
`<namespace>:device.<kind>.<placement>`, so `tera:device.mic.desk` and a
self-hoster's `acme:device.mic.boom` both read as a mic with nothing registered.
`Plan` drops a declaration whose anchor prop is device hardware of the *wrong*
kind: a mic bolted to a speaker is not a rendering mistake, it is a command
routed to the wrong instrument.

**`capabilities` should be `CANONICAL_CAPABILITIES[kind]`.** The device panel
builds its controls by walking that array and the arena's observation width is
the sum of them, so two studios describing a mic differently changes the shape of
an RL observation without anybody editing the arena.

**`disclosure` is mandatory and it is checked.** A declaration with
`provenance: "simulated"` whose disclosure does not contain the word is reported
as a problem and dropped — the same check `RobotOperationsDefinition` gets, for
the same reason. A level meter that moves, with nothing beside it saying where
the number came from, is a claim about a real room.

What a device is *doing* — powered, muted, its level in dBFS — is a `DeviceState`
and **never appears in a pack**. It arrives over the API from a route that can
refuse an anonymous caller, exactly as `Presence` does. A declaration is a
description of a room and is safe to publish; a reading is not, and the split is
the whole design.

## How full a room should be, and the trap in the answer

The number to aim at is **0.26 non-light props per square metre**, building-wide,
with no room over 20 m² below **0.15**. Both shipped studios clear it:
`lumbridge-hq` sits at 0.28 over 100 m², `mateo-court` at 0.29 over 1246 m².
`src/test/packs/mateoContent.test.ts` measures it if you want the exact method —
it counts prop centres by `Plan.roomAt`, and it excludes every `tera:light.*`
because a ceiling grid will satisfy any prop count you like while leaving the
floor bare. Mateo Court's first version proved that: ninety-eight of its props
were troffers, two of the grids hung in rooms declared `ceiling: null`, and it
looked empty from every viewpoint it had.

**But the ratio is the easy half, and on its own it is a lie.** `furnish.ts`
batches props by `(asset, colorKey)` and draws `ctx.rand` **once per batch**, so
every instance of a kind is geometrically identical — the same seeded jitter,
the same books on the same shelf, the same leaves on the same plant. Ten more
shelves in a room are one shelf drawn ten times. So:

> Apparent density is a function of **distinct kinds**, not of prop count.
> A room that looks thin does not get better when you copy what is already in it.

Two consequences for how you fill a room:

- **Reach for a kind you have not used yet before you reach for a second copy.**
  Mateo Court's courtyard went from 13 props of 6 kinds to 44 of 13, and it is
  the second number that changed what it looks like. Twelve of the assets in
  `src/assets/office/studio.ts` exist because of exactly that room.
- **If the kind you need is not in the catalogue, write it.** `defineAsset` plus
  a `registerAll` is a smaller change than it looks, `src/assets/office/studio.ts`
  is a worked example of a dozen of them, and a `colorKey` on an existing kind
  will not stand in for it — the colour is *in* the batch key, so two tints of
  one asset are two batches of the same geometry, which is better than one and is
  not a new object.

A useful floor for a big room is **seven distinct kinds over 40 m²**, which is
what the reference pack's one large room manages. Below that a room reads as a
pattern rather than a place, whatever the prop count says.

## Zones

A named region of floor with an opaque `colorKey`, no behaviour and no effect on
geometry. A consuming app can highlight it, filter against it or count what is
inside it. Whether "eng" is a team, a cost centre or a colour scheme is not the
engine's business, which is why there is no `kind` field to be tempted by.

## Viewpoints

```ts
{ id: "floor", label: "The Whole Floor", shortLabel: "The Floor", number: "01",
  description: "…", levelId: "level-1",
  focus: { at: { x: 17, z: 9 }, distance: 32, height: 14, rotation: 0.55 } }
```

`distance` is metres from the target to the camera; `height` is metres above the
level's floor. An office is not a city — 30 m is the whole building and 6 m is
standing on a mezzanine, where the equivalent city numbers are in the hundreds.

**`viewpoints[0]` is the arrival pose.** Reception is the obvious choice; the
reference pack puts the establishing shot there instead, on the grounds that
arriving inside a room before you have seen the shape of the building is
disorienting. Either is fine — that is a choice a pack gets to make, which is
why the field is an order and not an id.

## Surfaces

`Room.floor`, `Wall.surface`, `RoomCeiling.surface` and `Level.wallSurface` take
a `SurfaceId` string. `MaterialRegistry.resolve` throws away the namespace,
reads the **first dot-segment** as a role name, tries a small alias table, and
falls back rather than throwing:

```
tera:carpet.loop        -> carpet
acme:carpet.broadloom   -> carpet
tera:wood.plank         -> woodFloor   (via the alias table)
tera:glass.curtain      -> glazing     (alias)
tera:carpetAccent.x     -> carpetAccent (an exact role name)
tera:nonsense.at.all    -> the caller's fallback
```

The closed list of roles lives in `src/assets/materials.ts`. Aliases today
include `paint`, `plasterboard`, `wall`, `wood`, `timber`, `concrete`, `glass`,
`ceiling`, `felt`, `fabric`, `laminate`, `steel`, `metal`, `aluminium`,
`screen`, `plant`.

There is deliberately **no per-instance tint on a surface**, unlike
`Prop.colorKey`. One blue meeting room is a *material* — register
`acme:paint.blue` and point the wall at it. One red chair in a row of grey ones
is genuinely an instance.

## Registering your own assets instead of forking

You do not fork this repo to change what a desk looks like. Register your own
asset with an `overrides:` pointing at the built-in id:

```ts
import { defineAsset, kit } from "../assets/kit.ts";

type StandingParams = { width: number; depth: number; height: number };

kit.register(defineAsset<StandingParams>({
  id: "acme:desk.standing",
  overrides: "tera:desk.workstation",   // ← every reference to the tera id resolves here
  label: "Standing desk",
  defaults: { width: 1.6, depth: 0.8, height: 1.05 },
  footprint(p) {
    return { width: p.width, depth: p.depth, height: p.height, clearance: 0.9 };
  },
  build(p, ctx) {
    /* compose cached unit primitives from ctx.parts into a MeshBin */
  },
}));
```

Declare the parameter type as a `type` alias and not an `interface`: an
`interface` has no implicit index signature and will not satisfy `AssetParams`.

Every pack in the world that says `tera:desk.workstation` — including the
reference office, unmodified — now draws yours. That is the mechanism working as
designed: reskin, do not fork. Point an id at your own namespace *in a pack*
only when you want that one building to differ.

**Everything is procedural.** A mesh is a function composing cached unit
primitives; a texture is drawn on a 2D canvas from seeded noise. **No binary art
is ever committed to `src/`** — no `.glb`, no `.png`, no fonts, no logos. This
is the same property that gives the city zero asset-licensing exposure and it is
worth more than the quality ceiling it costs. Your *own* binary assets are your
business: `public/props/`, `public/kits/` and `public/offices/` are hard-exempt
from the repo's binary gate and gitignored as self-hoster space.

If you contribute an asset back, `CONTRIBUTING.md` and `src/assets/LICENSE-ART`
are the terms: Apache-2.0 on the code, with the artistic output additionally
dedicated under CC0-1.0.

## Validation: what `Plan` forgives and what it drops

`new Plan(office)` resolves the whole thing once and never throws. Every
complaint lands in `plan.problems`, so a pack can be asserted on in a test
without capturing console output. In a dev build it also warns.

**Dropped** (the offending item disappears, the rest of the pack survives):

- self-intersecting or degenerate room outlines, zero-length walls
- an opening that runs past either end of its wall, or overlaps another opening
- `head <= sill`
- a desk bank with fewer than one station, or a non-positive pitch
- a viewpoint on a level that does not exist
- duplicate ids — **ids are unique per kind and building-wide, not per level**,
  because a `Presence` binds to a seat id and an occupancy layer dims a prop id,
  so both have to mean one thing in the building. Later loses.
- a device whose anchor names a prop that does not exist, sits on another level,
  or is device hardware of a different kind; and one whose own declaration is
  invalid — no label, a `kind` its `assetId` disagrees with, no capabilities, or
  a `simulated` provenance whose disclosure does not say so
- an `arrival` anchor on a level that does not exist, of an unknown `kind`, or
  with a position that is not a number

**Repaired** (silently, and recorded):

- an outline hand-closed with a duplicated first point
- an outline wound the wrong way
- a negative sill clamped to the floor; a head above the wall clamped down
- a prop bound to an unknown seat id — the binding is cleared, the prop stays
- a device naming an unknown room or an unknown seat — the address is cleared,
  the device stays and the room is re-derived from where its hardware stands

Missing required arrays read as `[]`, because a pack that arrived over HTTP has
been through no type checker.

Opening ids are `"${wallId}#${authoredIndex}"` using the **authored** index, so
dropping one bad opening does not renumber its siblings.

## Shipping a pack

- **In the browser.** Import it and hand it to `Plan`. The reference office is
  the default; that is the zero-config path and it needs nothing else.
- **Over HTTP.** Drop the JSON in the server's office directory and it is served
  at `GET /api/v1/offices/:id` wrapped in an `OfficeDoc`
  (`{ id, name, floor, visibility, updated? }`, defined in `src/server/wire.ts`).
  A pack that omits `visibility` is treated as **private**, and a private office
  returns **404, not 403**, so the endpoint cannot be used to enumerate what
  exists.

## A checklist before you call it done

1. `new Plan(office).problems` is empty — **at both depths**, `"full"` and
   `"public"`. They are different builds and only one of them is what a visitor
   gets.
2. Every room you can walk into has a `door` or `arch` with `sill: 0` reaching
   at least 1.1 m of head. Walk the graph, or spot-check with `Plan.blocked`.
3. No window opening has `sill: 0` unless you meant a doorway.
4. Seat ids are the ones you are willing to live with for a year, and every seat
   somebody is meant to occupy has a prop bound to it with `seat:`.
5. Corridors are at least 1.2 m clear, doors 0.9 m, desks 1.4–1.6 m. Numbers a
   person would recognise are the whole difference between a floor plan and a
   diagram.
6. `JSON.parse(JSON.stringify(office))` **deep-equals** the office. The usual way
   to fail this is a helper that writes `elevation: opts.elevation`
   unconditionally: `{ elevation: undefined }` and `{}` are different objects and
   only one of them survives the wire. Spread optional fields, do not assign
   them.
7. Every room worth looking at has a viewpoint whose `focus.at` lands inside it,
   and `viewpoints[0]` is somewhere a person can stand — it is the walk spawn as
   well as the arrival camera.
8. At least 0.26 non-light props/m² building-wide, no room over 20 m² below
   0.15, and — the one that matters — **at least seven distinct kinds in every
   room over 40 m²**. See "How full a room should be" above for why the second
   number is the real one.
9. Nothing binary landed under `src/`.
