P09 — Native transition overlay import contract

The reader for a future transition overlay should work on a decoded 20-row table, not offsets calculated by Disk + stage*8. The 160-byte RAM table is stored as 108 packed bytes at Disk $84B14..$84B7F, and the active 10-byte runtime record $04AF8 is derived from one logical stage row. Prefer a small, isolated, read-only decoder module with independent tests; do not intermix it with tile editing or the $03 generator scripts. Each warp row has one source tile X/Y, a 16-bit target stage index and two 16-bit destination coordinates. Keep exact source types, level identity and confidence attached to overlays, with same-stage transitions supported. A zero row is a defined empty slot, not permission to enlarge compressed data. UI: left navigation/overlay toggles; centre map; right compact metadata on selection; top import/export unchanged; tooltips instead of explanatory text.

---

P07 editor extension decision (research, not implemented)

Current running editor baseline remains P03. When read-only entities are added, type $03 is the confirmed game-native DOOR / actor-generator class. The user-facing interface should display a generator layer distinct from (i) level-start $00, (ii) goal/boss $01/$02, and (iii) the separate level-header coordinate marker. Do not create fictional warp-arrival pins. Initial overlay can be enabled in the left navigation/display column; variant selection and details belong in the right property panel. Popup descriptions should be concise tooltips, with deep internals in the Wiki. Generation animation/artwork labels require further source proof; no guessed sprites.

The original engine has a 32-entry runtime door pool per stage. Do not enable additions beyond source/runtime capacity or allow modification of adjacent contiguous lists until the loader/writer and source relocation contracts are verified. Read-only inspection and source-derived CSV export are safe research utilities; graphics remain disk-derived.

---

P05 — documented future entity-overlay integration (not implemented)

Research-only pass. The live HTML5 application has not changed from P03. Future app modes should follow the established three-column Indy Heat-inspired layout: top bar for disk loading, import/export and history; left for level navigation and visibility, centre for the tile-accurate map, right for tools/tiles/objects. Interface text must be minimal, with concise tooltips instead of explanatory panels. New source-derived actor overlays should be read-only until the 68000 handler, type ID and list-size/export constraints are proven. Do not silently label arbitrary $03 records as enemies, and do not change unrelated map bytes during export.

The research manifest research/entity_manifest_disk.json now provides true 21-map object overlays: $00 = candidate normal start (once/map), $01 = candidate ordinary exit (16 maps), $02 = candidate boss objective (5 maps), $03 and other IDs = unknown; header +$0E/+10 must remain an independently toggled annotation. Always retain a clear way to distinguish confidence tiers in visuals.

---

App Architecture

P02: standalone browser editor with native Disk.1 graphics decoder. All P01 UI layout and controls remain.

Top: Open/Export Disk.1, raw map import/export, PNG, Undo/Redo. Left: level selection, map overview, navigation, visibility toggles. Centre: dominant 1,024×1,024 logical tile canvas, zoom, cursor status. Right: selected tile, painting tools, native 0–255 tile picker, indexed colour reference palette. Keep this layout; tooltips instead of tutorial prose in controls. Future tile editor reuses existing Indy Heat drawing functions without inheriting race-specific assumptions.

File	Responsibility
nzs-core.js	Raw map data model, bottom-up indexing, one-cell writes, drawing geometry, safe map-only disk round trip.
nzs-graphics.js	16 authentic RLE bank headers, decoder, 16×16 Amiga 4-plane pixel conversion, runtime browser canvas atlases. No graphics writing.
data/stock-maps.js	21 raw map previews derived from the actual supplied Disk.1; corrected 3_4 and bank mappings.
assets/tiles/*.png	Generated from the original Disk.1 native tile banks. Used as immediate previews, not accepted as authoritative when another Disk.1 is loaded.
data/source-manifest.json	Diagnostic inventory: offsets, compressed/unpacked sizes, counts and pixel hashes from native bank extraction.
app.js	Three-column UI, map editor/tool state, changes/undo, canvas, image preview and disk import/export.

When Disk.1 is opened, the editor re-decodes all 16 graphics banks from the selected disk, validates bank headers/lengths and constructs native tiles as canvases; the 21 maps then reference the correct bank indices. An invalid bank is rejected rather than mixing maps with unrelated graphical assets. The decoder is read-only and changing pixels in the future must await safe RLE recompression and in-game tests.

The 16-colour RGB display palette remains a reference palette pending native register recovery, although all tile pixel indices and drawing data are now from Disk.1. Do not silently label it as a proven disk palette.

Preview mode is available without opening a disk. Complete Disk.1 export stays unavailable until a full disk is loaded, and only verified map bytes can change. Right-click picks tile, P/F/I/L/B/Shift+B select tools, G grid, U/R history, Ctrl/Cmd+Z and Ctrl/Cmd+plus/minus are available.

Next modes: native indexed pixel Tile Editor, then sprite/entity/warp editors after respective data/write contracts are settled. Graphics decoding is complete for 16 scenery tile banks, not a blanket claim of sprite-bank recovery.

P03 — level-header display and native palettes

nzs-level-headers.js uses mapOffset−$80 to decode header bytes, bounds and two unclassified coordinate words, and provides read-only built-in preview values. The centre canvas defaults to dimming stored rows outside declared map height; left overview applies the same distinction. A separate optional Header point toggle shows the coordinate words as a ?, not as an enemy, exit, player start or warp. The right palette and atlas use the 16 original RGB words parsed from nzs-graphics.js bank metadata, with provisional ×2 display channel conversion. The entire map remains editable/exportable; only known map cell bytes are written.

P04 — research-to-app bridge, no feature change

P04 provided offline/mobile-friendly PNG graphics contact sheets and candidate position overlays. None are integrated as editable sprites/objects because their disk source or gameplay semantics are not established. Once verified, add a sprite browser/inspector using the existing three-panel layout: left = level/actor list, centre = pixel-perfect display and selected map overlay, right = thumbnails/palette/animation navigation. Use tooltips, not explanatory wall text; keep unknowns in this Wiki and in Further Investigations. Preserve all P03 editor behaviours until a user-testable implementation is ready.

---

P10 — Read-only entity inspection design (13 October 2026)

The three-column UI contract remains: top bar for disk load/import/export, left level and overlay navigation, centre rendered map, right compact tile/tools or future actor catalogue; explanatory prose belongs in the Wiki, not control panels. P10 is research-only and adds no new editor release. When implementing an entity-inspection mode later, use distinct toggleable $03 Generators, $1F, $20 and Other direct actors layers, with native numeric IDs shown until visuals/names are code+runtime verified. Clicking an actor should display stage, source address, type ID, coordinates, parameter and associated raw animation sequence pointer; do not insert any guessed creature portrait. On mobile, source evidence and map overlays should be PNGs supplied with investigation ZIPs.## P11 handover — required read-only actor/graphics viewer baseline

The active HTML5 app in Dropbox is P03 (P04–P10 were research releases), so native actor placement, generator overlay and true sprite pixels are not yet integrated. Build on the existing app/index.html, app/app.js, app/nzs-core.js, app/nzs-graphics.js, app/nzs-level-headers.js without replacing proven map decompression/export behaviour. Read original Disk.1 at load, correlate the P10 entity_manifest_disk.json and source inventory against those bytes, and draw separate overlays for actor starts/objectives, type $03 generators, direct actor placements, candidates $1F/$20 and native P09 transitions. Prevent any changes to unknown source structures; controls may be view-only and disabled.

Next pass blocking requirement: decode original moving game graphics through the frame index resolver and renderer, supply original-colour character/creature/pickup atlases and integrate all proved images into read-only overlays. Prior fixed-stride contact sheets are not validated; do not postpone this task. Adopt the Indy Heat resource-neutral drawing tools when genuinely reusable; keep the UI sparse (tooltips, not explanatory copy).

Coordinate mismatch: User has verified visually that prior markers look one tile too low. Keep binary coordinates unchanged, compare object anchor/baseline, source top-down Y and bottom-up map scanline display, and test with actual sprite heights. Preview overlay correction is separate from source data editing. See the single Further Investigations acceptance criteria.

All permanent visual proof must reside in wiki/images/ and be embedded in Wiki subject pages, not only in temporary visuals/ exports. Any temporary Research/visuals files may be deleted after their proven facts, images and needed reproducibility code have been migrated to the Wiki or elsewhere expressly designated as durable.