Skip to main content
Pharos
PHAROSlive stablecoin signals

PharosVille Page

The PharosVille route, desktop gate, canvas exception, and data-to-world contract.

Contract for /pharosville/, the beta PharosVille route.

/pharosville/ is a data-driven old-school RPG island city for exploring Pharos stablecoin signals.

Route Contract

  • Page shell: src/app/pharosville/page.tsx
  • Viewport gate: src/app/pharosville/client.tsx
  • Desktop fallback: src/app/pharosville/desktop-only-fallback.tsx
  • World shell: src/app/pharosville/pharosville-world.tsx
  • Route styles: src/app/pharosville/pharosville.css

The Server Component owns metadata, canonical /pharosville/, breadcrumb JSON-LD, and the screen-reader H1. The client component performs the desktop viewport gate before mounting the browser-only world module.

Screens below 1280px wide or 760px tall render a DOM fallback with links to the main analytical pages. They must not mount the canvas, world queries, asset manifest loader, or sprite decode path.

Current Phase

The current implementation includes the desktop PharosVille v0.1 baseline:

  • desktop-gated route, with a short-screen fallback as well as the narrow-screen fallback
  • Canvas 2D sea-first island map on eligible desktop viewports, with roughly 86% water by tile count
  • live aggregate Pharos queries mounted only after the desktop gate
  • pure world model for PSI, docks, active ships, clusters, cemetery, details, and visual cues
  • DOM map key, query status, detail panel, keyboard entity browser, toolbar, minimap, and accessibility ledger
  • canvas hit testing for lighthouse, docks, ships, clusters, and graves
  • mouse/touch drag pan, wheel zoom, toolbar pan/zoom/reset/follow/clear controls, keyboard arrow pan, Escape clear, minimap click-to-pan, and fullscreen inspection mode
  • normal-motion canvas loop for the lighthouse sweep, water shimmer, and capped selected/top/recent ship effects
  • deterministic reduced-motion render with no running animation frame loop
  • desktop, stressed-ship, short-screen, ultrawide backing-store, interaction, and motion visual coverage
  • controlled Pixellab asset manifest with critical and deferred sprite loading under public/pharosville/assets/
  • asset validation through npm run check:pharosville-assets
  • no production fixture/default market data

Data Mapping Target

The planned PharosVille visual grammar is:

  • lighthouse = PSI composite status
  • dock footprint = chain stablecoin supply
  • ships = active stablecoins only
  • ship distance from shore = peg/depeg risk first, with DEWS escalation
  • sea/weather = aggregate DEWS breadth
  • cemetery = dead and frozen assets from merged cemetery data
  • fog = missing, low-confidence, or stale evidence

Exact values and placement explanations must be available in DOM panels. The canvas must never be the only source of analytical truth.

Canvas Exception

Pharos narrative visualizations normally prefer SVG/CSS view-model presentations. PharosVille is a deliberate Canvas 2D exception because it needs a pan/zoom world, isometric tile projection, depth sorting, sprite layers, culling, and 200+ possible entities.

Compensating gates:

  • pure tested world model before renderer complexity
  • DOM ledger/detail parity for encoded signals
  • reduced-motion deterministic render
  • canvas nonblank, semantic terrain/water, and backing-pixel budget tests
  • no canvas/runtime work below 1280px
  • no canvas/runtime work below 760px viewport height
  • no CSP relaxation

Visual Regression

tests/visual/pharosville.spec.ts covers:

  • desktop canvas shell at 1440 x 1000
  • nonblank canvas pixels, terrain/water pixel coverage, and backing-store budget
  • sea-first tile ratio
  • stressed ship detail semantics for active depeg and storm-shelf placement
  • <1280px fallback
  • short desktop fallback
  • canvas click/selection, toolbar zoom/clear, and minimap interaction
  • fullscreen control visibility and mode toggle
  • ultrawide canvas DPR/backing-store caps
  • reduced-motion determinism and normal-motion RAF startup
  • no world API, site-data, manifest, or asset requests under the fallback

Visual tests route-mock /api/* and /_site-data/* data before asserting map semantics.

Color Guard

npm run check:harbor-palette remains as a compatibility script name, but it now runs scripts/check-pharosville-colors.mjs. The new guard checks the PharosVille route shell for unsafe placeholder/debug colors and visual-system drift.

Update Rules

Update this file when any of the following change:

  • /pharosville/ route shell, metadata, or desktop gate
  • PharosVille data mapping
  • canvas mount, renderer, or world-model contract
  • DOM parity, keyboard access, or detail-panel behavior
  • visual regression expectations
  • asset manifest or Pixellab pipeline

Related docs to check in the same change: