docs(mapgen-studio): add pass-2 design-fix frame, five OpenSpec slices (layout geometry, form hierarchy, run console, explore toolbar, first-run visibility)

[mateicanavra]

Pass 2 — Design Fixes (visually-grounded, spec-driven)

Following a direct visual inspection of the running studio (dark, 1600×950), the Pass 1 redesign was found to still read as squished and not functionally complete. The root cause: Pass 1 interpreted "preserve as-built dimensions" as covering chrome geometry, which meant the old pre-redesign skeleton shipped under new paint. This pass relaxes that constraint — control density stays inviolate, chrome geometry is redesigned.

What's wrong and why

Nine defects were identified from live inspection and DOM measurement, resolving to five fix slices:

• C1 — Layout geometry: The left dock is still 280px (helper prose wraps 3–4 lines per field); an ~88px dead band sits between the header and docks because AppHeader forces minHeight: 104 even though a ResizeObserver already measures the real header height; the recipe panel caps itself with a magic calc(100vh-180px) that cuts content mid-sentence with no scroll affordance.
• C2 — Form hierarchy: Field labels and descriptions render at the same size and color (text-muted-foreground), making the form a wall of indistinguishable gray. Separately, the field template mounts ~40 empty role="alert" live regions because it gates on the always-truthy errors element rather than rawErrors?.length.
• C3 — Run console: Two simultaneous "Run" primary CTAs exist (recipe panel bottom + footer). The footer's last-run summary renders "Bal" — a deliberate abbreviation that reads as accidental truncation.
• C4 — Explore toolbar: The Render and Space option clusters render as loose icon rows with no container boundary, reading as decoration rather than mutually-exclusive controls.
• C5 — First-run visibility: After a successful first run, the canvas stays visually black. The default Foundation/Mesh selection renders nothing the eye can find; matter only appears after manually selecting a later stage.

Changes introduced

Design system amendment (system.md, pass-2-design-fixes.md, 00-GOAL.md): documents the constraint relaxation, the nine observed issues mapped to five slices, and a falsifier — if the chrome still reads squished after C1+C2, the floating-panel paradigm itself is the problem and a structural relayout becomes the next frame.

C1 — mapgen-studio-layout-geometry: PANEL_WIDTH 280 → 340; EXPLORE_PANEL_WIDTH corrected to 260; HEADER_HEIGHT re-stated as the ResizeObserver seed (≈48), not a reserve. AppHeader drops the static minHeight. Docks gain a bottom constraint so panels span the full header→footer column. RecipePanel replaces the magic height cap with max-h-full; ExplorePanel gains internal scrolling. A sticky token-driven bottom fade replaces hard scroll cuts.

C2 — mapgen-studio-form-hierarchy: Field labels move to text-foreground medium weight in both rjsfTemplates.tsx and the hand-rolled field set; descriptions stay muted. The error live region gates on rawErrors?.length — zero empty role="alert" nodes on a pristine form, with the id="${id}__error" association contract preserved for fields that do have errors.

C3 — mapgen-studio-run-console: The recipe panel's Run button is removed; its footer row becomes Save & Deploy only. The dirty-config ring emphasis moves to the footer Run. formatResourceMode returns full words ("Balanced", etc.).

C4 — mapgen-studio-explore-toolbar: Render and Space option clusters become bounded segmented controls (bg-input-background container, active option lifted one surface tier). Independent toggles (fit, edges, debug) are left unwrapped.

C5 — mapgen-studio-first-run-visibility: Diagnosis is required before code — root cause (camera never fitted to first manifest bounds vs. inherently invisible default layer) recorded in design.md. Fix triggers the existing fit-to-view path when a run completes and the camera has never been positioned over generated matter; a user-positioned camera is never auto-refit on subsequent runs.

Each slice closes only with visual proof from the running app (screenshot or measured DOM delta, dark and light where theming is implicated).

[mateicanavra]

• feat(mapgen-studio): standalone Bun daemon owns the server surface — vite is frontend-only; legacy /api retired outright #1652 : 2 dependent PRs (#1653 , #1654 )
• refactor(mapgen-studio): control-oRPC mount on the fetch adapter behind a Connect shim #1651
• refactor(mapgen-studio): extract studio engines out of vite.config into src/server/studio (verbatim move, no topology change) #1650
• docs(mapgen-studio): bun-server workstream frame — P5b cutover proposal/design/tasks/spec (strict valid) #1649
• fix(mapgen): projection step phases carry their subject domain, not 'gameplay' #1648
• refactor(mapgen-studio): recipe-dag oRPC mount — fetch adapter, per-request ssrLoadModule, shared node⇄web bridge #1647
• feat(mapgen-studio): add Pipeline stage view with Map|Pipeline switcher, TanStack Query DAG data layer, and token-driven PipelineStage chrome #1646
• docs(mapgen-studio): add pipeline DAG stage-view workstream record, proposal, design, spec deltas, and tasks #1645
• docs(mapgen-studio): mark X6 and X7 as executed with hex-convention audit and world-console map-params revision notes #1644
• feat(mapgen-studio): remove Resources control from World console, codify pipeline-input zone boundary rule #1643
• fix(studio): render game's odd-R hex geometry for both tile spaces and retune tile border to graphite #1642
• docs(mapgen-studio): record Pass-5 design fixes (toolbar v2, tile orientation, grid icon, flash guard, pre-run cursor) #1641
• fix(mapgen-studio): apply flash guard to :root for between-navigations clear color #1640
• feat(mapgen-studio): disable canvas controller and grab cursor pre-run #1639
• fix(mapgen-studio): odd-Q flat-top orientation, canonical hex-space lattice, and tile-mesh contract #1638
• fix(mapgen-studio): replace empty grid toggle placeholder with Grid3x3 lucide icon #1637
• feat(mapgen-studio): toolbar architecture v2 — top = Game bar, bottom = World/Map console with History affordance #1636
• docs(mapgen-studio): add Pass 5 design-fixes spec (toolbar architecture v2, tile orientation, canvas affordances) #1635
• feat(mapgen-studio): add collapsible config objects with per-object header anatomy, sticky auto-expand-on-scroll toggle, and useConfigCollapse hook #1634
• feat(mapgen-studio): icon-only autoplay and run-in-game buttons, add Explore placeholder #1633
• feat(studio): dock game console beneath world bar, remove it from footer #1632
• docs(mapgen-studio): add Pass-4 design fixes — game console dock, console icon contract, and config collapse #1631
• feat(explore-toolbar): regroup into VIEW/LAYER clusters and relocate debug toggle to data list header #1630
• feat(mapgen-studio): extract GameConsole component and split footer into centered studio console and right-docked game console #1629
• feat(mapgen-studio): replace border-l indent ladder with page-tint well surface and codify 4/8/12px rhythm tiers #1628
• docs(mapgen-studio-no-hardcoded-defaults): mark all tasks as executed #1627
• fix(mapgen-studio): replace global reset with body-only flash guard and align theme bootstrap with useTheme system-preference resolution #1626
• docs(mapgen-studio): pass-3 frame — spacing substrate repair, config surface elevation, footer console split, explore toolbar grouping, and no-hardcoded-defaults law #1625
• fix(mapgen-studio): sync .dark class to theme preference at runtime #1624
• fix(mapgen-studio): add rAF backstop timeout to prevent viz commits being starved in backgrounded documents #1623
• feat(mapgen-studio): wrap Render and Space toolbar options in segmented controls #1622
• feat(mapgen-studio): remove Run button from RecipePanel footer, promote Save & Deploy to full-width, and expand resource mode labels #1621
• fix(mapgen-studio): split field label to foreground tier and gate error live regions on rawErrors #1620
• feat(mapgen-studio): pin docks between header and footer with bottom constraint, pointer-events pass-through, and LAYOUT geometry update #1619
• docs(mapgen-studio): add pass-2 design-fix frame, five OpenSpec slices (layout geometry, form hierarchy, run console, explore toolbar, first-run visibility) #1618 👈 (View in Graphite)
• feat(studio): a11y fixes — Radix save menu, rjsf error association, skip-link target, and group disclosure names #1617
• refactor(mapgen-studio): remove legacy createTheme/lightMode prop threading and dead field primitives; migrate rjsf chrome to design-system tokens #1616
• refactor(mapgen-studio): centralize ORPCError data cast, drop dead success fallbacks, and narrow router to contract-derived type #1615
• feat(mapgen-studio): migrate authoring/run state to Zustand persist stores, reads to TanStack Query, and fix runInGame contract selectedConfig.id optional #1614
• feat(mapgen-studio): token-driven chrome, a11y landmarks/live-regions/aria, and OptionSelect adapter #1613
• fix(mapgen-studio): wrap AppFooter test in TooltipProvider and add @ alias to vitest config #1612
• feat(mapgen-studio): decompose App.tsx into StudioProviders/StudioShell + chrome tree #1611
• feat(mapgen-studio): migrate client transport to oRPC, add TanStack Query client, and introduce Zustand viewStore #1610
• feat(studio-server): implement effect-orpc router, mount /rpc, and add typed client with TanStack Query utils #1609
• refactor(studio): decompose App.tsx non-React corpus into feature modules and shared utilities #1608
• refactor(studio): reskin shell chrome onto design tokens, shadcn primitives, and sonner toast #1607
• feat(mapgen-studio): add canonical token-driven shadcn primitive library with Radix UI and sonner #1606
• docs(studio): add control-oRPC seam doc, thin LiveControlPort adapter design, and re-baseline server-contract audit + target architecture for live-read surface #1605
• feat(mapgen-studio): Tailwind v4 + shadcn design system foundation — tokens, .dark theming, substrate elevation, self-hosted fonts #1657
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

Railway preview (MapGen Studio): not provisioned for this PR.

Policy (Graphite stacks): previews are created only for the top-of-stack PR by default.

• To force a preview for this PR: add label railway-preview
• To suppress a preview: add label no-railway-preview

Debug: {"isClosed":false,"isFork":false,"suppress":false,"force":false,"isTopOfStack":false,"hasToken":true,"draft":false}

[mateicanavra]

Merge activity

• Jun 12, 8:50 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Jun 12, 9:19 PM UTC: Graphite rebased this pull request as part of a merge.
• Jun 12, 9:19 PM UTC: @mateicanavra merged this pull request with Graphite.