Extract the city into @codecity/city

.codecityignore

@@ -1,2 +1,2 @@
-api/tests/fixtures/large-repo
-api/tests/fixtures/sample-repo
+packages/api/api/tests/fixtures/large-repo
+packages/api/api/tests/fixtures/sample-repo

.dockerignore

@@ -1,34 +1,29 @@
-# Version control + CI scaffolding
+# At the build-context root, because that is what `docker build .` sends.
+# Globs, not package paths: a new package inherits them.
+
 .git
 .github
 
-# Python local
-.venv
-.mypy_cache
-.pytest_cache
-.ruff_cache
-api/__pycache__
+# Python
+**/.venv
 **/__pycache__
 **/*.pyc
+**/.mypy_cache
+**/.pytest_cache
+**/.ruff_cache
+
+# Node
+**/node_modules
+**/dist
+**/.vite
 
-# Node local
-node_modules
-app/node_modules
-app/dist
-app/.vite
 
-# Codecity local artifacts
+# Local-run scratch and tool artifacts
 .local
-.codecity
 .codecityignore
-
-# Tool artifacts
 .claude
-.superpowers
 docs
-
-# Stale static dir (legacy)
-api/static
+TODO.md
 
 # OS / editors
 **/.DS_Store
@@ -38,9 +33,3 @@ api/static
 *~
 .idea
 .vscode
-
-# Repo-level scaffolding not needed at build time
-TODO.md
-# NOTE: README.md and LICENSE are NOT ignored — pyproject.toml references
-# them (`readme = "README.md"`, `license = { file = "LICENSE" }`), and
-# hatchling validates their existence during the wheel build.

.github/workflows/ci.yml

@@ -49,8 +49,8 @@ jobs:
         # pyproject.toml's pytest addopts already include
         # `--cov=api --cov-report=term --cov-fail-under=80`. The extra
         # `--cov-report=xml:/srv/api/coverage.xml` lands the XML report
-        # inside the mounted `./api` dir so it's visible on the host for
-        # artifact upload (the compose service only mounts ./api, uv.lock,
+        # inside the mounted `./packages/api/api` dir so it's visible on the host for
+        # artifact upload (the compose service only mounts ./packages/api/api, uv.lock,
         # and pyproject.toml — not the repo root).
         run: |
           docker compose -f docker-compose.test.yml run --rm pytest \
@@ -61,7 +61,7 @@ jobs:
 
       # Stdlib-only, so it runs on the runner rather than paying for a container.
       - name: Python comment cap
-        run: python3 bin/check-comments.py api bin scripts
+        run: python3 bin/check-comments.py packages/api/api packages/api/scripts bin
 
       # Reads PYRIGHT_VERSION from the repo-root .env, which compose loads
       # automatically — no `env:` mirror needed here, unlike NPM_VERSION
@@ -72,36 +72,51 @@ jobs:
       - name: Run vitest with coverage
         # Override the default compose command (which runs `npm test`) to
         # run `npm run coverage` instead. Same apt-get / npm bootstrap as
-        # the compose service. Output lands in app/coverage/ on the host
-        # via the ./app:/app bind mount.
+        # the compose service. Output lands in packages/app/coverage/ on the host
+        # via the ./packages/app:/app bind mount.
         run: |
           docker compose -f docker-compose.test.yml run --rm vitest \
+            sh -c "apt-get update && apt-get install -y --no-install-recommends libexpat1 fontconfig fonts-dejavu-core && npm install -g npm@$NPM_VERSION && (cd /city && npm ci) && npm ci && npm run coverage"
+
+      - name: Run the city's vitest with coverage
+        run: |
+          docker compose -f docker-compose.test.yml run --rm city-vitest \
             sh -c "apt-get update && apt-get install -y --no-install-recommends libexpat1 fontconfig fonts-dejavu-core && npm install -g npm@$NPM_VERSION && npm ci && npm run coverage"
 
       - name: Upload pytest coverage report
         if: always()
         uses: actions/upload-artifact@v7
         with:
           name: pytest-coverage
-          path: api/coverage.xml
+          path: packages/api/api/coverage.xml
           if-no-files-found: warn
 
       - name: Upload vitest coverage report
         if: always()
         uses: actions/upload-artifact@v7
         with:
           name: vitest-coverage
-          path: app/coverage/
+          path: packages/app/coverage/
+          if-no-files-found: warn
+
+      - name: Upload city vitest coverage report
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: city-vitest-coverage
+          path: packages/city/coverage/
           if-no-files-found: warn
 
       - name: Lint + typecheck
         run: |
           docker compose -f docker-compose.test.yml run --rm vitest \
-            sh -c "apt-get update && apt-get install -y --no-install-recommends libexpat1 fontconfig fonts-dejavu-core && npm install -g npm@$NPM_VERSION && npm ci && npm run lint && npm run typecheck"
+            sh -c "apt-get update && apt-get install -y --no-install-recommends libexpat1 fontconfig fonts-dejavu-core && npm install -g npm@$NPM_VERSION && (cd /city && npm ci) && npm ci && npm run lint && npm run typecheck && npm run format:check"
 
-      # Its own service: the app-scoped vitest service can't see the root config.
-      - name: Format check (prettier)
-        run: docker compose -f docker-compose.test.yml run --rm prettier
+      # Prettier lives inside each package, so there is no repo-wide format
+      # check — README, AGENTS.md, compose and these workflows belong to no
+      # package and are hand-formatted.
+      - name: city/ typecheck + format check
+        run: docker compose -f docker-compose.test.yml run --rm packages
 
       # Only the schema is written out here; the container owns everything node.
       # npm on the runner cannot work: compose mounts anonymous volumes over
@@ -110,7 +125,7 @@ jobs:
         run: |
           curl -LsSf https://astral.sh/uv/install.sh | sh
           mkdir -p .local
-          "$HOME/.local/bin/uv" run python scripts/gen_openapi.py > .local/openapi.generated.json
+          "$HOME/.local/bin/uv" run --project packages/api python packages/api/scripts/gen_openapi.py > .local/openapi.generated.json
           docker compose -f docker-compose.test.yml run --rm gentypes
 
       - name: Trivy scan

.gitignore

@@ -1,5 +1,5 @@
-# Output
-.codecity/
+# Repo-level only. Anything a single package generates is ignored by that
+# package's own .gitignore, so lifting one out takes its ignores with it.
 
 # Your own settings and credentials, seeded from .env.local.example.
 # .env itself is tracked: it holds what everyone shares.
@@ -9,58 +9,20 @@
 # always safe to delete.
 .local/
 
-# Tool artifacts
-.superpowers/
-
-# Generated test fixtures
-#   run `bash api/tests/fixtures/setup.sh` to regenerate
-api/tests/fixtures/sample-repo/
-api/tests/fixtures/.sample-repo-ready
-api/tests/fixtures/.sample-repo-setup.lock
-#   run `bash api/tests/fixtures/large-repo-setup.sh` to regenerate
-api/tests/fixtures/large-repo/
+# The root is not an npm project, but running a package's vitest from here
+# leaves vite's cache behind. Nothing installs into it.
+node_modules/
 
 # OS
 .DS_Store
 Thumbs.db
 
-# Dependencies
-node_modules/
-
-# Vite caches
-.vite/
-app/.vite/
-
-# vitest coverage report output
-app/coverage/
-
-# pytest-cov output
-#   .coverage   = SQLite data file (default)
-#   coverage.xml = Cobertura XML (CI artifact, written into api/ via
-#                  --cov-report=xml:/srv/api/coverage.xml in ci.yml)
-.coverage
-coverage.xml
-api/coverage.xml
-
-# Python
-__pycache__/
-*.pyc
-.venv/
-dist/
-*.egg-info/
-.pytest_cache/
-.mypy_cache/
-.ruff_cache/
-
 # Editors
 *.swp
 *.swo
 *~
 .idea/
 .vscode/
 
-# Visual regression diff output (generated by verify-references.ts)
-app/tests/visual/references-diff/
-
 # Claude Code session scratch (per-dev handoff notes, local settings)
 .claude/

AGENTS.md

@@ -110,20 +110,65 @@ leaving those containers pointing at a gone network (`just dev` then fails with
 
 ## Layout
 
-- `app/` — Preact + TypeScript frontend. Two routes, one view each: `/` is the
-  landing (pick a project) and `/city?src=…` is a world. The URL is the source of
-  truth for both — `router/` owns it, and `?src`, `?mode`, `?commit` and `?sel`
-  all survive Back and Forward.
-  - `src/city/` — the 3D city, a signals-driven mini-app. Layout runs in a
-    worker under `src/city/layout/` (snapshot-tested — keep output identical).
-  - `src/state/` — seven stores under `stores/`, each named for the question it
-    answers. `settings/` is its own subsystem: schema, drafts, reactions and
-    indicators over the fields they operate on.
+Everything the product is made of lives under `packages/`. `bin/` and
+`.github/` are how it gets built and shipped; the split is what stops the two
+kinds from interleaving alphabetically at the repo root.
+
+Each package is independent: its own manifest, its own lockfile, its own
+installed dependencies. Lifting one into a repo of its own is a copy, not a
+untangling.
+
+- `packages/app/` (`codecity`) and `packages/city/` (`@codecity/city`) — two
+  separate npm projects, each with its own `package.json`, `package-lock.json`,
+  `node_modules` and prettier.
+  There is no npm project at the repo root, so nothing formats `README.md`,
+  `AGENTS.md`, the compose files or the workflows: those belong to no package
+  and are hand-formatted on purpose.
+- `packages/city/` (`@codecity/city`) — the 3D renderer and the client every
+  backend call goes through. `createCity(canvas)` is the whole entry point: hand
+  it a canvas and an api base, and it fetches, builds, and reports what it is
+  doing. It depends on `three`, `three-mesh-bvh` and `rbush`, and on nothing
+  else — no Preact, no signals, no reactive runtime. Everything is per instance,
+  so two cities on one page share no settings, selection, timeline or GPU
+  resources; the landing's wallpaper and the `/city` scene are two such cities.
+  - Values in, events out. The consumer owns settings values and pushes them
+    with `updateSettings`; the city reports with `on(kind, listener)`. Layout
+    runs in a worker under `src/layout/` (snapshot-tested — keep output
+    identical).
+  - `src/index.ts` is the public surface. `tests/index.ts` is a second one,
+    `@codecity/city/testing`: the wire fixtures and stubs a consumer needs to
+    test against a city. The renderer stubs sit behind
+    `@codecity/city/testing/three` — a `vi.mock('three')` factory that awaits
+    the main barrel deadlocks, because the barrel reaches source that imports
+    three.
+  - Every import inside this package is RELATIVE, and there is no path alias to
+    add one back. An alias in published source resolves only if the consumer
+    maps the same prefix; ours did, which hid the fact that nobody else could.
+    The app reaches this package through `@codecity/city` and nothing else — a
+    test may reach past that surface, by explicit path so it says so, but no
+    file under `src/` may.
+- `packages/app/` — Preact + TypeScript frontend. Two routes, one view each:
+  `/` is the landing (pick a project) and `/city?src=…` is a world. The URL is
+  the source of truth for both — `router/` owns it, and `?src`, `?mode`,
+  `?commit` and `?sel` all survive Back and Forward.
+  - This is where signals live. `state/stores/city.ts` is the seam: it holds the
+    handle, mirrors the city's hover and selection onto app signals, and
+    attaches the app's half of each event family (`attachCityChrome`,
+    `attachBuildProgress`, `attachScanProgress`).
+  - `src/state/` — stores under `stores/`, each named for the question it
+    answers. `settings/` is its own subsystem: the city declares the fields and
+    what each one costs, the app owns their values, persistence and signals.
   - `src/components/` — grouped by what a component is, not where it appears. A
     component used by exactly one thing lives beside that thing instead.
-- `api/` — FastAPI backend that walks the repo and serves the manifest. Layered,
-  and imports only ever point down: `routers/` → `scan/` → `git/` and `cache/` →
-  `models/`, `core/`, `utils/`.
+  - `tests/integration/` is the seam under test: the app driving a real city.
+    Everything testing the city itself lives in `packages/city/tests/`.
+- `packages/api/` — the Python project: `pyproject.toml`, `uv.lock`, and its own
+  README and LICENSE (hatchling refuses paths outside the project directory).
+  The importable package is `packages/api/api/`, because Python resolves
+  `import api` by finding a directory named `api` and the manifest has to sit
+  above the directory it names. FastAPI backend that walks the repo and serves
+  the manifest. Layered, and imports only ever point down: `routers/` →
+  `scan/` → `git/` and `cache/` → `models/`, `core/`, `utils/`.
   - `routers/` — the whole HTTP surface, one module per route family. `sse.py`
     is the streaming plumbing the two SSE routes share, not a route.
   - `git/`, `scan/` and `cache/` each curate a barrel in `__init__`.