Requirements

Last updated: 2026-03-12 v04

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

5.1 URL Art Accuracy and Fitting

• URL art must be treated as a first-class thumbnail mode, not as a rough preview.
• The exported image must match the on-screen tile composition as closely as practical: same text scale, same line breaks, same safe areas, same QR relationship, and same footer interaction.
• The full URL text should be scaled down to fit exactly within the tile whenever the URL length is within normal operating bounds.
• If the short URL/footer URL is visible, URL art must not be placed underneath that small URL. The main URL art block should remain visible in the remaining design area.
• If the short URL/footer URL is hidden, the URL art block may use lower tile space more aggressively.
• Only at absurdly short or absurdly long extremes may the system relax exact fit expectations. In those edge cases, the renderer should preserve artistic intent while minimizing clipping.
• Within normal ranges, the full URL should remain visible in URL art whenever possible.

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

• The startup QR position, size, and anchoring used on first paint must match the steady-state tile layout. A QR code that appears in the wrong place at startup and later snaps into place is a bug.
• When QR display is enabled, all initially visible tiles must render their QR code immediately on load using the final computed geometry for that tile.
• Visible content must appear first. Work that is not needed for the first viewport should be deferred until after the visible area has already painted.

• 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

• Every relevant prompt in an active design conversation must be curated into the documentation set during the next iteration.
• Explicit requirements from prior conversation artifacts are binding until replaced. Missing them in later iterations is a documentation failure, not a user reminder problem.
• The user should never need to repeat an already-defined project rule merely because it was forgotten in a later pass.

• 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.