diff --git a/.gitignore b/.gitignore index cf688e41..be48bc76 100644 --- a/.gitignore +++ b/.gitignore @@ -36,7 +36,7 @@ builds/**/meta .playwright-mcp .playwright-cli test-results/ -.claude/worktrees/ +.claude/ __screenshots__ .dts-tmp/ .nx/ diff --git a/tko.io/public/agents/contract.md b/tko.io/public/agents/contract.md index 69a47359..2863c00e 100644 --- a/tko.io/public/agents/contract.md +++ b/tko.io/public/agents/contract.md @@ -1,6 +1,6 @@ # TKO Agent Contract -Use this file when deciding how state, bindings, and DOM work should be divided in TKO examples and prototypes. +Use this file when deciding how to divide state, bindings, and DOM work in TKO examples and prototypes. ## Core Rule @@ -10,7 +10,8 @@ Use this file when deciding how state, bindings, and DOM work should be divided ## Replace X With Y -- This section is about replacing ad-hoc DOM/event/state handling with bindings, not about binding-syntax style. +Replace ad-hoc DOM/event/state handling with bindings. Not about binding-syntax style. + - If you are about to do `element.textContent = value`, use the `text` binding. - If you are about to do `element.innerHTML = markup`, first ask whether the content should be plain text instead; prefer the `text` binding by default. Use `html` only when rendering trusted HTML is truly the point. - If you are about to manually create, replace, or reconcile a repeated set of child nodes, use `foreach`. diff --git a/tko.io/public/agents/glossary.md b/tko.io/public/agents/glossary.md index e996d87e..3c01647a 100644 --- a/tko.io/public/agents/glossary.md +++ b/tko.io/public/agents/glossary.md @@ -1,7 +1,5 @@ # TKO Glossary -Domain-specific terms for the TKO (Typed Knockout) framework. - ## Core Concepts - **Observable** (`ko.observable(value)`) — a value wrapper that notifies subscribers when it changes. The fundamental reactive primitive. diff --git a/tko.io/public/agents/options.md b/tko.io/public/agents/options.md index 88d21d03..3d136b27 100644 --- a/tko.io/public/agents/options.md +++ b/tko.io/public/agents/options.md @@ -1,8 +1,6 @@ # `ko.options.*` — Configurable Runtime Options -`ko.options` is TKO's runtime configuration object. It is a singleton `Options` -instance defined in `packages/utils/src/options.ts`. This page documents how -to add new options and which of the two available mechanisms to reach for. +`ko.options` is TKO's runtime configuration singleton, defined in `packages/utils/src/options.ts`. Two mechanisms for adding options — this page explains which to reach for. ## Two mechanisms — when to use which diff --git a/tko.io/public/agents/process.md b/tko.io/public/agents/process.md index eb222f2a..399d826c 100644 --- a/tko.io/public/agents/process.md +++ b/tko.io/public/agents/process.md @@ -77,7 +77,7 @@ For pages with runnable TSX examples, also run the headless Playwright flow: - Use `playwright-cli` in headless mode. 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:4321` so markdown/plugin edits reload while you work (`bun run dev` in `tko.io/`). - Verify each `Open in Playground` button on the page; if a page has multiple TSX examples, check every one, not just the first. -- Standard 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`. +- Standard 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 `[data-role="status"]` (shows "esbuild ready"), `[data-role="compile-time"]`, and `[data-role="error-bar"]`. - Treat docs example work as incomplete until the emitted playground payload compiles cleanly on the live site. Generator-owned files: see the note at the top of this document under "Never ship docs that reference things that don't exist on the target branch." diff --git a/tko.io/public/agents/soul.md b/tko.io/public/agents/soul.md index c785c0b0..4cc092b1 100644 --- a/tko.io/public/agents/soul.md +++ b/tko.io/public/agents/soul.md @@ -1,9 +1,6 @@ # The Soul of Knockout -This document describes the philosophical foundation of Knockout and TKO. -Read this to understand *why* the framework works the way it does, not just -*how* to use it. If you're an AI agent working on this codebase, this is -the context behind every design decision. +Read this to understand *why* Knockout/TKO is shaped the way it is, not just *how* to use it. AI agents working on this codebase: this is the context behind every design decision. ## The Core Insight diff --git a/tko.io/public/agents/testing.md b/tko.io/public/agents/testing.md index e1dc3842..5573409b 100644 --- a/tko.io/public/agents/testing.md +++ b/tko.io/public/agents/testing.md @@ -35,7 +35,7 @@ Workflow: 3. Navigate Playwright to `http://localhost:8765/tko-test.html` 4. Read `document.title` or snapshot the DOM to verify -This is the fastest option — no esbuild and no network dependency on the playground, though Option 1 still fetches `https://tko.io/lib/tko.js` unless you vendor that file locally. Works for all `data-bind` code. +Fastest option — no esbuild, no playground. Still fetches `https://tko.io/lib/tko.js` unless vendored locally. Works for all `data-bind` code. ## Option 2: Playground via Playwright (JSX/TSX) @@ -53,22 +53,22 @@ const url = `https://tko.io/playground#${hash}` 4. The code auto-compiles and runs in the preview iframe 5. Read the iframe content or console output to verify -The playground forwards console messages from the iframe to the parent page — look for `#console-messages` in the DOM for console.log/error output. +The playground forwards console messages from the iframe to the parent page — look for `[data-role="console-messages"]` in the DOM for console.log/error output. ### Checking results -The preview iframe is `#preview`. To read its content: +The preview iframe is `[data-role="preview"]`. To read its content: ```js -const iframe = document.querySelector('#preview') +const iframe = document.querySelector('[data-role="preview"]') const body = iframe.contentDocument.body ``` -Console output appears in `#console-messages` as child elements. +Console output appears in `[data-role="console-messages"]` as child elements. ### Timing -esbuild-wasm takes a few seconds to initialize on first load. The playground shows "esbuild ready" in `#esbuild-status` when it's ready. Code auto-runs after compilation. +esbuild-wasm takes a few seconds to initialize on first load. The playground shows "esbuild ready" in `[data-role="status"]` when it's ready. Code auto-runs after compilation. ## Option 3: Testing doc page examples