From 6103b615f97271a23b167abddffc07209c309da5 Mon Sep 17 00:00:00 2001 From: Brian M Hunt Date: Wed, 1 Apr 2026 15:26:39 -0230 Subject: [PATCH 1/7] Add TKO 5 plan --- plans/tko-5-agent-first-release.md | 133 +++++++++++++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 plans/tko-5-agent-first-release.md diff --git a/plans/tko-5-agent-first-release.md b/plans/tko-5-agent-first-release.md new file mode 100644 index 000000000..000e9a76b --- /dev/null +++ b/plans/tko-5-agent-first-release.md @@ -0,0 +1,133 @@ +# Plan: TKO 5.0 as an Agent-First Modern Reference Release + +TKO 5.0 should make the current modern path official instead of continuing to balance two equal identities. The release should center on `@tko/build.reference`, freeze `@tko/build.knockout` on the 4.x line, and define TKO as a zero-runtime-dependency, browser-native, AI-friendly reactive UI framework with a fast path from idea to verified behavior. + +The goal is not to add novelty AI features around the framework. It is to make TKO unusually legible to both humans and agents by reducing legacy ambiguity, simplifying the product story, and tightening the development and verification loop. + +## Why 5.0 Exists Now + +TKO already contains most of the ingredients for a sharper 5.0 direction: + +- the reference build already reads as the modern path +- the repository already frames TKO as zero-runtime-dependency software +- the agent docs, verified behaviors, and browser-native TSX flows already exist +- the biggest remaining drag is historical ambiguity rather than missing capability + +4.0 is the right place to stabilize and publish the current architecture. 5.0 is the right place to declare a center of gravity: one canonical build, one primary docs path, one clearer standard for how TKO is authored, tested, documented, and verified. + +## Core Product Stance + +TKO 5.0 should optimize first for modern builders, especially AI-assisted and agentic workflows, without giving up the framework's existing strengths in modularity, explicit state-to-DOM contracts, and zero-runtime-dependency discipline. + +In practice, that means treating `@tko/build.reference` as the canonical package, keeping `@tko/build.knockout` on the 4.x line, preferring standardized modern JavaScript and native browser APIs, protecting the no-new-runtime-dependencies rule, and treating agent-facing docs plus verified behaviors as part of the product contract. High-OODA development matters: contributors should be able to move quickly from prompt or spec to executable example to focused verification. + +This makes TKO 5.0 less about a rewrite and more about removing uncertainty about what the project is for and how it should be used. + +## Major Changes + +### 1. Make the reference build the only first-class 5.0 build + +5.0 should stop presenting the reference build and the Knockout compatibility build as equal answers to the same question. + +- `@tko/build.reference` becomes the default install, default documentation target, and default recommendation in all product messaging +- `@tko/build.knockout` stays maintained on 4.x with explicit support boundaries, but it is no longer positioned as a co-equal future-facing build +- new examples, docs, and feature work should target the reference build unless there is a specific compatibility reason not to + +### 1.1 Version the docs experience around the release line + +The docs site should stop asking the top-level reader to choose between historical and modern product stories. + +- top-level `tko.io/` becomes the canonical TKO 5 documentation experience +- the current TKO 4 documentation moves under `tko.io/4/` +- TKO 4 docs should be sourced from a long-lived `v4` branch rather than kept interleaved with v5 docs in the same working tree +- the GitHub Pages deploy process should assemble the published site by building v5 from `main` and v4 from the `v4` branch, then publishing a combined artifact with v4 rooted at `/4` +- old unversioned v4-oriented documentation URLs should redirect into `/4/...` during the transition + +This keeps v5 free to speak clearly in the singular while preserving a stable, versioned place for migration and compatibility guidance. + +### 2. Preserve zero-runtime-dependency discipline + +TKO already operates very close to true runtime zero-dependency status. 5.0 should protect that property aggressively. + +- do not add new runtime dependencies to core packages or builds +- prefer native platform features over helper libraries where practical +- treat any remaining runtime-support dependencies as exceptions that must earn their place + +The real dependency reduction opportunity in 5.0 is likely to be in development and testing tooling, not in the runtime surface itself. + +### 3. Modernize around standard JavaScript and browser-native patterns + +TKO 5.0 should lean into the strengths already visible in the reference build: + +- ESM-first usage and distribution +- CSP-safe parsing and provider-driven binding evaluation +- native DOM and event paths by default +- native-provider and TSX-based authoring for modern browser-native UI development +- removal of historical special cases that exist primarily to preserve older Knockout expectations + +The standard should be clear: modern JavaScript first, compatibility second. + +### 4. Treat agent-facing documentation as a public interface + +TKO is unusually well-positioned for AI-assisted development because its core abstractions are explicit and testable. 5.0 should make that an intentional product advantage. + +- `llms.txt` should advertise the modern canonical path +- the agent guide should remain concise and code-first +- verified behaviors should serve as machine-readable behavioral truth +- the agent testing guide should document fast, focused verification flows + +The flagship AI workflow for 5.0 is not "chat with TKO." It is "spec to verified behavior" with minimal ambiguity. + +## Test And OODA Strategy + +5.0 should improve development speed and verification confidence without turning the release into a tooling rewrite project. + +The testing strategy should be: + +- standardize on one primary behavior authoring style +- keep runner migration incremental rather than making it the gating item for 5.0 +- preserve coverage while reducing the cognitive overhead of mixed legacy and modern test patterns +- expand fast browser-level verification where it improves confidence, especially for docs and playground-style examples + +This implies a layered approach: + +1. unify the style and shape of behavior tests +2. keep existing coverage intact during migration +3. adopt additional runners or browser-verification tools only when they improve the OODA loop + +The release should not be blocked on a full runner rewrite. If existing work is already moving tests toward a more unified style, 5.0 should benefit from that momentum without depending on total completion. + +## Migration Approach + +TKO 5.0 should make a clean product decision without forcing a harsh user experience. + +The migration posture should be documentation-first: + +- ship a strong migration guide for Knockout-style and older TKO users moving to the reference build +- publish a clear compatibility matrix that explains which path stays on 4.x and which path moves to 5.0 +- use before-and-after examples to show modern equivalents for legacy build choices and authoring patterns +- keep migration help focused on guides, examples, and explicit support boundaries rather than on a long-lived compatibility layer +- align the docs with that posture by treating `/4/` as the preserved TKO 4 reference and `/` as the v5 canonical path + +This keeps the release honest. The break is real, but the path forward is well lit. + +## Acceptance Criteria + +TKO 5.0 is ready as a direction when the following statements are true: + +- there is one obvious answer to "which TKO build should I use?" and it is `@tko/build.reference` +- the legacy Knockout build has a clearly documented 4.x maintenance position +- no new runtime dependencies have been introduced for the 5.0 line +- the human docs path and the agent docs path tell the same story +- the published docs have a clear version boundary: v5 at `/` and v4 preserved at `/4/` +- verified behaviors and agent-facing docs are maintained as part of the public contract +- contributors can move from idea to example to focused verification without navigating multiple historical product paths +- migration guidance is strong enough that the clean break feels intentional instead of abrupt + +## Assumptions And Defaults + +- keep the canonical package identity as `@tko/build.reference` for 5.0 rather than introducing a package rename during the same release +- prefer migration guides and compatibility documentation over shipping a long-lived compatibility layer +- continue test modernization incrementally and do not make a complete runner replacement a hard prerequisite for 5.0 +- use the docs deployment pipeline to assemble a versioned published site rather than forcing v4 and v5 to coexist as one undifferentiated docs tree +- treat this document as a north-star product plan, not a fully sequenced execution program From f28066cfc7985557d4bb2ba7e8b69eafb8578354 Mon Sep 17 00:00:00 2001 From: Brian M Hunt Date: Wed, 1 Apr 2026 16:55:29 -0230 Subject: [PATCH 2/7] Add AI thesis docs --- plans/tko-5-agent-first-release.md | 1 + tko.io/public/agents/thesis.md | 32 ++++++++++++++++++++++++++++++ tko.io/public/llms.txt | 5 +++++ 3 files changed, 38 insertions(+) create mode 100644 tko.io/public/agents/thesis.md diff --git a/plans/tko-5-agent-first-release.md b/plans/tko-5-agent-first-release.md index 000e9a76b..f2c7aff7f 100644 --- a/plans/tko-5-agent-first-release.md +++ b/plans/tko-5-agent-first-release.md @@ -108,6 +108,7 @@ The migration posture should be documentation-first: - use before-and-after examples to show modern equivalents for legacy build choices and authoring patterns - keep migration help focused on guides, examples, and explicit support boundaries rather than on a long-lived compatibility layer - align the docs with that posture by treating `/4/` as the preserved TKO 4 reference and `/` as the v5 canonical path +- clean up the npm package surface so deprecated or legacy package names clearly point users toward the canonical 5.0 path This keeps the release honest. The break is real, but the path forward is well lit. diff --git a/tko.io/public/agents/thesis.md b/tko.io/public/agents/thesis.md new file mode 100644 index 000000000..5459750ff --- /dev/null +++ b/tko.io/public/agents/thesis.md @@ -0,0 +1,32 @@ +# TKO Thesis + +TKO treats Knockout as a reactive DOM substrate that is particularly well-suited to AI-assisted authoring, verification, and rapid iteration. + +This thesis starts from a simple observation: Knockout emerged very early in the evolution of frontend frameworks. Many later frameworks evolved toward the needs of human operators and human-scaled organizations: larger abstraction layers, heavier build assumptions, stronger framework ownership of application structure, and patterns optimized for large teams writing and reviewing code by hand. + +TKO takes a different view. It treats the Knockout model as valuable not because it is old, but because it is generic: + +- observables and computeds are explicit state primitives +- bindings are an explicit bridge between state and the DOM +- the runtime surface is comparatively small and inspectable +- behavior can be verified directly at the DOM and contract level + +These traits make TKO unusually compatible with AI-first workflows. Agents do better when systems are: + +- explicit rather than magical +- local rather than framework-global +- composable rather than heavily prescriptive +- easy to inspect at runtime +- easy to verify from behavior + +That does not mean older Knockout-era design should be preserved unchanged. TKO re-evolves from that substrate for a new environment: modern JavaScript, CSP-safe parsing, native browser APIs, TSX authoring, verified behavior contracts, and fast browser-level feedback loops. + +In practice, this thesis leads to a few design principles: + +- prefer explicit contracts over hidden machinery +- prefer browser-native flows over mandatory toolchain complexity +- prefer verifiable examples over illustrative but fragile snippets +- prefer modular primitives over organization-shaped abstractions +- prefer machine-readable behavior contracts alongside human docs + +The goal is not nostalgia. The goal is to make reactive UI development easier to generate, inspect, test, and evolve in a world where code and product flows are increasingly AI-assisted. diff --git a/tko.io/public/llms.txt b/tko.io/public/llms.txt index 689020ede..331e771a2 100644 --- a/tko.io/public/llms.txt +++ b/tko.io/public/llms.txt @@ -4,6 +4,9 @@ > reactive data binding and UI templating with zero runtime dependencies. TKO > uniquely enables building complex UIs directly in the browser using TSX and > esbuild-wasm, with no local toolchain required. +> +> TKO treats Knockout as a reactive DOM substrate that is particularly well-suited +> to AI-assisted authoring, verification, and rapid iteration. ## Quick Start @@ -16,6 +19,8 @@ - Verified Behaviors Index: /agents/verified-behaviors/index.md Unit-test-backed behavior contract. Prefer this when behavior questions matter. +- Thesis: /agents/thesis.md + Why TKO treats Knockout as an AI-friendly reactive DOM substrate. - Agent Guide: /agents/guide.md API reference, gotchas, and examples. - Agent Testing: /agents/testing.md From 33a7caf7e21d60f186984870359cda0d1f10b7e3 Mon Sep 17 00:00:00 2001 From: Brian M Hunt Date: Wed, 1 Apr 2026 17:20:43 -0230 Subject: [PATCH 3/7] Refine AI thesis --- tko.io/public/agents/thesis.md | 67 ++++++++++++++++++++++++++++++++-- 1 file changed, 63 insertions(+), 4 deletions(-) diff --git a/tko.io/public/agents/thesis.md b/tko.io/public/agents/thesis.md index 5459750ff..dd6224828 100644 --- a/tko.io/public/agents/thesis.md +++ b/tko.io/public/agents/thesis.md @@ -4,7 +4,7 @@ TKO treats Knockout as a reactive DOM substrate that is particularly well-suited This thesis starts from a simple observation: Knockout emerged very early in the evolution of frontend frameworks. Many later frameworks evolved toward the needs of human operators and human-scaled organizations: larger abstraction layers, heavier build assumptions, stronger framework ownership of application structure, and patterns optimized for large teams writing and reviewing code by hand. -TKO takes a different view. It treats the Knockout model as valuable not because it is old, but because it is generic: +TKO treats the Knockout observable and binding model as a foundational design principle for high-velocity abstraction of complex interactions: - observables and computeds are explicit state primitives - bindings are an explicit bridge between state and the DOM @@ -19,9 +19,29 @@ These traits make TKO unusually compatible with AI-first workflows. Agents do be - easy to inspect at runtime - easy to verify from behavior -That does not mean older Knockout-era design should be preserved unchanged. TKO re-evolves from that substrate for a new environment: modern JavaScript, CSP-safe parsing, native browser APIs, TSX authoring, verified behavior contracts, and fast browser-level feedback loops. +TKO builds from that substrate for a modern environment: modern JavaScript, CSP-safe parsing, native browser APIs, TSX authoring, verified behavior contracts, and fast browser-level feedback loops. -In practice, this thesis leads to a few design principles: +## Why TKO Fits AI-First Work + +TKO fits best when the task benefits from: + +- explicit reactive state +- direct DOM binding +- simple state-to-UI mental model that scales well +- browser-native execution +- easy runtime inspection +- fast behavior verification + +## Weaker Fit + +TKO is a weaker fit when the task depends on: + +- a project already deeply committed to another frontend runtime and unwilling to introduce a bridge layer +- drop-in use of an ecosystem centered on another framework's component model +- a development model that assumes a framework-managed application shell rather than an explicit state-to-DOM binding model +- avoiding the cost of introducing a second UI paradigm into an existing framework-dominant codebase + +## Design Principles - prefer explicit contracts over hidden machinery - prefer browser-native flows over mandatory toolchain complexity @@ -29,4 +49,43 @@ In practice, this thesis leads to a few design principles: - prefer modular primitives over organization-shaped abstractions - prefer machine-readable behavior contracts alongside human docs -The goal is not nostalgia. The goal is to make reactive UI development easier to generate, inspect, test, and evolve in a world where code and product flows are increasingly AI-assisted. +## What This Means For Agents + +Agents should be able to understand a TKO program by following a short chain: + +1. find the observables and computeds +2. find the bindings that connect that state to the DOM +3. run the code and verify the resulting behavior + +That favors authoring patterns with strong locality and low ambiguity: + +- keep state explicit and near the bindings that consume it +- put derived UI values in computeds instead of burying logic in ad hoc expressions +- prefer small DOM islands over framework-wide hidden coordination +- prefer bindings and providers that make the DOM contract easy to read back from the rendered output +- prefer examples that an agent can execute with minimal setup and no missing scaffolding + +For new UI, this generally points toward TSX plus `ko-*` bindings and the native provider path. For migration and comparison work, classic `data-bind` remains useful because it expresses the same state-to-DOM contract in a runtime-readable form. + +TKO can be organized into multiple architectural shapes. TKO is responsible for providing the primitives. The consuming agent is responsible for choosing an architecture that fits the system's scale, integration needs, and future direction, then keeping that architecture coherent over time. + +## What This Means For TKO + +Optimize for regeneration, inspection, and proof: + +- docs should route agents quickly to the right layer: thesis, guide, testing flow, verified behaviors +- examples should be runnable, not merely illustrative +- playground links should round-trip cleanly from docs to execution +- behavior claims should have a stable contract source when possible +- package and docs versioning should reduce ambiguity about what guidance applies to which release line +- legacy package names and migration lanes should point clearly to the modern canonical path + +## What Good Agent Output Looks Like + +In TKO, useful AI-generated output is not just syntactically valid code. It should be: + +- easy for a human to inspect and extend later +- easy to verify from DOM behavior +- explicit about reactive dependencies +- light on framework ceremony +- aligned with the documented contract and versioned docs surface From a26ec56af733018943bdb8ad9c6c4c7320166199 Mon Sep 17 00:00:00 2001 From: Brian M Hunt Date: Wed, 1 Apr 2026 17:45:44 -0230 Subject: [PATCH 4/7] Revise llms.txt and related agent docs --- tko.io/public/agents/thesis.md | 4 +++- tko.io/public/agents/why.txt | 29 +++++++++++++++++++++++++++++ tko.io/public/llms.txt | 6 ++++-- 3 files changed, 36 insertions(+), 3 deletions(-) create mode 100644 tko.io/public/agents/why.txt diff --git a/tko.io/public/agents/thesis.md b/tko.io/public/agents/thesis.md index dd6224828..2b35bab18 100644 --- a/tko.io/public/agents/thesis.md +++ b/tko.io/public/agents/thesis.md @@ -69,11 +69,13 @@ For new UI, this generally points toward TSX plus `ko-*` bindings and the native TKO can be organized into multiple architectural shapes. TKO is responsible for providing the primitives. The consuming agent is responsible for choosing an architecture that fits the system's scale, integration needs, and future direction, then keeping that architecture coherent over time. +Use `/agents/why.txt` for the short “why or why not use TKO?” decision surface. Use this thesis for the deeper rationale behind the project and for contribution alignment. + ## What This Means For TKO Optimize for regeneration, inspection, and proof: -- docs should route agents quickly to the right layer: thesis, guide, testing flow, verified behaviors +- docs should route agents quickly to the right layer: thesis, why, guide, testing flow, verified behaviors - examples should be runnable, not merely illustrative - playground links should round-trip cleanly from docs to execution - behavior claims should have a stable contract source when possible diff --git a/tko.io/public/agents/why.txt b/tko.io/public/agents/why.txt new file mode 100644 index 000000000..b7cc5b03a --- /dev/null +++ b/tko.io/public/agents/why.txt @@ -0,0 +1,29 @@ +TKO is a good fit when you want explicit observable state, direct DOM bindings, and DOM-level verification without a framework-owned application shell. + +Use TKO when the task benefits from: +- explicit state-to-DOM wiring +- a simple state-to-UI mental model +- browser-native execution +- direct runtime inspection +- fast behavior verification +- agent-driven work where state, bindings, and rendered behavior should be easy to trace + +TKO can support large and complex applications when the codebase maintains clear module, ownership, and composition boundaries. TKO provides the reactive primitives. The consuming team or agent chooses the surrounding architecture. + +TKO is a weaker fit when the task depends on: +- an application already standardized on another frontend runtime and unwilling to introduce a bridge +- drop-in use of an ecosystem centered on another framework's component model +- another framework already owning rendering, routing, SSR or hydration, and the application shell +- a framework that prescribes routing, application shell, and component architecture as part of the runtime + +Default authoring path: +- New UI: TSX plus `ko-*` bindings and the native provider path +- Migration, comparison, or inspection work: classic `data-bind` +- TKO gives reactive primitives, not a full app architecture + +How to read a TKO app: +1. Find the observables and computeds. +2. Find the bindings that connect that state to the DOM. +3. Run the code and verify the resulting rendered behavior. + +Good TKO output keeps state explicit, puts derived UI values in computeds, uses bindings for DOM updates, and stays verifiable with DOM assertions. diff --git a/tko.io/public/llms.txt b/tko.io/public/llms.txt index 331e771a2..8ce8d616f 100644 --- a/tko.io/public/llms.txt +++ b/tko.io/public/llms.txt @@ -19,8 +19,10 @@ - Verified Behaviors Index: /agents/verified-behaviors/index.md Unit-test-backed behavior contract. Prefer this when behavior questions matter. -- Thesis: /agents/thesis.md - Why TKO treats Knockout as an AI-friendly reactive DOM substrate. +- Why: /agents/why.txt + Quick “why or why not use TKO?” decision surface. +- agents/thesis.md: /agents/thesis.md + Deeper rationale, genesis, and contribution alignment for the project. - Agent Guide: /agents/guide.md API reference, gotchas, and examples. - Agent Testing: /agents/testing.md From 8fbd878d34bdb42eb6d83a6727821c9cedfc0ec6 Mon Sep 17 00:00:00 2001 From: Brian M Hunt Date: Thu, 2 Apr 2026 11:43:39 -0230 Subject: [PATCH 5/7] Refine agent docs stack --- tko.io/public/agents/thesis.md | 79 ++++++++++++--------------------- tko.io/public/agents/why.txt | 6 +-- tko.io/public/llms.txt | 81 +++++++++------------------------- 3 files changed, 50 insertions(+), 116 deletions(-) diff --git a/tko.io/public/agents/thesis.md b/tko.io/public/agents/thesis.md index 2b35bab18..172faa3fa 100644 --- a/tko.io/public/agents/thesis.md +++ b/tko.io/public/agents/thesis.md @@ -1,52 +1,32 @@ # TKO Thesis -TKO treats Knockout as a reactive DOM substrate that is particularly well-suited to AI-assisted authoring, verification, and rapid iteration. +Use `/agents/why.txt` for the short “why or why not use TKO?” decision surface. This file explains why TKO exists, what direction it follows, and what kinds of contributions align with that direction. -This thesis starts from a simple observation: Knockout emerged very early in the evolution of frontend frameworks. Many later frameworks evolved toward the needs of human operators and human-scaled organizations: larger abstraction layers, heavier build assumptions, stronger framework ownership of application structure, and patterns optimized for large teams writing and reviewing code by hand. +## Core Thesis -TKO treats the Knockout observable and binding model as a foundational design principle for high-velocity abstraction of complex interactions: +TKO treats the Knockout observable and binding model as a foundational design principle for building complex interactions at high velocity: - observables and computeds are explicit state primitives - bindings are an explicit bridge between state and the DOM - the runtime surface is comparatively small and inspectable - behavior can be verified directly at the DOM and contract level -These traits make TKO unusually compatible with AI-first workflows. Agents do better when systems are: - -- explicit rather than magical -- local rather than framework-global -- composable rather than heavily prescriptive -- easy to inspect at runtime -- easy to verify from behavior - TKO builds from that substrate for a modern environment: modern JavaScript, CSP-safe parsing, native browser APIs, TSX authoring, verified behavior contracts, and fast browser-level feedback loops. -## Why TKO Fits AI-First Work - -TKO fits best when the task benefits from: - -- explicit reactive state -- direct DOM binding -- simple state-to-UI mental model that scales well -- browser-native execution -- easy runtime inspection -- fast behavior verification +## Why This Matters Now -## Weaker Fit +Frontend frameworks after Knockout often specialized around the needs of human-operated organizations: stronger framework ownership of structure, deeper build pipelines, and abstractions designed around handwritten code at team scale. -TKO is a weaker fit when the task depends on: +TKO is not a rejection of those systems. It is a different bet. -- a project already deeply committed to another frontend runtime and unwilling to introduce a bridge layer -- drop-in use of an ecosystem centered on another framework's component model -- a development model that assumes a framework-managed application shell rather than an explicit state-to-DOM binding model -- avoiding the cost of introducing a second UI paradigm into an existing framework-dominant codebase +TKO is designed to enable AI to OODA faster: observe, orient, decide, and act by keeping state, DOM wiring, and runtime behavior explicit and verifiable. ## Design Principles - prefer explicit contracts over hidden machinery - prefer browser-native flows over mandatory toolchain complexity - prefer verifiable examples over illustrative but fragile snippets -- prefer modular primitives over organization-shaped abstractions +- prefer modular primitives over abstractions shaped mainly by organizational overhead - prefer machine-readable behavior contracts alongside human docs ## What This Means For Agents @@ -57,37 +37,32 @@ Agents should be able to understand a TKO program by following a short chain: 2. find the bindings that connect that state to the DOM 3. run the code and verify the resulting behavior -That favors authoring patterns with strong locality and low ambiguity: +This favors explicit contracts, local reasoning, and examples that can be executed and verified with minimal hidden scaffolding. -- keep state explicit and near the bindings that consume it -- put derived UI values in computeds instead of burying logic in ad hoc expressions -- prefer small DOM islands over framework-wide hidden coordination -- prefer bindings and providers that make the DOM contract easy to read back from the rendered output -- prefer examples that an agent can execute with minimal setup and no missing scaffolding +## Contribution Alignment -For new UI, this generally points toward TSX plus `ko-*` bindings and the native provider path. For migration and comparison work, classic `data-bind` remains useful because it expresses the same state-to-DOM contract in a runtime-readable form. +Contributions that align with the thesis usually: -TKO can be organized into multiple architectural shapes. TKO is responsible for providing the primitives. The consuming agent is responsible for choosing an architecture that fits the system's scale, integration needs, and future direction, then keeping that architecture coherent over time. +- make reactive contracts clearer +- improve runtime inspectability +- strengthen verified behavior coverage +- make examples more runnable and easier to prove +- reduce unnecessary dependency or toolchain burden +- improve migration clarity or interop with surrounding systems -Use `/agents/why.txt` for the short “why or why not use TKO?” decision surface. Use this thesis for the deeper rationale behind the project and for contribution alignment. +Contributions that move away from the thesis usually: -## What This Means For TKO +- hide reactive behavior behind opaque abstractions +- add framework-owned architecture by default +- increase toolchain burden without improving verification or clarity +- multiply package, version, or docs ambiguity -Optimize for regeneration, inspection, and proof: +TKO should continue optimizing for regeneration, inspection, and proof: runnable examples, stable behavior contracts, clear docs routing, and lower ambiguity around packages, versions, and migration paths. -- docs should route agents quickly to the right layer: thesis, why, guide, testing flow, verified behaviors -- examples should be runnable, not merely illustrative -- playground links should round-trip cleanly from docs to execution -- behavior claims should have a stable contract source when possible -- package and docs versioning should reduce ambiguity about what guidance applies to which release line -- legacy package names and migration lanes should point clearly to the modern canonical path +## Evolutionary Analogy -## What Good Agent Output Looks Like +In biology, early ancestors are often more general and later descendants become more specialized for a particular environment. A classic example is feathers: early feathers appear to have evolved before bird flight, likely serving functions such as insulation, communication, or water repellency, and only later became aerodynamic structures for flight. The earlier substrate was not obsolete. It became newly valuable when the environment and use case changed. -In TKO, useful AI-generated output is not just syntactically valid code. It should be: +TKO treats Knockout in that way. Knockout appeared early in the evolution of frontend frameworks, before the ecosystem specialized around virtual DOMs, framework-owned application shells, and large convention-heavy toolchains. Its observable and binding model remained closer to a general reactive DOM substrate: explicit state, explicit DOM wiring, and direct behavioral verification. -- easy for a human to inspect and extend later -- easy to verify from DOM behavior -- explicit about reactive dependencies -- light on framework ceremony -- aligned with the documented contract and versioned docs surface +Later frontend frameworks specialized for different environmental pressures: larger human organizations, heavier build systems, framework-managed application structure, and ecosystem-scale coordination. The thesis of TKO is that AI-assisted development changes the environment. Agents need systems they can inspect, regenerate, verify, and evolve directly. In that environment, Knockout's earlier observable-and-binding substrate becomes newly fit for the same reason early feathers did: a general structure developed under one set of pressures becomes newly fit under another. diff --git a/tko.io/public/agents/why.txt b/tko.io/public/agents/why.txt index b7cc5b03a..864d6a47f 100644 --- a/tko.io/public/agents/why.txt +++ b/tko.io/public/agents/why.txt @@ -8,18 +8,16 @@ Use TKO when the task benefits from: - fast behavior verification - agent-driven work where state, bindings, and rendered behavior should be easy to trace -TKO can support large and complex applications when the codebase maintains clear module, ownership, and composition boundaries. TKO provides the reactive primitives. The consuming team or agent chooses the surrounding architecture. +TKO can support large and complex applications when the codebase maintains clear module boundaries, ownership, and composition rules. TKO gives reactive primitives rather than a full application architecture. TKO is a weaker fit when the task depends on: - an application already standardized on another frontend runtime and unwilling to introduce a bridge - drop-in use of an ecosystem centered on another framework's component model -- another framework already owning rendering, routing, SSR or hydration, and the application shell -- a framework that prescribes routing, application shell, and component architecture as part of the runtime +- another framework already owning rendering, routing, SSR or hydration, and the application shell, so adding TKO would introduce a second mental model and explicit bridges for state, events, styling, or lifecycle Default authoring path: - New UI: TSX plus `ko-*` bindings and the native provider path - Migration, comparison, or inspection work: classic `data-bind` -- TKO gives reactive primitives, not a full app architecture How to read a TKO app: 1. Find the observables and computeds. diff --git a/tko.io/public/llms.txt b/tko.io/public/llms.txt index 8ce8d616f..e020ccad2 100644 --- a/tko.io/public/llms.txt +++ b/tko.io/public/llms.txt @@ -1,28 +1,16 @@ -# TKO (Typed Knockout) +# TKO (Technical Knockout) -> TKO is the modern TypeScript successor to Knockout.js — an MVVM framework for -> reactive data binding and UI templating with zero runtime dependencies. TKO -> uniquely enables building complex UIs directly in the browser using TSX and -> esbuild-wasm, with no local toolchain required. -> -> TKO treats Knockout as a reactive DOM substrate that is particularly well-suited -> to AI-assisted authoring, verification, and rapid iteration. - -## Quick Start - -```html - - -``` +> TKO is a small reactive UI runtime built around observables, bindings, and +> DOM-level verification. ## Start Here -- Verified Behaviors Index: /agents/verified-behaviors/index.md - Unit-test-backed behavior contract. Prefer this when behavior questions matter. - Why: /agents/why.txt Quick “why or why not use TKO?” decision surface. -- agents/thesis.md: /agents/thesis.md +- Thesis: /agents/thesis.md Deeper rationale, genesis, and contribution alignment for the project. +- Verified Behaviors Index: /agents/verified-behaviors/index.md + Unit-test-backed behavior contract. Prefer this when behavior questions matter. - Agent Guide: /agents/guide.md API reference, gotchas, and examples. - Agent Testing: /agents/testing.md @@ -30,18 +18,28 @@ - Agent TSX Scaffold: /agents/sample-tsx.html Minimal in-browser TSX + esbuild scaffold for rapid prototype work. -## Use This First +For fit questions, read `/agents/why.txt` first. For behavior disputes, trust `/agents/verified-behaviors/index.md` over prose docs. + +## Quick Start -- Behavior question or edge case: /agents/verified-behaviors/index.md -- API usage or authoring pattern: /agents/guide.md -- Verification or test flow: /agents/testing.md -- Rapid prototype in-browser: /agents/sample-tsx.html +```html + + +``` ## Build Choice - Use `@tko/build.reference` for modern TKO, including TSX, `ko-*`, and the native provider path. - Use `@tko/build.knockout` for compatibility-oriented Knockout-style work. +## Core Contract + +- TKO connects reactive state to the DOM. +- Observables, observableArrays, and computeds are the state layer. +- Bindings are the DOM integration layer. +- TKO does not prescribe routing, data loading, SSR strategy, or the application shell. +- In TSX, `tko.jsx.render()` creates DOM nodes and `ko.applyBindings({}, root)` activates the `ko-*` bindings on that DOM. + ## Common Gotchas - Derived `ko-*` values must stay observable or computed. `ko-text={price() > 50 ? 'expensive' : 'cheap'}` freezes; use a computed. @@ -55,46 +53,9 @@ - Binding parsing and provider selection: `@tko/provider.*`, `@tko/utils.parser` - TSX and JSX rendering: `@tko/utils.jsx`, `@tko/provider.native` -## URLs - -- Verified Behaviors: /agents/verified-behaviors/index.md (package-scoped index) -- Agent Guide: /agents/guide.md (API reference, gotchas, examples) -- Agent Testing: /agents/testing.md (how to run and verify TKO code) -- Agent TSX Scaffold: /agents/sample-tsx.html (minimal browser TSX + esbuild scaffold for rapid prototype work) -- Playground: /playground -- GitHub: https://github.com/knockout/tko - -## Core Contract - -- TKO is responsible for connecting state to the DOM. -- Observables, observableArrays, and computeds are the state layer. -- Bindings are the DOM integration layer: they read state, update DOM, and write user-driven changes back to state. -- `bindingHandlers` are the bridge between the DOM and the observable state layer. -- `ko.applyBindings(viewModel, element)` activates that bridge on an existing DOM subtree. -- In TSX, `tko.jsx.render()` creates DOM nodes and `ko.applyBindings({}, root)` then activates the `ko-*` bindings on that rendered DOM. - ## Two Binding Syntaxes HTML: `data-bind="text: msg"` — runtime strings, works with `ko.applyBindings(vm, el)` TSX: `ko-text={msg}` — compile-time JSX expressions, needs esbuild + `tko.jsx.render()` Inside `ko-foreach` children, binding-context vars use strings: `ko-text="$data"` (not `{$data}`) - -See /agents/guide.md for usage patterns. -Use /agents/verified-behaviors/index.md for test-backed behavior contracts. - -## Docs - -/observables/ · /computed/ · /bindings/ · /components/ · /binding-context/ · /advanced/ - -## Browser JSX (esbuild-wasm) - -```js -import * as esbuild from 'https://cdn.jsdelivr.net/npm/esbuild-wasm@0.27.4/esm/browser.min.js' -await esbuild.initialize({ wasmURL: 'https://cdn.jsdelivr.net/npm/esbuild-wasm@0.27.4/esbuild.wasm' }) -const result = await esbuild.transform(tsxCode, { - loader: 'tsx', - jsxFactory: 'tko.jsx.createElement', - jsxFragment: 'tko.jsx.Fragment' -}) -``` From 52803dfac67bb0b1ae995757eac0b13997061dbd Mon Sep 17 00:00:00 2001 From: Brian M Hunt Date: Thu, 2 Apr 2026 11:44:54 -0230 Subject: [PATCH 6/7] Add agent concepts doc --- tko.io/public/agents/concepts.md | 77 ++++++++++++++++++++++++++++++++ tko.io/public/agents/thesis.md | 2 +- tko.io/public/llms.txt | 2 + 3 files changed, 80 insertions(+), 1 deletion(-) create mode 100644 tko.io/public/agents/concepts.md diff --git a/tko.io/public/agents/concepts.md b/tko.io/public/agents/concepts.md new file mode 100644 index 000000000..f5773ba08 --- /dev/null +++ b/tko.io/public/agents/concepts.md @@ -0,0 +1,77 @@ +# TKO Concepts + +This file explains the core concepts that sit between the thesis and the API guide: what TKO is responsible for, what the consuming application is responsible for, and how TKO systems are typically composed. + +## Core Split + +TKO provides reactive primitives and DOM wiring. It does not provide a full application architecture. + +- TKO owns observables, computeds, bindings, providers, and DOM activation +- the consuming application owns routing, data loading, SSR strategy, application shell, and large-scale feature composition + +This is the main architectural boundary to keep in mind when designing with TKO. + +## State And DOM + +TKO is built around a direct state-to-DOM model. + +- observables and computed values hold reactive state +- bindings connect that state to the DOM +- `ko.applyBindings(...)` activates that connection on a DOM subtree + +The important idea is that reactive dependencies should stay visible. State is explicit. DOM wiring is explicit. Behavior can be verified from rendered output. + +## Two Authoring Paths + +TKO supports two main authoring styles. + +- `data-bind` + Runtime binding strings. Best for migration, comparison work, and HTML-first code. +- `ko-*` in TSX + Compile-time expressions carried through the native provider path. Best for new UI where you want explicit variables in scope and browser-native TSX authoring. + +These are different authoring surfaces for the same underlying state-to-DOM model. + +## Providers + +Providers determine how TKO discovers bindings on DOM nodes. + +- `DataBindProvider` supports classic `data-bind` +- `NativeProvider` supports `ko-*` attributes on JSX-generated DOM +- other providers support comment bindings, custom elements, mustache-like forms, and provider composition + +Providers are part of TKO's flexibility. They let the same runtime model appear through different syntaxes without changing the underlying reactive contract. + +## Composition + +TKO composes well when boundaries stay explicit. + +- use observables and computeds for local feature state +- keep DOM ownership boundaries coherent +- prefer modules and feature slices that are easy to inspect independently +- treat bindings as the visible contract between state and UI + +Large systems can be built from these pieces, but TKO does not impose the top-level structure for doing so. + +## Verification Model + +TKO is designed to be verified from behavior rather than hidden internal machinery. + +- inspect state through observables and computeds +- inspect UI behavior through DOM output +- use verified behaviors when questions of contract matter +- use guide and testing docs for API and execution details + +For agents, the normal reading order is: + +1. find the state +2. find the bindings or provider path +3. inspect the rendered behavior + +## Relationship To Other Agent Docs + +- [`/agents/why.txt`](/agents/why.txt): quick fit and anti-fit guidance +- [`/agents/thesis.md`](/agents/thesis.md): project rationale and contribution alignment +- [`/agents/guide.md`](/agents/guide.md): API usage and gotchas +- [`/agents/testing.md`](/agents/testing.md): verification flows +- [`/agents/verified-behaviors/index.md`](/agents/verified-behaviors/index.md): test-backed behavior contract diff --git a/tko.io/public/agents/thesis.md b/tko.io/public/agents/thesis.md index 172faa3fa..c962ea0c9 100644 --- a/tko.io/public/agents/thesis.md +++ b/tko.io/public/agents/thesis.md @@ -1,6 +1,6 @@ # TKO Thesis -Use `/agents/why.txt` for the short “why or why not use TKO?” decision surface. This file explains why TKO exists, what direction it follows, and what kinds of contributions align with that direction. +Use `/agents/why.txt` for the short “why or why not use TKO?” decision surface. Use `/agents/concepts.md` for architectural concepts and boundaries. This file explains why TKO exists, what direction it follows, and what kinds of contributions align with that direction. ## Core Thesis diff --git a/tko.io/public/llms.txt b/tko.io/public/llms.txt index e020ccad2..6ce7c2dc4 100644 --- a/tko.io/public/llms.txt +++ b/tko.io/public/llms.txt @@ -9,6 +9,8 @@ Quick “why or why not use TKO?” decision surface. - Thesis: /agents/thesis.md Deeper rationale, genesis, and contribution alignment for the project. +- Concepts: /agents/concepts.md + Architectural concepts, boundaries, and composition model. - Verified Behaviors Index: /agents/verified-behaviors/index.md Unit-test-backed behavior contract. Prefer this when behavior questions matter. - Agent Guide: /agents/guide.md From ce294b4e6eeee4ca1286884ca83dc7cb6c0f14af Mon Sep 17 00:00:00 2001 From: Brian M Hunt Date: Thu, 2 Apr 2026 11:51:07 -0230 Subject: [PATCH 7/7] Refine agent concepts docs --- tko.io/public/agents/concepts.md | 93 ++++++++++++++++--- tko.io/public/agents/guide.md | 2 +- tko.io/public/agents/testing.md | 2 +- tko.io/public/agents/thesis.md | 2 +- .../public/agents/verified-behaviors/index.md | 2 + tko.io/public/agents/why.txt | 2 + 6 files changed, 87 insertions(+), 16 deletions(-) diff --git a/tko.io/public/agents/concepts.md b/tko.io/public/agents/concepts.md index f5773ba08..db4133760 100644 --- a/tko.io/public/agents/concepts.md +++ b/tko.io/public/agents/concepts.md @@ -1,6 +1,23 @@ # TKO Concepts -This file explains the core concepts that sit between the thesis and the API guide: what TKO is responsible for, what the consuming application is responsible for, and how TKO systems are typically composed. +Use `/llms.txt` as the index for the full agent docs set. This file explains TKO's core concepts: what TKO is responsible for, what the consuming application is responsible for, and how TKO systems are typically composed. + +## Core Contract + +TKO's core contract is simple: + +- reactive state stays explicit +- DOM wiring stays explicit +- rendered behavior stays verifiable + +In practice, that means: + +- observables, observableArrays, subscribables, and computeds hold state and derived state +- bindings turn that state into DOM behavior +- providers decide how bindings are discovered on DOM nodes +- `ko.applyBindings(...)` activates that contract on a DOM subtree + +TKO does not prescribe routing, data loading, SSR or hydration strategy, styling system, or the application shell. Those are application concerns built around TKO's primitives. ## Core Split @@ -11,13 +28,35 @@ TKO provides reactive primitives and DOM wiring. It does not provide a full appl This is the main architectural boundary to keep in mind when designing with TKO. -## State And DOM +## Primitives + +The primitives that define TKO's model are: + +- `observable`, `observableArray`, and `subscribable` + Stateful values and notification sources. +- `computed`, `pureComputed`, and `when` + Derived state and reactive coordination. +- bindings and binding handlers + The DOM integration layer. Built-in bindings cover text, attributes, events, control flow, forms, templates, and components. Custom behavior can be added with binding handlers. +- `BindingContext` + The scope object that bindings read from as control-flow bindings create nested contexts. +- providers + Binding-discovery primitives. `DataBindProvider`, `NativeProvider`, `VirtualProvider`, `ComponentProvider`, mustache providers, and `MultiProvider` all map DOM nodes to binding accessors. +- `ko.applyBindings(...)` + Activates bindings against a DOM subtree and its binding context. +- `tko.jsx.render(...)`, `createElement`, and `Fragment` + The JSX/native render path that creates DOM nodes before binding activation. + +These primitives are intended to stay small, explicit, and composable. Higher-level application structure is built from them rather than imposed above them. + +## State, Binding, And Activation TKO is built around a direct state-to-DOM model. - observables and computed values hold reactive state -- bindings connect that state to the DOM -- `ko.applyBindings(...)` activates that connection on a DOM subtree +- bindings define how that state affects text, attributes, events, structure, and child contexts +- providers discover those bindings on DOM nodes +- `ko.applyBindings(...)` activates the resulting binding graph on a DOM subtree The important idea is that reactive dependencies should stay visible. State is explicit. DOM wiring is explicit. Behavior can be verified from rendered output. @@ -38,9 +77,40 @@ Providers determine how TKO discovers bindings on DOM nodes. - `DataBindProvider` supports classic `data-bind` - `NativeProvider` supports `ko-*` attributes on JSX-generated DOM -- other providers support comment bindings, custom elements, mustache-like forms, and provider composition +- `VirtualProvider` supports comment bindings +- `ComponentProvider` supports custom elements +- mustache providers support mustache-style interpolation +- `MultiProvider` composes multiple provider strategies into one binding pipeline + +Providers are part of TKO's flexibility. They let the same runtime model appear through different syntaxes without changing the underlying reactive contract. A provider maps DOM nodes to binding accessors; provider composition lets one app support multiple syntaxes at once. + +## View Components + +TKO supports view components today, and they are likely to become more central as TKO 5 strengthens lifecycle boundaries. + +The current component surface includes: + +- the `component` binding +- `ComponentProvider` for custom-element style component discovery +- `ComponentABC` and the component registry utilities +- class-based `BindingHandler` and `AsyncBindingHandler` patterns for component-like DOM ownership + +The important concept is that a view component is a DOM ownership boundary, not a replacement for the core contract. Components still sit on top of the same primitives: + +- observable and computed state +- bindings and binding contexts +- provider-driven node discovery +- DOM activation and disposal + +In that sense, components are a composition tool for packaging UI, local state, template structure, and lifecycle-sensitive DOM work into a reusable unit. + +For TKO 5, the likely direction is stronger lifecycle clarity around those units: + +- clearer setup and disposal boundaries +- stronger ownership of subscriptions, computeds, DOM listeners, and descendant activation +- more explicit component-level contracts for mount, update, and cleanup -Providers are part of TKO's flexibility. They let the same runtime model appear through different syntaxes without changing the underlying reactive contract. +The core idea does not change. Components should make the primitive model easier to organize at scale, not hide it behind a separate framework layer. ## Composition @@ -58,6 +128,7 @@ Large systems can be built from these pieces, but TKO does not impose the top-le TKO is designed to be verified from behavior rather than hidden internal machinery. - inspect state through observables and computeds +- inspect provider and binding choice when syntax questions matter - inspect UI behavior through DOM output - use verified behaviors when questions of contract matter - use guide and testing docs for API and execution details @@ -65,13 +136,9 @@ TKO is designed to be verified from behavior rather than hidden internal machine For agents, the normal reading order is: 1. find the state -2. find the bindings or provider path +2. find the binding and provider path 3. inspect the rendered behavior -## Relationship To Other Agent Docs +## Index -- [`/agents/why.txt`](/agents/why.txt): quick fit and anti-fit guidance -- [`/agents/thesis.md`](/agents/thesis.md): project rationale and contribution alignment -- [`/agents/guide.md`](/agents/guide.md): API usage and gotchas -- [`/agents/testing.md`](/agents/testing.md): verification flows -- [`/agents/verified-behaviors/index.md`](/agents/verified-behaviors/index.md): test-backed behavior contract +Use `/llms.txt` as the index for the rest of the agent docs. diff --git a/tko.io/public/agents/guide.md b/tko.io/public/agents/guide.md index 693f5b051..03baa10ff 100644 --- a/tko.io/public/agents/guide.md +++ b/tko.io/public/agents/guide.md @@ -1,6 +1,6 @@ # TKO Agent Guide -Test-backed behavior summaries live under `/agents/verified-behaviors/`. Treat those files as the contract layer when prose docs and implementation need reconciliation. +Use `/llms.txt` as the index for the full agent docs set. Treat the verified behaviors docs as the contract layer when prose docs and implementation need reconciliation. ## Setup diff --git a/tko.io/public/agents/testing.md b/tko.io/public/agents/testing.md index e1dc3842f..5c0feb591 100644 --- a/tko.io/public/agents/testing.md +++ b/tko.io/public/agents/testing.md @@ -1,6 +1,6 @@ # TKO Agent Testing Guide -How to run and verify TKO code without human interaction. +Use `/llms.txt` as the index for the full agent docs set. This file explains how to run and verify TKO code without human interaction. ## Option 1: Static HTML file (data-bind, no JSX) diff --git a/tko.io/public/agents/thesis.md b/tko.io/public/agents/thesis.md index c962ea0c9..3fdf1ec7b 100644 --- a/tko.io/public/agents/thesis.md +++ b/tko.io/public/agents/thesis.md @@ -1,6 +1,6 @@ # TKO Thesis -Use `/agents/why.txt` for the short “why or why not use TKO?” decision surface. Use `/agents/concepts.md` for architectural concepts and boundaries. This file explains why TKO exists, what direction it follows, and what kinds of contributions align with that direction. +Use `/llms.txt` as the index for the full agent docs set. This file explains why TKO exists, what direction it follows, and what kinds of contributions align with that direction. ## Core Thesis diff --git a/tko.io/public/agents/verified-behaviors/index.md b/tko.io/public/agents/verified-behaviors/index.md index c0a70c313..e6f766036 100644 --- a/tko.io/public/agents/verified-behaviors/index.md +++ b/tko.io/public/agents/verified-behaviors/index.md @@ -1,5 +1,7 @@ # Verified Behaviors Index +Use `/llms.txt` as the index for the full agent docs set. + > Generated from package discovery plus package-local curated unit-test-backed JSON. > If a behavior is not covered by unit tests, it does not belong in this directory. diff --git a/tko.io/public/agents/why.txt b/tko.io/public/agents/why.txt index 864d6a47f..307543f8a 100644 --- a/tko.io/public/agents/why.txt +++ b/tko.io/public/agents/why.txt @@ -1,3 +1,5 @@ +Use `/llms.txt` as the index for the full agent docs set. + TKO is a good fit when you want explicit observable state, direct DOM bindings, and DOM-level verification without a framework-owned application shell. Use TKO when the task benefits from: