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.

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.

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.

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.

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.