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.

v12 Delta — Deterministic Grid Geometry Rule

Principle: Never compute layout until the required inputs are known, and never recompute it unless new wall-level information exists.

Grid geometry must be solved exactly once when the following inputs are known:

• startup control state
• viewport and safe-area geometry
• aspect ratio and fit mode
• number of loaded URLs (tile count)

Once these inputs are known, the wall grid (rows, columns, tile size, and margins) must be computed deterministically and remain stable.

Thumbnail image loads, QR generation, and URL-art rendering must update only the contents of an existing tile box. These events must not trigger a recomputation of wall geometry.

Grid geometry may be recomputed only when one of the following changes:

• a control state
• viewport size
• safe-area selection
• tile count

This rule prevents unnecessary redraw loops and ensures consistent rendering between the startup pass and later rendering phases.