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.