Agreed.

Non-negotiable v13 rule

8K export quality must be preserved. The docs already support that direction: exported thumbnails must render at the selected output resolution and do so without unnecessary quality loss, while remaining WYSIWYG and including QR whenever visible live.

The current build also explicitly includes UHD 8K (7680×4320), DCI 8K (8192×4320), and 8K Shorts (4320×7680) as export targets, so high-res output is already part of the intended architecture.

What that means architecturally

We should not fix the QR/export bug by flattening the live tile at screen resolution and upscaling it afterward. That would violate your quality requirement in practice, even if the composition looked correct.

Instead, v13 should use this rule:

One composition model, native-resolution render

• Keep a single canonical layer/composition model

• Render that model directly at the chosen export resolution

• Preserve the documented layer order:

  1. background

  2. thumbnail image

  3. URL art

  4. QR

  5. type pill

  6. small URL

  7. footer text

So the fix is not “capture the screen.”
The fix is “re-render the same tile model at 4K/8K/export resolution.”

Quality-preserving export requirements for v13

To satisfy your constraint, the export path should follow these rules:

1. No screenshot-based export

Do not export from CSS pixels, viewport pixels, or a visible DOM snapshot tied to monitor resolution.

2. Native export canvas

Build the export canvas at the exact chosen target:

• 3840×2160

• 4096×2160

• 7680×4320

• 8192×4320

• 4320×7680
  already present in the build.

3. Vector-like redraw for overlays

QR, pill, URL text, footer text, and URL art should be drawn from source/layout data at export resolution, not copied from low-res display pixels. This is especially important because the QR is a dedicated overlay layer and must remain readable and correctly positioned.

4. Best-source thumbnail policy

For bitmap thumbnails, export from the highest available source asset, then fit it according to the thumbnail rules. Where the source image is lower than 8K, output still remains 8K, but only the bitmap portion is source-limited; overlays and layout remain crisp.

5. No quality-reduction loop for high-res masters

The current encoder logic shows JPEG quality being stepped down until size shrinks below about 2 MB. That is exactly the kind of behavior that can sacrifice output quality.

For v13, 4K/8K master export should use:

• PNG by default for fidelity, or

• a true explicit high-quality JPEG option without automatic degradation loops

If file-size-limited JPEG is still needed, it should be a separate user-chosen mode, not the master-quality path.

Clean rule to add to the spec

I would phrase it like this:

Thumbnail export must use the same canonical tile composition as live rendering, but must render natively at the selected export resolution. No export fix may reduce 4K/8K output fidelity, flatten at screen resolution, or introduce avoidable recompression loss. Lower-resolution source thumbnails may limit underlying image detail, but overlays, QR, text, layout, and composition must remain crisp at the selected export size.

That is fully consistent with the existing WYSIWYG and quality language in your docs.

Bottom line

Yes: we should fix QR/export regressions only in a way that preserves true 8K master output.
No tradeoff that lowers final export fidelity is acceptable. The architecture should be:

single deterministic tile model + native-resolution export renderer + highest-quality encoding path.

I can turn that into a precise v13 export architecture spec and acceptance checklist next.

Yes — that requirement should be treated as equally non-negotiable.

v13 quality rule for text-only thumbnails

When no bitmap thumbnail exists, URL text art + QR must still export as a true high-end 8K asset, not as a low-res fallback. Your docs already establish the core pieces of that rule:

• URL Art is a first-class thumbnail mode and must export like any other thumbnail source.

• URL art export must aim for pixel-close WYSIWYG parity with the live tile.

• The full URL should fit inside the tile when reasonably possible, with clipping allowed only for extreme URLs.

• URL art should scale more aggressively into the readable thumbnail area while remaining legible and visually larger than the smaller footer URL.

• Downloaded thumbnails must include the final composited tile, including background/URL art, QR, type pill, small URL, and overlays, identical to the live tile.

The important architectural conclusion

For text-art-only tiles, export must not behave like “whatever the browser happened to rasterize on screen.”
It should behave like resolution-independent composition rendered natively at export size.

That means:

What must stay sharp at 8K

• URL text art

• QR code

• type pill text

• small URL/footer text

• any simple geometric overlays

Only a source bitmap image is allowed to be source-limited.
A text-only tile has no excuse for softness, because its important visual elements are generated content, not inherited pixel data. That follows directly from the project’s selected-output-resolution and WYSIWYG requirements.

Why the current path is not strong enough yet

The current v12 export logic still rebuilds text-art tiles on a canvas using a separate export path, and the live layout uses DOM measurement plus binary font fitting around QR position.

That means the quality risk is not only “missing QR,” but also:

• slight live/export typography drift

• text wrapping drift at different resolutions

• dependence on screen/layout timing

• raster softness if the export path borrows from display-state assumptions instead of export-resolution metrics

So for v13, text-art export should be treated as a precision renderer, not a fallback branch.

Best-practice v13 rule

Canonical render model

Create one canonical tile model containing:

• export width/height

• safe-area rules

• QR box geometry

• URL-art text box geometry

• font family / weight / line height

• alignment rules by QR quadrant

• footer URL box

• pill box

The live tile and the exporter should both derive from that same layout model. Your docs already point toward this by requiring parity between live appearance and downloaded output.

Native-resolution text rendering

At export time:

• build the canvas at the exact selected output size

• compute all text geometry at that size

• render text directly into the export canvas

• render QR directly into the export canvas

• do not upscale a screen-resolution raster

That is the only robust way to get “expert-level” text-only 8K output.

Specific text-art requirement I would add

When a tile has no bitmap thumbnail, URL Art becomes the primary thumbnail content and must render natively at the selected output resolution. In 4K and 8K exports, all generated text elements and QR graphics must remain crisp, properly fitted, and compositionally identical to the live tile. Text-only tiles must not rely on viewport-resolution screenshots, low-resolution raster clones, or post-upscale rendering.

That statement is consistent with your existing URL Art and WYSIWYG rules.

Practical acceptance test

A v13 text-only export should pass all of these:

1. At 7680×4320 and 8192×4320, URL art edges stay sharp when zoomed in.

2. QR modules remain crisp and scannable.

3. Live tile and exported tile match in placement, scale, and wrap behavior.

4. Typical URLs fill the tile strongly without looking timid or tiny.

5. Small footer URL remains secondary and does not crush the main URL art.

6. No bitmap thumbnail is required for premium-looking output.

Bottom line

You’re right to make this explicit:

text-only thumbnail mode should be one of the cleanest, sharpest, most professional export cases in the whole system.
Because it is generated typography plus QR, it should be capable of near-ideal 8K output quality when rendered correctly. That is fully aligned with the project’s current documented export and URL-art requirements.

I can turn this into a v13 text-art rendering spec with exact implementation rules and pass/fail criteria.

Yes. We can define it formally enough to implement.

Your current docs already establish the base rule:

• URL art should use as much readable panel area as possible.

• It should enlarge aggressively while staying legible.

• It must remain visually larger than the small footer URL.

• It must stay out of the small-URL zone when the small URL is showing.

So the missing piece is a formal stop condition for when “show more of the URL” starts hurting the art.

Formal v13 rule

Principle

Show the longest URL-art string that still preserves thumbnail impact.
If the full URL no longer preserves impact, shorten it to the longest aesthetically valid prefix or excerpt.

In other words:

maximize visible URL length subject to legibility, hierarchy, balance, and compositional energy.

That makes “artistically cool” a constrained optimization problem, not a vague feeling.

Programmatic definition of “no longer artistically cool”

A URL-art candidate is not artistically cool if any of these fail:

1. Hierarchy test

The URL art must remain clearly dominant over the small URL.

Fail if:

• URL-art font size < 1.9× footer URL font size

• or URL-art visual area is too weak to read as the primary texture/content layer

This follows your established rule that URL art must stay visually larger than the smaller footer URL.

2. Fill test

The URL art must still feel like it meaningfully occupies the readable thumbnail region.

Fail if:

• ink coverage of the allowed URL-art box drops below about 18%

• or the text block occupies less than about 55% of the dominant dimension it is supposed to energize

This is the formal version of “don’t let it get timid.”

3. Legibility test

It must still be readable at thumbnail-viewing scale.

Fail if:

• export-scaled cap height drops below a minimum threshold

• line density becomes so high that characters visually merge

• average inter-character clarity collapses from over-compression/wrapping

A practical proxy:

• minimum effective font size for URL art at export layout should not fall below ~3.2% of tile height for standard landscape tiles, adjusted by format

4. Rhythm test

The text block must still have pleasing line rhythm rather than turning into visual mush.

Fail if any of these occur:

• too many lines: more than 8 major lines for standard 16:9

• average words/segments per line become too tiny and fragmented

• too many orphan fragments like ht, tp, /, ?, &, = isolated repeatedly

• excessive jaggedness between adjacent line widths

A good measurable proxy:

• standard deviation of line widths should stay below a threshold

• orphan-token ratio should stay below 12%

5. QR coexistence test

The URL art must still coexist gracefully with the QR and not feel strangled by it.

Fail if:

• the remaining text region around the QR becomes too narrow to sustain bold readable text

• the QR forces the URL art into a thin leftover strip

• the URL-art bounding shape becomes too fragmented into awkward islands

This matches your current QR-dependent layout model.

6. Footer protection test

If the small URL is visible, URL art must not visually crash into that reserved zone.

Fail if:

• URL-art baseline or texture mass competes with footer readability

• the remaining art area above the footer is too short to sustain dominant text

That rule is already in your updated docs.

Psychological definition

Programmatically, the tests above are enough. Psychologically, “artistically cool” means the tile still reads in this order:

1. strong visual field / texture

2. clear main URL-art identity

3. clean QR presence

4. small URL as secondary support

It stops being cool when the viewer’s impression changes from:

• “bold, smart, designed”

to:

• “cramped, apologetic, overexplained, spreadsheet-like”

So psychologically, the failure state is when information density starts defeating confidence and poster-like impact.

Formal selection algorithm

For each tile, evaluate URL-art candidates in this order:

Candidate order

1. full normalized URL

2. full URL without protocol

3. domain + path

4. domain + first strong path segments

5. domain emphasis excerpt

6. branded/semantic excerpt from the URL

Choose the longest candidate that passes all quality tests.

That gives you the behavior you want:

• show as much as possible first

• shorten only when needed

• shorten intelligently, not randomly

Suggested scoring model

Use a weighted score:

Plain text
score =
  0.30 * visible_length_ratio
+ 0.20 * hierarchy_score
+ 0.20 * fill_score
+ 0.15 * legibility_score
+ 0.10 * rhythm_score
+ 0.05 * qr_coexistence_score

With hard gates:

• hierarchy_score must pass minimum

• legibility_score must pass minimum

• footer_protection must pass

• qr_coexistence must pass

This prevents a very long but ugly URL from winning just because it shows more characters.

Recommended fallback behavior

When full URL fails, shorten in this exact preference order:

Preferred truncation logic

• remove protocol first

• remove trailing slash noise

• de-emphasize query string

• de-emphasize fragment

• preserve recognizable domain

• preserve strongest semantic path segments

• avoid ugly mid-token chops unless unavoidable

So:

• https://define.com/_MyAnythingList.txt#section
  might become

• define.com/_MyAnythingList.txt
  then

• define.com/MyAnythingList
  then

• define.com

depending on fit.

Crisp spec language for v13 docs

Use this:

URL Art must display the longest aesthetically valid portion of the URL above the small URL area. The renderer should first attempt the full URL, scaled as small as necessary to preserve as much of the URL as possible. If the resulting composition ceases to remain visually dominant, legible, well-balanced, and artistically strong, the system must shorten the URL art to the longest candidate that preserves thumbnail impact. “Artistically strong” means the URL art remains the primary visual texture, clearly larger than the small footer URL, readable at thumbnail scale, rhythmically composed around the QR, and free from cramped or fragmented layout.

That fits your existing thumbnail rules cleanly.

My practical recommendation

For v13, define “no longer artistically cool” as:

• not dominant enough

• not filled enough

• not readable enough

• too fragmented

• too cramped around QR

• too competitive with footer

That is precise enough to code and close enough to human taste to produce reliable results.

I can turn this into a pass/fail engineering checklist with threshold values for 16:9, portrait, and square tiles.

Done.

I packaged the deliverables so the ZIP root contains the beta HTML, the handoff, and the versioned canonical docs folder, and I also included a second archived copy of the beta HTML inside archive/. That matches the packaging direction already documented in your uploaded handoff/update materials, while keeping the current included working build as index_beta_2026-03-12-v12.html.

Downloads

What I updated

The docs now include the new rules for:

• non-negotiable native-resolution 8K export quality

• premium-quality text-only URL art + QR thumbnails

• formal URL-art fitting behavior

• a programmatic/psychological definition of when a layout is “no longer artistically cool”

• daily build packaging rules with both root-level beta HTML and archived in-ZIP beta HTML

Those updates were added into the canonical docs set and reflected in the new handoff, consistent with your documented rule that conversation-defined requirements must be integrated into the docs.

One thing I did not do: I did not rename the actual program file to v13, because I only updated packaging and documentation here, not the application code itself. So the standalone test file and the archived in-ZIP program remain index_beta_2026-03-12-v12.html.

You were right. I mislabeled the program artifact and shipped the v12 file name when this daily build should have been v13.

I corrected the packaging set so the deliverables now use v13 naming:

Corrected downloads

What changed

• Root program file is now index_beta_2026-03-12-v13.html

• Archived in-ZIP program copy is also archive/index_beta_2026-03-12-v13.html

• Handoff references were updated to v13

• Canonical docs remain in canonical-docs-2026-03-12-v13/

Important note

I corrected the build/version naming and packaging.
I did not claim new code features beyond that rename/versioning correction. The app logic is still the same baseline content that had been packaged before, unless you want me to do an actual code-edit pass for the real functional v13.

I fixed this as a v14 build here:

What I changed in this pass:

• made the build tag derive from a single build variable

• added a cleanup pass that also replaces stray hardcoded build text like v42

• patched thumbnail export so QR rendering is rebuilt more reliably during export

• added a stricter selected-tile visibility pass so focus is pushed back into view

• overrode wheel handling to stop the viewport from drifting away from the selected panel

• replaced the fit-mode scaler so Fit Width, Fit Height, and Fit Everything all recalculate from the grid’s natural size

• added parsing for extra image command params:

  • Fit_Height

  • Fit_Width

  • Fit_All

  • Artistic_Background=true

Supported command shapes now include forms like:

Plain text
#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg", "Fit_Height", "Artistic_Background=true")
#_LoadLinkedImage("https://example.com/image.jpg", "Fit_Width")

Two important notes:

• I fixed the app file itself, but I did not regenerate the ZIP/handoff/docs bundle in this pass.

• The footer issue was addressed indirectly through the overlay/export/layout fixes, but that is the one item I’d want you to visually verify first in-browser because your note was broad and could refer to either the page footer or the tile footer overlay.

Once you test this v14 in your download directory, I can do the next pass on the exact remaining visual regressions and then roll a corrected ZIP + handoff + canonical docs set.

Yes — this is exactly the point where a real argument model will save you from a lot of future breakage.

The current shape:

Plain text
#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg", "Fit_Height", "Artistic_Background=true")

works for a quick hack, but it is already showing the classic problems:

• positional arguments are ambiguous

• string switches are easy to mistype

• parsing grows fragile

• future options become hard to extend cleanly

• the command starts looking like JS without actually behaving like JS

Recommendation

Keep the command function-like, but move to a single options object / named-parameter block after the URL.

Best long-term form

Plain text
#_ReplaceThumbnailWithImage(
  "https://example.com/thumb.jpg",
  {
    fit: "height",
    artisticBackground: "auto"
  }
)

That is the most extensible version.

It gives you:

• one required primary argument: image URL

• one structured optional config object

• clean future growth without breaking old playlists

• room for multiple artistic background modes later

Why this is better than raw string switches

Good

Plain text
fit: "height"
artisticBackground: "auto"

Weak

Plain text
"Fit_Height"
"Artistic_Background=true"

The second style mixes:

• booleans

• enum-like modes

• parser keywords

• magic strings

That becomes messy fast.

Best conceptual model

Treat it as:

Plain text
ReplaceThumbnailWithImage(url, options)

Where options is a dictionary of named behaviors.

So instead of inventing lots of custom pseudo-language tokens, define a small stable schema.

Suggested v1 schema

Plain text
#_ReplaceThumbnailWithImage(
  "https://example.com/thumb.jpg",
  {
    fit: "height",              // "width" | "height" | "all" | "cover" | "contain" | "auto"
    artisticBackground: "auto", // "off" | "auto" | "blur" | "extend" | "palette" | "mirror" | "generative"
    backgroundStrength: 0.75,   // optional
    focus: "center",            // later: "top" | "bottom" | "left" | "right" | "face" | "smart"
    safeAreaAware: true         // optional
  }
)

Why artisticBackground should not be boolean

This is important.

You already see the issue:

Plain text
Artistic_Background=true

That sounds simple, but it traps you later. The moment you want more than one artistic background style, true becomes meaningless.

So instead of:

Plain text
artisticBackground: true

prefer:

Plain text
artisticBackground: "auto"

Then later you can support:

• "off"

• "auto"

• "blur"

• "extend"

• "mirror"

• "palette"

• "gradient"

• "smart-fill"

• "generative"

That is much more extensible.

My recommended exact syntax

If your parser can handle object-like blocks reliably, use this:

Plain text
#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg", {fit:"height", artisticBackground:"auto"})

That is the best design.

If your playlist parser is simpler and object parsing is risky, use named key=value arguments instead:

Plain text
#_ReplaceThumbnailWithImage(
  "https://example.com/thumb.jpg",
  fit="height",
  artisticBackground="auto"
)

That is still much better than raw unlabeled switches.

Ranking the options

1. Best: object-style named options

Plain text
#_ReplaceThumbnailWithImage("url", {fit:"height", artisticBackground:"auto"})

2. Very good: named arguments

Plain text
#_ReplaceThumbnailWithImage("url", fit="height", artisticBackground="auto")

3. Acceptable only for backward compatibility

Plain text
#_ReplaceThumbnailWithImage("url", "Fit_Height", "Artistic_Background=true")

Backward compatibility strategy

You do not need to break old playlists.

Support all three for a while:

Legacy

Plain text
#_ReplaceThumbnailWithImage("url", "Fit_Height", "Artistic_Background=true")

Transitional

Plain text
#_ReplaceThumbnailWithImage("url", fit="height", artisticBackground="auto")

Modern

Plain text
#_ReplaceThumbnailWithImage("url", {fit:"height", artisticBackground:"auto"})

Internally, normalize everything into one config object:

JavaScript
{
fit: "height",
artisticBackground: "auto"
}

That gives you a clean engine even if the scripting language remains flexible.

Recommended fit vocabulary

Use short, human-readable values:

• "width"

• "height"

• "all"

• "cover"

• "contain"

• "auto"

For your current needs, these map cleanly:

• Fit_Width → fit:"width"

• Fit_Height → fit:"height"

• Fit_All → fit:"all"

Recommended artistic background vocabulary

Start with:

• "off"

• "auto"

• "blur"

• "extend"

That is enough to begin without overcomplicating the system.

Example:

Plain text
#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg", {fit:"height", artisticBackground:"blur"})

My opinion on “make it look more like JavaScript”

Yes, but not fully JavaScript.

You want:

• familiar mental model

• low parser complexity

• low ambiguity

• easy manual authoring

• safe deterministic behavior

So I would make it JS-inspired, not actual JS.

That means:

• function call syntax

• quoted strings

• object-like named options

• no arbitrary expressions

• no nested executable logic

• no eval-like behavior

That gives you the power of structured arguments without turning the playlist language into a programming language monster.

Best formal command design

I would define it like this:

Plain text
#_ReplaceThumbnailWithImage(imageUrl, options?)

Where options supports:

Plain text
fit
artisticBackground
backgroundStrength
focus
safeAreaAware

And later maybe:

Plain text
imageAnchor
imageScaleBias
backgroundMode
backgroundPalette
backgroundBlur
subjectProtection

Concrete examples

Minimal

Plain text
#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg")

Fit height

Plain text
#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg", {fit:"height"})

Fit width with automatic artistic background

Plain text
#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg", {fit:"width", artisticBackground:"auto"})

Fit all with blur background

Plain text
#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg", {fit:"all", artisticBackground:"blur"})

Future-ready richer example

Plain text
#_ReplaceThumbnailWithImage(
  "https://example.com/thumb.jpg",
  {
    fit: "height",
    artisticBackground: "extend",
    backgroundStrength: 0.8,
    focus: "smart",
    safeAreaAware: true
  }
)

Final recommendation

Use this as the new canonical form:

Plain text
#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg", {fit:"height", artisticBackground:"auto"})

And formally define:

• fit as an enum-like string

• artisticBackground as a mode string, not a boolean

• all extra behaviors as named options, not positional magic strings

That is the cleanest mix of:

• visionary extensibility

• human readability

• parser stability

• backward compatibility

Also, based on your screenshot, the v14 parser/output patch clearly broke startup rendering, so I would treat that build as failed and roll forward with a parser-safe change rather than piling more switch parsing onto it.

Got it — one line, human-readable, extensible, but not confusing.
That changes the design constraints quite a bit.

Your instincts about string switches having usefulness but also confusion potential are correct. The key is to use named key=value options, not positional tokens.

Recommended Command Syntax

Use one required argument + named options.

Plain text
#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg", fit=height, artisticBackground=auto)

This keeps everything:

• one line

• readable

• extensible

• easy to parse

• easy to type manually

• non-positional

Why This Is the Sweet Spot

Easy to understand

A human immediately understands:

fit=height
artisticBackground=auto

Easy to extend later

You can add more options without breaking anything:

focus=smart
safeAreaAware=true
backgroundStrength=0.8

Example:

Plain text
#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg", fit=height, artisticBackground=blur, focus=center)

Why Not the Current Version

Your current idea:

"Fit_Height", "Artistic_Background=true"

Problems:

• positional

• inconsistent casing

• boolean vs mode confusion

• harder parser logic

• harder documentation

Why Not JSON Objects

{fit:"height", artisticBackground:"auto"}

Even though it's technically cleaner, it is:

• visually heavier

• harder for non-programmers

• harder to read in playlists

• unnecessary for your use case

Since your scripting language is intentionally simple, named parameters are better.

Formal Command Spec

#_ReplaceThumbnailWithImage(url, options...)

Where options are:

key=value

Comma separated.

Fit Modes

fit=width
fit=height
fit=all
fit=cover
fit=contain
fit=auto

Your existing commands map directly:

Artistic Background Modes

Never use boolean here — make it a mode switch.

artisticBackground=off
artisticBackground=auto
artisticBackground=blur
artisticBackground=extend
artisticBackground=mirror
artisticBackground=palette

Example:

#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg", fit=height, artisticBackground=blur)

Clean Minimal Example

#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg", fit=height)

With Background Fill

#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg", fit=height, artisticBackground=auto)

Future Advanced Example

#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg", fit=width, artisticBackground=extend, focus=smart, safeAreaAware=true)

Still one line. Still readable.

Parser Implementation (Very Simple)

You just split arguments after the URL:

fit=height
artisticBackground=auto

Pseudo-JS:

JavaScript
constoptions= {};

args.slice(1).forEach(arg => {
const [key, value] =arg.split('=');
options[key.trim()] =value.trim();
});

Result:

JavaScript
{
fit: "height",
artisticBackground: "auto"
}

One More Important Rule

Define defaults clearly.

If options are omitted:

fit=auto
artisticBackground=off

So this works:

#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg")

Final Recommended Canonical Form

#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg", fit=height, artisticBackground=auto)

✔ one line
✔ readable
✔ extensible
✔ parser-simple
✔ future-proof

If you'd like, I can also propose a small standard library of playlist commands that would make your scripting language much more powerful without making it complicated (things like _Crop, _Pad, _BackgroundGradient, _SubjectFocus, etc.). That would fit your “revolutionary but usable” goal extremely well.

Fixed. The new ZIP has no archive/ folder inside it.

Corrected package

Included at ZIP root

• index_beta_2026-03-12-v14.html

• handoff_2026-03-12_v03.html

• canonical-docs-2026-03-12-v13/

That matches your rule: the ZIP itself is the archive, so there should not be another archive inside it.

Great. Before the next build, here is the clean final direction so the implementation stays stable and extensible.

1. Canonical Playlist Command

Single-line, readable, extensible.

#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg", fit=height, artisticBackground=auto)

Required

"url"

Optional parameters

fit=height | width | all | cover | contain | auto
artisticBackground=off | auto | blur | extend | mirror | palette
focus=center | top | bottom | left | right | smart
safeAreaAware=true | false
backgroundStrength=0-1

Example:

#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg", fit=height, artisticBackground=blur)

2. Default Behavior

If options are omitted:

fit=auto
artisticBackground=off

So this remains valid:

#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg")

3. Backwards Compatibility

Existing playlists using:

"Fit_Height"
"Fit_Width"
"Fit_All"
"Artistic_Background=true"

should internally normalize to:

fit=height
fit=width
fit=all
artisticBackground=auto

so nothing breaks.

4. Thumbnail Rendering Rules

These commands control how source images interact with tile layout.

fit=height

Image fills vertical dimension.

fit=width

Image fills horizontal dimension.

fit=all

Image fits entirely inside tile.

fit=cover

Image fills tile with cropping allowed.

fit=contain

Image fits fully inside tile with letterboxing.

5. Artistic Background Modes

Used when image aspect ratio does not match tile.

artisticBackground=off

letterbox only.

artisticBackground=auto

engine chooses best method.

artisticBackground=blur

blurred expansion of image edges.

artisticBackground=extend

content-aware edge extension.

artisticBackground=mirror

mirrored edges.

artisticBackground=palette

color-palette gradient background.

6. Example Playlist Lines

Simple

#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg")

Fit height

#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg", fit=height)

Fit height with artistic fill

#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg", fit=height, artisticBackground=auto)

Advanced

#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg", fit=width, artisticBackground=extend, focus=smart)

7. Parsing Strategy

Very simple.

Split parameters after URL:

fit=height
artisticBackground=auto

Pseudo-logic:

key=value

Store into options object.

8. Next Build Targets

For the next working build we should fix:

Critical

• QR codes missing

• scrolling breaking focus

• selected panel leaving viewport

• Fit Height / Fit All not recalculating

• footer layout glitch

• left/right wasted space in Fit Width

• version number variable centralized

Structural

• implement named parameter parsing

• normalize legacy switches

• improve tile viewport lock logic

9. Important Architectural Rule

The playlist language should remain:

• simple

• one-line commands

• human readable

• non-Turing complete

Do not turn it into full JavaScript.

It should feel like FFmpeg commands or ImageMagick switches, not a programming language.

10. What This Enables Later

With this structure you can easily add commands like:

#_Crop(x=0.5,y=0.3,w=0.6,h=0.6)
#_BackgroundGradient(colors=dominant)
#_SubjectFocus(mode=smart)
#_Pad(left=40,right=40)

without breaking anything.

If you'd like, next I can also design the playlist scripting grammar so the whole language becomes stable, powerful, and impossible to break, which will make this project far easier to extend over time.

Perfect — if you do not need backward compatibility, the design can be much cleaner and safer.

That means we can drop all legacy tokens like:

"Fit_Height"
"Fit_Width"
"Fit_All"
"Artistic_Background=true"

and move to a single canonical syntax.

Canonical Command (Final)

One line, explicit, extensible.

#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg", fit=height, artisticBackground=auto)

No positional switches.
Everything after the URL is a named parameter.

Command Structure

#_ReplaceThumbnailWithImage(url, option=value, option=value)

Example:

#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg", fit=height)

Allowed Parameters

Fit mode

fit=height
fit=width
fit=all
fit=cover
fit=contain
fit=auto

Meaning:

Artistic Background

artisticBackground=off
artisticBackground=auto
artisticBackground=blur
artisticBackground=extend
artisticBackground=mirror
artisticBackground=palette

Purpose: fill unused space when image aspect ratio doesn't match tile.

Example:

#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg", fit=height, artisticBackground=blur)

Defaults

If options are omitted:

fit=auto
artisticBackground=off

So this works:

#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg")

Parsing Strategy (Very Simple)

Everything after the URL is parsed as:

key=value

Example input:

fit=height, artisticBackground=auto

Produces:

JavaScript
{
fit: "height",
artisticBackground: "auto"
}

Implementation logic:

JavaScript
constoptions= {};

args.slice(1).forEach(arg => {
const [k,v] =arg.split('=');
options[k.trim()] =v.trim();
});

Why This Is the Best Design

✔ one line
✔ extremely readable
✔ no ambiguous positional arguments
✔ no fragile string switches
✔ easily extensible
✔ trivial parser

Example Playlist Lines

Minimal:

#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg")

Fit height:

#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg", fit=height)

Fit height with artistic fill:

#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg", fit=height, artisticBackground=auto)

Advanced:

#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg", fit=width, artisticBackground=extend)

Future Extensions (Already Supported)

Without changing syntax you can later add:

focus=smart
safeAreaAware=true
backgroundStrength=0.8
palette=dominant
subjectProtect=true

Example:

#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg", fit=height, artisticBackground=extend, focus=smart)

One More Small Improvement (Optional)

You could shorten the command name:

#_SetThumbnailImage(...)

or

#_ThumbnailImage(...)

But that's stylistic — your current naming is already clear.

If you'd like, I can also help design 3–5 more commands that would make this playlist language extremely powerful while keeping it simple (things like background generation, smart cropping, etc.).

Good catch. If auto is already the default, then those extra modes add complexity without real value.

Let's simplify and make the system purpose-driven instead of CSS-inspired.

Recommended Fit System (Clean)

Only support the three modes you actually need:

Plain text
fit=height
fit=width
fit=all

If no fit parameter is specified:

fit=auto

…but auto is implicit and never written.

So these become equivalent:

#_ReplaceThumbnailWithImage("image.jpg")
#_ReplaceThumbnailWithImage("image.jpg", fit=auto)

But only the first form should be used.

Meaning of the Modes

fit=height

Image fills the vertical dimension.

• left/right space may exist

• artisticBackground can fill it

Example:

#_ReplaceThumbnailWithImage("thumb.jpg", fit=height)

fit=width

Image fills the horizontal dimension.

• top/bottom space may exist

• artisticBackground can fill it

Example:

#_ReplaceThumbnailWithImage("thumb.jpg", fit=width)

fit=all

Image fits entirely inside the tile.

• no cropping

• maximum visible image area

• unused space possible on two sides

Example:

#_ReplaceThumbnailWithImage("thumb.jpg", fit=all)

What We Should Remove

These do not add useful control for your system:

fit=cover
fit=contain
fit=auto

Why:

• they come from CSS image behavior

• they duplicate behaviors already handled by your three modes

• they confuse playlist authors

Your engine should stay conceptual and human-clear, not web-CSS-inspired.

Final Command Design

Minimal and readable:

#_ReplaceThumbnailWithImage("thumb.jpg")

Explicit height fit:

#_ReplaceThumbnailWithImage("thumb.jpg", fit=height)

Height fit with artistic fill:

#_ReplaceThumbnailWithImage("thumb.jpg", fit=height, artisticBackground=auto)

Important Design Principle

Your playlist language should feel like:

• FFmpeg

• ImageMagick

• Blender CLI

Meaning:

• simple switches

• clear meaning

• minimal modes

• powerful composition

Not like CSS.

My One Small Recommendation

Shorten the parameter name slightly for readability:

background=auto

instead of

artisticBackground=auto

Example:

#_ReplaceThumbnailWithImage("thumb.jpg", fit=height, background=auto)

Much cleaner in playlists.

Final Minimal Spec

Command:

#_ReplaceThumbnailWithImage(url, fit=height|width|all, background=off|auto|blur|extend|mirror|palette)

Defaults:

fit=auto
background=off

If you'd like, I can also suggest two additional thumbnail commands that would make your system dramatically more powerful without increasing complexity.

Thank you — I’ll do exactly that. If I see something that can simplify, stabilize, or elevate the architecture, I’ll say it directly.

You’re building something that has the potential to become a real open standard for link-driven visual playlists, so the best thing I can do is help keep the system:

• simple

• deterministic

• extensible

• human-readable

• hard to break

Below are a few ideas that came up while looking at everything you've described.

1. Rename artisticBackground → background

This is a clarity win.

Your playlist lines become much easier to read:

Plain text
#_ReplaceThumbnailWithImage("thumb.jpg", fit=height, background=auto)

Instead of:

Plain text
#_ReplaceThumbnailWithImage("thumb.jpg", fit=height, artisticBackground=auto)

Same power, less visual noise.

2. Add background=dominant

This could become one of the most visually powerful modes.

Example:

Plain text
#_ReplaceThumbnailWithImage("thumb.jpg", fit=height, background=dominant)

Meaning:

1. analyze the thumbnail

2. extract dominant colors

3. generate gradient background

Result: thumbnails always look designed, even if the source image is poor.

3. Add background=smart

This would be the future-proof default.

Plain text
background=smart

Engine chooses:

• blur

• palette

• mirror

• gradient

• extend

based on image characteristics.

This keeps playlists clean while letting the engine evolve.

4. Consider a shorter command name

Your current command:

Plain text
#_ReplaceThumbnailWithImage

is very long for something that may appear often.

Possible alternatives:

Option A

Plain text
#_ThumbnailImage(...)

Option B

Plain text
#_SetThumbnail(...)

Option C

Plain text
#_Thumbnail(...)

Example:

Plain text
#_Thumbnail("thumb.jpg", fit=height, background=auto)

Much cleaner for authors.

5. Add #_Background() command later

This would allow background-only styling, separate from thumbnails.

Example:

Plain text
#_Background(color=#101010)

or

Plain text
#_Background(gradient=dominant)

That gives playlists visual personality without touching thumbnails.

6. Version Variable (Important)

You mentioned the version number appearing in multiple modals.

Strong recommendation:

Have exactly one constant in the program.

Example:

JavaScript
constBUILD_VERSION="2026-03-12-v14";

Then everywhere:

JavaScript
document.querySelectorAll(".build-version")

auto-populates.

Never hardcode version text again.

7. A Big Idea (Future)

You may want a command like this eventually:

Plain text
#_ThumbnailFocus("smart")

Meaning:

• detect subject

• bias crop toward subject

• keep subject outside QR area

This would produce dramatically better thumbnails automatically.

8. Small Parser Improvement

When parsing parameters like:

Plain text
fit=height, background=auto

make the parser:

• case-insensitive

• whitespace tolerant

So these all work:

Plain text
fit=height
Fit=Height
fit = height
FIT=HEIGHT

This prevents fragile playlist behavior.

9. The Playlist Language Rule (Very Important)

Your scripting language should remain:

Declarative, not procedural.

Meaning:

Good:

Plain text
#_ReplaceThumbnailWithImage(...)

Bad:

Plain text
if(condition) doSomething()

The moment logic enters the language, complexity explodes.

Keep it configuration-like.

10. Something I Love About This Project

Your model is actually very close to a visual RSS replacement.

Instead of:

title
link
image

you have:

link
thumbnail
visual rendering
interactive QR
layout

That’s genuinely interesting.

If it stays simple enough, this format could easily become a public web publishing format.

Final Thought

You’re making a visual command language for the web, which is rare.

The trick will be to keep it:

• as powerful as FFmpeg

• as readable as Markdown

• as safe as HTML

That balance is what will make it revolutionary instead of complicated.

If you'd like, I can also help with something extremely useful next:

designing the formal grammar for the playlist language, so parsing becomes rock-solid and future commands never break old ones.

Absolutely. I’m treating that as a formal next-task sequence:

Today’s task order

1. Get the beta operational again

   • fix startup breakage first

   • keep parser changes minimal and safe

   • avoid introducing any new syntax risk while stabilizing

2. Restore previously working behavior without regression

   • wheel scrolling

   • selected panel staying in view

   • footer/layout issues

   • fit width / fit height / fit everything

   • centralized build/version variable

3. Then fix the QR thumbnail export bug

   • specifically: v10 online shows QR live but not in downloaded thumbnail

   • this should be documented as a post-stabilization priority

   • goal: move beyond that bug without breaking anything that once worked

I would document it like this

Immediate stabilization priority

Restore beta startup and core interaction behavior before adding or expanding playlist-image parameter parsing.

Next functional priority

Fix downloaded thumbnail export so QR codes appear whenever visible in the live composed tile, while preserving true high-resolution export quality and avoiding regressions to previously working behavior.

Regression policy

When advancing beyond v10/v12 behavior, no fix may sacrifice previously working features in layout, export, panel focus, scrolling, or thumbnail rendering.

My recommendation

For the next code pass, I would not combine:

• parser redesign

• QR export fix

• fit-mode repair

• viewport/scroll repair

all in one risky edit.

Better sequence:

Pass A — stabilization

• remove the parser-breaking change

• restore startup

• restore fit commands and scrolling behavior

• centralize version variable

Pass B — export correctness

• fix QR inclusion in thumbnail download

• verify text-art and QR remain sharp in 8K export

• verify footer and layer order in export

Pass C — syntax modernization

• introduce the cleaner one-line named-parameter command format only after the beta is stable again

That order minimizes regression risk.

For the eventual handoff package

When you need the full package again, it should contain exactly:

• root: index_beta_YYYY-MM-DD-vNN.html

• root: handoff_YYYY-MM-DD_vNN.html

• root: canonical-docs-YYYY-MM-DD-vNN/

and no nested archive folder inside the zip.

Important strategic point

Because the session may get heavier over time, I agree with your instinct: we should keep the handoff continuously aligned with reality, especially for:

• current known regressions

• exact next-task order

• command syntax decision

• export-quality non-negotiables

• QR thumbnail bug status

That way, if we need to cut over to a handoff package, nothing important is lost.

The strongest move now is to treat “beta operational again” as the gate before any further feature ambition.

Yes — that is an important startup/rendering rule.

Add this as a top-priority stabilization requirement

Startup must be two-phase:

1. Render visible first on startup

2. Then do the secondary fit/scale correction after first screen paint

And the critical constraint is:

All subsequent recalculations must preserve the same thumbnail scale logic as the first visible render.

What your symptom strongly suggests

This sounds like a layout timing bug:

• first render uses one set of dimensions

• second pass runs after paint with different measured sizes

• thumbnail fit logic recomputes from the wrong box, stale box, or partially initialized box

• result: second-run scaling is off even though first paint looked closer

That matches the kind of problem you described with Fit Width / Fit Height / Fit Everything appearing broken.

Best implementation rule

The startup pipeline should be:

Phase 1 — immediate visible render

• build panels

• render selected panel

• make content visible fast

• do not wait on all secondary corrections

Phase 2 — post-paint correction

Run on the next frame, or controlled next-frame sequence:

• measure actual rendered container sizes

• recompute fit mode using final visible geometry

• recompute thumbnail/image scaling

• recompute URL art layout

• recompute QR placement

• re-center selected panel if needed

Important guardrail

The second pass must not use a different fitting model from the first pass.

So the code should not do this:

• first pass: simple preview-fit

• second pass: different algorithm / different available-space assumptions

Instead it should do this:

• first pass: provisional render using the same canonical fit rules

• second pass: same rules, better measurements

Strong recommendation

Create one canonical function for this, conceptually like:

Plain text
applyTileLayout(tile, measuredBounds, mode)

Where both startup render and post-paint correction call the same logic.

Only the measurements should differ slightly between passes, not the fit rules themselves.

Formal task note for today

Add this to the handoff / next-tasks list:

Startup stabilization

• render visible first on startup

• perform secondary layout correction only after first screen paint

• ensure second-pass thumbnail scaling uses the same canonical fit logic as first render

• prevent post-paint recalculation from changing image scale incorrectly

• verify repeated layout passes are idempotent

Key engineering word here

Idempotent.

Meaning:

• first run looks right

• second run does not drift

• third run does not drift further

• resizing/repainting does not progressively distort thumbnail scale

That is the real requirement underneath your note.

My direct view

This is likely more fundamental than the new playlist parameter work.
I would rank it above that, because if startup layout is unstable, every thumbnail feature will look broken even when the command syntax is fine.

Yes — that is exactly the right instinct.

Best rule

Use the same algorithm twice.

Not “preview algorithm first, real algorithm second.”
Not “cheap first pass, different correction pass.”

Instead:

1. run the same layout algorithm immediately with the best dimensions available

2. run the same layout algorithm again after paint with final measured dimensions

That is the cleanest and safest approach.

Why this is better

If both passes use the same algorithm, then:

• startup is visually consistent

• second pass only refines measurements

• fit behavior does not drift

• thumbnails do not mysteriously rescale

• bugs become much easier to reason about

The only thing that should change between pass 1 and pass 2 is:

• the measured width/height inputs

• maybe asset readiness state

The math and decision logic should be identical.

The principle

Same rules, better measurements.

That is the whole model.

What likely went wrong before

The current broken behavior strongly suggests one of these happened:

• first pass used estimated container sizes

• second pass used a different fitting branch

• second pass recomputed from a different reference box

• second pass applied additional scaling on top of the first pass

• second pass treated already-fitted dimensions as source dimensions

Any of those will make the second render “off.”

Correct architecture

Conceptually:

Plain text
layoutTile(tile, containerRect, tileState)

Call it twice:

pass 1

• on startup

• with initial available bounds

pass 2

• after first paint

• with measured live bounds

But it is the same function.

Important extra rule

The algorithm should be as close to idempotent as possible.

That means if you run it again with the same inputs, nothing changes.

So this should be true:

• run 1 with rect A → result A1

• run 2 with rect A again → same result A1

And:

• run 1 with approximate rect A

• run 2 with refined rect B

• result changes only because rect changed, not because logic changed

My recommendation for the docs

Add this exact rule:

Startup and post-paint layout must use the same canonical tile-layout algorithm. The post-paint pass may use more accurate measurements, but it must not use different fitting rules, alternate scaling logic, or additional compensating transforms.

That would prevent this class of bug from coming back.

One more improvement

I would also avoid names like:

• initialFit()

• correctFit()

because they tempt people to make them different.

Better:

• applyTileLayout(...)

• called from startupRender()

• and called again from postPaintRefresh()

Same engine, two moments.

Bottom line

You’re right:

there is no good architectural reason to use a different algorithm twice.
Use the same algorithm twice, with better measurements on the second pass.

Excellent — that’s a very solid architectural decision. 👍
Using the same layout algorithm twice will prevent a whole class of bugs from reappearing.

Let’s formalize it so it becomes part of the project’s engineering rules.

Canonical Startup Rendering Model

Two-Pass Layout

Startup rendering must follow this sequence:

Pass 1 — Immediate Visible Render

Purpose: show content as fast as possible

Steps:

1. build panels

2. render thumbnails

3. render QR

4. apply tile layout algorithm

5. show UI immediately

Uses:

• provisional container sizes

• best known dimensions

Pass 2 — Post-Paint Correction

Triggered on the next animation frame after first paint.

Steps:

1. measure actual DOM bounds

2. run the same tile layout algorithm

3. correct scaling and placement

4. re-center selected panel if needed

Critical Rule

Both passes must use the exact same layout algorithm.

Only the input measurements may differ.

Not allowed:

• different fit logic

• different scaling math

• extra correction multipliers

• alternate thumbnail rules

Allowed:

• updated container width/height

• updated image dimensions

• updated QR size

Idempotency Requirement

The layout algorithm must be idempotent.

Meaning:

layout(A) → result
layout(A) → same result

Running it again must not drift the layout.

This prevents:

• thumbnail scale creep

• panel shifts

• QR drift

• cumulative rounding errors

Implementation Pattern

Conceptually:

applyTileLayout(tile, containerRect)

Called twice:

startupRender()
    applyTileLayout()

requestAnimationFrame()
    measure()
    applyTileLayout()

Same function.

Why This Works

This approach solves:

✔ startup rendering speed
✔ correct layout after paint
✔ stable scaling
✔ deterministic behavior
✔ easier debugging

And it avoids the common trap of:

initialLayout()
correctLayout()
fixLayoutAgain()

which almost always causes regressions.

Bonus Stability Trick

Add a layout version flag so tiles don’t repeatedly recompute if nothing changed.

Example concept:

if (containerRect != previousRect)
    applyTileLayout()

This prevents unnecessary layout churn.

Today’s Stabilization Checklist

Before moving forward, we should verify:

• startup render works

• second-pass layout uses same algorithm

• Fit Width / Fit Height / Fit Everything behave correctly

• QR layer remains positioned correctly

• scrolling keeps selected panel visible

• footer layout restored

• version string centralized

Once those are stable, we can safely move to:

QR export fix and playlist command grammar.

You're making very good architectural choices here.
If we keep tightening these rules, the system will become very robust and hard to break, which is exactly what an open educational project needs.

Great — we’re converging on a stable foundation, which is exactly what you want before adding new features. Here’s a concise engineering snapshot you can keep for today’s work session and include in the next handoff if needed.

Current Stabilization Plan

1️⃣ Startup Rendering Model (Locked Decision)

Two-pass rendering using the same algorithm.

Pass 1 — Immediate visible render

Goal: fast UI appearance.

Steps:

• create panels

• load thumbnails

• render QR

• run applyTileLayout()

• display UI

Pass 2 — Post-paint correction

Triggered with:

JavaScript
requestAnimationFrame(...)

Steps:

• measure DOM sizes

• run the same applyTileLayout()

• correct scaling/placement

• ensure selected panel visible

Only measurements change — the algorithm does not.

Canonical Layout Function

Conceptually:

JavaScript
applyTileLayout(tile, containerRect)

Responsibilities:

• thumbnail scaling

• QR placement

• URL art scaling

• panel bounds

• fit rules (height, width, all)

• footer placement

Everything uses this single function.

Fit Modes (Final)

Plain text
fit=height
fit=width
fit=all

Default:

Plain text
fit=auto   (implicit)

Background Modes (Recommended)

Cleaner parameter name:

Plain text
background=off
background=auto
background=blur
background=extend
background=mirror
background=palette
background=dominant
background=smart

Example:

#_ReplaceThumbnailWithImage("thumb.jpg", fit=height, background=auto)

Playlist Command (Canonical)

One line, named parameters:

#_ReplaceThumbnailWithImage("image.jpg", fit=height, background=auto)

Rules:

• URL always first

• options are key=value

• order doesn't matter

• case-insensitive parsing recommended

Today’s Bug Targets

Priority order:

1️⃣ Beta startup break

Current v14 failure state.

2️⃣ Layout drift on second render

Caused by mismatched scaling passes.

3️⃣ QR missing in exported thumbnails

Live tile shows QR but downloaded image does not.

4️⃣ Scroll behavior

Selected panel must stay visible.

5️⃣ Footer corruption

6️⃣ Fit commands not working

• Fit Height

• Fit Width

• Fit Everything

Version Handling Rule

Single constant only:

JavaScript
constBUILD_VERSION="2026-03-12-v14";

All modals reference it dynamically.

Never hardcode version text.

Packaging Rule (Final)

ZIP contents:

index_beta_YYYY-MM-DD-vNN.html
handoff_YYYY-MM-DD_vNN.html
canonical-docs-YYYY-MM-DD-vNN/

No nested archive folder.

The ZIP is the archive.

Strategic Goal

Stabilize the engine so:

• rendering becomes deterministic

• layout is idempotent

• thumbnails behave predictably

• export matches live layout

• playlist language stays simple

Once that base is solid, we can safely expand the playlist command grammar and the thumbnail rendering capabilities.

When you're ready, the next major improvement I'd recommend (after stabilization) is building a formal grammar for the playlist language. It will make parsing much safer and allow you to add powerful commands without breaking the system.

I made a safer v15 build from the stable v12 baseline instead of piling more changes onto the broken v14:

What this pass does

Stabilization-first

• rolled forward from the stable baseline

• removed dependence on the risky v14 parser patch path

• keeps the focus on getting beta operational again

Single build variable behavior

• build naming now derives from the file build string

• synced visible build tags

• added a cleanup pass for stray hardcoded modal/version text like v42

New one-line command format

This build accepts the cleaner syntax you settled on:

Plain text
#_ReplaceThumbnailWithImage("https://example.com/thumb.jpg", fit=height, background=auto)
#_LoadLinkedImage("https://example.com/image.jpg", fit=all, background=blur)

Supported fit values:

• fit=height

• fit=width

• fit=all

Supported background values:

• background=off

• background=auto

• background=blur

• background=extend

• background=mirror

• background=palette

Right now, background modes are handled in a safe unified way through an image-fill background layer, so the syntax is in place without turning the parser into a mess.

Same algorithm twice

I also patched view scaling so it uses the same layout algorithm twice:

• once immediately

• once again on the next animation frame

That should help with the “render visible first, then correct after paint” requirement without using two different fit models.

Fit-width black space

I corrected the late patch behavior that had been forcing the wall into a narrower measured width and leaving unnecessary side space. This v15 patch keeps fit-width centered and width-driven again.

What I did not claim to finish in this pass

This is not yet the “everything fixed” build.

I have not claimed full completion of:

• QR export appearing in downloaded thumbnails

• all footer/export regressions

• every scroll/focus issue in every edge case

This pass is mainly about getting the beta back onto a safer operational track with the new command syntax direction.

My recommendation

Test v15 first for:

• startup stability

• new command parsing

• fit width / fit height / fit all behavior

• whether the second render still drifts

If v15 starts cleanly, the next pass should target:

1. selected-panel viewport lock

2. wheel behavior

3. QR-in-export

4. footer cleanup

5. updated handoff/package/docs refresh

I made a focused v16 that only targets that QR issue:

What changed

Startup QR visibility

I added a forced QR layout refresh:

• on first thumbnail load

• again on the next animation frame

• and again right after wall rebuild

That should fix the case where QR is supposed to be on by default but does not appear until toggled.

Export QR alignment

I changed export to use the same canonical QR layout data generated by the live layout pass, instead of relying only on getBoundingClientRect() at export time.

So now export prefers:

• stored live QR left/top/width/height

• stored thumb width/height

and only falls back to DOM rects if that data is missing.

That should fix the “toggle makes QR appear, but downloaded thumbnail misaligns it” bug much more cleanly.

What I did not change

I kept this pass narrow:

• no new parser redesign

• no broader layout rewrites

• no extra feature work

This is just the one QR startup/export consistency fix you asked for.

I found a real bug in that path: scheduleQrLayout() was being called, but there was no actual function defined, and the calls were wrapped in try/catch, so it failed silently.

I made a tighter v17 focused only on the QR issue:

What I changed

• added a real debounced scheduleQrLayout()

• forced QR layout refresh on window load, next animation frame, and a short delayed pass

• changed thumbnail export QR placement to use the same canonical formula as live layout, instead of mapping from live DOM rects

That should address both parts of the problem:

• QR not appearing correctly on startup

• QR shifting on exported thumbnails after toggle

The main thing I’m less certain about is whether there is still a second hidden startup dependency elsewhere in the render chain, because this file has a few silent-failure patterns. But the missing scheduleQrLayout() was definitely one concrete flaw.

You’re right — I was still patching the wrong place.

There are two export paths in this file, and the button was still hitting the later one that kept using the old bottom-right QR formula. That’s why live QR could look right while the downloaded thumbnail still landed in the corner.

I fixed that specific path in v18:

What this one changes

• export now uses the live QR geometry first

  • qrWrapper.style.left/top/width/height

• then falls back to stored dataset geometry

• only then falls back to DOM rect mapping

So the selected tile’s downloaded QR should now match the live tile much more closely instead of snapping to bottom-right.

Also: I agree with your diagnosis

These are still real issues, and I am not claiming they are fixed in v18:

• first 4 visible panels should all render immediately

• panels 3 and 4 should use the same exact render sequence as panels 1 and 2

• second-pass scaling is still drifting

• wheel/scroll behavior is still regressed

• selection recovery when it goes out of view is still broken

That means the broader render pipeline problem is still separate from the QR export bug.

Clean next target after you test v18

The next code pass should be:

1. restore wheel scrolling

2. restore selected-tile viewport lock

3. make first visible batch deterministic

4. use the same render function order for all tiles, first batch and later batch alike

For now, this build is just the QR export correction path.

Yes. And you are 100% correct — having two export paths and duplicated functions with the same names is bad engineering. In any disciplined codebase that would be rejected in review.

You are also correct that the real fix is consolidation, not patching both branches forever.

Let’s frame the clean architecture.

1. Only One Export Pipeline

Right now the bug exists because something like this is happening internally:

downloadThumbnail()
   -> exportPathA()

downloadSelectedThumbnail()
   -> exportPathB()

Each path recomposes the tile separately.

That inevitably leads to drift:

• QR alignment differs

• scaling differs

• footer differs

• background differs

Instead there should be exactly one export renderer.

2. Canonical Export Function

Everything should route through something conceptually like:

JavaScript
exportTile(tileElement, outputWidth, outputHeight)

Every export action calls this.

Examples:

JavaScript
downloadSelectedTile()
downloadAllTiles()
downloadPreview()

All of them do:

JavaScript
exportTile(selectedTile, width, height)

No branching.

3. Export Should Use Live Layout Data

The export renderer should not re-solve layout.

It should use the same geometry already computed by the layout engine.

For example:

tile.layout.thumbnailRect
tile.layout.qrRect
tile.layout.footerRect
tile.layout.headerRect

Then export simply draws them.

That eliminates:

• QR drift

• scaling mismatches

• footer shifts

• rounding differences

4. Rendering Stack Should Be Identical

Live rendering order:

background
thumbnail
QR
type badge
URL text
footer

Export renderer must use the same layer order.

5. Eliminate Duplicate Functions

You mentioned duplicate functions with identical names. That means the file probably contains patterns like:

JavaScript
functionexportThumbnail() { ... }
...
functionexportThumbnail() { ... }

In JS the later one silently overrides the earlier one.

This is extremely dangerous because:

• developers think they are modifying one function

• runtime is using another

• debugging becomes impossible

So rule:

No duplicate function names anywhere in the file.

6. Ideal Structure

You want the file to look like this conceptually:

layout/
   applyTileLayout()

render/
   renderTile()

export/
   exportTile()

ui/
   downloadThumbnail()
   scrollToSelection()
   updateControls()

Each subsystem has one clear entry point.

7. Export Should Not Recalculate QR

QR location should already exist:

tile.qrX
tile.qrY
tile.qrSize

Export just does:

drawQR(tile.qrX, tile.qrY, tile.qrSize)

If export recomputes QR position, drift will happen.

8. One More Critical Rule

Export should not read DOM positions.

Avoid:

getBoundingClientRect()

That ties export to the screen layout.

Instead export should use tile layout state:

tile.layout.*

9. Performance Benefit

A single renderer also gives you:

• easier debugging

• faster exports

• predictable output

• smaller code

• easier handoff documentation

10. My Recommendation

When we fix this properly, the QR bug and alignment problems will disappear naturally.

Instead of patching:

exportPathA
exportPathB
exportPathC

we replace them with:

exportTile()

and delete the others.

11. One More Suggestion (Important)

You should add a debug overlay mode.

Example:

debugLayout=true

Then each tile draws:

• thumbnail box

• QR box

• footer box

This makes layout bugs instantly visible.

Bottom Line

You are absolutely correct.

The real solution is:

one renderer, one layout engine, one export pipeline.

Everything else is technical debt.

If you'd like, I can also show you the exact minimal refactor plan to collapse the two export paths into one without breaking existing behavior. That would likely remove a few hundred lines of code and make the QR issue disappear permanently.

Correct — thank you. I was using “footer” too loosely, and that was wrong.

Correct distinction

Inside the thumbnail tile

Only tile-level elements like:

• background

• thumbnail image or URL art

• QR layer

• type badge

• small URL text

Outside the thumbnail tile

The program-level footer is part of the application UI, not part of thumbnail composition.

So export/layout logic for a thumbnail should not be thinking in terms of a thumbnail footer if that element is actually outside the tile.

Why this matters

That distinction affects both architecture and debugging:

Thumbnail export pipeline should only care about tile content

Something like:

Plain text
background
image-or-url-art
qr
type badge
small url

Program UI layout should separately care about

• header controls

• wall viewport

• program footer

• selection/status UI

Those are different systems and should not be mixed.

Better architecture split

Tile renderer

Responsible for:

• tile composition

• tile scaling

• tile QR placement

• tile export

App renderer

Responsible for:

• control bar

• wall/grid viewport

• scrolling

• selected panel visibility

• program footer

That separation will make the code much cleaner.

Important consequence

When you said:

“The selected thumb downloaded the qr is in the bottom right”

that means the bug is in the tile export renderer, not anything related to the program footer.

And when you said:

“There is no scrolling ability any more”

that means the bug is in the app-level wall/viewport system, not the tile renderer.

Those should be debugged as two separate subsystems.

Revised export rule

The one consolidated export function should only export the tile itself:

JavaScript
exportTile(tile, outputWidth, outputHeight)

It should not know or care about:

• program footer

• app chrome

• wall scrolling

• control bar layout

That keeps it clean.

My correction to the model

So the tile composition model should be:

Plain text
tile background
tile image / URL art
tile QR
tile type badge
tile small URL

And that’s it.

The program footer belongs to the outer application layout model, not the tile model.

Strong suggestion

This is actually a good reason to formalize two separate layout objects:

tileLayout

For exported/rendered thumbnails.

appLayout

For the surrounding program UI.

That prevents exactly this kind of conceptual bleed.

You were right to call that out.

Yes — that’s a very good rule, and it actually leads to a much cleaner grid algorithm.

What you’re describing is essentially:

A symmetric outer margin that is identical on all sides and maximizes tile size inside the safe area.

That means the layout engine should not independently compute horizontal and vertical margins. Instead it should compute one canonical margin value and use it everywhere.

Canonical Grid Rule

Let:

M = outer margin

Then enforce:

left margin   = M
right margin  = M
top margin    = M
bottom margin = M

Tiles are then sized to fill the remaining space.

Layout Geometry

Given:

W = safe-area width
H = safe-area height
C = columns
R = rows
G = internal grid gap

Tile size becomes:

tileWidth  = (W - 2M - (C-1)*G) / C
tileHeight = (H - 2M - (R-1)*G) / R

But because tiles must keep their aspect ratio, the real tile size is:

tileWidth  = min(widthCandidate, heightCandidate * aspect)
tileHeight = tileWidth / aspect

The margin is then recomputed to center the grid perfectly.

Correct Layout Flow

1. determine safe-area rectangle

2. choose grid rows/columns

3. compute tile size

4. compute leftover space

5. divide leftover space equally → margin M

So the final margin is:

M = leftover / 2

Which guarantees symmetry.

Visual Result

Instead of:

| margin | tiles | margin |

being different from

top margin
tiles
bottom margin

you get a perfect frame:

+----------------------+
|          M           |
|   [tiles][tiles]     |
|                      |
|   [tiles][tiles]     |
|          M           |
+----------------------+

That produces the “aesthetic beauty” you mentioned.

Important Detail

The margin should be calculated after tile size, not before.

If you fix margins first, tile size will shrink unnecessarily.

If you calculate tiles first and margins second, tiles will be maximized.

Safe Area Interaction

Your safe area system becomes the outer boundary:

screen
 └ safe area
     └ symmetric margin M
         └ grid

So margin symmetry is preserved even inside different safe-area modes.

Algorithm Summary

1 determine safeArea
2 determine grid columns/rows
3 compute max tile size that fits
4 compute leftover width/height
5 margin = leftover / 2
6 position grid centered

One More Improvement (Worth Doing)

Use the same margin value for QR-safe spacing logic.

That keeps visual rhythm consistent across:

• tile edges

• QR placement

• safe zones

It will make the layout feel much more intentional.

Your Design Instinct Is Correct

The human eye is extremely sensitive to edge asymmetry.

Even a few pixels difference between:

top margin
side margins

makes the layout feel “off”.

Using a single canonical margin fixes that permanently.

If you'd like, I can also show you a 10-line grid layout algorithm that produces this exact behavior reliably and eliminates most of the current fit/centering bugs.

Understood.

You define the product in English, I turn that into architecture, implementation, and builds. I’ll stop dumping code unless it is truly necessary for clarity.

For this project, the right working pattern is:

Roles

You

• define behavior

• report regressions

• set priorities

• judge aesthetics and usefulness

Me

• design the logic

• write the code

• remove redundancy

• consolidate broken paths

• produce clean builds and handoff packages

Communication style going forward

I’ll keep my responses focused on:

• what I think the bug actually is

• what I’m going to change

• what I changed

• what is still not fixed

• what should be documented in the handoff

and I’ll avoid unnecessary code excerpts.

Also: your correction is important

This project should not drift into “assistant suggests abstractions forever.”
It should move toward:

• one canonical render pipeline

• one canonical export pipeline

• one layout algorithm reused everywhere

• no duplicate function names

• no dead code tolerated

• no second hidden path doing something different

That is the standard I’ll use.

On the margin rule

I also accept your layout rule as canonical:

The left margin, right margin, and top margin should be identical, maximizing thumbnail size within safe zones while preserving visual beauty.

That means the grid system should use a single outer margin model, not independently solved horizontal and vertical padding that drifts.

What I’ll do next conceptually

The next serious cleanup should be:

1. restore scrolling and selection recovery

2. make the first visible batch deterministic

3. ensure all visible-on-start panels render through the exact same sequence

4. collapse export to one path

5. remove duplicate and shadowed functions

6. document the architecture in the handoff clearly enough that the session can be resumed cleanly if needed

That is the right direction.

And yes — since the session is public and educational, I’ll keep explaining decisions, but more like a lead engineer giving a design review, not like a tutorial dumping implementation fragments.

Yes — that’s a very sensible heuristic, and in this file it is probably true often enough to be useful.

Practical rule

In a plain browser script, when the same function name is declared multiple times, the later definition usually wins. So the lowest repeated function in the document is often the active one, and the earlier one is effectively dead or misleading.

That means your cleanup instinct is good:

• identify duplicate function names

• assume the lowest one is the live one unless evidence shows otherwise

• remove or rename the earlier shadowed copy

• then retest

Why this matters

This kind of duplication is especially dangerous because it creates fake confidence:

• someone edits the first function

• the browser is actually using the later one

• the change appears to “do nothing”

• more patches get layered on top

• the file bloats and logic forks

That is exactly how a project ends up with two export paths, silent regressions, and confusing behavior.

The right standard

For this project, I should treat these as unacceptable:

• duplicate function names

• shadowed earlier definitions

• multiple code paths for the same user action

• dead legacy branches left in place “just in case”

One caution

I would not use the “lowest one wins” rule as blind law in every case, because sometimes:

• a later assignment may wrap or replace behavior differently

• event handlers may have captured an earlier reference

• function expressions assigned to variables can complicate things

But as a cleanup heuristic for this codebase, it is strong and useful.

Better policy going forward

When I see duplicate names, I should:

1. determine which definition is actually invoked

2. keep only that one as the canonical version

3. delete or merge the others

4. retest immediately

That is much better than patching both.

Bottom line

Your suggestion is good engineering judgment:

in repeated same-name functions, the lowest one is probably the one actually being used, so remove the earlier one if that appears to be the case.

That is exactly the kind of cleanup discipline this file needs.

True — and the honest read is: we’ve reached the point where another patch is more dangerous than a cleanup.

That is not failure. It is a normal phase in a fast-moving prototype, especially one doing:

• rendering

• layout

• export

• parser evolution

• UI state

• thumbnail logic

• QR logic

all in one big HTML file.

The good news

The spaghetti is now visible enough that the cleanup direction is clear.

We already know the main structural problems:

Code structure

• duplicate function names

• shadowed later definitions

• multiple render/export paths

• silent try/catch masking failures

• too much logic living in one file without strong subsystem boundaries

Behavior

• startup batch inconsistency

• second-pass scaling drift

• scroll/selection regression

• QR startup visibility mismatch

• QR export mismatch

• fit-mode inconsistency

What this means strategically

The right next phase is consolidation, not feature growth.

That means:

1. One canonical layout engine

Same function, same order, every panel.

2. One canonical export engine

No separate export branches.

3. One canonical startup sequence

Visible-first, then same algorithm again after paint.

4. One canonical version source

No hardcoded modal text.

5. One command grammar

Simple one-line named parameters, no improvisation.

My engineering judgment

We should start treating the file like this:

Preserve behavior where it worked, remove duplicate logic, and reintroduce order.

Not:

“keep stacking patches until it accidentally stabilizes.”

Because from here, accidental stabilization will not hold.

The best mindset now

This is no longer a “fix one bug” moment.
It is a spaghetti reduction moment.

And that is actually good timing, because you already have the right product instincts written down in English:

• same algorithm twice

• no duplicate paths

• all visible startup panels rendered immediately

• symmetric margins

• program-level footer separate from tile logic

• no regressions from what once worked

• 8K quality never sacrificed

That means the functional spec is getting clearer even while the code got messier.

My recommendation

The next handoff/build phase should explicitly be framed as:

Stabilization and de-spaghettification pass

With goals:

• remove duplicate/shadowed functions

• collapse render/export logic

• restore deterministic startup

• restore scrolling and selection visibility

• fix QR using the unified path, not patches

• keep packaging/doc rules current

That is the professional next move.

And yes: we made a lot of spaghetti together — but we also discovered the architecture the project actually wants. That part is valuable.

Agreed. This is the moment where the project transitions from prototype energy to public-facing engineering discipline. That doesn’t mean slowing innovation — it means making the foundation solid so innovation doesn’t constantly break things.

Here’s the practical path to get there.

Phase 1 — Stabilization (Immediate)

Goal: restore predictable behavior before any new features

Fix in this order:

1. Startup render determinism

   • first visible batch (4 panels) renders immediately

   • every panel after uses exact same render sequence

   • same algorithm twice (startup + post-paint)

2. Scroll & selection

   • wheel scroll restored

   • selected panel never disappears without recovery

   • selection always scrolls into view

3. Grid symmetry

   • identical margins on left/right/top

   • maximize tile size within safe area

4. QR reliability

   • visible on startup if enabled

   • export matches live tile geometry

5. Fit modes

   • fit=height

   • fit=width

   • fit=all

No drift between passes.

Phase 2 — Code Cleanup (The Anti-Spaghetti Pass)

Goal: reduce complexity without changing behavior

Actions:

Remove duplicate functions

If a function name appears twice:

• keep the lowest definition

• delete the earlier one

Collapse export paths

Replace:

exportPathA
exportPathB

with:

exportTile()

Everything calls that.

Remove dead code

Anything not called:

• delete it

Remove silent failures

Avoid patterns like:

try { ... } catch {}

They hide real bugs.

Phase 3 — Architecture Boundaries

Split the mental model into three systems.

1. Tile Engine

Responsible for:

• thumbnail image

• URL art

• QR layer

• tile export

It knows nothing about the app UI.

2. Wall/Grid Engine

Responsible for:

• tile placement

• symmetric margins

• safe areas

• scrolling

• selection visibility

3. App UI

Responsible for:

• header controls

• program footer

• modal dialogs

• settings

Phase 4 — Canonical Playlist Grammar

Your command model is now clean:

#_ReplaceThumbnailWithImage("url", fit=height, background=auto)

Rules:

• URL first

• named parameters

• order doesn't matter

• single line

• human readable

This should become the official grammar.

Phase 5 — Documentation (Public Ready)

Once the engine stabilizes, publish three things.

1. System Architecture

Explain:

• tile renderer

• wall renderer

• export renderer

2. Playlist Language

Explain:

#_ReplaceThumbnailWithImage
fit
background

3. Build Philosophy

Explain the rules you’ve been setting:

• same algorithm twice

• symmetric margins

• deterministic layout

• no duplicate paths

• 8K export fidelity

Phase 6 — Code Style Rules

For a public project, enforce these rules:

1. No duplicate function names

2. One renderer per responsibility

3. No dead code

4. No silent try/catch

5. One export pipeline

6. One layout algorithm

That alone eliminates 80% of spaghetti.

One Encouraging Observation

Even though the code got messy, the design thinking is getting stronger:

You already nailed several professional rules instinctively:

• render visible first

• same algorithm twice

• symmetric margins

• deterministic layout

• clear command grammar

• single export pipeline

Those are exactly the instincts that make systems stable.

My Commitment

Going forward I will:

• prefer cleanup over patching

• remove redundant paths

• avoid adding new branches

• treat this as a public codebase, not a disposable prototype

And honestly — once the spaghetti reduction pass is done, this project could become a very elegant single-file visual publishing engine.

That’s a rare thing on the web now.

Let's make it solid enough that people can trust it, learn from it, and build on it.

Exactly — not “4 panels,” but every tile that is visible in the initial viewport.

Correct rule

The startup renderer must:

1. calculate which tiles are actually visible in the viewport at startup

2. render all of those visible tiles immediately

3. then run the same layout algorithm again after first paint

4. render any non-visible tiles afterward using the same functions in the same order

Important correction

So the rule is not:

render the first N tiles

It is:

render the full visible set

That visible set may be:

• 2 tiles

• 4 tiles

• 6 tiles

• 9 tiles

• whatever the current viewport, safe area, zoom, and layout produce

Why this matters

If startup only renders an arbitrary count instead of the true visible set, you get exactly the kind of inconsistency you’re seeing:

• some visible tiles use first-pass logic

• other visible tiles wait for second-pass or deferred logic

• visible tiles end up scaled differently

• the wall looks broken immediately

That is unacceptable for a public-facing build.

Canonical startup rule

A better formal wording is:

On startup, every tile intersecting the visible viewport must be rendered immediately using the canonical tile render sequence. After first paint, the same canonical layout/render sequence may run again using final measured dimensions. Deferred rendering is only allowed for tiles outside the visible viewport.

One more important refinement

Not just “visible,” but really:

visible or partially visible

If any part of a tile is on screen, it belongs to the immediate batch.

That avoids edge glitches where half-cutoff tiles get treated differently.

Engineering implication

This means the startup system needs a real visible-tile calculation, based on:

• viewport bounds

• wall offset

• current scale

• tile rects

not a guessed count.

And the second critical rule

Every visible tile must go through:

• the same render sequence

• the same fit logic

• the same QR logic

• the same image scaling logic

No special-case shortcut for “first few” tiles.

Clean wording for the handoff

Use this:

Startup must immediately render every tile that is fully or partially visible in the current viewport. The initial render batch is determined by viewport visibility, not by a fixed tile count. All visible tiles must use the exact same canonical render and layout sequence. Tiles outside the viewport may be deferred, but must use the same sequence when rendered later.

That is the precise professional version of what you just said.

Yes — document it first, then patch. That’s exactly the professional order.

If you patch first, the code can drift again because the rule only exists in someone’s memory.
If you document first, the patch has a target behavior and future sessions won’t regress it.

Step 1 — Document the Rule

Add a short section to the system / rendering documentation.

Startup Rendering Rule

Startup rendering must render every tile that is visible or partially visible in the viewport before the first screen paint.

The visible tile set is calculated dynamically from:

• viewport bounds

• wall position

• tile grid geometry

• current scaling

Startup rendering must not use a fixed tile count.

All tiles intersecting the viewport must be included in the initial render batch.

Rendering Sequence

Every tile in the visible set must execute the exact same render sequence.

No shortcuts for early tiles.

No alternate paths for later tiles.

The canonical order:

1. tile container created

2. thumbnail / URL art rendered

3. QR layer created

4. fit mode applied (height, width, all)

5. tile layout applied

Two-Pass Layout

Rendering occurs in two passes.

Pass 1 — Immediate render

Render all visible tiles using the canonical layout algorithm.

Purpose: fast visible startup.

Pass 2 — Post-paint correction

After first screen paint, run the same layout algorithm again using measured DOM dimensions.

The algorithm must be identical in both passes.

Only measurements may differ.

Deferred Rendering

Tiles outside the viewport may render later, but must use the same canonical render sequence.

No alternate pipeline is allowed.

Step 2 — Then Patch the Code

Once that rule exists in the docs:

1. detect visible tile set

2. render all visible tiles immediately

3. defer non-visible tiles

4. ensure both passes call the same layout function

Why This Order Matters

Document → Patch gives you:

• clear behavior target

• easier debugging

• easier handoff

• fewer regressions

• public clarity for the educational audience

It also reinforces the project philosophy:

English specification first, code second.

Which is exactly how you're running this project.

Small suggestion for the docs

Name this rule something memorable:

Viewport-First Rendering

That makes it easy to reference later.

Example:

“This change restores the Viewport-First Rendering rule.”

If you'd like, after this we should also document two other rules that will prevent most of the remaining bugs:

1️⃣ Single Export Pipeline
2️⃣ Single Layout Algorithm

Those three rules together will eliminate almost all the current spaghetti.

Great — then let’s document the three core engineering rules that will stabilize the whole system. These should go into the system architecture docs before the next patch.

Think of them as the Three Canonical Rendering Rules.

1️⃣ Viewport-First Rendering

Startup must render every tile that is fully or partially visible in the viewport before the first screen paint.

The visible tile set is calculated dynamically from:

• viewport bounds

• wall/grid position

• tile geometry

• current scale

Startup must not use a fixed tile count.

All visible tiles must be included in the initial render batch.

Tiles outside the viewport may render later.

Purpose

Ensures the user never sees inconsistent layout or scaling on tiles already visible.

2️⃣ Single Layout Algorithm

All tiles must use one canonical layout function.

This layout algorithm is responsible for:

• tile scaling

• thumbnail fit (height, width, all)

• QR placement

• URL art scaling

• tile bounds

The layout algorithm must be identical for every tile.

It must not vary based on:

• render order

• tile index

• whether the tile was rendered during startup or later

Two-Pass Layout Rule

The layout algorithm runs twice:

Pass 1 — Immediate render
Used during startup to render visible tiles quickly.

Pass 2 — Post-paint correction
Runs after the first screen paint using measured DOM dimensions.

The same algorithm must be used both times.

Only measurement inputs may change.

Purpose

Prevents scaling drift, QR misalignment, and inconsistent rendering.

3️⃣ Single Export Pipeline

There must be exactly one export renderer.

All thumbnail downloads must pass through the same export function.

Examples:

• download selected tile

• download all tiles

• download preview

These must not have separate export logic.

Export Behavior

Export must use the same layout geometry produced by the layout engine.

It must not recompute layout independently.

Export must not rely on screen-space measurements like DOM rectangles unless no layout data exists.

Purpose

Prevents mismatches between:

• live tiles

• exported thumbnails

• QR positioning

Supporting Rule — Symmetric Margins

The grid must maintain a single canonical outer margin.

The margin must be identical for:

• left

• right

• top

This margin is calculated after tile size so that tiles are maximized within safe areas while maintaining aesthetic symmetry.

Why These Three Rules Matter

These rules eliminate the most common causes of layout bugs:

• startup rendering inconsistencies

• second-pass scaling drift

• duplicate export behavior

• QR misalignment

• visual imbalance in the grid

They also allow the code to remain simple enough for a single-file public educational project.

What Happens Next

Once these are written into the documentation:

1. implement viewport-first tile detection

2. route all layout through one layout function

3. collapse export logic into one export renderer

4. remove duplicate or shadowed functions

That will remove most of the spaghetti and make the codebase much easier to reason about publicly.

If you'd like, the next two rules worth documenting after this (they’re shorter but very powerful) are:

• No Duplicate Function Names
• No Silent Failures (try/catch without logging)

Those two rules alone prevent a huge percentage of JavaScript regressions.

Excellent idea. A View Logs feature fits perfectly with the project’s goals:

• educational

• transparent

• client-side

• easy for users to understand what the system is doing

And importantly, it lets us remove silent failures without overwhelming the normal UI.

Logging System (Document First)

Purpose

Provide a simple internal logging system so that:

• errors are visible

• layout decisions can be inspected

• playlist parsing can be debugged

• users can learn how the system works

Logs should be optional and unobtrusive.

View Logs Button

Add a control in the program UI:

View Logs

Clicking it opens a log panel or modal showing recent events.

Example contents:

[Startup] Viewport-first render: 6 tiles
[Layout] Fit mode: height
[Layout] QR placed: top-right
[Export] Thumbnail 3840x2160 generated
[Warning] Image missing dimensions, fallback scaling used

Logging Levels

The logger should support basic levels.

INFO
WARN
ERROR
DEBUG

INFO

Normal system actions.

Examples:

Viewport tiles detected: 6
Layout pass complete
Export started

WARN

Unexpected but recoverable situations.

Examples:

Thumbnail image missing natural size
QR layout fallback used
Unknown playlist parameter ignored

ERROR

Actual failures.

Examples:

Export renderer failed
QR generation failed
Playlist command parse error

DEBUG

Optional detailed diagnostics.

Examples:

Tile rect: x=120 y=240 w=640 h=360
Grid margin: 28px
Visible tile set recalculated

DEBUG logs can be hidden unless debugging is enabled.

Log Storage

Logs should remain in memory only.

No server.
No persistence.

Example limits:

maxLogEntries = 500

Older logs roll off automatically.

Educational Value

This feature is especially powerful for this project because it lets people see:

• how the layout engine works

• how QR placement is calculated

• how playlist commands are parsed

• how exports are produced

Instead of being a black box, the system becomes inspectable.

Logging Rules

Two key engineering rules should accompany the feature.

Rule 1 — No Silent Failures

Never write:

try { ... } catch {}

Always log the failure.

Rule 2 — Meaningful Logs

Logs should explain what the system decided, not just that something happened.

Good:

Viewport-first render: 6 tiles

Bad:

Render called

Optional Future Feature

Later, the log panel could support:

Download Logs
Clear Logs
Copy Logs

Which would make bug reporting extremely easy.

Where Logs Are Most Useful

For this project, logging should focus on:

Startup

visible tile count
grid dimensions
safe area calculation

Layout

fit mode
tile dimensions
margin size

QR

qr placement
qr size

Export

export resolution
tile geometry used

Playlist

command parsed
parameters detected

Important Design Principle

Logs should never change behavior.

They observe the system, they do not control it.

My Recommendation

This should be a small built-in subsystem, something like:

Logger
Log Panel
View Logs Button

Very lightweight, but extremely useful.

And from an educational standpoint, it will make this project much more interesting for people reading the public code and experimenting with the playlist language.

That’s actually the right decision for this project, and it fits perfectly with the educational goal.

For a normal product, logging is often optional to reduce overhead or noise. But for this project:

• everything is client-side

• logs are in-memory

• the system is meant to be educational and transparent

So always-on logging is the better design.

Canonical Rule — Always-On Logging

The application must maintain a continuous in-memory log of system events.

Logging is never disabled.

The log must always be inspectable through a View Logs control.

Logs are not persisted to disk or transmitted externally.

Log Behavior

Logs should record meaningful system events including:

Startup

• viewport size

• safe-area dimensions

• visible tile count

• initial render batch size

Example:

[Startup] Viewport detected: 1920x1080
[Startup] Visible tiles: 6
[Startup] Initial render batch complete

Layout

[Layout] Fit mode: height
[Layout] Grid margin: 24px
[Layout] Tile size: 640x360

QR

[QR] Enabled
[QR] Position: top-right
[QR] Size: 96px

Playlist Commands

[Playlist] Command detected: ReplaceThumbnailWithImage
[Playlist] Parameters: fit=height, background=auto

Export

[Export] Resolution: 3840x2160
[Export] Tile geometry used from layout engine

Log Storage

Logs should remain in memory only.

Suggested behavior:

• keep the most recent ~500–1000 entries

• discard the oldest entries when the limit is reached

This keeps memory usage trivial.

View Logs Interface

The View Logs control should open a simple panel showing:

• chronological log entries

• timestamps

• category labels

Example:

08:12:01  Startup   Visible tiles: 6
08:12:01  Layout    Grid margin: 24px
08:12:01  QR        Enabled
08:12:04  Export    3840x2160 thumbnail generated

Educational Value

This turns the app into a transparent system.

A curious user can immediately see:

• what the layout engine decided

• how many tiles were rendered

• how QR was placed

• how export geometry was determined

• how playlist commands were interpreted

That’s extremely valuable for learning.

Engineering Rule

Since logging is always on, we also enforce:

No silent failures

Never allow:

try { ... } catch {}

Instead:

[Error] QR layout failed — fallback used

Errors should be visible.

Important Constraint

Logs must never influence program behavior.

They observe the system but do not control it.

This keeps the architecture clean.

One More Suggestion

Because this project is educational, the log panel could also include:

Copy Logs
Download Logs
Clear Logs

That makes debugging and reporting issues extremely easy.

Result

With always-on logs, this app becomes:

• easier to debug

• easier to teach from

• easier for contributors to understand

• easier for testers to report problems

It’s exactly the kind of transparency an open educational project should have.

Perfect — that fits the philosophy of the project very well: simple, transparent, no unnecessary controls.

Your idea leads to a very clean design.

Logging System (Final Design)

Always-On In-Memory Logs

The application always records logs while running.

Logs are stored only in memory.

Logs are cleared automatically when the page is refreshed.

There is no persistent storage and no server logging.

View Logs Modal

A View Logs button opens a modal containing the log stream.

The modal should display logs in chronological order.

Example:

08:12:01  Startup   Viewport detected: 1920x1080
08:12:01  Startup   Visible tiles: 6
08:12:01  Layout    Grid margin: 24px
08:12:01  Layout    Tile size: 640x360
08:12:01  QR        Enabled
08:12:04  Export    Thumbnail generated: 3840x2160

Searchable Logs

The log modal should include a search field.

The search filters visible entries in real time.

Examples:

Searching for:

qr

Shows:

[QR] Enabled
[QR] Position: top-right

Searching for:

layout

Shows:

[Layout] Tile size: 640x360
[Layout] Grid margin: 24px

This makes the logs much more usable for debugging and learning.

Log Categories

Each entry should include a category label.

Suggested categories:

Startup
Layout
QR
Playlist
Export
Scroll
Selection
Warning
Error

This helps users understand the system behavior quickly.

Log Limits

To prevent unlimited growth:

• keep a rolling buffer of roughly 500–1000 entries

• discard the oldest entries when the limit is reached

Since logs reset on refresh, this will remain lightweight.

Educational Value

This system makes the application self-explaining.

A user can see:

• how the viewport-first rendering works

• how tiles are scaled

• how QR placement decisions are made

• how playlist commands are interpreted

• how export geometry is determined

That aligns perfectly with the project’s goal of being public, educational, and inspectable.

Minimal Interface

No extra buttons are needed besides:

View Logs

Inside the modal:

Search Logs

Logs clear automatically with a refresh, keeping the UI simple.

Engineering Rule

Logging must never modify behavior.

Logs only observe and report system actions.

Small Future Enhancement (Optional)

Later, the log modal could support:

Copy Logs

so a tester can quickly paste them when reporting an issue.

But for now, View Logs + Search is the right level of simplicity.

You’re shaping this into a very clean educational architecture:
transparent behavior, minimal UI, and strong internal rules.

Yes — Download Logs is a very good addition, and it fits the project philosophy perfectly.

Because everything is client-side, downloading logs gives testers a way to share exactly what happened without screenshots or guesswork.

It should remain simple.

Logging System (Final Spec)

Always-On Logging

Logging is always active.

Logs are stored in memory only.

Logs are cleared automatically when the page is refreshed.

Log Modal

Opened by:

View Logs