Skip to content

Phase 6: recipe + getting-started markdown rewrites (Subscribe/Publish nomenclature)#27

Open
adnaan wants to merge 1 commit into
mainfrom
broadcast-redesign-phase-6
Open

Phase 6: recipe + getting-started markdown rewrites (Subscribe/Publish nomenclature)#27
adnaan wants to merge 1 commit into
mainfrom
broadcast-redesign-phase-6

Conversation

@adnaan
Copy link
Copy Markdown
Contributor

@adnaan adnaan commented May 21, 2026 •
edited
Loading

Phase 6 of the broadcast-redesign wave (livetemplate#415) — docs side, markdown-rewrites-only after rebase.

Scope (post-rebase, net-new on top of origin/main)

docs#24 (already merged) covered the _app/*.go migrations + go.mod bump. This PR is the markdown-teaching-text companion that #24 didn't touch:

  • 8 recipe rewrites at section-level conceptual depth (not search-replace):
    • content/index.md — top-of-funnel "Try it" paragraph.
    • content/recipes/counter/index.md — full "How Subscribe + Publish route" section + frontmatter + "What next" list.
    • content/recipes/shared-notepad/index.md — frontmatter, intro bullets, Mount + Save sections (two-step Subscribe+Publish shape with the "no Subscribe, no fan-out" caveat), Refresh section, scaling table.
    • content/recipes/todos/index.md — same-user-multiple-tabs bullet, scaling table cell, "What next" Counter link.
    • content/recipes/broadcasting.md — full reframe around the two-step shape; Mount section, "Sending — Publish under the lock-release rule", multi-replica section.
    • content/recipes/sync-and-broadcast.md — full rewrite. Title: "Broadcast & Server Push" → "Sync & Server Push". New 4-row When-to-pick matrix.
    • content/recipes/architecture-flow.md — two-tab paragraph reframed.
    • content/recipes/progressive-enhancement/index.md — Tier B limitation bullet.
  • content/recipes/apps/index.md, content/getting-started/your-first-app.md — V20-flagged residue.
  • 3 .tmpl files (broadcasting, multi-user-sync, notepad) — explanatory paragraphs.

13 files, +96/-77.

V15 acceptance GREEN

5 chromedp e2e tests / 15 subtests pass against current main + the migrated controllers from #24.

Build / CI dependency on tinkerdown#279

This PR's build job has been red since open. Root cause: bug in tinkerdown's mermaid validator, not in this PR's content:

  • The validator (tinkerdown validate content/) creates a fresh Chromium process per file with a 15s deadline shared across all diagrams in the file. On Ubuntu Actions runners, Chrome cold-start routinely takes 5–10s, leaving 5–10s for navigation+render — randomly insufficient. The failure manifests two ways: chrome failed to start: Failed to connect to the bus (when Chrome OOMs /dev/shm) or context deadline exceeded. Different files failed each run, including ones this PR never touched (recipes/how-this-site-works.md).
  • Local repro: validator passes all 55 files in 17 seconds against the same docs content. Bug is in the validator's CI-environment behavior, not in this PR's mermaid diagrams.

Fix landed in livetemplate/tinkerdown#279 (commit 74f51ad): adds --disable-dev-shm-usage + --disable-extensions + --no-first-run to the Chromium launch flags, and bumps the per-file deadline 15s → 60s. Locally verified to still pass the docs content in 17s.

The docs CI workflow installs tinkerdown by cloning https://github.com/livetemplate/tinkerdown.git at default branch. Once tinkerdown#279 merges, the next docs CI rerun on this PR will install the fixed validator and build should pass.

Audit-was-wrong note

The original Phase 6 worktree branched off pre-#24 SHA d15b96f and didn't notice docs#24 had already shipped (it's named in the project's pinned memory entry as a Phase 5 companion merge). The original commit re-migrated the same _app/*.go files; the rebase dropped those duplicate changes and kept only the net-new markdown work. Recorded in livetemplate#430's phase-6.md as a recovery deviation.

Companion PRs

🤖 Generated with Claude Code

@adnaan adnaan mentioned this pull request May 21, 2026
Open
@adnaan @claude
feat(recipes)!: Phase 6 — migrate recipes + _app code to Subscribe/Pu…
9ba2df0 
…blish (livetemplate v0.10.0)

Phase 6 of the broadcast-redesign wave (livetemplate#415) — docs side.

go.mod + e2e/go.mod bumped to livetemplate v0.10.0 (separate Go modules;
both must bump in lockstep).

8 user-named recipes rewritten at section-level depth (conceptual content,
not search-replace):

- content/index.md — top-of-funnel "Try it" paragraph.
- content/recipes/counter/index.md — full "How Subscribe + Publish route"
  section replaces the prior BroadcastAction routing section; intro,
  frontmatter, and "What next" list updated.
- content/recipes/shared-notepad/index.md — frontmatter, intro bullets,
  Mount + Save sections (two-step Subscribe+Publish shape with the
  "no Subscribe, no fan-out" caveat), Refresh section, scaling table.
- content/recipes/todos/index.md — same-user-multiple-tabs bullet,
  scaling table cell, "What next" Counter link.
- content/recipes/broadcasting.md — full reframe around the two-step
  shape; Mount section, "Sending — Publish under the lock-release rule",
  multi-replica section now describes the topic-channel + seen-ring.
- content/recipes/sync-and-broadcast.md — full rewrite. Title: "Broadcast
  & Server Push" → "Sync & Server Push". New 4-row When-to-pick matrix.
  Mermaid diagram rewired with the Subscribe-aware sequence.
- content/recipes/architecture-flow.md — two-tab paragraph reframed.
- content/recipes/progressive-enhancement/index.md — Tier B limitation
  bullet reframed to Publish-via-WS.

Inline _app/*.go migration (forced by the go.mod bump):

- content/recipes/counter/_app/counter.go: Mount adds Subscribe(SelfTopic);
  Increment/Decrement swap to Publish.
- content/recipes/shared-notepad/_app/controller.go: Mount adds Subscribe;
  Save publishes; Refresh comment rewritten.
- content/recipes/shared-notepad/_app/handler.go: 3 comment blocks reworded.
- content/recipes/shared-notepad/_app/notepad.tmpl: "How it works" bullet.
- content/recipes/todos/_app/controller.go: Mount adds Subscribe; 4 call
  sites swap to Publish.
- content/recipes/patterns/_app/handlers_realtime.go: 3 controllers
  (MultiUserSync, Broadcasting, Presence) gain Mount Subscribe; 5 Publish
  call sites; 2 comment blocks reworded.
- content/recipes/patterns/_app/handlers_lists.go: 1 comment.
- content/recipes/patterns/_app/data.go: 2 pattern descriptions.
- content/recipes/patterns/_app/templates/realtime/{broadcasting,
  multi-user-sync}.tmpl: explanatory paragraphs.
- cmd/site/main.go: shared-notepad mount-rationale comment block.

V20-zero cleanup (beyond user-named recipes):

- content/recipes/apps/index.md, content/getting-started/your-first-app.md:
  flagged by the V20 substring sweep; reframed.
- e2e/shared-notepad/notepad_test.go, e2e/patterns/patterns_test.go:
  comments and assertion messages.

V15 acceptance sweep GREEN — 5 chromedp e2e tests / 15 subtests pass
end-to-end against the migrated wiring (TestMultiUserSync,
TestBroadcasting, TestPresence, TestSharedNotepad_E2E,
TestSharedNotepad_MultiUserIsolation). The
Late_Joiner_Sees_Current_Counter_On_Mount subtest specifically validates
the Mount-side Subscribe + snapshot pattern works when a tab opens after
others have already published.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@adnaan adnaan force-pushed the broadcast-redesign-phase-6 branch from ed45f88 to 9ba2df0 Compare May 21, 2026 17:52
@adnaan adnaan changed the title Phase 6: migrate recipes + _app code to Subscribe/Publish (livetemplate v0.10.0) Phase 6: recipe + getting-started markdown rewrites (Subscribe/Publish nomenclature) May 21, 2026
adnaan added a commit to livetemplate/tinkerdown that referenced this pull request May 21, 2026
@adnaan @claude
fix(validate): unflake mermaid validator on Ubuntu CI (--disable-dev-…
74f51ad 
…shm-usage + bump per-file deadline 15s → 60s)

Surfaced while running the broadcast-redesign Phase-6 wave through livetemplate/docs#27's build workflow: the same docs content that validates cleanly in ~17s on a devbox failed in 5 successive CI runs with two error modes:

  ✗ index.md:  chrome failed to start: Failed to connect to the bus
  ✗ recipes/architecture-flow.md:  context deadline exceeded
  ✗ recipes/how-this-site-works.md:  context deadline exceeded

Each rerun flagged a *different* set of files (sometimes index.md alone; sometimes 3 unrelated files including ones the docs PR didn't touch), with the failures clustering on cold-runner runs. Local repro: 17s total for 55 files / 5 mermaid diagrams against the same content. The bug was in two layers:

1. **Missing `--disable-dev-shm-usage`.** Ubuntu CI runners default `/dev/shm` to 64MB (Docker/Actions cgroup default); Chrome's renderer process attempts to allocate shared memory there, OOMs, and the recovery path manifests as the `"Failed to connect to the bus"` D-Bus negotiation failure rather than a clean OOM error. Switching to `/tmp` via `--disable-dev-shm-usage` eliminates both the OOM and the misleading D-Bus message. Plus `--disable-extensions` + `--no-first-run` for faster cold-start.

2. **15s per-file deadline too tight on slow runners.** `validateMermaidDiagrams` creates a fresh `chromedp.NewExecAllocator` per file. Chrome cold-start on Ubuntu CI is routinely 5-10s; the diagram loop then adds Navigate + Sleep(2s) + Evaluate (~3s per diagram). On devbox: 15s holds. On CI with a slow cold start: only 5-7s budget remains — explaining the per-file randomness in which files fail. Bumped to 60s with a per-file rationale comment.

Verified locally: same `time /tmp/tk-bin validate content/` against the docs site = 17s (no slowdown from the new flags), all 55 files pass. The CI side should follow once `docs#27` re-runs against a tinkerdown@main that includes this commit.

This unblocks livetemplate/docs#27 (which has been red on `build` since its open) without changing any docs content — the docs content was always valid; the validator was over-tight for slow CI hardware.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@adnaan