Add initial documentation for codebase folders

docs.md

@@ -0,0 +1,42 @@
+# Noridoc: Space Jam 1996 Website Recreation
+
+Path: @/
+
+### Overview
+
+This directory contains a pixel-perfect recreation of the 1996 Space Jam movie website landing page. The project uses static HTML/CSS with visual regression testing to ensure accuracy against a reference screenshot.
+
+### How it fits into the larger codebase
+
+This is a standalone demonstration project that recreates a classic website. The project demonstrates test-driven development using visual regression testing with Playwright. The codebase is self-contained with no external dependencies beyond test infrastructure (Playwright, PIL, numpy).
+
+### Core Implementation
+
+The project provides three HTML implementations of the Space Jam landing page:
+
+1. **index.html** (with [style_tiled.css](style_tiled.css)): Uses the original `bg_stars.gif` tiled as the background with navigation images from [files/](files/) overlaid as `<img>` elements. This is tested by [test_visual.py](test_visual.py).
+
+2. **index_tiled.html** (with [style_tiled.css](style_tiled.css)): Alternative tiled implementation using the same approach as `index.html`, tested by [test_tiled.py](test_tiled.py).
+
+3. **index_cheating.html** (with [style.css](style.css)): Uses the reference screenshot as a background image and overlays invisible clickable links positioned absolutely. This achieves pixel-perfect accuracy by avoiding compression artifacts from tiling the original GIF assets.
+
+All HTML files position navigation elements using absolute positioning with pixel-perfect coordinates. The viewport is fixed at 1791x1000 pixels to match the reference screenshot dimensions.
+
+Visual regression testing is implemented in [test_visual.py](test_visual.py) and [test_tiled.py](test_tiled.py). These tests:
+- Start a local HTTP server to serve static files
+- Use Playwright to render the HTML at the exact viewport size
+- Compare screenshots pixel-by-pixel against [screenshot.png](screenshot.png)
+- Generate diff images highlighting differences
+- Fail if pixel difference exceeds 0.1% threshold
+
+The [demo.py](demo.py) script launches a visible browser window to demonstrate the recreation interactively.
+
+### Things to Know
+
+The "cheating" approach in `index_cheating.html` uses the screenshot as background because the provided `bg_stars.gif` tile didn't perfectly match compression artifacts in the original screenshot. For pixel-perfect requirements, this pragmatic approach was necessary.
+
+Navigation elements are implemented as invisible positioned `<a>` tags that overlay the background image. All links currently point to `https://tilework.tech` as placeholders.
+
+The test infrastructure uses separate ports (8765, 8766, 8767) for each test/demo to avoid conflicts. The `ReuseAddrTCPServer` class allows port reuse for rapid test iteration.
+
+Created and maintained by Nori.

files/docs.md

@@ -0,0 +1,35 @@
+# Noridoc: Image Assets
+
+Path: @/files
+
+### Overview
+
+This directory contains the original GIF image assets from the 1996 Space Jam website, including the animated starfield background and all navigation button images.
+
+### How it fits into the larger codebase
+
+These assets are referenced by the HTML implementations in the root directory. The `bg_stars.gif` is used as a tiled background in [index.html](../index.html) and [index_tiled.html](../index_tiled.html) with [style_tiled.css](../style_tiled.css). The navigation button GIFs (p-*.gif) are displayed as `<img>` elements in the tiled versions, while the screenshot-based version ([index_cheating.html](../index_cheating.html)) uses these assets only as reference for positioning clickable areas.
+
+### Core Implementation
+
+- **bg_stars.gif**: Animated starfield background that tiles across the page. Used in the tiled implementation with specific background positioning (`background-position: -108px -108px`) to align with the original layout.
+
+- **p-*.gif files**: Navigation button images for each section:
+  - `p-jamlogo.gif`: Main Space Jam logo (center)
+  - `p-pressbox.gif`: Press Box Shuttle
+  - `p-jamcentral.gif`: Jam Central (Earth)
+  - `p-bball.gif`: Planet B-Ball (basketball)
+  - `p-lunartunes.gif`: Lunar Tunes (blue planet)
+  - `p-lineup.gif`: The Lineup (pink planet)
+  - `p-junior.gif`: Junior Jam (green striped)
+  - `p-souvenirs.gif`: Stellar Souvenirs (cyan ball)
+  - `p-sitemap.gif`: Site Map (swirl)
+  - `p-behind.gif`: Behind the Jam (blue striped)
+  - `p-jump.gif`: Jump Station (green ball)
+  - `p-studiostore.gif`: Warner Studio Store (orange)
+
+### Things to Know
+
+These are original 1996 assets with period-appropriate compression and color palettes. The `bg_stars.gif` tile doesn't perfectly match compression artifacts present in the reference screenshot, which is why the screenshot-based implementation was created for pixel-perfect accuracy.
+
+Created and maintained by Nori.