ORIGINAL OPENING PIECE COMPOSITION, TRIGGER ORDER, AND POTOS PATCH

Source: the user's supplied Secret of Mana (USA), headerless 2,097,152 bytes.
SHA256 4c15013131351e694e05f22e38bb1b3e4031dedac77ec75abecebe8520d82d5f
Every offset below is a headerless ROM offset, not a CPU bank address.
Source-evidence.json records the relevant original byte ranges verbatim.

REPRODUCE

From the packaged java-viewer directory, Python 3.10+, standard library:
  python tools/compose_opening_maps.py --rom PATH_TO_ORIGINAL_USA_ROM --maps-dir ../assets/maps --output dist/data/opening-composition --flag 0x10=6

Use the full, original map JSONs under ../assets/maps. The smaller browser
dist/assets JSONs are runtime copies, not the reproduction input.
--flags-json accepts an array of 256 original raw counter bytes. --flag
accepts a base-0 ID=value override. Both are source-state inputs, not native
quests invented by the exporter. The ROM is read only and rechecked afterward.

To regenerate the two original Potos PNG patches, install Pillow and add:
  --map-art-dir ../assets/maps --patch-assets dist/assets
PNG generation compares every atlas pixel against original ROM bitplanes,
subtile references and palette words. It also checks source priority fields,
Mode1 code, transparent tile188 and the exact six-cell delta. The renderer
helper render_mode1_maps.py must remain alongside the composer in tools/.

JSON API

map-N.json contains mapId, widthTiles, heightTiles and tileSize=16.
layerTileIndices[2] and collisionIds[2] are row-major original logical layers:
index=y*widthTiles+x; array0=original layer1, array1=original layer2.
rawCounterBytes contains the exact input state. placements records every
original five-byte placement, source offset, layer, position and interval.
selectedPlacementOrders lists the active placements in original stream order.
sourcePieces records compressed and decoded-tile hashes. deltaFromZeroFlags
gives the resulting changed cells and their original collision IDs.
flatWalkable and flatWalkableWithTriggerHandler retain the conservative
development-mask limits from opening-collision; they are not the original
full actor collision interpreter.

PIECE VISIBILITY AND OVERWRITE ORDER

Original code00CC28-00CC4E reads the ENTIRE raw counter byte from7ECF00+ID.
It compares the placement's high-nibble minimum and low-nibble maximum,
including both endpoints. It neither masks the counter to four bits nor
special-cases flag00. An upper counter nibble can therefore make a piece
inactive. This matters because the native event VM preserves upper nibbles.
Later active placements overwrite earlier placements, including tile index0.
The opening base piece must remain active and cover its original bounds;
the exporter rejects unsupported base-state/bounds assumptions.

Map256:27 placements, all raw flag00 interval0..15; no conditioned geometry.
Map128:5 placements, all raw flag00 interval0..15; no conditioned geometry.
Map129:5 placements, all raw flag00 interval0..15; no conditioned geometry.
Map130:2 placements, all raw flag00 interval0..15; no conditioned geometry.
Map131:2 base placements plus original piece13, layer1 at tile29,28,
  raw flag0x10 (decimal16), inclusive interval6..15.

Thus sword acquisition raw flag16=1 does not change map128 piece geometry.
The original sword object speciesD8 at tile31,59 is instead visible only
when flag16=0. Original ghost object speciesD7 uses flag0A interval1..1.
Cuttable grass is a separate runtime terrain mutation; none is fabricated
by this composer.

POTOS SIX-CELL ORIGINAL VISUAL/COLLISION CHANGE

potos-hole-delta.json records piece13, ROM0D23D2, four compressed bytes,
3x2 decoded metatiles188. The affected cells are x29..31, y28..29.
Original layer1 metatiles144 become188. Original collision IDs00 become04:
00 record12 06 00 00 is supported flat;04 record13 06 00 00 remains blocked.

beforeAsset=assets/potos-hole-before.png and afterAsset=assets/potos-hole-after.png
are each48x32 pixels, covering world pixels464,448 through511,479 inclusive.
Always select one patch using the entire raw flag16 byte:6..15 selects after;
otherwise before. Do not draw only after over the existing flattened map.

The source layer1 grass144 and layer2 hole metatiles369..374 all have subtile
priority bit0. Original Mode1 puts BG1 priority0 in front of BG2 priority0.
Before activation, opaque BG1 grass therefore covers the BG2 hole. Activated
BG1 metatile188 has only transparent pixels, exposing the existing BG2 hole.
Original display code00C1DA is a9 09 8d 05 21 (write09 to BGMODE2105).

The earlier static export flattened all logical layer2 pixels over layer1,
ignoring source subtile priorities. Its Potos hole already appeared at zero
flags. These before/after patches correct this checked region. The original
preserved bulk static-map PNGs still omit source-priority composition. The
new map-N-mode1.png opening images correct background priority and source
backdrop for all five opening maps; see their Mode1 manifest/README. Sprite
depth, color math, ongoing animation and display effects remain unsupported.
Neither profile is a complete original renderer.

Pixel hashes are SHA256 of unpacked RGBA pixels, not PNG file bytes:
before:7d7c52100398d6910c492378338bb3428027fa95672fcb82ae65e2ffaaa0fff3
after: f783e022fb820bc291fe3bf7fbbccd6167641ae1691c911f4c5bac99e768fcaa
Both patches are opaque. Their source atlas and individual source metatiles
are recorded in potos-hole-delta.json. No replacement artwork was generated.

ORIGINAL TILE-TRIGGER SAMPLE AND LATCH

00D7F3-00D85D samples predicted actor-origin X/Y, offset by encoded velocity
sign and wrapped with original map dimensions. It derives x>>4 and y>>4 and
reads the original map tile/type using the internal128-cell row stride.
The source trigger test does not add a visual-feet Y offset. The original
physical collision code also uses radius0C and actor state; the current
native footprint is a development setting, not a decoded reproduction.

00D666-00D694 only latches when FF|D0 is zero, the player actor is active,
and its visible/state condition passes. It compares sampled tile index06 to
actor E04C. On change only, it stores the new index to pending E04B and last
sample E04C. 02B517-02B559 gives each original trigger cell a distinct runtime
indexC0+ordinal. Adjacent trigger cells can therefore latch independently.

00B630-00B69B collects pending triggers only with the event VM idle, skips
busy actors, derives the original table slot, clears pending E04B BEFORE
starting the event, and retains last-sample E04C. It clears velocity before
event start. Standing on a cell does not continually restart its event.
Leaving and reentering a different sampled tile can rearm the latch.

Arrival initialization/persistence of E04C across every original transition
has not been verified. A native current-cell edge/debounce rule is therefore
a development integration rule; it must not be claimed to reproduce all
arrival suppression or full original collision timing.

ORIGINAL MAP-ENTRY EXECUTION ORDER

00BED3-00BEFB requires header bit04, separate E8 bit7 clear, and(E8&3)!=3.
It reads the FIRST original trigger word and attempts to start that event.
01E77B-01E795 accepts event starts only when D0 is00 (idle) orFF; an already
active interpreter rejects a new event instead of queueing it.

01E7F2-01E7FF loads ordinary door Y/transition into DF/E0, then CLEARS E8.
E8 is separate execution state, not the original door transition byte. A
door transition byteC3 therefore does not itself suppress a map-entry event.
The script door opcode18 handler advances the running event without clearing
D0. Its map-entry attempt is rejected while that event remains active.
A free-walking door with an idle VM can run the target map-entry event.

Original new-game event400 takes Door00 to map256, then jumps to106. Because
400 is active during the door, map256 entry100 is suppressed. Event106 takes
Door82 to map128, then jumps to101; map128 has no map-entry event anyway.
Free-walk map128 to129 can run entry105;129 to130 can run entry70E;130 to131
can run entry610. Scripted transitions must preserve the active script rather
than unconditionally starting the destination entry event.

PRIMARY FORMAT/HARDWARE REFERENCES

https://github.com/Moppu/SecretOfManaRandomizer/blob/main/SoMRandomizer/processing/common/VanillaMapUtil.cs
https://github.com/Moppu/SecretOfManaRandomizer/blob/main/SoMRandomizer/processing/common/SomMapCompressor.cs
https://hackofmana.com/maps/
https://wiki.superfamicom.org/backgrounds#mode-1

The exact USA-ROM byte guards are the evidence for source execution behavior;
format documentation provides context. Unsupported source behavior remains
explicitly separate from the current editable native development runtime.
