jq79 0.5.7 → 0.5.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jq79",
-  "version": "0.5.7",
+  "version": "0.5.9",
   "description": "Mini reactive component library: single-file components, Svelte-style setup scripts, fine-grained proxy reactivity. Single-file build, zero dependencies.",
   "keywords": [
     "reactive",

package/src/jq79.ts

@@ -19,6 +19,12 @@ type TemplateNode = {
   tag: string
   attrs: Record<string, string>
   children: (TemplateNode | string)[]
+  // the tag as the author capitalized it, present only when they wrote it
+  // uppercase-initial - i.e. when they meant a component. `tag` cannot answer
+  // this: the HTML parser lowercases it, so the claim is captured before the
+  // parse (see stampComponentTag) and lifted off attrs here, where it stops
+  // looking like an attribute to every loop downstream
+  component?: string
 }
 
 type TagBlock = {
@@ -45,20 +51,29 @@ const elementAttrs = (el: Element): Record<string, string> =>
 // they are not in the AST at all - which is where slot content is written
 // (<template :slot.name>), and why a nested <template> used to render as an
 // empty element whatever was inside it
-const elementToAST = (el: Element): TemplateNode => ({
-  tag: el.tagName.toLowerCase(),
-  attrs: elementAttrs(el),
-  children: Array.from((el instanceof HTMLTemplateElement ? el.content : el).childNodes).flatMap((node): (TemplateNode | string)[] => {
-    if (node.nodeType === Node.TEXT_NODE) {
-      const text = node.textContent ?? ""
-      return text ? [text] : []
-    }
-    if (node.nodeType === Node.ELEMENT_NODE) {
-      return [elementToAST(node as Element)]
-    }
-    return []
-  })
-})
+const elementToAST = (el: Element): TemplateNode => {
+  const attrs = elementAttrs(el)
+  // the pre-parse stamp becomes a field and leaves attrs entirely: it is not a
+  // prop, not a directive and not an attribute, and every loop that walks attrs
+  // would otherwise need to know its name
+  const component = attrs[COMPONENT_TAG_ATTR]
+  delete attrs[COMPONENT_TAG_ATTR]
+  return {
+    tag: el.tagName.toLowerCase(),
+    attrs,
+    ...(component === undefined ? {} : { component }),
+    children: Array.from((el instanceof HTMLTemplateElement ? el.content : el).childNodes).flatMap((node): (TemplateNode | string)[] => {
+      if (node.nodeType === Node.TEXT_NODE) {
+        const text = node.textContent ?? ""
+        return text ? [text] : []
+      }
+      if (node.nodeType === Node.ELEMENT_NODE) {
+        return [elementToAST(node as Element)]
+      }
+      return []
+    })
+  }
+}
 
 // evaluated with `with` (rather than passing scope keys as positional params)
 // so only the identifiers an expression actually references are read from
@@ -383,6 +398,32 @@ const findComponentKey = (scope: Record<string, any>, tag: string): string | nul
   return null
 }
 
+// every name a tag *could* have resolved to, walking the same chain
+// findComponentKey does. Deduped and sorted, because the chain can hold one
+// name twice (a prop shadowing a sibling) and the order it comes out in is the
+// prototype's, which means nothing to a reader scanning for their typo
+const componentsInScope = (scope: Record<string, any>): string[] => {
+  const names = new Set<string>()
+  for (let obj: any = scope; obj && obj !== Object.prototype; obj = Object.getPrototypeOf(obj)) {
+    for (const key of Object.keys(obj)) if (/^[A-Z]/.test(key)) names.add(key)
+  }
+  return [...names].sort()
+}
+
+// a tag whose name resolves to no component, once nothing can still supply one.
+// The error names what *is* in scope: the mistake is nearly always a typo or a
+// missing import, and both are one glance from the list. "(none)" is its own
+// answer - it says the component has no components at all, which points at the
+// import rather than at the spelling
+const unresolvedComponent = (tag: string, scope: Record<string, any>): Error => {
+  const names = componentsInScope(scope)
+  return new Error(
+    `jq79: <${tag}> is not defined - no component of that name is in scope, and nothing renders here. ` +
+    `Import it in a :setup script, declare it as a prop, or add a <template name="${tag}"> to this file. ` +
+    `In scope: ${names.length ? names.join(", ") : "(none)"}.`
+  )
+}
+
 // how deep a component may nest inside itself before the runtime calls it a
 // cycle. Deeper than any real tree, shallower than the JS stack: a truncated
 // render with an error on the console beats a stack overflow with none
@@ -1025,6 +1066,32 @@ const renderNode = (node: TemplateNode, outerScope: Record<string, any>, fx: Eff
 
   const el = document.createElement(node.tag)
 
+  // <UserCrad /> - written as a component (node.component), resolving to no
+  // component, and not an element either. Nothing else on the page can supply
+  // the name once every script has settled, so this renders no markup, no
+  // styles, no children and no script, forever, and says so by throwing rather
+  // than leaving a hole where a region of the page was meant to be.
+  //
+  // All three conditions carry weight. Without the capitalization <lable> and
+  // <svg> would be fatal (createElement builds SVG names in the HTML namespace,
+  // so an <svg> is an HTMLUnknownElement too); without the element check <DIV>
+  // would be, though it renders a perfectly good div; and without the pending
+  // count a factory that awaits $mounted() before returning its components
+  // could never render one, which is exactly what the watcher below is for.
+  //
+  // An *absent* count is a fourth case, and it is not zero: renderComponent()
+  // renders a template against a store somebody else owns and assembles, so
+  // nothing there has finished and nothing says a key can't still be written
+  // in. The claim being tested is a component's claim about its own scripts,
+  // and where none was made the tag waits for the upgrade, as it always has.
+  //
+  // Written without a local for the count because renderNode is on the stack
+  // for the whole of the subtree below it, so a slot here is a slot per level
+  // of a component nested inside itself - see renderWith
+  if (node.component && el instanceof HTMLUnknownElement && ((scope as any)[PENDING_SCRIPTS] as PendingScripts | undefined)?.count === 0) {
+    throw unresolvedComponent(node.component, scope)
+  }
+
   // a tag that isn't standard HTML but has no matching scope key *yet* may be
   // a component that arrives later (e.g. an async factory script exposing an
   // imported component after `await`). Watch for the key: the effect tracks
@@ -1527,6 +1594,36 @@ const SLOT_TAG_RE = /^slot\./i
 const kebabTagName = (tag: string): string =>
   SLOT_TAG_RE.test(tag) ? `slot.${camelToKebab(tag.slice("slot.".length))}` : tag
 
+// the same pass records what it declined to rewrite. An uppercase-initial tag
+// is a claim about a component: HTML's own elements are matched
+// case-insensitively but nobody writes <DIV> by accident, and a custom element
+// may not be spelled that way at all. So <UserCard> is a name the author
+// expected to resolve - which is what lets renderNode throw when it doesn't
+// (see unresolvedComponent).
+//
+// Carried in a *value* rather than left in the tag name, because the value is
+// the one place the HTML parser preserves case - the same move expandPropsSpread
+// makes for `...userData`, and for the same reason. elementToAST lifts it
+// straight off attrs into a field, so no attribute loop downstream ever sees
+// it - and since that lift is unconditional, the name has to be one no author
+// would write: a plain `:component` would eat the prop of that name off
+// <Card :component="Widget" />
+const COMPONENT_TAG_ATTR = ":jq79-component"
+const COMPONENT_TAG_RE = /^[A-Z]/
+
+// appends the stamp inside the tag, *before* a self-closing slash: this pass
+// runs first and expandSelfClosingTags still has to recognize the `/>` that
+// OPEN_TAG_RE swept into the attributes. A slash inside a quoted value can't be
+// mistaken for it - only a trailing one is matched
+const TRAILING_SLASH_RE = /\/\s*$/
+
+const stampComponentTag = (tag: string, attrs: string): string => {
+  if (!COMPONENT_TAG_RE.test(tag)) return attrs
+  const stamp = ` ${COMPONENT_TAG_ATTR}="${tag}"`
+  const slash = TRAILING_SLASH_RE.exec(attrs)
+  return slash ? `${attrs.slice(0, slash.index)}${stamp}${slash[0]}` : `${attrs}${stamp}`
+}
+
 const expandNameCase = (src: string): string =>
   src
     .split(RAW_BLOCK_RE)
@@ -1538,7 +1635,7 @@ const expandNameCase = (src: string): string =>
               const rewritten = attrs.replace(ATTR_NAME_RE, (whole, space: string | undefined, name: string | undefined) =>
                 name === undefined ? whole : `${space}${camelToKebab(name)}`
               )
-              return `<${kebabTagName(tag)}${rewritten}>`
+              return `<${kebabTagName(tag)}${stampComponentTag(tag, rewritten)}>`
             })
             .replace(CLOSE_SLOT_RE, (_match, suffix: string, space: string) => `</slot.${camelToKebab(suffix)}${space}>`)
     )
@@ -1806,6 +1903,11 @@ const resolveSpecifier = (spec: string, filename: string | undefined): string =>
 // or devtools shows only one of them)
 type ScriptLocation = { filename?: string; index?: number }
 
+// what running a script tells its caller: the promise it settles through, and
+// whether it already finished on this stack. `sync` is the fast path the render
+// gate is built on - see runSetupScript
+type ScriptRun = { settled: Promise<unknown>; sync: boolean }
+
 // nothing to name an inline component's scripts after, so they stay anonymous
 const sourceUrlComment = (filename: string | undefined, index: number): string =>
   filename ? `\n//# sourceURL=${filename}?jq79-script=${index}` : ""
@@ -1851,23 +1953,36 @@ const releaseStyle = (content: string) => {
 // normally. get/set are deliberately not trapped: they default-forward to
 // `scope` (the reactive proxy), preserving tracking and notify.
 // The body is wrapped in an async IIFE so top-level `await` works: everything
-// up to the first await runs synchronously (before the template renders), and
-// later assignments update the DOM reactively when they happen
-const runSetupScript = (code: string, scope: Record<string, any>, effect: (run: () => void) => void, instanceHelpers: Record<string, any> = {}, importer: (url: string) => Promise<any> = importResource, at: ScriptLocation = {}) => {
+// up to the first await runs synchronously, and later assignments update the
+// DOM reactively when they happen.
+//
+// Returns whether the body ran to completion synchronously, plus the promise it
+// settles through. renderWith needs the *synchronous* answer - a script that
+// finished in this turn cannot hold anything up, so the template can render on
+// this stack exactly as it always has (see the render gate). Asking the promise
+// instead would defer every render by a microtask, including the overwhelmingly
+// common case of a script with no await in it at all.
+//
+// The flag is set on the code's last line, after the `with` block rather than
+// inside it, so the scope proxy never sees the name - and appended, so the
+// author's line numbers (which sourceUrlComment maps for devtools) don't shift
+const runSetupScript = (code: string, scope: Record<string, any>, effect: (run: () => void) => void, instanceHelpers: Record<string, any> = {}, importer: (url: string) => Promise<any> = importResource, at: ScriptLocation = {}): ScriptRun => {
   // instanceHelpers are per-component-instance additions (e.g. $emit, which
   // is bound to this instance's DOM position)
   const helpers = { ...SETUP_HELPERS, ...instanceHelpers }
   const scriptScope = new Proxy(scope, {
     has: (target, key) =>
-      key !== "$__effect" && key !== "$__import" &&
+      key !== "$__effect" && key !== "$__import" && key !== "$__state" &&
       (Reflect.has(target, key) || !(key in globalThis) && !(key in helpers)),
   })
+  const state: { done?: boolean } = {}
   const result: Promise<void> = new Function(
-    "$scope", "$__effect", "$__import", ...Object.keys(helpers),
-    `return (async () => { with ($scope) { ${code} } })()${sourceUrlComment(at.filename, at.index ?? 0)}`
-  )(scriptScope, effect, importer, ...Object.values(helpers))
+    "$scope", "$__effect", "$__import", "$__state", ...Object.keys(helpers),
+    `return (async () => { with ($scope) { ${code} }\n;$__state.done = true })()${sourceUrlComment(at.filename, at.index ?? 0)}`
+  )(scriptScope, effect, importer, state, ...Object.values(helpers))
   result.catch(error => console.error("jq79: error in :setup script", error))
   trackScript(result)
+  return { settled: result, sync: state.done === true }
 }
 
 // puts a component's declared props on the store, before any script runs and
@@ -2031,6 +2146,21 @@ const siblingsInScope = (
 // it too) without ever showing up as data
 const UNFILLED_PROPS = Symbol("jq79.unfilledProps")
 
+// how many of this render generation's scripts have yet to settle, as a live
+// box rather than a snapshot. Rides the scope chain like UNFILLED_PROPS, and
+// for one reader: a <Tag> naming no component in scope is only a mistake once
+// nothing is left that could still supply the name.
+//
+// The count is not the render gate. A script that called $mounted() released
+// the template and is still running - that is the whole point of the call - so
+// at paint time this can be non-zero, and a name arriving from a factory that
+// awaited $mounted() is exactly the case the count keeps quiet. Read live, so
+// an :if that opens after everything settled is judged against the scripts as
+// they are then, not as they were at the first paint
+const PENDING_SCRIPTS = Symbol("jq79.pendingScripts")
+
+type PendingScripts = { count: number }
+
 // default-import interop for factory scripts: real modules expose .default,
 // while importing an .html component resolves to the Component79 itself
 const interopDefault = (mod: any) => (mod && mod.default !== undefined ? mod.default : mod)
@@ -2042,7 +2172,7 @@ const interopDefault = (mod: any) => (mod && mod.default !== undefined ? mod.def
 // synchronous body invokes the factory before the first render, matching
 // setup-script timing; bodies with top-level await (static imports included)
 // resolve later and the template updates reactively
-const runFactoryScript = (code: string, scope: Record<string, any>, effect: (run: () => void) => void, instanceHelpers: Record<string, any> = {}, importer: (url: string) => Promise<any> = importResource, at: ScriptLocation = {}) => {
+const runFactoryScript = (code: string, scope: Record<string, any>, effect: (run: () => void) => void, instanceHelpers: Record<string, any> = {}, importer: (url: string) => Promise<any> = importResource, at: ScriptLocation = {}): ScriptRun => {
   const helpers = { ...SETUP_HELPERS, ...instanceHelpers }
   const $__exports: { default?: (props: Record<string, any>, ctx: Record<string, any>) => any; done?: boolean } = {}
   const result: Promise<void> = new Function(
@@ -2083,8 +2213,14 @@ const runFactoryScript = (code: string, scope: Record<string, any>, effect: (run
   // tracked through the merge, not just the module body: a factory's names
   // reach the store in `merge`, and a template expression that reads one before
   // then is not an authoring mistake (see reportExprError)
-  trackScript(result.then(invoke, logError))
+  const settled = result.then(invoke, logError)
+  trackScript(settled)
   if ($__exports.done) invoke() // fully-sync body: factory runs before first render
+  // sync only if the bindings are already on the store: a factory whose body
+  // finished but whose *factory* returned a promise (an async factory, or one
+  // that awaits $mounted()) still has names on the way, and the render gate
+  // must treat it as pending rather than race its merge
+  return { settled, sync: $__exports.done === true && merging === undefined }
 }
 
 // ---------------------------------------------------------------------------
@@ -2183,6 +2319,32 @@ export const enableHotReload = (): void => {
 
 type EmitListener = (event: CustomEvent, payload: any) => void
 
+// how long a first render may sit behind its scripts before the console says so
+const STUCK_RENDER_DELAY = 3000
+
+// a script that neither returns nor calls $mounted() holds the template
+// forever, and the failure looks like nothing at all: no error, no markup, a
+// component indistinguishable from one nobody mounted. So the wait is loud
+// after a few seconds - and it keeps waiting, because rendering on a timer
+// would make the moment of the first render depend on the machine it runs on.
+//
+// Armed only on the deferred path, so a page of synchronous components creates
+// no timers at all
+const warnIfStuck = (component: Component79, gates: Promise<void>[]) => {
+  const timer = setTimeout(() => {
+    console.warn(
+      `jq79: ${component.name ? `<${component.name}>` : "a component"}${component.filename ? ` (${component.filename})` : ""} ` +
+      `has been waiting ${STUCK_RENDER_DELAY / 1000}s for a :setup script and has rendered nothing. ` +
+      "The template waits until every script returns or calls $mounted() - add an " +
+      "await $mounted() above the slow part to render first and fill in after."
+    )
+  }, STUCK_RENDER_DELAY)
+  // unref where it exists (node/vitest): a pending timer must not be what keeps
+  // a process alive. Browsers have no such notion and no such need
+  ;(timer as any)?.unref?.()
+  Promise.all(gates).then(() => clearTimeout(timer))
+}
+
 const fetchComponent = async (url: string): Promise<Component79> => {
   const response = await fetch(url)
   if (!response.ok) throw new Error(`failed to fetch component from ${url}: ${response.status}`)
@@ -2253,6 +2415,11 @@ export class Component79 {
   private mountRoot: Element | ShadowRoot | DocumentFragment | null = null
   // settles the $mounted() promise handed to this render generation's scripts
   private resolveMounted: (() => void) | null = null
+  // whether this generation's template has been built. A render held back by a
+  // script (see the gate in renderWith) has markers but no nodes, and $mounted()
+  // must not resolve on attach alone - a script awaiting it would wake to an
+  // empty component and find nothing to query
+  private renderDone = false
   // instance-level listeners for $emit events, registered with on(). Kept
   // outside the render generation so they survive re-render and destroy()
   private emitListeners = new Map<string, Set<EmitListener>>()
@@ -2345,7 +2512,7 @@ export class Component79 {
     if (shadow) this.styleEls.forEach(el => parent.insertBefore(el, before))
     parent.insertBefore(this.content!, before)
     this.mountRoot = parent
-    this.resolveMounted?.()
+    this.settleMounted()
     return true
   }
 
@@ -2411,6 +2578,14 @@ export class Component79 {
     // (`<footer :if="$slots.footer">`). Filled at the usage site, so it can
     // only change when the tag itself re-renders - which builds a new instance
     if (this.slots) Object.defineProperty(raw, SLOTS, { value: this.slots })
+    // in place before the store wraps it, because the scripts that increment it
+    // run against the store and the template reads it back through the same
+    // scope chain. Read back out of `raw` where it is needed rather than kept
+    // in a local: this frame is on the stack for the whole of the subtree it
+    // renders, so a component nested inside itself pays for it once per level -
+    // and the depth guard at MAX_NESTING_DEPTH only beats a RangeError while
+    // this function stays small (see the note in docs/development.md)
+    Object.defineProperty(raw, PENDING_SCRIPTS, { value: { count: 0 } as PendingScripts })
 
     const store = $reactive(raw)
     const fx = createEffectScope(store)
@@ -2453,16 +2628,18 @@ export class Component79 {
       return !event.defaultPrevented
     }
 
-    // `await $mounted()` suspends a setup script until mount() attaches the
-    // component, so code below it can querySelector its own DOM. Resumption
-    // is a microtask, so in the usual synchronous render().mount() flow the
-    // whole tree (nested components included) is in the document before the
-    // script continues. If this instance is never mounted, the promise stays
-    // pending and the script's tail never runs
+    // `await $mounted()` suspends a setup script until the component is
+    // rendered *and* attached, so code below it can querySelector its own DOM.
+    // If this instance is never mounted, the promise stays pending and the
+    // script's tail never runs.
+    //
+    // Calling it is also how a script releases the first render - see the gate
+    // below - so the two halves of the contract are one call: "put me on the
+    // page, and don't wait for the rest of me"
     let resolveMounted!: () => void
     const mounted = new Promise<void>(resolve => { resolveMounted = resolve })
     this.resolveMounted = resolveMounted
-    const $mounted = () => mounted
+    this.renderDone = false
 
     // $self / $$self mirror $ / $$ but only search this instance's own
     // output: the sibling nodes between its markers. They work detached too
@@ -2533,7 +2710,31 @@ export class Component79 {
     // first line, so deferring doesn't shift the lines devtools reports for it
     const defer = (code: string) => `await $mounted();${code}`
 
+    // what the first render is still waiting for. A script holds the template
+    // back until it returns or calls $mounted() - whichever comes first - so
+    // `let rows = await fetch(...)` renders once, with rows, instead of
+    // rendering empty and filling in. `:mounted` is not a special case here: it
+    // *is* a script that yields on line 0, which is what `defer` above writes.
+    //
+    // One gate per script, not one per instance: a script yielding must not
+    // release the render on behalf of a sibling script that is still fetching
+    const gates: Promise<void>[] = []
+    let allSync = true
+
     this.scripts.forEach((script, index) => {
+      let resolveGate!: () => void
+      gates.push(new Promise<void>(resolve => { resolveGate = resolve }))
+      // whether this gate is already open on *this* stack, which is not the
+      // same as the script having finished: a script that yields immediately
+      // (`await $mounted()` on its first line, which is what `:mounted`
+      // compiles to) never finishes synchronously but holds nothing up either.
+      // Reading the promise instead would push every such render a microtask
+      // later, for no one's benefit
+      let open = false
+      const release = () => { open = true; resolveGate() }
+      // this script's own view of $mounted: the call releases its gate, the
+      // promise it returns is the instance's (one mount, one resolution)
+      const $mounted = () => { release(); return mounted }
       // the file's other components are passed as parameters of the compiled
       // script, not just left on the store's prototype: a factory script runs
       // as plain lexical JS with no `with`, so a bare `Row` in one would
@@ -2542,20 +2743,53 @@ export class Component79 {
       // parameter is what the name resolves to
       const instanceHelpers = { $mounted, $self, $$self, ...injected, ...siblingScope }
       const at: ScriptLocation = { filename: this.filename, index }
+      const deferred = ":mounted" in script.attrs
       const factoryCode = transformFactoryScript(script.content)
-      if (factoryCode !== null) {
-        declareProps(store, parseFactoryProps(script.content))
-        const body = ":mounted" in script.attrs ? defer(factoryCode) : factoryCode
-        runFactoryScript(body, store, fx.effect, instanceHelpers, $import, at)
-        return
+      const run = ((): ScriptRun => {
+        if (factoryCode !== null) {
+          // a factory publishes its names by returning them, so one that yields
+          // before it returns renders against a store where none of them exist.
+          // In factory mode `:mounted` yields on line 0, which means *always* -
+          // and unlike a setup script there is no way to put the useful half
+          // above the yield. Awaiting $mounted() inside the factory does what
+          // the author meant, and is what the message points at
+          if (deferred) {
+            console.warn(
+              "jq79: :mounted on a factory script renders the template before the factory has returned, " +
+              "so none of its bindings exist yet - await $mounted() inside the factory instead."
+            )
+          }
+          declareProps(store, parseFactoryProps(script.content))
+          const body = deferred ? defer(factoryCode) : factoryCode
+          return runFactoryScript(body, store, fx.effect, instanceHelpers, $import, at)
+        }
+        const { vars, code } = transformSetupScript(script.content)
+        declareProps(store, setupSignature(script))
+        // pre-declare script vars on the store so `with` resolves assignments
+        // to them (and reads of them) through the reactive proxy
+        vars.forEach(name => { if (!(name in store)) (store as any)[name] = undefined })
+        const body = deferred ? defer(code) : code
+        return runSetupScript(body, store, fx.effect, instanceHelpers, $import, at)
+      })()
+      // a script that threw has nothing left to contribute, so its rejection
+      // releases the gate exactly as completion does - the error is already
+      // reported by the runner, and holding the template hostage to it would
+      // turn one broken script into a blank component. It also stops counting
+      // as a source of names, for that same reason.
+      //
+      // A script that finished on this stack is counted at zero rather than
+      // incremented and decremented a microtask later: its names are on the
+      // store already, and the promise it settles through does not resolve
+      // until after the synchronous paint - which is every paint, for the
+      // components that have no await in them at all
+      if (run.sync) run.settled.then(release, release)
+      else {
+        const pending: PendingScripts = (raw as any)[PENDING_SCRIPTS]
+        pending.count++
+        const settle = () => { pending.count--; release() }
+        run.settled.then(settle, settle)
       }
-      const { vars, code } = transformSetupScript(script.content)
-      declareProps(store, setupSignature(script))
-      // pre-declare script vars on the store so `with` resolves assignments
-      // to them (and reads of them) through the reactive proxy
-      vars.forEach(name => { if (!(name in store)) (store as any)[name] = undefined })
-      const body = ":mounted" in script.attrs ? defer(code) : code
-      runSetupScript(body, store, fx.effect, instanceHelpers, $import, at)
+      if (!run.sync && !open) allSync = false
     })
 
     const content = document.createDocumentFragment()
@@ -2570,8 +2804,36 @@ export class Component79 {
           ? injected[key]
           : Reflect.get(target, key, receiver),
     })
-    content.append(this.startMarker, renderNodes(this.template, templateScope, fx, shadow), this.endMarker)
+    // the markers go in either way, so render() returns something mountable
+    // whether or not the template has been built yet: they are what detach()
+    // collects between and what the deferred pass inserts before, exactly as
+    // :if/:each anchors already work. That is what keeps render() and mount()
+    // synchronous while the first render itself is allowed to wait
+    content.append(this.startMarker, this.endMarker)
     this.content = content
+    if (allSync) {
+      // nothing is pending, so the template is built on this stack - the
+      // ordinary case, and byte-for-byte the timing render() has always had.
+      //
+      // Written out rather than routed through the closure below on purpose: a
+      // component that nests itself recurses through here, so one extra frame
+      // per level is one fewer level before the stack gives out - enough, when
+      // this was a shared `paint()`, to overflow *underneath* the depth guard
+      // at MAX_NESTING_DEPTH and turn a named error back into a RangeError
+      this.endMarker.parentNode!.insertBefore(renderNodes(this.template, templateScope, fx, shadow), this.endMarker)
+      this.renderDone = true
+      this.settleMounted()
+    } else {
+      Promise.all(gates).then(() => {
+        // destroy() nulls the markers and a re-render replaces them, so a gate
+        // that opens after either one has nothing left to paint into
+        if (marker !== this.startMarker) return
+        this.endMarker!.parentNode!.insertBefore(renderNodes(this.template, templateScope, fx, shadow), this.endMarker!)
+        this.renderDone = true
+        this.settleMounted()
+      })
+      warnIfStuck(this, gates)
+    }
 
     if (shadow) {
       this.styleEls = this.styles.map(style => {
@@ -2618,10 +2880,18 @@ export class Component79 {
     if (this.useShadow) this.styleEls.forEach(el => root.appendChild(el))
     root.appendChild(this.content!)
     this.mountRoot = root
-    this.resolveMounted?.()
+    this.settleMounted()
     return this
   }
 
+  // `await $mounted()` means "rendered and on the page", so it waits for both -
+  // whichever lands last calls this. In the ordinary synchronous flow the render
+  // is already done and this is the attach; for a component whose first render
+  // a script held back, it is the other way round
+  private settleMounted() {
+    if (this.renderDone && this.mountRoot) this.resolveMounted?.()
+  }
+
   // detaches from the DOM while keeping all state; a later mount() re-attaches
   // with any updates that happened while detached already applied
   detach(): this {
@@ -2657,6 +2927,7 @@ export class Component79 {
     this.content = null
     this.startMarker = null
     this.endMarker = null
+    this.renderDone = false
     this.data = null
     this.resolveMounted = null
     return this