Developer Hub

Developer Hub

Swan Song is a simulation-first WonderSwan core for the Analogue Pocket. This wiki summarizes the developer path; the repository Markdown, source, tests, and machine-readable policies remain the exact reviewable evidence.

No verified release exists. Protected-main commit a897ecbf now has two distinct signed, audit-passing Quartus candidates with byte-identical RBF and build-ID files. That closes fit, timing, and reproduction evidence for that exact development commit; it is not a substitute for licensing authorization, final package review, or the physical Pocket and Dock matrix.

Start here

• Build and Test
• Architecture
• Roadmap and current evidence
• First-class Pocket compliance matrix
• Upstream provenance

Engineering boundaries

The codebase separates three concerns:

1. Console logic implements the WonderSwan machine and remains comparable with the pinned MiSTer source.
2. Pocket integration owns APF commands, data slots, settings, controls, video delivery, audio transport, saves, packaging, and hardware pins.
3. Evidence tooling builds open/generated fixtures, runs translated-RTL simulation, checks metadata and release policy, and records what still requires vendor tools or hardware.

Changes should keep those boundaries visible. A Pocket workaround should not silently redefine shared console behavior, and a simulator result should not be relabeled as physical proof.

The detailed merge boundary is documented in MiSTer/Pocket porting.

Technical map

Area	Primary documentation
Module, clock, memory, and video map	ARCHITECTURE.md
APF lifecycle and data slots	BUILDING.md
Launcher, Recent, and Library boundary	POCKET_LAUNCHER_LIBRARY.md
Core icon and Swan Wake platform art	CORE_ICON.md, PLATFORM_ART.md
Controls and Dock	FIRST_CLASS_INPUT_DOCK.md
Frame delivery and orientation	FRAME_DELIVERY.md, VERTICAL_PLAY.md, ORIENTATION_TRANSITION.md
Color and temporal response	SCREEN_AUTHENTICITY.md
Memories/save-state work	SAVESTATE_FORMAT.md, SAVESTATE_V2_FORMAT.md, MEMORIES_STAGING.md
Homebrew and WonderWitch	HOMEBREW_WONDERWITCH.md
Original homebrew showcase	SWANFRAME
WonderSwan music workflow	Make WonderSwan Music skill
Physical QA	HARDWARE_QA_PROTOCOL.md, KNOWN_TITLE_COMPATIBILITY.md

Contribution principles

• Preserve original authorship and pinned provenance.
• Prefer open, generated, or personally authored fixtures.
• Never add commercial ROMs, BIOS files, saves, or private captures.
• Make malformed inputs fail closed.
• Bind claims to executable tests or explicitly name the missing hardware gate.
• Keep deterministic build inputs separate from host clocks and randomness.
• Upstream shared console fixes after the evidence is strong enough to review.

The inherited tree contains a standalone GPL v2 license text, a GPL v2-or-later program notice, GPL v3-or-later and MIT file notices, and vendor-specific notices. The standalone GPL v2 text does not by itself license unheaded files. Release licensing is still under review; consult UPSTREAMS.md and preserve every file-level notice before redistributing anything.