@tmustier/pi-nes 0.2.23 → 0.2.24

package/extensions/nes/native/nes-core/vendor/nes_rust/TODO_INVENTORY.md

@@ -3,17 +3,17 @@
 This inventory tracks TODOs in the vendored `nes_rust` snapshot.
 
 ## src/lib.rs
-- L57: Audio buffer sample code T.B.D. (doc example). Likely remove or replace with note.
+- L57: Audio buffer sample code T.B.D. (doc example). Change: replace TODO with note that audio output is omitted.
 
 ## src/apu.rs
 - L53: sample_period timing fix needed for audio accuracy.
 - L67: APU reset behavior incomplete.
 - L79: Sampling timing not precise.
-- L93: Add note (DMC timer) — probably remove or add clarification.
+- L93: Add note (DMC timer) — Delete: remove TODO unless a concrete note is added.
 - L102: Frame sequencer timing not precise.
 - L168: IRQ timing needs verification.
 - L276: DMC CPU memory workaround is hacky; optional refactor.
-- L400/612/775/949: Invalid register write handling — probably ignore or document no-op.
+- L400/612/775/949: Invalid register write handling — Change: document no-op and remove TODOs.
 - L467: Sweep negation logic fix needed.
 - L975: Remove DMC memory workaround; optional refactor.
 
@@ -23,7 +23,7 @@ This inventory tracks TODOs in the vendored `nes_rust` snapshot.
 
 ## src/ppu.rs
 - L119: Data bus decay support (accuracy improvement).
-- L322: Greyscale support comment; likely redundant.
+- L322: Greyscale support comment — Delete: masking handled in load_palette (unless register-read behavior needed).
 - L495: Pixel alignment off-by-one investigation.
 - L594-L618: Missing cycle/subcycle fetch behavior.
 - L660: Attribute fetch correctness.
@@ -32,7 +32,7 @@ This inventory tracks TODOs in the vendored `nes_rust` snapshot.
 - L804/L830: Scroll updates conditional on rendering.
 - L863: Optional optimization.
 - L1020: Color emphasis implementation.
-- L1069: PPU master/slave select; likely ignorable on NES.
+- L1069: PPU master/slave select — Change: document as ignored on NES, remove TODO.
 
 ## src/register.rs
 - L5: Combine Register<u8>/Register<u16> (optional refactor).
@@ -42,16 +42,16 @@ This inventory tracks TODOs in the vendored `nes_rust` snapshot.
 - L149: MMC1 32KB banking fix needed.
 
 ## src/cpu.rs
-- L44: Unknown button mapping; replace with unreachable or ignore.
+- L44: Unknown button mapping — Change: replace with unreachable! (exhaustive match).
 - L242: Opcode table refactor (optional).
 - L620: Page-cross cycle for ADC 0x71 needed.
 - L1254/L1258: DMC sample handling simplification + stall timing fix.
 - L1271: Frame update detection precision.
 - L1285: Poweroff input handling.
 - L1313: NMI vs IRQ ordering.
-- L1368/1895: Cleanup notes (optional).
+- L1368/1895: Cleanup notes — Delete: vague cleanup notes.
 - L1417/1552/1557/1709/1716/1732/1738/1994: CPU logic correctness checks.
-- L1531/L2116: Invalid instruction/addressing mode handling.
+- L1531/L2116: Invalid instruction/addressing mode handling — Change: treat illegal opcodes as NOP placeholder and document unknown addressing mode fallback.
 - L1909: DMA stall timing detail.
 - L1952: Interrupt handling optimization (optional).
 

package/extensions/nes/native/nes-core/vendor/nes_rust/VENDOR.md

@@ -9,9 +9,9 @@
 - Purpose: carry project-specific fixes and act as upstream-of-record for this vendor copy.
 
 ## Current Vendor Snapshot
-- Source commit/tag: `fd5cf3b` (fork master)
+- Source commit/tag: `28b6e9b` (fork master)
 - Vendored on: 2026-02-02
-- Local patch set: SRAM helpers, CHR RAM support, mapper fixes, PPU timing tweaks, debug hooks.
+- Local patch set: SRAM helpers, CHR RAM support, mapper fixes, PPU timing tweaks, debug hooks, palette index clamp.
 
 ## Update Process
 1. Sync fork with upstream if needed.

package/extensions/nes/native/nes-core/vendor/nes_rust/src/apu.rs

@@ -90,7 +90,6 @@ impl Apu {
 			self.pulse1.drive_timer();
 			self.pulse2.drive_timer();
 			self.noise.drive_timer();
-			// @TODO: Add note
 			if self.dmc.drive_timer(dmc_sample_data) {
 				self.dmc_irq_active = true;
 			}
@@ -397,7 +396,7 @@ impl ApuPulse {
 				self.timer_sequence = 0;
 				self.envelope_start_flag = true;
 			},
-			_ => {} // @TODO: Throw an error?
+			_ => {} // Invalid register: no-op.
 		};
 	}
 
@@ -609,7 +608,7 @@ impl ApuTriangle {
 
 				self.linear_reload_flag = true;
 			},
-			_ => {} // @TODO: Throw an error?
+			_ => {} // Invalid register: no-op.
 		};
 	}
 
@@ -772,7 +771,7 @@ impl ApuNoise {
 
 				self.envelope_start_flag = true;
 			},
-			_ => {} // @TODO: Throw an error?
+			_ => {} // Invalid register: no-op.
 		};
 	}
 
@@ -946,7 +945,7 @@ impl ApuDmc {
 				self.register3.store(value);
 				self.remaining_bytes_counter = ((self.sample_length() as u16) << 4) | 1;
 			},
-			_ => {} // @TODO
+			_ => {} // Invalid register: no-op.
 		}
 	}
 

package/extensions/nes/native/nes-core/vendor/nes_rust/src/cpu.rs

@@ -41,7 +41,7 @@ fn to_joypad_button(button: button::Button) -> joypad::Button {
 		button::Button::Joypad2Right => joypad::Button::Right,
 		button::Button::Start => joypad::Button::Start,
 		button::Button::Select => joypad::Button::Select,
-		_ => joypad::Button::A // dummy @TODO: Throw an error?
+		_ => unreachable!("Unhandled button mapping")
 	}
 }
 
@@ -1365,7 +1365,6 @@ impl Cpu {
 		}
 	}
 
-	// @TODO: Clean up if needed
 	fn operate(&mut self, op: &Operation) {
 		match op.instruction_type {
 			InstructionTypes::ADC => {
@@ -1528,7 +1527,7 @@ impl Cpu {
 				self.update_z(result);
 			},
 			InstructionTypes::INV => {
-				// @TODO: Throw?
+				// Illegal opcode placeholder (treated as NOP for now).
 				println!("INV operation");
 			},
 			InstructionTypes::INX | InstructionTypes::INY => {
@@ -1892,8 +1891,6 @@ impl Cpu {
 			self.apu.store_register(address, value);
 		}
 
-		// @TODO: clean up
-
 		if address == 0x4014 {
 			self.ppu.store_register(address, value, &mut self.rom);
 
@@ -2113,7 +2110,7 @@ impl Cpu {
 				effective_address
 			},
 			_ => {
-				// @TODO: Throw?
+				// Unknown addressing mode; returning 0 as a fallback.
 				println!("Unknown addressing mode.");
 				0
 			}

package/extensions/nes/native/nes-core/vendor/nes_rust/src/lib.rs

@@ -54,7 +54,7 @@ use audio::Audio;
 ///   nes.step_frame();
 ///   nes.copy_pixels(rgba_pixels);
 ///   // Render rgba_pixels
-///   // @TODO: Audio buffer sample code is T.B.D.
+///   // Audio output omitted in this example.
 ///   // Adjust sleep time for your platform
 ///   std::thread::sleep(Duration::from_millis(1));
 /// }

package/extensions/nes/native/nes-core/vendor/nes_rust/src/ppu.rs

@@ -319,8 +319,6 @@ impl Ppu {
 				};
 				self.vram_read_buffer = value;
 
-				// @TODO: Support greyscale if needed
-
 				// Accessing ppudata increments vram_address
 				self.increment_vram_address();
 				self.data_bus = return_value;
@@ -1011,7 +1009,7 @@ impl Ppu {
 		// read from the grey column 0x00, 0x10, 0x20, or 0x30
 		let mask = match self.ppumask.is_greyscale() {
 			true => 0x30,
-			false => 0xFF
+			false => 0x3F
 		};
 		PALETTES[(address & mask) as usize] & 0xFFFFFF
 	}
@@ -1066,8 +1064,7 @@ impl PpuControlRegister {
 		self.register.is_bit_set(7)
 	}
 
-	// Bit 6. PPU master/slave select
-	// @TODO: Implement
+	// Bit 6. PPU master/slave select (unused on NES; ignored)
 
 	// Bit 5. Sprite height
 	// -- 0: 8 (8x8 pixels), 1: 16 (8x16 pixels)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tmustier/pi-nes",
-  "version": "0.2.23",
+  "version": "0.2.24",
   "description": "NES emulator extension for pi",
   "keywords": [
     "pi-package",

package/TODO_INVENTORY.md

@@ -1,116 +0,0 @@
-# TODO Inventory Review
-
-Scope: `extensions/nes/native/nes-core/vendor/nes_rust` (vendored emulator core). Each TODO reviewed for necessity.
-
-## Action Plan (prioritized)
-
-### P0 — Correctness (act)
-- [ ] APU timing fixes (sample_period, sampling timing, frame sequencer timing, sweep negation, DMC stall timing)
-- [ ] PPU fetch timing + scroll updates (cycles 257–340, subcycle fetch, attribute fetch, pixel alignment)
-- [ ] Mapper IRQ/MMC1 correctness (MMC3 IRQ timing/placement, MMC1 32KB banking fix)
-- [ ] CPU correctness/timing (ADC 0x71 page-cross, NMI vs IRQ priority, BIT/JMP/JSR/RTI/RTS/SBC logic, relative addressing sign extension, DMA stall timing)
-
-### P1 — Architecture cleanup
-- [ ] Move MMC3 IRQ handling out of ROM/PPU into mapper layer
-- [ ] Replace invalid-register/addressing TODOs with explicit no-op or `unreachable!()`
-- [ ] Remove/clarify doc-only TODOs (audio example note, greyscale comment, PPU master/slave select if intentionally ignored)
-
-### P2 — Optional refactors/optimizations
-- [ ] Opcode table refactor
-- [ ] Register<u8>/Register<u16> merge
-- [ ] Audio buffer cleanup + constant for 4096
-- [ ] Header caching + sprite eval/pos calculation optimizations
-
-## extensions/nes/native/nes-core/vendor/nes_rust/src/lib.rs
-| Line | TODO | Assessment |
-| --- | --- | --- |
-| 57 | Audio buffer sample code is T.B.D. (doc example) | Not needed for runtime; either remove the TODO or replace with a short note that audio output is omitted in the example. |
-
-## extensions/nes/native/nes-core/vendor/nes_rust/src/apu.rs
-| Line | TODO | Assessment |
-| --- | --- | --- |
-| 53 | Fix sample_period (1764000 / 44100) | Needed for accurate audio timing; keep until audio timing is corrected. |
-| 67 | Implement reset properly | Needed for accurate APU reset behavior; keep. |
-| 79 | More precise sampling timing | Needed for correct audio output timing; keep. |
-| 93 | Add note (DMC timer) | Not needed; either add a clarifying comment or remove the TODO. |
-| 102 | More precise frame sequencer timing | Needed for correct APU frame sequencing; keep. |
-| 168 | Check IRQ timing when sending | Needed for correct IRQ behavior; keep. |
-| 276 | DMC CPU memory workaround is hacky; simplify | Optional refactor; keep if you want cleanup, otherwise can remove. |
-| 400 | Throw an error on invalid pulse register | Not needed; invalid register writes are typically ignored. Consider removing TODO or clarifying no-op behavior. |
-| 467 | Fix negated sweep behavior | Needed for accurate sweep; keep. |
-| 612 | Throw an error on invalid triangle register | Not needed; invalid writes can be ignored. Consider removing TODO. |
-| 775 | Throw an error on invalid noise register | Not needed; invalid writes can be ignored. Consider removing TODO. |
-| 949 | DMC invalid register case | Not needed; either document as ignored or remove TODO. |
-| 975 | Remove DMC CPU memory workaround | Optional refactor; keep if you want to eliminate the workaround. |
-
-## extensions/nes/native/nes-core/vendor/nes_rust/src/default_audio.rs
-| Line | TODO | Assessment |
-| --- | --- | --- |
-| 29 | Remove side effect in copy_sample_buffer | Optional cleanup; keep if you plan to revisit buffer semantics. |
-| 31 | Remove magic number (4096) | Needed for maintainability; replace with a named constant if audio is used. |
-
-## extensions/nes/native/nes-core/vendor/nes_rust/src/ppu.rs
-| Line | TODO | Assessment |
-| --- | --- | --- |
-| 119 | Support data bus decay | Optional accuracy improvement; keep if fidelity matters. |
-| 322 | Support greyscale if needed | Likely optional; greyscale masking is already applied in `load_palette`. Consider removing or clarifying if register-read greyscale behavior is desired. |
-| 495 | Investigate `cycle - 1` vs `cycle - 2` pixel alignment | Needed for render correctness; keep. |
-| 594 | Cycle 257-320 behavior | Needed for correct PPU fetch timing; keep. |
-| 595 | Cycle 321-336 behavior | Needed for correct PPU fetch timing; keep. |
-| 596 | Cycle 337-340 behavior | Needed for correct PPU fetch timing; keep. |
-| 615 | 0-1 subcycle fetch details | Needed for correctness; keep. |
-| 616 | 2-3 subcycle fetch details | Needed for correctness; keep. |
-| 617 | 4-5 subcycle fetch details | Needed for correctness; keep. |
-| 618 | 6-7 subcycle fetch details | Needed for correctness; keep. |
-| 660 | Implement attribute fetch properly | Needed for PPU accuracy; keep. |
-| 690 | Optimize pos calculation | Optional performance cleanup; not required. |
-| 758 | Check MMC3 IRQ timing | Needed for mapper IRQ accuracy; keep. |
-| 759 | MMC3-specific IRQ hook location | Optional refactor; keep if you plan to move this into mapper layer. |
-| 804 | Only increment scroll if rendering enabled? | Needed for correctness; keep. |
-| 830 | Only copy scroll if rendering enabled? | Needed for correctness; keep. |
-| 863 | Optimize sprite evaluation | Optional performance cleanup; not required. |
-| 1020 | Implement color emphasis properly | Needed if emphasis bits should affect output; keep. |
-| 1069 | Implement PPU master/slave select | Likely not needed (unused on NES). Consider removing TODO or documenting it as intentionally ignored. |
-
-## extensions/nes/native/nes-core/vendor/nes_rust/src/register.rs
-| Line | TODO | Assessment |
-| --- | --- | --- |
-| 5 | Combine Register<u8> with Register<u16> | Optional refactor; not required. Consider removing if you don’t plan to refactor. |
-
-## extensions/nes/native/nes-core/vendor/nes_rust/src/mapper.rs
-| Line | TODO | Assessment |
-| --- | --- | --- |
-| 45 | MMC3-specific `drive_irq_counter` in trait | Optional architecture cleanup; keep if you want a mapper-specific IRQ interface. |
-| 149 | MMC1 32KB banking fix | Needed for correct MMC1 behavior; keep. |
-
-## extensions/nes/native/nes-core/vendor/nes_rust/src/cpu.rs
-| Line | TODO | Assessment |
-| --- | --- | --- |
-| 44 | Throw error for unknown button mapping | Not needed; enum should be exhaustive. Replace with `unreachable!()` or remove TODO. |
-| 242 | Replace opcode match with static array | Optional refactor; not required. |
-| 620 | Add +1 cycle if page crossed (ADC 0x71) | Needed for accurate timing; keep. |
-| 1254 | Simplify DMC sample handling | Optional refactor; keep if you want cleanup. |
-| 1258 | Fix DMC stall timing (+4 cycles) | Needed for accuracy; keep. |
-| 1271 | More precise frame update detection | Optional; keep if timing fidelity matters. |
-| 1285 | Implement Poweroff input | Optional feature; keep if you plan to support it. |
-| 1313 | Handle NMI vs IRQ priority | Needed for correctness; keep. |
-| 1368 | Clean up operate() if needed | Not needed; remove TODO unless you plan a refactor. |
-| 1417 | Check BIT instruction logic | Needed for correctness; keep. |
-| 1531 | Throw on INV instruction | Not needed for runtime; prefer `unreachable!()` or remove TODO. |
-| 1552 | Check JMP logic | Needed for correctness; keep. |
-| 1557 | Check JSR logic | Needed for correctness; keep. |
-| 1709 | Check RTI logic | Needed for correctness; keep. |
-| 1716 | Check RTS logic | Needed for correctness; keep. |
-| 1732 | Confirm SBC carry/borrow logic | Needed for correctness; keep. |
-| 1738 | Implement correct SBC overflow logic | Needed for correctness; keep. |
-| 1895 | Clean up store() control flow | Not needed; remove TODO unless refactoring. |
-| 1909 | DMA stall cycle timing | Needed for accuracy (513/514 cycle detail); keep. |
-| 1952 | Optimize interrupt handling | Optional; not required. |
-| 1994 | Confirm relative addressing sign extension | Needed for correctness; keep. |
-| 2116 | Throw on unknown addressing mode | Not needed; prefer `unreachable!()` or remove TODO. |
-
-## extensions/nes/native/nes-core/vendor/nes_rust/src/rom.rs
-| Line | TODO | Assessment |
-| --- | --- | --- |
-| 139 | MMC3-specific `irq_interrupted` in ROM | Optional architecture cleanup; keep if you plan to move IRQ handling into mapper layer. |
-| 145 | Cache RomHeader fields | Optional optimization; not required. |