Canonical Handoff Spec

_MyAnythingList / _MyAnythingGrid Requirements

This document is the continuity spec for future sessions. It exists to stop repeated regressions, repeated explanation, accidental redesign, and wasted emotional energy.

1. Master Rule

Once a requirement is decided, it becomes the permanent documented standard until the user explicitly changes it.

No casual redesign.
No “small spacing fix” that silently changes borders, corners, glow, padding, overlays, cursor behavior, or tile composition.
Future sessions must read this file first and treat it like a checklist.
Thumbnail filename standard: downloaded thumbnails must never use YouTube-like or URL-like filenames. Use MyAnythingList_Thumbnail_YYYYMMDDhhmm.ext only.
Modal context rule: while a modal is open, the gear/control-toggle must not be clickable. Closing a modal should return to the immediately previous context.
Load modal placement: the playlist loader must always be horizontally centered and must never overlap the control-bar boundary line.
Remote playlist requirement: the exact sample URL https://8k.art/_MyAnythingList.txt must load instantly on both local and hosted builds.
Remote playlist general rule: any playlist URL should be valid in both the GET string and the startup JavaScript config object.
Gear behavior: the visible gear should read as the gear itself, not as a tiny glyph trapped inside a heavy button.
Control crowding: slider rows, knobs, and controls must not overlap or visually crowd nearby controls.

2. HTML Header Invariant

The first lines of source must always begin exactly like this, with no whitespace before the DOCTYPE:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>The Real FREE PRESS</title>

3. Canonical Thumbnail Rendering Reference

The canonical reference for thumbnail rendering is the look shown by index_beta_2026-03-07-v78.html, then further evolved without changing the essential visual language.

Rounded inner corners inside the tile border.
Visible border and shadow structure.
Canonical footer overlay with type pill and URL text.
QR code placement integrated into the tile without redesign.
Selected tile gets a vivid magical pulsing green glow.
Changing padding or safe-zone values must never cause a total thumbnail redesign.

4. Aesthetic Standard

The UI must feel safe, orderly, calming, hypnotic, visually clear, and intelligent.
Zero redundant wording. Zero visual disorder.
No ugly student-looking modal boxes.
No inconsistent button sizing or orphaned labels.
The green pulsing glow is a major feature and must not be weakened or removed.

5. Safe Zone and Space Efficiency

A safe zone is required on all sides because some displays crop outermost pixels, especially CRTs and overscanning displays.
This safe zone must be accounted for, but must not be overcompensated.
Use all available space efficiently.
Top control bar spacing must be minimal, consistent, and symmetric.
Above the footer: only the minimum aesthetically acceptable black padding.
Footer: enough bottom safe zone for cropped displays.
No wasted vertical space anywhere.
OPTIMIZE FOR SPACE is a permanent rule. Controls, buttons, dropdowns, overlays, and margins should use only the space truly needed for clarity, touchability, and beauty.

6. Tile / Glow / Corner Non-Regression Rules

Tile corners must stay rounded inside the border.
Thumbnail panels must preserve their canonical formatting and styling.
The magical selected-tile green glow must remain strong, visible, pulsing, and have enough room to render.

7. Thumbnail Quality Rule

Thumbnail quality should always be max. This is a print-driven product.

YouTube thumbnails must request the highest available resolution first.
Priority order:
1. maxresdefault
2. sddefault
3. hqdefault
4. mqdefault
5. default
On playlist load, visible top thumbnails should appear immediately while the rest continue loading.
The wall should never go fully black during loading when avoidable.

8. Startup / Playlist Modal Requirements

The main control bar button must read Load a New Playlist.
If the modal is opened at startup with no playlist, title should read No playlist loaded.
If the user opens it manually later, title should read Load a New Playlist.
Modal wording must be minimal, non-redundant, and centered where appropriate.
Actual URL text box should be left-aligned.
Close button belongs at the bottom.
The modal must always sit below the control-bar bottom divider and never cover the control area.

9. Playlist Loading Requirements

Remote playlist loading from the modal must work from local downloaded builds and hosted builds.
If direct in-page fetching is unreliable, the accepted fallback is to reopen/navigate using ?myanythinglist=<URL>.
If the remote input appears blank but has the demo URL as placeholder/default sample, pressing the remote-load button must still load that sample URL.
The family-friendly default sample playlist is https://8k.art/_MyAnythingList.txt.

10. Playlist Editor Requirements

The editor is a true _MyAnythingList.txt editor.
It must preserve and display raw UTF-8 source text character-for-character.
Even with no playlist loaded, a user must be able to open the editor, paste one YouTube URL, save, and immediately see results.
Editor should open scrolled to the very top.
Editor controls must include Load a New Playlist and Download THIS _MyAnythingList.txt.

11. Naming Conventions

Exported thumbnail names must never look like source URLs.
Canonical thumbnail filename format is MyAnythingList_Thumbnail_YYYYMMDD_HHMMSS.jpg or PNG equivalent.

12. Print / Export Requirements

Support 3.5" × 2" business cards at 300 and 600 DPI.
Support standard postcards at 300 and 600 DPI.
WYSIWYG QR placement/scale is required.

13. Feed Type Expansion

Add a future feed type called STREAM.
Users must be able to enter playable video stream URLs directly in playlists.

14. Documentation Direction

Docs should live under 8k.art/_docs so users do not need local files.
Documentation must be translation-ready English written for high-school graduates with minimal computer experience.
Everything decided in session should be documented in one of the docs or a new one.
Future versions must be able to move docs to S3/CDN paths without architectural changes.