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-12 v14

2026-03-17 Conversation Additions

2026-03-17 Additive Expansion: These are additive non-negotiable requirements ratified after the original v14 requirements document. They do not replace earlier requirements; they formalize additional binding truth.

R1. Documentation Preservation Rule

No previously documented information may be removed, reduced, summarized, or replaced with lower-detail text. Documentation is append-only by default. Updated files should generally become larger because knowledge accumulates. Any shrinkage is treated as a regression risk requiring explicit justification.

R2. Unified Render Truth

The project must use one canonical composition model for live rendering, export rendering, scripted rendering, and future automated rendering. Separate export reconstruction that can drift from live behavior is disallowed.

R3. Native 4K / 8K Fidelity

Selected output size is real. The system must render generated layers at target resolution, including 4K and 8K classes, rather than scaling up lower-resolution previews. This requirement applies especially to QR, URL-art, pills, labels, and other generated text.

R4. QR Presence Requirement

If QR is visible live, QR must be present in export. The QR layer must remain dedicated and above thumbnail or URL-art imagery. Omission caused by timing, export shortcuts, or alternative code paths is unacceptable.

R5. Text-Only Tile Quality Requirement

When no bitmap thumbnail exists, URL-art plus QR output must still be professional and sharp at 4K and 8K. Text-only tiles are first-class outputs, not degraded placeholders.

R6. Export Quality Rule

PNG is the default master-quality path. Silent quality-reduction loops on the master path are not permitted. Explicit lower-quality or smaller-size modes may exist only as user-chosen alternatives.

R7. Localization Rule

All user-facing controls and labels must be localizable. Documentation must define language-agnostic labeling strategy, support for world languages, and resilience for both LTR and RTL interfaces. The project serves schools worldwide; therefore multilingual deployment is part of the requirement set, not optional polish.

R8. Replicability Rule

The documentation package must be sufficient for open-source programmers to repeat prior work without requiring the original author. If behavior is discussed and accepted, it belongs in the docs. Tribal knowledge is not an acceptable dependency.

R9. Verification Rule

Acceptance tests, failure conditions, golden render cases, and release checklists are required parts of the package so future contributors can detect regressions objectively.