palette/background: first-class declarations with reset-time load and runtime swaps

Re-adds `palette Name { colors: [...] }` and
`background Name { tiles: [...], attributes: [...] }` as first-class
declarations, plus `set_palette Name` and `load_background Name`
statements for runtime swaps. Unlike the previous iteration that
quietly no-op'd, this one is fully wired through the pipeline and
its behavior is pinned by both unit tests and an emulator golden.

Pipeline:

- Lexer: re-adds `palette`, `background`, `set_palette`,
  `load_background` keywords and tokenizes them.
- AST: `PaletteDecl` (name + 1..=32 colour bytes) and `BackgroundDecl`
  (name + 0..=960 tile bytes + 0..=64 attribute bytes) live in
  `Program`. `Statement::SetPalette` and `Statement::LoadBackground`
  name-reference these declarations.
- Parser: `palette Name { colors: [...] }` / `background Name
  { tiles: [...], attributes: [...] }` blocks and their statement
  forms parse via the existing byte-array helper.
- Analyzer: validates colour indices ($00-$3F), palette length
  (<=32), nametable length (<=960), attribute length (<=64), and
  duplicate decl names. `set_palette` / `load_background` targets
  must reference a declared name (E0502 otherwise). When a program
  declares palette or background, the analyzer bumps the user
  zero-page allocator's starting address from `$10` to `$18` to
  reserve `$11-$17` for the runtime update handshake — programs
  that don't use the feature keep the old layout so their emulator
  goldens stay byte-exact.
- Assets: `PaletteData` and `BackgroundData` resolve declarations
  into zero-padded fixed-size blobs (32 / 960 / 64 bytes) and
  expose `label()` / `tiles_label()` / `attrs_label()` for codegen
  to reference.
- IR: new `IrOp::SetPalette(String)` and
  `IrOp::LoadBackground(String)`; lowering forwards the names
  verbatim.
- Codegen: `gen_set_palette` writes the palette label pointer into
  ZP `$12/$13` and ORs bit 0 into the update flags at `$11`;
  `gen_load_background` does the same for tile/attribute pointers
  at `$14/$15/$16/$17` with bit 1. Both emit a `__ppu_update_used`
  marker so the linker splices in the NMI apply helper only when
  the feature is actually used.
- Runtime: `gen_initial_palette_load` and
  `gen_initial_background_load` write the first declared
  palette/background at reset time (before rendering is enabled,
  where PPU writes are safe). `gen_nmi(has_ppu_updates)` takes a
  new flag; when true it splices `gen_ppu_update_apply` at the top
  of the NMI body, which checks the `$11` flags byte and copies
  pending palette / nametable data to `$3F00` / `$2000` inside
  vblank. All helpers use only ZP $02/$03 as scratch at reset time
  and never clobber ZP slots live across NMI.
- Linker: new `link_banked_with_ppu` takes slice of `PaletteData` /
  `BackgroundData`; splices each blob as a labelled data block in
  PRG ROM, picks the first-declared as the reset-time load target,
  enables background rendering automatically when a background is
  declared, and threads `has_ppu_updates` into `gen_nmi`. Old
  `link_banked` remains as a thin wrapper for callers without
  palette/background data so existing tests don't shift.

Tests:

- Lexer: tokenization of the 4 new keywords (single added test case).
- Parser: 5 new tests for `palette` / `background` decls with and
  without attributes, plus `set_palette` / `load_background`
  statements.
- Analyzer: 9 new tests covering acceptance of declared
  palettes/backgrounds, E0502 for unknown names, E0201 for
  out-of-range NES colors and oversized blobs, E0501 for duplicate
  names, and the zero-page-layout guard (palette/bg decls bump ZP
  start; no decls keeps it at $10).
- Resolver: 3 new tests for zero-padding, truncation of oversized
  decls, and label derivation.
- IR: 2 new lowering tests for `set_palette` and `load_background`.
- Integration: 5 new tests — blob contents spliced verbatim into
  PRG, `STA $12` / `STA $14` emitted by set_palette /
  load_background codegen, and a regression guard that programs
  without palette/background still land user vars at $10.
- Emulator: new `examples/palette_and_background.ne` driven by a
  frame counter that toggles between `CoolBlues` / `WarmReds` and
  `TitleScreen` / `StageOne` every 90 frames. Golden PNG and audio
  hash checked in under `tests/emulator/goldens/` and verified via
  `node run_examples.mjs` — rendered image shows the blue
  `CoolBlues` palette with the nametable populated from
  `TitleScreen`.

Docs:

- `README.md` adds the feature to the headline list and the example
  table.
- `docs/language-guide.md` restores the palette/background sections
  with the full 32-byte layout table and `set_palette` /
  `load_background` statement references.
- `docs/future-work.md` replaces the "removed as dead code" entry
  with the remaining gaps (PNG-sourced palette and nametable
  assets, cross-vblank large background updates, memory-map
  reporting).
- `spec.md` restores the grammar productions and usage examples.
- `examples/README.md` lists the new demo.

All 497 unit + integration tests pass. Clippy clean. All 21
emulator goldens match after the update pass.

https://claude.ai/code/session_012fKB251HvEUQwG3tizFyqt

src/parser/mod.rs

@@ -127,6 +127,8 @@ impl Parser {
         let mut functions = Vec::new();
         let mut states = Vec::new();
         let mut sprites = Vec::new();
+        let mut palettes = Vec::new();
+        let mut backgrounds = Vec::new();
         let mut sfx = Vec::new();
         let mut music = Vec::new();
         let mut banks = Vec::new();
@@ -163,6 +165,12 @@ impl Parser {
                 TokenKind::KwSprite => {
                     sprites.push(self.parse_sprite_decl()?);
                 }
+                TokenKind::KwPalette => {
+                    palettes.push(self.parse_palette_decl()?);
+                }
+                TokenKind::KwBackground => {
+                    backgrounds.push(self.parse_background_decl()?);
+                }
                 TokenKind::KwSfx => {
                     sfx.push(self.parse_sfx_decl()?);
                 }
@@ -235,6 +243,8 @@ impl Parser {
             functions,
             states,
             sprites,
+            palettes,
+            backgrounds,
             sfx,
             music,
             banks,
@@ -662,6 +672,107 @@ impl Parser {
         })
     }
 
+    // ── Palette / Background declarations ──
+
+    /// `palette Name { colors: [c0, c1, ..., c31] }` — declares a
+    /// 32-byte PPU palette. Colors shorter than 32 are zero-padded
+    /// by the analyzer; colors longer than 32 are rejected.
+    fn parse_palette_decl(&mut self) -> Result<PaletteDecl, Diagnostic> {
+        let start = self.current_span();
+        self.expect(&TokenKind::KwPalette)?;
+        let (name, _) = self.expect_ident()?;
+        self.expect(&TokenKind::LBrace)?;
+
+        let mut colors: Option<Vec<u8>> = None;
+        while *self.peek() != TokenKind::RBrace && *self.peek() != TokenKind::Eof {
+            let (key, key_span) = self.expect_ident()?;
+            self.expect(&TokenKind::Colon)?;
+            match key.as_str() {
+                "colors" => {
+                    colors = Some(self.parse_byte_array("colors")?);
+                }
+                _ => {
+                    return Err(Diagnostic::error(
+                        ErrorCode::E0201,
+                        format!("unknown palette property '{key}'"),
+                        key_span,
+                    ));
+                }
+            }
+            if *self.peek() == TokenKind::Comma {
+                self.advance();
+            }
+        }
+        self.expect(&TokenKind::RBrace)?;
+
+        let colors = colors.ok_or_else(|| {
+            Diagnostic::error(
+                ErrorCode::E0201,
+                "palette requires 'colors' property",
+                start,
+            )
+        })?;
+
+        Ok(PaletteDecl {
+            name,
+            colors,
+            span: Span::new(start.file_id, start.start, self.current_span().end),
+        })
+    }
+
+    /// `background Name { tiles: [...], attributes: [...] }` — the
+    /// tiles array is the 32×30 nametable (up to 960 bytes); the
+    /// attributes array is the 8×8 attribute table (up to 64 bytes).
+    /// Both shorter and omitted arrays are zero-padded by the
+    /// analyzer. Longer arrays are rejected.
+    fn parse_background_decl(&mut self) -> Result<BackgroundDecl, Diagnostic> {
+        let start = self.current_span();
+        self.expect(&TokenKind::KwBackground)?;
+        let (name, _) = self.expect_ident()?;
+        self.expect(&TokenKind::LBrace)?;
+
+        let mut tiles: Option<Vec<u8>> = None;
+        let mut attributes: Option<Vec<u8>> = None;
+        while *self.peek() != TokenKind::RBrace && *self.peek() != TokenKind::Eof {
+            let (key, key_span) = self.expect_ident()?;
+            self.expect(&TokenKind::Colon)?;
+            match key.as_str() {
+                "tiles" => {
+                    tiles = Some(self.parse_byte_array("tiles")?);
+                }
+                "attributes" => {
+                    attributes = Some(self.parse_byte_array("attributes")?);
+                }
+                _ => {
+                    return Err(Diagnostic::error(
+                        ErrorCode::E0201,
+                        format!("unknown background property '{key}'"),
+                        key_span,
+                    ));
+                }
+            }
+            if *self.peek() == TokenKind::Comma {
+                self.advance();
+            }
+        }
+        self.expect(&TokenKind::RBrace)?;
+
+        let tiles = tiles.ok_or_else(|| {
+            Diagnostic::error(
+                ErrorCode::E0201,
+                "background requires 'tiles' property",
+                start,
+            )
+        })?;
+
+        Ok(BackgroundDecl {
+            name,
+            tiles,
+            attributes: attributes.unwrap_or_default(),
+            span: Span::new(start.file_id, start.start, self.current_span().end),
+        })
+    }
+
     // ── SFX / Music declarations ──
 
     /// `sfx Name { duty: N, pitch: [..], volume: [..] }`. Pitch and
@@ -1060,6 +1171,18 @@ impl Parser {
                 self.advance();
                 Ok(Statement::WaitFrame(span))
             }
+            TokenKind::KwLoadBackground => {
+                let span = self.current_span();
+                self.advance();
+                let (name, _) = self.expect_ident()?;
+                Ok(Statement::LoadBackground(name, span))
+            }
+            TokenKind::KwSetPalette => {
+                let span = self.current_span();
+                self.advance();
+                let (name, _) = self.expect_ident()?;
+                Ok(Statement::SetPalette(name, span))
+            }
             TokenKind::KwScroll => {
                 let span = self.current_span();
                 self.advance();