Run request analysis on demand on the VPS

docs/kb/systems/chunk-storage-streaming.md

@@ -0,0 +1,48 @@
+# Chunk Storage And Streaming
+
+## What It Does
+
+World data is stored as per-chunk JSON files and loaded into the editor as chunk neighborhoods around a center chunk. The runtime caches chunk payloads, shifts neighborhoods as the viewport moves, and saves dirty chunks in batches.
+
+## Key Files
+
+- `server.js`
+- `src/worldChunking.ts`
+- `src/worldshaperStudio/bootstrap.ts`
+- `src/worldshaperStudio/runtime.ts`
+- `src/worldshaperStudio/persistenceController.ts`
+
+## Endpoints It Uses
+
+- `GET /api/world/:worldId/chunk/:chunkX/:chunkY`
+- `POST /api/world/:worldId/chunk/:chunkX/:chunkY`
+- `GET /api/world/:worldId/chunks`
+- `POST /api/world/:worldId/chunks/batch-save`
+
+## Important Data And Rules
+
+- chunks are stored as `content/worlds/<worldId>/chunks/<x>_<y>.json`
+- world neighborhoods are requested as a square around a center chunk
+- runtime keeps a chunk cache and tracks dirty chunk keys
+- chunk payloads include `roomLayers`, `heightLayers`, `instances`, and optional `backgroundTileId`
+
+## Invariants And Constraints
+
+- Exact chunk lookup is grid-based and direct.
+- The editor does not load the entire world for normal editing.
+- Small tile edits must sync back into the correct cached chunk.
+- Save flow should preserve chunk-local edits without rebuilding unrelated chunks.
+
+## Common Request Themes
+
+- chunk loading speed
+- chunk streaming behavior
+- per-chunk backgrounds
+- chunk transforms, duplication, deletion
+- performance questions around indexing and caching
+
+## Triage Questions
+
+- Is the request about storage, fetch patterns, cache behavior, or save behavior?
+- Does it affect only visible chunks or the full world?
+- Is the user asking for chunk-local data, or freeform world overlays that break chunk assumptions?

docs/kb/systems/content-catalog-records.md

@@ -0,0 +1,51 @@
+# Content Catalog And Records
+
+## What It Does
+
+This subsystem manages tiles, sprites, images, and related metadata. It is the bridge between authored graphics data and the editor features that paint, preview, import, and delete those records.
+
+## Key Files
+
+- `server.js`
+- `src/App.tsx`
+- `src/components/worldshaperShared.ts`
+- `src/worldshaperStudio/graphicsDocumentHelpers.ts`
+- `src/worldshaperStudio/importController.ts`
+
+## Endpoints It Uses
+
+- `GET /api/content/:type`
+- `POST /api/content/:type`
+- `POST /api/content/tiles/:tileId/delete`
+- `POST /api/content/sprites/:spriteId/delete`
+- `GET /api/catalog-meta`
+- `POST /api/catalog-meta`
+- `GET /api/images`
+- `GET /api/images/:filename`
+
+## Important Data And Rules
+
+- tiles and sprites are content records, not world chunk records
+- tile symbols are used heavily by painting and rendering paths
+- deleting tiles or sprites can require scrubbing world references
+- catalog metadata can influence grouping and presentation
+
+## Invariants And Constraints
+
+- content ids must stay stable if worlds reference them
+- deletion flows need to consider world data cleanup
+- image availability affects painter previews and imports
+- schema drift here can break multiple editor systems at once
+
+## Common Request Themes
+
+- better tile metadata
+- sprite or tile deletion behavior
+- import and catalog organization
+- richer animation metadata on graphics records
+
+## Triage Questions
+
+- Is the request about the content record itself, or how it is used in-world?
+- Will this require schema changes to tiles or sprites?
+- Could this impact rendering, painting, and save behavior all at once?

docs/kb/systems/floating-window-shell.md

@@ -0,0 +1,44 @@
+# Floating Window Shell
+
+## What It Does
+
+Worldshaper relies on separate floating windows and internal popout shells for several tools. This subsystem defines how the main studio window opens, how internal tool windows are placed, and how overlay-layer tools are managed inside the editor.
+
+## Key Files
+
+- `src/worldshaperStudio/windowing.ts`
+- `src/worldshaperStudio/floatingWindowUtils.ts`
+- `src/worldshaperStudio/toolWindowController.ts`
+- `src/worldshaperStudio/changelogSplashWindowController.ts`
+- `src/worldshaperStudio/engineOverrideWindowController.ts`
+
+## Endpoints It Uses
+
+- none directly
+
+## Important Data And Rules
+
+- the launcher opens the studio in a new browser window
+- many studio tools use internal popout shells layered above the editor
+- floating window state may be persisted per tool
+- focus, z-index, clamp-to-viewport, and drag behavior all live here
+
+## Invariants And Constraints
+
+- popup blocking can break launch
+- tool windows should stay usable on small screens
+- tool windows should not render behind the main viewport layer
+- window persistence should not trap a tool off-screen forever
+
+## Common Request Themes
+
+- docking and undocking
+- better positioning behavior
+- tool window focus bugs
+- opening or closing auxiliary windows
+
+## Triage Questions
+
+- Is the request about the external studio window, or internal tool popouts?
+- Does it depend on persisted window coordinates?
+- Does it affect one tool window or the shared shell behavior?

docs/kb/systems/graphics-painter.md

@@ -0,0 +1,48 @@
+# Graphics Painter
+
+## What It Does
+
+The Graphics Painter is the tile and sprite art editing window. It handles pixel editing, frame management, animation timeline editing, preview playback, and import-oriented art workflows.
+
+## Key Files
+
+- `src/worldshaperStudio/tileArtEditorWindowController.ts`
+- `src/worldshaperStudio/graphicsDocumentHelpers.ts`
+- `src/worldshaperStudio/importController.ts`
+- `src/worldshaperStudio/dom.ts`
+
+## Endpoints It Uses
+
+- `GET /api/images`
+- `GET /api/images/:filename`
+- `POST /api/content/images`
+- `POST /api/content/sprites`
+- `POST /api/content/tiles`
+
+## Important Data And Rules
+
+- graphics records may include animation frame data and playback metadata
+- preview behavior is maintained in painter-local UI state
+- art changes eventually flow into tile and sprite content records
+- imports and previews are tightly tied to painter usability
+
+## Invariants And Constraints
+
+- the painter is a floating tool window, not a docked pane
+- animation preview should reflect current frame ordering and speed settings
+- save behavior must preserve frame structure and timing metadata
+- painter workflows often depend on tile and sprite schema conventions
+
+## Common Request Themes
+
+- move or selection tools
+- frame duplication and frame management
+- animation controls
+- import workflow improvements
+- better preview behavior
+
+## Triage Questions
+
+- Is this request about art authoring, record storage, or runtime playback?
+- Does it affect tiles, sprites, or both?
+- Is the requested behavior inside the painter window only?

docs/kb/systems/launcher-home.md

@@ -0,0 +1,42 @@
+# Launcher Home
+
+## What It Does
+
+The launcher is the public-facing entry point for Worldshaper. It presents the hero card, opens the editor in its own floating window, links to the repo, and hosts the News and Requests tabs.
+
+## Key Files
+
+- `src/WorldshaperLauncher.tsx`
+- `src/index.css`
+- `src/worldshaperStudio/windowing.ts`
+
+## Endpoints It Uses
+
+- `GET /api/world-default`
+- `GET /api/launcher-requests`
+
+## Important State
+
+- launch state: ready, opening, opened, blocked, error
+- active board tab: news or requests
+- request list, filters, and expanded request rows
+- resolved default world id
+
+## Invariants And Constraints
+
+- The editor is intended to open in a separate popup-style window.
+- The launcher should still work if the default world lookup fails by falling back to `overworld`.
+- Browser popup blocking is a real failure mode and must be surfaced to the user.
+
+## Common Request Themes
+
+- page styling and presentation
+- launch flow and popup behavior
+- repo button or external links
+- tab layout and launcher information architecture
+
+## Triage Questions
+
+- Is this about the launcher page itself, or the studio window after launch?
+- Does it affect only presentation, or also request API behavior?
+- Does it depend on popup/window behavior?

docs/kb/systems/layers-tile-editing.md

@@ -0,0 +1,47 @@
+# Layers And Tile Editing
+
+## What It Does
+
+This subsystem handles normal tile painting, erasing, selection, visible layer management, sparse height layers, and the mapping between visible document edits and stored chunk data.
+
+## Key Files
+
+- `src/worldshaperStudio/interactionController.ts`
+- `src/worldshaperStudio/runtime.ts`
+- `src/worldshaperStudio/sidebarController.ts`
+- `src/worldshaperStudio/mapDocumentController.ts`
+- `src/worldshaperStudio/popupSessionStore.ts`
+- `src/worldshaperStudio/dom.ts`
+
+## Endpoints It Uses
+
+- primarily saved through `POST /api/world/:worldId/chunks/batch-save`
+
+## Important Data And Rules
+
+- room layer `0` is the base layer
+- non-base layers use sparse or transparent-style fill semantics
+- height layers are separate structures from room layers
+- visibility is tracked in popup session state
+- painting in world mode must mark affected chunks dirty
+
+## Invariants And Constraints
+
+- layer ordering matters to rendering and selection behavior
+- layer visibility must not destroy layer data
+- tile edits in world mode must map local viewport coordinates back to world chunk coordinates
+- height layers are not the same thing as standard room layers
+
+## Common Request Themes
+
+- better layer reordering
+- more precise tiling tools
+- height/elevation features
+- snapping or unsnapped placement
+- erase or selection behavior
+
+## Triage Questions
+
+- Is this about normal room layers or height layers?
+- Does the request affect paint semantics, visibility, ordering, or storage?
+- Does it apply to map mode, world mode, or both?

docs/kb/systems/persistence-save-pipeline.md

@@ -0,0 +1,49 @@
+# Persistence And Save Pipeline
+
+## What It Does
+
+This subsystem turns editor state into saved content and world data. It persists content records, world metadata, bookmarks, and dirty chunks, while keeping save state and toolbar status in sync.
+
+## Key Files
+
+- `src/worldshaperStudio/persistenceController.ts`
+- `src/worldshaperStudio/historyController.ts`
+- `src/worldshaperStudio/historyStateStore.ts`
+- `server.js`
+
+## Endpoints It Uses
+
+- `POST /api/world/:worldId/chunks/batch-save`
+- `POST /api/content/:type`
+- `GET /api/editor-settings`
+- `POST /api/editor-settings`
+- `GET /api/catalog-meta`
+- `POST /api/catalog-meta`
+
+## Important Data And Rules
+
+- world save batches metadata, bookmarks, and dirty chunks together
+- content saves are per content type
+- successful world saves clear dirty chunk keys
+- save failures surface through status messages and toolbar state
+
+## Invariants And Constraints
+
+- save must not lose dirty chunk edits
+- content records and world chunks have different persistence paths
+- history state should know when a save succeeds
+- partial failures need clear error reporting
+
+## Common Request Themes
+
+- save reliability
+- auto-save ideas
+- validation before save
+- batch save size or performance
+- stale content vs world metadata mismatches
+
+## Triage Questions
+
+- Is the failure on world save, content save, or both?
+- Are we persisting the right data, but at the wrong time?
+- Does the request need new API support or just better client save orchestration?

docs/kb/systems/rendering-viewport.md

@@ -0,0 +1,45 @@
+# Rendering And Viewport
+
+## What It Does
+
+This subsystem draws the active world or map, manages Pixi chunk surfaces, keeps chunk visibility in sync with the viewport, and overlays debug and selection information on top of the scene.
+
+## Key Files
+
+- `src/worldshaperStudio/renderController.ts`
+- `src/worldshaperStudio/pixiTileStageController.ts`
+- `src/worldshaperStudio/pixiSceneRebuildHelpers.ts`
+- `src/worldshaperStudio/pixiChunkSurfaceHelpers.ts`
+- `src/worldshaperStudio/overlayRenderer.ts`
+
+## Endpoints It Uses
+
+- none directly; it consumes already-loaded document and chunk data
+
+## Important Data And Rules
+
+- chunk surfaces are built per layer and per chunk
+- viewport movement drives visible chunk culling
+- Pixi visibility is separate from data caching
+- debug snapshots expose visible chunk counts and renderer state
+
+## Invariants And Constraints
+
+- rendering changes must respect layer visibility
+- the viewport can hide chunk sprites without unloading their cached data
+- background tile behavior is special for base-layer rendering
+- performance work needs profiling because rendering cost and fetch cost are different problems
+
+## Common Request Themes
+
+- rendering performance
+- chunk culling
+- animation playback in-world
+- background drawing behavior
+- viewport glitches on very large worlds
+
+## Triage Questions
+
+- Is the request about data load, or only about drawing what is already loaded?
+- Is the issue specific to Pixi chunk surfaces?
+- Does it reproduce only at certain zoom levels or viewport sizes?

docs/kb/systems/request-board.md

@@ -0,0 +1,54 @@
+# Request Board
+
+## What It Does
+
+The request board lives on the launcher and stores lightweight user submissions. It currently supports pending and active request states, filtering, expansion of active items, and deletion with confirmation.
+
+## Key Files
+
+- `src/WorldshaperLauncher.tsx`
+- `server.js`
+- `data/launcher_requests.json`
+
+## Endpoints It Uses
+
+- `GET /api/launcher-requests`
+- `POST /api/launcher-requests`
+- `PATCH /api/launcher-requests/:requestId`
+- `DELETE /api/launcher-requests/:requestId`
+
+## Important Data Shape
+
+Current request records include:
+
+- `id`
+- `sourceSubmissionId`
+- `title`
+- `status`
+- `category`
+- `tags`
+- `sourceText`
+- `summary`
+- `implementationNotes`
+- `createdAt`
+- `updatedAt`
+
+## Invariants And Constraints
+
+- New submissions enter as pending unless promoted.
+- One raw submission may contain multiple real feature requests.
+- Active requests should be normalized, titled, and tagged.
+- Deletion is destructive and should remain explicit.
+
+## Common Request Themes
+
+- parse and split user submissions
+- request tags and filtering
+- moderation and cleanup
+- queue automation and confidence review
+
+## Triage Questions
+
+- Is the user asking to change request storage, presentation, or parsing behavior?
+- Should one submission become many active requests?
+- Is the request really a bug report or a feature idea?

docs/kb/systems/world-bootstrap.md

@@ -0,0 +1,45 @@
+# Studio Bootstrap
+
+## What It Does
+
+Bootstrap prepares the initial studio session. It resolves the target world, loads world metadata, bookmarks, and the first chunk neighborhood, then composes the initial editable document shown in the studio window.
+
+## Key Files
+
+- `src/worldshaperStudio/bootstrap.ts`
+- `src/worldshaperStudio/main.ts`
+- `src/worldshaperStudio/runtime.ts`
+
+## Endpoints It Uses
+
+- `GET /api/world-default`
+- `GET /api/world/:worldId`
+- `GET /api/world/:worldId/bookmarks`
+- `GET /api/world/:worldId/chunks`
+
+## Important State
+
+- current world id and world metadata
+- chunk width and height
+- source chunk list
+- bookmark-derived initial camera position
+- initial composed document layers and height layers
+
+## Invariants And Constraints
+
+- World mode starts from a chunk neighborhood, not a full-world payload.
+- Bookmarks can influence the initial view center.
+- Bootstrap has to hydrate enough content catalogs for tiles and sprites to render correctly.
+
+## Common Request Themes
+
+- startup performance
+- opening the wrong world or stale world state
+- incorrect first camera position
+- missing tiles or sprites on first load
+
+## Triage Questions
+
+- Is the problem visible only at startup?
+- Does the issue disappear after movement or reload?
+- Is it a missing bootstrap dependency, or a later runtime bug?

docs/kb/systems/world-overview.md

@@ -0,0 +1,45 @@
+# World Overview
+
+## What It Does
+
+World Overview is a separate window that displays a coarse map of all known chunks, supports bookmark navigation, and exposes chunk operations such as move, duplicate, rotate, flip, delete, and background adjustments.
+
+## Key Files
+
+- `src/worldshaperStudio/worldOverviewWindowController.ts`
+- `src/worldshaperStudio/dom.ts`
+- `server.js`
+
+## Endpoints It Uses
+
+- `GET /api/world/:worldId/overview`
+- `GET /api/world/:worldId/bookmarks`
+- bookmark writes flow through the world save path
+
+## Important Data And Rules
+
+- overview currently requests the full set of world chunks from the server
+- it draws its own chunk preview surfaces
+- it merges server chunks with cached client chunks to reflect unsaved local state
+- chunk context menus expose world-level operations
+
+## Invariants And Constraints
+
+- overview is only available in world mode
+- overview actions should not silently discard unsaved chunk edits
+- chunk transform actions must preserve chunk addressing rules
+- the full overview payload can become a performance hotspot on larger worlds
+
+## Common Request Themes
+
+- chunk operations
+- world navigation
+- bookmark workflows
+- overview performance
+- better high-level visualization
+
+## Triage Questions
+
+- Is the issue specific to the overview window, or all world editing?
+- Does it affect overview drawing only, or also chunk save/load behavior?
+- Is the request about overview scale, navigation, or chunk manipulation?