From 5d603b0f8066b1ff700bc0e795a5a4a6402834db Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Tue, 23 Nov 2021 15:45:18 -0700
Subject: [PATCH 01/53] Template imports: start filling out the content

In this commit, introduce a *first draft* of some of the RFC:

- [x] Summary
- [ ] Motivation
- [-] Detailed Design
- [-] How we teach this
- [x] Alternatives
- [x] Unresolved questions
---
 text/0000-template-imports.md | 878 ++++++++++++++++++++++++++++++++++
 1 file changed, 878 insertions(+)
 create mode 100644 text/0000-template-imports.md

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
new file mode 100644
index 0000000000..2ff252f5ad
--- /dev/null
+++ b/text/0000-template-imports.md
@@ -0,0 +1,878 @@
+---
+Stage: Accepted
+Start Date: 2021-11-22
+Release Date: Unreleased
+Release Versions:
+  ember-source: vX.Y.Z
+  ember-data: vX.Y.Z
+Relevant Team(s): Ember.js, Learning
+RFC PR: 
+---
+
+<!--- 
+Directions for above: 
+
+Stage: Leave as is
+Start Date: Fill in with today's date, YYYY-MM-DD
+Release Date: Leave as is
+Release Versions: Leave as is
+Relevant Team(s): Fill this in with the [team(s)](README.md#relevant-teams) to which this RFC applies
+RFC PR: Fill this in with the URL for the Proposal RFC PR
+-->
+
+# Template Imports and Strict Mode
+
+## Summary
+
+Adopt `<template>` as the standard authoring format for components, in files with the extensions `.gjs` and `.gts` for JavaScript and TypeScript respectively, enabling strict mode.
+
+<details><summary>Full-fledged example showing how this might work in practice</summary>
+
+```js
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on, modifier } from '@glimmer/modifier';
+import { eq, gt } from '@glimmer/helper';
+
+const Greet = <template>
+  <p>Hello, {{@name}}!</p>
+</template>
+
+class SetUsername extends Component {
+  @tracked name = '';
+
+  updateName = ({ target: { value } }) => {
+    this.name = value;
+  }
+
+  saveName = (submitEvent) => {
+    submitEvent.preventDefault();
+    this.args.onSaveName(this.name);
+  };
+
+  <template>
+    <form {{on "submit" this.saveName}}>
+      <label for='name'>Set username:</label>
+      <input
+        id='name'
+        value={{this.value}}
+        {{on "input" this.updateName}}
+      />
+      <button type='submit' disabled={{eq this.value.length 0}}>
+        Generate
+      </button>
+    </form>
+  </template>
+}
+
+const replaceLocation = modifier((el, _ , { with: newUrl }) => {
+  el.contentWindow.location.replace(newUrl);
+});
+
+export default class GenerateAvatar extends Component {
+  @tracked name = "";
+
+  get previewUrl() {
+    return `http://www.example.com/avatars/${name}`;
+  }
+
+  updateName = (newName) => {
+    this.name = newName;
+  };
+
+  <template>
+    <Greet @name={{this.name}} />
+    <SetUsername
+      @name={{this.name}}
+      @onSaveName={{this.updateName}}
+    />
+    
+    {{#if (gt 0 this.name.length)}}
+      <iframe
+        title='Preview'
+        {{replaceLocation with=this.previewUrl}}
+      >
+    {{/if}}
+  </template>
+}
+```
+
+</details>
+
+The new format provides a number of new capabilities to Ember and Glimmer users:
+
+- to access local JavaScript values with no ceremony and no backing class, enabling much easier use of existing JavaScript ecosystem tools, including especially styling libraries—native CSS modules will “just work,” for example
+- to author more than one component in a single file, where colocation makes sense—and thereby providing more control over a component’s public API
+- to likewise author locally-scoped helpers, modifiers, and other JavaScript functionality
+
+It offers these new capabilities while not only maintaining but *improving* Ember’s long-standing commitment to integrated testing, in that it allows app and test code to share a single authoring paradigm—substantially simplifying our teaching story. Similarly, it preserves Ember’s long-standing commitment to treating JavaScript and HTML (and CSS!) as distinctive concerns which, however closely related, are not the *same*.
+
+## Motivation
+
+<!--
+
+> Why are we doing this? What use cases does it support? What is the expected
+outcome?
+
+-->
+
+## Detailed design
+
+Introduce a new high-level syntax, the `<template>` tag, which is syntactical sugar for `setComponentTemplate` and `precompileTemplate`, in conjunction with the existing Ember and Glimmer `Component` classes and the special template-only component class returned by the `templateOnlyComponent` default export from `@ember/component/template-only`. There are three distinct, legal forms for this compilation:
+
+- a standalone `<template>` at the top level of a module
+- a `<template>` bound to a name
+- in the body of a component class
+
+For a discussion of the `setComponentTemplate` and `templateOnlyComponent` primitives, see [RFC #0481][rfc-0481]; for discussion of the `precompileTemplate` primitive, see [RFC #0496][rfc-0496]. This discussion will *assume* rather than *define* those.
+
+[rfc-0481]: https://emberjs.github.io/rfcs/0481-component-templates-co-location.html
+[rfc-0496]: https://emberjs.github.io/rfcs/0496-handlebars-strict-mode.html
+
+The value produced by authoring a `<template>` is a *JavaScript value*, and accordingly may be exported, bound to other values, passed as an argument to a function or set as a value on a class, etc. However, the value may not be treated as *dynamic*: the rendering engine will evaluate the value exactly and only once. Therefore, it is nonsensical to use it with a `let` binding or to attempt to create new `<template>`s dynamically from the body of a function. (A function may of course return different components based on its arguments, etc.; it simply may not *construct* new component templates dynamically.)
+
+<!-- TODO: validate import locations for `on`, `eq`, `gt` (see https://github.com/emberjs/rfcs/pull/560) -->
+
+### Bound to a name
+
+<!-- TODO: validate correct compile output for `scope` given deprecation -->
+
+Given a `<template>` tag assigned to a name in JavaScript scope:
+
+```js
+const Greet = <template>
+  <p>Hello, {{@name}}!</p>
+</template>
+```
+
+Then the compiled output is:
+
+```js
+import { precompileTemplate } from '@ember/template-compilation';
+import { setComponentTemplate } from '@ember/component';
+import templateOnlyComponent from '@ember/component/template-only';
+
+const Greet = setComponentTemplate(
+  precompileTemplate(`
+  <p>Hello, {{@name}}!</p>
+  `
+  ),
+  templateOnlyComponent()
+);
+```
+
+If the `<template>` references values in scope, they will be included in an object with a `scope` argument (matching the current implementation of the underlying primitives). Thus, this definition:
+
+```js
+import { precompileTemplate } from '@ember/template-compilation';
+import { setComponentTemplate } from '@ember/component';
+import templateOnlyComponent from '@ember/component/template-only';
+
+function isBirthday(dateOfBirth) {
+  const today = new Date();
+  return (
+    today.getMonth() === dateOfBirth.getMonth() &&
+    today.getDate() === dateOfBirth.getDate()
+  );
+}
+
+const Greet = <template>
+  <p>Hello, {{@name}}!</p>
+  {{#if (isBirthday @dateOfBirth)}}
+    <p>Happy birthday! 🎈</p>
+  {{/if}}
+</template>
+```
+
+```js
+import { precompileTemplate } from '@ember/template-compilation';
+import { setComponentTemplate } from '@ember/component';
+import templateOnlyComponent from '@ember/component/template-only';
+
+function isBirthday(dateOfBirth) {
+  const today = new Date();
+  return (
+    today.getMonth() === dateOfBirth.getMonth() &&
+    today.getDate() === dateOfBirth.getDate()
+  );
+}
+
+const Greet = setComponentTemplate(
+  precompileTemplate(`
+  <p>Hello, {{@name}}!</p>
+  {{#if (isBirthday @dateOfBirth)}}
+    <p>Happy birthday! 🎈</p>
+  {{/if}}
+  `,
+    {
+      scope: () => ({ isBirthday }),
+    }
+  ),
+  templateOnlyComponent()
+);
+```
+
+**Two important notes:**
+
+1. Users *should* always and only use `const` bindings for the result of such a template, because Ember will never reevaluate if the name is re-bound later. We should introduce a lint rule forbidding assignment of a `<template>` to a `let` binding to prevent that confusion.
+
+2. Relatedly, in normal app code, authors should not introduce component definitions `<template>`s other than at the top level of the code. It is technically possible to create components from a function, like so:
+
+    ```ts
+    function conditionalComponent(predicate: boolean) {
+      if (predicate) {
+        return <template><p>Cool</p></template>
+      } else {
+        return <template><p>Lame</p></template>
+      }
+    }
+    ```
+
+    However, doing so will have unexpected costs at runtime. It’s worth remembering what the resulting output is:
+
+    ```ts
+    function conditionalComponent(predicate: boolean) {
+      if (predicate) {
+        return setComponentTemplate(
+          precompileTemplate(`<p>Cool</p>`),
+          templateOnly()
+        );
+      } else {
+        return setComponentTemplate(
+          precompileTemplate(`<p>Lame</p>`),
+          templateOnly()
+        );
+      }
+    }
+    ```
+
+    The problem here is that this requires re-running both the template precompilation step *and* the creation of the template-only empty backing instance (which has `null` for `this`, etc.). Re-doing the template precompilation
+
+    In this scenario, users can accomplish the same thing by manually hoisting the component definitions to module scope:
+
+    ```ts
+    const Cool = <template><p>Cool</p></template>;
+    const Lame = <template><p>Lame</p></template>;
+
+    function conditionalComponent(predicate: boolean) {
+      if (predicate) {
+        return Cool;
+      } else {
+        return Lame;
+      }
+    }
+    ```
+
+    (This is similar to the concern around other costly operations needlessly happening in a function body repeatedly.)
+
+### Standalone
+
+The compiled output for a top-level `<template>` tag *not* bound to a name is a default export, but otherwise identical to a `<template>` declaration bound to a tag. Thus, given this input:
+
+```js
+<template>
+  <p>Hello, {{@name}}!</p>
+</template>
+```
+
+The compiled output is:
+
+```js
+import { precompileTemplate } from '@ember/template-compilation';
+import { setComponentTemplate } from '@ember/component';
+import templateOnlyComponent from '@ember/component/template-only';
+
+export default setComponentTemplate(
+  precompileTemplate(`
+  <p>Hello, {{@name}}!</p>
+  `
+  ),
+  templateOnlyComponent()
+);
+```
+
+Scoped values are included the same as with named definitions.
+
+Since the compiled output is a default export, it is a static error to have multiple top-level (i.e. not bound to a name) `<template>`s in a file—because it is a static error to have multiple `export default` statements in a JavaScript file. (We should provide linting tooling to error on this case, rather than letting it fail at runtime.)
+
+### Class body
+
+The compilation output with a class-backed component is similar, but instead of using `templateOnlyComponent`, it uses the backing class. Given this component:
+
+```js
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { eq } from '@glimmer/helper';
+import { on } from '@glimmer/modifier';
+
+class SetUsername extends Component {
+  @tracked name = '';
+
+  updateName = ({ target: { value } }) => {
+    this.name = value;
+  }
+
+  saveName = (submitEvent) => {
+    submitEvent.preventDefault();
+    this.args.onSaveName(this.name);
+  };
+
+  <template>
+    <form {{on "submit" this.saveName}}>
+      <label for='name'>Set username:</label>
+      <input
+        id='name'
+        value={{this.value}}
+        {{on "input" this.updateName}}
+      />
+      <button type='submit' disabled={{eq this.value.length 0}}>
+        Generate
+      </button>
+    </form>
+  </template>
+}
+```
+
+The compiled output is:
+
+```js
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { eq } from '@glimmer/helper';
+import { on } from '@glimmer/modifier';
+import { precompileTemplate } from '@ember/template-compilation';
+import { setComponentTemplate } from '@ember/component';
+
+class SetUsername extends Component {
+  @tracked name = '';
+
+  updateName = ({ target: { value } }) => {
+    this.name = value;
+  }
+
+  saveName = (submitEvent) => {
+    submitEvent.preventDefault();
+    this.args.onSaveName(this.name);
+  };
+
+  <template>
+    <form {{on "submit" this.saveName}}>
+      <label for='name'>Set username:</label>
+      <input
+        id='name'
+        value={{this.value}}
+        {{on "input" this.updateName}}
+      />
+      <button type='submit' disabled={{eq this.value.length 0}}>
+        Generate
+      </button>
+    </form>
+  </template>
+}
+
+setComponentTemplate(
+  precompileTemplate`
+    <form {{on "submit" this.saveName}}>
+      <label for='name'>Set username:</label>
+      <input
+        id='name'
+        value={{this.value}}
+        {{on "input" this.updateName}}
+      />
+      <button type='submit' disabled={{eq this.value.length 0}}>
+        Generate
+      </button>
+    </form>
+  `,
+    {
+      scope: () => ({ on, eq }),
+    }
+  ),
+  SetUsername
+)
+```
+
+### Interop
+
+Since all existing components already work using the same low-level primitives the new system uses, strict-mode components using `<template>` can import and invoke components authored in Ember’s loose mode format. Similarly, since loose mode components are resolved to a component which is the default export of a module in the correct/conventional location on disk, components authored in strict mode with `<template>` and exported as the default export in that conventional location will be resolveable by loose mode components as well.
+
+However, other components exported as *named* exports will not be available in loose mode. This is a temporary incoherence which will be resolved as the ecosystem migrates to strict mode. As a workaround, users may choose to create reexport-only modules to allow loose-mode access. For example, given a module `app/components/named-only.js` with two named export components:
+
+```js
+export const Greet = <template>
+  <p>Hello, {{@name}}!</p>
+</template>
+
+export const Farewell = <template>
+  <p>Hello, {{@name}}!</p>
+</template>
+```
+
+A user wishing to make these available to loose mode could introduce two new modules:
+
+- `app/components/named-only/greet.js`:
+
+    ```js
+    export { Greet as default } from '../named-only';
+    ```
+
+- `app/components/named-only/farewell.js`:
+
+    ```js
+    export { Farewell as default } from '../named-only';
+    ```
+
+Then a loose-mode component could invoke them like `<NamedOnly::Greet @name="Chris">` and `<NamedOnly::Farewell @name="Krycho" />`. Note that this pattern is not at all *necessary* for migration, but may be useful.
+
+<!--
+
+> This is the bulk of the RFC.
+
+> Explain the design in enough detail for somebody
+familiar with the framework to understand, and for somebody familiar with the
+implementation to implement. This should get into specifics and corner-cases,
+and include examples of how the feature is used. Any new terminology should be
+defined here.
+
+-->
+
+## How we teach this
+
+We describe a `<template>` as representing the *template* for a *component*. When there is no backing class, that’s all there is to the component. When there *is* a backing class, the component also has associated state and behavior. (Notably, this shift already began with Octane, where we generate template-only components by default.)
+
+This explanatory model provides a helpful opportunity, when first introducing the idea of a backing class, to link to deeper-dive materials which let people who want to understand more deeply. In particular, it allows us a place to point out that mechanically, there *is* in fact always an associated component instance (generated via `templateOnlyComponent()`), but it’s just a way for this `<template>` to be hooked into the broader system, rather than a home for state.
+
+### Guides
+
+Once this is implemented and tooling is sufficiently stable, we will update the guides with the following changes:
+
+- Update the output from generators, including correct new file extensions.
+
+- Update the introductory examples, which start with pure HTML, to add a wrapping `<template>` tag, and update the prose to describe that `<template>` marks this as Ember/Glimmer’s special superset of HTML. Note that all you need to do to have a working Ember component is to wrap your HTML in `<template>`.
+
+<!-- TODO: the rest of the pedagogy updates -->
+
+### API Docs
+
+There is presently no API for `<template>` itself, as proposed in this RFC, though it leaves room for future RFCs, which could introduce e.g. a `<template lang="...">` variation to experiment with alternative template languages.[^emblem] Since there is no import location, we should cover it under the `@glimmer/component` module documentation. This will be a natural home for it, since we will always discuss it in the context of components.
+
+[^emblem]: Historically, for example, many Ember apps used [Emblem][emblem]—and it is still possible to do so today! In the future, that could be supported with `<template lang="emblem">`. This would also be an easy home for experiments with a Svelte-like syntax.
+
+[emblem]: http://emblemjs.com
+
+### TypeScript
+
+The type of a component is not affected by this proposal. However, it is worth seeing *how* a component defined using `<template>` works with types.
+
+- For a class-backed component, there is no change when using `<template>`. As described above, tools like Glint will need to <!-- TODO -->
+
+- For a template-only component, defining the type will require a type import to represent that there is a component with no `this` context, etc. Glint already supplies such a type, albeit with the types updated for [RFC #0748][rfc-0748]. For today’s purposes, we can define such a type as follows (with the `TemplateComponent`/`TC` shorthand here following the lead of React’s `FunctionComponent`/`FC` types):
+
+    ```ts
+    export interface TemplateOnly<Args extends {} = {}> {}
+    export type TC<Args extends {} = {}> = TemplateOnly<Args>;
+    ```
+
+    Users can then define a tmeplate-only component like this:
+
+    ```ts
+    import { TC } from '@glimmer/component';
+
+    const Greet: TC<{ name: string }> = <template>
+      <p>Hello, {{@name}}!</p>
+    </template>
+    ```
+
+    While this empty interface is currently more or less useless from a type-checking perspective (we will need something like Glint to support it), it suffices to provide a hook for documentation tooling such as TypeDoc or API Extractor—but this suffices for the level of support we have for TypeScript today.
+
+[rfc-0748]: https://github.com/emberjs/rfcs/pull/748
+
+### Existing Ember users
+
+<!-- existing ember users introduction -->
+
+<!--
+
+> What names and terminology work best for these concepts and why? How is this
+idea best presented? As a continuation of existing Ember patterns, or as a
+wholly new one?
+
+> Would the acceptance of this proposal mean the Ember guides must be
+re-organized or altered? Does it change how Ember is taught to new users
+at any level?
+
+> How should this feature be introduced and taught to existing Ember
+users?
+
+-->
+
+## Drawbacks
+
+- API documentation is somewhat difficult, since there is no notional import for `<template>`.
+
+- We must build a custom tooling integration with Prettier for the file format to *parse*. (As discussed below, we must build custom tooling to *use* Prettier for other options, but Prettier can *parse* them without custom tooling.)
+
+- While not especially important in the context of a front-end framework (as opposed to a framework-less/“vanilla” context), `<template>` does technically overlap with a platform built-in, and would look very strange if a user *did*  want to use the built-in form.
+
+<!--
+
+> Why should we *not* do this? Please consider the impact on teaching Ember,
+on the integration of this feature with other existing and planned features,
+on the impact of the API churn on existing apps, etc.
+
+> There are tradeoffs to choosing any path, please attempt to identify them here.
+
+-->
+
+## Alternatives
+
+<!--
+
+> What other designs have been considered? What is the impact of not doing this?
+
+> This section could also include prior art, that is, how other frameworks in the same domain have solved this problem.
+
+-->
+
+Within the major strokes of this design proposal, we could tweak the invocation for the template space to clarify that it does *not* overlap
+
+- Use `<Template>` or `<Glimmer>` or similar. This would disambiguate it from the built-in `<template>`, but would introduce ambiguity with component invocation.
+- Use a new sigil—much as we use `<:main>...</:main>` for named blocks, we could do `<[template]>...</[template]>` or something similar. While verbose and not especially pretty, this avoids overloading the platform tag.
+
+Additionally, there are three major alternatives which Ember community members have proposed in the design space:
+
+- **imports-only:** a design which uses “front-matter” to add imports, and only imports, to templates, while maintaining
+- **single-file components (SFCs)**: a design which follows the example of Svelte and Vue and make HTML the basis of a component, and
+- **`hbs` template literals**: a design which mirrors the `<template>` design quite closely, but uses `hbs` template literals similar to those we use in tests today
+
+I discuss each of these briefly below; for a *much* longer and more thorough discussion, please see the \~16,000-word series of blog posts I wrote as a deep dive: [**Ember Template Imports**](https://v5.chriskrycho.com/journal/ember-template-imports/).
+
+### Imports-only
+
+The imports-only design borrows the idea of “front-matter” from many text authoring formats, using something like `---`-delimiters to introduce a new, non-Handlebars area at the top of a template which allows exactly and only *imports* to appear. As with all strict-mode designs, all non-built-in values must be imported here. Thus, the *template* for the final component shown in the motivating example might appear like this:
+
+<details><summary>motivating example shown with imports-only</summary>
+
+- `greet.hbs`:
+
+    ```hbs
+    <p>Hello, {{@name}}!</p>
+    ```
+
+- `set-username.js`:
+
+    ```js
+    import Component from '@glimmer/component';
+    import { tracked } from '@glimmer/tracking';
+
+    export default class SetUsername extends Component {
+      @tracked name = '';
+
+      updateName = ({ target: { value } }) => {
+        this.name = value;
+      }
+
+      saveName = (submitEvent) => {
+        submitEvent.preventDefault();
+        this.args.onSaveName(this.name);
+      };
+    }
+    ```
+
+- `set-username.hbs`:
+
+    ```hbs
+    ---
+    import { on } from '@glimmer/modifier';
+    import { eq } from '@glimmer/helper';
+    ---
+
+    <form {{on "submit" this.saveName}}>
+      <label for='name'>Set username:</label>
+      <input
+        id='name'
+        value={{this.value}}
+        {{on "input" this.updateName}}
+      />
+      <button type='submit' disabled={{eq this.value.length 0}}>
+        Generate
+      </button>
+    </form>
+    ```
+
+- `replace-location.js`:
+
+    ```js
+    import { modifier } from '@glimmer/modifier';
+
+    export default modifier((el, _ , { with: newUrl }) => {
+        el.contentWindow.location.replace(newUrl);
+    });
+    ```
+
+- `generate-avatar.js`:
+
+    ```js
+    import Component from '@glimmer/component';
+    import { tracked } from '@glimmer/tracking';
+    import Greet from './greet.glimmer';
+    import SetUsername from './set-username.glimmer';
+
+
+
+    export default class GenerateAvatar extends Component {
+      @tracked name = "";
+
+      get previewUrl() {
+        return `http://www.example.com/avatars/${name}`;
+      }
+
+      updateName = (newName) => {
+        this.name = newName;
+      };
+    }
+    ```
+
+- `generate-avatar.hbs`:
+
+    ```hbs
+    ---
+    import Greet from './greet';
+    import SetUsername from './set-username';
+    import { gt } from '@glimmer/helper';
+    ---
+
+    <Greet @name={{this.name}} />
+    <SetUsername
+      @name={{this.name}}
+      @onSaveName={{this.updateName}}
+    />
+
+    {{#if (gt 0 this.name.length)}}
+      <iframe
+        title='Preview'
+        {{replaceLocation with=this.previewUrl}}
+      >
+    {{/if}}
+    ```
+
+</details>
+
+The major upside to this is that it is the smallest possible delta over today’s implementation. However, it has a number of significant downsides:
+
+- It does not allow locally-scoped functions (including helpers and modifiers) even when that is a perfectly appropriate design decision.
+- It substantially complicates the implementation of tooling for language servers.
+- It requires that we continue to support a completely separate design for testing than for app code (indeed: it basically requires that we fully implement the `hbs` or `<template>` designs for those!)
+
+<!-- TODO: more? -->
+
+### SFCs
+
+Single File Components (hereafter SFCs) start with an HTML baseline and layer on functionality in a `<script>` tag, modeled on HTML’s own design, but with extra semantics supporting imports and making an `export default class extends Component` statement provide the `this` for the template context. It can, however, define modifiers and helpers local to the component. You can think of this as a fairly natural (and HTML-like) extension to the imports-only design.
+
+<details><summary>motivating example shown with SFCs</summary>
+
+- `greet.glimmer`:
+
+    ```hbs
+    <p>Hello, {{@name}}!</p>
+    ```
+
+- `set-username.glimmer`:
+
+    ```hbs
+    <script>
+      import Component from '@glimmer/component';
+      import { tracked } from '@glimmer/tracking';
+      import { on } from '@glimmer/modifier';
+      import { eq } from '@glimmer/helper';
+
+      export default class SetUsername extends Component {
+        @tracked name = '';
+
+        updateName = ({ target: { value } }) => {
+          this.name = value;
+        }
+
+        saveName = (submitEvent) => {
+          submitEvent.preventDefault();
+          this.args.onSaveName(this.name);
+        };
+      }
+    </script>
+
+    <form {{on "submit" this.saveName}}>
+      <label for='name'>Set username:</label>
+      <input
+        id='name'
+        value={{this.value}}
+        {{on "input" this.updateName}}
+      />
+      <button type='submit' disabled={{eq this.value.length 0}}>
+        Generate
+      </button>
+    </form>
+    ```
+
+- `generate-avatar.glimmer`:
+
+    ```hbs
+    <script>
+      import Component from '@glimmer/component';
+      import { tracked } from '@glimmer/tracking';
+      import { gt } from '@glimmer/helper';
+      import { modifier } from '@glimmer/modifier';
+      import Greet from './greet.glimmer';
+      import SetUsername from './set-username.glimmer';
+
+      const replaceLocation = modifier(
+        (el, _ , { with: newUrl }) => {
+          el.contentWindow.location.replace(newUrl);
+        }
+      );
+
+      export default class GenerateAvatar extends Component {
+        @tracked name = "";
+
+        get previewUrl() {
+          return `http://www.example.com/avatars/${name}`;
+        }
+
+        updateName = (newName) => {
+          this.name = newName;
+        };
+      }
+    </script>
+
+    <Greet @name={{this.name}} />
+    <SetUsername
+      @name={{this.name}}
+      @onSaveName={{this.updateName}}
+    />
+
+    {{#if (gt 0 this.name.length)}}
+      <iframe
+        title='Preview'
+        {{replaceLocation with=this.previewUrl}}
+      >
+    {{/if}}
+    ```
+
+</details>
+
+This is very attractive in some ways, but it comes with three downsides:
+
+- SFCs do not allow multiple components to be defined in a single file. This has been an ongoing sticking point with the Vue and Svelte designs, such that there is even an open-for-years RFC for Svelte for supporting it. <!-- TODO: find and link RFC -->
+- SFCs do not allow using the same format for testing as for authoring code. As with the imports-only design, they require us to support `hbs` or `<template>` (or some similar design) for testing *in parallel* with this one, or to come up with some other test-specific authoring format.
+- Additionally, the scope handling for the default export is unusual and requires additional teaching.
+
+### Template literals
+
+The “template literals” design takes as its starting point the `hbs` template strings Ember has used for testing since the 1.x era. It is relatively similar to the `<template>` design, in that it uses JavaScript/TypeScript files as the basis for its design. Unlike `template`, it uses an explicit `hbs` import, presumably from `@glimmer/component`. For components with a backing class, the template is defined as a static class field.
+
+<details><summary>Motivating example shown with <code>hbs</code></summary>
+
+```js
+import Component, { hbs } from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on, modifier } from '@glimmer/modifier';
+import { eq, gt } from '@glimmer/helper';
+
+const Greet = hbs`
+  <p>Hello, {{@name}}!</p>
+`;
+
+class SetUsername extends Component {
+  @tracked name = '';
+
+  updateName = ({ target: { value } }) => {
+    this.name = value;
+  }
+
+  saveName = (submitEvent) => {
+    submitEvent.preventDefault();
+    this.args.onSaveName(this.name);
+  };
+
+  static template = hbs`
+    <form {{on "submit" this.saveName}}>
+      <label for='name'>Set username:</label>
+      <input
+        id='name'
+        value={{this.value}}
+        {{on "input" this.updateName}}
+      />
+      <button type='submit' disabled={{eq this.value.length 0}}>
+        Generate
+      </button>
+    </form>
+  `;
+}
+
+const replaceLocation = modifier((el, _ , { with: newUrl }) => {
+  el.contentWindow.location.replace(newUrl);
+});
+
+export default class GenerateAvatar extends Component {
+  @tracked name = "";
+
+  get previewUrl() {
+    return `http://www.example.com/avatars/${name}`;
+  }
+
+  updateName = (newName) => {
+    this.name = newName;
+  };
+
+  static template = hbs`
+    <Greet @name={{this.name}} />
+    <SetUsername
+      @name={{this.name}}
+      @onSaveName={{this.updateName}}
+    />
+
+    {{#if (gt 0 this.name.length)}}
+      <iframe
+        title='Preview'
+        {{replaceLocation with=this.previewUrl}}
+      >
+    {{/if}}
+  `;
+}
+```
+
+</details>
+
+This has a couple significant advantages:
+
+- Unlike with the `<template>` proposal, Prettier can *parse* a file using `hbs` string with no further changes. (It cannot *format* them, however: it treats the contents of the string opaquely.)
+- It feels familiar to developers in the Ember ecosystem used to
+- The broader JavaScript ecosystem makes use of a number of template string syntaxes, e.g. with `css` from [Emotion][emotion] or `graphql` from [TODO][graphql].
+
+[emotion]: TODO
+[graphql]: graphql
+
+However, it also has some significant disadvantages:
+
+- The design repurposes JavaScript syntax and gives it totally different semantics—like `<template>` does with HTML, but with *zero* signal from the context that it is doing something special.
+    - `hbs` is *not* actually a template string literal; it is a compile-time macro. Attempting to use it like a template string literal (e.g. by using `${...}` string interpolation) is a build-time error. This substantially undercuts the familiarity of the design: `css` and `graphql` and similar are *actual* string templates, not compile-time macros, and accordingly developers can use normal JavaScript semantics with them.
+    - The use of `static template = ...` has the wrong semantics: static class fields do not have access to an instance’s `this`—but templates quite expressly *do*. The whole point of a component with a backing class is to provide a normal JavaScript `this`, so this is a significant mismatch, which has consequences for both teaching and tooling.
+
+- The learning path is *much* less gradual: the simplest possible component requires showing and at least minimally explaining JavaScript import and export semantics and template literals *and* that it isn’t a normal template literal as described above.
+
+## Unresolved questions
+
+- Does the possible confusion with the platform `<template>` warrant adopting an alternative syntax, whether component-like (`<Template>`) or using an additional sigil (`<[template]>`, `<% ... %>`, `<$ ... $>` etc.)? If so, what design? Here we must keep in mind that the design should not be ambiguous with “dynamic” behavior (e.g. `<{template}>` which is suggestive of the Svelte and React expression marker, and which we might find attractive for future iterations of template language ourselves).
+
+- Are `.gjs` and `.gts` the best file extensions?
+
+- How does this relate to the currently un-merged [RFC #0731: Add `setRouteComponent` API][rfc-0731]?
+
+[rfc-0731]: https://github.com/emberjs/rfcs/pull/731
+
+<!--
+
+> Optional, but suggested for first drafts. What parts of the design are still
+TBD?
+
+ -->
\ No newline at end of file

From 64b73c4715d28070cc5818e568670e14981d8b8d Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Tue, 23 Nov 2021 15:51:48 -0700
Subject: [PATCH 02/53] Add table-of-contents and planned new section

---
 text/0000-template-imports.md | 36 ++++++++++++++++++++++++++++++++---
 1 file changed, 33 insertions(+), 3 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 2ff252f5ad..3f7f7d6046 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -107,6 +107,30 @@ The new format provides a number of new capabilities to Ember and Glimmer users:
 
 It offers these new capabilities while not only maintaining but *improving* Ember’s long-standing commitment to integrated testing, in that it allows app and test code to share a single authoring paradigm—substantially simplifying our teaching story. Similarly, it preserves Ember’s long-standing commitment to treating JavaScript and HTML (and CSS!) as distinctive concerns which, however closely related, are not the *same*.
 
+
+### Contents <!-- omit in toc -->
+
+- [Summary](#summary)
+- [Motivation](#motivation)
+- [Detailed design](#detailed-design)
+  - [Compilation](#compilation)
+    - [Bound to a name](#bound-to-a-name)
+    - [Standalone](#standalone)
+    - [Class body](#class-body)
+  - [Interop](#interop)
+  - [The “prelude”](#the-prelude)
+- [How we teach this](#how-we-teach-this)
+  - [Guides](#guides)
+  - [API Docs](#api-docs)
+  - [TypeScript](#typescript)
+  - [Existing Ember users](#existing-ember-users)
+- [Drawbacks](#drawbacks)
+- [Alternatives](#alternatives)
+  - [Imports-only](#imports-only)
+  - [SFCs](#sfcs)
+  - [Template literals](#template-literals)
+- [Unresolved questions](#unresolved-questions)
+
 ## Motivation
 
 <!--
@@ -129,11 +153,13 @@ For a discussion of the `setComponentTemplate` and `templateOnlyComponent` primi
 [rfc-0481]: https://emberjs.github.io/rfcs/0481-component-templates-co-location.html
 [rfc-0496]: https://emberjs.github.io/rfcs/0496-handlebars-strict-mode.html
 
+### Compilation
+
 The value produced by authoring a `<template>` is a *JavaScript value*, and accordingly may be exported, bound to other values, passed as an argument to a function or set as a value on a class, etc. However, the value may not be treated as *dynamic*: the rendering engine will evaluate the value exactly and only once. Therefore, it is nonsensical to use it with a `let` binding or to attempt to create new `<template>`s dynamically from the body of a function. (A function may of course return different components based on its arguments, etc.; it simply may not *construct* new component templates dynamically.)
 
 <!-- TODO: validate import locations for `on`, `eq`, `gt` (see https://github.com/emberjs/rfcs/pull/560) -->
 
-### Bound to a name
+#### Bound to a name
 
 <!-- TODO: validate correct compile output for `scope` given deprecation -->
 
@@ -265,7 +291,7 @@ const Greet = setComponentTemplate(
 
     (This is similar to the concern around other costly operations needlessly happening in a function body repeatedly.)
 
-### Standalone
+#### Standalone
 
 The compiled output for a top-level `<template>` tag *not* bound to a name is a default export, but otherwise identical to a `<template>` declaration bound to a tag. Thus, given this input:
 
@@ -295,7 +321,7 @@ Scoped values are included the same as with named definitions.
 
 Since the compiled output is a default export, it is a static error to have multiple top-level (i.e. not bound to a name) `<template>`s in a file—because it is a static error to have multiple `export default` statements in a JavaScript file. (We should provide linting tooling to error on this case, rather than letting it fail at runtime.)
 
-### Class body
+#### Class body
 
 The compilation output with a class-backed component is similar, but instead of using `templateOnlyComponent`, it uses the backing class. Given this component:
 
@@ -436,6 +462,10 @@ defined here.
 
 -->
 
+### The “prelude”
+
+<!-- TODO -->
+
 ## How we teach this
 
 We describe a `<template>` as representing the *template* for a *component*. When there is no backing class, that’s all there is to the component. When there *is* a backing class, the component also has associated state and behavior. (Notably, this shift already began with Octane, where we generate template-only components by default.)

From f46cc46a4e02d6eec56a910d7d09c1aa727fbadb Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Tue, 23 Nov 2021 15:52:12 -0700
Subject: [PATCH 03/53] Add planned new Tooling section

---
 text/0000-template-imports.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 3f7f7d6046..9e1fa8ea0d 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -119,6 +119,7 @@ It offers these new capabilities while not only maintaining but *improving* Embe
     - [Class body](#class-body)
   - [Interop](#interop)
   - [The “prelude”](#the-prelude)
+  - [Tooling](#tooling)
 - [How we teach this](#how-we-teach-this)
   - [Guides](#guides)
   - [API Docs](#api-docs)
@@ -466,6 +467,10 @@ defined here.
 
 <!-- TODO -->
 
+### Tooling
+
+<!-- TODO -->
+
 ## How we teach this
 
 We describe a `<template>` as representing the *template* for a *component*. When there is no backing class, that’s all there is to the component. When there *is* a backing class, the component also has associated state and behavior. (Notably, this shift already began with Octane, where we generate template-only components by default.)

From 223c688fd04a3943c0a6f1443c603cb7a5cfb53c Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Tue, 23 Nov 2021 15:54:57 -0700
Subject: [PATCH 04/53] Update examples assuming the prelude

---
 text/0000-template-imports.md | 38 +++--------------------------------
 1 file changed, 3 insertions(+), 35 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 9e1fa8ea0d..1b39ac700c 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -31,8 +31,7 @@ Adopt `<template>` as the standard authoring format for components, in files wit
 ```js
 import Component from '@glimmer/component';
 import { tracked } from '@glimmer/tracking';
-import { on, modifier } from '@glimmer/modifier';
-import { eq, gt } from '@glimmer/helper';
+import { modifier } from '@glimmer/modifier';
 
 const Greet = <template>
   <p>Hello, {{@name}}!</p>
@@ -329,8 +328,6 @@ The compilation output with a class-backed component is similar, but instead of
 ```js
 import Component from '@glimmer/component';
 import { tracked } from '@glimmer/tracking';
-import { eq } from '@glimmer/helper';
-import { on } from '@glimmer/modifier';
 
 class SetUsername extends Component {
   @tracked name = '';
@@ -365,8 +362,6 @@ The compiled output is:
 ```js
 import Component from '@glimmer/component';
 import { tracked } from '@glimmer/tracking';
-import { eq } from '@glimmer/helper';
-import { on } from '@glimmer/modifier';
 import { precompileTemplate } from '@ember/template-compilation';
 import { setComponentTemplate } from '@ember/component';
 
@@ -381,20 +376,6 @@ class SetUsername extends Component {
     submitEvent.preventDefault();
     this.args.onSaveName(this.name);
   };
-
-  <template>
-    <form {{on "submit" this.saveName}}>
-      <label for='name'>Set username:</label>
-      <input
-        id='name'
-        value={{this.value}}
-        {{on "input" this.updateName}}
-      />
-      <button type='submit' disabled={{eq this.value.length 0}}>
-        Generate
-      </button>
-    </form>
-  </template>
 }
 
 setComponentTemplate(
@@ -410,10 +391,7 @@ setComponentTemplate(
         Generate
       </button>
     </form>
-  `,
-    {
-      scope: () => ({ on, eq }),
-    }
+  `
   ),
   SetUsername
 )
@@ -617,11 +595,6 @@ The imports-only design borrows the idea of “front-matter” from many text au
 - `set-username.hbs`:
 
     ```hbs
-    ---
-    import { on } from '@glimmer/modifier';
-    import { eq } from '@glimmer/helper';
-    ---
-
     <form {{on "submit" this.saveName}}>
       <label for='name'>Set username:</label>
       <input
@@ -674,7 +647,6 @@ The imports-only design borrows the idea of “front-matter” from many text au
     ---
     import Greet from './greet';
     import SetUsername from './set-username';
-    import { gt } from '@glimmer/helper';
     ---
 
     <Greet @name={{this.name}} />
@@ -719,8 +691,6 @@ Single File Components (hereafter SFCs) start with an HTML baseline and layer on
     <script>
       import Component from '@glimmer/component';
       import { tracked } from '@glimmer/tracking';
-      import { on } from '@glimmer/modifier';
-      import { eq } from '@glimmer/helper';
 
       export default class SetUsername extends Component {
         @tracked name = '';
@@ -755,7 +725,6 @@ Single File Components (hereafter SFCs) start with an HTML baseline and layer on
     <script>
       import Component from '@glimmer/component';
       import { tracked } from '@glimmer/tracking';
-      import { gt } from '@glimmer/helper';
       import { modifier } from '@glimmer/modifier';
       import Greet from './greet.glimmer';
       import SetUsername from './set-username.glimmer';
@@ -810,8 +779,7 @@ The “template literals” design takes as its starting point the `hbs` templat
 ```js
 import Component, { hbs } from '@glimmer/component';
 import { tracked } from '@glimmer/tracking';
-import { on, modifier } from '@glimmer/modifier';
-import { eq, gt } from '@glimmer/helper';
+import { modifier } from '@glimmer/modifier';
 
 const Greet = hbs`
   <p>Hello, {{@name}}!</p>

From a88c6c3ea05180e57d0a82f95e7a4c1b3f6cc8fe Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Tue, 23 Nov 2021 15:59:52 -0700
Subject: [PATCH 05/53] Add more sections and prose and TODOs

---
 text/0000-template-imports.md | 18 ++++++++++++++++--
 1 file changed, 16 insertions(+), 2 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 1b39ac700c..3a7d0ad4cd 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -111,6 +111,7 @@ It offers these new capabilities while not only maintaining but *improving* Embe
 
 - [Summary](#summary)
 - [Motivation](#motivation)
+  - [Constraints](#constraints)
 - [Detailed design](#detailed-design)
   - [Compilation](#compilation)
     - [Bound to a name](#bound-to-a-name)
@@ -140,6 +141,17 @@ outcome?
 
 -->
 
+### Constraints
+
+<!--
+TODO:
+
+- [ ] not regressing (and, optimally, improving!) testing
+- [ ] pedagogy
+- [ ] interop with existing story
+
+-->
+
 ## Detailed design
 
 Introduce a new high-level syntax, the `<template>` tag, which is syntactical sugar for `setComponentTemplate` and `precompileTemplate`, in conjunction with the existing Ember and Glimmer `Component` classes and the special template-only component class returned by the `templateOnlyComponent` default export from `@ember/component/template-only`. There are three distinct, legal forms for this compilation:
@@ -240,7 +252,7 @@ const Greet = setComponentTemplate(
 
 **Two important notes:**
 
-1. Users *should* always and only use `const` bindings for the result of such a template, because Ember will never reevaluate if the name is re-bound later. We should introduce a lint rule forbidding assignment of a `<template>` to a `let` binding to prevent that confusion.
+1. Users *should* always and only use `const` bindings for the result of such a template, because Ember will never reevaluate if the name is re-bound later. (Even if we wanted to do that, it would be difficult at best: nothing would notify Ember that it *should* re-evaluate that value!) We should introduce a lint rule forbidding assignment of a `<template>` to a `let` binding to prevent that confusion.
 
 2. Relatedly, in normal app code, authors should not introduce component definitions `<template>`s other than at the top level of the code. It is technically possible to create components from a function, like so:
 
@@ -272,7 +284,7 @@ const Greet = setComponentTemplate(
     }
     ```
 
-    The problem here is that this requires re-running both the template precompilation step *and* the creation of the template-only empty backing instance (which has `null` for `this`, etc.). Re-doing the template precompilation
+    The problem here is that this requires re-running both the template precompilation step *and* the creation of the template-only empty backing instance (which has `null` for `this`, etc.). Re-doing the template precompilation <!-- TODO: doesn't even work, right? -->
 
     In this scenario, users can accomplish the same thing by manually hoisting the component definitions to module scope:
 
@@ -291,6 +303,8 @@ const Greet = setComponentTemplate(
 
     (This is similar to the concern around other costly operations needlessly happening in a function body repeatedly.)
 
+    The sole exception here is that it makes perfectly good sense to define components, whether class-backed or not, in the context of *test modules*, where the context only exists for as long as the test itself and so the concerns are no longer an issue.
+
 #### Standalone
 
 The compiled output for a top-level `<template>` tag *not* bound to a name is a default export, but otherwise identical to a `<template>` declaration bound to a tag. Thus, given this input:

From 38982bbf6566d0a61f1e7db4bf5323cc62f2f5a1 Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Tue, 23 Nov 2021 16:01:13 -0700
Subject: [PATCH 06/53] Elaborate an unresolved question

---
 text/0000-template-imports.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 3a7d0ad4cd..8f03913c21 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -883,7 +883,7 @@ However, it also has some significant disadvantages:
 
 - Are `.gjs` and `.gts` the best file extensions?
 
-- How does this relate to the currently un-merged [RFC #0731: Add `setRouteComponent` API][rfc-0731]?
+- How does this relate to the currently un-merged [RFC #0731: Add `setRouteComponent` API][rfc-0731]? That is: can we merge this and proceed with authoring components while there is an unresolved design problem for the related issue of routes, controllers, and their host components? Or should we see this as a helpful part of resolving *that* design question? (I believe we can move forward in parallel.)
 
 [rfc-0731]: https://github.com/emberjs/rfcs/pull/731
 

From d0732c9f1521b789503729fdbfd1e5e45c90ff86 Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Tue, 23 Nov 2021 16:04:52 -0700
Subject: [PATCH 07/53] Improve discussion of alternatives

---
 text/0000-template-imports.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 8f03913c21..33b4aa16d2 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -681,9 +681,9 @@ The imports-only design borrows the idea of “front-matter” from many text au
 
 The major upside to this is that it is the smallest possible delta over today’s implementation. However, it has a number of significant downsides:
 
-- It does not allow locally-scoped functions (including helpers and modifiers) even when that is a perfectly appropriate design decision.
-- It substantially complicates the implementation of tooling for language servers.
-- It requires that we continue to support a completely separate design for testing than for app code (indeed: it basically requires that we fully implement the `hbs` or `<template>` designs for those!)
+- It does not allow locally-scoped JavaScript values (including helpers and modifiers and also ecosystem tooling like GraphQL values, CSS-in-JS tooling, etc.) even when that is a perfectly reasonable design decision.
+- It substantially complicates the implementation of tooling for language servers, which have to do extra work to detect the presence of a backing class and “stitch together” the backing class and the template if a backing class does exist.
+- Perhaps most critically: **it requires that we continue to support a completely separate design for testing than for app code** (indeed: it basically requires that we fully implement the `hbs` or `<template>` designs for those!)
 
 <!-- TODO: more? -->
 
@@ -781,8 +781,8 @@ Single File Components (hereafter SFCs) start with an HTML baseline and layer on
 This is very attractive in some ways, but it comes with three downsides:
 
 - SFCs do not allow multiple components to be defined in a single file. This has been an ongoing sticking point with the Vue and Svelte designs, such that there is even an open-for-years RFC for Svelte for supporting it. <!-- TODO: find and link RFC -->
-- SFCs do not allow using the same format for testing as for authoring code. As with the imports-only design, they require us to support `hbs` or `<template>` (or some similar design) for testing *in parallel* with this one, or to come up with some other test-specific authoring format.
-- Additionally, the scope handling for the default export is unusual and requires additional teaching.
+- The scope handling for the default export is unusual and requires additional teaching.
+- Perhaps most critically: as with the imports-only design, **the SFC design requires that we continue to support a completely separate design for testing than for app code** (indeed: it basically requires that we fully implement the `hbs` or `<template>` designs for those!)
 
 ### Template literals
 
@@ -863,7 +863,7 @@ export default class GenerateAvatar extends Component {
 This has a couple significant advantages:
 
 - Unlike with the `<template>` proposal, Prettier can *parse* a file using `hbs` string with no further changes. (It cannot *format* them, however: it treats the contents of the string opaquely.)
-- It feels familiar to developers in the Ember ecosystem used to
+- It feels familiar to developers in the Ember ecosystem used to using `hbs` strings with their tests.
 - The broader JavaScript ecosystem makes use of a number of template string syntaxes, e.g. with `css` from [Emotion][emotion] or `graphql` from [TODO][graphql].
 
 [emotion]: TODO

From 19aa02df182dbf64ccacd9a8a799a1ba45df2fc4 Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Tue, 23 Nov 2021 17:13:17 -0700
Subject: [PATCH 08/53] Another note about `hbs` alternative

---
 text/0000-template-imports.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 33b4aa16d2..22c15ee8ca 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -877,6 +877,10 @@ However, it also has some significant disadvantages:
 
 - The learning path is *much* less gradual: the simplest possible component requires showing and at least minimally explaining JavaScript import and export semantics and template literals *and* that it isn’t a normal template literal as described above.
 
+- Explaining what exactly `hbs` invocations produce is also strange: they aren’t actually JavaScript expressions, but they *appear* to be. In a template-only context, “invoking” `hbs` produces a component; in a class, it produces the *template* for that component. This is the same as with the `<template>` proposal, but it has the additional quirk of using JavaScript syntax to do it, rather than shifting languages.
+
+Net, while there are some nice features to 
+
 ## Unresolved questions
 
 - Does the possible confusion with the platform `<template>` warrant adopting an alternative syntax, whether component-like (`<Template>`) or using an additional sigil (`<[template]>`, `<% ... %>`, `<$ ... $>` etc.)? If so, what design? Here we must keep in mind that the design should not be ambiguous with “dynamic” behavior (e.g. `<{template}>` which is suggestive of the Svelte and React expression marker, and which we might find attractive for future iterations of template language ourselves).

From 905817bfc87531507a2c92b16453150e8036ca1f Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Tue, 23 Nov 2021 17:29:12 -0700
Subject: [PATCH 09/53] Fill out the section 'Motivation: Constraints'

---
 text/0000-template-imports.md | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 22c15ee8ca..cf142f64a7 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -143,14 +143,17 @@ outcome?
 
 ### Constraints
 
-<!--
-TODO:
+This RFC proposes a design which addresses this set of motivations, but it does not do so in a vacuum; I take the following constraints as guiding the design decision (and the ordering here is purposeful—items earlier in the list I judge to be more important than items later in the list):
 
-- [ ] not regressing (and, optimally, improving!) testing
-- [ ] pedagogy
-- [ ] interop with existing story
+1. Our choice of design **must not** regress our ability to write tests, and if it is possible to *improve* our testing story, we should take the opportunity to do so.
 
--->
+2. In the absence of hard technical constraints forbidding it, we should **prefer** the solution which has the best story for teaching—at all levels, including beginners but also supporting advanced users. In particular, this means that we should value both *progressive disclosure of complexity* and the *principle of least surprise*, and that we may need to weight them against each other, but that we should pay particular attention when they agree.
+
+3. This design must cleanly interoperate with existing Ember codebases. That is, adopting this **must not** require users to migrate their entire codebase at once.
+
+4. We should prefer a design which provides more flexibility to end users over a design which provides less.
+
+While it is certainly possible to differ with these constraints *a priori*—reevaluating constraints is, in a very real sense, [how we got to this very RFC](https://github.com/emberjs/rfcs/pull/367#issuecomment-423839940)—we also run the risk of paralysis if we *continually* reevaluate from first principles. More challenging is inevitable disagreement about how we *weight* these constraints; on that, there is no possibility of *final* agreement, but we should commit to some ordering for the purposes of this design so that the rest of it can proceed on the same terms.
 
 ## Detailed design
 

From 6cec6b6b80393157e29e662163ca4c178c6ec401 Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Tue, 23 Nov 2021 19:39:20 -0700
Subject: [PATCH 10/53] Note on surprising module semantics

---
 text/0000-template-imports.md | 43 +++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index cf142f64a7..7cdeb020d0 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -685,9 +685,52 @@ The imports-only design borrows the idea of “front-matter” from many text au
 The major upside to this is that it is the smallest possible delta over today’s implementation. However, it has a number of significant downsides:
 
 - It does not allow locally-scoped JavaScript values (including helpers and modifiers and also ecosystem tooling like GraphQL values, CSS-in-JS tooling, etc.) even when that is a perfectly reasonable design decision.
+
 - It substantially complicates the implementation of tooling for language servers, which have to do extra work to detect the presence of a backing class and “stitch together” the backing class and the template if a backing class does exist.
+
+- Since there are separate files for a template and its backing class, users may be tempted try to implement JavaScript functionality in the module for the backing class, and import it in the template:
+
+    ```js
+    import Component from '@glimmer/component';
+
+    export function isBirthday() {/*...*/}
+
+    export default class MyComponent extends Component { /*...*/ }
+    ```
+
+    ```hbs
+    ---
+    import { isBirthday } from './my-component';
+    ---
+    {{#if (isBirthday @user.name)}}
+      <p>Happy birthday, {{@user.name}}!</p>
+    {{/if}}
+    ```
+
+    While a colocated template (the default since Octane) is part of the same module as the backing class, this does technically work![^recursive-module] However, it’s the kind of extremely surprising and weird thing we would generally try to avoid pedagogically—it requires us to explain that these two separate files (`.js` and `.hbs`) are combined into a single module at build time.
+
 - Perhaps most critically: **it requires that we continue to support a completely separate design for testing than for app code** (indeed: it basically requires that we fully implement the `hbs` or `<template>` designs for those!)
 
+[^recursive-module]: To see this for yourself:
+
+    1. Create a new Node package (an empty folder with a `package.json` will do), and set `"type": "module"` in it.
+
+    2. Create an `index.js` file with this content:
+  
+        ```js
+        export function amaze() {
+          console.log("modules importing themselves? wow");
+        }
+
+        import { amaze as wow } from './index.js';
+
+        wow();
+        ```
+
+    3. Invoke it by running `node index.js`. It will work just fine and log the string.
+
+    I had to test this out myself, and while it’s a reasonable decision I actually find it fairly surprising!
+
 <!-- TODO: more? -->
 
 ### SFCs

From 4c17d9d4993063668c0732051e84e1cd43149c18 Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Tue, 23 Nov 2021 19:42:07 -0700
Subject: [PATCH 11/53] Fix footnote (GFM footnotes don't support code blocks)

---
 text/0000-template-imports.md | 22 ++--------------------
 1 file changed, 2 insertions(+), 20 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 7cdeb020d0..dea1d36c0d 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -711,28 +711,10 @@ The major upside to this is that it is the smallest possible delta over today’
 
 - Perhaps most critically: **it requires that we continue to support a completely separate design for testing than for app code** (indeed: it basically requires that we fully implement the `hbs` or `<template>` designs for those!)
 
-[^recursive-module]: To see this for yourself:
-
-    1. Create a new Node package (an empty folder with a `package.json` will do), and set `"type": "module"` in it.
-
-    2. Create an `index.js` file with this content:
-  
-        ```js
-        export function amaze() {
-          console.log("modules importing themselves? wow");
-        }
-
-        import { amaze as wow } from './index.js';
-
-        wow();
-        ```
-
-    3. Invoke it by running `node index.js`. It will work just fine and log the string.
-
-    I had to test this out myself, and while it’s a reasonable decision I actually find it fairly surprising!
-
 <!-- TODO: more? -->
 
+[^recursive-module]: To see this for yourself, follow the instructions in [this gist](https://gist.github.com/chriskrycho/dc5adabd80c04d405c7a4894c0ffb99e). I had to test this out myself, and while it’s a reasonable decision I actually find it fairly surprising!
+
 ### SFCs
 
 Single File Components (hereafter SFCs) start with an HTML baseline and layer on functionality in a `<script>` tag, modeled on HTML’s own design, but with extra semantics supporting imports and making an `export default class extends Component` statement provide the `this` for the template context. It can, however, define modifiers and helpers local to the component. You can think of this as a fairly natural (and HTML-like) extension to the imports-only design.

From 3d7e240675cfd6ba2866421e96c66dd7498b6cfa Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Wed, 24 Nov 2021 08:21:15 -0700
Subject: [PATCH 12/53] Notes on route templates around pedagogy

---
 text/0000-template-imports.md | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index dea1d36c0d..3558d9ccd5 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -20,7 +20,7 @@ Relevant Team(s): Fill this in with the [team(s)](README.md#relevant-teams) to w
 RFC PR: Fill this in with the URL for the Proposal RFC PR
 -->
 
-# Template Imports and Strict Mode
+# Template Imports
 
 ## Summary
 
@@ -153,7 +153,7 @@ This RFC proposes a design which addresses this set of motivations, but it does
 
 4. We should prefer a design which provides more flexibility to end users over a design which provides less.
 
-While it is certainly possible to differ with these constraints *a priori*—reevaluating constraints is, in a very real sense, [how we got to this very RFC](https://github.com/emberjs/rfcs/pull/367#issuecomment-423839940)—we also run the risk of paralysis if we *continually* reevaluate from first principles. More challenging is inevitable disagreement about how we *weight* these constraints; on that, there is no possibility of *final* agreement, but we should commit to some ordering for the purposes of this design so that the rest of it can proceed on the same terms.
+While it is certainly possible to differ with these constraints *a priori*—reevaluating constraints is, in a very real sense, [how we got to this very RFC](https://github.com/emberjs/rfcs/pull/367#issuecomment-423839940)—we also run the risk of paralysis if we *continually* reevaluate from first principles. More challenging is inevitable disagreement about how we *weight* these constraints. On that front, there is no possibility of *final* agreement, but we should commit to some ordering for the purposes of this design so that the rest of it can proceed on the same terms.
 
 ## Detailed design
 
@@ -478,10 +478,13 @@ Once this is implemented and tooling is sufficiently stable, we will update the
 
 - Update the output from generators, including correct new file extensions.
 
-- Update the introductory examples, which start with pure HTML, to add a wrapping `<template>` tag, and update the prose to describe that `<template>` marks this as Ember/Glimmer’s special superset of HTML. Note that all you need to do to have a working Ember component is to wrap your HTML in `<template>`.
+- Update the introductory examples, which start with pure HTML, to add a wrapping `<template>` tag, and update the prose to describe that `<template>` marks this as Ember/Glimmer’s special superset of HTML. Note that all you need to do to have a working Ember component is to wrap your HTML in `<template>`.[^route-template]
 
+- The introduction of components 
 <!-- TODO: the rest of the pedagogy updates -->
 
+[^route-template]: This is complicated by the need to introduce route templates as well as component templates. The text here assumes that we will, in parallel with this work, resolve the design questions addressed by [RFC #0731][rfc-0731] in something like the design proposed there. Fundamentally, we *should not* update the guides until we have a resolution for that design space, so they can be updated in a coherent way.
+
 ### API Docs
 
 There is presently no API for `<template>` itself, as proposed in this RFC, though it leaves room for future RFCs, which could introduce e.g. a `<template lang="...">` variation to experiment with alternative template languages.[^emblem] Since there is no import location, we should cover it under the `@glimmer/component` module documentation. This will be a natural home for it, since we will always discuss it in the context of components.
@@ -492,7 +495,7 @@ There is presently no API for `<template>` itself, as proposed in this RFC, thou
 
 ### TypeScript
 
-The type of a component is not affected by this proposal. However, it is worth seeing *how* a component defined using `<template>` works with types.
+The type of a component is not affected by this proposal. However, it is worth seeing *how* a component defined using `<template>` works with types, at least for the purpose of documentation (and for integration with the current DefinitelyTyped definitions).
 
 - For a class-backed component, there is no change when using `<template>`. As described above, tools like Glint will need to <!-- TODO -->
 
@@ -917,6 +920,8 @@ Net, while there are some nice features to
 
 - How does this relate to the currently un-merged [RFC #0731: Add `setRouteComponent` API][rfc-0731]? That is: can we merge this and proceed with authoring components while there is an unresolved design problem for the related issue of routes, controllers, and their host components? Or should we see this as a helpful part of resolving *that* design question? (I believe we can move forward in parallel.)
 
+    The primary challenge here is that, as things stand, our guides would have some fairly substantial incoherence until we solve the problems which #0731 is addressing: route templates would be totally different from component templates in their semantics and behavior. This points to the ongoing and increasing divergence of the `Route` and `Component` design from the rest of the framework, but it’s directly connected to *this* RFC pedagogically.
+
 [rfc-0731]: https://github.com/emberjs/rfcs/pull/731
 
 <!--

From 8b1aa7e41363315fb33d1ab9a6986821040cf8bb Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Wed, 24 Nov 2021 08:44:07 -0700
Subject: [PATCH 13/53] Start filling out components teaching section

---
 text/0000-template-imports.md | 24 ++++++++++++++++++++----
 1 file changed, 20 insertions(+), 4 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 3558d9ccd5..cd7daec51c 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -474,16 +474,30 @@ This explanatory model provides a helpful opportunity, when first introducing th
 
 ### Guides
 
-Once this is implemented and tooling is sufficiently stable, we will update the guides with the following changes:
+Once this is implemented and tooling is sufficiently stable, we will update the guides with changes along the following lines:[^route-template]
 
 - Update the output from generators, including correct new file extensions.
 
-- Update the introductory examples, which start with pure HTML, to add a wrapping `<template>` tag, and update the prose to describe that `<template>` marks this as Ember/Glimmer’s special superset of HTML. Note that all you need to do to have a working Ember component is to wrap your HTML in `<template>`.[^route-template]
+- Update the introductory examples, which start with pure HTML, to add a wrapping `<template>` tag, and update the prose to describe that `<template>` marks this as Ember/Glimmer’s special superset of HTML. Note that all you need to do to have a working Ember component is to wrap your HTML in `<template>`.
+
+- Introducing components will see the most changes, unsurprisingly:
+	- Note that we have already seen components in practice, because the templates we used with our routes were also components.
+
+	- While we *conventionally* use `<CapitalizedComponents />` (and historically *had* to because that was the decision for how the resolver would work), that’s no longer a hard constraint. If someone does `const foo = <template>...</template>`, they will be able to invoke that as `<foo />` elsewhere. The notes in this section as well as about `LinkTo` will need to be updated to describe this as a helpful convention.
+
+	- After introducing `<Jumbo />` with updated use of a wrapping `<template>`, discuss *importing it* into the route (component) template which uses it. This is a good place to describe how `.gjs` can use JS features, and hint that we’ll see more of this later; it is also a good opportunity to note that we *could* have defined `<Jumbo />` locally, but that we moved it to a separate file because we’re sharing it across multiple different components.
+
+	- Our discussion of the testing will need to be updated to include importing the components under test, and to use `<template>` rather than `hbs` strings for the `render` calls.[^testing-rfc]
+
+	- We can simply *remove* the discussion of namespaced components, in favor of simply describing the use of normal JS imports to accomplish the same goal. However, here we can also note that JavaScript modules are a great way to organize groups of related components, and show how we might use namespace-style imports (`import * as Rental from '';` and then `<Rental.Image />` within a `<template>`) for this kind of organization.[^namespace-deprecation]
 
-- The introduction of components 
 <!-- TODO: the rest of the pedagogy updates -->
 
-[^route-template]: This is complicated by the need to introduce route templates as well as component templates. The text here assumes that we will, in parallel with this work, resolve the design questions addressed by [RFC #0731][rfc-0731] in something like the design proposed there. Fundamentally, we *should not* update the guides until we have a resolution for that design space, so they can be updated in a coherent way.
+[^route-template]: This is complicated by the need to introduce route templates as well as component templates. The text here assumes that we will, in parallel with this work, resolve the design questions addressed by [RFC #0731][rfc-0731] in something like the design proposed there. Accordingly, it also assumes we will update the generators and the relevant text accordingly. Fundamentally, we *should not* update the guides until we have a resolution for that design space, so they can be updated in a coherent way.
+
+[^testing-rfc]: Here I assume a forthcoming RFC which will allow `render` to work not only with templates (the _status quo_) but also with components. This will be an independent change which helps eliminate a number of quirks in the testing infrastructure today, but complements *this* RFC by allowing local definition of tests.
+
+[^namespace-deprecation]: This does mean that the namespace sigil is a candidate for later deprecation, since it will be entirely redundant once the ecosystem moves fully to strict mode and template imports. I think that question is best left to a hypothetical RFC deprecating loose mode.
 
 ### API Docs
 
@@ -922,6 +936,8 @@ Net, while there are some nice features to
 
     The primary challenge here is that, as things stand, our guides would have some fairly substantial incoherence until we solve the problems which #0731 is addressing: route templates would be totally different from component templates in their semantics and behavior. This points to the ongoing and increasing divergence of the `Route` and `Component` design from the rest of the framework, but it’s directly connected to *this* RFC pedagogically.
 
+- Should we include a plan for a staged rollout of deprecating namespace resolution in this RFC, rather than tackling it in a later RFC?
+
 [rfc-0731]: https://github.com/emberjs/rfcs/pull/731
 
 <!--

From 0fdfc1dba5e33f2f1ecaec1eb0e724a3c156e1ac Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Wed, 24 Nov 2021 08:47:12 -0700
Subject: [PATCH 14/53] Add more expected sections in Tooling

---
 text/0000-template-imports.md | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index cd7daec51c..8878dbce25 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -120,6 +120,9 @@ It offers these new capabilities while not only maintaining but *improving* Embe
   - [Interop](#interop)
   - [The “prelude”](#the-prelude)
   - [Tooling](#tooling)
+    - [Generators](#generators)
+    - [Linting and formatting](#linting-and-formatting)
+    - [Language server support](#language-server-support)
 - [How we teach this](#how-we-teach-this)
   - [Guides](#guides)
   - [API Docs](#api-docs)
@@ -466,6 +469,18 @@ defined here.
 
 <!-- TODO -->
 
+#### Generators
+
+<!-- TODO -->
+
+#### Linting and formatting
+
+<!-- TODO -->
+
+#### Language server support
+
+<!-- TODO -->
+
 ## How we teach this
 
 We describe a `<template>` as representing the *template* for a *component*. When there is no backing class, that’s all there is to the component. When there *is* a backing class, the component also has associated state and behavior. (Notably, this shift already began with Octane, where we generate template-only components by default.)

From 94291b2a4717a668bd50cbc69666bc78946c2c8b Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Wed, 24 Nov 2021 09:10:58 -0700
Subject: [PATCH 15/53] Describe changes to guides for components w/behavior

---
 text/0000-template-imports.md | 18 +++++++++++++-----
 1 file changed, 13 insertions(+), 5 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 8878dbce25..4346e8b91e 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -496,15 +496,23 @@ Once this is implemented and tooling is sufficiently stable, we will update the
 - Update the introductory examples, which start with pure HTML, to add a wrapping `<template>` tag, and update the prose to describe that `<template>` marks this as Ember/Glimmer’s special superset of HTML. Note that all you need to do to have a working Ember component is to wrap your HTML in `<template>`.
 
 - Introducing components will see the most changes, unsurprisingly:
-	- Note that we have already seen components in practice, because the templates we used with our routes were also components.
+    - Note that we have already seen components in practice, because the templates we used with our routes were also components.
 
-	- While we *conventionally* use `<CapitalizedComponents />` (and historically *had* to because that was the decision for how the resolver would work), that’s no longer a hard constraint. If someone does `const foo = <template>...</template>`, they will be able to invoke that as `<foo />` elsewhere. The notes in this section as well as about `LinkTo` will need to be updated to describe this as a helpful convention.
+    - While we *conventionally* use `<CapitalizedComponents />` (and historically *had* to because that was the decision for how the resolver would work), that’s no longer a hard constraint. If someone does `const foo = <template>...</template>`, they will be able to invoke that as `<foo />` elsewhere. The notes in this section as well as about `LinkTo` will need to be updated to describe this as a helpful convention.
 
-	- After introducing `<Jumbo />` with updated use of a wrapping `<template>`, discuss *importing it* into the route (component) template which uses it. This is a good place to describe how `.gjs` can use JS features, and hint that we’ll see more of this later; it is also a good opportunity to note that we *could* have defined `<Jumbo />` locally, but that we moved it to a separate file because we’re sharing it across multiple different components.
+    - After introducing `<Jumbo />` with updated use of a wrapping `<template>`, discuss *importing it* into the route (component) template which uses it. This is a good place to describe how `.gjs` can use JS features, and hint that we’ll see more of this later; it is also a good opportunity to note that we *could* have defined `<Jumbo />` locally, but that we moved it to a separate file because we’re sharing it across multiple different components.
 
-	- Our discussion of the testing will need to be updated to include importing the components under test, and to use `<template>` rather than `hbs` strings for the `render` calls.[^testing-rfc]
+    - Our discussion of the testing will need to be updated to include importing the components under test, and to use `<template>` rather than `hbs` strings for the `render` calls.[^testing-rfc]
 
-	- We can simply *remove* the discussion of namespaced components, in favor of simply describing the use of normal JS imports to accomplish the same goal. However, here we can also note that JavaScript modules are a great way to organize groups of related components, and show how we might use namespace-style imports (`import * as Rental from '';` and then `<Rental.Image />` within a `<template>`) for this kind of organization.[^namespace-deprecation]
+    - We can simply *remove* the discussion of namespaced components, in favor of simply describing the use of normal JS imports to accomplish the same goal. However, here we can also note that JavaScript modules are a great way to organize groups of related components, and show how we might use namespace-style imports (`import * as Rental from '';` and then `<Rental.Image />` within a `<template>`) for this kind of organization.[^namespace-deprecation]
+
+- The discussion of adding behavior to components will need to be updated as follows:
+
+    1. Show that when we generate a class for an existing component, it  adds the `Component` import, creates a wrapping class, and moves the template into the body of that class. Here, teach the mental model that a `<template>` which is part of a class body has access to the instance properties on the backing class.
+
+    2. When discussing use of values from `ENV`, instead of providing a getter on a backing class, start by creating a `TOKEN` constant in module scope, and show that it is available to access in the template. In the following section, which shows args being used in the template, simply use that `TOKEN` value in the template directly, `access_token={{TOKEN}}`.
+
+    3. When refactoring to use a getter for `src`, use the value as `${TOKEN}`. Note explicitly how there is a symmetry between JS and templates: you can use whichever approach is clearer for a given context.
 
 <!-- TODO: the rest of the pedagogy updates -->
 

From a847a1799a4f6d586555eaeace14b08b8e329dbf Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Wed, 24 Nov 2021 09:12:17 -0700
Subject: [PATCH 16/53] Better structure for guides discussion

---
 text/0000-template-imports.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 4346e8b91e..5721680d0d 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -495,18 +495,18 @@ Once this is implemented and tooling is sufficiently stable, we will update the
 
 - Update the introductory examples, which start with pure HTML, to add a wrapping `<template>` tag, and update the prose to describe that `<template>` marks this as Ember/Glimmer’s special superset of HTML. Note that all you need to do to have a working Ember component is to wrap your HTML in `<template>`.
 
-- Introducing components will see the most changes, unsurprisingly:
-    - Note that we have already seen components in practice, because the templates we used with our routes were also components.
+- Introducing components will see a lot of changes, unsurprisingly:
+    1. Note that we have already seen components in practice, because the templates we used with our routes were also components.
 
-    - While we *conventionally* use `<CapitalizedComponents />` (and historically *had* to because that was the decision for how the resolver would work), that’s no longer a hard constraint. If someone does `const foo = <template>...</template>`, they will be able to invoke that as `<foo />` elsewhere. The notes in this section as well as about `LinkTo` will need to be updated to describe this as a helpful convention.
+    2. While we *conventionally* use `<CapitalizedComponents />` (and historically *had* to because that was the decision for how the resolver would work), that’s no longer a hard constraint. If someone does `const foo = <template>...</template>`, they will be able to invoke that as `<foo />` elsewhere. The notes in this section as well as about `LinkTo` will need to be updated to describe this as a helpful convention.
 
-    - After introducing `<Jumbo />` with updated use of a wrapping `<template>`, discuss *importing it* into the route (component) template which uses it. This is a good place to describe how `.gjs` can use JS features, and hint that we’ll see more of this later; it is also a good opportunity to note that we *could* have defined `<Jumbo />` locally, but that we moved it to a separate file because we’re sharing it across multiple different components.
+    3. After introducing `<Jumbo />` with updated use of a wrapping `<template>`, discuss *importing it* into the route (component) template which uses it. This is a good place to describe how `.gjs` can use JS features, and hint that we’ll see more of this later; it is also a good opportunity to note that we *could* have defined `<Jumbo />` locally, but that we moved it to a separate file because we’re sharing it across multiple different components.
 
-    - Our discussion of the testing will need to be updated to include importing the components under test, and to use `<template>` rather than `hbs` strings for the `render` calls.[^testing-rfc]
+    4. Our discussion of the testing will need to be updated to include importing the components under test, and to use `<template>` rather than `hbs` strings for the `render` calls.[^testing-rfc]
 
-    - We can simply *remove* the discussion of namespaced components, in favor of simply describing the use of normal JS imports to accomplish the same goal. However, here we can also note that JavaScript modules are a great way to organize groups of related components, and show how we might use namespace-style imports (`import * as Rental from '';` and then `<Rental.Image />` within a `<template>`) for this kind of organization.[^namespace-deprecation]
+    5. We can simply *remove* the discussion of namespaced components, in favor of simply describing the use of normal JS imports to accomplish the same goal. However, here we can also note that JavaScript modules are a great way to organize groups of related components, and show how we might use namespace-style imports (`import * as Rental from '';` and then `<Rental.Image />` within a `<template>`) for this kind of organization.[^namespace-deprecation]
 
-- The discussion of adding behavior to components will need to be updated as follows:
+- The discussion of adding behavior to components will similarly need to be updated substantially:
 
     1. Show that when we generate a class for an existing component, it  adds the `Component` import, creates a wrapping class, and moves the template into the body of that class. Here, teach the mental model that a `<template>` which is part of a class body has access to the instance properties on the backing class.
 

From 3e307528b0a768a455aaed1a71b4486ab54435f0 Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Wed, 24 Nov 2021 09:17:18 -0700
Subject: [PATCH 17/53] Clarify footnote on self-imports

---
 text/0000-template-imports.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 5721680d0d..9100b4df41 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -753,7 +753,7 @@ The major upside to this is that it is the smallest possible delta over today’
 
 <!-- TODO: more? -->
 
-[^recursive-module]: To see this for yourself, follow the instructions in [this gist](https://gist.github.com/chriskrycho/dc5adabd80c04d405c7a4894c0ffb99e). I had to test this out myself, and while it’s a reasonable decision I actually find it fairly surprising!
+[^recursive-module]: To see this for yourself, follow the instructions in [this gist](https://gist.github.com/chriskrycho/dc5adabd80c04d405c7a4894c0ffb99e). I had to test this out myself, and while it’s actually *very good* that modules work this way, I was initially surprised by it! If you’re curious: imports and exports are *static* and so are analyzed before the module is executed.
 
 ### SFCs
 

From 96e5741a6ceb31ef6cafe4af1d548655d45c6974 Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Wed, 24 Nov 2021 09:29:38 -0700
Subject: [PATCH 18/53] Document TS changes for `TC<Args>`

---
 text/0000-template-imports.md | 33 ++++++++++++++++++++++++++++-----
 1 file changed, 28 insertions(+), 5 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 9100b4df41..9145308fe9 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -534,16 +534,38 @@ There is presently no API for `<template>` itself, as proposed in this RFC, thou
 
 The type of a component is not affected by this proposal. However, it is worth seeing *how* a component defined using `<template>` works with types, at least for the purpose of documentation (and for integration with the current DefinitelyTyped definitions).
 
-- For a class-backed component, there is no change when using `<template>`. As described above, tools like Glint will need to <!-- TODO -->
+- For a class-backed component, there is no change when using `<template>`. As described above, tools like Glint will need to provide an interpretation of `<template>` which captures, minimally, the arguments to the function.
 
-- For a template-only component, defining the type will require a type import to represent that there is a component with no `this` context, etc. Glint already supplies such a type, albeit with the types updated for [RFC #0748][rfc-0748]. For today’s purposes, we can define such a type as follows (with the `TemplateComponent`/`TC` shorthand here following the lead of React’s `FunctionComponent`/`FC` types):
+- For a template-only component, defining the type will require a type import to represent that there is a component with no `this` context, etc. Glint already supplies such a type, albeit with the types updated for [RFC #0748][rfc-0748]. For today’s purposes, we can simply augment the [existing types on DefinitelyTyped][DT-toc] with `Args`.
+
+    <details><summary>updated signature on DT</summary>
 
     ```ts
-    export interface TemplateOnly<Args extends {} = {}> {}
-    export type TC<Args extends {} = {}> = TemplateOnly<Args>;
+    declare const A: unique symbol;
+
+    // This class is not intended to be directly constructable.
+    declare class _TemplateOnlyComponent<Args extends {}> {
+        // Type brand to simulate a nominal type.
+        declare private brand: 'TemplateOnlyComponent';
+        // Host to make args "used"
+        declare private [A]: Args;
+        toString(): string;
+    }
+
+    // Export an interface instead to prevent construction.
+    // tslint:disable-next-line:no-empty-interface
+    export interface TemplateOnlyComponent<Args extends {} = {}> extends _TemplateOnlyComponent<Args> {}
+    type TC<Args extends {} = {}> = TemplateOnlyComponent<Args>
+
+    declare function templateOnly(moduleName?: string): TemplateOnlyComponent;
+
+    export default templateOnly;
+
+    // Shut off automatic exporting.
+    export {};
     ```
 
-    Users can then define a tmeplate-only component like this:
+    Users can then define a template-only component like this:
 
     ```ts
     import { TC } from '@glimmer/component';
@@ -556,6 +578,7 @@ The type of a component is not affected by this proposal. However, it is worth s
     While this empty interface is currently more or less useless from a type-checking perspective (we will need something like Glint to support it), it suffices to provide a hook for documentation tooling such as TypeDoc or API Extractor—but this suffices for the level of support we have for TypeScript today.
 
 [rfc-0748]: https://github.com/emberjs/rfcs/pull/748
+[DT-toc]: https://github.com/DefinitelyTyped/DefinitelyTyped/blob/54d540ab4deb2588c0eff39dadf370cbf0a2dee4/types/ember__component/template-only.d.ts
 
 ### Existing Ember users
 

From 8af440e07aeeb03222be5a09e2643245db4ab701 Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Wed, 24 Nov 2021 09:31:00 -0700
Subject: [PATCH 19/53] Better wording on one drawback

---
 text/0000-template-imports.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 9145308fe9..6d40d18ec5 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -601,7 +601,7 @@ users?
 
 ## Drawbacks
 
-- API documentation is somewhat difficult, since there is no notional import for `<template>`.
+- Since there is no notional import for `<template>`, there also isn’t a notional home for API documentation.
 
 - We must build a custom tooling integration with Prettier for the file format to *parse*. (As discussed below, we must build custom tooling to *use* Prettier for other options, but Prettier can *parse* them without custom tooling.)
 

From 3b995ae42098aa0a1e9de6ec5ae119bc8d5da865 Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Wed, 24 Nov 2021 10:03:53 -0700
Subject: [PATCH 20/53] Elaborate Drawbacks

---
 text/0000-template-imports.md | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 6d40d18ec5..42ce1081e5 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -601,12 +601,18 @@ users?
 
 ## Drawbacks
 
-- Since there is no notional import for `<template>`, there also isn’t a notional home for API documentation.
+- Since there is no notional import for `<template>`, there also isn’t a notional home for API documentation for it other than components.
 
 - We must build a custom tooling integration with Prettier for the file format to *parse*. (As discussed below, we must build custom tooling to *use* Prettier for other options, but Prettier can *parse* them without custom tooling.)
 
 - While not especially important in the context of a front-end framework (as opposed to a framework-less/“vanilla” context), `<template>` does technically overlap with a platform built-in, and would look very strange if a user *did*  want to use the built-in form.
 
+- Developers may put an unreasonable number of components, helpers, modifiers, etc. in a single file, degrading the maintainability of that module. However, the counterpoint here is that large files are already common in many code bases, with or without this tool. Indeed, that happens in non-UI and UI code bases alike!
+
+    Moreover, experience from frameworks which restrict component authoring formats to a single component per file, including Ember’s loose mode templates as well as Vue and Svelte SFCs, is that those components themselves tend to balloon in size. Sometimes that’s because everything in those components is notionally related or because much of it should be treated as "private API" for that component (even if it would be helpful to refactor small local components). Sometimes it is just because of the annoying overhead of needing to create a separate file to break the huge component into smaller pieces, and then import them all (or make them globally available, in Ember loose mode template!).
+
+    The analogy here would be if a JavaScript module could only have a single function or class in it, or a CSS file could only have a single declaration in it, regardless of what actually made sense for that particular module.
+
 <!--
 
 > Why should we *not* do this? Please consider the impact on teaching Ember,

From de5973b651ce06917fa26c5e86f8ef5500f245ba Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Wed, 1 Dec 2021 09:43:15 -0700
Subject: [PATCH 21/53] Spaces before sections!

---
 text/0000-template-imports.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 42ce1081e5..c40c37c6f1 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -135,6 +135,7 @@ It offers these new capabilities while not only maintaining but *improving* Embe
   - [Template literals](#template-literals)
 - [Unresolved questions](#unresolved-questions)
 
+
 ## Motivation
 
 <!--
@@ -144,6 +145,7 @@ outcome?
 
 -->
 
+
 ### Constraints
 
 This RFC proposes a design which addresses this set of motivations, but it does not do so in a vacuum; I take the following constraints as guiding the design decision (and the ordering here is purposeful—items earlier in the list I judge to be more important than items later in the list):
@@ -158,6 +160,7 @@ This RFC proposes a design which addresses this set of motivations, but it does
 
 While it is certainly possible to differ with these constraints *a priori*—reevaluating constraints is, in a very real sense, [how we got to this very RFC](https://github.com/emberjs/rfcs/pull/367#issuecomment-423839940)—we also run the risk of paralysis if we *continually* reevaluate from first principles. More challenging is inevitable disagreement about how we *weight* these constraints. On that front, there is no possibility of *final* agreement, but we should commit to some ordering for the purposes of this design so that the rest of it can proceed on the same terms.
 
+
 ## Detailed design
 
 Introduce a new high-level syntax, the `<template>` tag, which is syntactical sugar for `setComponentTemplate` and `precompileTemplate`, in conjunction with the existing Ember and Glimmer `Component` classes and the special template-only component class returned by the `templateOnlyComponent` default export from `@ember/component/template-only`. There are three distinct, legal forms for this compilation:
@@ -171,12 +174,14 @@ For a discussion of the `setComponentTemplate` and `templateOnlyComponent` primi
 [rfc-0481]: https://emberjs.github.io/rfcs/0481-component-templates-co-location.html
 [rfc-0496]: https://emberjs.github.io/rfcs/0496-handlebars-strict-mode.html
 
+
 ### Compilation
 
 The value produced by authoring a `<template>` is a *JavaScript value*, and accordingly may be exported, bound to other values, passed as an argument to a function or set as a value on a class, etc. However, the value may not be treated as *dynamic*: the rendering engine will evaluate the value exactly and only once. Therefore, it is nonsensical to use it with a `let` binding or to attempt to create new `<template>`s dynamically from the body of a function. (A function may of course return different components based on its arguments, etc.; it simply may not *construct* new component templates dynamically.)
 
 <!-- TODO: validate import locations for `on`, `eq`, `gt` (see https://github.com/emberjs/rfcs/pull/560) -->
 
+
 #### Bound to a name
 
 <!-- TODO: validate correct compile output for `scope` given deprecation -->
@@ -311,6 +316,7 @@ const Greet = setComponentTemplate(
 
     The sole exception here is that it makes perfectly good sense to define components, whether class-backed or not, in the context of *test modules*, where the context only exists for as long as the test itself and so the concerns are no longer an issue.
 
+
 #### Standalone
 
 The compiled output for a top-level `<template>` tag *not* bound to a name is a default export, but otherwise identical to a `<template>` declaration bound to a tag. Thus, given this input:
@@ -341,6 +347,7 @@ Scoped values are included the same as with named definitions.
 
 Since the compiled output is a default export, it is a static error to have multiple top-level (i.e. not bound to a name) `<template>`s in a file—because it is a static error to have multiple `export default` statements in a JavaScript file. (We should provide linting tooling to error on this case, rather than letting it fail at runtime.)
 
+
 #### Class body
 
 The compilation output with a class-backed component is similar, but instead of using `templateOnlyComponent`, it uses the backing class. Given this component:
@@ -417,6 +424,7 @@ setComponentTemplate(
 )
 ```
 
+
 ### Interop
 
 Since all existing components already work using the same low-level primitives the new system uses, strict-mode components using `<template>` can import and invoke components authored in Ember’s loose mode format. Similarly, since loose mode components are resolved to a component which is the default export of a module in the correct/conventional location on disk, components authored in strict mode with `<template>` and exported as the default export in that conventional location will be resolveable by loose mode components as well.
@@ -461,32 +469,39 @@ defined here.
 
 -->
 
+
 ### The “prelude”
 
 <!-- TODO -->
 
+
 ### Tooling
 
 <!-- TODO -->
 
+
 #### Generators
 
 <!-- TODO -->
 
+
 #### Linting and formatting
 
 <!-- TODO -->
 
+
 #### Language server support
 
 <!-- TODO -->
 
+
 ## How we teach this
 
 We describe a `<template>` as representing the *template* for a *component*. When there is no backing class, that’s all there is to the component. When there *is* a backing class, the component also has associated state and behavior. (Notably, this shift already began with Octane, where we generate template-only components by default.)
 
 This explanatory model provides a helpful opportunity, when first introducing the idea of a backing class, to link to deeper-dive materials which let people who want to understand more deeply. In particular, it allows us a place to point out that mechanically, there *is* in fact always an associated component instance (generated via `templateOnlyComponent()`), but it’s just a way for this `<template>` to be hooked into the broader system, rather than a home for state.
 
+
 ### Guides
 
 Once this is implemented and tooling is sufficiently stable, we will update the guides with changes along the following lines:[^route-template]
@@ -522,6 +537,7 @@ Once this is implemented and tooling is sufficiently stable, we will update the
 
 [^namespace-deprecation]: This does mean that the namespace sigil is a candidate for later deprecation, since it will be entirely redundant once the ecosystem moves fully to strict mode and template imports. I think that question is best left to a hypothetical RFC deprecating loose mode.
 
+
 ### API Docs
 
 There is presently no API for `<template>` itself, as proposed in this RFC, though it leaves room for future RFCs, which could introduce e.g. a `<template lang="...">` variation to experiment with alternative template languages.[^emblem] Since there is no import location, we should cover it under the `@glimmer/component` module documentation. This will be a natural home for it, since we will always discuss it in the context of components.
@@ -530,6 +546,7 @@ There is presently no API for `<template>` itself, as proposed in this RFC, thou
 
 [emblem]: http://emblemjs.com
 
+
 ### TypeScript
 
 The type of a component is not affected by this proposal. However, it is worth seeing *how* a component defined using `<template>` works with types, at least for the purpose of documentation (and for integration with the current DefinitelyTyped definitions).
@@ -580,6 +597,7 @@ The type of a component is not affected by this proposal. However, it is worth s
 [rfc-0748]: https://github.com/emberjs/rfcs/pull/748
 [DT-toc]: https://github.com/DefinitelyTyped/DefinitelyTyped/blob/54d540ab4deb2588c0eff39dadf370cbf0a2dee4/types/ember__component/template-only.d.ts
 
+
 ### Existing Ember users
 
 <!-- existing ember users introduction -->
@@ -599,6 +617,7 @@ users?
 
 -->
 
+
 ## Drawbacks
 
 - Since there is no notional import for `<template>`, there also isn’t a notional home for API documentation for it other than components.
@@ -623,6 +642,7 @@ on the impact of the API churn on existing apps, etc.
 
 -->
 
+
 ## Alternatives
 
 <!--
@@ -646,6 +666,7 @@ Additionally, there are three major alternatives which Ember community members h
 
 I discuss each of these briefly below; for a *much* longer and more thorough discussion, please see the \~16,000-word series of blog posts I wrote as a deep dive: [**Ember Template Imports**](https://v5.chriskrycho.com/journal/ember-template-imports/).
 
+
 ### Imports-only
 
 The imports-only design borrows the idea of “front-matter” from many text authoring formats, using something like `---`-delimiters to introduce a new, non-Handlebars area at the top of a template which allows exactly and only *imports* to appear. As with all strict-mode designs, all non-built-in values must be imported here. Thus, the *template* for the final component shown in the motivating example might appear like this:
@@ -784,6 +805,7 @@ The major upside to this is that it is the smallest possible delta over today’
 
 [^recursive-module]: To see this for yourself, follow the instructions in [this gist](https://gist.github.com/chriskrycho/dc5adabd80c04d405c7a4894c0ffb99e). I had to test this out myself, and while it’s actually *very good* that modules work this way, I was initially surprised by it! If you’re curious: imports and exports are *static* and so are analyzed before the module is executed.
 
+
 ### SFCs
 
 Single File Components (hereafter SFCs) start with an HTML baseline and layer on functionality in a `<script>` tag, modeled on HTML’s own design, but with extra semantics supporting imports and making an `export default class extends Component` statement provide the `this` for the template context. It can, however, define modifiers and helpers local to the component. You can think of this as a fairly natural (and HTML-like) extension to the imports-only design.
@@ -881,6 +903,7 @@ This is very attractive in some ways, but it comes with three downsides:
 - The scope handling for the default export is unusual and requires additional teaching.
 - Perhaps most critically: as with the imports-only design, **the SFC design requires that we continue to support a completely separate design for testing than for app code** (indeed: it basically requires that we fully implement the `hbs` or `<template>` designs for those!)
 
+
 ### Template literals
 
 The “template literals” design takes as its starting point the `hbs` template strings Ember has used for testing since the 1.x era. It is relatively similar to the `<template>` design, in that it uses JavaScript/TypeScript files as the basis for its design. Unlike `template`, it uses an explicit `hbs` import, presumably from `@glimmer/component`. For components with a backing class, the template is defined as a static class field.
@@ -978,6 +1001,7 @@ However, it also has some significant disadvantages:
 
 Net, while there are some nice features to 
 
+
 ## Unresolved questions
 
 - Does the possible confusion with the platform `<template>` warrant adopting an alternative syntax, whether component-like (`<Template>`) or using an additional sigil (`<[template]>`, `<% ... %>`, `<$ ... $>` etc.)? If so, what design? Here we must keep in mind that the design should not be ambiguous with “dynamic” behavior (e.g. `<{template}>` which is suggestive of the Svelte and React expression marker, and which we might find attractive for future iterations of template language ourselves).

From 7bff1b1169b13a3b2b0f20aa289b02c94c1314d8 Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Wed, 1 Dec 2021 09:43:37 -0700
Subject: [PATCH 22/53] Flag some TODOs: the title, and content to write

---
 text/0000-template-imports.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index c40c37c6f1..625b4e047a 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -20,7 +20,9 @@ Relevant Team(s): Fill this in with the [team(s)](README.md#relevant-teams) to w
 RFC PR: Fill this in with the URL for the Proposal RFC PR
 -->
 
-# Template Imports
+
+# TODO: let's name this thing something catchy!
+
 
 ## Summary
 
@@ -999,7 +1001,7 @@ However, it also has some significant disadvantages:
 
 - Explaining what exactly `hbs` invocations produce is also strange: they aren’t actually JavaScript expressions, but they *appear* to be. In a template-only context, “invoking” `hbs` produces a component; in a class, it produces the *template* for that component. This is the same as with the `<template>` proposal, but it has the additional quirk of using JavaScript syntax to do it, rather than shifting languages.
 
-Net, while there are some nice features to 
+Net, while there are some nice features to <!-- TODO: finish discussing `hbs` -->
 
 
 ## Unresolved questions

From 1bdb851d4c43e887bf0b1a7af273ac5750d19955 Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Wed, 1 Dec 2021 10:41:33 -0700
Subject: [PATCH 23/53] Add motivation section!

---
 text/0000-template-imports.md | 94 +++++++++++++++++++++++++++++++----
 1 file changed, 84 insertions(+), 10 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 625b4e047a..3a10b0ee2c 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -140,12 +140,90 @@ It offers these new capabilities while not only maintaining but *improving* Embe
 
 ## Motivation
 
-<!--
+Today, authors of Ember and Glimmer apps and libraries must author their templates and JavaScript in separate `.hbs` and `.js` files, and the templates exist in a “resolution” mode where every component, helper, and modifier exists in a single global namespace. This has a number of significant downsides. What’s more, there are significant new capabilities for Ember and Glimmer authors made available by embracing JavaScript scope—while keeping our commitments to testing and separation of concerns.[^original-primitives-rfc]
 
-> Why are we doing this? What use cases does it support? What is the expected
-outcome?
+[^original-primitives-rfc]: See also [the SFC & Template Import Primitives RFC](https://github.com/emberjs/rfcs/blob/tomdale/template-primitives/text/000-sfc-and-template-import-primitives.md), which described the motivation for implementing the primitives on which this proposal will build.
 
--->
+
+### Namespaces and Modules
+
+First, because of the global namespace, name conflicts are common, and avoiding them requires either manually namespacing components or using (now-deprecated) experimental tools like [`ember-holy-futuristic-template-namespacing-batman`](https://github.com/rwjblue/ember-holy-futuristic-template-namespacing-batman). But:
+
+- Manually namespacing is clunky and does not actually *guarantee* there won't be conflicts. Combined with the way addons typically supply , name conflicts are sometimes unavoidable.
+
+- Even the workaround via `ember-holy-futuristic-template-namespacing-batman` requires using different names for modules in Ember than their Node package name when the Node package uses [npm scopes][scopes]. (This was one of the original motivations for exploring a design which leverages JavaScript modules, in fact!) Since our resolution modes must ultimately deal in JavaScript terms, we are in the position of always potentially being one ecosystem shift away from another syntax conflict with template-language-only designs for managing scope.
+
+- It requires our tooling to understand Ember's resolution rules, and cannot take advantage of existing ecosystem tooling. Our language servers, for example, have to more or less reimplement Ember’s resolver themselves. And on the build side, Ember CSS Modules has to do an enormous amount of very hacky work (just ask the author!) to make CSS Modules work with Ember. These problems are fundamental to the current model.
+
+- There is a substantial performance cost to dynamically resolving components by name at runtime. This can be mitigated by using the combination of something like `ember-holy-futuristic-template-namespacing-batman` with the [strict resolver][strict-resolver], but the strict resolver is not standard—and really cannot be without something like this proposal.[^strict-resolver-rfc]
+
+- It is extremely unpleasant (though, strictly speaking, *possible* as of Ember 3.25[^verbose-local]) to introduce a component, helper, or modifier which is not in the global namespace. See the next section, [**Scope**](#scope), for further on this.
+
+The global namespace also comes with overhead for our teaching story by introducing a layer of “magic”: people just have to memorize that a file with a default export in a given location *automagically* is available with a given name. This is just a “bare fact”: there is nothing to connect it to in terms of a developers’ existing JavaScript or HTML knowledge.
+
+[strict-resolver]: https://github.com/stefanpenner/ember-strict-resolver
+
+These problems are all well-solved already, using the JavaScript modules spec (or "ESM", for ECMAScript Modules). Today, however Ember developers cannot take advantage of those or the tooling which understands them!
+
+[^strict-resolver-rfc]: See the still-open [RFC #0683][rfc-0683] for a discussion of the full set of concerns involved in resolution, which include but are not limited to the template concerns addressed here.
+
+[rfc-0683]: https://github.com/emberjs/rfcs/pull/683
+
+[^verbose-local]: In all cases, doing so requires introducing a backing class to make the value available to the template *or* writing Ember's strict mode template syntax manually (which is error-prone and extremely verbose: it is designed as an output format, not an authoring format).
+
+
+### Scope
+
+Second, and closely related to the global namespace problem: there is presently no good way for users to introduce or use locally-scoped code. Every component, helper, and modifier must live in its own file, and be globally availbale—even if it is meant to be used privately. Where JavaScript modules provide users to control their public APIs in terms of `export`s, Ember apps largely cannot take advantage of those for anything which interacts with the template layer.
+
+In practice, this has a number of knock-on effects for Ember code:
+
+- Components tend to grow without bound, because there is no easy equivalent to the "extract method" or "extract into new class" refactorings (which we commonly use on the JS side) which does not (a) make the newly-extracted components available to the whole app and (b) require an entirely new file.
+
+- Users also often introduce classes with actions where a simple function-based helper would do, because that is the only way to provide a non-global function.
+
+- It likewise incentivizes the use of the ember-render-modifiers with backing classes, rather than custom modifiers, because the behavior can then be scoped to that module—whereas, again, a custom modifier would be in global scope. This in turn makes it easy for users to miss the helpful separation of concerns which custom modifiers enable.
+
+Over time, these all lead to a proliferation of backing classes which are only present to work around the fact that we have no *other* way to provide non-global scope for our components. These classes in turn tend to act as “state attractors,” leading to an unnecessary proliferation of state throughout an app or addon.
+
+[scopes]: https://docs.npmjs.com/cli/v8/using-npm/scope
+
+What’s more, tools which assume they will be used in JavaScript contexts more or less don’t work with our templates today, because the templates have no way to access them. Think of CSS tools like [Emotion][emotion], [Styled Components][styled-components], [vanilla-extract][vanilla-extract], and even [CSS Modules][css-modules]: none of them work out of the box with our current design, and tools like Ember CSS Modules have to jump through many hoops and do many hacks to work at all. Whatever anyone’s personal opinions on these specific, they’re potentially-valuable tools which are barely or not at all usable in Ember today.
+
+[emotion]: https://emotion.sh/docs/@emotion/css
+[styled-components]: https://styled-components.com
+[vanilla-extract]: https://vanilla-extract.style
+[css-modules]: https://github.com/css-modules/css-modules
+
+
+### Testing
+
+Finally, the authoring format for tests and the authoring format for app code today is completely different. A test can render a component by calling the `render()` function from `@ember/test-helpers` and passing it a Handlebars string.[^testing-rfc] App code *cannot* do this or anything like it. This has teaching overhead: we both *can* do things in tests we *cannot* do in app code, raising the obvious “but why not?”; and we also *must* do things in tests we do not *need* to do in app code.
+
+Additionally, introducing test-only components is quite painful, requiring use of the `this.owner.register()` functionality, and therefore requiring users to understand at least some of Ember’s custom runtime resolution (as well as learning a microsyntax for it[^microsyntax]). What's more, authoring a *template* for a test-only component is undocumented and is also entirely unlike the story for authoring templates for app components.
+
+[^testing-rfc]: The test helper `render()` also does not actually render components today—but the *mental model* is that it does, and a forthcoming RFC will make that mental model reality.
+
+[^microsyntax]: made that much more bespoke since [RFC #0585](https://emberjs.github.io/rfcs/0585-improved-ember-registry-apis.html) is accepted but not yet implemented
+
+
+### The solution
+
+To address these problems, the Ember community [proposed primitives][rfc-0454] which unlocked experimentation in this space and [defined the semantics of “strict” templates which use those primitives][rfc-0496]. Now, with a history of having done that experimentation—with [GlimmerX][glimmerx] and [ember-template-imports]—and having had *many* discussions about the tradeoffs over the years, it’s time to ship a proposal which resolves these questions: <!-- TODO: name the proposal -->.
+
+[rfc-0454]: https://github.com/emberjs/rfcs/pull/454
+[rfc-0496]: https://emberjs.github.io/rfcs/0496-handlebars-strict-mode.html
+[glimmerx]: https://glimmerjs.github.io/glimmer-experimental/
+
+In this new world, templates are authored in JavaScript files with a `<template>` tag. Templates defined this way have normal Glimmer template semantics, but instead of using a runtime resolution strategy, they have access to values in JavaScript scope, which means they can just use normal JavaScript imports. What's more, they can define other local components, helpers, or modifiers and export them or not as makes sense. They can do the same kind of extraction refactors they do with JavaScript or CSS. And other tools from the JavaScript ecosystem “just work”—from custom CSS tooling to GraphQL queries authored with [Apollo Client’s `gql` template strings][gql] and anything else the ecosystem comes up with.
+
+[gql]: https://www.apollographql.com/docs/react/data/queries/
+
+At the same time, since the body of a template defined with a `<template>` tag has all the same rules as Glimmer templates do today, this new authoring format keeps all the goodness of today’s clear separation of concerns between HTML and JavaScript and CSS. That means it continues to empower developers who are HTML and CSS experts and reach for JavaScript only secondarily. Indeed, the design goes out of its way to make HTML/Handlebars-only files feel like first-class citizens.
+
+Finally, it completely unifies the story between app and test code: in this new world, introducing a test-only component is as simple as introducing any other component in the same file as an existing component.
+
+This resolves every single one of the problems outlined above, and introduces new capabilities to boot!
 
 
 ### Constraints
@@ -174,7 +252,6 @@ Introduce a new high-level syntax, the `<template>` tag, which is syntactical su
 For a discussion of the `setComponentTemplate` and `templateOnlyComponent` primitives, see [RFC #0481][rfc-0481]; for discussion of the `precompileTemplate` primitive, see [RFC #0496][rfc-0496]. This discussion will *assume* rather than *define* those.
 
 [rfc-0481]: https://emberjs.github.io/rfcs/0481-component-templates-co-location.html
-[rfc-0496]: https://emberjs.github.io/rfcs/0496-handlebars-strict-mode.html
 
 
 ### Compilation
@@ -906,7 +983,7 @@ This is very attractive in some ways, but it comes with three downsides:
 - Perhaps most critically: as with the imports-only design, **the SFC design requires that we continue to support a completely separate design for testing than for app code** (indeed: it basically requires that we fully implement the `hbs` or `<template>` designs for those!)
 
 
-### Template literals
+### Template literals (`hbs`)
 
 The “template literals” design takes as its starting point the `hbs` template strings Ember has used for testing since the 1.x era. It is relatively similar to the `<template>` design, in that it uses JavaScript/TypeScript files as the basis for its design. Unlike `template`, it uses an explicit `hbs` import, presumably from `@glimmer/component`. For components with a backing class, the template is defined as a static class field.
 
@@ -986,10 +1063,7 @@ This has a couple significant advantages:
 
 - Unlike with the `<template>` proposal, Prettier can *parse* a file using `hbs` string with no further changes. (It cannot *format* them, however: it treats the contents of the string opaquely.)
 - It feels familiar to developers in the Ember ecosystem used to using `hbs` strings with their tests.
-- The broader JavaScript ecosystem makes use of a number of template string syntaxes, e.g. with `css` from [Emotion][emotion] or `graphql` from [TODO][graphql].
-
-[emotion]: TODO
-[graphql]: graphql
+- The broader JavaScript ecosystem makes use of a number of template string syntaxes, e.g. with `css` from [Emotion][emotion] or [`gql` from Apollo][gql].
 
 However, it also has some significant disadvantages:
 

From 5c007bb6c76edb936772815ed3e053a9c0c5afc5 Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Wed, 1 Dec 2021 11:03:18 -0700
Subject: [PATCH 24/53] Improve the summary and code samples

- swap order of example code vs benefits list
- add note about assuming default modifier manager, and update the code
  to use that capability throughout
---
 text/0000-template-imports.md | 45 ++++++++++++++++-------------------
 1 file changed, 21 insertions(+), 24 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 3a10b0ee2c..b6f6cdded5 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -26,14 +26,25 @@ RFC PR: Fill this in with the URL for the Proposal RFC PR
 
 ## Summary
 
-Adopt `<template>` as the standard authoring format for components, in files with the extensions `.gjs` and `.gts` for JavaScript and TypeScript respectively, enabling strict mode.
+Adopt `<template>` as the standard authoring format for components, in files with the extensions `.gjs` and `.gts` for JavaScript and TypeScript respectively, enabling [strict mode][rfc-0496], addressing a number of pain points in today’s component authoring world, and providing a number of new capabilities to Ember and Glimmer users:
+
+- accessing local JavaScript values with no ceremony and no backing class, enabling much easier use of existing JavaScript ecosystem tools, including especially styling libraries—native CSS modules will “just work,” for example
+
+- authoring more than one component in a single file, where colocation makes sense—and thereby providing more control over a component’s public API
+
+- likewise authoring locally-scoped helpers, modifiers, and other JavaScript functionality
+
+It offers these new capabilities while not only maintaining but *improving* Ember’s long-standing commitment to integrated testing, in that it allows app and test code to share a single authoring paradigm—substantially simplifying our teaching story. Similarly, it preserves Ember’s long-standing commitment to treating JavaScript and HTML (and CSS!) as distinctive concerns which, however closely related, are not the *same*.
 
 <details><summary>Full-fledged example showing how this might work in practice</summary>
 
+(Note that for this and all following examples, I assume [RFC #0757: Default Modifier Manager][rfc-0757] for simplicity, but it does not meaningfully change *this* proposal.)
+
+[rfc-0757]: https://github.com/emberjs/rfcs/pull/757
+
 ```js
 import Component from '@glimmer/component';
 import { tracked } from '@glimmer/tracking';
-import { modifier } from '@glimmer/modifier';
 
 const Greet = <template>
   <p>Hello, {{@name}}!</p>
@@ -66,9 +77,9 @@ class SetUsername extends Component {
   </template>
 }
 
-const replaceLocation = modifier((el, _ , { with: newUrl }) => {
+function replaceLocation(el, { with: newUrl }) {
   el.contentWindow.location.replace(newUrl);
-});
+}
 
 export default class GenerateAvatar extends Component {
   @tracked name = "";
@@ -100,14 +111,6 @@ export default class GenerateAvatar extends Component {
 
 </details>
 
-The new format provides a number of new capabilities to Ember and Glimmer users:
-
-- to access local JavaScript values with no ceremony and no backing class, enabling much easier use of existing JavaScript ecosystem tools, including especially styling libraries—native CSS modules will “just work,” for example
-- to author more than one component in a single file, where colocation makes sense—and thereby providing more control over a component’s public API
-- to likewise author locally-scoped helpers, modifiers, and other JavaScript functionality
-
-It offers these new capabilities while not only maintaining but *improving* Ember’s long-standing commitment to integrated testing, in that it allows app and test code to share a single authoring paradigm—substantially simplifying our teaching story. Similarly, it preserves Ember’s long-standing commitment to treating JavaScript and HTML (and CSS!) as distinctive concerns which, however closely related, are not the *same*.
-
 
 ### Contents <!-- omit in toc -->
 
@@ -258,8 +261,6 @@ For a discussion of the `setComponentTemplate` and `templateOnlyComponent` primi
 
 The value produced by authoring a `<template>` is a *JavaScript value*, and accordingly may be exported, bound to other values, passed as an argument to a function or set as a value on a class, etc. However, the value may not be treated as *dynamic*: the rendering engine will evaluate the value exactly and only once. Therefore, it is nonsensical to use it with a `let` binding or to attempt to create new `<template>`s dynamically from the body of a function. (A function may of course return different components based on its arguments, etc.; it simply may not *construct* new component templates dynamically.)
 
-<!-- TODO: validate import locations for `on`, `eq`, `gt` (see https://github.com/emberjs/rfcs/pull/560) -->
-
 
 #### Bound to a name
 
@@ -797,7 +798,6 @@ The imports-only design borrows the idea of “front-matter” from many text au
 - `replace-location.js`:
 
     ```js
-    import { modifier } from '@glimmer/modifier';
 
     export default modifier((el, _ , { with: newUrl }) => {
         el.contentWindow.location.replace(newUrl);
@@ -833,6 +833,7 @@ The imports-only design borrows the idea of “front-matter” from many text au
     ---
     import Greet from './greet';
     import SetUsername from './set-username';
+    import replaceLocation from '../modifiers/replace-location';
     ---
 
     <Greet @name={{this.name}} />
@@ -937,15 +938,12 @@ Single File Components (hereafter SFCs) start with an HTML baseline and layer on
     <script>
       import Component from '@glimmer/component';
       import { tracked } from '@glimmer/tracking';
-      import { modifier } from '@glimmer/modifier';
       import Greet from './greet.glimmer';
       import SetUsername from './set-username.glimmer';
 
-      const replaceLocation = modifier(
-        (el, _ , { with: newUrl }) => {
-          el.contentWindow.location.replace(newUrl);
-        }
-      );
+      function replaceLocation(el, { with: newUrl }) {
+        el.contentWindow.location.replace(newUrl);
+      }
 
       export default class GenerateAvatar extends Component {
         @tracked name = "";
@@ -992,7 +990,6 @@ The “template literals” design takes as its starting point the `hbs` templat
 ```js
 import Component, { hbs } from '@glimmer/component';
 import { tracked } from '@glimmer/tracking';
-import { modifier } from '@glimmer/modifier';
 
 const Greet = hbs`
   <p>Hello, {{@name}}!</p>
@@ -1025,9 +1022,9 @@ class SetUsername extends Component {
   `;
 }
 
-const replaceLocation = modifier((el, _ , { with: newUrl }) => {
+function replaceLocation(el, { with: newUrl }) {
   el.contentWindow.location.replace(newUrl);
-});
+}
 
 export default class GenerateAvatar extends Component {
   @tracked name = "";

From aa8549a40efa17716ab8aaa7e02d02aad387f8c0 Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Thu, 2 Dec 2021 08:40:45 -0700
Subject: [PATCH 25/53] Tweak summary of Motivation

---
 text/0000-template-imports.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index b6f6cdded5..9186ebf804 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -224,9 +224,9 @@ In this new world, templates are authored in JavaScript files with a `<template>
 
 At the same time, since the body of a template defined with a `<template>` tag has all the same rules as Glimmer templates do today, this new authoring format keeps all the goodness of today’s clear separation of concerns between HTML and JavaScript and CSS. That means it continues to empower developers who are HTML and CSS experts and reach for JavaScript only secondarily. Indeed, the design goes out of its way to make HTML/Handlebars-only files feel like first-class citizens.
 
-Finally, it completely unifies the story between app and test code: in this new world, introducing a test-only component is as simple as introducing any other component in the same file as an existing component.
+Finally, introducing `<template>` completely unifies the story between app and test code: in this new world, introducing a test-only component is as simple as introducing any other component in the same file as an existing component.
 
-This resolves every single one of the problems outlined above, and introduces new capabilities to boot!
+In sum, `<template>` resolves each problem outlined above, and introduces new capabilities to boot.
 
 
 ### Constraints

From b05c383f57b59592e82572499b253dc593bb0619 Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Thu, 2 Dec 2021 08:42:14 -0700
Subject: [PATCH 26/53] Tweak 'Motivation: Constraints' verbiage

---
 text/0000-template-imports.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 9186ebf804..2054928d13 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -231,7 +231,7 @@ In sum, `<template>` resolves each problem outlined above, and introduces new ca
 
 ### Constraints
 
-This RFC proposes a design which addresses this set of motivations, but it does not do so in a vacuum; I take the following constraints as guiding the design decision (and the ordering here is purposeful—items earlier in the list I judge to be more important than items later in the list):
+There are a number of solutions which could address these needs and add these capabilities. This RFC proposes `<template>` out of all the possible options because I take the following constraints as guiding the design decision (and the ordering here is purposeful—items earlier in the list I judge to be more important than items later in the list):
 
 1. Our choice of design **must not** regress our ability to write tests, and if it is possible to *improve* our testing story, we should take the opportunity to do so.
 

From 367a526be43bd7a541cb88dec1f13ef22e4f59bb Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Thu, 2 Dec 2021 08:47:43 -0700
Subject: [PATCH 27/53] Misc. prep and cleanup

---
 text/0000-template-imports.md | 38 ++++++++++++-----------------------
 1 file changed, 13 insertions(+), 25 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 2054928d13..1141e4bba9 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -264,8 +264,6 @@ The value produced by authoring a `<template>` is a *JavaScript value*, and acco
 
 #### Bound to a name
 
-<!-- TODO: validate correct compile output for `scope` given deprecation -->
-
 Given a `<template>` tag assigned to a name in JavaScript scope:
 
 ```js
@@ -290,7 +288,7 @@ const Greet = setComponentTemplate(
 );
 ```
 
-If the `<template>` references values in scope, they will be included in an object with a `scope` argument (matching the current implementation of the underlying primitives). Thus, this definition:
+If the `<template>` references values in scope, they will be included in an object with a `scope` argument (matching the current implementation of the underlying primitives). Thus, this definition—
 
 ```js
 import { precompileTemplate } from '@ember/template-compilation';
@@ -313,6 +311,8 @@ const Greet = <template>
 </template>
 ```
 
+—compiles to this output:
+
 ```js
 import { precompileTemplate } from '@ember/template-compilation';
 import { setComponentTemplate } from '@ember/component';
@@ -347,8 +347,8 @@ const Greet = setComponentTemplate(
 
 2. Relatedly, in normal app code, authors should not introduce component definitions `<template>`s other than at the top level of the code. It is technically possible to create components from a function, like so:
 
-    ```ts
-    function conditionalComponent(predicate: boolean) {
+    ```js
+    function conditionalComponent(predicate) {
       if (predicate) {
         return <template><p>Cool</p></template>
       } else {
@@ -359,8 +359,8 @@ const Greet = setComponentTemplate(
 
     However, doing so will have unexpected costs at runtime. It’s worth remembering what the resulting output is:
 
-    ```ts
-    function conditionalComponent(predicate: boolean) {
+    ```js
+    function conditionalComponent(predicate) {
       if (predicate) {
         return setComponentTemplate(
           precompileTemplate(`<p>Cool</p>`),
@@ -537,42 +537,30 @@ A user wishing to make these available to loose mode could introduce two new mod
 
 Then a loose-mode component could invoke them like `<NamedOnly::Greet @name="Chris">` and `<NamedOnly::Farewell @name="Krycho" />`. Note that this pattern is not at all *necessary* for migration, but may be useful.
 
-<!--
-
-> This is the bulk of the RFC.
-
-> Explain the design in enough detail for somebody
-familiar with the framework to understand, and for somebody familiar with the
-implementation to implement. This should get into specifics and corner-cases,
-and include examples of how the feature is used. Any new terminology should be
-defined here.
-
--->
-
 
 ### The “prelude”
 
-<!-- TODO -->
+<!-- TODO: prelude -->
 
 
 ### Tooling
 
-<!-- TODO -->
+<!-- TODO: tooling -->
 
 
-#### Generators
+#### Blueprints
 
-<!-- TODO -->
+<!-- TODO: blueprints -->
 
 
 #### Linting and formatting
 
-<!-- TODO -->
+<!-- TODO: linting and formatting -->
 
 
 #### Language server support
 
-<!-- TODO -->
+<!-- TODO: LSP -->
 
 
 ## How we teach this

From 4f15b82fdb1c3e4a831ef9485a591d61931d7f14 Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Thu, 2 Dec 2021 08:58:52 -0700
Subject: [PATCH 28/53] Note on private class fields

---
 text/0000-template-imports.md | 22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 1141e4bba9..899395869d 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -504,6 +504,26 @@ setComponentTemplate(
 )
 ```
 
+##### Private class fields
+
+In the present design of the template compilation primitives, a template cannot access private fields from the backing class. That is, the following *will not work*:
+
+```js
+import Component from '@glimmer/component';
+
+class Example extends Component {
+  #aField = true;
+
+  <template>
+    <p>The value of the field is: {{this.#aField}}</p>
+  </template>
+}
+```
+
+That is because the compilation output does *not* embed the template in the class' body in any way, but instead associates it *externally* to the class—but private class fields are only accessible within the body of the class itself, per the ECMAScript spec. While we could invest time to change the implementation to avoid this, it is not generally a problem. Because we do not interact with component class instances directly—only through the template layer—we do not actually *need* private class fields.
+
+Even, this is a real gap, which we could address in a future RFC. Notably, it is *not specific to this proposal*, applies to *all* proposals built on the current primitives.
+
 
 ### Interop
 
@@ -619,7 +639,7 @@ There is presently no API for `<template>` itself, as proposed in this RFC, thou
 
 The type of a component is not affected by this proposal. However, it is worth seeing *how* a component defined using `<template>` works with types, at least for the purpose of documentation (and for integration with the current DefinitelyTyped definitions).
 
-- For a class-backed component, there is no change when using `<template>`. As described above, tools like Glint will need to provide an interpretation of `<template>` which captures, minimally, the arguments to the function.
+- For a class-backed component, there is no change to the *types* of the component when using `<template>`. As described above in the discussion of language servers, tools like Glint will need to provide an interpretation of the body of a `<template>` which correctly understands the scope in which it is embedded, i.e. correctly providing `this` to it.
 
 - For a template-only component, defining the type will require a type import to represent that there is a component with no `this` context, etc. Glint already supplies such a type, albeit with the types updated for [RFC #0748][rfc-0748]. For today’s purposes, we can simply augment the [existing types on DefinitelyTyped][DT-toc] with `Args`.
 

From b22dbbdb08558e1a8b4dab2bb682319e9fc1bb4f Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Thu, 2 Dec 2021 09:18:18 -0700
Subject: [PATCH 29/53] Discuss <template> cost both technically and
 pedagogicaly

---
 text/0000-template-imports.md | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 899395869d..7211eb0319 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -345,7 +345,7 @@ const Greet = setComponentTemplate(
 
 1. Users *should* always and only use `const` bindings for the result of such a template, because Ember will never reevaluate if the name is re-bound later. (Even if we wanted to do that, it would be difficult at best: nothing would notify Ember that it *should* re-evaluate that value!) We should introduce a lint rule forbidding assignment of a `<template>` to a `let` binding to prevent that confusion.
 
-2. Relatedly, in normal app code, authors should not introduce component definitions `<template>`s other than at the top level of the code. It is technically possible to create components from a function, like so:
+2. Relatedly, in normal app code, authors should not introduce component definitions `<template>`s in contexts where they will be “re-executed,” e.g. in a function body. It is technically possible to create components from a function, like so:
 
     ```js
     function conditionalComponent(predicate) {
@@ -375,15 +375,15 @@ const Greet = setComponentTemplate(
     }
     ```
 
-    The problem here is that this requires re-running both the template precompilation step *and* the creation of the template-only empty backing instance (which has `null` for `this`, etc.). Re-doing the template precompilation <!-- TODO: doesn't even work, right? -->
+    The problem here is that this requires re-running both the template precompilation step *and* the creation of the template-only empty backing instance which has `null` for `this`. Re-doing the template precompilation will *work*, but it is expensive and slow.
 
     In this scenario, users can accomplish the same thing by manually hoisting the component definitions to module scope:
 
-    ```ts
+    ```js
     const Cool = <template><p>Cool</p></template>;
     const Lame = <template><p>Lame</p></template>;
 
-    function conditionalComponent(predicate: boolean) {
+    function conditionalComponent(predicate) {
       if (predicate) {
         return Cool;
       } else {
@@ -392,9 +392,9 @@ const Greet = setComponentTemplate(
     }
     ```
 
-    (This is similar to the concern around other costly operations needlessly happening in a function body repeatedly.)
+    (Notice that this is no different than any other concern around other costly operations needlessly happening in a function body repeatedly.)
 
-    The sole exception here is that it makes perfectly good sense to define components, whether class-backed or not, in the context of *test modules*, where the context only exists for as long as the test itself and so the concerns are no longer an issue.
+    See further discussion below under [**How We Teach This**](#how-we-teach-this).
 
 
 #### Standalone
@@ -617,6 +617,11 @@ Once this is implemented and tooling is sufficiently stable, we will update the
 
     3. When refactoring to use a getter for `src`, use the value as `${TOKEN}`. Note explicitly how there is a symmetry between JS and templates: you can use whichever approach is clearer for a given context.
 
+In the course of the discussion of components, we should call out (e.g. with a “Zoey says” block) that users should treat `<template>` the same way they treat a costly function which produces a result for the life of the whole app, and should therefore avoidng using `<template>` in function bodies rather than hoisting them, etc. This cannot be a hard and fast rule about where `<template>` definitions live, because there are plenty of ways to do it safely, and what’s more we *need* to do it in test modules.
+
+The point is simply to align people’s mental model for `<template>` with *other* costly operations, since these concerns are not specific to component creation.
+
+
 <!-- TODO: the rest of the pedagogy updates -->
 
 [^route-template]: This is complicated by the need to introduce route templates as well as component templates. The text here assumes that we will, in parallel with this work, resolve the design questions addressed by [RFC #0731][rfc-0731] in something like the design proposed there. Accordingly, it also assumes we will update the generators and the relevant text accordingly. Fundamentally, we *should not* update the guides until we have a resolution for that design space, so they can be updated in a coherent way.

From 5c5708983534da130cebbafc7757b0294a125444 Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Thu, 2 Dec 2021 17:29:16 -0700
Subject: [PATCH 30/53] Continue expanding the How We Teach This section

---
 text/0000-template-imports.md | 70 ++++++++++++++++++++++++++++++++---
 1 file changed, 64 insertions(+), 6 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 7211eb0319..552b631069 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -589,10 +589,15 @@ We describe a `<template>` as representing the *template* for a *component*. Whe
 
 This explanatory model provides a helpful opportunity, when first introducing the idea of a backing class, to link to deeper-dive materials which let people who want to understand more deeply. In particular, it allows us a place to point out that mechanically, there *is* in fact always an associated component instance (generated via `templateOnlyComponent()`), but it’s just a way for this `<template>` to be hooked into the broader system, rather than a home for state.
 
+**Note:** This is complicated by the need to introduce route templates as well as component templates. The text here assumes that we will, in parallel with this work, resolve the design questions addressed by [RFC #0731][rfc-0731] in something like the design proposed there. Accordingly, it also assumes we will update the generators and the relevant text accordingly. Fundamentally, we *should not* update the guides until we have a resolution for that design space, so they can be updated in a coherent way.
+
 
 ### Guides
 
-Once this is implemented and tooling is sufficiently stable, we will update the guides with changes along the following lines:[^route-template]
+Once `<template>` is implemented and tooling is sufficiently stable, we will update the guides with changes along the following lines:
+
+
+#### Tutorial
 
 - Update the output from generators, including correct new file extensions.
 
@@ -617,18 +622,71 @@ Once this is implemented and tooling is sufficiently stable, we will update the
 
     3. When refactoring to use a getter for `src`, use the value as `${TOKEN}`. Note explicitly how there is a symmetry between JS and templates: you can use whichever approach is clearer for a given context.
 
-In the course of the discussion of components, we should call out (e.g. with a “Zoey says” block) that users should treat `<template>` the same way they treat a costly function which produces a result for the life of the whole app, and should therefore avoidng using `<template>` in function bodies rather than hoisting them, etc. This cannot be a hard and fast rule about where `<template>` definitions live, because there are plenty of ways to do it safely, and what’s more we *need* to do it in test modules.
+
+<!-- TODO: the rest of the tutorial updates -->
+
+[^testing-rfc]: Here I assume a forthcoming RFC which will allow `render` to work not only with templates (the _status quo_) but also with components. This will be an independent change which helps eliminate a number of quirks in the testing infrastructure today, but complements *this* RFC by allowing local definition of tests.
+
+[^namespace-deprecation]: This does mean that the namespace sigil is a candidate for later deprecation, since it will be entirely redundant once the ecosystem moves fully to strict mode and template imports. I think that question is best left to a hypothetical RFC deprecating loose mode.
+
+
+#### Core Concepts: Components
+
+This entire section will also need to be substantially reworked. Once again, I am here summarizing the changes rather than trying to rewrite the guide in place. Each section represents a page to be changed; if a section is not mentioned, it needs few or no changes.
+
+At some point in the course of this discussion, we should call out (e.g. with a “Zoey says” block) that users should treat `<template>` the same way they treat a costly function which produces a result for the life of the whole app, and should therefore avoidng using `<template>` in function bodies rather than hoisting them, etc. This cannot be a hard and fast rule about where `<template>` definitions live, because there are plenty of ways to do it safely, and what’s more we *need* to do it in test modules.
 
 The point is simply to align people’s mental model for `<template>` with *other* costly operations, since these concerns are not specific to component creation.
 
 
-<!-- TODO: the rest of the pedagogy updates -->
+##### Templates are HTML
 
-[^route-template]: This is complicated by the need to introduce route templates as well as component templates. The text here assumes that we will, in parallel with this work, resolve the design questions addressed by [RFC #0731][rfc-0731] in something like the design proposed there. Accordingly, it also assumes we will update the generators and the relevant text accordingly. Fundamentally, we *should not* update the guides until we have a resolution for that design space, so they can be updated in a coherent way.
+The point of this will remain the same—modulo changes for route templates; presumably we will have a top-level `<template>`, but do not need to explain that it is a component until the next page. We'll be using `.gjs` instead of `.hbs`.
 
-[^testing-rfc]: Here I assume a forthcoming RFC which will allow `render` to work not only with templates (the _status quo_) but also with components. This will be an independent change which helps eliminate a number of quirks in the testing infrastructure today, but complements *this* RFC by allowing local definition of tests.
 
-[^namespace-deprecation]: This does mean that the namespace sigil is a candidate for later deprecation, since it will be entirely redundant once the ecosystem moves fully to strict mode and template imports. I think that question is best left to a hypothetical RFC deprecating loose mode.
+##### Introducing Components
+
+Unsurprisingly, this is the section which will see the most sweeping changes.
+
+- Here, we can note that we’ve already seen our first component: the application template *was* a component.
+
+- We can continue to breaking out into separate files.
+
+- Then, back in the application file, we can show using `import` to refer to it.
+
+- As in the tutorial, the discussion around naming will need to be updated to indicate that we capitalize by *convention*: it will no longer be a hard requirement. Likewise, the “Zoey says...” will go away because we will no longer be using resolution to get imports.
+
+- After showing the other extraction-style refactors, we can show how components which don't need to be exported can just be defined locally with a `const` declaration. This will provide the first hook for defininig helpers etc. locally in following sections.
+
+- We will entirely drop the folder namespace syntax (`::`) discussion, in favor of showing how normal JS imports handle that concern—including showing how the combination of named exports and namespace-style imports handle those. (This will necessitate reworking the example, which currently uses that namespacing as a means of scoping.)
+
+
+##### Helper functions
+
+Instead of introducing `app/helpers` and the resolution-based lookup, we can introduce the helper as a local function in the component which needs it. This will be the first place where this guide explicitly calls out that components have access to values in their surrounding scope, just like normal JavaScript. This will be a good point to call out the power and versatility this affords.
+
+Additionally, instead of the *next* section being the place where we first identify that JS is needed to make our UI dynamic, we will address that here. The next section can then build on that by showing how classes make certain patterns *easier*.
+
+
+##### Component State and Actions
+
+Here, the content will need to shift in two ways:
+
+First, the motivation for introducing a backing class shifts slightly: we have the ability to have state at the module level already, including via class-backed helpers. What we need is a way to have state that is for *just one component*. A class is JavaScript’s first-class way of doing that, so we have a version which supports it.
+
+Second, having made the motivation clear, we can show the `<template>` in the body of the class and explain that it is exactly the same as a standalone template component, except that it now has access to the backing class for local state, "actions", etc.
+
+
+##### Looping Through Lists
+
+This section will just need to update each of the component examples it provides to use the new syntax with a wrapper `<template>`, and in the case where the component is class-backed, move it into the backing class body.
+
+
+##### Template Lifecycle, DOM, and Modifiers
+
+Once again, many of the changes here will be mechanical: just using the new syntax. However, this also provides another opportunity to discuss (and demonstrate) the value of local-only vs. exported functionality. Both of the main custom modifier examples here currently show highly-reusable examples of modifiers which *should* be exported and should indeed probably live in their own modules. Accordingly, we might find an example which shows the value of having a locally-scoped modifier—e.g. something which manages the details of an `iframe`.
+
+<!-- TODO: the rest of the Core Concepts updates -->
 
 
 ### API Docs

From 67ef8bcc4f5319d81c1e0954afe9cbe098c844ca Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Thu, 2 Dec 2021 18:21:56 -0700
Subject: [PATCH 31/53] Finish up How We Teach This: Guides: Core Concepts

---
 text/0000-template-imports.md | 16 ++--------------
 1 file changed, 2 insertions(+), 14 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 552b631069..f83327ab11 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -632,18 +632,13 @@ Once `<template>` is implemented and tooling is sufficiently stable, we will upd
 
 #### Core Concepts: Components
 
-This entire section will also need to be substantially reworked. Once again, I am here summarizing the changes rather than trying to rewrite the guide in place. Each section represents a page to be changed; if a section is not mentioned, it needs few or no changes.
+This entire section will also need to be substantially reworked. Once again, I am here summarizing the changes rather than trying to rewrite the guide in place. Each section represents a page to be changed; if a section is not mentioned, it needs no substantive changes—likely only switching over to using the `<template>` wrapper.
 
 At some point in the course of this discussion, we should call out (e.g. with a “Zoey says” block) that users should treat `<template>` the same way they treat a costly function which produces a result for the life of the whole app, and should therefore avoidng using `<template>` in function bodies rather than hoisting them, etc. This cannot be a hard and fast rule about where `<template>` definitions live, because there are plenty of ways to do it safely, and what’s more we *need* to do it in test modules.
 
 The point is simply to align people’s mental model for `<template>` with *other* costly operations, since these concerns are not specific to component creation.
 
 
-##### Templates are HTML
-
-The point of this will remain the same—modulo changes for route templates; presumably we will have a top-level `<template>`, but do not need to explain that it is a component until the next page. We'll be using `.gjs` instead of `.hbs`.
-
-
 ##### Introducing Components
 
 Unsurprisingly, this is the section which will see the most sweeping changes.
@@ -677,16 +672,9 @@ First, the motivation for introducing a backing class shifts slightly: we have t
 Second, having made the motivation clear, we can show the `<template>` in the body of the class and explain that it is exactly the same as a standalone template component, except that it now has access to the backing class for local state, "actions", etc.
 
 
-##### Looping Through Lists
-
-This section will just need to update each of the component examples it provides to use the new syntax with a wrapper `<template>`, and in the case where the component is class-backed, move it into the backing class body.
-
-
 ##### Template Lifecycle, DOM, and Modifiers
 
-Once again, many of the changes here will be mechanical: just using the new syntax. However, this also provides another opportunity to discuss (and demonstrate) the value of local-only vs. exported functionality. Both of the main custom modifier examples here currently show highly-reusable examples of modifiers which *should* be exported and should indeed probably live in their own modules. Accordingly, we might find an example which shows the value of having a locally-scoped modifier—e.g. something which manages the details of an `iframe`.
-
-<!-- TODO: the rest of the Core Concepts updates -->
+Once again, many of the changes here will be mechanical: just using the new syntax. However, this also provides another opportunity to discuss (and demonstrate) the value of local-only vs. exported functionality. Both of the main custom modifier examples here currently show highly-reusable examples of modifiers which *should* be exported and should indeed probably live in their own modules. Accordingly, we might find an example which shows the value of having a locally-scoped modifier—e.g. something which manages the private details of an `iframe`.
 
 
 ### API Docs

From 7517d7a2cb07711c1ba32eebe5f4befa68fd468b Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Thu, 2 Dec 2021 19:08:12 -0700
Subject: [PATCH 32/53] Finish first pass on most of How We Teach This

---
 text/0000-template-imports.md | 118 ++++++++++++++++++++++++++++------
 1 file changed, 98 insertions(+), 20 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index f83327ab11..7301abd9e6 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -183,10 +183,12 @@ In practice, this has a number of knock-on effects for Ember code:
 
 - Components tend to grow without bound, because there is no easy equivalent to the "extract method" or "extract into new class" refactorings (which we commonly use on the JS side) which does not (a) make the newly-extracted components available to the whole app and (b) require an entirely new file.
 
-- Users also often introduce classes with actions where a simple function-based helper would do, because that is the only way to provide a non-global function.
+- Users also often introduce classes with actions where a simple [function-based helper][rfc-0756] would do, because that is the only way to provide a non-global function.
 
 - It likewise incentivizes the use of the ember-render-modifiers with backing classes, rather than custom modifiers, because the behavior can then be scoped to that module—whereas, again, a custom modifier would be in global scope. This in turn makes it easy for users to miss the helpful separation of concerns which custom modifiers enable.
 
+[rfc-0756]: https://github.com/emberjs/rfcs/pull/756
+
 Over time, these all lead to a proliferation of backing classes which are only present to work around the fact that we have no *other* way to provide non-global scope for our components. These classes in turn tend to act as “state attractors,” leading to an unnecessary proliferation of state throughout an app or addon.
 
 [scopes]: https://docs.npmjs.com/cli/v8/using-npm/scope
@@ -205,7 +207,7 @@ Finally, the authoring format for tests and the authoring format for app code to
 
 Additionally, introducing test-only components is quite painful, requiring use of the `this.owner.register()` functionality, and therefore requiring users to understand at least some of Ember’s custom runtime resolution (as well as learning a microsyntax for it[^microsyntax]). What's more, authoring a *template* for a test-only component is undocumented and is also entirely unlike the story for authoring templates for app components.
 
-[^testing-rfc]: The test helper `render()` also does not actually render components today—but the *mental model* is that it does, and a forthcoming RFC will make that mental model reality.
+[^testing-rfc]: The test helper `render()` also does not actually render components today—but the *mental model* is that it does. Here and below I assume a forthcoming RFC which will allow `render` to work not only with templates (the _status quo_) but also with components. This will be an independent change which helps eliminate a number of quirks in the testing infrastructure today as well as make it more TypeScript friendly, but it complements *this* RFC by allowing local definition of tests.
 
 [^microsyntax]: made that much more bespoke since [RFC #0585](https://emberjs.github.io/rfcs/0585-improved-ember-registry-apis.html) is accepted but not yet implemented
 
@@ -599,35 +601,111 @@ Once `<template>` is implemented and tooling is sufficiently stable, we will upd
 
 #### Tutorial
 
-- Update the output from generators, including correct new file extensions.
+One cross-cutting change here will be updating the output from generators, including correct new file extensions. The following discussion of the current sections of the guide *assumes* that change, and addresses concrete *pedagogical* changes we need to make. If a section is not included here, it (a) needs little or no other change beyond the minimum or (b) is dependent on the results of [RFC #0731][rfc-0731] to flesh out the details.
+
+
+##### Orientation
+
+Here we will need to update the prose to describe that `<template>` marks this as Ember/Glimmer’s special superset of HTML, with prose long the lines of:
+
+> Note that all you need to do to have a working Ember component is to wrap your HTML in `<template>`.
+
+
+##### Component Basics
+
+Introducing components will see a lot of changes, unsurprisingly:
+
+1. The introduction to components in updated guides will depend on the specific design choices we make in [RFC #0731][rfc-0731]. One possible approach here will be to note that we have already seen components in practice, if the decision in that space is that routes simply invoke a component template. Otherwise we may indicated that components are similar to route templates, but are self-contained.
+
+2. The use of `<CapitalizedComponents />` is no longer required, but remains a *helpful convention*.[^resolver-capitalized-components] If someone does `const foo = <template>...</template>`, they will be able to invoke that as `<foo />` elsewhere. The notes in this section as well as about `LinkTo` will need to be updated to describe it accordingly.
+
+3. After introducing `<Jumbo />` with updated use of a wrapping `<template>`, discuss *importing it* into the route (component) template which uses it. This is a good place to describe how `.gjs` can use JS features, and hint that we’ll see more of this later; it is also a good opportunity to note that we *could* have defined `<Jumbo />` locally, but that we moved it to a separate file because we’re sharing it across multiple different components.
+
+4. Our discussion of the testing will need to be updated to include importing the components under test, and to use `<template>` rather than `hbs` strings for the `render` calls.[^testing-rfc]
+
+[^resolver-capitalized-components]: Historically users *had* to use this convention, but only because that was the decision for how the resolver would work.
+
+
+##### More About Components
+
+We can simply *remove* the discussion of namespaced components, in favor of simply describing the use of normal JS imports to accomplish the same goal. However, here we can also note that JavaScript modules are a great way to organize groups of related components, and show how we might use namespace-style imports (`import * as Rental from '';` and then `<Rental.Image />` within a `<template>`) for this kind of organization.[^namespace-deprecation]
+
+[^namespace-deprecation]: Attentive readers will likely have noticed that this makes the namespace sigil a candidate for later deprecation, since it will be entirely redundant once the ecosystem moves fully to strict mode and template imports. However, that question is best left to a potential future RFC deprecating loose mode.
+
 
-- Update the introductory examples, which start with pure HTML, to add a wrapping `<template>` tag, and update the prose to describe that `<template>` marks this as Ember/Glimmer’s special superset of HTML. Note that all you need to do to have a working Ember component is to wrap your HTML in `<template>`.
+##### Interactive Components
 
-- Introducing components will see a lot of changes, unsurprisingly:
-    1. Note that we have already seen components in practice, because the templates we used with our routes were also components.
+The discussion of adding behavior to components will need to be updated to account for the design *and* the new possibilities in the space:
 
-    2. While we *conventionally* use `<CapitalizedComponents />` (and historically *had* to because that was the decision for how the resolver would work), that’s no longer a hard constraint. If someone does `const foo = <template>...</template>`, they will be able to invoke that as `<foo />` elsewhere. The notes in this section as well as about `LinkTo` will need to be updated to describe this as a helpful convention.
+1. Show that when we generate a class for an existing component, it  adds the `Component` import, creates a wrapping class, and moves the template into the body of that class. Here, teach the mental model that a `<template>` which is part of a class body has access to the instance properties on the backing class.
 
-    3. After introducing `<Jumbo />` with updated use of a wrapping `<template>`, discuss *importing it* into the route (component) template which uses it. This is a good place to describe how `.gjs` can use JS features, and hint that we’ll see more of this later; it is also a good opportunity to note that we *could* have defined `<Jumbo />` locally, but that we moved it to a separate file because we’re sharing it across multiple different components.
+2. When discussing use of values from `ENV`, instead of providing a getter on a backing class, start by creating a `TOKEN` constant in module scope, and show that it is available to access in the template. In the following section, which shows args being used in the template, simply use that `TOKEN` value in the template directly, `access_token={{TOKEN}}`.
 
-    4. Our discussion of the testing will need to be updated to include importing the components under test, and to use `<template>` rather than `hbs` strings for the `render` calls.[^testing-rfc]
+3. When refactoring to use a getter for `src`, use the value as `${TOKEN}`. Note explicitly how there is a symmetry between JS and templates: you can use whichever approach is clearer for a given context.
 
-    5. We can simply *remove* the discussion of namespaced components, in favor of simply describing the use of normal JS imports to accomplish the same goal. However, here we can also note that JavaScript modules are a great way to organize groups of related components, and show how we might use namespace-style imports (`import * as Rental from '';` and then `<Rental.Image />` within a `<template>`) for this kind of organization.[^namespace-deprecation]
 
-- The discussion of adding behavior to components will similarly need to be updated substantially:
+##### Reusable Components
 
-    1. Show that when we generate a class for an existing component, it  adds the `Component` import, creates a wrapping class, and moves the template into the body of that class. Here, teach the mental model that a `<template>` which is part of a class body has access to the instance properties on the backing class.
+This section provides is an opportunity to show how useful it can be to introduce local functions. The code samples here currently use a backing class, but they only do so to provide a home for getters which provide an encoded URI for the Mapbox token and derive the `src` from the arguments.
 
-    2. When discussing use of values from `ENV`, instead of providing a getter on a backing class, start by creating a `TOKEN` constant in module scope, and show that it is available to access in the template. In the following section, which shows args being used in the template, simply use that `TOKEN` value in the template directly, `access_token={{TOKEN}}`.
+(I will provide this example in full here in part because it shows powerfully the pedagogical value of this RFC!)
 
-    3. When refactoring to use a getter for `src`, use the value as `${TOKEN}`. Note explicitly how there is a symmetry between JS and templates: you can use whichever approach is clearer for a given context.
+The Mapbox token value is not reactive and therefore the computation has no reason to exist on a backing class *at all*. It is only there today because *without* <!-- TODO: name of this thing -->, it would otherwise require introducing the heavier notion of classic (pre-[RFC #0756][rfc-0756]) helpers. Now that we *have* `<template>`, it can simply become a constant value defined in local scope:
+
+```js
+import ENV from 'super-rentals/config/environment';
+
+const TOKEN = encodeURIComponent(ENV.MAPBOX_ACCESS_TOKEN)
+
+<template>
+  <div class="map">
+    <img
+      alt="Map image at coordinates {{@lat}},{{@lng}}"
+      ...attributes
+      src="https://api.mapbox.com/styles/v1/mapbox/streets-v11/static/{{@lng}},{{@lat}},{{@zoom}}/{{@width}}x{{@height}}@2x?access_token={{TOKEN}}"
+      width={{@width}} height={{@height}}
+    >
+  </div>
+</template>
+```
+
+Similarly, while `src` *is* computed from reactive data, there is once again no reason to compute it *in a class* if we are not going to use the class to store state. We can just write a local function and use it (and use that to note that we handle named arguments, too):
+
+```js
+import ENV from 'super-rentals/config/environment';
+
+const TOKEN = encodeURIComponent(ENV.MAPBOX_ACCESS_TOKEN)
+const MAPBOX_API = 'https://api.mapbox.com/styles/v1/mapbox/streets-v11/static';
+
+function source({ lng, lat, width, height, zoom }) {
+  let coordinates = `${lng},${lat},${zoom}`;
+  let dimensions = `${width}x${height}`;
+  let accessToken = `access_token=${TOKEN}`;
+
+  return `${MAPBOX_API}/${coordinates}/${dimensions}@2x?${accessToken}`;
+}
+
+<template>
+  <div class="map">
+    <img
+      alt="Map image at coordinates {{@lat}},{{@lng}}"
+      ...attributes
+      src={{source lng=@lng lat=@lat width=@width zoom=@zoom}}
+      width={{@width}} height={{@height}}
+    >
+  </div>
+</template>
+```
 
+Notice the results of this pedagogically:
 
-<!-- TODO: the rest of the tutorial updates -->
+- We have asked people to write *less code*.
+- The code they *do* write feels much more HTML-first.
+- For developers who have experience with other frameworks, this feels familiar, but with an Ember twist.
 
-[^testing-rfc]: Here I assume a forthcoming RFC which will allow `render` to work not only with templates (the _status quo_) but also with components. This will be an independent change which helps eliminate a number of quirks in the testing infrastructure today, but complements *this* RFC by allowing local definition of tests.
+At this point we could *additionally* show that we could introduce a backing class, and discuss the tradeoffs of introducing a class when we don't have any other local state. This also allows us to encourage just using functions unless you *do* need local state.
 
-[^namespace-deprecation]: This does mean that the namespace sigil is a candidate for later deprecation, since it will be entirely redundant once the ecosystem moves fully to strict mode and template imports. I think that question is best left to a hypothetical RFC deprecating loose mode.
+The section “Getting JavaScript Values into the Test Context” will also be possible to simplify: we will simply be able to introduce tracked state locally and update it directly, without special testing helpers. That will dramatically reduce the number of bespoke ideas we have to cover here. Much of the related work will be addressed in other RFCs, but being able to use the *same* primitives to bring values into scope for tests as we do in apps (immediately above!) will be very helpful in reducing what we have to cover in this section.
 
 
 #### Core Concepts: Components
@@ -679,9 +757,9 @@ Once again, many of the changes here will be mechanical: just using the new synt
 
 ### API Docs
 
-There is presently no API for `<template>` itself, as proposed in this RFC, though it leaves room for future RFCs, which could introduce e.g. a `<template lang="...">` variation to experiment with alternative template languages.[^emblem] Since there is no import location, we should cover it under the `@glimmer/component` module documentation. This will be a natural home for it, since we will always discuss it in the context of components.
+There is presently no API for `<template>` itself, as proposed in this RFC, though it leaves room for future RFCs to do so.[^emblem-etc] Since there is no import location, we should cover it under the `@glimmer/component` module documentation. This will be a natural home for it, since we will always discuss it in the context of components.
 
-[^emblem]: Historically, for example, many Ember apps used [Emblem][emblem]—and it is still possible to do so today! In the future, that could be supported with `<template lang="emblem">`. This would also be an easy home for experiments with a Svelte-like syntax.
+[^emblem-etc]: Historically, for example, many Ember apps used [Emblem][emblem] as a templating language—and it is still possible to do so today! In the future, that could be supported with `<template lang="emblem">`. This would also be an easy home for experiments with a Svelte-like syntax with e.g. `<template lang="svelte">` etc.
 
 [emblem]: http://emblemjs.com
 
@@ -739,7 +817,7 @@ The type of a component is not affected by this proposal. However, it is worth s
 
 ### Existing Ember users
 
-<!-- existing ember users introduction -->
+<!-- TODO: existing ember users introduction -->
 
 <!--
 

From 7ed8ea6eccbf8e8157bf99b280c0be4ac485d279 Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Thu, 2 Dec 2021 22:09:26 -0700
Subject: [PATCH 33/53] Finish an incomplete sentence

---
 text/0000-template-imports.md | 10 +---------
 1 file changed, 1 insertion(+), 9 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 7301abd9e6..c8b0d2bd48 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -862,15 +862,7 @@ on the impact of the API churn on existing apps, etc.
 
 ## Alternatives
 
-<!--
-
-> What other designs have been considered? What is the impact of not doing this?
-
-> This section could also include prior art, that is, how other frameworks in the same domain have solved this problem.
-
--->
-
-Within the major strokes of this design proposal, we could tweak the invocation for the template space to clarify that it does *not* overlap
+Within the major strokes of this design proposal, we could tweak the invocation for the template space to clarify that it does *not* overlap with the built-in `<template>` tag.
 
 - Use `<Template>` or `<Glimmer>` or similar. This would disambiguate it from the built-in `<template>`, but would introduce ambiguity with component invocation.
 - Use a new sigil—much as we use `<:main>...</:main>` for named blocks, we could do `<[template]>...</[template]>` or something similar. While verbose and not especially pretty, this avoids overloading the platform tag.

From da8c68a1895beab57ad5d4db6cc229bf734c232e Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Thu, 2 Dec 2021 22:11:10 -0700
Subject: [PATCH 34/53] A(nother) link for CSS Modules

---
 text/0000-template-imports.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index c8b0d2bd48..ff8ed884c4 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -28,7 +28,7 @@ RFC PR: Fill this in with the URL for the Proposal RFC PR
 
 Adopt `<template>` as the standard authoring format for components, in files with the extensions `.gjs` and `.gts` for JavaScript and TypeScript respectively, enabling [strict mode][rfc-0496], addressing a number of pain points in today’s component authoring world, and providing a number of new capabilities to Ember and Glimmer users:
 
-- accessing local JavaScript values with no ceremony and no backing class, enabling much easier use of existing JavaScript ecosystem tools, including especially styling libraries—native CSS modules will “just work,” for example
+- accessing local JavaScript values with no ceremony and no backing class, enabling much easier use of existing JavaScript ecosystem tools, including especially styling libraries—standard [CSS Modules][css-modules] will “just work,” for example
 
 - authoring more than one component in a single file, where colocation makes sense—and thereby providing more control over a component’s public API
 

From b028a07f232b9715ea83dfdc766c2eaa07040e2d Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Thu, 2 Dec 2021 22:17:20 -0700
Subject: [PATCH 35/53] More on pedagogy in guides

---
 text/0000-template-imports.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index ff8ed884c4..f1c0bde37a 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -699,8 +699,8 @@ function source({ lng, lat, width, height, zoom }) {
 
 Notice the results of this pedagogically:
 
-- We have asked people to write *less code*.
-- The code they *do* write feels much more HTML-first.
+- We have asked people to write *less code*: fewer imports, and less overall syntax.
+- The code they *do* write feels much more HTML-first. The template can stay almost exactly as it was, with no shift to a backing class.
 - For developers who have experience with other frameworks, this feels familiar, but with an Ember twist.
 
 At this point we could *additionally* show that we could introduce a backing class, and discuss the tradeoffs of introducing a class when we don't have any other local state. This also allows us to encourage just using functions unless you *do* need local state.
@@ -721,15 +721,15 @@ The point is simply to align people’s mental model for `<template>` with *othe
 
 Unsurprisingly, this is the section which will see the most sweeping changes.
 
-- Here, we can note that we’ve already seen our first component: the application template *was* a component.
+- As described in the tutorial, our introduction will depend on the design chosen for route templates. We will either note that we’ve already seen our first component, if the application template *was* a component, or note the similarities and differences between route templates and components otherwise.
 
-- We can continue to breaking out into separate files.
+- We can continue to show breaking the component out into separate files, with a top-level `<template>` (serving, so far implicitly, as a default export).
 
 - Then, back in the application file, we can show using `import` to refer to it.
 
 - As in the tutorial, the discussion around naming will need to be updated to indicate that we capitalize by *convention*: it will no longer be a hard requirement. Likewise, the “Zoey says...” will go away because we will no longer be using resolution to get imports.
 
-- After showing the other extraction-style refactors, we can show how components which don't need to be exported can just be defined locally with a `const` declaration. This will provide the first hook for defininig helpers etc. locally in following sections.
+- After showing the other extraction-style refactors, we can show how components which don't need to be exported can just be defined locally with a `const` declaration, and explain that the standalone `<template>` tag is sugar for a default export. This will also provide the first hook for defininig helpers etc. locally in following sections.
 
 - We will entirely drop the folder namespace syntax (`::`) discussion, in favor of showing how normal JS imports handle that concern—including showing how the combination of named exports and namespace-style imports handle those. (This will necessitate reworking the example, which currently uses that namespacing as a means of scoping.)
 

From 45cc887ff9a3be418841591306a7da87ab9d0fb3 Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Thu, 2 Dec 2021 22:18:02 -0700
Subject: [PATCH 36/53] Formatting for Component State and Actions

---
 text/0000-template-imports.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index f1c0bde37a..8e209dadc0 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -745,9 +745,9 @@ Additionally, instead of the *next* section being the place where we first ident
 
 Here, the content will need to shift in two ways:
 
-First, the motivation for introducing a backing class shifts slightly: we have the ability to have state at the module level already, including via class-backed helpers. What we need is a way to have state that is for *just one component*. A class is JavaScript’s first-class way of doing that, so we have a version which supports it.
+1. The motivation for introducing a backing class shifts slightly: we have the ability to have state at the module level already, including via class-backed helpers. What we need is a way to have state that is for *just one component*. A class is JavaScript’s first-class way of doing that, so we have a version which supports it.
 
-Second, having made the motivation clear, we can show the `<template>` in the body of the class and explain that it is exactly the same as a standalone template component, except that it now has access to the backing class for local state, "actions", etc.
+2. Having made the motivation clear, we can show the `<template>` in the body of the class and explain that it is exactly the same as a standalone template component, except that it now has access to the backing class for local state, "actions", etc.
 
 
 ##### Template Lifecycle, DOM, and Modifiers

From ccf839074234428d2c2acf43258af09fcfb549ea Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Thu, 2 Dec 2021 22:20:32 -0700
Subject: [PATCH 37/53] More on alternatives

---
 text/0000-template-imports.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 8e209dadc0..05944546e3 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -983,7 +983,7 @@ The imports-only design borrows the idea of “front-matter” from many text au
 
 The major upside to this is that it is the smallest possible delta over today’s implementation. However, it has a number of significant downsides:
 
-- It does not allow locally-scoped JavaScript values (including helpers and modifiers and also ecosystem tooling like GraphQL values, CSS-in-JS tooling, etc.) even when that is a perfectly reasonable design decision.
+- As with today’s _status quo_, it does not allow locally-scoped JavaScript values (including helpers and modifiers but also ecosystem tooling like GraphQL values, CSS-in-JS tooling, etc.) even when that is a perfectly reasonable design decision.
 
 - It substantially complicates the implementation of tooling for language servers, which have to do extra work to detect the presence of a backing class and “stitch together” the backing class and the template if a backing class does exist.
 
@@ -1006,7 +1006,7 @@ The major upside to this is that it is the smallest possible delta over today’
     {{/if}}
     ```
 
-    While a colocated template (the default since Octane) is part of the same module as the backing class, this does technically work![^recursive-module] However, it’s the kind of extremely surprising and weird thing we would generally try to avoid pedagogically—it requires us to explain that these two separate files (`.js` and `.hbs`) are combined into a single module at build time.
+    While a colocated template (the default since Octane) is part of the same module as the backing class, this does technically work![^recursive-module] However, it’s the kind of extremely surprising and weird thing we would generally try to avoid pedagogically—it requires us to explain that these two separate files (`.js` and `.hbs`) are combined into a single module at build time… and that we have nonetheless kept them separate at authoring time, requiring these kinds of workarounds.[^recursive-import-perf]
 
 - Perhaps most critically: **it requires that we continue to support a completely separate design for testing than for app code** (indeed: it basically requires that we fully implement the `hbs` or `<template>` designs for those!)
 
@@ -1014,6 +1014,8 @@ The major upside to this is that it is the smallest possible delta over today’
 
 [^recursive-module]: To see this for yourself, follow the instructions in [this gist](https://gist.github.com/chriskrycho/dc5adabd80c04d405c7a4894c0ffb99e). I had to test this out myself, and while it’s actually *very good* that modules work this way, I was initially surprised by it! If you’re curious: imports and exports are *static* and so are analyzed before the module is executed.
 
+[^recursive-import-perf]: Without additional post-processing, this would also introduce extra runtime overhead in terms of the imports!
+
 
 ### SFCs
 

From 5120276ca3f3680b04e595931929a1c66ba2f504 Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Thu, 2 Dec 2021 22:28:15 -0700
Subject: [PATCH 38/53] Yet more on alternatives

---
 text/0000-template-imports.md | 63 +++++++++++++++++++++++++----------
 1 file changed, 45 insertions(+), 18 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 05944546e3..a9c642813f 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -981,34 +981,61 @@ The imports-only design borrows the idea of “front-matter” from many text au
 
 </details>
 
-The major upside to this is that it is the smallest possible delta over today’s implementation. However, it has a number of significant downsides:
+The major upside to this is that it is the smallest possible delta over today’s implementation. However, it has a number of significant downsides
 
-- As with today’s _status quo_, it does not allow locally-scoped JavaScript values (including helpers and modifiers but also ecosystem tooling like GraphQL values, CSS-in-JS tooling, etc.) even when that is a perfectly reasonable design decision.
+First, as with today’s _status quo_, it does not allow locally-scoped JavaScript values (including helpers and modifiers but also ecosystem tooling like GraphQL values, CSS-in-JS tooling, etc.) even when that is a perfectly reasonable design decision.
 
-- It substantially complicates the implementation of tooling for language servers, which have to do extra work to detect the presence of a backing class and “stitch together” the backing class and the template if a backing class does exist.
+Second, it substantially complicates the implementation of tooling for language servers, which have to do extra work to detect the presence of a backing class and “stitch together” the backing class and the template if a backing class does exist.
 
-- Since there are separate files for a template and its backing class, users may be tempted try to implement JavaScript functionality in the module for the backing class, and import it in the template:
+Third, Since there are separate files for a template and its backing class, users may be tempted try to implement JavaScript functionality in the module for the backing class, and import it in the template:
 
-    ```js
-    import Component from '@glimmer/component';
+```js
+import Component from '@glimmer/component';
 
-    export function isBirthday() {/*...*/}
+export function isBirthday() {/*...*/}
 
-    export default class MyComponent extends Component { /*...*/ }
-    ```
+export default class MyComponent extends Component { /*...*/ }
+```
 
-    ```hbs
-    ---
-    import { isBirthday } from './my-component';
-    ---
-    {{#if (isBirthday @user.name)}}
-      <p>Happy birthday, {{@user.name}}!</p>
-    {{/if}}
+```hbs
+---
+import { isBirthday } from './my-component';
+---
+{{#if (isBirthday @user.name)}}
+  <p>Happy birthday, {{@user.name}}!</p>
+{{/if}}
+```
+
+While a colocated template (the default since Octane) is part of the same module as the backing class, this does technically work![^recursive-module] However, it’s the kind of extremely surprising and weird thing we would generally try to avoid pedagogically—it requires us to explain that these two separate files (`.js` and `.hbs`) are combined into a single module at build time… and that we have nonetheless kept them separate at authoring time, requiring these kinds of workarounds.[^recursive-import-perf]
+
+Perhaps most critically, this is **much worse than the _status quo_ for tests**. It requires that we do one of the following:
+
+- Require people’s test authoring format to become *massively* more verbose and less useful, with imports in every single test `hbs` string, to support strict mode for tests:
+
+    ```js
+    import { module, test } from 'qunit';
+    import { hbs } from 'ember-cli-htmlbars';
+    import { setupRenderingTest } from 'ember-qunit';
+    import { render } from '@ember/test-helpers';
+
+    module('demonstrates the problem', function (hooks) {
+      setupRenderingTest(hooks);
+
+      test('by rendering an imported component', async function (assert) {
+        await render(hbs`
+          ---
+          import ComponentToTest from 'my-app/components/component-to-test';
+          ---
+
+          <ComponentToTest />
+        `);
+      });
+    });
     ```
 
-    While a colocated template (the default since Octane) is part of the same module as the backing class, this does technically work![^recursive-module] However, it’s the kind of extremely surprising and weird thing we would generally try to avoid pedagogically—it requires us to explain that these two separate files (`.js` and `.hbs`) are combined into a single module at build time… and that we have nonetheless kept them separate at authoring time, requiring these kinds of workarounds.[^recursive-import-perf]
+    Notice that this also requires us to maintain, *and to teach*, the `hbs` handling for tests (or to design some replacement for it).
 
-- Perhaps most critically: **it requires that we continue to support a completely separate design for testing than for app code** (indeed: it basically requires that we fully implement the `hbs` or `<template>` designs for those!)
+- Continue to support a completely separate design for testing than for app code. In that case, though, supporting strict mode templates in tests *and* avoiding the verbosity of the first option means we need a separate authoring format for tests—in fact, it basically requires that we fully implement something like the <!-- TODO: name of proposal --> design!
 
 <!-- TODO: more? -->
 

From 6774406ce9dd2a9b80c80d03aa561dcf552e20be Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Thu, 2 Dec 2021 22:36:13 -0700
Subject: [PATCH 39/53] Elaborate testing downsides for imports-only, SFCs

---
 text/0000-template-imports.md | 55 ++++++++++++++++++++++++++++++++---
 1 file changed, 51 insertions(+), 4 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index a9c642813f..a147484f76 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -1030,10 +1030,20 @@ Perhaps most critically, this is **much worse than the _status quo_ for tests**.
           <ComponentToTest />
         `);
       });
+
+      test('then again with an argument', async function (assert) {
+        await render(hbs`
+          ---
+          import ComponentToTest from 'my-app/components/component-to-test';
+          ---
+
+          <ComponentToTest @anArg= />
+        `);
+      });
     });
     ```
 
-    Notice that this also requires us to maintain, *and to teach*, the `hbs` handling for tests (or to design some replacement for it).
+    The first thing to notice is that there is no way to import `ComponentToTest` here just once. The second thing to notice is that this also requires us to maintain, *and to teach*, the `hbs` handling for tests (or to design some replacement for it).
 
 - Continue to support a completely separate design for testing than for app code. In that case, though, supporting strict mode templates in tests *and* avoiding the verbosity of the first option means we need a separate authoring format for tests—in fact, it basically requires that we fully implement something like the <!-- TODO: name of proposal --> design!
 
@@ -1134,9 +1144,46 @@ Single File Components (hereafter SFCs) start with an HTML baseline and layer on
 
 This is very attractive in some ways, but it comes with three downsides:
 
-- SFCs do not allow multiple components to be defined in a single file. This has been an ongoing sticking point with the Vue and Svelte designs, such that there is even an open-for-years RFC for Svelte for supporting it. <!-- TODO: find and link RFC -->
-- The scope handling for the default export is unusual and requires additional teaching.
-- Perhaps most critically: as with the imports-only design, **the SFC design requires that we continue to support a completely separate design for testing than for app code** (indeed: it basically requires that we fully implement the `hbs` or `<template>` designs for those!)
+First, SFCs do not allow multiple components to be defined in a single file. This has been an ongoing sticking point with the Vue and Svelte designs, such that there is even an open-for-years RFC for Svelte for supporting it. <!-- TODO: find and link RFC -->
+
+Second, the scope handling for the default export is unusual and requires additional teaching.
+
+Third, and again most critically: as with the imports-only design, **the SFC design requires that we continue to support a completely separate design for testing than for app code or use an incredibly verbose test authoring format.** If we maintain the same authoring format, we end up with the same problems as in the imports-only proposal:
+
+```js
+import { module, test } from 'qunit';
+import { hbs } from 'ember-cli-htmlbars';
+import { setupRenderingTest } from 'ember-qunit';
+import { render } from '@ember/test-helpers';
+
+module('demonstrates the problem', function (hooks) {
+  setupRenderingTest(hooks);
+
+  test('by rendering an imported component', async function (assert) {
+    await render(hbs`
+      <script>
+        import ComponentToTest from 'my-app/components/component-to-test';
+      </script>
+
+      <ComponentToTest />
+    `);
+  });
+
+  test('then again with an argument', async function (assert) {
+    await render(hbs`
+      <script>
+        import ComponentToTest from 'my-app/components/component-to-test';
+      </script>
+
+      <ComponentToTest @anArg= />
+    `);
+  });
+});
+```
+
+Notice that this also substantially increases the cost of tooling even at the level of syntax highlighting, because now we need multiple nested layers of syntax highlighting: `hbs` strings include both HTML and JavaScript! While some syntax highlighters support this, it is a much higher lift for those which do not.
+
+And, once again, avoiding those problems more or less requires that we fully implement <!-- TODO: name of proposal --> to avoid this!
 
 
 ### Template literals (`hbs`)

From d40da3a28612fc66775ac43ba0cc8fd5cb27af06 Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Thu, 2 Dec 2021 22:40:15 -0700
Subject: [PATCH 40/53] Expand discussion of `hbs` alternative

---
 text/0000-template-imports.md | 35 ++++++++++++++++++++++++-----------
 1 file changed, 24 insertions(+), 11 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index a147484f76..e9022d9b82 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -1261,23 +1261,36 @@ export default class GenerateAvatar extends Component {
 
 </details>
 
-This has a couple significant advantages:
+#### Advantages
 
-- Unlike with the `<template>` proposal, Prettier can *parse* a file using `hbs` string with no further changes. (It cannot *format* them, however: it treats the contents of the string opaquely.)
-- It feels familiar to developers in the Ember ecosystem used to using `hbs` strings with their tests.
-- The broader JavaScript ecosystem makes use of a number of template string syntaxes, e.g. with `css` from [Emotion][emotion] or [`gql` from Apollo][gql].
+This has a couple significant advantages!
 
-However, it also has some significant disadvantages:
+First, unlike with the `<template>` proposal, Prettier can *parse* a file using `hbs` string with no further changes. (It cannot *format* them, however: it treats the contents of the string opaquely.) This is a small, but significant, decrease in the cost of supporting the format both up front and over time.
 
-- The design repurposes JavaScript syntax and gives it totally different semantics—like `<template>` does with HTML, but with *zero* signal from the context that it is doing something special.
-    - `hbs` is *not* actually a template string literal; it is a compile-time macro. Attempting to use it like a template string literal (e.g. by using `${...}` string interpolation) is a build-time error. This substantially undercuts the familiarity of the design: `css` and `graphql` and similar are *actual* string templates, not compile-time macros, and accordingly developers can use normal JavaScript semantics with them.
-    - The use of `static template = ...` has the wrong semantics: static class fields do not have access to an instance’s `this`—but templates quite expressly *do*. The whole point of a component with a backing class is to provide a normal JavaScript `this`, so this is a significant mismatch, which has consequences for both teaching and tooling.
+Second, it feels familiar to developers in the Ember ecosystem used to using `hbs` strings with their tests.
 
-- The learning path is *much* less gradual: the simplest possible component requires showing and at least minimally explaining JavaScript import and export semantics and template literals *and* that it isn’t a normal template literal as described above.
+Third, the broader JavaScript ecosystem makes use of a number of template string syntaxes, e.g. with `css` from [Emotion][emotion] or [`gql` from Apollo][gql], so it has familiarity for people coming from *outside* the Ember ecosystem as well.
 
-- Explaining what exactly `hbs` invocations produce is also strange: they aren’t actually JavaScript expressions, but they *appear* to be. In a template-only context, “invoking” `hbs` produces a component; in a class, it produces the *template* for that component. This is the same as with the `<template>` proposal, but it has the additional quirk of using JavaScript syntax to do it, rather than shifting languages.
+Fourth, it shares many of the other strongly-positive properties of the `<template>` design, including that it works exactly the same way for testing and app code.
 
-Net, while there are some nice features to <!-- TODO: finish discussing `hbs` -->
+These advantages are strong enough that this is *absolutely* the second-best move in the design space for us, and we should choose it if there is significant resistance to using `<template>`.
+
+
+#### Disadvantages
+
+Those positives notwithstanding, it also has some significant disadvantages compared to `<template>`.
+
+First, the design repurposes JavaScript syntax and gives it totally different semantics—like `<template>` does with HTML, but with *zero* signal from the context that it is doing something special.
+
+- `hbs` is *not* actually a template string literal; it is a compile-time macro. Attempting to use it like a template string literal (e.g. by using `${...}` string interpolation) is a build-time error. This substantially undercuts the familiarity of the design: `css` and `graphql` and similar are *actual* string templates, not compile-time macros, and accordingly developers can use normal JavaScript semantics with them.
+
+- The use of `static template = ...` has the wrong semantics: static class fields do not have access to an instance’s `this`—but templates quite expressly *do*. The whole point of a component with a backing class is to provide a normal JavaScript `this`, so this is a significant mismatch, which has consequences for both teaching and tooling.
+
+Second, the learning path is *much* less gradual: the simplest possible component requires showing and at least minimally explaining JavaScript import and export semantics and template literals *and* that it isn’t a normal template literal as described above.
+
+Third, explaining what exactly `hbs` invocations produce is also strange: they aren’t actually JavaScript expressions, but they *appear* to be. In a template-only context, “invoking” `hbs` produces a component; in a class, it produces the *template* for that component. This is the same as with the `<template>` proposal, but it has the additional quirk of using JavaScript syntax to do it, rather than shifting languages.
+
+Net, while there are some nice features to the `hbs` proposal, it comes out significantly worse than `<template>` in most ways we care about. The additional tooling costs are real, but they are much smaller than the other downsides of the format.
 
 
 ## Unresolved questions

From 5c8bd12a0d1f736a4ffcb9ec2a8836c9679492b9 Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Thu, 2 Dec 2021 22:45:16 -0700
Subject: [PATCH 41/53] Elaborate problems with imports-only and SFCs for
 testing

---
 text/0000-template-imports.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index e9022d9b82..31c3e428a8 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -1043,7 +1043,9 @@ Perhaps most critically, this is **much worse than the _status quo_ for tests**.
     });
     ```
 
-    The first thing to notice is that there is no way to import `ComponentToTest` here just once. The second thing to notice is that this also requires us to maintain, *and to teach*, the `hbs` handling for tests (or to design some replacement for it).
+    The first thing to notice is that there is no way to import `ComponentToTest` here just once. This overhead will multiply across the number of items to reference in a given test—every component, every helper, every modifier!—as well as across the number of tests. This is a *large* increase in the burden of testing compared to today.
+
+    The second thing to notice is that this also requires us to maintain, *and to teach*, the `hbs` handling for tests (or to design some replacement for it), on top of the “regular” template handling for components. This is the same situation as in Ember apps today—but since <!-- TODO: name of proposal --> allows us to *improve* the consistency between app code and test code, this counts as a negative by comparison!
 
 - Continue to support a completely separate design for testing than for app code. In that case, though, supporting strict mode templates in tests *and* avoiding the verbosity of the first option means we need a separate authoring format for tests—in fact, it basically requires that we fully implement something like the <!-- TODO: name of proposal --> design!
 
@@ -1181,7 +1183,7 @@ module('demonstrates the problem', function (hooks) {
 });
 ```
 
-Notice that this also substantially increases the cost of tooling even at the level of syntax highlighting, because now we need multiple nested layers of syntax highlighting: `hbs` strings include both HTML and JavaScript! While some syntax highlighters support this, it is a much higher lift for those which do not.
+Besides having all the same problems as the imports-only approach does, notice that this also substantially increases the cost of tooling even at the level of syntax highlighting, because now we need multiple nested layers of syntax highlighting: `hbs` strings include both HTML and JavaScript! While some syntax highlighters support this, it is a much higher lift for those which do not.
 
 And, once again, avoiding those problems more or less requires that we fully implement <!-- TODO: name of proposal --> to avoid this!
 

From 751f9d6caa1065c4f64fc28bd535f577bdf089df Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Thu, 2 Dec 2021 22:47:32 -0700
Subject: [PATCH 42/53] Emphasize `hbs` is massively better than status quo

---
 text/0000-template-imports.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 31c3e428a8..e245d2b066 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -1275,7 +1275,7 @@ Third, the broader JavaScript ecosystem makes use of a number of template string
 
 Fourth, it shares many of the other strongly-positive properties of the `<template>` design, including that it works exactly the same way for testing and app code.
 
-These advantages are strong enough that this is *absolutely* the second-best move in the design space for us, and we should choose it if there is significant resistance to using `<template>`.
+These advantages are strong enough that this is *absolutely* the second-best move in the design space for us, and given a choice between maintaining the status quo and using `hbs` (i.e. if `<template>` were off the table), ***we should absolutely choose `hbs`***.
 
 
 #### Disadvantages

From f4fb93e22069b8893caf38e7bf49c490ba78a123 Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Thu, 2 Dec 2021 22:48:45 -0700
Subject: [PATCH 43/53] Delete one completed TODO

---
 text/0000-template-imports.md | 2 --
 1 file changed, 2 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index e245d2b066..270b7ff1a7 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -1049,8 +1049,6 @@ Perhaps most critically, this is **much worse than the _status quo_ for tests**.
 
 - Continue to support a completely separate design for testing than for app code. In that case, though, supporting strict mode templates in tests *and* avoiding the verbosity of the first option means we need a separate authoring format for tests—in fact, it basically requires that we fully implement something like the <!-- TODO: name of proposal --> design!
 
-<!-- TODO: more? -->
-
 [^recursive-module]: To see this for yourself, follow the instructions in [this gist](https://gist.github.com/chriskrycho/dc5adabd80c04d405c7a4894c0ffb99e). I had to test this out myself, and while it’s actually *very good* that modules work this way, I was initially surprised by it! If you’re curious: imports and exports are *static* and so are analyzed before the module is executed.
 
 [^recursive-import-perf]: Without additional post-processing, this would also introduce extra runtime overhead in terms of the imports!

From 782913ee4a3520d54f6b8c0e37336aa185910e1c Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Fri, 3 Dec 2021 08:39:08 -0700
Subject: [PATCH 44/53] Fix a wordo

---
 text/0000-template-imports.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 270b7ff1a7..a91548b350 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -1290,7 +1290,7 @@ Second, the learning path is *much* less gradual: the simplest possible componen
 
 Third, explaining what exactly `hbs` invocations produce is also strange: they aren’t actually JavaScript expressions, but they *appear* to be. In a template-only context, “invoking” `hbs` produces a component; in a class, it produces the *template* for that component. This is the same as with the `<template>` proposal, but it has the additional quirk of using JavaScript syntax to do it, rather than shifting languages.
 
-Net, while there are some nice features to the `hbs` proposal, it comes out significantly worse than `<template>` in most ways we care about. The additional tooling costs are real, but they are much smaller than the other downsides of the format.
+Net, while there are some nice features to the `hbs` proposal, it comes out significantly worse than `<template>` in most ways we care about. The decreased tooling costs are real, but they are much smaller than the other downsides of the format.
 
 
 ## Unresolved questions

From e61a278791357a1f67ef66f3fd326bd44e64f762 Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Fri, 3 Dec 2021 09:36:33 -0700
Subject: [PATCH 45/53] Describe the prelude

---
 text/0000-template-imports.md | 45 ++++++++++++++++++++++++++++++++++-
 1 file changed, 44 insertions(+), 1 deletion(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index a91548b350..94cf6b6c06 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -562,7 +562,50 @@ Then a loose-mode component could invoke them like `<NamedOnly::Greet @name="Chr
 
 ### The “prelude”
 
-<!-- TODO: prelude -->
+While all values used in templates must be explicitly in scope, Ember[^glimmer-prelude] will provide some via a “prelude”.[^prelude] These are always in scope and do not need to be imported.
+
+The helpers in the prelude are:
+
+- `action`
+- `array`
+- `component`
+- `concat`
+- `debugger`
+- `each`
+- `each-in`
+- `fn`
+- `get`
+- `has-block`
+- `has-block-params`
+- `hash`
+- `if`
+- `in-element`
+- `let`
+- `log`
+- `mount`
+- `mut`
+- `on`
+- `outlet`
+- `query-params`
+- `unbound`[^unbound-deprecated]
+- `unless`
+- `yield`
+
+The modifiers in the prelude are:
+
+- `on`
+
+The components in the prelude are:
+
+- `LinkTo`
+- `Input`
+- `Textarea`
+
+[^glimmer-prelude]: Glimmer.js may provide its own prelude. While long-term the two should likely align, this RFC simply takes the _status quo_ as a given
+
+[^prelude]: “Prelude” is the conventional name for this functionality in programming language design.
+
+[^unbound-deprecated]: `unbound` is deprecated, but since it will not be removed till Ember 5.0.0, it should appear in the prelude nonetheless.
 
 
 ### Tooling

From e3320d478e6b9cb3b56972a38266a707ebf4b897 Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Fri, 3 Dec 2021 09:38:20 -0700
Subject: [PATCH 46/53] Update TOC

---
 text/0000-template-imports.md | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 94cf6b6c06..774eb01c43 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -116,6 +116,10 @@ export default class GenerateAvatar extends Component {
 
 - [Summary](#summary)
 - [Motivation](#motivation)
+  - [Namespaces and Modules](#namespaces-and-modules)
+  - [Scope](#scope)
+  - [Testing](#testing)
+  - [The solution](#the-solution)
   - [Constraints](#constraints)
 - [Detailed design](#detailed-design)
   - [Compilation](#compilation)
@@ -125,11 +129,13 @@ export default class GenerateAvatar extends Component {
   - [Interop](#interop)
   - [The “prelude”](#the-prelude)
   - [Tooling](#tooling)
-    - [Generators](#generators)
+    - [Blueprints](#blueprints)
     - [Linting and formatting](#linting-and-formatting)
     - [Language server support](#language-server-support)
 - [How we teach this](#how-we-teach-this)
   - [Guides](#guides)
+    - [Tutorial](#tutorial)
+    - [Core Concepts: Components](#core-concepts-components)
   - [API Docs](#api-docs)
   - [TypeScript](#typescript)
   - [Existing Ember users](#existing-ember-users)
@@ -137,7 +143,9 @@ export default class GenerateAvatar extends Component {
 - [Alternatives](#alternatives)
   - [Imports-only](#imports-only)
   - [SFCs](#sfcs)
-  - [Template literals](#template-literals)
+  - [Template literals (`hbs`)](#template-literals-hbs)
+    - [Advantages](#advantages)
+    - [Disadvantages](#disadvantages)
 - [Unresolved questions](#unresolved-questions)
 
 

From 084dd9a87915da7676d24786e89b65b42cd25b56 Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Fri, 3 Dec 2021 09:39:18 -0700
Subject: [PATCH 47/53] Fix an incomplete sentence

---
 text/0000-template-imports.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 774eb01c43..d524bd8f4a 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -160,7 +160,7 @@ Today, authors of Ember and Glimmer apps and libraries must author their templat
 
 First, because of the global namespace, name conflicts are common, and avoiding them requires either manually namespacing components or using (now-deprecated) experimental tools like [`ember-holy-futuristic-template-namespacing-batman`](https://github.com/rwjblue/ember-holy-futuristic-template-namespacing-batman). But:
 
-- Manually namespacing is clunky and does not actually *guarantee* there won't be conflicts. Combined with the way addons typically supply , name conflicts are sometimes unavoidable.
+- Manually namespacing is clunky and does not actually *guarantee* there won't be conflicts. Combined with the way addons typically supply their components, helpers, and modifiers into the app namespace, name conflicts are sometimes unavoidable.
 
 - Even the workaround via `ember-holy-futuristic-template-namespacing-batman` requires using different names for modules in Ember than their Node package name when the Node package uses [npm scopes][scopes]. (This was one of the original motivations for exploring a design which leverages JavaScript modules, in fact!) Since our resolution modes must ultimately deal in JavaScript terms, we are in the position of always potentially being one ecosystem shift away from another syntax conflict with template-language-only designs for managing scope.
 

From 1dcd0197cd349adafd0657aa38e042af15fc5754 Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Fri, 3 Dec 2021 09:47:01 -0700
Subject: [PATCH 48/53] Improve on and elaborate motivation

---
 text/0000-template-imports.md | 19 +++++++++++++------
 1 file changed, 13 insertions(+), 6 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index d524bd8f4a..ee450d6c36 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -187,13 +187,16 @@ These problems are all well-solved already, using the JavaScript modules spec (o
 
 Second, and closely related to the global namespace problem: there is presently no good way for users to introduce or use locally-scoped code. Every component, helper, and modifier must live in its own file, and be globally availbale—even if it is meant to be used privately. Where JavaScript modules provide users to control their public APIs in terms of `export`s, Ember apps largely cannot take advantage of those for anything which interacts with the template layer.
 
-In practice, this has a number of knock-on effects for Ember code:
+In practice, this has a number of knock-on effects for Ember code.
 
-- Components tend to grow without bound, because there is no easy equivalent to the "extract method" or "extract into new class" refactorings (which we commonly use on the JS side) which does not (a) make the newly-extracted components available to the whole app and (b) require an entirely new file.
+First, components tend to grow without bound, because the equivalent of the "extract method" or "extract into new class" refactorings (which we commonly use on the JS side) end up with two downsides:
 
-- Users also often introduce classes with actions where a simple [function-based helper][rfc-0756] would do, because that is the only way to provide a non-global function.
+- they make the newly-extracted components available to the whole app, even if the concern is private to that component
+- the require an entirely new file, which is friction both for the creation and the use/understanding of a given view
 
-- It likewise incentivizes the use of the ember-render-modifiers with backing classes, rather than custom modifiers, because the behavior can then be scoped to that module—whereas, again, a custom modifier would be in global scope. This in turn makes it easy for users to miss the helpful separation of concerns which custom modifiers enable.
+Second, users also often introduce classes with actions or getters where a simple [function-based helper][rfc-0756] would do, because that is the only way to provide a non-global function. (I show this by example in [**How We Teaching This: Guides: Tutorial: Reusable Components**](#reusable-components) below.)
+
+Third, it likewise incentivizes the use of the ember-render-modifiers with backing classes, rather than custom modifiers, because the behavior can then be scoped to that module—whereas, again, a custom modifier would be in global scope. This in turn makes it easy for users to miss the helpful separation of concerns which custom modifiers enable.
 
 [rfc-0756]: https://github.com/emberjs/rfcs/pull/756
 
@@ -201,12 +204,16 @@ Over time, these all lead to a proliferation of backing classes which are only p
 
 [scopes]: https://docs.npmjs.com/cli/v8/using-npm/scope
 
-What’s more, tools which assume they will be used in JavaScript contexts more or less don’t work with our templates today, because the templates have no way to access them. Think of CSS tools like [Emotion][emotion], [Styled Components][styled-components], [vanilla-extract][vanilla-extract], and even [CSS Modules][css-modules]: none of them work out of the box with our current design, and tools like Ember CSS Modules have to jump through many hoops and do many hacks to work at all. Whatever anyone’s personal opinions on these specific, they’re potentially-valuable tools which are barely or not at all usable in Ember today.
+What’s more, tools which assume they will be used in JavaScript contexts more or less don’t work with our templates today, because the templates have no way to access them. Think of CSS tools like [CSS Modules][css-modules], which is widely used in the Ember ecosystem via [Ember CSS Modules][e-css-m]: our current implementation has to jump through many hoops and do many hacks to work at all. A format which makes JavaScript values available in template scope would let us drop *all* of that special sauce—and this goes for *all* such JavaScript-side tooling.
+
+[css-modules]: https://github.com/css-modules/css-modules
+[e-css-m]: https://github.com/salsify/ember-css-modules
+
+[^other-css-tools]: The same applies to all other similar tools, e.g. [Emotion][emotion], [Styled Components][styled-components], [vanilla-extract][vanilla-extract]: none of them work out of the box with our current design. Whatever anyone’s personal opinions on these specific, they’re potentially-valuable tools which are barely or not at all usable in Ember today.
 
 [emotion]: https://emotion.sh/docs/@emotion/css
 [styled-components]: https://styled-components.com
 [vanilla-extract]: https://vanilla-extract.style
-[css-modules]: https://github.com/css-modules/css-modules
 
 
 ### Testing

From abf372d9390de0269967eee13db708d8392965fc Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Fri, 3 Dec 2021 09:48:14 -0700
Subject: [PATCH 49/53] Standardize constraints format

---
 text/0000-template-imports.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index ee450d6c36..41804a54b1 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -250,13 +250,13 @@ In sum, `<template>` resolves each problem outlined above, and introduces new ca
 
 There are a number of solutions which could address these needs and add these capabilities. This RFC proposes `<template>` out of all the possible options because I take the following constraints as guiding the design decision (and the ordering here is purposeful—items earlier in the list I judge to be more important than items later in the list):
 
-1. Our choice of design **must not** regress our ability to write tests, and if it is possible to *improve* our testing story, we should take the opportunity to do so.
+1. Our choice of design **must not regress our ability to write tests**, and if it is possible to *improve* our testing story, we should take the opportunity to do so.
 
-2. In the absence of hard technical constraints forbidding it, we should **prefer** the solution which has the best story for teaching—at all levels, including beginners but also supporting advanced users. In particular, this means that we should value both *progressive disclosure of complexity* and the *principle of least surprise*, and that we may need to weight them against each other, but that we should pay particular attention when they agree.
+2. In the absence of hard technical constraints forbidding it, we should **prefer the solution which has the best story for teaching**—at all levels, including beginners but also supporting advanced users. In particular, this means that we should value both *progressive disclosure of complexity* and the *principle of least surprise*, and that we may need to weight them against each other, but that we should pay particular attention when they agree.
 
-3. This design must cleanly interoperate with existing Ember codebases. That is, adopting this **must not** require users to migrate their entire codebase at once.
+3. This design must cleanly interoperate with existing Ember codebases. That is, adopting this **must not require users to migrate their entire codebase at once**.
 
-4. We should prefer a design which provides more flexibility to end users over a design which provides less.
+4. We should **prefer a design which provides more flexibility** to end users over a design which provides less.
 
 While it is certainly possible to differ with these constraints *a priori*—reevaluating constraints is, in a very real sense, [how we got to this very RFC](https://github.com/emberjs/rfcs/pull/367#issuecomment-423839940)—we also run the risk of paralysis if we *continually* reevaluate from first principles. More challenging is inevitable disagreement about how we *weight* these constraints. On that front, there is no possibility of *final* agreement, but we should commit to some ordering for the purposes of this design so that the rest of it can proceed on the same terms.
 

From 97a7683335951f04ee01f7b8efb85dcb1a1a3571 Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Fri, 3 Dec 2021 09:49:27 -0700
Subject: [PATCH 50/53] Fix a missing word

---
 text/0000-template-imports.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index 41804a54b1..a7a053688c 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -539,7 +539,7 @@ class Example extends Component {
 
 That is because the compilation output does *not* embed the template in the class' body in any way, but instead associates it *externally* to the class—but private class fields are only accessible within the body of the class itself, per the ECMAScript spec. While we could invest time to change the implementation to avoid this, it is not generally a problem. Because we do not interact with component class instances directly—only through the template layer—we do not actually *need* private class fields.
 
-Even, this is a real gap, which we could address in a future RFC. Notably, it is *not specific to this proposal*, applies to *all* proposals built on the current primitives.
+Even, this is a real gap, which we could address in a future RFC. Notably, it is *not specific to this proposal*, but applies to *all* proposals built on the current primitives.
 
 
 ### Interop

From 2351118db2626638486548e1d2ecda89a68fb105 Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Fri, 3 Dec 2021 10:06:35 -0700
Subject: [PATCH 51/53] Start on Tooling: do Syntax Highlighting

---
 text/0000-template-imports.md | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index a7a053688c..b1fd942711 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -625,7 +625,19 @@ The components in the prelude are:
 
 ### Tooling
 
-<!-- TODO: tooling -->
+To support the new format, we need to update tooling across the ecosystem to understand the format.
+
+
+#### Syntax highlighting
+
+First, we need syntax highlighting support across the ecosystem. Support already exists [for VS Code][vsc-highlighting], which represents the single largest group of web developers; as well as for any tool which can use [a tree-sitter grammar][tree-sitter-highlighting] (e.g. Neovim).
+
+We will also need to implement support in [Linguist](https://github.com/github/linguist) for GitHub syntax highlighting.
+
+Beyond that, we should encourage the community to add support for other editors (IntelliJ, Atom, Emacs, etc.) as well as for tools like [Rouge](https://rubygems.org/gems/rouge) (which powers GitLab syntax highlighting) and other highlighters, but need not treat those as *blocking* adoption of <!-- TODO: name of proposal -->
+
+[vsc-highlighting]: https://marketplace.visualstudio.com/items?itemName=chiragpat.vscode-glimmer
+[tree-sitter-highlighting]: https://github.com/alexlafroscia/tree-sitter-glimmer
 
 
 #### Blueprints

From 421f94f232d0931c72d5fbd0931a6bc12305ab49 Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Fri, 3 Dec 2021 10:19:01 -0700
Subject: [PATCH 52/53] Tooling: Blueprints

---
 text/0000-template-imports.md | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index b1fd942711..ea094ab26d 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -642,7 +642,21 @@ Beyond that, we should encourage the community to add support for other editors
 
 #### Blueprints
 
-<!-- TODO: blueprints -->
+All blueprints will need to be updated to support generating the new format. During the transition period, we should allow generating both. The rollout will follow the example of the rollout of Glimmer components with Octane:
+
+1. Introduce the ability to author components in the new format with a new `--strict` flag, but leave the default today’s loose mode format. Introduce `--loose` as an explicit flag for using today’s loose mode format.
+
+2. When Ember Polaris is released, change the default to the new format, while leaving loose mode available via `--loose`, and preserving `--strict` as an explicit flag for the new default.
+
+3. If or when loose mode templates are deprecated, the supporting blueprint infrastructure can be removed, including the `--loose` flag.
+
+The current blueprints support generating a backing class for any existing component template which does not already have a backing class with the `component-class` format. We have two choices about the behavior of that blueprint for strict mode templates:
+
+1. Do not support it. Adding a backing class is simply a matter of adding an import and adding a class.
+
+2. Reimplement the blueprint using an AST transform (which we have prior art for: route generation uses that approach), to add a backing class for an existing default export in the module.
+
+We should take (1) here as a default starting point, while encouraging the community to implement (2) if interested.
 
 
 #### Linting and formatting

From 23ee8c7dd6880ed1bfdd9160838afdf39fca308b Mon Sep 17 00:00:00 2001
From: Chris Krycho <hello@chriskrycho.com>
Date: Fri, 3 Dec 2021 10:21:15 -0700
Subject: [PATCH 53/53] Tweak TODOs to make it easier for myself

---
 text/0000-template-imports.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/text/0000-template-imports.md b/text/0000-template-imports.md
index ea094ab26d..8b0df9fbb9 100644
--- a/text/0000-template-imports.md
+++ b/text/0000-template-imports.md
@@ -21,7 +21,7 @@ RFC PR: Fill this in with the URL for the Proposal RFC PR
 -->
 
 
-# TODO: let's name this thing something catchy!
+# TODO/name of proposal
 
 
 ## Summary
@@ -229,7 +229,7 @@ Additionally, introducing test-only components is quite painful, requiring use o
 
 ### The solution
 
-To address these problems, the Ember community [proposed primitives][rfc-0454] which unlocked experimentation in this space and [defined the semantics of “strict” templates which use those primitives][rfc-0496]. Now, with a history of having done that experimentation—with [GlimmerX][glimmerx] and [ember-template-imports]—and having had *many* discussions about the tradeoffs over the years, it’s time to ship a proposal which resolves these questions: <!-- TODO: name the proposal -->.
+To address these problems, the Ember community [proposed primitives][rfc-0454] which unlocked experimentation in this space and [defined the semantics of “strict” templates which use those primitives][rfc-0496]. Now, with a history of having done that experimentation—with [GlimmerX][glimmerx] and [ember-template-imports]—and having had *many* discussions about the tradeoffs over the years, it’s time to ship a proposal which resolves these questions: <!-- TODO/name of proposal -->.
 
 [rfc-0454]: https://github.com/emberjs/rfcs/pull/454
 [rfc-0496]: https://emberjs.github.io/rfcs/0496-handlebars-strict-mode.html
@@ -634,7 +634,7 @@ First, we need syntax highlighting support across the ecosystem. Support already
 
 We will also need to implement support in [Linguist](https://github.com/github/linguist) for GitHub syntax highlighting.
 
-Beyond that, we should encourage the community to add support for other editors (IntelliJ, Atom, Emacs, etc.) as well as for tools like [Rouge](https://rubygems.org/gems/rouge) (which powers GitLab syntax highlighting) and other highlighters, but need not treat those as *blocking* adoption of <!-- TODO: name of proposal -->
+Beyond that, we should encourage the community to add support for other editors (IntelliJ, Atom, Emacs, etc.) as well as for tools like [Rouge](https://rubygems.org/gems/rouge) (which powers GitLab syntax highlighting) and other highlighters, but need not treat those as *blocking* adoption of <!-- TODO/name of proposal -->
 
 [vsc-highlighting]: https://marketplace.visualstudio.com/items?itemName=chiragpat.vscode-glimmer
 [tree-sitter-highlighting]: https://github.com/alexlafroscia/tree-sitter-glimmer
@@ -734,7 +734,7 @@ This section provides is an opportunity to show how useful it can be to introduc
 
 (I will provide this example in full here in part because it shows powerfully the pedagogical value of this RFC!)
 
-The Mapbox token value is not reactive and therefore the computation has no reason to exist on a backing class *at all*. It is only there today because *without* <!-- TODO: name of this thing -->, it would otherwise require introducing the heavier notion of classic (pre-[RFC #0756][rfc-0756]) helpers. Now that we *have* `<template>`, it can simply become a constant value defined in local scope:
+The Mapbox token value is not reactive and therefore the computation has no reason to exist on a backing class *at all*. It is only there today because *without* <!-- TODO/name of proposal -->, it would otherwise require introducing the heavier notion of classic (pre-[RFC #0756][rfc-0756]) helpers. Now that we *have* `<template>`, it can simply become a constant value defined in local scope:
 
 ```js
 import ENV from 'super-rentals/config/environment';
@@ -1129,9 +1129,9 @@ Perhaps most critically, this is **much worse than the _status quo_ for tests**.
 
     The first thing to notice is that there is no way to import `ComponentToTest` here just once. This overhead will multiply across the number of items to reference in a given test—every component, every helper, every modifier!—as well as across the number of tests. This is a *large* increase in the burden of testing compared to today.
 
-    The second thing to notice is that this also requires us to maintain, *and to teach*, the `hbs` handling for tests (or to design some replacement for it), on top of the “regular” template handling for components. This is the same situation as in Ember apps today—but since <!-- TODO: name of proposal --> allows us to *improve* the consistency between app code and test code, this counts as a negative by comparison!
+    The second thing to notice is that this also requires us to maintain, *and to teach*, the `hbs` handling for tests (or to design some replacement for it), on top of the “regular” template handling for components. This is the same situation as in Ember apps today—but since <!-- TODO/name of proposal --> allows us to *improve* the consistency between app code and test code, this counts as a negative by comparison!
 
-- Continue to support a completely separate design for testing than for app code. In that case, though, supporting strict mode templates in tests *and* avoiding the verbosity of the first option means we need a separate authoring format for tests—in fact, it basically requires that we fully implement something like the <!-- TODO: name of proposal --> design!
+- Continue to support a completely separate design for testing than for app code. In that case, though, supporting strict mode templates in tests *and* avoiding the verbosity of the first option means we need a separate authoring format for tests—in fact, it basically requires that we fully implement something like the <!-- TODO/name of proposal --> design!
 
 [^recursive-module]: To see this for yourself, follow the instructions in [this gist](https://gist.github.com/chriskrycho/dc5adabd80c04d405c7a4894c0ffb99e). I had to test this out myself, and while it’s actually *very good* that modules work this way, I was initially surprised by it! If you’re curious: imports and exports are *static* and so are analyzed before the module is executed.
 
@@ -1267,7 +1267,7 @@ module('demonstrates the problem', function (hooks) {
 
 Besides having all the same problems as the imports-only approach does, notice that this also substantially increases the cost of tooling even at the level of syntax highlighting, because now we need multiple nested layers of syntax highlighting: `hbs` strings include both HTML and JavaScript! While some syntax highlighters support this, it is a much higher lift for those which do not.
 
-And, once again, avoiding those problems more or less requires that we fully implement <!-- TODO: name of proposal --> to avoid this!
+And, once again, avoiding those problems more or less requires that we fully implement <!-- TODO/name of proposal --> to avoid this!
 
 
 ### Template literals (`hbs`)