From e5ccc7ebd850a907682f96e453700029cd886745 Mon Sep 17 00:00:00 2001
From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com>
Date: Mon, 6 Jul 2026 15:06:19 -0400
Subject: [PATCH 1/2] Add consume() and captureContext() to createContext

`context.consume()` with no argument behaves exactly like reading
`context.value`. Passed a handle from the new `captureContext()` export,
it resolves the nearest `<Provide>` above the captured render-tree
position instead -- which works outside of rendering, where the ambient
reads throw. This is the way to read a context from event handlers,
timers, and other async callbacks that run after the render stack has
unwound.

A capture is an opaque frozen handle validated through a WeakMap in the
render-scope layer (plus a type-only brand), so it can't be forged or
introspected. One handle works with every context: it captures the
render-tree position, not any one context's value, and resolution
happens at consume time so the value read is the provider's current
@value rather than a snapshot.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/@ember/-internals/glimmer/index.ts   |   7 +-
 .../-internals/glimmer/lib/create-context.ts  | 134 ++++++++-
 .../tests/integration/create-context-test.ts  | 283 +++++++++++++++++-
 packages/@ember/helper/index.ts               |  61 +++-
 packages/@glimmer/runtime/lib/render-scope.ts |  65 +++-
 tests/docs/expected.cjs                       |   1 +
 type-tests/@ember/helper-tests.ts             |  18 ++
 7 files changed, 552 insertions(+), 17 deletions(-)

diff --git a/packages/@ember/-internals/glimmer/index.ts b/packages/@ember/-internals/glimmer/index.ts
index e0ce66b3054..a8e9b4a781c 100644
--- a/packages/@ember/-internals/glimmer/index.ts
+++ b/packages/@ember/-internals/glimmer/index.ts
@@ -519,7 +519,12 @@ export {
   type View,
 } from './lib/renderer';
 // RFC #1200 -- render-tree-scoped context (provide/consume)
-export { createContext, type Context } from './lib/create-context';
+export {
+  createContext,
+  captureContext,
+  type Context,
+  type CapturedContext,
+} from './lib/create-context';
 export {
   getTemplate,
   setTemplate,
diff --git a/packages/@ember/-internals/glimmer/lib/create-context.ts b/packages/@ember/-internals/glimmer/lib/create-context.ts
index 545fe615dcb..8951209e4fc 100644
--- a/packages/@ember/-internals/glimmer/lib/create-context.ts
+++ b/packages/@ember/-internals/glimmer/lib/create-context.ts
@@ -2,21 +2,44 @@
  * @module @ember/helper
  */
 import { precompileTemplate } from '@ember/template-compilation';
-import { lookupRenderContext, provideRenderContext } from '@glimmer/runtime/lib/render-scope';
+import {
+  captureRenderScope,
+  lookupCapturedRenderContext,
+  lookupRenderContext,
+  provideRenderContext,
+} from '@glimmer/runtime/lib/render-scope';
 import { valueForRef } from '@glimmer/reference/lib/reference';
 import InternalComponent, {
   type OpaqueInternalComponentConstructor,
   opaquify,
 } from './components/internal';
 
+declare const CAPTURED_CONTEXT: unique symbol;
+
+/**
+ * An opaque handle to a position in the render tree, returned by
+ * `captureContext()`. Pass it to a context's `consume(captured)` to resolve
+ * that context from the captured position later -- e.g. inside an event
+ * handler, after the render stack has unwound and ambient reads like `value`
+ * would throw.
+ */
+export interface CapturedContext {
+  // A type-only brand so arbitrary objects don't typecheck as a capture. The
+  // only way to obtain one is `captureContext()`; at runtime validity is
+  // checked against the render-scope layer's WeakMap, not this symbol.
+  readonly [CAPTURED_CONTEXT]: never;
+}
+
 /**
  * The shape returned by `createContext`. Use `Provide` in templates to bind a
- * value into the render tree and read `value` to get the nearest enclosing
- * provided value.
+ * value into the render tree, read `value` to get the nearest enclosing
+ * provided value, or call `consume(captured)` to read it from a previously
+ * captured render-tree position (e.g. in an event handler).
  */
 export interface Context<T> {
   Provide: OpaqueInternalComponentConstructor;
   get value(): T;
+  consume(captured?: CapturedContext): T;
 }
 
 /**
@@ -69,11 +92,19 @@ export interface Context<T> {
  * legitimate "fall back to undefined" state. If you want a default, provide
  * one at the application root.
  *
+ * The returned object also has a `consume()` method. With no argument it
+ * behaves exactly like reading `value`. Passed a handle from
+ * `captureContext()`, it resolves the context from that captured
+ * render-tree position instead -- the way to read a context from event
+ * handlers and other code that runs outside of rendering (see
+ * `captureContext`).
+ *
  * @method createContext
  * @static
  * @for @ember/helper
  * @returns {Object} An object with `Provide` (a component that takes a
- *   `@value`) and `value` (a getter that reads the nearest provided value).
+ *   `@value`), `value` (a getter that reads the nearest provided value), and
+ *   `consume` (reads ambiently like `value`, or from a captured position).
  * @public
  */
 export function createContext<T>(): Context<T> {
@@ -104,19 +135,45 @@ export function createContext<T>(): Context<T> {
     }
   }
 
+  // The ambient read backing both the `value` getter and a no-argument
+  // `consume()` call: resolve the nearest provider at the currently-rendering
+  // position.
+  function resolveAmbient(): T {
+    let read = lookupRenderContext(key);
+    if (read === undefined) {
+      throw new Error(
+        'A context `value` was read outside of rendering. The render-tree scope is only available during rendering -- there is nothing to read. To read a context from an event handler or other async callback, capture a handle during rendering with `captureContext()` and pass it to `consume(captured)`.'
+      );
+    }
+    if (read === null) {
+      throw new Error(
+        'No matching `<Provide>` was found in the render tree. Wrap consumers in `<Context.Provide @value={{...}}>...</Context.Provide>`, or provide a default at the application root.'
+      );
+    }
+    return read() as T;
+  }
+
   return {
     Provide: opaquify(Provide, PROVIDE_TEMPLATE),
 
     get value(): T {
-      let read = lookupRenderContext(key);
+      return resolveAmbient();
+    },
+
+    consume(captured?: CapturedContext): T {
+      if (captured === undefined) {
+        return resolveAmbient();
+      }
+
+      let read = lookupCapturedRenderContext(captured, key);
       if (read === undefined) {
         throw new Error(
-          'A context `value` was read outside of rendering. The render-tree scope is only available during rendering -- there is nothing to read.'
+          '`consume(captured)` expects the handle returned from `captureContext()`, but received some other value.'
         );
       }
       if (read === null) {
         throw new Error(
-          'No matching `<Provide>` was found in the render tree. Wrap consumers in `<Context.Provide @value={{...}}>...</Context.Provide>`, or provide a default at the application root.'
+          'No matching `<Provide>` was found above the captured render-tree position. Wrap the component that called `captureContext()` in `<Context.Provide @value={{...}}>...</Context.Provide>`, or provide a default at the application root.'
         );
       }
       return read() as T;
@@ -124,6 +181,69 @@ export function createContext<T>(): Context<T> {
   };
 }
 
+/**
+ * Captures the current render-tree position as an opaque handle that can be
+ * passed to a context's `consume(captured)` later.
+ *
+ * The ambient reads -- `context.value` or `context.consume()` -- only work
+ * while rendering, because they resolve against the currently-rendering
+ * node. Event handlers, timers, and other async callbacks run after the
+ * render stack has unwound, so they have no ambient position to read from.
+ * `captureContext()` bridges that gap: call it while rendering (a component
+ * constructor or a field initializer is the natural spot), keep the handle,
+ * and resolve any context from that position later.
+ *
+ * @example
+ *
+ * ```gjs
+ * import Component from '@glimmer/component';
+ * import { createContext, captureContext } from '@ember/helper';
+ * import { on } from '@ember/modifier';
+ *
+ * const theme = createContext<Theme>();
+ *
+ * class ThemedButton extends Component {
+ *   // Field initializers run in the constructor, during rendering, so this
+ *   // captures the position of <ThemedButton/> in the render tree.
+ *   context = captureContext();
+ *
+ *   onClick = () => {
+ *     // Outside of rendering, `theme.value` would throw -- but the captured
+ *     // handle still resolves the nearest <theme.Provide> above this
+ *     // component.
+ *     console.log(theme.consume(this.context).color);
+ *   };
+ *
+ *   <template>
+ *     <button {{on 'click' this.onClick}}>{{yield}}</button>
+ *   </template>
+ * }
+ * ```
+ *
+ * A single captured handle works with every context -- it captures the
+ * render-tree position, not any one context's value. Resolution happens at
+ * `consume` time, so the value read is the provider's current `@value`, not
+ * a snapshot from when the handle was captured.
+ *
+ * `captureContext()` throws if called outside of rendering -- there is no
+ * position to capture.
+ *
+ * @method captureContext
+ * @static
+ * @for @ember/helper
+ * @returns {Object} An opaque handle for `consume(captured)`.
+ * @public
+ */
+export function captureContext(): CapturedContext {
+  let handle = captureRenderScope();
+  if (handle === undefined) {
+    throw new Error(
+      '`captureContext()` was called outside of rendering -- there is no render-tree position to capture. Capture while rendering (e.g. in a component constructor or field initializer) and pass the handle to `consume(captured)` later.'
+    );
+  }
+  return handle as CapturedContext;
+}
+
 // All Provide components share the same template: yield to the block.
 // Per-instance behavior is parameterized via the closure in createContext.
 const PROVIDE_TEMPLATE = precompileTemplate('{{yield}}');
diff --git a/packages/@ember/-internals/glimmer/tests/integration/create-context-test.ts b/packages/@ember/-internals/glimmer/tests/integration/create-context-test.ts
index 39d59861e8a..d0558b1b03a 100644
--- a/packages/@ember/-internals/glimmer/tests/integration/create-context-test.ts
+++ b/packages/@ember/-internals/glimmer/tests/integration/create-context-test.ts
@@ -13,8 +13,9 @@ import GlimmerishComponent from '../utils/glimmerish-component';
 
 import { run } from '@ember/runloop';
 import { associateDestroyableChild, registerDestructor } from '@glimmer/destroyable';
+import { on } from '@ember/modifier';
 import { renderComponent } from '../../lib/renderer';
-import { createContext } from '../../lib/create-context';
+import { captureContext, createContext, type CapturedContext } from '../../lib/create-context';
 import { tracked } from '@glimmer/tracking';
 import type Owner from '@ember/owner';
 
@@ -892,3 +893,283 @@ moduleFor(
     }
   }
 );
+
+/**
+ * Coverage for `consume()` and `captureContext()`:
+ *
+ * - `consume()` with no argument behaves exactly like reading `value`
+ *   (same result, same error cases).
+ * - `captureContext()` captures the current render-tree position; passing
+ *   the handle to `consume(captured)` resolves the context from that
+ *   position *outside* of rendering (the event-handler use case).
+ */
+moduleFor(
+  'RFC #1200 -- createContext: consume() and captureContext()',
+  class extends CreateContextTestCase {
+    afterEach() {
+      runDestroy(this);
+    }
+
+    '@test consume() with no argument reads like value'(assert: QUnit['assert']) {
+      const ctx = createContext<string>();
+
+      let observed: string | undefined;
+      class Reader extends GlimmerishComponent {
+        constructor(owner: Owner, args: Record<string, unknown>) {
+          super(owner, args);
+          observed = ctx.consume();
+        }
+      }
+      setComponentTemplate(precompileTemplate(''), Reader);
+
+      let Root = setComponentTemplate(
+        precompileTemplate('<ctx.Provide @value="ambient"><Reader/></ctx.Provide>', {
+          strictMode: true,
+          scope: () => ({ ctx, Reader }),
+        }),
+        templateOnly()
+      );
+
+      this.renderComponent(Root);
+      assert.strictEqual(observed, 'ambient', 'consume() saw the provided value');
+    }
+
+    '@test consume() with no argument throws outside of rendering'(assert: QUnit['assert']) {
+      const ctx = createContext<string>();
+
+      assert.throws(
+        () => ctx.consume(),
+        /outside of rendering/,
+        'an ambient consume() outside a render is rejected'
+      );
+    }
+
+    '@test consume() with no argument throws when no <Provide> exists'(assert: QUnit['assert']) {
+      const ctx = createContext<string>();
+
+      let error: Error | undefined;
+      class Reader extends GlimmerishComponent {
+        constructor(owner: Owner, args: Record<string, unknown>) {
+          super(owner, args);
+          try {
+            ctx.consume();
+          } catch (e) {
+            error = e as Error;
+          }
+        }
+      }
+      setComponentTemplate(precompileTemplate(''), Reader);
+
+      let Root = setComponentTemplate(
+        precompileTemplate('<Reader/>', { strictMode: true, scope: () => ({ Reader }) }),
+        templateOnly()
+      );
+
+      this.renderComponent(Root);
+      assert.ok(
+        /No matching `<Provide>`/.test(error?.message ?? ''),
+        `error mentions missing provider, got: ${error?.message}`
+      );
+    }
+
+    '@test captureContext() throws outside of rendering'(assert: QUnit['assert']) {
+      assert.throws(
+        () => captureContext(),
+        /outside of rendering/,
+        'a capture outside a render is rejected'
+      );
+    }
+
+    '@test consume(captured) resolves the context from an event handler'(assert: QUnit['assert']) {
+      const theme = createContext<{ color: string }>();
+      const value = { color: 'rebeccapurple' };
+
+      let observed: { color: string } | undefined;
+      let ambientError: Error | undefined;
+      class Button extends GlimmerishComponent {
+        // Field initializers run in the constructor, during rendering.
+        context = captureContext();
+
+        onClick = () => {
+          // Prove we really are outside of rendering: the ambient read throws...
+          try {
+            void theme.value;
+          } catch (e) {
+            ambientError = e as Error;
+          }
+          // ...but the captured position still resolves.
+          observed = theme.consume(this.context);
+        };
+      }
+      setComponentTemplate(
+        precompileTemplate('<button type="button" {{on "click" this.onClick}}>go</button>', {
+          strictMode: true,
+          scope: () => ({ on }),
+        }),
+        Button
+      );
+
+      let Root = setComponentTemplate(
+        precompileTemplate('<theme.Provide @value={{value}}><Button/></theme.Provide>', {
+          strictMode: true,
+          scope: () => ({ theme, value, Button }),
+        }),
+        templateOnly()
+      );
+
+      this.renderComponent(Root);
+      this.element.querySelector('button')!.click();
+
+      assert.ok(
+        /outside of rendering/.test(ambientError?.message ?? ''),
+        'the ambient value read in the handler threw (we were outside of rendering)'
+      );
+      assert.strictEqual(observed, value, 'consume(captured) resolved the provided value');
+    }
+
+    '@test consume(captured) resolves the nearest provider above the captured position'(
+      assert: QUnit['assert']
+    ) {
+      const ctx = createContext<string>();
+
+      let innerCapture: CapturedContext | undefined;
+      let outerCapture: CapturedContext | undefined;
+      class InnerReader extends GlimmerishComponent {
+        constructor(owner: Owner, args: Record<string, unknown>) {
+          super(owner, args);
+          innerCapture = captureContext();
+        }
+      }
+      class OuterReader extends GlimmerishComponent {
+        constructor(owner: Owner, args: Record<string, unknown>) {
+          super(owner, args);
+          outerCapture = captureContext();
+        }
+      }
+      setComponentTemplate(precompileTemplate(''), InnerReader);
+      setComponentTemplate(precompileTemplate(''), OuterReader);
+
+      let Root = setComponentTemplate(
+        precompileTemplate(
+          `<ctx.Provide @value="outer">
+             <OuterReader/>
+             <ctx.Provide @value="inner">
+               <InnerReader/>
+             </ctx.Provide>
+           </ctx.Provide>`,
+          { strictMode: true, scope: () => ({ ctx, InnerReader, OuterReader }) }
+        ),
+        templateOnly()
+      );
+
+      this.renderComponent(Root);
+
+      // Both resolutions happen here, after the render stack has unwound.
+      assert.strictEqual(ctx.consume(outerCapture!), 'outer', 'outer capture sees "outer"');
+      assert.strictEqual(ctx.consume(innerCapture!), 'inner', 'inner capture sees "inner"');
+    }
+
+    '@test one captured handle works with every context'(assert: QUnit['assert']) {
+      const ctxA = createContext<string>();
+      const ctxB = createContext<string>();
+
+      let captured: CapturedContext | undefined;
+      class Reader extends GlimmerishComponent {
+        constructor(owner: Owner, args: Record<string, unknown>) {
+          super(owner, args);
+          captured = captureContext();
+        }
+      }
+      setComponentTemplate(precompileTemplate(''), Reader);
+
+      let Root = setComponentTemplate(
+        precompileTemplate(
+          '<ctxA.Provide @value="A"><ctxB.Provide @value="B"><Reader/></ctxB.Provide></ctxA.Provide>',
+          { strictMode: true, scope: () => ({ ctxA, ctxB, Reader }) }
+        ),
+        templateOnly()
+      );
+
+      this.renderComponent(Root);
+
+      assert.strictEqual(ctxA.consume(captured!), 'A', 'the handle resolves ctxA');
+      assert.strictEqual(ctxB.consume(captured!), 'B', 'the same handle resolves ctxB');
+    }
+
+    '@test consume(captured) reads the current @value, not a snapshot'(assert: QUnit['assert']) {
+      class State {
+        @tracked count = 1;
+      }
+      const state = new State();
+      const ctx = createContext<number>();
+
+      let captured: CapturedContext | undefined;
+      class Reader extends GlimmerishComponent {
+        constructor(owner: Owner, args: Record<string, unknown>) {
+          super(owner, args);
+          captured = captureContext();
+        }
+      }
+      setComponentTemplate(precompileTemplate(''), Reader);
+
+      let Root = setComponentTemplate(
+        precompileTemplate('<ctx.Provide @value={{state.count}}><Reader/></ctx.Provide>', {
+          strictMode: true,
+          scope: () => ({ ctx, state, Reader }),
+        }),
+        templateOnly()
+      );
+
+      this.renderComponent(Root);
+      assert.strictEqual(ctx.consume(captured!), 1, 'initial value');
+
+      run(() => {
+        state.count = 2;
+      });
+      assert.strictEqual(ctx.consume(captured!), 2, 'resolution reflects the updated @value');
+    }
+
+    '@test consume(captured) throws when no provider exists above the captured position'(
+      assert: QUnit['assert']
+    ) {
+      const provided = createContext<string>();
+      const missing = createContext<string>();
+
+      let captured: CapturedContext | undefined;
+      class Reader extends GlimmerishComponent {
+        constructor(owner: Owner, args: Record<string, unknown>) {
+          super(owner, args);
+          captured = captureContext();
+        }
+      }
+      setComponentTemplate(precompileTemplate(''), Reader);
+
+      let Root = setComponentTemplate(
+        precompileTemplate('<provided.Provide @value="here"><Reader/></provided.Provide>', {
+          strictMode: true,
+          scope: () => ({ provided, Reader }),
+        }),
+        templateOnly()
+      );
+
+      this.renderComponent(Root);
+
+      assert.strictEqual(provided.consume(captured!), 'here', 'sanity: the handle is valid');
+      assert.throws(
+        () => missing.consume(captured!),
+        /No matching `<Provide>` was found above the captured render-tree position/,
+        'a context with no provider above the captured position is rejected'
+      );
+    }
+
+    '@test consume(captured) rejects a value that is not a capture'(assert: QUnit['assert']) {
+      const ctx = createContext<string>();
+
+      assert.throws(
+        () => ctx.consume({} as CapturedContext),
+        /expects the handle returned from `captureContext\(\)`/,
+        'an arbitrary object is not accepted as a capture'
+      );
+    }
+  }
+);
diff --git a/packages/@ember/helper/index.ts b/packages/@ember/helper/index.ts
index 92152f2a831..e08107ec884 100644
--- a/packages/@ember/helper/index.ts
+++ b/packages/@ember/helper/index.ts
@@ -727,6 +727,10 @@ export interface NotHelper extends Opaque<'helper:not'> {}
  * - `value`: a getter (also usable as a template path) that returns the
  *    nearest enclosing provided value. **Throws** if there is no matching
  *    provider higher in the render tree, or if read outside of rendering.
+ * - `consume`: with no argument, identical to reading `value`. Passed a
+ *    handle from `captureContext()`, it resolves the context from that
+ *    captured render-tree position instead -- the way to read a context
+ *    from event handlers and other code that runs outside of rendering.
  *
  * ```gjs
  * import { createContext } from '@ember/helper';
@@ -753,9 +757,62 @@ export interface NotHelper extends Opaque<'helper:not'> {}
  * @method createContext
  * @static
  * @for @ember/helper
- * @returns {Object} `{ Provide, value }`
+ * @returns {Object} `{ Provide, value, consume }`
  * @public
  */
 export { createContext } from '@ember/-internals/glimmer/lib/create-context';
 
-export type { Context } from '@ember/-internals/glimmer/lib/create-context';
+/**
+ * Captures the current render-tree position as an opaque handle that can be
+ * passed to a context's `consume(captured)` later.
+ *
+ * The ambient reads — `context.value` or `context.consume()` — only work
+ * while rendering, because they resolve against the currently-rendering
+ * node. Event handlers, timers, and other async callbacks run after the
+ * render stack has unwound, so they have no ambient position to read from.
+ * `captureContext()` bridges that gap: call it while rendering (a component
+ * constructor or a field initializer is the natural spot), keep the handle,
+ * and resolve any context from that position later.
+ *
+ * ```gjs
+ * import Component from '@glimmer/component';
+ * import { createContext, captureContext } from '@ember/helper';
+ * import { on } from '@ember/modifier';
+ *
+ * const theme = createContext<Theme>();
+ *
+ * class ThemedButton extends Component {
+ *   // Field initializers run in the constructor, during rendering, so this
+ *   // captures the position of <ThemedButton/> in the render tree.
+ *   context = captureContext();
+ *
+ *   onClick = () => {
+ *     // Outside of rendering, `theme.value` would throw — but the captured
+ *     // handle still resolves the nearest <theme.Provide> above this
+ *     // component.
+ *     console.log(theme.consume(this.context).color);
+ *   };
+ *
+ *   <template>
+ *     <button {{on 'click' this.onClick}}>{{yield}}</button>
+ *   </template>
+ * }
+ * ```
+ *
+ * A single captured handle works with every context — it captures the
+ * render-tree position, not any one context's value. Resolution happens at
+ * `consume` time, so the value read is the provider's current `@value`, not
+ * a snapshot from when the handle was captured.
+ *
+ * **Throws** if called outside of rendering — there is no position to
+ * capture.
+ *
+ * @method captureContext
+ * @static
+ * @for @ember/helper
+ * @returns {Object} An opaque handle for `consume(captured)`
+ * @public
+ */
+export { captureContext } from '@ember/-internals/glimmer/lib/create-context';
+
+export type { Context, CapturedContext } from '@ember/-internals/glimmer/lib/create-context';
diff --git a/packages/@glimmer/runtime/lib/render-scope.ts b/packages/@glimmer/runtime/lib/render-scope.ts
index bf6eab315f3..dbfb7665643 100644
--- a/packages/@glimmer/runtime/lib/render-scope.ts
+++ b/packages/@glimmer/runtime/lib/render-scope.ts
@@ -67,14 +67,25 @@ export class RenderScopeTracker {
     if (current === null) {
       return undefined;
     }
-    for (let node: Nullable<RenderScopeNode> = current; node !== null; node = node.parent) {
-      let read = node.contexts?.get(key);
-      if (read !== undefined) {
-        return read;
-      }
+    return lookupInChain(current, key);
+  }
+
+  // The node currently being rendered, for `captureRenderScope`. `null`
+  // outside a render frame.
+  capture(): Nullable<RenderScopeNode> {
+    return this.stack.current;
+  }
+}
+
+// Walk `start` and its ancestors for the nearest provider of `key`.
+function lookupInChain(start: RenderScopeNode, key: object): ContextRead | null {
+  for (let node: Nullable<RenderScopeNode> = start; node !== null; node = node.parent) {
+    let read = node.contexts?.get(key);
+    if (read !== undefined) {
+      return read;
     }
-    return null;
   }
+  return null;
 }
 
 // The renderer points this at the active tracker for the duration of a render,
@@ -103,3 +114,45 @@ export function provideRenderContext(key: object, read: ContextRead): void {
 export function lookupRenderContext(key: object): ContextRead | null | undefined {
   return CURRENT === undefined ? undefined : CURRENT.lookup(key);
 }
+
+// captured handle -> node. Handing out an empty frozen object (rather than
+// the node itself) keeps captures opaque: user code can't forge or introspect
+// one. The node -- and the provider chain above it -- stays resolvable for as
+// long as user code holds the handle.
+const CAPTURED_NODES = new WeakMap<object, RenderScopeNode>();
+
+/**
+ * Capture the current render-tree position as an opaque handle
+ * (createContext's `captureContext`). The handle can be resolved later with
+ * `lookupCapturedRenderContext`, even after the render stack has unwound.
+ * Returns `undefined` when called outside of rendering -- there is no
+ * position to capture.
+ */
+export function captureRenderScope(): object | undefined {
+  let node = CURRENT === undefined ? null : CURRENT.capture();
+  if (node === null) {
+    return undefined;
+  }
+  let handle = Object.freeze({});
+  CAPTURED_NODES.set(handle, node);
+  return handle;
+}
+
+/**
+ * The nearest provider of `key` above a previously-captured render-tree
+ * position:
+ *   `undefined` -> `handle` is not a capture produced by `captureRenderScope`,
+ *   `null`      -> a valid capture, but no provider for `key` above it,
+ *   a function  -> the nearest provider's read fn.
+ *
+ * Unlike `lookupRenderContext` this works outside of rendering -- that is the
+ * point: event handlers and other async callbacks run after the render stack
+ * has unwound, so the ambient lookup has nothing to see.
+ */
+export function lookupCapturedRenderContext(
+  handle: object,
+  key: object
+): ContextRead | null | undefined {
+  let node = CAPTURED_NODES.get(handle);
+  return node === undefined ? undefined : lookupInChain(node, key);
+}
diff --git a/tests/docs/expected.cjs b/tests/docs/expected.cjs
index bfbcd844102..56a1cc9b11b 100644
--- a/tests/docs/expected.cjs
+++ b/tests/docs/expected.cjs
@@ -99,6 +99,7 @@ module.exports = {
     'cancelRouterSetup',
     'canInvoke',
     'capabilities',
+    'captureContext',
     'captureRenderTree',
     'catalogEntriesByType',
     'catch',
diff --git a/type-tests/@ember/helper-tests.ts b/type-tests/@ember/helper-tests.ts
index 014d54a3855..96f1000d83a 100644
--- a/type-tests/@ember/helper-tests.ts
+++ b/type-tests/@ember/helper-tests.ts
@@ -10,7 +10,9 @@ import {
   hash,
   type HashHelper,
   createContext,
+  captureContext,
   type Context,
+  type CapturedContext,
   uniqueId,
   type UniqueIdHelper,
 } from '@ember/helper';
@@ -35,3 +37,19 @@ expectTypeOf(theme.value).toEqualTypeOf<Theme>();
 
 // @ts-expect-error createContext does not accept a class (or any value) argument
 createContext(Theme);
+
+// `consume()` with no argument reads ambiently, like `value`
+expectTypeOf(theme.consume()).toEqualTypeOf<Theme>();
+
+// `consume(captured)` resolves from a captured render-tree position
+const captured = captureContext();
+expectTypeOf(captured).toEqualTypeOf<CapturedContext>();
+expectTypeOf(theme.consume(captured)).toEqualTypeOf<Theme>();
+
+// captureContext takes no arguments
+// @ts-expect-error
+captureContext(theme);
+
+// The capture is opaque -- arbitrary objects don't typecheck as one
+// @ts-expect-error
+theme.consume({});

From 4fae99c5f57dc9ac9786d45aa1480a2a5461febb Mon Sep 17 00:00:00 2001
From: NullVoxPopuli <199018+NullVoxPopuli@users.noreply.github.com>
Date: Mon, 6 Jul 2026 15:18:52 -0400
Subject: [PATCH 2/2] Make the render-tree position an implementation detail:
 consume(this)

Review feedback: users should not need to capture a handle themselves.
Drop the public captureContext() export entirely. Instead, the VM
associates the user-facing component instance with its render-scope
node when the component's self becomes known (VM_GET_COMPONENT_SELF_OP,
via a WeakMap in the render-scope layer), so an event handler can just
pass the component itself:

    onClick = () => theme.consume(this);

Component self refs are const refs wrapping the instance, so the eager
read consumes no tracking tags; template-only components have a
NULL_REFERENCE self and are skipped (there is no instance to pass).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/@ember/-internals/glimmer/index.ts   |   7 +-
 .../-internals/glimmer/lib/create-context.ts  | 137 ++++++------------
 .../tests/integration/create-context-test.ts  |  89 +++++-------
 packages/@ember/helper/index.ts               |  58 ++------
 .../runtime/lib/compiled/opcodes/component.ts |  15 ++
 packages/@glimmer/runtime/lib/render-scope.ts |  43 +++---
 tests/docs/expected.cjs                       |   1 -
 type-tests/@ember/helper-tests.ts             |  18 +--
 8 files changed, 139 insertions(+), 229 deletions(-)

diff --git a/packages/@ember/-internals/glimmer/index.ts b/packages/@ember/-internals/glimmer/index.ts
index a8e9b4a781c..e0ce66b3054 100644
--- a/packages/@ember/-internals/glimmer/index.ts
+++ b/packages/@ember/-internals/glimmer/index.ts
@@ -519,12 +519,7 @@ export {
   type View,
 } from './lib/renderer';
 // RFC #1200 -- render-tree-scoped context (provide/consume)
-export {
-  createContext,
-  captureContext,
-  type Context,
-  type CapturedContext,
-} from './lib/create-context';
+export { createContext, type Context } from './lib/create-context';
 export {
   getTemplate,
   setTemplate,
diff --git a/packages/@ember/-internals/glimmer/lib/create-context.ts b/packages/@ember/-internals/glimmer/lib/create-context.ts
index 8951209e4fc..1ef1487e823 100644
--- a/packages/@ember/-internals/glimmer/lib/create-context.ts
+++ b/packages/@ember/-internals/glimmer/lib/create-context.ts
@@ -3,9 +3,8 @@
  */
 import { precompileTemplate } from '@ember/template-compilation';
 import {
-  captureRenderScope,
-  lookupCapturedRenderContext,
   lookupRenderContext,
+  lookupRenderContextFor,
   provideRenderContext,
 } from '@glimmer/runtime/lib/render-scope';
 import { valueForRef } from '@glimmer/reference/lib/reference';
@@ -14,32 +13,16 @@ import InternalComponent, {
   opaquify,
 } from './components/internal';
 
-declare const CAPTURED_CONTEXT: unique symbol;
-
-/**
- * An opaque handle to a position in the render tree, returned by
- * `captureContext()`. Pass it to a context's `consume(captured)` to resolve
- * that context from the captured position later -- e.g. inside an event
- * handler, after the render stack has unwound and ambient reads like `value`
- * would throw.
- */
-export interface CapturedContext {
-  // A type-only brand so arbitrary objects don't typecheck as a capture. The
-  // only way to obtain one is `captureContext()`; at runtime validity is
-  // checked against the render-scope layer's WeakMap, not this symbol.
-  readonly [CAPTURED_CONTEXT]: never;
-}
-
 /**
  * The shape returned by `createContext`. Use `Provide` in templates to bind a
  * value into the render tree, read `value` to get the nearest enclosing
- * provided value, or call `consume(captured)` to read it from a previously
- * captured render-tree position (e.g. in an event handler).
+ * provided value, or call `consume(this)` to read it from a component
+ * instance's position in the render tree (e.g. in an event handler).
  */
 export interface Context<T> {
   Provide: OpaqueInternalComponentConstructor;
   get value(): T;
-  consume(captured?: CapturedContext): T;
+  consume(consumer?: object): T;
 }
 
 /**
@@ -93,18 +76,43 @@ export interface Context<T> {
  * one at the application root.
  *
  * The returned object also has a `consume()` method. With no argument it
- * behaves exactly like reading `value`. Passed a handle from
- * `captureContext()`, it resolves the context from that captured
- * render-tree position instead -- the way to read a context from event
- * handlers and other code that runs outside of rendering (see
- * `captureContext`).
+ * behaves exactly like reading `value`. Passed a component instance, it
+ * resolves the context from that component's position in the render tree
+ * instead -- the way to read a context from event handlers and other code
+ * that runs outside of rendering:
+ *
+ * ```gjs
+ * import Component from '@glimmer/component';
+ * import { createContext } from '@ember/helper';
+ * import { on } from '@ember/modifier';
+ *
+ * const theme = createContext<Theme>();
+ *
+ * class ThemedButton extends Component {
+ *   onClick = () => {
+ *     // Outside of rendering, `theme.value` would throw -- but passing the
+ *     // component instance resolves the nearest <theme.Provide> above it.
+ *     console.log(theme.consume(this).color);
+ *   };
+ *
+ *   <template>
+ *     <button {{on 'click' this.onClick}}>{{yield}}</button>
+ *   </template>
+ * }
+ * ```
+ *
+ * Any rendered component instance works with every context -- the instance
+ * identifies a position in the render tree, not any one context's value.
+ * Resolution happens at `consume` time, so the value read is the provider's
+ * current `@value`, not a snapshot from render time.
  *
  * @method createContext
  * @static
  * @for @ember/helper
  * @returns {Object} An object with `Provide` (a component that takes a
  *   `@value`), `value` (a getter that reads the nearest provided value), and
- *   `consume` (reads ambiently like `value`, or from a captured position).
+ *   `consume` (reads ambiently like `value`, or from a component instance's
+ *   position).
  * @public
  */
 export function createContext<T>(): Context<T> {
@@ -142,7 +150,7 @@ export function createContext<T>(): Context<T> {
     let read = lookupRenderContext(key);
     if (read === undefined) {
       throw new Error(
-        'A context `value` was read outside of rendering. The render-tree scope is only available during rendering -- there is nothing to read. To read a context from an event handler or other async callback, capture a handle during rendering with `captureContext()` and pass it to `consume(captured)`.'
+        'A context `value` was read outside of rendering. The render-tree scope is only available during rendering -- there is nothing to read. To read a context from an event handler or other async callback, pass the component instance: `context.consume(this)`.'
       );
     }
     if (read === null) {
@@ -160,20 +168,20 @@ export function createContext<T>(): Context<T> {
       return resolveAmbient();
     },
 
-    consume(captured?: CapturedContext): T {
-      if (captured === undefined) {
+    consume(consumer?: object): T {
+      if (consumer === undefined) {
         return resolveAmbient();
       }
 
-      let read = lookupCapturedRenderContext(captured, key);
+      let read = lookupRenderContextFor(consumer, key);
       if (read === undefined) {
         throw new Error(
-          '`consume(captured)` expects the handle returned from `captureContext()`, but received some other value.'
+          '`consume(component)` expects a component instance that has been rendered -- the instance is how the context finds its position in the render tree. Pass the component itself (usually `this`), not another object, and only after the component has rendered.'
         );
       }
       if (read === null) {
         throw new Error(
-          'No matching `<Provide>` was found above the captured render-tree position. Wrap the component that called `captureContext()` in `<Context.Provide @value={{...}}>...</Context.Provide>`, or provide a default at the application root.'
+          'No matching `<Provide>` was found above the component passed to `consume`. Wrap the component in `<Context.Provide @value={{...}}>...</Context.Provide>`, or provide a default at the application root.'
         );
       }
       return read() as T;
@@ -181,69 +189,6 @@ export function createContext<T>(): Context<T> {
   };
 }
 
-/**
- * Captures the current render-tree position as an opaque handle that can be
- * passed to a context's `consume(captured)` later.
- *
- * The ambient reads -- `context.value` or `context.consume()` -- only work
- * while rendering, because they resolve against the currently-rendering
- * node. Event handlers, timers, and other async callbacks run after the
- * render stack has unwound, so they have no ambient position to read from.
- * `captureContext()` bridges that gap: call it while rendering (a component
- * constructor or a field initializer is the natural spot), keep the handle,
- * and resolve any context from that position later.
- *
- * @example
- *
- * ```gjs
- * import Component from '@glimmer/component';
- * import { createContext, captureContext } from '@ember/helper';
- * import { on } from '@ember/modifier';
- *
- * const theme = createContext<Theme>();
- *
- * class ThemedButton extends Component {
- *   // Field initializers run in the constructor, during rendering, so this
- *   // captures the position of <ThemedButton/> in the render tree.
- *   context = captureContext();
- *
- *   onClick = () => {
- *     // Outside of rendering, `theme.value` would throw -- but the captured
- *     // handle still resolves the nearest <theme.Provide> above this
- *     // component.
- *     console.log(theme.consume(this.context).color);
- *   };
- *
- *   <template>
- *     <button {{on 'click' this.onClick}}>{{yield}}</button>
- *   </template>
- * }
- * ```
- *
- * A single captured handle works with every context -- it captures the
- * render-tree position, not any one context's value. Resolution happens at
- * `consume` time, so the value read is the provider's current `@value`, not
- * a snapshot from when the handle was captured.
- *
- * `captureContext()` throws if called outside of rendering -- there is no
- * position to capture.
- *
- * @method captureContext
- * @static
- * @for @ember/helper
- * @returns {Object} An opaque handle for `consume(captured)`.
- * @public
- */
-export function captureContext(): CapturedContext {
-  let handle = captureRenderScope();
-  if (handle === undefined) {
-    throw new Error(
-      '`captureContext()` was called outside of rendering -- there is no render-tree position to capture. Capture while rendering (e.g. in a component constructor or field initializer) and pass the handle to `consume(captured)` later.'
-    );
-  }
-  return handle as CapturedContext;
-}
-
 // All Provide components share the same template: yield to the block.
 // Per-instance behavior is parameterized via the closure in createContext.
 const PROVIDE_TEMPLATE = precompileTemplate('{{yield}}');
diff --git a/packages/@ember/-internals/glimmer/tests/integration/create-context-test.ts b/packages/@ember/-internals/glimmer/tests/integration/create-context-test.ts
index d0558b1b03a..17b3ae4f592 100644
--- a/packages/@ember/-internals/glimmer/tests/integration/create-context-test.ts
+++ b/packages/@ember/-internals/glimmer/tests/integration/create-context-test.ts
@@ -15,7 +15,7 @@ import { run } from '@ember/runloop';
 import { associateDestroyableChild, registerDestructor } from '@glimmer/destroyable';
 import { on } from '@ember/modifier';
 import { renderComponent } from '../../lib/renderer';
-import { captureContext, createContext, type CapturedContext } from '../../lib/create-context';
+import { createContext } from '../../lib/create-context';
 import { tracked } from '@glimmer/tracking';
 import type Owner from '@ember/owner';
 
@@ -895,16 +895,18 @@ moduleFor(
 );
 
 /**
- * Coverage for `consume()` and `captureContext()`:
+ * Coverage for `consume()`:
  *
  * - `consume()` with no argument behaves exactly like reading `value`
  *   (same result, same error cases).
- * - `captureContext()` captures the current render-tree position; passing
- *   the handle to `consume(captured)` resolves the context from that
- *   position *outside* of rendering (the event-handler use case).
+ * - `consume(componentInstance)` resolves the context from that component's
+ *   position in the render tree, *outside* of rendering (the event-handler
+ *   use case). The instance -> render-node association is made by the VM
+ *   when the component renders -- an implementation detail; user code just
+ *   passes `this`.
  */
 moduleFor(
-  'RFC #1200 -- createContext: consume() and captureContext()',
+  'RFC #1200 -- createContext: consume()',
   class extends CreateContextTestCase {
     afterEach() {
       runDestroy(this);
@@ -972,24 +974,13 @@ moduleFor(
       );
     }
 
-    '@test captureContext() throws outside of rendering'(assert: QUnit['assert']) {
-      assert.throws(
-        () => captureContext(),
-        /outside of rendering/,
-        'a capture outside a render is rejected'
-      );
-    }
-
-    '@test consume(captured) resolves the context from an event handler'(assert: QUnit['assert']) {
+    '@test consume(this) resolves the context from an event handler'(assert: QUnit['assert']) {
       const theme = createContext<{ color: string }>();
       const value = { color: 'rebeccapurple' };
 
       let observed: { color: string } | undefined;
       let ambientError: Error | undefined;
       class Button extends GlimmerishComponent {
-        // Field initializers run in the constructor, during rendering.
-        context = captureContext();
-
         onClick = () => {
           // Prove we really are outside of rendering: the ambient read throws...
           try {
@@ -997,8 +988,8 @@ moduleFor(
           } catch (e) {
             ambientError = e as Error;
           }
-          // ...but the captured position still resolves.
-          observed = theme.consume(this.context);
+          // ...but the component instance's position still resolves.
+          observed = theme.consume(this);
         };
       }
       setComponentTemplate(
@@ -1024,26 +1015,26 @@ moduleFor(
         /outside of rendering/.test(ambientError?.message ?? ''),
         'the ambient value read in the handler threw (we were outside of rendering)'
       );
-      assert.strictEqual(observed, value, 'consume(captured) resolved the provided value');
+      assert.strictEqual(observed, value, 'consume(this) resolved the provided value');
     }
 
-    '@test consume(captured) resolves the nearest provider above the captured position'(
+    '@test consume(this) resolves the nearest provider above each component'(
       assert: QUnit['assert']
     ) {
       const ctx = createContext<string>();
 
-      let innerCapture: CapturedContext | undefined;
-      let outerCapture: CapturedContext | undefined;
+      let innerInstance: object | undefined;
+      let outerInstance: object | undefined;
       class InnerReader extends GlimmerishComponent {
         constructor(owner: Owner, args: Record<string, unknown>) {
           super(owner, args);
-          innerCapture = captureContext();
+          innerInstance = this;
         }
       }
       class OuterReader extends GlimmerishComponent {
         constructor(owner: Owner, args: Record<string, unknown>) {
           super(owner, args);
-          outerCapture = captureContext();
+          outerInstance = this;
         }
       }
       setComponentTemplate(precompileTemplate(''), InnerReader);
@@ -1065,19 +1056,19 @@ moduleFor(
       this.renderComponent(Root);
 
       // Both resolutions happen here, after the render stack has unwound.
-      assert.strictEqual(ctx.consume(outerCapture!), 'outer', 'outer capture sees "outer"');
-      assert.strictEqual(ctx.consume(innerCapture!), 'inner', 'inner capture sees "inner"');
+      assert.strictEqual(ctx.consume(outerInstance!), 'outer', 'outer component sees "outer"');
+      assert.strictEqual(ctx.consume(innerInstance!), 'inner', 'inner component sees "inner"');
     }
 
-    '@test one captured handle works with every context'(assert: QUnit['assert']) {
+    '@test one component instance works with every context'(assert: QUnit['assert']) {
       const ctxA = createContext<string>();
       const ctxB = createContext<string>();
 
-      let captured: CapturedContext | undefined;
+      let instance: object | undefined;
       class Reader extends GlimmerishComponent {
         constructor(owner: Owner, args: Record<string, unknown>) {
           super(owner, args);
-          captured = captureContext();
+          instance = this;
         }
       }
       setComponentTemplate(precompileTemplate(''), Reader);
@@ -1092,22 +1083,22 @@ moduleFor(
 
       this.renderComponent(Root);
 
-      assert.strictEqual(ctxA.consume(captured!), 'A', 'the handle resolves ctxA');
-      assert.strictEqual(ctxB.consume(captured!), 'B', 'the same handle resolves ctxB');
+      assert.strictEqual(ctxA.consume(instance!), 'A', 'the instance resolves ctxA');
+      assert.strictEqual(ctxB.consume(instance!), 'B', 'the same instance resolves ctxB');
     }
 
-    '@test consume(captured) reads the current @value, not a snapshot'(assert: QUnit['assert']) {
+    '@test consume(this) reads the current @value, not a snapshot'(assert: QUnit['assert']) {
       class State {
         @tracked count = 1;
       }
       const state = new State();
       const ctx = createContext<number>();
 
-      let captured: CapturedContext | undefined;
+      let instance: object | undefined;
       class Reader extends GlimmerishComponent {
         constructor(owner: Owner, args: Record<string, unknown>) {
           super(owner, args);
-          captured = captureContext();
+          instance = this;
         }
       }
       setComponentTemplate(precompileTemplate(''), Reader);
@@ -1121,25 +1112,25 @@ moduleFor(
       );
 
       this.renderComponent(Root);
-      assert.strictEqual(ctx.consume(captured!), 1, 'initial value');
+      assert.strictEqual(ctx.consume(instance!), 1, 'initial value');
 
       run(() => {
         state.count = 2;
       });
-      assert.strictEqual(ctx.consume(captured!), 2, 'resolution reflects the updated @value');
+      assert.strictEqual(ctx.consume(instance!), 2, 'resolution reflects the updated @value');
     }
 
-    '@test consume(captured) throws when no provider exists above the captured position'(
+    '@test consume(this) throws when no provider exists above the component'(
       assert: QUnit['assert']
     ) {
       const provided = createContext<string>();
       const missing = createContext<string>();
 
-      let captured: CapturedContext | undefined;
+      let instance: object | undefined;
       class Reader extends GlimmerishComponent {
         constructor(owner: Owner, args: Record<string, unknown>) {
           super(owner, args);
-          captured = captureContext();
+          instance = this;
         }
       }
       setComponentTemplate(precompileTemplate(''), Reader);
@@ -1154,21 +1145,21 @@ moduleFor(
 
       this.renderComponent(Root);
 
-      assert.strictEqual(provided.consume(captured!), 'here', 'sanity: the handle is valid');
+      assert.strictEqual(provided.consume(instance!), 'here', 'sanity: the instance is known');
       assert.throws(
-        () => missing.consume(captured!),
-        /No matching `<Provide>` was found above the captured render-tree position/,
-        'a context with no provider above the captured position is rejected'
+        () => missing.consume(instance!),
+        /No matching `<Provide>` was found above the component/,
+        'a context with no provider above the component is rejected'
       );
     }
 
-    '@test consume(captured) rejects a value that is not a capture'(assert: QUnit['assert']) {
+    '@test consume(component) rejects an object that never rendered'(assert: QUnit['assert']) {
       const ctx = createContext<string>();
 
       assert.throws(
-        () => ctx.consume({} as CapturedContext),
-        /expects the handle returned from `captureContext\(\)`/,
-        'an arbitrary object is not accepted as a capture'
+        () => ctx.consume({}),
+        /expects a component instance that has been rendered/,
+        'an arbitrary object is not accepted'
       );
     }
   }
diff --git a/packages/@ember/helper/index.ts b/packages/@ember/helper/index.ts
index e08107ec884..9bd4b1b1de3 100644
--- a/packages/@ember/helper/index.ts
+++ b/packages/@ember/helper/index.ts
@@ -728,9 +728,9 @@ export interface NotHelper extends Opaque<'helper:not'> {}
  *    nearest enclosing provided value. **Throws** if there is no matching
  *    provider higher in the render tree, or if read outside of rendering.
  * - `consume`: with no argument, identical to reading `value`. Passed a
- *    handle from `captureContext()`, it resolves the context from that
- *    captured render-tree position instead -- the way to read a context
- *    from event handlers and other code that runs outside of rendering.
+ *    component instance, it resolves the context from that component's
+ *    position in the render tree instead -- the way to read a context from
+ *    event handlers and other code that runs outside of rendering.
  *
  * ```gjs
  * import { createContext } from '@ember/helper';
@@ -754,43 +754,21 @@ export interface NotHelper extends Opaque<'helper:not'> {}
  * consumers re-render; mutating `@tracked` fields on a stable provided
  * object likewise invalidates consumers.
  *
- * @method createContext
- * @static
- * @for @ember/helper
- * @returns {Object} `{ Provide, value, consume }`
- * @public
- */
-export { createContext } from '@ember/-internals/glimmer/lib/create-context';
-
-/**
- * Captures the current render-tree position as an opaque handle that can be
- * passed to a context's `consume(captured)` later.
- *
- * The ambient reads — `context.value` or `context.consume()` — only work
- * while rendering, because they resolve against the currently-rendering
- * node. Event handlers, timers, and other async callbacks run after the
- * render stack has unwound, so they have no ambient position to read from.
- * `captureContext()` bridges that gap: call it while rendering (a component
- * constructor or a field initializer is the natural spot), keep the handle,
- * and resolve any context from that position later.
+ * Reading a context from an event handler (or any other code that runs
+ * outside of rendering, where the ambient `value` read throws) works by
+ * passing the component instance to `consume` — the instance identifies the
+ * component's position in the render tree:
  *
  * ```gjs
  * import Component from '@glimmer/component';
- * import { createContext, captureContext } from '@ember/helper';
+ * import { createContext } from '@ember/helper';
  * import { on } from '@ember/modifier';
  *
  * const theme = createContext<Theme>();
  *
  * class ThemedButton extends Component {
- *   // Field initializers run in the constructor, during rendering, so this
- *   // captures the position of <ThemedButton/> in the render tree.
- *   context = captureContext();
- *
  *   onClick = () => {
- *     // Outside of rendering, `theme.value` would throw — but the captured
- *     // handle still resolves the nearest <theme.Provide> above this
- *     // component.
- *     console.log(theme.consume(this.context).color);
+ *     console.log(theme.consume(this).color);
  *   };
  *
  *   <template>
@@ -799,20 +777,16 @@ export { createContext } from '@ember/-internals/glimmer/lib/create-context';
  * }
  * ```
  *
- * A single captured handle works with every context — it captures the
- * render-tree position, not any one context's value. Resolution happens at
- * `consume` time, so the value read is the provider's current `@value`, not
- * a snapshot from when the handle was captured.
+ * Any rendered component instance works with every context, and resolution
+ * happens at `consume` time — the value read is the provider's current
+ * `@value`, not a snapshot from render time.
  *
- * **Throws** if called outside of rendering — there is no position to
- * capture.
- *
- * @method captureContext
+ * @method createContext
  * @static
  * @for @ember/helper
- * @returns {Object} An opaque handle for `consume(captured)`
+ * @returns {Object} `{ Provide, value, consume }`
  * @public
  */
-export { captureContext } from '@ember/-internals/glimmer/lib/create-context';
+export { createContext } from '@ember/-internals/glimmer/lib/create-context';
 
-export type { Context, CapturedContext } from '@ember/-internals/glimmer/lib/create-context';
+export type { Context } from '@ember/-internals/glimmer/lib/create-context';
diff --git a/packages/@glimmer/runtime/lib/compiled/opcodes/component.ts b/packages/@glimmer/runtime/lib/compiled/opcodes/component.ts
index 961ec280cd8..0a86cb75a7e 100644
--- a/packages/@glimmer/runtime/lib/compiled/opcodes/component.ts
+++ b/packages/@glimmer/runtime/lib/compiled/opcodes/component.ts
@@ -103,6 +103,7 @@ import {
   CheckReference,
 } from './-debug-strip';
 import { UpdateDynamicAttributeOpcode } from './dom';
+import { associateRenderScope } from '../../render-scope';
 
 /**
  * The VM creates a new ComponentInstance data structure for every component
@@ -665,6 +666,20 @@ APPEND_OPCODES.add(VM_GET_COMPONENT_SELF_OP, (vm, { op1: register, op2: _names }
   let { manager } = definition;
   let selfRef = manager.getSelf(state);
 
+  // RFC #1200 -- associate the user-facing component instance with this
+  // component's render-scope node, so `context.consume(this)` can resolve
+  // contexts from event handlers and other code that runs after the render
+  // stack has unwound. Component self refs are const refs wrapping the
+  // instance, so the eager read consumes no tracking tags; template-only
+  // components have a NULL_REFERENCE self and are skipped (there is no
+  // instance for user code to pass).
+  if (isConstRef(selfRef)) {
+    let self: unknown = valueForRef(selfRef);
+    if (self !== null && typeof self === 'object') {
+      associateRenderScope(self);
+    }
+  }
+
   if (vm.env.debugRenderTree !== undefined) {
     let instance = check(vm.fetchValue(check(register, CheckRegister)), CheckComponentInstance);
     let { definition, manager } = instance;
diff --git a/packages/@glimmer/runtime/lib/render-scope.ts b/packages/@glimmer/runtime/lib/render-scope.ts
index dbfb7665643..1e56cda603b 100644
--- a/packages/@glimmer/runtime/lib/render-scope.ts
+++ b/packages/@glimmer/runtime/lib/render-scope.ts
@@ -115,44 +115,41 @@ export function lookupRenderContext(key: object): ContextRead | null | undefined
   return CURRENT === undefined ? undefined : CURRENT.lookup(key);
 }
 
-// captured handle -> node. Handing out an empty frozen object (rather than
-// the node itself) keeps captures opaque: user code can't forge or introspect
-// one. The node -- and the provider chain above it -- stays resolvable for as
-// long as user code holds the handle.
-const CAPTURED_NODES = new WeakMap<object, RenderScopeNode>();
+// user-facing component instance -> its render-scope node. Populated by the
+// VM when a component's `self` becomes known (VM_GET_COMPONENT_SELF_OP), so
+// `context.consume(this)` can resolve contexts after the render stack has
+// unwound. The association -- and the provider chain above the node -- lives
+// exactly as long as the instance itself.
+const ASSOCIATED_NODES = new WeakMap<object, RenderScopeNode>();
 
 /**
- * Capture the current render-tree position as an opaque handle
- * (createContext's `captureContext`). The handle can be resolved later with
- * `lookupCapturedRenderContext`, even after the render stack has unwound.
- * Returns `undefined` when called outside of rendering -- there is no
- * position to capture.
+ * Associate a user-facing component instance with the currently-rendering
+ * node, making the instance usable with `lookupRenderContextFor` later. A
+ * no-op outside of a render frame (there is no node to associate with).
  */
-export function captureRenderScope(): object | undefined {
+export function associateRenderScope(instance: object): void {
   let node = CURRENT === undefined ? null : CURRENT.capture();
-  if (node === null) {
-    return undefined;
+  if (node !== null) {
+    ASSOCIATED_NODES.set(instance, node);
   }
-  let handle = Object.freeze({});
-  CAPTURED_NODES.set(handle, node);
-  return handle;
 }
 
 /**
- * The nearest provider of `key` above a previously-captured render-tree
- * position:
- *   `undefined` -> `handle` is not a capture produced by `captureRenderScope`,
- *   `null`      -> a valid capture, but no provider for `key` above it,
+ * The nearest provider of `key` above `instance`'s position in the render
+ * tree:
+ *   `undefined` -> `instance` has no associated render-scope node (it is not
+ *                  a component instance, or it has not rendered),
+ *   `null`      -> a known instance, but no provider for `key` above it,
  *   a function  -> the nearest provider's read fn.
  *
  * Unlike `lookupRenderContext` this works outside of rendering -- that is the
  * point: event handlers and other async callbacks run after the render stack
  * has unwound, so the ambient lookup has nothing to see.
  */
-export function lookupCapturedRenderContext(
-  handle: object,
+export function lookupRenderContextFor(
+  instance: object,
   key: object
 ): ContextRead | null | undefined {
-  let node = CAPTURED_NODES.get(handle);
+  let node = ASSOCIATED_NODES.get(instance);
   return node === undefined ? undefined : lookupInChain(node, key);
 }
diff --git a/tests/docs/expected.cjs b/tests/docs/expected.cjs
index 56a1cc9b11b..bfbcd844102 100644
--- a/tests/docs/expected.cjs
+++ b/tests/docs/expected.cjs
@@ -99,7 +99,6 @@ module.exports = {
     'cancelRouterSetup',
     'canInvoke',
     'capabilities',
-    'captureContext',
     'captureRenderTree',
     'catalogEntriesByType',
     'catch',
diff --git a/type-tests/@ember/helper-tests.ts b/type-tests/@ember/helper-tests.ts
index 96f1000d83a..8cff51c3aac 100644
--- a/type-tests/@ember/helper-tests.ts
+++ b/type-tests/@ember/helper-tests.ts
@@ -10,9 +10,7 @@ import {
   hash,
   type HashHelper,
   createContext,
-  captureContext,
   type Context,
-  type CapturedContext,
   uniqueId,
   type UniqueIdHelper,
 } from '@ember/helper';
@@ -41,15 +39,11 @@ createContext(Theme);
 // `consume()` with no argument reads ambiently, like `value`
 expectTypeOf(theme.consume()).toEqualTypeOf<Theme>();
 
-// `consume(captured)` resolves from a captured render-tree position
-const captured = captureContext();
-expectTypeOf(captured).toEqualTypeOf<CapturedContext>();
-expectTypeOf(theme.consume(captured)).toEqualTypeOf<Theme>();
+// `consume(component)` resolves from a component instance's render-tree
+// position (validity of the instance is checked at runtime)
+declare const componentInstance: object;
+expectTypeOf(theme.consume(componentInstance)).toEqualTypeOf<Theme>();
 
-// captureContext takes no arguments
+// consume takes an object, not a primitive
 // @ts-expect-error
-captureContext(theme);
-
-// The capture is opaque -- arbitrary objects don't typecheck as one
-// @ts-expect-error
-theme.consume({});
+theme.consume('not-a-component');