A custom element's connectedCallback reads this.querySelector('.label') and gets null when the defining script runs inline in <head>, but finds the element when the same script is loaded as a module at the end of <body>. Why does the timing change the result?

## Two different moments called "the element appears" A custom element instance is produced by one of two mechanisms, and they sit on opposite sides of parsing. **Immediate creation.** The definition is already in the registry when the parser reaches the start tag. The parser creates the element as an instance of your class straight away, and inserting it into the document fires `connectedCallback` right then. The parser has not yet read a single byte of the element's inner markup, so the element is genuinely empty at that moment. **Upgrade.** The parser reaches `<my-card>` with no definition registered. It creates a plain `HTMLElement` marked as an undefined custom element, parses the children into it normally, and moves on. Later, `customElements.define('my-card', MyCard)` runs and every matching element in the document is upgraded: your constructor runs on the existing instance, `attributeChangedCallback` is replayed for each observed attribute currently present, and `connectedCallback` is called — now with the full subtree in place. An inline script in `<head>` puts you in the first case. A `type="module"` script, or a classic script with `defer`, is executed only after the document has finished parsing, which puts you in the second. ## Why the parser cannot do better This is not a browser bug or an ordering accident. HTML parsing is streaming: the parser inserts an element into the tree the moment it sees the start tag, so incremental rendering can begin, and the closing tag may be kilobytes and one network round trip away. `connectedCallback` means "you are now in the document", and that is true at the start tag. There is no "your children have finished parsing" callback in the platform. ## The fixes, in order of robustness **1. Do not read light-DOM children at connect time.** Render your own UI into a shadow root and let the author's content project into it. Projection is resolved by the browser as content arrives, so late-parsed children simply show up. This is why component libraries so rarely hit the problem: it does not arise for them. **2. Wait for parsing to finish when you must read children.** Detect the case explicitly rather than relying on where the script tag happens to sit: ```js connectedCallback() { if (this.ownerDocument.readyState === 'loading') { this.ownerDocument.addEventListener( 'DOMContentLoaded', () => this.#init(), { once: true } ); } else { this.#init(); } } ``` `readyState === 'loading'` is true exactly while the parser is still running, which is the only situation in which children can be missing. Note that this deliberately does *not* delay elements created later at runtime — those always arrive complete. **3. Load the definition with a deferred or module script.** Making the whole registration happen after parsing turns every element on the page into the upgrade case. It works, and it is what most sites do accidentally, but it is a page-level accident rather than a component-level guarantee: someone who inlines your bundle for performance reintroduces the bug. ## Related tools `customElements.whenDefined('my-card')` returns a promise resolving with the constructor once the name is registered. It is for code waiting on *someone else's* definition — gating a `:not(:defined)` loading state, or waiting before setting properties on a third-party element — not for solving the children-not-parsed problem, which is about the parser, not the registry. `customElements.upgrade(root)` forces upgrade of already-created elements inside a subtree without waiting for them to be inserted into the document. That matters when you build a detached subtree with `innerHTML` or clone one from a fragment and want the instances to be real class instances before you insert them. ## The wider lesson A custom element cannot assume anything about *when* it runs relative to its own markup, because that depends on how the page loaded the definition — inline, deferred, dynamically imported, lazily on interaction — and a component author does not control that. Well-behaved components are written to be correct in every one of those orderings: read attributes through `attributeChangedCallback`, treat light-DOM children as content that may arrive late, and make `connectedCallback` idempotent. Components that only work when the bundle is at the end of `<body>` are carrying an undeclared dependency on the host page's loading strategy.