Tinyworld Island Viewer

---
name: tinyworld-island-viewer
description: Use when changing the first-class Island Viewer shell, sequential generated-island viewer routing, or viewer-scoped graphics defaults.
---

# TinyWorld Island Viewer

Island Viewer is the first-class generated-island viewing surface:

- Shell: `island-viewer.html`
- Styles: `styles/island-viewer.css`
- Generator: `scripts/island-viewer-sequential-generator.js`
- Renderer adapter: `scripts/island-viewer-engine-runtime.js`
- Controller: `scripts/island-viewer.js`
- Compatibility redirect: `random-island-preview.html`

Rules:

- Keep the active generator viewer-only and sequential. `island-viewer.html`
  should load `scripts/island-viewer-sequential-generator.js`, not the giant
  `scripts/tinyworld-island-core.js` copied random-island bundle.
- Keep the builder-engine renderer stack active for now. Do not load
  `scripts/island-viewer-renderer.js` on `island-viewer.html` while
  `scripts/island-viewer-engine-runtime.js` provides the current look.
- The sequential layer stack is: all grass, first house, corner towers, paths,
  extra houses, fenced crops, fenced animals, rock patch, water route, bridge
  detection, strategic lanterns, plain stone outcrops, trees/bushes, then final
  weighted infill.
- The viewer sequential generator must emit schema-valid `v:4` world cells,
  use normal `terrain: "path"` cells for public path output, and expose
  `TinyWorldIslandGenerator.generate(...)` and `.profile(...)`.
- Do not emit `water-bridge` or `bridgeAxis` metadata from the active viewer
  generator. Bridges are allowed only through the new local detector: after
  water carving, scan local crossings with path cells on one axis and water
  cells on the perpendicular axis, then turn only the center water cell into a
  normal `kind: "bridge"`.
- Strategic lanterns are native `kind: "lamp-post"` cells placed after bridge
  detection. Keep them on empty grass cells that touch exactly two perpendicular
  path cells, and keep every pair more than 3 Manhattan spaces apart.
- A manor is a rare native `house` with `buildingType: "manor"`, not a promoted
  cottage. Only roll the 25% manor chance after at least three normal houses
  exist, reserve its footprint during generation, and connect a path from the
  cell in front of its door back into the existing path network before plots,
  rocks, water, or lanterns run.
- Trees and bushes are native `kind: "tree"` / `kind: "bush"` decoration placed
  after the functional path/water/bridge/lamp layers. Only use empty grass cells,
  keep trees spaced out, and let bushes fill smaller remaining border/garden
  opportunities without occupying paths.
- The initial fenced crop plot should keep its four dirt plot cells and fence
  gates, but each cell rolls independently: 25% empty, otherwise evenly between
  wheat, corn, carrot, pumpkin, and sunflower.
- The quarry/rock patch is the canonical ore showcase: its four cells should
  emit `kind: "rock"` with `appearance.oreMetal` covering `copper`, `iron`,
  `silver`, and `gold` once each. Extra infill ore may still pick a deterministic
  metal, but the core patch should visibly expose all four variants. Prefer a
  2x2 quarry; if earlier sequential layers leave no legal 2x2 space, place a
  compact connected four-cell quarry without overwriting paths, water, fences,
  structures, or reserved manor footprint cells.
- After the sparse tree/bush pass, run a final weighted infill loop over normal
  empty buildable cells until none remain. The infill choices should stay within
  native economy objects: crops, plain stone, ore, sheep/cow, bushes, and trees.
  Plain stone should be generated by the dedicated outcrop layer and can be
  extended by this weighted pass, clustered around stone/quarry terrain; do not
  add a post-pass forced stone correction.
  Do not fill water, paths, fences, structures, or reserved manor footprint cells.
- Water route planning must treat path crossings as single-cell crossings per
  connected path area. Do not let water carve two adjacent path cells or run
  along the path before turning back into normal terrain.
- Keep normal viewer chrome minimal. It is not a build screen: visible controls
  should stay viewer actions such as New Island, Load, and Save.
- Put grid/seed and graphics controls in the local/developer defaults helper,
  not in the primary viewer toolbar. Do not expose archetype as a viewer-facing
  economy or card concept; it is only hidden generator input when a caller passes
  it explicitly.
- Generated Island Viewer islands are fixed at `8 x 8`.
- Viewer runtime load applies the normalized 64-cell island once. Do not restore
  the old `clearViewerWorld()` + full reapply double pass, and do not force
  every tile rebuild during initial load. Use the
  `window.__tinyworldIslandViewerLoading` guard to suppress interleaved renders,
  then render once after the island settles.
- Viewer directional sun defaults to `10.0` (1000%). Migrate the old viewer
  default `1.1` only when it still looks untouched; user-edited values should
  stay user-owned.
- Persist viewer defaults only under `tinyworld:island-viewer:*`. Do not write
  viewer graphics into normal builder `tinyworld:render:*` keys.
- Use `npm run stats:island-viewer -- --count 1000` for on-demand sequential
  generator sweeps. The CLI loads the shared Raw Yield economy helper plus the
  viewer generator directly, validates schema/invariants, reports Raw Yield
  score/rarity/leader/resource summaries, and writes reports under
  `stats-runs/island-viewer-sequential/`.

Validation:

- `npm test`
- `npm run build`
- `npm run stats:island-viewer -- --count 1000`
- Check `/island-viewer` or `/island-viewer.html`: page loads through the
  builder-engine renderer, generated saves contain no legacy bridge metadata,
  and the shell does not request `scripts/tinyworld-island-core.js` or
  `scripts/island-viewer-renderer.js`.