Developer Guide

developer_en.html

This document describes how developers should understand, extend, and maintain the MyAnythingList system.

1. Development Philosophy

• Preserve simplicity.
• Preserve human-readable text.
• Prefer transparent behavior over hidden logic.
• Document decisions clearly.

2. Core System Components

Playlist text
   ↓
URL discovery
   ↓
Command parsing
   ↓
Tile model creation
   ↓
Thumbnail / QR resolution
   ↓
Grid rendering

3. Playlist Parser

The parser extracts valid URLs from any UTF-8 text.

• URLs may appear anywhere in text.
• Lines beginning with # are comments.
• Commands use the syntax #_Command().

My research notes:

https://example.com/article

#_ReplaceThumbnailWithImage("cover.jpg")

4. Command System

Commands extend playlist behavior.

#_ReplaceThumbnailWithImage("image.jpg")
#_LoadImage("panel.png")
#_LoadImageHideLinks("poster.png")

5. UI State Architecture

Runtime state is controlled by configuration variables.

• ShowControls
• ShowGear
• AutoHideGear
• ShowQR
• ShowTypes
• ShowURLs

• startup configuration
• URL parameters
• UI interaction

6. Thumbnail System

Command thumbnail
→ Uploaded thumbnail
→ Platform thumbnail
→ Fallback image

• QR images must never replace thumbnails.
• Uploaded images must affect only the intended tile.

7. Contribution Guidelines

• Preserve existing behavior unless explicitly redesigned.
• Update documentation when behavior changes.
• Favor readability over cleverness.

8. Long-Term Goal

v09 Delta — Implementation Routing and Export Details

Future sessions should not reread the full corpus every turn. Keep a high-level routing map of which document owns each type of rule and update only the affected docs. For the build, ViewScaleMode and SafeAreaProfile are first-class runtime settings that belong in window.MyAnythingListConfig and should also be GET-addressable. Exported thumbnails must capture the final composited tile canvas and use informative filenames such as MyAnythingThumbnail_2026-03-12_041552PM_3840x2160.png.

Updated: 2026-03-12 v09

v10 Delta — Latest-Build Discipline and Packaging Boundaries

Always build from the latest version. A new iteration may not start from an older build when a newer build already contains fixes or clarified runtime behavior. This rule prevents regressions such as the return of previously corrected QR startup behavior.

Canonical docs folders are meant to copy directly into 8k.art/_docs/en without stowaway files. Progress logs belong at the root of the iteration package beside the app build and handoff file, not inside the canonical docs folder.

All documentation pages must share the standard navigation header/footer and the same high-visibility freshness timestamp treatment at the top and bottom so anyone opening any page immediately knows how current it is.

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: The original developer guidance remains unchanged above. The material below adds hard implementation rules so later contributors cannot accidentally reintroduce the exact regressions discussed in the 2026-03-16 conversation.

A. One Renderer Rule

There is one renderer. Developers may expose multiple entry points such as live render, export render, batch render, print render, or scripted render, but those entry points must all drive the same compositional truth. Separate "manual export reconstruction" code paths are prohibited where they drift from live behavior.

composeTile(state, layout, outputSpec) -> canonical composition model
renderTile(compositionModel, outputSpec) -> raster or export artifact

• The live UI may preview a tile at UI scale.
• The export path must call the same composition model at target resolution.
• The print path must not substitute its own composition logic.
• Any scripting API must map to documented state, never to invisible ad hoc mutation.

B. QR Developer Rules

• If QR is visible live, it must exist in export. Missing QR in export is a hard failure.
• QR waits for final geometry and final payload readiness. A race condition is not an excuse for omission.
• The QR payload must preserve the full valid URL, including anchor-comment fragments where those fragments are part of the authoritative target.
• QR draws on its own layer above thumbnail imagery and URL art.
• Developers must not flatten the QR into a thumbnail image source or treat it as background art.

C. Text and URL-Art Developer Rules

• URL-art tiles are first-class tiles, not fallback junk states.
• Text-only tiles must render sharply at selected output size, including 8K.
• No DOM screenshot or browser-raster text stretching is allowed as the final master-fidelity path.
• Text fitting logic must be deterministic and shared between live and export, so line breaks and fit decisions do not drift unexpectedly.
• Long URLs should fit when reasonably possible; clipping is reserved for extreme cases and must remain visually intentional.

D. Image and Quality Rules

• Use the highest available image source for export.
• If the image source is smaller than target resolution, the bitmap layer may be source-limited; overlays must remain crisp.
• Do not silently walk JPEG quality downward on the master-fidelity path.
• PNG is the default reference-quality export path unless the user explicitly chooses another format.
• File-size-limited or socially-shareable compression modes must be explicit user choices, not silent downgrade loops.

E. Localization and Labels

All user-facing controls and labels are now documented as localization-sensitive. Developers must define visible text through language keys or another clearly localizable system. Hardcoded English-only labels violate the new worldwide-schools requirement. Layout must survive longer translated strings and right-to-left languages without breaking control visibility or tile integrity.

F. Documentation and Contribution Rules

• If a behavior exists in code and is not documented, the docs are incomplete.
• If a conversation ratified a new requirement, the next doc update must record it in the correct focused document.
• Contributors may expand, clarify, and cross-link documentation, but must not shrink or summarize away earlier detail.
• Every future ChatGPT or AI-assisted doc pass operates under a no-loss constraint.
• Updated docs are expected to become larger and more explicit over time.