A city that owns its state and its scene, and a loading overlay that waits for the whole world

[thalida]

Two reports: sometimes re-opening a repo showed no loading modal at all, and sometimes the modal lifted while trees were still popping in. Neither was in the overlay component, and chasing them turned up a third thing (re-opening never asked the server) and a fourth (the landing's wallpaper and the city route were the same city as far as app state was concerned).

The modal lifted early on purpose

A cold scan streams three cities: structure, then per-file metadata, then git history. The overlay came down at metadata, on the reasoning that history "only adds decorations to an already-correct city". But commits are what trees are made of, so that reveal handed you a finished-looking city that then grew trees under you.

The overlay's lifetime is one rule now: up while a world is coming, down once that world is on screen. Idle already meant "a frame carrying these meshes has been presented" (see city/render/LOADING.md); it is now the only thing that takes the overlay down. The stream ending is the middle of the wait, not the end of it.

The cost is real and worth naming: on a cold scan of a big repo the overlay now sits through the git log walk, which is the longest stage by far. So the list says which wait it is:

Resolving source  ✓
Cloning           ✓
Scanning files    ✓
Sketching layout  ✓
Reading history   ›          <- new row
Building city                   67% trees

Cancel is where it always was. A cached open never sees that row light up: one complete manifest, no history stage.

The modal that never appeared

Re-opening the project you were just in never streamed anything, so nothing raised the overlay. Leaving /city unmounts the canvas, though, so coming back re-packs the whole city from scratch: seconds of real work behind a blank stage.

A build with nothing on screen behind it now raises the overlay by itself, showing the build row alone (nothing was fetched, so the clone and scan rows would be rows for work nobody did). progress.cityOnScreen is what "on screen" means, and unmounting the canvas clears it. A rebuild under a city, a settings Save or a live update, stays the footer's to report.

Re-opening never asked the server

Worse than the missing modal: it never asked. The committed source matched the URL, so the route effect returned early and the city was repacked from the manifest already in memory. Come back an hour and a few commits later and you were looking at the old repo.

Nothing on this machine can know whether a scan still holds. The server decides that, off its own cache, per ask. Leaving the city route arms the next open as a fresh one, and the guard now covers only what it was written for: the branch a remote commit puts in the URL while you stay put. The in-hand manifest is dropped when no city is on screen, so a re-open packs the scan it just asked for rather than building the stale one first and the fresh one a moment later.

Every city is a whole city

The landing's wallpaper and the project you opened are two cities from one composer, and the composer reached straight into app state. The wallpaper:

• called markIdle, so "a city is on screen" stayed true for a canvas the landing had already thrown away. That is what made the missing modal intermittent: the next open saw a city already up and skipped its overlay.
• drove the build-stage readouts
• refit its camera off CURRENT_SOURCE_KEY, the other city's project
• pruned its selection off the global scrubber
• on a Timeline exit, repacked itself from MANIFEST, putting the opened project's city on the landing
• and on a settings Save, packed the opened project into itself

The first attempt at this fixed the coupling but kept a role: an isWorld flag, two named binding bundles, and a component that branched on a variant to choose a camera, a reporter, a handle slot, a rebuild strategy, a manifest to read, and whether to clear state on unmount. That was worse than what it replaced, because it looked principled.

There is no role now, and no config to assemble either. A city renders a session, and there is one code path:

<City session={session} opaque />

<City session={backdrop} cameraMode={CameraMode.Backdrop} label="Decorative 3D city." />

Two cities are two sessions and nothing else. Camera behaviour is the only thing left that differs between those two lines, because it is the only thing that is genuinely about this rendering rather than about the city.

Most of the branches turned out not to need a config value at all, because the city already knew the answer:

• rebuildScene / currentManifest are gone. A city re-packs what it is showing (handle.repack, handle.manifest), so the settings reactions take a city and ask it, instead of being handed a manifest and a strategy per variant. A union city under a scrubber reassembles instead, which the timeline binding owns.
• markSceneGone is gone. It is report.markGone(), the same channel as every other status write.
• BACKDROP_HANDLE is gone. The landing feeds its city a source signal and reads its own reporter for "it painted", so it needs no global slot, and "written only once it has actually painted" is now literally true.
• whenCityOnScreen is gone. It was a promise wrapping an effect wrapping a microtask, watching the global status from outside. WebGL has no "the pixels landed" callback, but the composer already knows which revision's frame it presented, so it hands out that promise directly: handle.whenOnScreen(). It is report.markIdle's moment asked rather than told, which is the split between the two: the reporter is the city telling whoever mounted it, the handle is whoever holds it asking.
• The canvas id="city" is gone. Two mounted cities would both have claimed it.

Two smaller ones on the way past. isOpenedSource() collapses three hand-rolled CURRENT_SOURCE + sameSourceIdentity comparisons. And the route-load flag is named for the fact it tracks: you arrive at the city route, and arriving asks the server, where before it was a boolean called away.

And the state a city is made of was still the app's

A city instance being self-contained did not make two of them possible, because
everything a city is made of was a module singleton: MANIFEST,
CURRENT_SOURCE, the scan and rebuild status, the timeline and its scrub
position, the scene handle, and the fetch layer's load generation. Two cities
meant one repo between them.

All of it belongs to a CitySession now — a class holding classes:

class CitySession {
  manifest = new ManifestStore()
  source   = new SourceStore(this.manifest)
  progress = new ProgressStore(this.manifest, this.source)
  timeline = new TimelineStore(this.manifest)
  scene    = signal<CityScene | null>(null)

  commands     = new CityCommands(this)   // the verbs the chrome sends its scene
  load         = new CityLoader(this)     // the scan, its cancel, the live poll
  timelineMode = new TimelineMode(this)   // entering, scrubbing, leaving

  bindings(cameraMode?) { … }             // everything a scene is wired to
}

Each store takes the stores it reads, so the dependency graph is written down in
that constructor order rather than being ambient. The loader and the Timeline
controller are per session too — which deleted the handler injection
(setTimelineRefreshHandler and friends) that used to bridge them, since both
sides can now reach each other through the session they are in.

They were factory functions returning interfaces at first, wired together by
free helpers: cityPropsFor(session), a SILENT_BUILD_REPORTER for a city
nobody was listening to, a zero-argument subjectKey(), a const ONE_CITY = 'city' standing in for a city that had no name. Every one of those existed to
paper over a city that was not a thing you could hold. Holding one deletes them:
session.bindings() is the single way to instance a city, report is
session.progress, subjectKey is session.source.key.

That in turn is what let the landing's backdrop stop being special. It gets a
session of its own — it is a second city, showing a different repo — so its
build reports into stores the chrome never reads, and HomeBackdrop is a
component that renders <City> rather than a hook returning parts to assemble.
tests/city/twoCities.test.ts mounts the two side by side and asserts neither
can see the other's status, camera, timeline or manifest.

The chrome reads its city from a provider, not an import.

<CityProvider session={session}>   // one session today
  <CityHeader /> <CitySidebarLeft /> <CityStage /> …
</CityProvider>

That is the part that makes a side-by-side view a new view rather than another
refactor: wrap each column in its own session and the same components work
unchanged. The URL follows: router/urlBinding.ts is an adapter pointed at one
session, so a column view can point it at the focused column or at none.

A session is a place, not an identity. Opening a new source swaps what it
holds and keeps the scene rendering it — a column is somewhere you point at
repos over time.

Everything else falls out. SCENE_HANDLE's verbs became a session's commands.
The picker's selection key moved onto the picker that owns the selection.
LIVE_UPDATES_ACTIVE and the settings-transfer excludes part became questions
about a session rather than about the app. The city internals that read the
timeline directly (facade panels, the picker, the scrub controller) take it
through SceneContext.

Two real bugs surfaced on the way: installScrubController threw on a city with
no timeline binding (a city nobody scrubs cannot be handed a scrubber, so it
no-ops), and the module-level selection key let a test seed state before the
picker that resolves it existed.

But its LOOK was still the app's

A session held everything about a city except what it looked like. Fifty files
under city/ read BUILDINGS.value, TREES.value, GEM.value straight off
the settings panel's signals, so two cities on screen could not differ and one
Save re-packed both.

CityConfig is one city's settings: a signal per section that follows the panel
until that city is given its own, and a signature(route) over its own fields,
so the rebuild reaction watches the city it is attached to. Every read moved:
the components take ctx.config, and the helpers below them take the values
they draw with.

Two workers were the proof of how deep it went. Both the tree-placement worker
and the layout worker wrote the global stores before calling the pure code,
because the algorithms read them as module singletons. They take a config now,
which is what they were already being sent.

buildings/material.ts was the other kind of sharing: a module-level
ShaderMaterial and icon atlas, so two cities drew with one fog colour, one
outline width, one window emission, and whichever atlas built last. It is a
BuildingMaterial per city, made from that city's config. gemFaceColors was
the same shape — one memo over the global palette — and is one memo per city.

The decoration and layout goldens are unchanged through all of it, which is what
says no building, tree or street moved.

And it reached out for the app

A city imported the app's chrome store: a canvas click opened a pane, a
keystroke collapsed the sidebar, a modal holding the keyboard was read off
OVERLAY_OPEN. Mounted anywhere else it was reaching for furniture that does
not exist.

CityChrome is the port — keyboardBusy, showDetails, revealCity — and
state/cityChrome.ts is codecity's answer to it. A session given none asks for
nothing, which is what the landing's backdrop now runs as.

The loader read ROUTE_PARAMS itself, so a session could only ever be loaded by
an address bar. Following the URL is the adapter's job, and it already owned the
other two halves of that binding: attachRouteLoad moved there, and the loader
keeps boot(view). Which surfaced a real bug — App attached it twice, so
arriving at /city ran two scans and let the generation counter drop the first.

RECENTS was being read inside the loader just to label the overlay, which two
cities would have shared: whoever opens a city passes a label instead.

So city/ is a module now

Everything a city is lives in one folder, split by the question it answers:

city/
  City.tsx  CityProvider.tsx   render one, share one
  session/   what a city IS    session, config, its settings fields, stores,
                               api, loader, timelineMode, commands
  scene/     what DRAWS it     composer, build, components, layout, render,
                               interaction, scrub, debug, types, constants

Named for what they hold: scene/state was a second "state" beside session/,
so it is scene/build — what the last apply MADE. onSettings is onConfig,
because it takes a config section and not a store. context.tsx is
CityProvider.tsx.

Its own backend calls, its settings field definitions, its excludes, its picker
types and its model — Building, Street, CityLayout — came in with it.
Every non-city user of those turned out to be a CityView pane, which is the
chrome around a city reading what it is made of; 55 app files import from the
package now.

What is left going outward is the server's contract (@/types), vocabulary the
whole app shares, and two files of generic machinery. No store, no router, no
component. city/README.md lists it in full.

One word, one meaning

A project is the city being rendered, so having both words meant one idea with
two names — and the reason "project" got invented at all is that City was
taken by the Three.js handle. The renderer layer had already voted on what it is
(SceneComponent ×31, SceneContext ×27, SceneHandle); the handle was the
outlier holding the domain word hostage.

CitySession	the city you have open, and everything it is made of
.scene → CityScene	canvas, renderer, camera, picker — from createCityScene()
useCity() under CityProvider	what the chrome calls
state/city/	where the session lives

Nothing named "project" is left in the code, and nothing named "city" means the
renderer.

Renaming the factory touched one word of prose in five files this branch had no
other business in, and the comment cap only covers what a push changes — so that
word pulled their pre-existing over-length blocks into scope. The right answer
was not to skip the rename but to put long form where it belongs:
facadePanelTextureArray.ts's 31-line header moved into FACADE_PANELS.md,
which already documents that component. Why the texture array pages, the repo
that overflowed MAX_ARRAY_TEXTURE_LAYERS, the texStorage3D allocation bug
behind dataReady = false, and what happens to an upload that beats the
renderer are all still written down — as prose you can read, with the code
pointing at it.

And one signal was not measuring time at all

Reported separately, same shape of bug: the grime streaks did not change as you
scrubbed, while colour and window light did.

They were the one date-driven signal that was not a function of now. Colour
decays from the last edit against the moment on screen; grime instead ranked
a file inside the repo's created span — where its birthday falls between the
oldest and newest file present. A scrub barely moves that span, so the streaks
were frozen by construction. Measured before touching anything: createdAge
pinned at exactly 1.000 across five years of scrubbing while modifiedAge
tracked.

Grime stays a creation-date signal — how long the building has stood, so
one laid down in 2019 and edited yesterday is grimy and vivid at once. Only its
reference changed, to the same hyperbolic curve colour and tree growth already
use, read at the scrubbed moment.

Which means a building has two clocks, not two effects that each own one.
They sit together above the factors they drive, named for their dates rather
than for whatever they happen to weather today:

		drives today
CREATED_HALF_LIFE_DAYS	365d	grime, the age-lean
MODIFIED_HALF_LIFE_DAYS	90d (was HALF_LIFE_DAYS)	colour, window light

Two rather than one because standing a year and going untouched a year are not
the same span, and a slider labelled Color should not silently re-grime a
city. The rename resets a customised colour half-life to its default, which is
deliberate.

Every other date-driven visual was already relative to now — tree height, canopy
size, firefly orbits. What rankings remain rank counts (files per commit,
commits per day), which is right: a file count does not age.

What that made dead

Ranking against a span was the only reason three things existed.

commitDateRanges is off the wire, and with it the slowest step of
assembling a bundle: it walked every file present at every commit — minutes on a
large repo — and had to report progress from inside itself because it could not
fit on one step of the readout. Assembly is three steps now, not four.

ageT — a commit's rank inside the repo's commit span — had no production
caller at all, only its own tests. Same idea, left over.

stats.commitDates fed one expression: max(newestCommit, scanDate) as the
moment trees age against. The scan date is always present (required on the
model, stamped by wrap_manifest, union manifests included), so the fallback
could not fire. That left the max, which only fires on a commit dated after
the scan — and then ages every tree in the city by that skew, when recencyT
already clamps the one odd commit by itself. Gone, with its model and the walk
that filled it. oldestCommit / newestCommit stay: the almanac names those.

AgeRange carried three fields to serve one read, so it is AgeMoment, a
number, and what a tree ages against is one day.

Two fixtures were leaning on that fallback by omitting a scan date — including
the decoration golden. They pass the newest commit explicitly now, which is what
the fallback handed them, and the golden came back bit-identical: the proof
this changes nothing a real manifest sees.

What holds it

The grime fix has its own guard: the same building must weather further the
later you scrub, with no new files needed. Broken back to the ranking, it goes
red.

tests/city/twoCities.test.ts mounts two cities at once and runs two sessions
side by side: one scanning while the other is idle, one scrubbing while the
other is live, different manifests, and neither one's source recognising the
other's. Share a single store between sessions and it goes red; re-couple the
city defaults and its other four cases go red.

Two more in that file for the second kind of sharing: override one session's
trees and the other's values and its rebuild signature stay put, and two
sessions' building materials are different objects with different atlases.

Every other guard here was broken and watched go red before being restored: the
overlay holding through the history stream, the overlay a stream-less build
raises, Timeline's reveal waiting for its frame, and the re-open that has to ask
again.

The comment cap needed one change to survive this: it runs over what a push
changes, so renaming ~245 files made one restructure answer for a backlog of 82
blocks it never wrote. A byte-identical move is skipped now; anything with a
real edit still counts, and the blocks in files this branch did touch are
trimmed here.

What this does not do

There is no multi-city UI. One session is created, the URL is pointed at it, and
the layout is the single column it always was. What changed is that a second one
is now a thing you can build rather than a thing the state layer forbids.

Nor is city/ a package you could npm i. Lifting it means carrying the 22
modules it still imports, or declaring them as peer dependencies — the server's
contract, shared vocabulary, and generic machinery. The part that matters is
that none of them is the app: what a city needs from its host is three methods.

One behavior change worth knowing

A landing visited before you have ever opened a project now frames its wallpaper.
The CURRENT_SOURCE_KEY guard used to leave that case on the boot pose, since
there was no key for it to change.