Requirements

requirements_en.html

This document defines the canonical behavioral requirements for the MyAnythingList and MyAnythingGrid system. It is intended to be detailed enough that a future human or AI contributor can reconstruct the system without relying on chat history, private notes, or undocumented assumptions.

1. Core Non-Negotiable Premise

MyAnythingList converts any UTF-8 free-form text document into a valid URL playlist by extracting recognized URLs wherever they appear in the text.

• It does not require one URL per line.
• It does not require rigid playlist syntax.
• It may process ordinary notes, essays, outlines, transcripts, logs, multilingual prose, and mixed documents.
• It must support left-to-right and right-to-left writing systems.
• It must support any language that can be represented in UTF-8 text.

2. URL Extraction Requirements

The parser scans input text and extracts valid URLs in order of discovery. That order defines the playlist order unless later behavior explicitly changes it.

• URLs may appear anywhere in a document.
• URLs may appear inside sentences, paragraphs, bullet lists, or mixed notes.
• URLs may be repeated; duplicate handling may be documented later but must never alter discovery order silently.
• Anchor text, descriptive text, and surrounding prose are permitted and expected.
• Very long URLs must still be handled as valid playlist items.

Example:

Today's research and media notes:

Watch this:
https://youtube.com/watch?v=ABC123

Then compare with:
https://example.org/article

Reminder: translate this later.

3. Comment and Command Rules

3.1 Comment Rule

Lines beginning with # are treated as comments and ignored by default.

3.2 Command Rule

A comment line may also contain a recognized command using the form:

#_CommandName(...)

These commands are not ordinary comments. They are part of the playlist language and must be parsed intentionally.

3.3 Command Context Rule

Unless the command explicitly defines standalone content, a command applies to the most recent URL above it.

https://example.com/page-a
#_ReplaceThumbnailWithImage("https://example.com/image-a.jpg")

https://example.com/page-b
#_ReplaceThumbnailWithImage("https://example.com/image-b.jpg")

4. Supported and Planned Command Behavior

4.1 Replace Thumbnail With Image

#_ReplaceThumbnailWithImage("https://example.com/image.jpg")

• Applies to the most recent URL above the command.
• Overrides platform-derived thumbnail behavior for that tile.
• Must not become GET-driven or exported object-driven state by default.
• Belongs to the playlist document itself.

4.2 Load Image

#_LoadImage("https://example.com/image.jpg")

• Creates a URL-less image presentation panel in the grid.
• The image URL is itself the content source.
• The QR code, when shown, points to that image URL.
• Useful for informational, decorative, instructional, and kiosk panels.

4.3 Load Image Show Links

#_LoadImageShowLinks("https://example.com/image.jpg")

• Creates an image presentation panel.
• Preserves visible URL and QR affordances.
• Suitable for image-based panels that remain visibly linkable.

4.4 Load Image Hide Links

#_LoadImageHideLinks("https://example.com/image.jpg")

• Creates an image presentation panel with hidden link affordances.
• Useful for signage, FYI panels, explanatory inserts, and non-clickable informational tiles.
• Should remain documented as intentionally different from normal URL-backed tiles.

5. Thumbnail Requirements

Tiles may obtain thumbnails from several sources.

• QR code graphics must never be mistaken for thumbnails.
• Uploaded thumbnails must not disappear essential overlays unless a command explicitly requests hidden links.
• Thumbnail overrides are part of the content design system, not accidental UI hacks.

6. QR Code Requirements

• QR codes are overlays, not thumbnails.
• QR visibility is controlled by startup/config/UI state.
• QR position and size must respect startup parameters and startup binding at first render.
• QR state must be correct on startup, not only after later UI interaction.
• QR codes must not stretch, replace, or contaminate thumbnail images.
• When image-only commands create panels, QR behavior must remain explicitly defined.

7. Tile Layering Requirements

The visual stack of a normal tile should remain logically separated.

Thumbnail or image layer
→ QR overlay
→ type pill
→ URL text / footer metadata

• Thumbnail uploads must stay behind type pill and URL footer when those are enabled.
• Command-driven thumbnails must not overwrite QR rendering.
• URL-art fallback tiles must still support overlays correctly.

8. Control Interface Startup Requirements

Runtime startup behavior is determined through the startup configuration object and compatible GET variables.

Important variables include:

• ShowControls
• ShowGear
• AutoHideGear
• ShowQR
• ShowTypes
• ShowURLs
• ShowHeaderText
• ShowFooterText

• The gear hotzone must not block large portions of nearby buttons.
• The gear must remain visible when controls are visible, because it serves as the close affordance.
• Auto-hide behavior must never incorrectly hide the gear while controls are actively shown.

9. Startup Configuration Requirements

The startup architecture separates runtime/state values from branding/template values.

• window.MyAnythingListConfig contains real startup/runtime values and URL-mirror values.
• PageTitle, HeaderText, FooterText, ProjectSourceURL, and BUILD_FILE are separate top-level startup variables.
• Branding/template text does not belong in recreate-state URLs or exported state objects.
• Browser title should be set from PageTitle so the same file can remain index.html in generic deployments.
• Generic builds must not contain hard-coded branding for specific downstream deployments unless intentionally edited for that deployment.

10. Playlist Editor Requirements

• The editor must permit loading local text files.
• The editor must permit loading remote playlist URLs when CORS allows it.
• The editor must preserve ordinary free-form text behavior and not falsely imply one-URL-per-line restrictions.
• The editor should describe commands accurately and avoid misleading syntax hints.
• The editor must rebuild the wall from edited text.
• The editor must support thumbnail upload behavior without corrupting tile overlays.
• Remote-source labels should not falsely imply success when remote loading has failed.

11. Remote Playlist Loading Requirements

• Remote playlists must load through public HTTP or HTTPS when CORS is correctly configured.
• Remote loading should use straightforward cross-origin-safe requests such as mode:"cors" and credentials:"omit" when appropriate.
• Failure modes must be honest and visible.
• Successful loading must update source labels only after actual success.
• Local-file mode and hosted mode should be handled carefully, since browser behavior differs.

12. Output, Export, and Print Requirements

• The system must support configurable output resolutions for thumbnail export and print workflows.
• Print/card/postcard style outputs are part of the intended use cases.
• Download format choices should remain readable, explicit, and predictable.
• Output-resolution lists should be presented in a logical and stable order.

13. Documentation Requirements

• The documentation set must be sufficient to onboard future humans and AI systems.
• Each major English document must be long-form, logically structured, and translation-ready.
• Core rules must be repeated across multiple docs where necessary so they are not easily missed.
• The documentation should eliminate dependence on private chat history for core system understanding.
• Historical chat logs may exist for human insight, but they are not the canonical spec.

14. Deployment and Hosting Requirements

• The system must remain usable on static hosting.
• Apache, S3, and CDN-style hosting are first-class targets.
• Folder browsing and generated indexes are part of the transparency model.
• Where possible, static generation should be preferred over request-time CPU overhead.
• Authoring/mastering and public serving may be separated into different hosting layers.

15. Final Requirement

MyAnythingList must remain a flexible, transparent, multilingual, human-friendly system for turning ordinary text into useful media navigation surfaces. Any future development that quietly narrows this flexibility should be treated as a regression unless that change has been explicitly justified and documented.

v09 Delta — View Scaling, Safe Area, and Export Guarantees

• Fit Width must use the full available horizontal space of the usable viewport. In the Digital safe-area profile that should look near full width with only tiny margins.
• Fit Everything must compute a uniform scale that fits the full visible grid inside the usable viewport rectangle.
• Downloaded thumbnails must be fully WYSIWYG at the selected Output_Resolution. The QR code must appear in the exported thumbnail whenever QR is visible in the live tile, and must be absent only when intentionally hidden.
• Thumbnail filenames must use the format MyAnythingThumbnail_YYYY-MM-DD_HHMMSSAM_Resolution.ext, for example MyAnythingThumbnail_2026-03-11_125330PM_3840x2160.png.

Updated: 2026-03-12 v09

v10 Delta — Freshness, QR Payload, Export Fidelity, and View Rules

• Every documentation page must use the standard navigation header and footer and must show a highly visible freshness timestamp at both the very top and the very bottom of the document.
• QR payloads must encode the full valid URL line, including anchor-comment fragments when present. The QR code is not a shortened URL and must preserve the full shareable target.
• Exported thumbnails are always WYSIWYG scaled to the selected output resolution. QR appears in export whenever it is visible in the UI and disappears only when intentionally hidden by the QR toggle.
• Downloaded thumbnails must preserve quality. Scaling down is acceptable; unnecessary quality loss, low-resolution capture, or re-enlargement are not.
• URL art is a thumbnail class and should scale to fill the readable viewable area when possible, while remaining significantly larger than the smaller URL footer text. If fitting the entire URL would make it unreadably small, the system may keep a larger artistic layout instead.
• Uploaded thumbnails must scale to fit the panel logically instead of cropping unpredictably.
• Progress logs are root-level iteration artifacts and must not ride inside the canonical docs folder that is intended for copying directly into 8k.art/_docs/en.
• Builds must always start from the latest version so previously-fixed startup QR behavior and other resolved regressions are not lost in later iterations.

v14 Delta — Educational Mission, Transparency, and Misuse Resistance

MyAnythingList is a public educational system intended to help ethical, curious, and globally diverse people learn how information can be structured, inspected, rendered, and shared. The project should favor transparency, inspectability, multilingual access, and source-aware communication over black-box presentation.

• Open documentation, visible runtime logs, and educational commentary in code are intentional safeguards.
• The system should encourage understanding, attribution, and critical inspection rather than manipulative opacity.
• Language support should treat world language communities equitably, including both LTR and RTL interfaces.
• The project should be designed so good-faith users can learn it quickly and adapt it responsibly.
• No documentation update should erase the project’s educational and civilizational purpose.

Updated: 2026-03-17 v15

v15 Delta — Canonical Export Fidelity, Text-Only Mastering, and Contributor Independence

Promoted from the 2026-03-16 conversation and now part of the canonical requirements.

The following rules are non-negotiable requirements, not optional implementation suggestions. They exist so future work can continue correctly even if the original author is unavailable.

Export fidelity requirements

• Downloaded thumbnails must be a true WYSIWYG export of the final tile composition. Exported output must match the live tile’s composition model, not an approximate reconstruction.
• The export path may never rely on a viewport screenshot, monitor-resolution DOM capture, or low-resolution flatten-then-upscale shortcut.
• 4K and 8K exports are first-class deliverables. The system must render directly at the chosen output size, including at least 3840×2160, 4096×2160, 7680×4320, 8192×4320, and 4320×7680.
• No export bug fix is allowed to reduce output fidelity. A fix that restores QR visibility while lowering final sharpness is not acceptable.

Canonical layer order

1. background layer
2. thumbnail image or URL text art layer
3. dedicated QR layer
4. type pill layer
5. small URL text layer
6. footer or optional overlay layer

The QR code is never treated as a background image and must remain on its own layer above imagery or URL art and below the pill and small URL.

Text-only tile requirements

• When no bitmap thumbnail exists, URL text art plus QR is still a first-class export mode and must produce a crisp high-end 4K/8K master.
• A text-only tile has no excuse for softness. URL art, QR, type pill text, small URL text, and geometric overlays must remain sharp because they are generated elements rather than inherited low-resolution pixels.
• The full URL should fit inside the tile when reasonably possible. If an extreme URL would become unreadably small, the system may keep a larger artistic arrangement, but only as a deliberate readability-preserving decision.

Encoding and source-asset requirements

• Master-fidelity export should prefer PNG by default. JPEG may exist as an explicit user option, but silent quality-loss loops are not allowed on the canonical high-quality path.
• For bitmap thumbnails, the system must use the highest available source asset. A lower-resolution source image may limit only the image detail itself; it must not soften QR, text, layout, or overlays.
• Compression, resizing, or recomposition steps that introduce avoidable degradation violate the requirements even if the overall layout appears correct.

v15 Delta — Explicit Failure Conditions