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.

v11 Delta — Selection-Armed JPEG Pre-Rendering

• The system must use a unified two-step tile interaction rule: selecting an unselected tile must not activate it, except that startup-prearmed tile 1 may activate on the first post-load click.
• Selecting a tile must immediately trigger a background JPEG render/preparation pass for that tile using the current output-resolution and visible tile composition state.
• The default thumbnail-download format should be JPEG unless a user explicitly selects another mode.
• If the user presses the download button before the JPEG is ready, the button must acknowledge the click immediately and the JPEG download must begin automatically as soon as preparation completes, without requiring a second click.
• The same background-preparation and queued-download behavior must apply consistently for every tile.

Updated: 2026-05-06 v11

v12 Delta — Real-Time Button Feedback, Educational Reliability, and Quality Demands

• Zero-latency button acknowledgment: every button in the app must provide visible press feedback at the earliest possible input moment, before any subsequent processing. This requirement is global and must be implemented from one shared button-feedback pathway rather than duplicated per button.
• No perceptible delay: button feedback must feel instantaneous on modern hardware. A user must never wait for click acknowledgment while app logic, exports, network work, parsing, rendering, or downloads continue afterward.
• Stable button geometry: button feedback must not resize controls, reflow labels, or cause distracting layout shifts. Visual acknowledgment should use styling such as border, glow, animation, or other non-resizing effects.
• Download behavior: the Download Thumbnail button must acknowledge press instantly and then fulfill the requested download as soon as the export artifact is ready. If pre-rendered output is ready, download should begin immediately after acknowledgment.
• Schools and colleges: this app is intended to be teachable, demoable, and dependable in classrooms, labs, studios, libraries, and campus media environments. Immediate feedback is therefore not cosmetic; it is a core usability requirement for instruction, accessibility, confidence, and trust during live teaching and public demonstration.
• Quality philosophy: visible UI responsiveness is a non-negotiable product-quality baseline. A build that allows perceptible delay before button acknowledgment fails the intended standard even if the underlying function eventually succeeds.

Updated: 2026-05-06 v12

v13 Delta — Universal Pointer-Down Acknowledgment and Deterministic Startup

• Universal rule: every button must acknowledge input from one shared global pathway with identical timing and identical visual-language rules.
• Earliest moment: visible feedback must appear at pointer-down or the earliest equivalent input phase. This feedback must be the first visible consequence of the press.
• Parallel processing: after feedback is triggered, processing may begin immediately and may continue while the feedback animation is still in progress. The system must not wait for animation completion before beginning work.
• Single highlighted control: the currently pressed button alone may show the active feedback state; previously active buttons must promptly restore so the interface remains visually unambiguous.
• Deterministic startup tile: the application must start on tile 1 every time unless a future shuffle feature is explicitly enabled. Apparent random startup selection is a failure.

Updated: 2026-05-06 v13