Fix TSX docs examples and playground payloads

Author: brianmhunt

AGENTS.md

@@ -157,6 +157,17 @@ changes — update **both** the Starlight docs (for humans) and the agent guide
 (for agents). The agent guide should be token-efficient: dense, code-first,
 minimal prose.
 
+## Docs Verification
+
+When validating `tko.io` documentation changes with the local docs site:
+
+- Use `playwright-cli` in headless mode by default. Do not use headed/browser-stealing runs unless the user explicitly asks for them.
+- Prefer a live Astro dev server on `127.0.0.1` so markdown/plugin edits reload while you work.
+- For docs pages with runnable examples, verify the live page and each `Open in Playground` button after edits.
+- Standard headless flow: `playwright-cli close-all`, `playwright-cli open http://127.0.0.1:4321/...`, inspect the snapshot for playground refs, click each button, switch to the playground tab, and confirm `#esbuild-status`, `#compile-time`, and `#error-bar`.
+- Treat docs example work as incomplete until the emitted playground payload compiles cleanly on the live site.
+- If a page has multiple TSX examples, check every TSX playground button, not just the first one.
+
 ## Important Guidelines
 
 - Do not modify `tools/build.mk` or `tools/karma.conf.js` without understanding

plans/tsx-doc-examples-rollout.md

@@ -0,0 +1,214 @@
+# Plan: TSX Docs Example Rollout
+
+## Goal
+
+Make the TSX side of the docs easier to read than the legacy HTML + viewmodel
+examples while keeping every example runnable in the playground.
+
+The reader-facing convention is:
+
+- Declare observables and other referenced variables at the top of the example
+- Show the binding-focused TSX snippet only
+- Hide mount/setup boilerplate from the visible example
+- Keep the legacy HTML + JS example intact inside the HTML tab
+- Ensure both tabs continue to open working playground sessions
+
+---
+
+## Current Problem
+
+The first TSX migration pass made several examples longer and noisier than the
+legacy HTML version:
+
+- Some TSX examples include repeated `root / render / applyBindings` ceremony
+- Some examples introduce intermediate objects that are not needed to explain
+  the binding
+- Legacy HTML `viewModel` blocks can appear visually detached from the HTML tab
+- The docs are teaching setup details at the same level as binding syntax
+
+This is backwards for readers. TSX should feel more direct, not more verbose.
+
+---
+
+## Reader-First Convention
+
+### Visible TSX example
+
+Each TSX example should show only:
+
+1. Top-level variables and observables referenced by `ko-*={...}`
+2. The JSX that demonstrates the binding itself
+
+Example shape:
+
+```tsx
+const url = ko.observable('year-end.html')
+const details = ko.observable('Report including final year-end statistics')
+
+<a ko-attr={{ href: url, title: details }}>Report</a>
+```
+
+### Hidden playground wrapper
+
+The playground button should wrap the visible snippet with the standard mount
+code automatically:
+
+- locate or create `#root`
+- render the JSX into the root
+- call `tko.applyBindings({}, root)`
+
+This keeps the docs short without breaking playground execution.
+
+### HTML tab behavior
+
+- Keep the legacy HTML snippet visible
+- Keep the matching JS viewmodel visible, but only inside the HTML tab panel
+- Preserve a working HTML playground button using the paired HTML + JS payload
+
+---
+
+## Scope
+
+Apply this convention to TSX-capable docs examples across:
+
+- `tko.io/src/content/docs/bindings/`
+- selected examples in `observables/`, `computed/`, and `components/` where a
+  TSX companion is helpful and already being introduced
+- supporting docs for agents/readers:
+  - `tko.io/public/agent-guide.md`
+  - `tko.io/public/agent-testing.md`
+
+Initial priority is bindings pages that already have active TSX work:
+
+- `attr`
+- `click`
+- `enable`
+- `foreach`
+- `hasfocus`
+- `if`
+- `text`
+- `textInput`
+- `value`
+- component pages already touched in the current branch
+
+---
+
+## Implementation Plan
+
+### Phase 1: Lock the convention in tooling
+
+Update the docs rendering/playground pipeline so it supports the reader-first
+shape:
+
+- `plugins/tsx-tabs.js`
+  - continue pairing handwritten `tsx` + `html` examples
+  - keep legacy JS blocks inside the HTML tab panel
+- `plugins/playground-button.js`
+  - support TSX snippets that omit mount/setup boilerplate
+  - auto-wrap TSX snippets before encoding the playground payload
+  - keep HTML payload pairing exact and deterministic
+
+Success criteria:
+
+- visible TSX snippet can stop at the JSX example
+- playground still receives runnable `{ html, js }`
+- HTML tab still renders its JS block inside the tab
+
+### Phase 2: Migrate simple binding examples
+
+For simple bindings, prefer:
+
+- observables first
+- inline JSX binding expression
+- no extra `view` variable unless it improves readability
+- no visible mount/setup footer
+
+Examples include:
+
+- `attr`
+- `enable`
+- `text`
+- `textInput`
+- `value`
+- `click`
+
+### Phase 3: Migrate context-sensitive examples
+
+Bindings like `foreach` and `if` need extra care because they mix:
+
+- compile-time variables in `ko-*={...}`
+- runtime binding-context strings like `$data`, `$parent`, `name`
+
+For these pages:
+
+- keep top-level collections/computeds explicit
+- keep runtime binding-context references as strings in child nodes
+- add short notes only where the compile-time/runtime boundary is easy to miss
+
+### Phase 4: Align docs and agent docs
+
+After the pattern stabilizes in the binding pages, update:
+
+- `public/agent-guide.md`
+- `public/agent-testing.md`
+
+to document the new visible-snippet convention and the hidden playground
+wrapper behavior.
+
+---
+
+## Content Rules
+
+Use these rules consistently during migration:
+
+- If a `ko-*` attribute references a value, define that value first
+- Prefer observables when the original example is demonstrating reactive data
+- Prefer literals only when reactivity is not the point of the example
+- Do not show `document.getElementById`, `appendChild`, or `applyBindings`
+  unless the page is explicitly teaching render/setup mechanics
+- Avoid helper objects like `const attrs = { ... }` unless the object itself is
+  part of what the reader should learn
+- Keep the TSX tab shorter than the HTML + JS alternative whenever possible
+
+---
+
+## Verification
+
+For each migrated page:
+
+1. Run `bun run build`
+2. Run the docs site locally with `bun x astro dev --host 127.0.0.1 --port 4321 --force`
+3. Verify the page with headless `playwright-cli`
+4. Confirm:
+   - TSX tab renders the shortened reader-facing snippet
+   - HTML tab renders both legacy HTML and its JS block inside the tab
+   - TSX playground button opens a runnable payload
+   - HTML playground button opens a runnable payload
+   - no visible error bar or console errors in the playground
+
+For the full rollout, spot-check every migrated page and fully verify the more
+complex ones (`foreach`, `if`, components).
+
+---
+
+## Risks
+
+- Hidden wrapper logic can drift from the documented render pattern if it is not
+  kept in sync with the playground
+- Over-shortening TSX examples can hide important compile-time scope rules
+- Complex bindings may need a visible `view` variable for readability even if
+  simple bindings do not
+- Astro/Expressive Code caching can obscure plugin changes; force rebuilds may
+  be needed during iteration
+
+---
+
+## Outcome
+
+After this rollout:
+
+- TSX examples read as the modern, concise path
+- observables remain explicit and teach the compile-time scope rule
+- setup ceremony stops dominating simple binding pages
+- HTML examples remain fully available for legacy readers
+- both tabs remain runnable through the playground

tko.io/plugins/playground-button.js

@@ -19,6 +19,7 @@
  */
 
 const MASK_SVG = `url("data:image/svg+xml,%3Csvg%20xmlns%3D'http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg'%20viewBox%3D'0%200%2024%2024'%20fill%3D'none'%20stroke%3D'black'%20stroke-width%3D'1.75'%3E%3Cpath%20d%3D'M15%203h6v6'%2F%3E%3Cpath%20d%3D'M10%2014%2021%203'%2F%3E%3Cpath%20d%3D'M18%2013v6a2%202%200%200%201-2%202H5a2%202%200%200%201-2-2V8a2%202%200%200%201%202-2h6'%2F%3E%3C%2Fsvg%3E")`
+const DEFAULT_PLAYGROUND_HTML = '<div id="root"></div>'
 
 function h(tag, props, children = []) {
   return {
@@ -64,13 +65,54 @@ function autoApplyBindings(js) {
   return js + `\nko.applyBindings(${vmName});`
 }
 
-function addPlaygroundButton(renderData, html, js) {
-  const runnableJs = autoApplyBindings(js)
-  if (!runnableJs) return
-  const hash = encodePlaygroundHash(html, runnableJs)
-  const ast = renderData.blockAst
+function looksLikeJsxExpression(code) {
+  const trimmed = code.trim()
+  return trimmed.startsWith('<') || trimmed.startsWith('(')
+}
 
-  const copyDiv = findNode(ast, n =>
+function indentBlock(code, spaces) {
+  const indent = ' '.repeat(spaces)
+  return code
+    .split('\n')
+    .map(line => (line ? `${indent}${line}` : line))
+    .join('\n')
+}
+
+function wrapTsxForPlayground(tsx) {
+  const code = tsx.trim()
+  if (!code) return code
+
+  // Hand-authored full examples should keep their explicit setup.
+  if (
+    /tko\.jsx\.render\s*\(/.test(code) ||
+    /(?:^|\W)(?:ko|tko)\.applyBindings\s*\(/.test(code) ||
+    /document\.getElementById\s*\(/.test(code)
+  ) {
+    return code
+  }
+
+  const blocks = code.split(/\n\s*\n/)
+  const jsxBlock = blocks.at(-1)?.trim()
+  if (!jsxBlock || !looksLikeJsxExpression(jsxBlock)) return code
+
+  const prelude = blocks.slice(0, -1).join('\n\n').trim()
+
+  let wrapped = ''
+  if (prelude) wrapped += `${prelude}\n\n`
+  wrapped += '// boilerplate added by the docs playground\n'
+  wrapped += "const root = document.getElementById('root')\n"
+  wrapped += 'const { node } = tko.jsx.render(\n'
+  wrapped += `${indentBlock(jsxBlock, 2)}\n`
+  wrapped += ')\n'
+  wrapped += 'root.appendChild(node)\n'
+  wrapped += 'tko.applyBindings({}, root)'
+  return wrapped
+}
+
+function insertPlaygroundButton(blockAst, html, js) {
+  const hash = encodePlaygroundHash(html, js)
+
+  const copyDiv = findNode(blockAst, n =>
     n.type === 'element' &&
     n.tagName === 'div' &&
     Array.isArray(n.properties?.className) &&
@@ -89,11 +131,17 @@ function addPlaygroundButton(renderData, html, js) {
   copyDiv.children.unshift(link)
 }
 
-export function pluginPlaygroundButton() {
-  // Track pending blocks for pairing with a following JS block
-  let pendingHtml = null
-  let pendingTsx = null
+function addHtmlPlaygroundButton(blockAst, html, js) {
+  const runnableJs = autoApplyBindings(js)
+  if (!runnableJs) return
+  insertPlaygroundButton(blockAst, html, runnableJs)
+}
 
+function addTsxButton(blockAst, tsx) {
+  insertPlaygroundButton(blockAst, DEFAULT_PLAYGROUND_HTML, wrapTsxForPlayground(tsx))
+}
+
+export function pluginPlaygroundButton() {
   return {
     name: 'playground-button',
 
@@ -177,38 +225,25 @@ export function pluginPlaygroundButton() {
     hooks: {
       postprocessRenderedBlock: ({ codeBlock, renderData }) => {
         if (codeBlock.language === 'tsx') {
-          // TSX block (from tsx-tabs) — store for pairing with following JS block
-          pendingTsx = { html: codeBlock.code.trim(), renderData }
-        } else if (codeBlock.language === 'html') {
-          const code = codeBlock.code
-          const { html, js } = splitHtmlAndScript(code)
-
-          if (js) {
-            // Self-contained HTML block with inline <script> — add button now
-            pendingHtml = null
-            pendingTsx = null
-            addPlaygroundButton(renderData, html, js)
-          } else {
-            // HTML-only block — store for potential pairing with next JS block
-            pendingHtml = { html: code.trim(), renderData }
-          }
-        } else if (codeBlock.language === 'javascript' && (pendingHtml || pendingTsx)) {
-          // JS block after an HTML/TSX block — pair them
-          const js = codeBlock.code.trim()
-          if (js) {
-            if (pendingHtml) {
-              addPlaygroundButton(pendingHtml.renderData, pendingHtml.html, js)
-            }
-            if (pendingTsx) {
-              addPlaygroundButton(pendingTsx.renderData, pendingTsx.html, js)
-            }
-          }
-          pendingHtml = null
-          pendingTsx = null
-        } else {
-          // Any other block type breaks the pairing
-          pendingHtml = null
-          pendingTsx = null
+          addTsxButton(renderData.blockAst, codeBlock.code.trim())
+          return
+        }
+
+        if (codeBlock.language !== 'html') return
+
+        const { html, js } = splitHtmlAndScript(codeBlock.code)
+        if (js) {
+          addHtmlPlaygroundButton(renderData.blockAst, html, js)
+          return
+        }
+
+        const pairedJs = codeBlock.metaOptions.getString('playground-js')
+        if (pairedJs) {
+          addHtmlPlaygroundButton(
+            renderData.blockAst,
+            html,
+            Buffer.from(pairedJs, 'base64url').toString('utf8')
+          )
         }
       }
     }