Add makeContext: render-tree-scoped provide/consume (RFC #1154)

[NullVoxPopuli-ai-agent]

Summary

Implements makeContext as the user-facing context API discussed in RFC emberjs#1154, on top of a small internal render-tree scope tracker.

import { makeContext } from '@ember/helper';

class Theme {
  color = 'dark';
}

const theme = makeContext<Theme>();

<template>
  <theme.Provide @value={{this.theme}}>
    {{#let (theme.consume) as |t|}}
      {{t.color}}
    {{/let}}
  </theme.Provide>

  {{ (theme.consume) }}  {{! throws — no provider in the hierarchy }}
</template>

API

• makeContext<T>() takes no value — the type parameter declares the shape, and it returns { Provide, consume }.
• <context.Provide @value={{...}}> provides a value to everything in its block. Nested <Provide>s shadow; siblings don't bleed.
• (context.consume) (a function helper) or context.consume() (in JS, e.g. a component constructor) reads the nearest provided value.
• Exported from @ember/helper (it returns a consume usable as a template helper, so it sits with the other helpers).

Behavior (matching the RFC clarifications)

• consume() throws when no <Provide> is in the hierarchy. A missing provider is a bug, not a "fall back to undefined" state.
• consume() throws when called outside of rendering.
• The @value binding is reactive: when the argument updates, consumers re-render. If @value is a stable object, mutating its @tracked fields likewise re-renders consumers.
• Omitting @value (or passing undefined/null) provides that value — the provider is in the tree, so consume() returns it rather than throwing.

How it works

Two layers:

1. Render-tree scope tracker (@glimmer/runtime/lib/render-scope.ts, internal). Always-on, mirrors DebugRenderTree's stack lifecycle. Each component pushes a node at VM_CREATE_COMPONENT_OP (before the user constructor runs) and pops it at VM_DID_RENDER_LAYOUT_OP; matched updating opcodes re-push/pop on re-render so a consume() re-evaluated mid-update still finds the right parent chain. Each node holds a lazily-allocated Map<key, read>; lookup walks the node up its parents for the nearest provider. The two context operations are exposed as module-level helpers (provideRenderContext / lookupRenderContext) so a plain consume() — which has no handle to the VM — can reach the active tracker.
2. makeContext (packages/@ember/-internals/glimmer/lib/make-context.ts). Builds Provide on the same internal-component infrastructure as Input/Textarea/LinkTo (so ember-source doesn't take a dep on @glimmer/component). Each <Provide> stores a lazy read for its @value reference on the current scope node; consume walks up for the nearest. The closure-created consume function doubles as the context's identity key (unique per makeContext() call), so there's no separate token object. The shared {{yield}} template is precompiled once.

Why an always-on tracker (and is it free?)

A reactive, render-tree-scoped, ambiently-callable consume() can't be built from today's public APIs — there's no public "after my block rendered" hook, and a plain consume() has no scope handle. (This is exactly what the RFC proposes to add; ember-provide-consume-context ships its own component manager for the same reason.) Glimmer's built-in dynamic scope was evaluated as an alternative but is more invasive (it's hard-wired to outletState, the shared InternalManager can't selectively opt in, and the JS-imperative consume() would still need an ambient) — a lateral-to-worse move, so the contained tracker stays.

Performance: tracerbench compare (krausest, fidelity 20, control = main) shows no difference across all 23 markers — render, re-render, update, select, swap, remove, clear, paint — even though that workload renders/updates thousands of components and none use context. The per-component lifecycle + updating opcodes are below the measurement noise floor, so the always-on design needs no "gate on first use."

Scope / notes

• Components only for now (where <Provide> lives). The tracker is bucket-agnostic; extending to helpers / modifiers later is mechanical. Known limitation pinned by a test: consume() inside a modifier install throws "outside of rendering" (modifier install runs during commit, after the render stack has unwound) — a follow-up, not a regression.
• The render-scope primitives are private to @glimmer/runtime. makeContext is the only public surface in this PR.

Tests

packages/@ember/-internals/glimmer/tests/integration/render-tree-scope-test.ts (the substantive scenarios are ported from ember-provide-consume-context, the prior art NVP called out):

• consume() throws outside a render, and with no provider in the tree
• nearest-provider lookup with nested <Provide> shadowing; sibling isolation
• reactivity when @value changes, across {{#if}} toggles, and via @tracked fields on a provided object
• (context.consume) as a template helper, from a plain function helper, and (known-limitation) from a modifier
• explicit @value={{undefined}} / @value={{null}} and omitted @value
• multiple consume() calls return the same identity; cross-renderComponent isolation

Plus:

• End-to-end smoke test in smoke-tests/scenarios/basic-test.ts (make-context-test.gjs) exercising the published @ember/helper export in a real built app.
• Type smoke test in type-tests/@ember/helper-tests.ts pinning the generic-only signature (makeContext<T>() → Context<T>, consume() → T, and makeContext(SomeClass) is a type error).

Validation

• pnpm run type-check:internals / type-check:types clean.
• pnpm build:js succeeds for dist/dev and dist/prod.
• pnpm run lint:docs / lint:eslint / lint:format clean.
• The 23 makeContext integration tests pass in headless Chrome.
• tracerbench compare vs main: no regression (see above).

References

• RFC Resolved issue with cursor jumping in Ember.TextArea in IE/Opera emberjs/ember.js#1154: Public API for render-tree-based scope exploration emberjs/rfcs#1154
• NVP's makeContext sketch: Public API for render-tree-based scope exploration emberjs/rfcs#1154 (comment)
• Original Context RFC Ember.Select optionValuePath doesn't work as expected emberjs/ember.js#975: Add context API emberjs/rfcs#975

🤖 Generated with Claude Code

[bolt-new-by-stackblitz]

Run & review this pull request in StackBlitz Codeflow.