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-17 v15

v15 Delta — Unified Live/Export Rendering Contract

This section converts the 2026-03-16 conversation into mandatory developer rules.

There is one rendering system. Live view and export are two outputs of the same composition model, not two independently-evolved drawing paths.

canonical state
  → tile composition model
  → resolution-aware renderer
  → live canvas or export canvas

• Do not maintain a fragile “manual export reconstruction” path that redraws image, URL art, and QR from a different code path than the live tile.
• Do not capture the DOM at monitor resolution and upscale it later.
• Do not allow export-specific layout shortcuts that can drift from the live layer stack.

Recommended implementation discipline

renderTile(tileState, targetWidth, targetHeight, mode)
  - resolve geometry once
  - resolve layer visibility once
  - draw background
  - draw thumbnail image or URL art
  - draw QR on dedicated layer
  - draw type pill
  - draw small URL
  - draw optional footer/overlays
  - return high-resolution canvas

The function above is illustrative, not normative in naming. The normative rule is that the same composition decisions must drive both live output and downloaded output.

v15 Delta — QR Readiness, Timing, and Regression Prevention

• Export must not proceed until QR readiness is confirmed. If QR generation or placement is asynchronous, export waits rather than silently dropping the QR.
• QR startup position must be computed from final tile geometry. Any placeholder placement before geometry settles is a bug, not an acceptable transient.
• When developers refactor export, thumbnail, or layout code, regression tests must explicitly cover: live QR visible → exported QR visible; live URL art readable → exported URL art readable; no-image text-art tile → 8K sharpness preserved.
• When merging work from older branches or earlier builds, developers must begin from the latest known-good version so already-fixed QR and layout behavior is not lost.

v15 Delta — Encoding, Performance, and Source-Quality Policy

• High-quality export mode should not run an invisible JPEG quality step-down loop whose only purpose is to force a small file. That is a convenience mode, not the canonical master path.
• For source-limited imagery, the renderer should preserve the best available bitmap while still drawing QR and text with full output-resolution sharpness.
• If an implementation uses offscreen rendering, the offscreen container or canvas must still be created at the final export resolution, not at display size.
• Any optimization that changes composition, order, visibility, or fidelity is not a safe optimization and must be documented as a behavior change.