From 87d2baa35e125ffd2980375dc3eaea97f4c22c82 Mon Sep 17 00:00:00 2001
From: phillipc <phillipc@gmx.de>
Date: Thu, 16 Jul 2026 19:27:39 +0200
Subject: [PATCH 1/2] docs: update descendantsComplete behavior and migration
 guidance for TKO

---
 tko.io/src/content/docs/3to4.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/tko.io/src/content/docs/3to4.md b/tko.io/src/content/docs/3to4.md
index 024cd6c10..51e35fe98 100644
--- a/tko.io/src/content/docs/3to4.md
+++ b/tko.io/src/content/docs/3to4.md
@@ -54,6 +54,30 @@ TKO is designed for stricter Content Security Policies and avoids the older `eva
 
 `ko.applyBindings` returns a `Promise`. If you chain bootstrap work after binding or need to wait for async bindings to finish, account for that in your startup flow.
 
+### `descendantsComplete` no longer waits for async descendants
+
+In Knockout 3, `descendantsComplete` fired only after every descendant — including content rendered asynchronously by a nested `if`, `template`, `foreach`, or component — had finished binding. Knockout tracked this with an ancestor-linked async-completion context and, on control-flow bindings, a `completeOn: 'render'` option.
+
+TKO drops that ancestor-tracking machinery in favor of a simpler per-node model. As a result, `descendantsComplete` is decided **once**, synchronously, when the node itself binds, and waits only for async bindings **on that same node** — not for subtrees that appear later. If a descendant `if`/`template` renders its content after the fact (for example when its condition flips to `true`), the `descendantsComplete` callback is not re-triggered and will not fire.
+
+**Why:** the async-completion context was cross-cutting, hard to reason about, and a common source of disposal and ordering bugs. The per-node lifecycle is smaller and predictable, at the cost of this one edge case.
+
+**Migration:** use `childrenComplete` instead, which is notified every time a node's descendants are (re-)bound and therefore still fires when async content renders:
+
+```html
+<!-- Knockout 3: relied on descendantsComplete firing after nested async content -->
+<div data-bind="if: ready, descendantsComplete: onReady">
+  <div data-bind="if: innerReady">…</div>
+</div>
+```
+
+```html
+<!-- TKO: move the callback to the node whose children you care about -->
+<div data-bind="if: ready">
+  <div data-bind="if: innerReady, childrenComplete: onReady">…</div>
+</div>
+```
+
 ## What is still familiar
 
 - `ko.observable`, `ko.observableArray`, and `ko.computed`

From 138631b20a39d90ba39c0d4c8fac5906e16698ce Mon Sep 17 00:00:00 2001
From: phillipc <phillipc@gmx.de>
Date: Sat, 18 Jul 2026 08:51:24 +0200
Subject: [PATCH 2/2] Restore Knockout 3.5 binding-lifecycle semantics for
 `descendantsComplete` and add `completeOn: "render"`.

---
 .changeset/binding-lifecycle-parity.md        |  37 +++
 .../components/componentBindingBehaviors.js   |  12 +-
 packages/bind/src/applyBindings.ts            | 104 ++++----
 packages/bind/src/bindingEvent.ts             | 127 +++++++++-
 packages/bind/verified-behaviors.json         |   3 +-
 .../binding.component/src/componentBinding.ts |  37 ++-
 .../binding.component/verified-behaviors.json |   8 +
 .../spec/descendantsCompleteBehaviors.ts      |  79 +++++-
 .../binding.core/src/descendantsComplete.ts   |  11 +-
 packages/binding.core/verified-behaviors.json |   5 +-
 .../src/ConditionalBindingHandler.ts          |  26 +-
 packages/binding.if/src/ifUnless.ts           |   4 +-
 packages/binding.if/src/with.ts               |   6 +-
 packages/binding.if/verified-behaviors.json   |   8 +
 .../2026-07-16-ko-binding-lifecycle-parity.md | 234 ++++++++++++++++++
 .../2026-07-18-template-completeon-parity.md  |  69 ++++++
 tko.io/public/agents/guide.md                 |   1 +
 .../public/agents/verified-behaviors/bind.md  |   2 +-
 .../verified-behaviors/binding-component.md   |   3 +
 .../agents/verified-behaviors/binding-core.md |   2 +-
 .../verified-behaviors/binding-foreach.md     |   2 +
 .../agents/verified-behaviors/binding-if.md   |   3 +
 tko.io/src/content/docs/3to4.md               |  26 +-
 .../docs/components/component-binding.md      |   2 +
 24 files changed, 700 insertions(+), 111 deletions(-)
 create mode 100644 .changeset/binding-lifecycle-parity.md
 create mode 100644 plans/2026-07-16-ko-binding-lifecycle-parity.md
 create mode 100644 plans/2026-07-18-template-completeon-parity.md

diff --git a/.changeset/binding-lifecycle-parity.md b/.changeset/binding-lifecycle-parity.md
new file mode 100644
index 000000000..6b89323be
--- /dev/null
+++ b/.changeset/binding-lifecycle-parity.md
@@ -0,0 +1,37 @@
+---
+"@tko/bind": minor
+"@tko/binding.if": minor
+"@tko/binding.component": minor
+"@tko/binding.core": minor
+---
+
+Restore Knockout 3.5 binding-lifecycle semantics for `descendantsComplete` and
+add `completeOn: "render"`.
+
+`@tko/bind` now owns the KO 3.5 async-completion bookkeeping
+(`bindingEvent.startPossiblyAsyncContentBinding` / `AsyncCompleteContext`).
+`childrenComplete` drives per-node tracking of pending async descendants, and
+`descendantsComplete` fires once a node's children **and** every
+asynchronously-completing descendant (components, conditionals) have bound.
+
+Behavior changes to be aware of:
+
+- **`descendantsComplete` re-arms per content cycle.** Previously it fired at
+  most once (when the initial binding pass settled), and never fired for a
+  conditional that started false. It now fires each time a node renders content
+  — a nested `if` becoming true re-fires the ancestor's `descendantsComplete`,
+  and toggling a conditional off then on fires it again. Consumers who attached
+  one-shot `descendantsComplete` callbacks may see additional calls.
+- **`completeOn: "render"`** is now supported on `if`/`ifnot`/`with`. It defers
+  the node's `childrenComplete` (and any ancestor `descendantsComplete`, or a
+  component's `koDescendantsComplete`) until the binding actually renders
+  content. `completeOn` is a reserved binding key (as in KO 3.5).
+- A component viewmodel's **`koDescendantsComplete`** now fires via the
+  element's `descendantsComplete` event, so inner components complete before
+  their outer component (KO 3.5 ordering), including across intermediate
+  bindings and several nesting layers.
+
+Fixes the root cause behind
+[#414](https://github.com/knockout/tko/issues/414): `koDescendantsComplete` is
+no longer suppressed when a component template contains a conditional that
+starts false.
diff --git a/builds/knockout/spec/components/componentBindingBehaviors.js b/builds/knockout/spec/components/componentBindingBehaviors.js
index a3ef45967..065dd926d 100644
--- a/builds/knockout/spec/components/componentBindingBehaviors.js
+++ b/builds/knockout/spec/components/componentBindingBehaviors.js
@@ -295,9 +295,7 @@ describe('Components: Component binding', function () {
     expect(renderedCount).to.equal(1)
   })
 
-  // @mbest - This fails b/c `test-component`'s koDescendantsComplete is called
-  // after the test function completes.  Otherwise the result is correct.
-  it.skip("Inner components' koDescendantsComplete occurs before the outer component's", function () {
+  it("Inner components' koDescendantsComplete occurs before the outer component's", function () {
     after(function () {
       ko.components.unregister('sub-component')
     })
@@ -331,7 +329,7 @@ describe('Components: Component binding', function () {
     expect(renderedComponents).to.deep.equal(['sub-component1', 'sub-component2', 'test-component'])
   })
 
-  it.skip('koDescendantsComplete occurs after all inner components even if outer component is rendered synchronously', function () {
+  it('koDescendantsComplete occurs after all inner components even if outer component is rendered synchronously', function () {
     after(function () {
       ko.components.unregister('sub-component')
     })
@@ -400,7 +398,7 @@ describe('Components: Component binding', function () {
     expect(renderedComponents).to.deep.equal(['sub-component1', 'sub-component2', 'test-component'])
   })
 
-  it.skip('koDescendantsComplete waits for inner component to complete even if it is several layers down', function () {
+  it('koDescendantsComplete waits for inner component to complete even if it is several layers down', function () {
     after(function () {
       ko.components.unregister('sub-component')
     })
@@ -431,7 +429,7 @@ describe('Components: Component binding', function () {
     expect(renderedComponents).to.deep.equal(['sub-component1', 'test-component'])
   })
 
-  it.skip('koDescendantsComplete waits for inner components that are not yet loaded', function () {
+  it('koDescendantsComplete waits for inner components that are not yet loaded', function () {
     restoreAfter(window, 'require')
     after(function () {
       ko.components.unregister('sub-component')
@@ -997,7 +995,7 @@ describe('Components: Component binding', function () {
     expect(callbacks).to.deep.equal(1)
   })
 
-  it.skip("Does not call outer component's koDescendantsComplete function if an inner component is re-rendered", function () {
+  it("Does not call outer component's koDescendantsComplete function if an inner component is re-rendered", function () {
     after(function () {
       ko.components.unregister('sub-component')
     })
diff --git a/packages/bind/src/applyBindings.ts b/packages/bind/src/applyBindings.ts
index f469eb015..011e2d239 100644
--- a/packages/bind/src/applyBindings.ts
+++ b/packages/bind/src/applyBindings.ts
@@ -98,34 +98,35 @@ function applyBindingsToDescendantsInternal(
 ) {
   let nextInQueue: ChildNode | null = virtualElements.firstChild(elementOrVirtualElement)
 
-  if (!nextInQueue) {
-    return
-  }
+  if (nextInQueue) {
+    let currentChild: Node | null
+    const provider = getBindingProvider()
+    const preprocessNode = provider.preprocessNode
+
+    // Preprocessing allows a binding provider to mutate a node before bindings are applied to it. For example it's
+    // possible to insert new siblings after it, and/or replace the node with a different one. This can be used to
+    // implement custom binding syntaxes, such as {{ value }} for string interpolation, or custom element types that
+    // trigger insertion of <template> contents at that point in the document.
+    if (preprocessNode) {
+      while ((currentChild = nextInQueue)) {
+        nextInQueue = virtualElements.nextSibling(currentChild)
+        preprocessNode.call(provider, currentChild)
+      }
 
-  let currentChild: Node | null
-  const provider = getBindingProvider()
-  const preprocessNode = provider.preprocessNode
+      // Reset nextInQueue for the next loop
+      nextInQueue = virtualElements.firstChild(elementOrVirtualElement)
+    }
 
-  // Preprocessing allows a binding provider to mutate a node before bindings are applied to it. For example it's
-  // possible to insert new siblings after it, and/or replace the node with a different one. This can be used to
-  // implement custom binding syntaxes, such as {{ value }} for string interpolation, or custom element types that
-  // trigger insertion of <template> contents at that point in the document.
-  if (preprocessNode) {
     while ((currentChild = nextInQueue)) {
+      // Keep a record of the next child *before* applying bindings, in case the binding removes the current child from its position
       nextInQueue = virtualElements.nextSibling(currentChild)
-      preprocessNode.call(provider, currentChild)
+      applyBindingsToNodeAndDescendantsInternal(bindingContext, currentChild, asyncBindingsApplied)
     }
-
-    // Reset nextInQueue for the next loop
-    nextInQueue = virtualElements.firstChild(elementOrVirtualElement)
-  }
-
-  while ((currentChild = nextInQueue)) {
-    // Keep a record of the next child *before* applying bindings, in case the binding removes the current child from its position
-    nextInQueue = virtualElements.nextSibling(currentChild)
-    applyBindingsToNodeAndDescendantsInternal(bindingContext, currentChild, asyncBindingsApplied)
   }
 
+  // Notify childrenComplete unconditionally (KO parity) — a node that renders no
+  // content still reached a completed state, which the async-completion
+  // bookkeeping and `childrenComplete` subscribers need to observe.
   bindingEvent.notify(elementOrVirtualElement, bindingEvent.childrenComplete)
 }
 
@@ -157,9 +158,9 @@ function applyBindingsToNodeAndDescendantsInternal(
     isElement || // Case (1)
     hasBindings(nodeVerified) // Case (2)
 
-  const { shouldBindDescendants }: any = shouldApplyBindings
+  const { shouldBindDescendants, bindingContextForDescendants }: any = shouldApplyBindings
     ? applyBindingsToNodeInternal(nodeVerified, null, bindingContext, asyncBindingsApplied)
-    : { shouldBindDescendants: true }
+    : { shouldBindDescendants: true, bindingContextForDescendants: bindingContext }
 
   if (shouldBindDescendants && !bindingDoesNotRecurseIntoElementTypes[tagNameLower(nodeVerified as Element)]) {
     // We're recursing automatically into (real or virtual) child nodes without changing binding contexts. So,
@@ -168,7 +169,7 @@ function applyBindingsToNodeAndDescendantsInternal(
     //  * For children of a *virtual* element, we can't be sure. Evaluating .parentNode on those children may
     //    skip over any number of intermediate virtual elements, any of which might define a custom binding context,
     //    hence bindingContextsMayDifferFromDomParentElement is true
-    applyBindingsToDescendantsInternal(bindingContext, nodeVerified, asyncBindingsApplied)
+    applyBindingsToDescendantsInternal(bindingContextForDescendants, nodeVerified, asyncBindingsApplied)
   }
 }
 
@@ -276,6 +277,7 @@ function applyBindingsToNodeInternal<T>(
   }
 
   let bindingHandlerThatControlsDescendantBindings: string | undefined
+  let contextToExtend = bindingContext
   if (bindings) {
     const $component = bindingContext.$component || {}
 
@@ -324,8 +326,27 @@ function applyBindingsToNodeInternal<T>(
       )
     }
 
+    if (bindingEvent.descendantsComplete in bindings) {
+      // Register the node as (potentially) completing asynchronously and thread
+      // the resulting context to descendants so nested async content reports
+      // completion up to this node. The callback re-checks `firstChild` at fire
+      // time, so a conditional that renders nothing suppresses the callback yet
+      // still re-arms when it later renders content.
+      contextToExtend = bindingEvent.startPossiblyAsyncContentBinding(node, bindingContext)
+      bindingEvent.subscribe(
+        node,
+        bindingEvent.descendantsComplete,
+        () => {
+          const callback = evaluateValueAccessor(bindings![bindingEvent.descendantsComplete])
+          if (callback && virtualElements.firstChild(node)) {
+            callback(node)
+          }
+        },
+        null
+      )
+    }
+
     const bindingsGenerated = topologicalSortBindings(bindings, $component)
-    const nodeAsyncBindingPromises = new Set<Promise<any>>()
     for (const [key, BindingHandlerClass] of bindingsGenerated) {
       // Go through the sorted bindings, calling init and update for each
       const reportBindingError = function (during: string, errorCaptured: Error) {
@@ -351,7 +372,7 @@ function applyBindingsToNodeInternal<T>(
             new BindingHandlerClass({
               allBindings,
               $element: node,
-              $context: bindingContext,
+              $context: contextToExtend,
               onError: reportBindingError,
               valueAccessor(...v) {
                 return getValueAccessor(key)(...v)
@@ -381,43 +402,18 @@ function applyBindingsToNodeInternal<T>(
 
         if (bindingHandler.bindingCompleted instanceof Promise) {
           asyncBindingsApplied!.add(bindingHandler.bindingCompleted)
-          nodeAsyncBindingPromises.add(bindingHandler.bindingCompleted)
         }
       } catch (err) {
         const error = err instanceof Error ? err : new Error(String(err))
         reportBindingError('creation', error)
       }
     }
-
-    triggerDescendantsComplete(node, bindings, nodeAsyncBindingPromises)
   }
 
   const shouldBindDescendants = bindingHandlerThatControlsDescendantBindings === undefined
-  return { shouldBindDescendants }
-}
-
-/**
- *
- * @param {HTMLElement} node
- * @param {Object} bindings
- * @param {[Promise]} nodeAsyncBindingPromises
- */
-function triggerDescendantsComplete(node: Node, bindings: object, nodeAsyncBindingPromises: Set<Promise<any>>) {
-  /** descendantsComplete ought to be an instance of the descendantsComplete
-   *  binding handler. */
-  const hasBindingHandler = bindingEvent.descendantsComplete in bindings
-  const hasFirstChild = virtualElements.firstChild(node)
-  const accessor = hasBindingHandler && evaluateValueAccessor(bindings[bindingEvent.descendantsComplete])
-  const callback = () => {
-    bindingEvent.notify(node, bindingEvent.descendantsComplete)
-    if (accessor && hasFirstChild) {
-      accessor(node)
-    }
-  }
-  if (nodeAsyncBindingPromises.size) {
-    Promise.all(nodeAsyncBindingPromises).then(callback)
-  } else {
-    callback()
+  return {
+    shouldBindDescendants,
+    bindingContextForDescendants: shouldBindDescendants ? contextToExtend : bindingContext
   }
 }
 
diff --git a/packages/bind/src/bindingEvent.ts b/packages/bind/src/bindingEvent.ts
index 7fcb24471..d57cf2b01 100644
--- a/packages/bind/src/bindingEvent.ts
+++ b/packages/bind/src/bindingEvent.ts
@@ -1,10 +1,81 @@
-import { domData } from '@tko/utils'
-import { subscribable } from '@tko/observable'
-import type { Subscribable, Subscription, SubscriptionCallback } from '@tko/observable'
+import { domData, addDisposeCallback, removeDisposeCallback, arrayRemoveItem } from '@tko/utils'
+import { subscribable, dependencyDetection } from '@tko/observable'
+import type { Subscribable, Subscription } from '@tko/observable'
+import type { BindingContext } from './bindingContext'
 
 export const contextAncestorBindingInfo = Symbol('_ancestorBindingInfo')
 const boundElementDomDataKey = domData.nextKey()
 
+interface BindingInfo {
+  eventSubscribable?: Subscribable
+  notifiedEvents?: Record<string, boolean>
+  asyncContext?: AsyncCompleteContext | null
+}
+
+function asyncContextDispose(node: Node): void {
+  const bindingInfo = domData.get(node, boundElementDomDataKey) as BindingInfo | undefined
+  const asyncContext = bindingInfo && bindingInfo.asyncContext
+  if (asyncContext) {
+    bindingInfo!.asyncContext = null
+    asyncContext.notifyAncestor()
+  }
+}
+
+/**
+ * Per-node bookkeeping of pending asynchronously-completing descendants.
+ * Ported from Knockout 3.5 (`src/binding/bindingAttributeSyntax.js`); it lets
+ * `descendantsComplete` fire once a node's children *and* every async descendant
+ * (components, conditionals held open by `completeOn: "render"`) have bound.
+ */
+class AsyncCompleteContext {
+  node: Node
+  bindingInfo: BindingInfo
+  asyncDescendants: Node[] = []
+  childrenComplete = false
+  ancestorBindingInfo?: BindingInfo
+
+  constructor(node: Node, bindingInfo: BindingInfo, ancestorBindingInfo?: BindingInfo) {
+    this.node = node
+    this.bindingInfo = bindingInfo
+
+    if (!bindingInfo.asyncContext) {
+      addDisposeCallback(node, asyncContextDispose)
+    }
+
+    if (ancestorBindingInfo && ancestorBindingInfo.asyncContext) {
+      ancestorBindingInfo.asyncContext.asyncDescendants.push(node)
+      this.ancestorBindingInfo = ancestorBindingInfo
+    }
+  }
+
+  notifyAncestor(): void {
+    if (this.ancestorBindingInfo && this.ancestorBindingInfo.asyncContext) {
+      this.ancestorBindingInfo.asyncContext.descendantComplete(this.node)
+    }
+  }
+
+  descendantComplete(node: Node): void {
+    arrayRemoveItem(this.asyncDescendants, node)
+    if (!this.asyncDescendants.length && this.childrenComplete) {
+      this.completeChildren()
+    }
+  }
+
+  completeChildren(): void {
+    this.childrenComplete = true
+    if (this.bindingInfo.asyncContext && !this.asyncDescendants.length) {
+      this.bindingInfo.asyncContext = null
+      removeDisposeCallback(this.node, asyncContextDispose)
+      bindingEvent.notify(this.node, bindingEvent.descendantsComplete)
+      this.notifyAncestor()
+    }
+  }
+}
+
+export interface BindingEventSubscribeOptions {
+  notifyImmediately?: boolean
+}
+
 export const bindingEvent = {
   //TODO better: String-Enum "BindingEventEnum"
   childrenComplete: 'childrenComplete',
@@ -14,21 +85,59 @@ export const bindingEvent = {
     node: Node,
     event: string | 'childrenComplete' | 'descendantsComplete',
     callback: (node: Node) => void,
-    callbackContext?: any
+    callbackContext?: any,
+    options?: BindingEventSubscribeOptions
   ): Subscription {
-    const bindingInfo = domData.getOrSet(node, boundElementDomDataKey, {})
+    const bindingInfo = domData.getOrSet(node, boundElementDomDataKey, {}) as BindingInfo
     if (!bindingInfo.eventSubscribable) {
       bindingInfo.eventSubscribable = new subscribable()
     }
-    return (bindingInfo.eventSubscribable as Subscribable).subscribe(callback, callbackContext, event)
+    if (options && options.notifyImmediately && bindingInfo.notifiedEvents && bindingInfo.notifiedEvents[event]) {
+      dependencyDetection.ignore(callback, callbackContext, [node])
+    }
+    return bindingInfo.eventSubscribable.subscribe(callback, callbackContext, event)
   },
 
-  notify(node: Node, event: string) {
-    const bindingInfo = domData.get(node, boundElementDomDataKey)
+  notify(node: Node, event: string): void {
+    const bindingInfo = domData.get(node, boundElementDomDataKey) as BindingInfo | undefined
     if (bindingInfo) {
+      if (!bindingInfo.notifiedEvents) {
+        bindingInfo.notifiedEvents = {}
+      }
+      bindingInfo.notifiedEvents[event] = true
       if (bindingInfo.eventSubscribable) {
-        ;(bindingInfo.eventSubscribable as Subscribable).notifySubscribers(node, event)
+        bindingInfo.eventSubscribable.notifySubscribers(node, event)
       }
+      // Drive the async-completion bookkeeping once a node's direct children
+      // have bound. TKO stays lenient here: KO throws when a descendantsComplete
+      // subscription exists without an async context; we don't, because
+      // `bindingEvent.subscribe` is public and works on any node.
+      if (event === bindingEvent.childrenComplete && bindingInfo.asyncContext) {
+        bindingInfo.asyncContext.completeChildren()
+      }
+    }
+  },
+
+  /**
+   * Register `node` as (potentially) completing its content asynchronously.
+   * Creates the node's `AsyncCompleteContext` (linking it into its ancestor's
+   * pending set) and returns a binding context extended so descendant contexts
+   * can find this node as their completion ancestor.
+   */
+  startPossiblyAsyncContentBinding(node: Node, bindingContext: BindingContext): BindingContext {
+    const bindingInfo = domData.getOrSet(node, boundElementDomDataKey, {}) as BindingInfo
+
+    if (!bindingInfo.asyncContext) {
+      bindingInfo.asyncContext = new AsyncCompleteContext(node, bindingInfo, bindingContext[contextAncestorBindingInfo])
+    }
+
+    // If the provided context was already extended with this node's binding info, reuse it.
+    if (bindingContext[contextAncestorBindingInfo] === bindingInfo) {
+      return bindingContext
     }
+
+    return bindingContext.extend(function (this: BindingContext) {
+      this[contextAncestorBindingInfo] = bindingInfo
+    } as any)
   }
 }
diff --git a/packages/bind/verified-behaviors.json b/packages/bind/verified-behaviors.json
index 96032c133..70020f855 100644
--- a/packages/bind/verified-behaviors.json
+++ b/packages/bind/verified-behaviors.json
@@ -26,7 +26,8 @@
     {
       "statement": "`childrenComplete` fires after descendant bindings are applied.",
       "notes": [
-        "It works on normal elements and virtual elements, and it does not fire when there are no descendants."
+        "It works on normal elements and virtual elements. The event is notified unconditionally once children are bound, but the callback only runs when there are child nodes to hand back — so it does not call back when there are no descendants.",
+        "`bindingEvent` owns the KO 3.5 async-completion bookkeeping (`startPossiblyAsyncContentBinding` / `AsyncCompleteContext`): `childrenComplete` drives a node's pending-descendant tracking so `descendantsComplete` fires once children and every async descendant have bound."
       ],
       "specs": ["packages/bind/spec/bindingAttributeBehaviors.ts", "packages/bind/spec/nodePreprocessingBehaviors.ts"]
     }
diff --git a/packages/binding.component/src/componentBinding.ts b/packages/binding.component/src/componentBinding.ts
index f25598da9..90b421398 100644
--- a/packages/binding.component/src/componentBinding.ts
+++ b/packages/binding.component/src/componentBinding.ts
@@ -6,7 +6,7 @@ import { virtualElements, makeArray, cloneNodes } from '@tko/utils'
 
 import { unwrap } from '@tko/observable'
 
-import { DescendantBindingHandler } from '@tko/bind'
+import { DescendantBindingHandler, bindingEvent } from '@tko/bind'
 
 import { JsxObserver, maybeJsx } from '@tko/utils.jsx'
 
@@ -27,6 +27,12 @@ export default class ComponentBinding extends DescendantBindingHandler {
   latestComponentName: string
   loadingOperationId: number
   originalChildNodes: Node[]
+  /** Context extended with this element's async-completion info, used as the
+   *  parent of the component's child context (KO parity). */
+  asyncBindingContext?: BindingContext
+  /** Subscription bridging the element's `descendantsComplete` event to the
+   *  view model's `koDescendantsComplete` hook. */
+  afterRenderSub?: { dispose(): void } | null
   constructor(params: any) {
     super(params)
     this.originalChildNodes = makeArray(virtualElements.childNodes(this.$element as Node))
@@ -112,6 +118,11 @@ export default class ComponentBinding extends DescendantBindingHandler {
       throw new Error('No component name specified')
     }
 
+    // Register the element as (potentially) completing asynchronously so an
+    // ancestor's `descendantsComplete` waits for this component, and so the
+    // component's own `descendantsComplete` fires once its content is bound.
+    this.asyncBindingContext = bindingEvent.startPossiblyAsyncContentBinding(this.$element, this.$context)
+
     this.loadingOperationId = this.currentLoadingOperationId = ++componentLoadingOperationUniqueId
     registry.get(componentName, (defn: any) => this.applyComponentDefinition(componentName, componentParams, defn))
   }
@@ -124,7 +135,7 @@ export default class ComponentBinding extends DescendantBindingHandler {
         $componentTemplateSlotNodes: this.makeTemplateSlotNodes(this.originalChildNodes as HTMLElement[])
       })
 
-    return this.$context.createChildContext($component, undefined, ctxExtender)
+    return (this.asyncBindingContext ?? this.$context).createChildContext($component, undefined, ctxExtender)
   }
 
   applyComponentDefinition(componentName: string, componentParams: any, componentDefinition: any) {
@@ -156,6 +167,17 @@ export default class ComponentBinding extends DescendantBindingHandler {
 
     this.childBindingContext = this.makeChildBindingContext(componentViewModel)
 
+    // Fire the view model's `koDescendantsComplete` hook when the element's
+    // descendants (including async ones) have all completed (KO parity).
+    if (componentViewModel && typeof componentViewModel.koDescendantsComplete === 'function') {
+      this.afterRenderSub = bindingEvent.subscribe(
+        this.$element,
+        bindingEvent.descendantsComplete,
+        componentViewModel.koDescendantsComplete,
+        componentViewModel
+      )
+    }
+
     const viewTemplate = componentViewModel && componentViewModel.template
 
     if (!componentDefinition.template) {
@@ -174,14 +196,11 @@ export default class ComponentBinding extends DescendantBindingHandler {
 
     this.currentViewModel = componentViewModel
 
-    const onBinding = this.onBindingComplete.bind(this, componentViewModel)
+    const onBinding = this.onBindingComplete.bind(this)
     this.applyBindingsToDescendants(this.childBindingContext, onBinding)
   }
 
-  onBindingComplete(componentViewModel, bindingResult) {
-    if (componentViewModel && componentViewModel.koDescendantsComplete) {
-      componentViewModel.koDescendantsComplete(this.$element)
-    }
+  onBindingComplete(bindingResult) {
     this.completeBinding(bindingResult)
   }
 
@@ -191,6 +210,10 @@ export default class ComponentBinding extends DescendantBindingHandler {
     if (typeof currentViewDispose === 'function') {
       currentViewDispose.call(currentView)
     }
+    if (this.afterRenderSub) {
+      this.afterRenderSub.dispose()
+      this.afterRenderSub = null
+    }
     this.currentViewModel = null
     // Any in-flight loading operation is no longer relevant, so make sure we ignore its completion
     this.currentLoadingOperationId = null
diff --git a/packages/binding.component/verified-behaviors.json b/packages/binding.component/verified-behaviors.json
index 66cd96f19..4bca856eb 100644
--- a/packages/binding.component/verified-behaviors.json
+++ b/packages/binding.component/verified-behaviors.json
@@ -9,6 +9,14 @@
       "statement": "`childrenComplete` fires after a component finishes rendering and receives the rendered nodes plus the component params.",
       "specs": ["packages/binding.component/spec/componentBindingBehaviors.ts"]
     },
+    {
+      "statement": "A component viewmodel's `koDescendantsComplete` is invoked via the element's `descendantsComplete` event, so it waits for inner components to complete first (KO 3.5 ordering: inner components before outer).",
+      "notes": [
+        "Ordering holds whether components render synchronously or asynchronously, and across intermediate bindings (`with`, nesting several layers deep).",
+        "Re-rendering an inner component does not re-fire the outer component's `koDescendantsComplete`."
+      ],
+      "specs": ["builds/knockout/spec/components/componentBindingBehaviors.js"]
+    },
     {
       "statement": "`slot` supports named and default slots, works in virtual-element form, and preprocesses native `<slot>` elements.",
       "notes": ["Named slot templates and plain nodes with a matching `slot` attribute are both covered."],
diff --git a/packages/binding.core/spec/descendantsCompleteBehaviors.ts b/packages/binding.core/spec/descendantsCompleteBehaviors.ts
index 2d8fd3746..e764c8bc4 100644
--- a/packages/binding.core/spec/descendantsCompleteBehaviors.ts
+++ b/packages/binding.core/spec/descendantsCompleteBehaviors.ts
@@ -115,7 +115,7 @@ describe('Binding: DescendantsComplete', function () {
     expect(callbacks).to.equal(1)
   })
 
-  it('TKO-Change: descendantsComplete callback function is not called after nested "if" binding', function () {
+  it('Should call a descendantsComplete callback after a nested "if" binding renders (KO 3.5 default)', function () {
     testNode.innerHTML =
       "<div data-bind='if: outerCondition, descendantsComplete: callback'><div data-bind='if: innerCondition, childrenComplete: render'><span data-bind='text: someText'></span></div></div>"
     let callbacks = 0,
@@ -137,15 +137,82 @@ describe('Binding: DescendantsComplete', function () {
     expect(render).to.equal(0)
     expectContainText(testNode, '')
 
-    // Complete the outer condition first and then the inner one
+    // Rendering the outer content completes its descendants (the inner "if"
+    // renders nothing but still reports completion), so the callback fires.
     viewModel.outerCondition(true)
-    expect(callbacks).to.equal(0)
+    expect(callbacks).to.equal(1)
     expect(render).to.equal(0)
-    expectContainText(testNode, '')
 
+    // The inner condition renders its content; childrenComplete fires there.
     viewModel.innerCondition(true)
-    expect(callbacks).to.equal(0) //Breaking Changing to KO = there was completeOn: 'render' possible
-    expect(render).to.equal(1) //The workaround with children is complete. It is also asynchronously usable in TKO.
+    expect(callbacks).to.equal(1)
+    expect(render).to.equal(1)
     expectContainText(testNode, 'hello')
   })
+
+  it("Should defer descendantsComplete with completeOn: 'render' until inner content renders", function () {
+    testNode.innerHTML =
+      "<div data-bind='if: outerCondition, descendantsComplete: callback'><div data-bind='if: innerCondition, completeOn: \"render\"'><span data-bind='text: someText'></span></div></div>"
+    let callbacks = 0
+    const viewModel = {
+      outerCondition: observable(false),
+      innerCondition: observable(false),
+      someText: 'hello',
+      callback: function () {
+        callbacks++
+      }
+    }
+
+    applyBindings(viewModel, testNode)
+    expect(callbacks).to.equal(0)
+
+    // The inner "if" holds the outer's descendantsComplete open until it renders.
+    viewModel.outerCondition(true)
+    expect(callbacks).to.equal(0)
+
+    viewModel.innerCondition(true)
+    expect(callbacks).to.equal(1)
+    expectContainText(testNode, 'hello')
+  })
+
+  it('Should still fire childrenComplete on a false "if" branch that renders nothing', function () {
+    testNode.innerHTML = "<div data-bind='if: condition, childrenComplete: callback'></div>"
+    let callbacks = 0
+    const viewModel = {
+      condition: observable(false),
+      callback: function () {
+        callbacks++
+      }
+    }
+    applyBindings(viewModel, testNode)
+    // childrenComplete fires even though there are no rendered children, but the
+    // callback only runs when there are child nodes to hand back.
+    expect(callbacks).to.equal(0)
+  })
+
+  it('Should re-fire descendantsComplete each time a conditional re-renders its content (KO 3.5 semantics)', function () {
+    testNode.innerHTML =
+      "<div data-bind='if: condition, descendantsComplete: callback'><span data-bind='text: someText'></span></div>"
+    let callbacks = 0
+    const viewModel = {
+      condition: observable(false),
+      someText: 'hello',
+      callback: function () {
+        callbacks++
+      }
+    }
+
+    applyBindings(viewModel, testNode)
+    expect(callbacks).to.equal(0)
+
+    // Each render cycle that produces content re-arms and re-fires the callback.
+    viewModel.condition(true)
+    expect(callbacks).to.equal(1)
+
+    viewModel.condition(false)
+    expect(callbacks).to.equal(1)
+
+    viewModel.condition(true)
+    expect(callbacks).to.equal(2)
+  })
 })
diff --git a/packages/binding.core/src/descendantsComplete.ts b/packages/binding.core/src/descendantsComplete.ts
index 7c1a45ee5..a8d380a77 100644
--- a/packages/binding.core/src/descendantsComplete.ts
+++ b/packages/binding.core/src/descendantsComplete.ts
@@ -1,15 +1,14 @@
 /**
  * A simple callback binding.
+ *
+ * The actual `descendantsComplete` firing is driven by the async-completion
+ * bookkeeping in `@tko/bind` (`applyBindings` subscribes to the node's
+ * `descendantsComplete` event). This handler only marks the key as a valid
+ * binding that may appear on virtual elements.
  */
 import { BindingHandler } from '@tko/bind'
 
 export default class DescendantsCompleteHandler extends BindingHandler {
-  onDescendantsComplete() {
-    if (typeof this.value === 'function') {
-      this.value(this.$element)
-    }
-  }
-
   static override get allowVirtualElements() {
     return true
   }
diff --git a/packages/binding.core/verified-behaviors.json b/packages/binding.core/verified-behaviors.json
index 5523e5a44..23c6f06fb 100644
--- a/packages/binding.core/verified-behaviors.json
+++ b/packages/binding.core/verified-behaviors.json
@@ -19,7 +19,10 @@
       "notes": [
         "It does not fire when there are no descendant nodes.",
         "A `null` callback is ignored.",
-        "It also works with `ko.bindingEvent.subscribe(...)`."
+        "It also works with `ko.bindingEvent.subscribe(...)`.",
+        "It re-arms per content cycle: a nested `if` firing its content re-fires the ancestor's `descendantsComplete` (KO 3.5 semantics), and toggling a conditional off then on fires it again.",
+        "`completeOn: \"render\"` on an inner conditional holds the ancestor's `descendantsComplete` open until the inner content actually renders.",
+        "A false `if` branch that renders nothing still notifies `childrenComplete`, but the callback only runs when there are child nodes to hand back."
       ],
       "specs": ["packages/binding.core/spec/descendantsCompleteBehaviors.ts"]
     }
diff --git a/packages/binding.if/src/ConditionalBindingHandler.ts b/packages/binding.if/src/ConditionalBindingHandler.ts
index 674bcd92b..c7fd5b036 100644
--- a/packages/binding.if/src/ConditionalBindingHandler.ts
+++ b/packages/binding.if/src/ConditionalBindingHandler.ts
@@ -4,7 +4,7 @@ import { dependencyDetection, observable } from '@tko/observable'
 
 import type { Observable } from '@tko/observable'
 
-import { applyBindingsToDescendants, AsyncBindingHandler } from '@tko/bind'
+import { applyBindingsToDescendants, AsyncBindingHandler, bindingEvent } from '@tko/bind'
 
 import type { BindingContext } from '@tko/bind'
 
@@ -42,11 +42,22 @@ export default class ConditionalBindingHandler extends AsyncBindingHandler {
   completesElseChain: Observable
   hasElse: boolean
   ifElseNodes?: any
+  /** When `completeOn: "render"`, defer this node's `childrenComplete` (and thus
+   *  any ancestor `descendantsComplete`) until content is actually rendered. */
+  completeOnRender: boolean
+  /** Whether this node participates in the async-completion bookkeeping. */
+  needAsyncContext: boolean
+  /** Parent context used for rendered content; carries the async-completion
+   *  ancestor info when `needAsyncContext` is set. Re-armed on each render. */
+  asyncParentContext: BindingContext
   constructor(params) {
     super(params)
     this.hasElse = this.detectElse(this.$element)
     const elseChainSatisfied = (this.completesElseChain = observable())
     domData.set(this.$element, 'conditional', { elseChainSatisfied })
+    this.completeOnRender = this.allBindings.get('completeOn') === 'render'
+    this.needAsyncContext = this.completeOnRender || this.allBindings.has('descendantsComplete')
+    this.asyncParentContext = this.$context
   }
 
   getIfElseNodes() {
@@ -69,6 +80,13 @@ export default class ConditionalBindingHandler extends AsyncBindingHandler {
     // Save the nodes before we possibly remove them from the DOM.
     this.ifElseNodes = this.getIfElseNodes() || {}
 
+    // Re-arm the async-completion context on every render cycle. This links the
+    // node into its ancestor's pending set so `descendantsComplete` (and a
+    // component's `koDescendantsComplete`) can stay open until content renders.
+    this.asyncParentContext = this.needAsyncContext
+      ? bindingEvent.startPossiblyAsyncContentBinding(this.$element, this.$context)
+      : this.$context
+
     if (shouldDisplay) {
       const useOriginalNodes = isFirstRender && !this.hasElse
       this.renderAndApplyBindings(this.ifElseNodes.ifNodes, useOriginalNodes)
@@ -77,6 +95,12 @@ export default class ConditionalBindingHandler extends AsyncBindingHandler {
     } else {
       virtualElements.emptyNode(this.$element)
       this.completeBinding()
+      // A branch that renders nothing has still reached a completed state — notify
+      // `childrenComplete` so the async bookkeeping resolves. Unless `completeOn:
+      // "render"` asked us to hold it open until content actually renders.
+      if (!this.completeOnRender) {
+        bindingEvent.notify(this.$element, bindingEvent.childrenComplete)
+      }
     }
   }
 
diff --git a/packages/binding.if/src/ifUnless.ts b/packages/binding.if/src/ifUnless.ts
index 9da5165dc..3a70edfa2 100644
--- a/packages/binding.if/src/ifUnless.ts
+++ b/packages/binding.if/src/ifUnless.ts
@@ -19,14 +19,14 @@ export class IfBindingHandler extends ConditionalBindingHandler {
 
   override get bindingContext() {
     return this.ifCondition.isActive()
-      ? this.$context.extend(() => {
+      ? this.asyncParentContext.extend(() => {
           // Ensure that this context is dependant upon the conditional, so the
           // order of binding application is: conditional before its children.
           // See https://github.com/knockout/knockout/pull/2226
           this.ifCondition()
           return null
         })
-      : this.$context
+      : this.asyncParentContext
   }
 
   override renderStatus() {
diff --git a/packages/binding.if/src/with.ts b/packages/binding.if/src/with.ts
index 3aed8ad56..cf91a1bff 100644
--- a/packages/binding.if/src/with.ts
+++ b/packages/binding.if/src/with.ts
@@ -26,11 +26,11 @@ export class WithBindingHandler extends ConditionalBindingHandler {
 
   override get bindingContext() {
     if (!this.asOption) {
-      return this.$context.createChildContext(this.valueAccessor)
+      return this.asyncParentContext.createChildContext(this.valueAccessor)
     }
     return options.createChildContextWithAs
-      ? this.$context.createChildContext(this.value, this.asOption)
-      : this.$context.extend({ [this.asOption]: this.value })
+      ? this.asyncParentContext.createChildContext(this.value, this.asOption)
+      : this.asyncParentContext.extend({ [this.asOption]: this.value })
   }
 
   override renderStatus() {
diff --git a/packages/binding.if/verified-behaviors.json b/packages/binding.if/verified-behaviors.json
index b8b4b5292..c4bb3238e 100644
--- a/packages/binding.if/verified-behaviors.json
+++ b/packages/binding.if/verified-behaviors.json
@@ -23,6 +23,14 @@
       "statement": "When `options.createChildContextWithAs` is disabled, `with: value, as: \"alias\"` aliases the value without creating a new child context.",
       "notes": ["Observable aliases update in place without re-rendering the region."],
       "specs": ["packages/binding.if/spec/withBehaviors.ts"]
+    },
+    {
+      "statement": "`if`/`ifnot`/`with` participate in the KO 3.5 async-completion lifecycle: each render cycle re-arms the node's async context so an ancestor's `descendantsComplete` fires once content renders, and a false branch that renders nothing still notifies `childrenComplete`.",
+      "notes": [
+        "`completeOn: \"render\"` defers the node's `childrenComplete` (and any ancestor `descendantsComplete`) until content is actually rendered.",
+        "The `completeOn` binding key is reserved and read via `allBindings`; it needs no binding handler of its own."
+      ],
+      "specs": ["packages/binding.core/spec/descendantsCompleteBehaviors.ts"]
     }
   ]
 }
diff --git a/plans/2026-07-16-ko-binding-lifecycle-parity.md b/plans/2026-07-16-ko-binding-lifecycle-parity.md
new file mode 100644
index 000000000..f5954efe1
--- /dev/null
+++ b/plans/2026-07-16-ko-binding-lifecycle-parity.md
@@ -0,0 +1,234 @@
+# Plan: KO 3.5 binding-lifecycle parity (descendantsComplete / completeOn: "render")
+
+## Context
+
+Knockout 3.5 has a two-event binding lifecycle:
+
+- **`childrenComplete`** — fires synchronously each time a node's direct
+  children have been bound. Bindings that render nothing (`if: false`
+  without an `else`, `with: null`) still notify it, because "no content"
+  is a completed state.
+- **`descendantsComplete`** — fires once per rendered content cycle,
+  after the node's children *and every asynchronously-completing
+  descendant* (components, conditionals holding it open) are bound. KO
+  tracks this with a per-node `AsyncCompleteContext` created by
+  `ko.bindingEvent.startPossiblyAsyncContentBinding`; completion bubbles
+  to ancestor contexts.
+- **`completeOn: "render"`** — opt-in on `if`/`ifnot`/`with`/`template`.
+  Defers the node's `childrenComplete` until the binding actually
+  renders content, which holds ancestor `descendantsComplete` (and a
+  component's `koDescendantsComplete`) open until the condition becomes
+  true.
+
+TKO replaced this bookkeeping with a promise chain: each
+`AsyncBindingHandler` exposes a `bindingCompleted` promise,
+`applyBindings` returns `Promise.all` over them, and
+`triggerDescendantsComplete` (`packages/bind/src/applyBindings.ts`)
+fires the `descendantsComplete` callback once, when the promises of the
+*initial* binding pass settle. Two behavioral gaps follow:
+
+1. `triggerDescendantsComplete` captures `virtualElements.firstChild`
+   at bind time. A conditional that starts false has already emptied
+   the node, so the callback is suppressed forever — it never re-arms
+   when the condition later becomes true.
+2. `completeOn: "render"` is not implemented at all, so the deferred
+   variant of the lifecycle cannot be expressed.
+
+Two artifacts document the divergence:
+
+- **Issue [knockout/tko#414](https://github.com/knockout/tko/issues/414)** —
+  `koDescendantsComplete` never called when a component template
+  contains `<!-- ko if: false -->`. Root cause (the false branch never
+  resolved its completion promise) is already fixed on `main` by
+  `6f941262` ("fix: resolve async completion in
+  ConditionalBindingHandler"), but that fix is **not in the released
+  v4.1.0** — the changeset is still pending in `.changeset/`. After the
+  next release, #414's scenario works (verified by repro against
+  `main`, 2026-07-16).
+- **Spec `packages/binding.core/spec/descendantsCompleteBehaviors.ts`,
+  test "TKO-Change: descendantsComplete callback function is not called
+  after nested 'if' binding"** — enshrines the remaining gap as if it
+  were intended behavior.
+
+Behavior matrix for that spec's markup —
+`<div data-bind='if: outer, descendantsComplete: cb'>` wrapping
+`<div data-bind='if: inner, childrenComplete: render'>`, both starting
+false, then `outer(true)`, then `inner(true)`:
+
+| Step            | KO 3.5 default | KO 3.5 + `completeOn: "render"` | TKO today |
+| --------------- | -------------- | ------------------------------- | --------- |
+| initial (both false) | cb: 0     | cb: 0                           | cb: 0     |
+| `outer(true)`   | cb: 1          | cb: 0                           | cb: 0     |
+| `inner(true)`   | cb: 1          | cb: 1                           | cb: 0     |
+
+TKO today matches neither column: the callback never fires. The issue
+reporter wants the KO default column; the spec author wanted the
+`completeOn: "render"` column. Restoring the KO mechanism serves both,
+which is why the two concerns are one plan, not two.
+
+## Approach
+
+Port KO 3.5's event bookkeeping into `@tko/bind` and let it own
+`descendantsComplete` semantics. The promise machinery stays — it is
+TKO's public async story (`applyBindings(...)` return value, SSR,
+`BindingResult`) and the #414 fix depends on it. Events and promises
+answer different questions ("is this content cycle rendered?" vs. "is
+the initial binding pass settled?") and can coexist.
+
+### 1. `bindingEvent` bookkeeping (`packages/bind/src/bindingEvent.ts`)
+
+Port from KO 3.5 (`src/binding/bindingAttributeSyntax.js`):
+
+- `AsyncCompleteContext` — per-node record of pending async
+  descendants; `completeChildren()` / `descendantComplete()` /
+  `notifyAncestor()`.
+- `bindingEvent.startPossiblyAsyncContentBinding(node, ctx)` — creates
+  the context, extends the binding context with
+  `contextAncestorBindingInfo` (symbol already exists in TKO) so
+  descendant contexts can find their ancestor's bookkeeping.
+- `notify(node, childrenComplete)` drives the context: mark children
+  complete, and when no async descendants remain, fire
+  `descendantsComplete` on the node and notify the ancestor context.
+- Track `notifiedEvents` per node and support KO's
+  `subscribe(..., { notifyImmediately })` option.
+- **Deviation from KO, on purpose:** KO throws
+  `"descendantsComplete event not supported for bindings on this node"`
+  when subscribing without an async context. TKO's public
+  `bindingEvent.subscribe` today works on any node (covered by the
+  existing spec that subscribes manually) — stay lenient, don't adopt
+  the throw.
+
+### 2. Wire-up in `applyBindings.ts`
+
+- Replace `triggerDescendantsComplete`'s one-shot `Promise.all` with
+  the KO pattern: when `bindings` contain `descendantsComplete`, call
+  `startPossiblyAsyncContentBinding(node, ctx)` and subscribe a handler
+  that evaluates `firstChild` **at fire time**.
+- `applyBindingsToDescendantsInternal` currently early-returns when a
+  node has no children and only notifies `childrenComplete` when it
+  bound something. KO notifies unconditionally. Align with KO — the
+  "no descendants → callback not called" behavior remains enforced by
+  the fire-time `firstChild` check, not by skipping the event.
+- Keep adding `bindingCompleted` promises to `asyncBindingsApplied`
+  unchanged.
+
+### 3. Descendant-controlling bindings
+
+- **`ConditionalBindingHandler`** (`if`/`ifnot`/`with`/`else`):
+  - Read `completeOn` via `allBindings.get('completeOn') === 'render'`.
+    No binding handler needed for the key — KO reads it the same way,
+    and TKO's `topologicalSortBindings` already skips unknown keys.
+  - `needAsyncContext = completeOnRender ||
+    allBindings.has('descendantsComplete')`; when set, run each render
+    cycle through `startPossiblyAsyncContentBinding`.
+  - False/empty branch: keep `completeBinding()` (the #414 fix — must
+    not regress) and additionally notify `childrenComplete` unless
+    `completeOnRender`.
+  - Rendering branch with `completeOnRender`: notify `childrenComplete`
+    after content is bound.
+- **`ComponentBinding`**: subscribe `koDescendantsComplete` to the
+  element's `descendantsComplete` event (KO parity) instead of calling
+  it from `onBindingComplete`; keep `completeBinding` for the promise
+  chain. Component re-renders (name/params change) then re-fire it per
+  cycle, as in KO.
+- **`template` / `foreach`**: audit against KO's template binding —
+  `completeOn: "render"` support and per-render `childrenComplete`
+  notification; foreach delegates to template in KO and should here
+  too. Scope creep guard: if the audit shows template needs its own
+  async-context rework, split it into a follow-up plan and land
+  if/with/component parity first.
+
+### 4. Cleanup in scope
+
+- `packages/binding.core/src/descendantsComplete.ts`: the handler's
+  `onDescendantsComplete()` is dead code today (nothing invokes it).
+  Either wire the handler to the event or drop the method — after this
+  plan the subscription in `applyBindings.ts` is the single path, so
+  the method goes.
+
+### 5. Specs
+
+- Delete the "TKO-Change: …" test and replace it with the KO 3.5
+  originals (from knockout/knockout `spec/asyncBehaviors.js` and
+  `spec/defaultBindings/*`): nested `if` with `completeOn: "render"`
+  completing outer-first **and** inner-first, the KO-default column of
+  the matrix above, re-render re-firing, and `bindingEvent.subscribe`
+  variants.
+- Keep a regression spec for the `childrenComplete`-on-false-branch
+  workaround the deleted test documented.
+- Re-enable/port the `descendantsComplete` specs in
+  `builds/knockout/spec/` that cover the legacy `ko.*` surface,
+  including the currently skipped `koDescendantsComplete` ordering
+  tests if the new bookkeeping fixes their ordering (KO order:
+  inner components before outer).
+- Update `verified-behaviors.json` in `bind`, `binding.core`,
+  `binding.if`, `binding.component` where statements change (e.g.
+  "`descendantsComplete` fires after descendant bindings finish"
+  gains the conditional/re-render cases).
+
+### 6. Release artifacts
+
+- Changeset: minor bump on the fixed `@tko/*` release line; call out
+  the behavior change ("descendantsComplete now fires for conditional
+  content per KO 3.5 semantics; completeOn: 'render' supported").
+- Docs: tko.io binding-lifecycle page + `tko.io/public/agents/guide.md`
+  (dense, code-first), per the agent-first documentation rule.
+- Comment on #414: fixed root cause ships in the next release; link
+  the new lifecycle docs for `completeOn: "render"`.
+
+## Files
+
+| File | Change |
+| ---- | ------ |
+| `packages/bind/src/bindingEvent.ts` | Port `AsyncCompleteContext`, `startPossiblyAsyncContentBinding`, `notifiedEvents`, `notifyImmediately` |
+| `packages/bind/src/applyBindings.ts` | Event-driven `descendantsComplete` (fire-time `firstChild`), unconditional `childrenComplete` notify |
+| `packages/bind/src/bindingContext.ts` | Expose/reuse `contextAncestorBindingInfo` plumbing |
+| `packages/binding.if/src/ConditionalBindingHandler.ts` | `completeOn: "render"`, false-branch `childrenComplete`, async context per render |
+| `packages/binding.component/src/componentBinding.ts` | `koDescendantsComplete` via `descendantsComplete` event |
+| `packages/binding.template/src/`, `packages/binding.foreach/src/` | Audit + `completeOn` parity (possible follow-up split) |
+| `packages/binding.core/src/descendantsComplete.ts` | Remove dead `onDescendantsComplete` |
+| `packages/binding.core/spec/descendantsCompleteBehaviors.ts` | Replace "TKO-Change" test with KO originals |
+| `packages/{bind,binding.if,binding.component}/spec/` | New/ported lifecycle specs |
+| `builds/knockout/spec/components/componentBindingBehaviors.js` | Un-skip ordering tests if fixed |
+| `packages/*/verified-behaviors.json` | Update changed statements |
+| `.changeset/*.md` | Minor bump, behavior-change note |
+| `tko.io` docs + `tko.io/public/agents/guide.md` | Lifecycle docs |
+
+## Verification
+
+1. `bunx vitest run packages/bind packages/binding.if
+   packages/binding.core packages/binding.component
+   packages/binding.template packages/binding.foreach` — fast loop
+   while porting.
+2. New specs assert the full matrix above (KO default and
+   `completeOn: "render"` columns) plus #414's component scenario
+   (`<!-- ko if: false -->` in a component template →
+   `koDescendantsComplete` fires).
+3. `bun run verify` before every commit (full suite, real-browser
+   matrix is authoritative).
+4. Backwards-compat sweep: `builds/knockout` specs green — this is the
+   legacy surface consumers of `@tko/build.knockout` rely on.
+5. Adversarial review per AGENTS.md on each in-scope commit; audit
+   line in the commit message.
+
+## Risks / open questions
+
+- **Timing semantics.** KO fires these events synchronously; TKO's
+  promise path resolves in microtasks. Existing TKO specs (and
+  downstream code) may assume the async timing for
+  `descendantsComplete` on nodes with async descendants. Decide and
+  document: event fires synchronously when the completing notification
+  is synchronous, later otherwise — same as KO.
+- **Re-firing is a behavior change.** In TKO today `descendantsComplete`
+  fires at most once; after this plan it fires once *per content
+  cycle* (KO semantics). Consumers who attached one-shot callbacks see
+  extra calls. Changeset must state this loudly.
+- **`completeOn` as a reserved key.** Any userland binding named
+  `completeOn` would now collide. KO has the same reservation; note it
+  in docs.
+- **JSX path.** `JsxObserver`-rendered component templates bypass parts
+  of `applyBindingsToDescendants`; verify the async context still
+  completes there (component spec has JSX cases).
+- **`with` binding uses the same base class** — false branch (`with:
+  null`) gets the same new notification; check its specs for
+  assumptions.
diff --git a/plans/2026-07-18-template-completeon-parity.md b/plans/2026-07-18-template-completeon-parity.md
new file mode 100644
index 000000000..6408c453f
--- /dev/null
+++ b/plans/2026-07-18-template-completeon-parity.md
@@ -0,0 +1,69 @@
+# Plan: `completeOn: "render"` parity for `template` / `foreach`
+
+## Context
+
+Follow-up split from
+[`plans/2026-07-16-ko-binding-lifecycle-parity.md`](2026-07-16-ko-binding-lifecycle-parity.md).
+That plan ported KO 3.5's `AsyncCompleteContext` bookkeeping into
+`@tko/bind` and wired it through `if`/`ifnot`/`with` (via
+`ConditionalBindingHandler`) and `component`. The scope-creep guard in
+that plan's §3 deferred `template`/`foreach` because they need their own
+async-context rework rather than a small edit:
+
+- `TemplateBindingHandler` (`packages/binding.template/src/templating.ts`)
+  is not a `ConditionalBindingHandler` subclass — it renders through
+  `renderTemplate` / `renderTemplateForEach` and an `onValueChange`
+  computed, not `render()` + `renderAndApplyBindings`.
+- Its false/empty branch
+  (`virtualElements.emptyNode(element); elseChainSatisfied(false)`) does
+  **not** notify `childrenComplete`, so a `template` that evaluates to a
+  non-displaying state never resolves an ancestor's
+  `descendantsComplete`. (The displaying paths already notify
+  `childrenComplete` at lines ~163 and ~309.)
+- `completeOn: "render"` is not read anywhere in the template path.
+
+`foreach` delegates to the template engine in both KO and TKO, so it
+inherits whatever the template handler does.
+
+## Approach
+
+1. Notify `childrenComplete` on the template's false/empty branch
+   (parity with `ConditionalBindingHandler`), guarded by a
+   `completeOnRender` check so `completeOn: "render"` can hold it open.
+2. Read `completeOn` via `allBindings.get('completeOn') === 'render'`;
+   compute `needAsyncContext = completeOnRender ||
+   allBindings.has('descendantsComplete')`.
+3. Thread `startPossiblyAsyncContentBinding(element, ctx)` through each
+   render cycle (both `renderTemplate` and `renderTemplateForEach`
+   inner-context creation) so nested async content reports completion up
+   to the template node, re-armed per cycle like `if`/`with`.
+4. Confirm `foreach` (which routes through the template engine) inherits
+   the behavior; add a spec.
+
+## Files
+
+| File | Change |
+| ---- | ------ |
+| `packages/binding.template/src/templating.ts` | `completeOn`, false-branch `childrenComplete`, async context per render |
+| `packages/binding.template/spec/` | template/foreach lifecycle specs |
+| `packages/binding.foreach/spec/` | foreach `descendantsComplete` / `completeOn` spec |
+| `packages/binding.template/verified-behaviors.json` | changed statements |
+| `.changeset/*.md` | minor bump, behavior note |
+
+## Verification
+
+1. `bunx vitest run packages/binding.template packages/binding.foreach`
+   (build first — tests load compiled `dist/`).
+2. New specs: template with `if: false` holds ancestor
+   `descendantsComplete` open under `completeOn: "render"` and resolves
+   it otherwise; foreach fires `descendantsComplete` after items render.
+3. `bun run verify` (full matrix authoritative).
+4. Adversarial review per AGENTS.md; audit line per in-scope commit.
+
+## Risks / open questions
+
+- `renderTemplateForEach` completion timing across array mutations —
+  each add/remove is a content cycle; decide whether `descendantsComplete`
+  re-fires per mutation or per batch, and document it.
+- The template computed re-runs on `onValueChange`; ensure the async
+  context is re-armed on the computed's re-evaluation, not just first run.
diff --git a/tko.io/public/agents/guide.md b/tko.io/public/agents/guide.md
index f08f0ae53..addb843a2 100644
--- a/tko.io/public/agents/guide.md
+++ b/tko.io/public/agents/guide.md
@@ -297,6 +297,7 @@ tko.applyBindings({ removeTodo: t => todos.remove(t) }, root)
 - **Binary HTML attributes** (`disabled`, `readonly`, `hidden`, `required`, `checked`, `selected`) omit the attribute when the value is `null`, `undefined`, or `false`. Use `|| undefined` in computeds to make "no attribute" explicit: `disabled={this.computed(() => shouldBeDisabled() || undefined)}`. Never return the string `"false"` — it keeps the attribute set.
 - **Pass the observable itself to `ko-*` attrs — not a called expression.** `ko-text={obs()}` calls `obs()` once at render time and gives TKO a static value; the DOM never updates after the initial render. Write `ko-text={obs}` (pass the observable). For derived expressions, hoist to a `ko.pureComputed`: `const label = ko.pureComputed(() => a() + b())`, then `ko-text={label}`.
 - **Prefer named computed variables over inline computeds in JSX.** A computed created inline in JSX is easier to accidentally recreate on each render than one bound to a class field or `const`.
+- **Binding lifecycle (`descendantsComplete` / `completeOn`) follows Knockout 3.5.** `childrenComplete: fn` fires when a node's direct children (re-)bind; `descendantsComplete: fn` fires once children *and every async descendant* (components, conditionals) have bound. `descendantsComplete` **re-fires per content cycle** — a nested `if` becoming true, or toggling a conditional off then on, fires it again, so don't assume it's one-shot. `completeOn: "render"` on an inner `if`/`ifnot`/`with` holds an ancestor's `descendantsComplete` (or a component's `koDescendantsComplete`) open until that inner content actually renders. `completeOn` is a reserved binding key. A component viewmodel's `koDescendantsComplete(el)` fires via the element's `descendantsComplete` event, so inner components complete before outer ones.
 
 ## Testing
 
diff --git a/tko.io/public/agents/verified-behaviors/bind.md b/tko.io/public/agents/verified-behaviors/bind.md
index e158e42d4..ddf70527c 100644
--- a/tko.io/public/agents/verified-behaviors/bind.md
+++ b/tko.io/public/agents/verified-behaviors/bind.md
@@ -18,7 +18,7 @@ Binding application, binding-handler lifecycle, and completion callbacks.
   Notes: Virtual-element use requires `allowVirtualElements = true`.
   Specs: `packages/bind/spec/bindingHandlerBehaviors.ts`
 - `childrenComplete` fires after descendant bindings are applied.
-  Notes: It works on normal elements and virtual elements, and it does not fire when there are no descendants.
+  Notes: It works on normal elements and virtual elements. The event is notified unconditionally once children are bound, but the callback only runs when there are child nodes to hand back — so it does not call back when there are no descendants. `bindingEvent` owns the KO 3.5 async-completion bookkeeping (`startPossiblyAsyncContentBinding` / `AsyncCompleteContext`): `childrenComplete` drives a node's pending-descendant tracking so `descendantsComplete` fires once children and every async descendant have bound.
   Specs: `packages/bind/spec/bindingAttributeBehaviors.ts`, `packages/bind/spec/nodePreprocessingBehaviors.ts`
 
 _Curated source: `packages/bind/verified-behaviors.json`_
diff --git a/tko.io/public/agents/verified-behaviors/binding-component.md b/tko.io/public/agents/verified-behaviors/binding-component.md
index b2d8a2b6d..1304f7642 100644
--- a/tko.io/public/agents/verified-behaviors/binding-component.md
+++ b/tko.io/public/agents/verified-behaviors/binding-component.md
@@ -10,6 +10,9 @@ Component binding runtime, slots, virtual elements, and JSX/object templates.
   Specs: `packages/binding.component/spec/componentBindingBehaviors.ts`
 - `childrenComplete` fires after a component finishes rendering and receives the rendered nodes plus the component params.
   Specs: `packages/binding.component/spec/componentBindingBehaviors.ts`
+- A component viewmodel's `koDescendantsComplete` is invoked via the element's `descendantsComplete` event, so it waits for inner components to complete first (KO 3.5 ordering: inner components before outer).
+  Notes: Ordering holds whether components render synchronously or asynchronously, and across intermediate bindings (`with`, nesting several layers deep). Re-rendering an inner component does not re-fire the outer component's `koDescendantsComplete`.
+  Specs: `builds/knockout/spec/components/componentBindingBehaviors.js`
 - `slot` supports named and default slots, works in virtual-element form, and preprocesses native `<slot>` elements.
   Notes: Named slot templates and plain nodes with a matching `slot` attribute are both covered.
   Specs: `packages/binding.component/spec/componentBindingBehaviors.ts`
diff --git a/tko.io/public/agents/verified-behaviors/binding-core.md b/tko.io/public/agents/verified-behaviors/binding-core.md
index d3659d211..04f37a3fb 100644
--- a/tko.io/public/agents/verified-behaviors/binding-core.md
+++ b/tko.io/public/agents/verified-behaviors/binding-core.md
@@ -13,7 +13,7 @@ Core element bindings such as `event` and descendant-completion hooks.
   Notes: Default click handling prevents default navigation unless `preventDefault: false` is supplied. Bubbling is on by default and can be disabled.
   Specs: `packages/binding.core/spec/eventBehaviors.ts`
 - `descendantsComplete` fires after descendant bindings finish on both DOM and virtual elements.
-  Notes: It does not fire when there are no descendant nodes. A `null` callback is ignored. It also works with `ko.bindingEvent.subscribe(...)`.
+  Notes: It does not fire when there are no descendant nodes. A `null` callback is ignored. It also works with `ko.bindingEvent.subscribe(...)`. It re-arms per content cycle: a nested `if` firing its content re-fires the ancestor's `descendantsComplete` (KO 3.5 semantics), and toggling a conditional off then on fires it again. `completeOn: "render"` on an inner conditional holds the ancestor's `descendantsComplete` open until the inner content actually renders. A false `if` branch that renders nothing still notifies `childrenComplete`, but the callback only runs when there are child nodes to hand back.
   Specs: `packages/binding.core/spec/descendantsCompleteBehaviors.ts`
 
 _Curated source: `packages/binding.core/verified-behaviors.json`_
diff --git a/tko.io/public/agents/verified-behaviors/binding-foreach.md b/tko.io/public/agents/verified-behaviors/binding-foreach.md
index 33b8b776e..0d77aad2c 100644
--- a/tko.io/public/agents/verified-behaviors/binding-foreach.md
+++ b/tko.io/public/agents/verified-behaviors/binding-foreach.md
@@ -18,5 +18,7 @@ Standalone `foreach` binding behavior, templates, and else-chain state.
   Specs: `packages/binding.foreach/spec/eachBehavior.ts`
 - Array mutation, reordering, duplicate values, `$index`, `as`, and `noIndex` are all exercised in spec coverage.
   Specs: `packages/binding.foreach/spec/eachBehavior.ts`
+- `foreach` supports `afterRender(nodes, value)`, `beforeMove(node, newIndex, value)`, and `afterMove(node, newIndex, value)` lifecycle callbacks in addition to the existing batch-shaped `afterAdd` and `beforeRemove` callbacks.
+  Specs: `packages/binding.foreach/spec/eachBehavior.ts`
 
 _Curated source: `packages/binding.foreach/verified-behaviors.json`_
diff --git a/tko.io/public/agents/verified-behaviors/binding-if.md b/tko.io/public/agents/verified-behaviors/binding-if.md
index 205462fcb..3baf6169d 100644
--- a/tko.io/public/agents/verified-behaviors/binding-if.md
+++ b/tko.io/public/agents/verified-behaviors/binding-if.md
@@ -19,5 +19,8 @@ Conditional and contextual bindings: `if`, `ifnot`, `with`, `else`, and `elseif`
 - When `options.createChildContextWithAs` is disabled, `with: value, as: "alias"` aliases the value without creating a new child context.
   Notes: Observable aliases update in place without re-rendering the region.
   Specs: `packages/binding.if/spec/withBehaviors.ts`
+- `if`/`ifnot`/`with` participate in the KO 3.5 async-completion lifecycle: each render cycle re-arms the node's async context so an ancestor's `descendantsComplete` fires once content renders, and a false branch that renders nothing still notifies `childrenComplete`.
+  Notes: `completeOn: "render"` defers the node's `childrenComplete` (and any ancestor `descendantsComplete`) until content is actually rendered. The `completeOn` binding key is reserved and read via `allBindings`; it needs no binding handler of its own.
+  Specs: `packages/binding.core/spec/descendantsCompleteBehaviors.ts`
 
 _Curated source: `packages/binding.if/verified-behaviors.json`_
diff --git a/tko.io/src/content/docs/3to4.md b/tko.io/src/content/docs/3to4.md
index 51e35fe98..e5d6ac7d1 100644
--- a/tko.io/src/content/docs/3to4.md
+++ b/tko.io/src/content/docs/3to4.md
@@ -54,30 +54,32 @@ TKO is designed for stricter Content Security Policies and avoids the older `eva
 
 `ko.applyBindings` returns a `Promise`. If you chain bootstrap work after binding or need to wait for async bindings to finish, account for that in your startup flow.
 
-### `descendantsComplete` no longer waits for async descendants
+### `descendantsComplete` matches Knockout 3.5
 
-In Knockout 3, `descendantsComplete` fired only after every descendant — including content rendered asynchronously by a nested `if`, `template`, `foreach`, or component — had finished binding. Knockout tracked this with an ancestor-linked async-completion context and, on control-flow bindings, a `completeOn: 'render'` option.
+In Knockout 3.5, `descendantsComplete` fires after every descendant — including content rendered asynchronously by a nested `if`, `template`, `foreach`, or component — has finished binding. Knockout tracks this with an ancestor-linked async-completion context and, on control-flow bindings, a `completeOn: 'render'` option.
 
-TKO drops that ancestor-tracking machinery in favor of a simpler per-node model. As a result, `descendantsComplete` is decided **once**, synchronously, when the node itself binds, and waits only for async bindings **on that same node** — not for subtrees that appear later. If a descendant `if`/`template` renders its content after the fact (for example when its condition flips to `true`), the `descendantsComplete` callback is not re-triggered and will not fire.
+TKO ports that mechanism, so `descendantsComplete` behaves as it did in Knockout 3.5:
 
-**Why:** the async-completion context was cross-cutting, hard to reason about, and a common source of disposal and ordering bugs. The per-node lifecycle is smaller and predictable, at the cost of this one edge case.
-
-**Migration:** use `childrenComplete` instead, which is notified every time a node's descendants are (re-)bound and therefore still fires when async content renders:
+- It fires once a node's children **and every asynchronously-completing descendant** have bound.
+- It **re-fires per content cycle**: if a descendant `if`/`with` renders its content after the fact (for example when its condition flips to `true`), the callback fires again. Attach one-shot callbacks accordingly.
+- `completeOn: "render"` on an inner `if`/`ifnot`/`with` holds the ancestor's `descendantsComplete` (and a component's `koDescendantsComplete`) open until that inner content actually renders.
 
 ```html
-<!-- Knockout 3: relied on descendantsComplete firing after nested async content -->
+<!-- Fires onReady after the nested async content has rendered -->
 <div data-bind="if: ready, descendantsComplete: onReady">
   <div data-bind="if: innerReady">…</div>
 </div>
-```
 
-```html
-<!-- TKO: move the callback to the node whose children you care about -->
-<div data-bind="if: ready">
-  <div data-bind="if: innerReady, childrenComplete: onReady">…</div>
+<!-- Defer onReady until the inner content renders -->
+<div data-bind="if: ready, descendantsComplete: onReady">
+  <div data-bind="if: innerReady, completeOn: 'render'">…</div>
 </div>
 ```
 
+`childrenComplete` remains available for the narrower "this node's direct children were (re-)bound" signal, and is notified every render cycle.
+
+> **Earlier 4.x behavior:** releases up to v4.1.0 decided `descendantsComplete` once, synchronously, when the node itself bound, and did not re-fire when descendant async content rendered later. If you added workarounds for that gap (moving the callback onto the inner node via `childrenComplete`), you can revert them.
+
 ## What is still familiar
 
 - `ko.observable`, `ko.observableArray`, and `ko.computed`
diff --git a/tko.io/src/content/docs/components/component-binding.md b/tko.io/src/content/docs/components/component-binding.md
index 7aefe0554..775793156 100644
--- a/tko.io/src/content/docs/components/component-binding.md
+++ b/tko.io/src/content/docs/components/component-binding.md
@@ -183,6 +183,8 @@ For slot-based composition, components can expose named `<slot>` placeholders in
 
 If a component viewmodel defines `koDescendantsComplete(element)`, TKO calls it after the component's descendants have finished binding. Use this for post-render work that must wait until the component tree is active.
 
+Following Knockout 3.5 semantics, this waits for every asynchronously-completing descendant — so a nested component's `koDescendantsComplete` runs before its outer component's. To hold the callback open until a conditional inside the template actually renders, mark that conditional with `completeOn: "render"` (see [binding lifecycle](../../3to4/#descendantscomplete-matches-knockout-35)).
+
 ### Disposal and memory management
 
 Optionally, your viewmodel class may have a `dispose` function. If implemented, Knockout will call this whenever the component is being torn down and removed from the DOM (e.g., because the corresponding item was removed from a `foreach`, or an `if` binding has become `false`).