Text column edges

Feature plan: Step 1 · Step 2 · Step 3 · Step 4

Debug mode: enabled

Effort study: railspike-effort / v3/tour_snapshots; host ledger. Standing P2 enrollment.

Extended estimates: enabled

Cycle estimate: 0.6

Problem

Each tour visit makes 16 slow PHP renders at once (7–13 s each in production on 2026-11-15), and the dense grid with one-line captions says little about why each feature matters.

User stories

  • As a visitor, I want to scroll a calm page, one feature at a time, with a short essay and a working copy of the page beside it, so that I understand what ZenMemes is without having it explained up front.

  • As the maintainer, I want the tour to cost the same whether one person or a hundred open it, so that sharing it can't take the site down.

  • As the maintainer, I don't want to SSH in to make it work: snapshots should appear on their own when missing, and I want a button in Tools to refresh them.

  • As the maintainer editing essays, I want them in one plain-text file, so that I can change wording without touching HTML.

Core requirements

  • Snapshots. ./v3 tour refresh renders each tour route once, in process, as a logged-out visitor, through the renderer used by ./v3 high-traffic refresh, and writes public/assets/tour/<name>.html atomically, plus the tour page itself at public/assets/tour/index.html. Each snapshot gets noindex and <base target="_top"> (clicks open the real page in the same tab). No HTTP requests to the site. A route that fails to render keeps its previous snapshot and is reported; the rest still refresh.

  • Self-healing. When snapshots are missing, they get made without the terminal: the step that runs after Deploy now queues a tour refresh in the background if any snapshot is missing or older than the deployed code. The existing high-traffic run cron, where installed, does the same check. Both use the existing detached task queue (src/ForumRewrite/TaskQueue/), so a refresh never blocks a page load and only one runs at a time.

  • Tools button. Tools → Operations gets a "Tour snapshots" row: last refreshed time, a Refresh now button (root operators only) that queues the same background task, and status while it runs or the last error.

  • Essays. One plain-text source, content/tour.txt, in Key: value sections (Route:, Name:, Title:, then the essay body). The refresh command builds the page from it; editing it and refreshing (button or deploy) updates the page.

  • Page. One snapshot per row: heading and essay (80–150 words) beside a wide frame on desktop, essay above the frame on phone. Look/Interact and Desktop/Phone toggles stay, pinned at the top. Frames load as they approach the viewport (static files, so lazy loading no longer means waiting on the server); the first two load immediately. No intro, nothing opens a new tab, noindex, unlinked.

  • Features (9): Board · a thread (Start here) · Agents and Prompts · Unread · Gallery · Calendar · Tags · Your key · Backup (your data as Git). Final wording in the essays.

  • Retraction. The retraction sweep's retirement of managed generated HTML covers public/assets/tour/. A retired snapshot is regenerated by the next refresh (deploy, cron, or button) from the current read model, which already excludes retracted content.

  • Old page. /assets/tour.html becomes a one-line redirect to /assets/tour/ so any link already copied keeps working.

Decisions taken from the maintainer's message

  • Option A approved, on the condition that snapshots are created automatically when missing and can be triggered from Tools.

  • Refresh triggers: after Deploy now (when missing or stale), cron where installed, and the Tools button. No fixed schedule required.

  • Tools location: Operations (it already holds high-traffic mode, the closest relative).

Decisions to confirm

  • Essays drafted by Claude during implementation, delivered in the PR for your edits (rather than drafted now in Step 2).

  • Unread replaces Recent and Users in the list; Compose and API/llms.txt drop out (Compose is empty logged-out; the API pages are text, not features).

  • Frame sizes stay as in #256 (820×1100 desktop, 390×844 phone).

Delivery scope

Application change. In scope: the refresh command and task, the deploy and cron hooks, the Operations row, content/tour.txt, the generated page template, retraction coverage, redirect from the old page. Not in scope: linking the tour anywhere, per-instance feature lists beyond editing content/tour.txt, logged-in snapshots.

Completion boundary

  • Entry: /assets/tour/ (and the old /assets/tour.html redirecting there); Tools → Operations → Tour snapshots → Refresh now.

  • End-to-end: on a fresh deploy with no snapshots, the tour appears within minutes without a terminal; a visit makes no PHP renders; editing content/tour.txt then pressing Refresh now shows the new essay.

  • Recovery: a route that fails to render keeps its old snapshot and shows its error on Operations; a second Refresh while one runs reports "already running"; retracting a post shown in a snapshot removes that snapshot until the next refresh.

  • Release: maintainer deploys, opens the tour on his phone, scrolls smoothly, and finds it fast.

Risks

  • Renderer coverage. Calendar, Unread and Your key may not render through the high-traffic path. Check each early; a route that can't is dropped from the list or rendered by the ordinary page renderer.

  • Snapshots leak viewer state. Render strictly logged-out; a test asserts no session or username markup in snapshots.

  • Deploy hook adds time to Deploy now. It only queues a task; the deploy itself stays as fast as today.

Shared component inventory

  • Rendering: HighTrafficCache, HighTrafficRefresh, HighTrafficRenderInput.

  • Background work: DetachedTaskQueueLauncher, TaskQueueWorker, SqliteTaskQueueStore.

  • Tools: templates/pages/operations.php and its controller; switch/row markup reused.

  • Retraction: the sweep's generated-HTML retirement (see retraction sweep).

  • Page: the current public/assets/tour.html styles and toggles, moved into the generated page template.

Concepts touched

  • Proposed tour snapshot (created): documented in docs/reference/ next to high-traffic mode.

Success criteria

  • A tour visit triggers zero PHP renders (access log check).

  • Snapshots appear after Deploy now with no terminal use.

  • Refresh now works from Operations and reports status.

  • Retraction test: a snapshot containing a retracted post is retired.

  • Phone: page scrolls smoothly over frames in Look mode; nothing opens a new tab.

Debug log: tour_snapshots_debug_log.md

Approval

2026-11-15 15:36 ET, maintainer: "Approved step 2." (covers the three decisions to confirm).