Powered by

World Detail Page Shell

World Detail Page Shell is VySol's frontend layout and route contract for a single world screen. It provides the visual frame that Customize and future Ingestion features fill, rehydrates backend-owned draft or committed detail state when route state identifies a world, and exposes parent navigation back to World Hub.

This page is for developers, power users, and AI coding agents that need to understand the World Detail shell before changing frontend layout, route state, world-mode presentation, default visual assets, committed detail loading, Customize tab hosting, or future Ingestion tab work.

Why It Exists

VySol needs a stable world-level surface before the full world-management workflows exist. The shell gives draft worlds and committed worlds the same recognizable place in the app: cinematic background, VySol branding, and two top-level tabs.

The boundary matters because a layout shell should not accidentally become storage, ingestion, settings, upload, or source-management logic. Feature-specific tab content can live inside the shell while keeping the outer frame consistent.

Ownership Boundary

World Detail Page Shell owns:

  • Rendering the World Detail page frame in the frontend.
  • Showing the VySol logo mark and wordmark as non-clickable branding.
  • Showing parent Worlds navigation beside the centered Customize and Ingestion tabs.
  • Switching between draft-safe Customize and Ingestion shell panes.
  • Supporting draft and committed display modes through frontend route/query state.
  • Reading backend draft detail when draft route state includes a draft ID.
  • Reading backend committed detail when committed route state includes a world ID.
  • Routing back to World Hub through explicit parent navigation.
  • Delegating draft abandon checks to Draft Abandon Confirmation UI when parent navigation would leave an uncommitted draft.
  • Hosting World Detail Customize UI inside the Customize tab.
  • Using the app's true default world image and default font assets for the temporary visual shell.
  • Keeping the cinematic glass styling and responsive layout stable across desktop and narrow viewports.

World Detail Page Shell does not own:

  • Customize field behavior, validation, saving, or asset picking.
  • Ingestion controls, source staging, start, pause, retry, progress, or provider behavior.
  • Backend draft creation, draft storage, or API contracts.
  • The World Hub Create World card or draft-opening click behavior.
  • The World Hub committed-world card icon behavior.
  • Backend leave-safety policy, confirmed draft cleanup, or discard persistence behavior.
  • Draft-world persistence or committed-world storage.
  • Committed-world customization saving, committed source mutation, committed source deletion, committed source replacement, re-ingestion, Open World, chat, retrieval, or graph behavior.
  • File uploads, source file handling, parsing, chunking, embeddings, graph extraction, or retrieval.
  • App logging or console diagnostics.
  • User task documentation for customizing or ingesting worlds.

Normal Flow

The frontend route switch renders the World Detail shell when route/query state indicates a world-detail mode, draft ID, or committed world ID. If the mode is draft and a draft ID is present, the shell asks the backend for draft detail so the visible state reflects backend-owned splitter defaults and staged-source setup. If the mode is committed and a world ID is present, the shell asks the backend for committed detail so the visible state reflects saved metadata, committed sources, and locked splitter settings.

If draft mode has no draft ID, the shell keeps a draft-safe visual fallback for direct development loading without creating a frontend-only committed draft. If committed detail loading fails, the shell keeps the user on World Detail and renders visible error state instead of logging to the browser console.

The page always renders the same top-level frame: background image, dark cinematic overlays, non-clickable VySol branding, and a glass navigation pill containing parent Worlds navigation plus the Customize and Ingestion tab controls. The user can switch between Customize and Ingestion. The Customize tab is delegated to World Detail Customize UI, while the Ingestion tab still renders placeholder shell state. Activating Worlds uses app-owned parent navigation instead of browser-history Back behavior. In committed mode it routes directly to World Hub. In draft mode with a draft ID it delegates to Draft Abandon Confirmation UI before leaving.

Inputs

World Detail Page Shell currently receives frontend route/query state for display mode, optional draft ID, and optional committed world ID. That route state may come from direct URL loading, browser Back/Forward, the Hub's client-side Create World navigation, or the Hub's committed-world icon navigation. In backend-backed draft mode, it receives draft detail from the Draft World Detail API and passes draft route context to Draft Abandon Confirmation UI. In committed mode, it receives committed detail from the Committed World Detail API. It imports app-owned built-in assets for the visual default background, font, and logo mark.

It does not receive committed world records, raw source paths, ingestion attempts, database rows, provider responses, or uploaded assets.

Outputs

The system produces visible frontend UI state only. It renders the page shell, parent Worlds navigation, active tab state, draft loading/error state, Customize tab hosting, and Ingestion placeholder copy.

It may read backend draft detail when a draft ID is present, read backend committed detail when a committed world ID is present, and route back to World Hub when the parent navigation is activated. It does not write files, create database rows, create drafts by rendering, persist draft data, update committed-world recent-use state, start ingestion, save settings, own backend leave-safety policy, discard drafts directly, or emit app logs.

User-Facing Behavior

Users see a full-screen world detail frame with VySol branding in the top-left and a centered glass navigation pill. The pill shows Worlds with a left arrow, a thin separator line, and the Customize and Ingestion tabs. The Worlds control returns to World Hub as parent navigation, but draft routes may show Draft Abandon Confirmation UI first. Committed detail routes can show loading, loaded, or visible error state inside the pane. The brand is informational only and must not navigate or refresh the page when clicked.

The Customize and Ingestion tabs are visible in both draft and committed modes. Customize shows local identity fields and visual previews through World Detail Customize UI. Ingestion still avoids real controls until a related feature ticket adds them.

System Interactions

World Detail Page Shell currently interacts with:

  • Built-in default assets, which provide the true default world image and default font used by the shell.
  • Draft Abandon Confirmation UI, which guards unsafe draft parent navigation before returning to World Hub.
  • Draft World Detail API, which provides backend-owned draft splitter settings and staged-source summaries when a draft ID is present.
  • Committed World Detail API, which provides saved metadata, committed sources, and locked splitter settings when a committed world ID is present.
  • World Hub Page, which can create a draft, open a committed-world route, and route into this shell through client-side route updates.
  • Frontend route helpers, which build draft detail, committed detail, and Hub URLs.
  • The frontend launcher service, which can start the Vite development server when the frontend service is enabled.
  • World Detail Customize UI, which places local world identity fields and visual previews inside the Customize pane.
  • Future Ingestion UI, which can place source and ingestion controls inside the Ingestion pane.

It must stay separate from backend storage, draft-world registries, committed-world indexes, source staging mutation, ingestion attempt state, parsing, chunking, graph systems, and retrieval.

Current Edge Cases

Internal edge cases:

  • Missing or unknown mode values fall back to draft display mode.
  • Draft mode without a draft ID stays a visual shell fallback and does not create frontend-only draft state.
  • Client-side navigation from the Hub can render this shell without a full document reload.
  • Parent Worlds navigation uses app route helpers instead of stepping through browser history.
  • Browser Back/Forward can return between Hub and World Detail through route state.
  • Committed detail load failures render visible error text without console logging.
  • The brand area is not an anchor or button, so clicking it does not navigate.
  • The tab shell must fit without clipped tab labels on narrow viewports.
  • The parent navigation group must disappear on World Hub because it belongs only to World Detail.
  • The active tab underline must remain tied to the selected tab.
  • The shell uses source built-in assets, while generated frontend build output remains reproducible and ignored.

Cross-system edge cases:

  • The shell must use the true default world image and font rather than choosing any built-in asset at random.
  • Backend draft IDs must be read from route state and rehydrated from the backend rather than invented by the frontend.
  • Missing or failed draft rehydration must stay draft-safe and must not create committed storage.
  • Route changes must not create draft state by rendering the shell; draft creation belongs to the Hub entrypoint and Draft World Detail API.
  • Committed route changes must not update last_used_at; committed detail loading is read-only.
  • Committed detail loading must not create missing committed world folders or replacement world.sqlite files.
  • Parent navigation for draft routes with a draft ID must delegate unsafe-leave handling to Draft Abandon Confirmation UI.
  • Draft mode must not create committed-world records or durable folders.
  • Committed mode must not mark a world as used simply because this static shell rendered.
  • Committed mode must load committed-world data from the backend only through the committed detail API.
  • Customize and future Ingestion work must add behavior inside the tab panes without turning the shell into storage or orchestration logic.
  • Logs must remain absent unless a future UI logging standard is introduced.

Invariants

  • The World Detail shell must render both Customize and Ingestion tabs in draft and committed modes.
  • The World Detail shell must render parent Worlds navigation in World Detail and keep that parent navigation absent from World Hub.
  • Committed mode must default to the Customize tab and load committed detail from the backend when a world ID is present.
  • Committed detail loading must not refresh last_used_at.
  • The nav control must use the shared content-sized app nav behavior: width follows its contents, height stays fixed, and tab text size matches other app nav tabs.
  • Parent Worlds navigation must route to the Hub URL directly instead of relying on browser-history Back.
  • Draft parent navigation must keep the Worlds label stable while leave-state checks are in flight.
  • The VySol brand must remain visible, top-left, and non-clickable.
  • The shell must host Customize UI without owning its field behavior, and must not implement Ingestion controls by itself.
  • The shell must not persist draft state, committed-world state, source state, or ingestion state.
  • Rendering the shell must not create a draft; draft creation belongs to the Hub Create World entrypoint calling the backend API.
  • Rendering the shell must not discard draft state; draft discard can happen only through the dedicated confirmation UI after user confirmation.
  • The shell must not hardcode local machine paths, user data, secrets, or uploaded file paths.
  • Frontend build output must remain reproducible from source assets and package metadata.

Implementation Landmarks

  • frontend/src/world-detail-page.tsx owns the shell composition, mode handling, branding, and tab panes.
  • frontend/src/world-detail-customize-tab.tsx owns the Customize tab field and preview behavior hosted by the shell.
  • frontend/src/committed-world-api.ts owns committed detail API calls and response types.
  • frontend/src/draft-abandon-navigation.ts owns the draft parent-navigation guard hook.
  • frontend/src/draft-abandon-confirmation-dialog.tsx owns the draft abandon confirmation dialog.
  • frontend/src/draft-world-api.ts owns draft detail API calls and the Create World navigation helper.
  • frontend/src/app-navigation.ts owns frontend route helpers for Hub and World Detail navigation.
  • frontend/src/main.tsx owns the current route switch between Hub and World Detail.
  • frontend/src/styles.css owns the cinematic glass visual treatment, responsive layout, and default font face.
  • frontend/src/components/ui/tabs.tsx owns the local Radix Tabs wrapper used by the shell.
  • scripts/launcher/launcher.config.json contains the frontend service configuration for the Vite dev server.

What AI/Coders Must Check Before Changing This System

Before editing World Detail Page Shell, check:

  • Whether the change belongs in the shell instead of Customize UI, future Ingestion UI, storage, or backend route systems.
  • Whether both draft and committed modes still render the same shell structure.
  • Whether backend-backed draft route state still rehydrates from Draft World Detail API.
  • Whether backend-backed committed route state still rehydrates from Committed World Detail API without changing last_used_at.
  • Whether parent Worlds navigation still routes committed worlds directly and delegates draft unsafe-leave handling to Draft Abandon Confirmation UI.
  • Whether the VySol brand remains non-clickable.
  • Whether the tab labels, active state, and responsive layout remain visible without clipping.
  • Whether true default assets are still used when no real world data is connected.
  • Whether generated build output stays ignored and source assets remain the tracked source of truth.