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.

16. Tile Layering, Startup Visibility, and Viewport Fit Requirements

Immutable tile layer order

• Tile composition must use a fixed back-to-front layer sequence that does not change between startup, steady state, export, download, or print.
• Background thumbnail content renders first. This includes generated backgrounds, downloaded thumbnails, uploaded thumbnails, replacement images, and URL Art thumbnails.
• The QR code renders on its own dedicated QR layer above all thumbnail imagery.
• The type pill renders above the QR layer.
• The small URL footer text renders above the type pill.
• Optional top text overlays render above those layers when enabled.

Visible-first startup

• On startup, only the tiles already visible in the viewport should be prioritized for immediate rendering.
• The QR, type pill, and small URL for visible tiles must also be correct on first paint.
• Remaining off-screen tiles may continue loading after the visible-first frame is stable.

URL Art WYSIWYG rule

• URL Art is a thumbnail class, not a UI overlay.
• Live display, export, download, and print must preserve the same URL Art proportions, positioning, scaling, and clipping rules.
• The export path must preserve the same composited order used by the live tile.

Fit and safe-area controls

• The control panel must expose a compact Fit dropdown with the modes fitWidth, fitHeight, and fitEverything.
• The control panel must expose a compact Safe Area dropdown with the profiles digital and tube.
• These are real runtime settings and must be represented in window.MyAnythingListConfig and GET/state URL handling.
• Digital displays may use a very small safe area. Tube TVs must use a much more generous safe area.