jq79 0.4.12 → 0.4.14

package/src/jq79.ts

@@ -1,7 +1,7 @@
 
 import { $, $$, $create, sanitizeHTML, allowedHosts } from "./dom"
 import type { AllowUrl } from "./dom"
-import { $reactive, untracked, createEffectScope } from "./reactive"
+import { $reactive, untracked, createEffectScope, ALSO_WAKEN_BY } from "./reactive"
 import type { ReactiveDeepData, EffectScope } from "./reactive"
 import { transformSetupScript, transformFactoryScript, parsePropsPattern, parseFactoryProps, type PropDecl } from "./transform"
 
@@ -31,10 +31,16 @@ const elementAttrs = (el: Element): Record<string, string> =>
 // to decide what it's worth (nothing in a block or flex container, one space
 // between inline elements). Trimming it here, as this used to, silently glued
 // siblings together and ate the spaces in `hola <b>mundo</b> adios`
+//
+// A <template>'s children are read from its .content fragment: that is where
+// the HTML parser puts them, and its childNodes are empty. Without the descent
+// 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.childNodes).flatMap((node): (TemplateNode | string)[] => {
+  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] : []
@@ -103,7 +109,8 @@ const CONTROL_ATTRS = new Set([":attrs", ":class", ":value", ":checked", ":selec
 // single-flag shorthand) and `:props.<n>` (one spread among several) are
 // open-ended, so they're matched by prefix - they can't be enumerated into the set
 const isControlAttr = (attr: string): boolean =>
-  CONTROL_ATTRS.has(attr) || attr.startsWith(":class.") || attr.startsWith(":props.")
+  CONTROL_ATTRS.has(attr) || attr.startsWith(":class.") || attr.startsWith(":props.") ||
+  attr === ":slot" || attr.startsWith(":slot.")
 // `item in items`, `item, i in items`, `(value, key) in props` - the second
 // binding is the array index or the object key, parens optional (Vue-style).
 // The list expression can span lines, so it matches [\s\S] rather than `.`
@@ -216,6 +223,236 @@ const findComponentKey = (scope: Record<string, any>, tag: string): string | nul
   return null
 }
 
+// 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
+const MAX_NESTING_DEPTH = 200
+let nestingDepth = 0
+
+// ---------------------------------------------------------------------------
+// slots - content projection
+//
+// A component tag's children are content the child renders where it wrote a
+// <slot>. The dot marks the named variant on both sides, like :model.<name>
+// and :class.<name> already do:
+//
+//   <!-- Card.html -->        <!-- the parent -->
+//   <section>                 <Card>
+//     <header>                  <template :slot.header><h2>{{ t }}</h2></template>
+//       <slot.header>?</slot.header>
+//     </header>                 <p>{{ body }}</p>
+//   <slot />                  </Card>
+//   </section>
+//
+// Three rules decide everything below:
+//
+// 1. Content belongs to the parent - its AST, its scope, its effects, its
+//    scoped styles. The child decides *where* it goes and *whether* it goes,
+//    never what the names in it mean.
+// 2. Slot props are declared, not injected: `:slot="{ item }"` on the usage
+//    site, for the same reason :each writes `item in rows`. Every bare name in
+//    the parent's file is introduced by the parent, so a `<slot :item>` the
+//    child adds later can't silently capture one.
+// 3. What isn't projected isn't rendered. No <slot>, or one behind a false
+//    :if, and the content's effects never exist.
+//
+// The content travels as a thunk, not as DOM: an instance is replaced (a
+// definition swap, a hot reload) and one <slot> may render many times, so a
+// pre-rendered fragment would leak effects and could only be inserted once
+// ---------------------------------------------------------------------------
+
+// renders one slot's content at the position the child put the <slot>: it is
+// handed the slot's props (lazy, so each read re-evaluates in the child's
+// scope), that position's scope and effect scope, and the style mode the
+// child renders under
+type SlotRenderer = (
+  props: Record<string, () => any>,
+  slotScope: Record<string, any>,
+  fx: EffectScope,
+  shadow: boolean
+) => Node
+
+type SlotMap = Record<string, SlotRenderer>
+
+// the content an instance was handed, by slot name. Symbol-keyed and
+// non-enumerable on the store's data, like UNFILLED_PROPS: it rides the scope
+// chain (so a <slot> inside an :each or a :with finds it) and never shows up
+// as data - not in Object.keys, not in a snapshot spread, not in the props a
+// nested component is handed
+const SLOTS = Symbol("jq79.slots")
+
+// <slot>, <slot.header-bar>: the hole and its name. Names are kebab-case where
+// written (the HTML parser lowercases tag names and attribute modifiers alike)
+// and camelCase where read - <slot.header-bar> is :slot.header-bar is
+// $slots.headerBar
+const isSlotTag = (tag: string): boolean => tag === "slot" || tag.startsWith("slot.")
+
+const slotName = (suffix: string): string => (suffix ? kebabToCamel(suffix) : "default")
+
+// the content of one slot, as written at the usage site
+type SlotContent = { nodes: (TemplateNode | string)[]; binder?: string }
+
+// the :slot attribute of a <template>, if it carries one
+const slotAttrOf = (node: TemplateNode): string | undefined =>
+  Object.keys(node.attrs).find(attr => attr === ":slot" || attr.startsWith(":slot."))
+
+const slotAttrName = (name: string) => (name === "default" ? ":slot" : `:slot.${name}`)
+
+// whitespace-only text between two <template :slot> blocks is the indentation
+// between them and nothing else - the same call renderNodes makes between the
+// branches of an :if chain. It is what decides whether a tag has default
+// content at all, which is what $slots.default answers
+const isMeaningful = (node: TemplateNode | string): boolean => typeof node !== "string" || node.trim() !== ""
+
+// a component tag's children, partitioned by slot name: a direct
+// <template :slot.<name>> child fills that name, everything else is the
+// default slot's content. The attribute's value is the pattern the content
+// binds the slot's props to - on the tag itself for the default, since the
+// default content has no <template> of its own to carry it
+const partitionSlots = (node: TemplateNode): Record<string, SlotContent> => {
+  const contents: Record<string, SlotContent> = {}
+  const loose: (TemplateNode | string)[] = []
+
+  node.children.forEach(child => {
+    const attr = typeof child === "object" && child.tag === "template" ? slotAttrOf(child) : undefined
+    if (typeof child === "string" || attr === undefined) {
+      loose.push(child)
+      return
+    }
+    const name = slotName(attr.slice(":slot.".length))
+    // first wins, like two <template name="X"> in one file: a duplicate is a
+    // typo, and the fix is to delete one - not to guess which
+    if (name in contents) {
+      console.warn(`jq79: two <template ${slotAttrName(name)}> in <${node.tag}>; the second was ignored`)
+      return
+    }
+    contents[name] = { nodes: child.children, binder: child.attrs[attr] || undefined }
+  })
+
+  const hasLoose = loose.some(isMeaningful)
+  if (hasLoose && "default" in contents) {
+    console.warn(
+      `jq79: <${node.tag}> has both a <template :slot> and content outside it - ` +
+      "the <template> is the default slot's content, and the rest was ignored"
+    )
+  } else if (hasLoose) {
+    contents.default = { nodes: loose, binder: node.attrs[":slot"] || undefined }
+  }
+  return contents
+}
+
+// `:slot="{ item, index: i, total = 0 }"` - the names the content binds the
+// slot's props to. The bindings are accessors, not values: each read
+// re-evaluates the child's expression, so an effect that reads `item` tracks
+// exactly what that expression touches, on every run (createWithScope's design)
+const bindSlotProps = (scope: Record<string, any>, binder: string | undefined, props: Record<string, () => any>) => {
+  parsePropsPattern(binder)?.forEach(({ name, as, default: fallback }) => {
+    const local = as ?? name
+    Object.defineProperty(scope, local, {
+      enumerable: true,
+      configurable: true,
+      get: () => {
+        const value = props[name]?.()
+        return value === undefined && fallback !== undefined ? evalExpr(fallback, scope) : value
+      },
+      // a slot prop is the child's value: it arrives on every read and there
+      // is nowhere for a write to go. Silence would be worse - `with` swallows
+      // an assignment to a getter without a word
+      set: () => console.warn(`jq79: "${local}" is a slot prop - it comes from the component, so assigning to it does nothing`),
+    })
+  })
+}
+
+// a <template :slot> only fills a slot as a direct child of a component tag,
+// where the usage site takes it out of the children before they are ever
+// rendered (see partitionSlots). Anywhere else the position is a mistake, and
+// rendering the content in place - in the wrong scope, into a <template>
+// nobody clones - would be a strange way to say so. A comment rather than
+// nothing: an :if branch needs a node to hold on to (see boundsOf)
+const misplacedSlotContent = (node: TemplateNode): Node => {
+  const attr = slotAttrOf(node)
+  console.warn(`jq79: <template ${attr}> fills a slot only as a direct child of a component tag; here it rendered nothing`)
+  return document.createComment(`misplaced ${attr}`)
+}
+
+// what a usage site hands its instance: every slot it filled, as the thunk
+// that renders it. Built once per site, and in one call - a component tag is
+// on the stack while its whole subtree renders below it (a component that
+// renders itself does this 200 deep), so the intermediates stay in here rather
+// than in the frame that waits
+const buildSlots = (node: TemplateNode, scope: Record<string, any>): SlotMap | null => {
+  const contents = Object.entries(partitionSlots(node))
+  if (!contents.length) return null
+  const slots: SlotMap = {}
+  contents.forEach(([name, content]) => { slots[name] = makeSlotRenderer(content, scope) })
+  return slots
+}
+
+// the thunk one slot's content becomes: the usage site closes over its AST and
+// its scope, the child calls it wherever (and however many times) it renders
+// the matching <slot>
+const makeSlotRenderer = (content: SlotContent, parentScope: Record<string, any>): SlotRenderer =>
+  (props, slotScope, fx, shadow) => {
+    // the parent's scope, plus the names the content declared for the slot's
+    // props (rule 1: what the content says is decided where it was written)
+    const scope: Record<string, any> = Object.create(parentScope)
+    bindSlotProps(scope, content.binder, props)
+    // this content reads the parent's store (its own names) and the child's
+    // (through the slot props), so every effect created anywhere inside it is
+    // registered with both - see ALSO_WAKEN_BY. Appended rather than assigned:
+    // content forwarded through a <slot> inside slot content is still woken by
+    // the store it came from
+    const inherited: Record<string, any>[] = (scope as any)[ALSO_WAKEN_BY] ?? []
+    Object.defineProperty(scope, ALSO_WAKEN_BY, { value: [...inherited, slotScope] })
+
+    const contentFx = createEffectScope(scope)
+    // rule 3: the <slot> is the content's lifetime. When the child's subtree at
+    // this position goes - an :if turning false, the instance being replaced,
+    // the whole child being destroyed - the content's effects go with it
+    fx.onDispose(() => contentFx.dispose())
+    return renderNodes(content.nodes, scope, contentFx, shadow)
+  }
+
+// <slot />, <slot.name>fallback</slot.name>: where the parent's content goes.
+// Unfilled, the slot renders its own children instead - in this component's
+// scope, since that content is this component's. Every attribute that isn't a
+// directive is a slot prop: `:item="item"` evaluates here and reaches the
+// content under the name it declared, a plain attribute passes a literal
+// string, and there are no reserved names (the slot's own name is in the tag).
+// Bracketed by anchors like a nested component, so the chunk has stable bounds
+// even when it renders nothing (see boundsOf)
+const renderSlot = (node: TemplateNode, scope: Record<string, any>, fx: EffectScope, shadow: boolean): Node => {
+  const name = slotName(node.tag.slice("slot.".length))
+  const wrapper = document.createDocumentFragment()
+  const anchor = document.createComment(node.tag)
+  const endAnchor = document.createComment(`/${node.tag}`)
+  wrapper.append(anchor, endAnchor)
+
+  const render = (scope as any)[SLOTS]?.[name] as SlotRenderer | undefined
+  if (!render) {
+    wrapper.insertBefore(renderNodes(node.children, scope, fx, shadow), endAnchor)
+    return wrapper
+  }
+
+  const props: Record<string, () => any> = {}
+  Object.entries(node.attrs).forEach(([attr, value]) => {
+    // the scope stamp is the component's, not a prop; @events have no element
+    // to bind here; and a directive means what it means everywhere else -
+    // :if/:each/:with decide whether and how often this slot renders, so they
+    // are the renderer's, not the content's
+    if (attr === SCOPE_ATTR || isControlAttr(attr) || attr.startsWith("@")) return
+    if (attr.startsWith(":")) {
+      const expr = value || attr.slice(1)
+      props[kebabToCamel(attr.slice(1))] = () => evalExpr(expr, scope)
+    } else {
+      props[kebabToCamel(attr)] = () => value
+    }
+  })
+
+  wrapper.insertBefore(render(props, scope, fx, shadow), endAnchor)
+  return wrapper
+}
+
 // <MyComponent :user :title="'str'"></MyComponent> - renders a child
 // component instance at this position. Props: `:name="expr"` evaluates expr
 // in the parent scope (`:name` alone is shorthand for `:name="name"`), plain
@@ -239,6 +476,11 @@ const renderNestedComponent = (key: string, node: TemplateNode, scope: Record<st
   const wrapper = document.createDocumentFragment()
   wrapper.append(anchor, endAnchor)
 
+  // the tag's children, as content for the child's <slot>s. Built once per
+  // usage site (the AST doesn't change) and closed over the parent's scope
+  // here, so every instance this site ever renders is handed the same thunks
+  const slots = buildSlots(node, scope)
+
   const props: Record<string, string> = {} // prop name -> expression in parent scope
   const models: Record<string, string> = {} // model name -> assignable expression in parent scope
   const events: Array<[string, string]> = [] // @attr (modifiers included) -> handler expression
@@ -329,9 +571,34 @@ const renderNestedComponent = (key: string, node: TemplateNode, scope: Record<st
   let currentDef: Component79 | null = null
   let childFx: EffectScope | null = null
 
+  // a usage site that resolves to no component renders nothing, which is
+  // deliberate - `undefined` while an `await import(...)` is in flight has to
+  // wait quietly, and the child appears when it lands. Two cases can never
+  // resolve, though, and both are wiring mistakes worth naming: a value that
+  // isn't a component (and so will never become one by waiting), and a name
+  // the component declared as a prop that the parent passed nothing for. Once
+  // each, per usage site: an effect re-runs
+  const reported = new Set<string>()
+  const reportUnresolved = (value: any) => {
+    if (value === undefined || value === null) {
+      const unfilled: Set<string> | undefined = (scope as any)[UNFILLED_PROPS]
+      if (!unfilled?.has(key) || reported.has("unfilled")) return
+      reported.add("unfilled")
+      console.error(
+        `jq79: <${node.tag}> is declared as a prop and the parent passed nothing - nothing renders here. ` +
+        `Pass it (:${key}="…"), or drop it from the signature to use the one declared in this file.`
+      )
+      return
+    }
+    if (reported.has("type")) return
+    reported.add("type")
+    console.error(`jq79: <${node.tag}> is ${typeof value}, not a component - nothing renders here`)
+  }
+
   fx.effect(() => {
     const value = evalExpr(key, scope)
     const nextDef = value instanceof Component79 ? value : null
+    if (!nextDef) reportUnresolved(value)
     if (nextDef === currentDef) return
 
     childFx?.dispose()
@@ -349,7 +616,15 @@ const renderNestedComponent = (key: string, node: TemplateNode, scope: Record<st
       styles: nextDef.styles,
       modules: nextDef.modules,
       filename: nextDef.filename,
+      // its file's other components, and which of them it is: without the
+      // first a child rendered here loses the siblings its definition could
+      // see, and without the second hot reload can't tell it what it is
+      siblings: nextDef.siblings,
+      name: nextDef.name,
     })
+    // the content this site wrote inside the tag, before the first render: a
+    // <slot> is resolved while rendering, so the map has to be there by then
+    if (slots) instance.slots = slots
     // the writeback half of :model - one event, one contract. The name is
     // normalized like the attribute was (kebab->camel; absent means default),
     // and everything off-contract warns and does nothing: an event protocol's
@@ -395,7 +670,24 @@ const renderNestedComponent = (key: string, node: TemplateNode, scope: Record<st
     // shadow-rendered child keeps its <style> elements inline, next to the DOM
     // they style, and the parent's shadow root is what scopes both
     const holder = document.createDocumentFragment()
-    ;(shadow ? instance.renderShadow(seed) : instance.render(seed)).mount(holder)
+    // rendering a child happens on this same stack, so a component that
+    // renders itself recurses as deep as its data does - and a cycle in that
+    // data would recurse until the JS stack gave out, ~900 identical frames
+    // naming nothing. Cut and named instead, exactly like the effect runner
+    // cuts an effect that wakes itself
+    if (nestingDepth >= MAX_NESTING_DEPTH) {
+      console.error(
+        `jq79: <${node.tag}> is ${MAX_NESTING_DEPTH} levels deep inside itself; giving up here. ` +
+        "A component that renders itself stops when its data stops - is there a cycle in it?"
+      )
+      return
+    }
+    nestingDepth++
+    try {
+      ;(shadow ? instance.renderShadow(seed) : instance.render(seed)).mount(holder)
+    } finally {
+      nestingDepth--
+    }
     endAnchor.parentNode!.insertBefore(holder, endAnchor)
 
     const syncFx = createEffectScope(scope)
@@ -515,6 +807,12 @@ const renderNode = (node: TemplateNode, outerScope: Record<string, any>, fx: Eff
   const withExpr = node.attrs[":with"]
   const scope = withExpr !== undefined ? createWithScope(withExpr, outerScope) : outerScope
 
+  // before the component-key scan, so <slot> is <slot> even in a file that
+  // happens to have a component named Slot in scope: the tag is the library's
+  // now, and a name that resolved it away would be a very quiet surprise
+  if (isSlotTag(node.tag)) return renderSlot(node, scope, fx, shadow)
+  if (node.tag === "template" && slotAttrOf(node) !== undefined) return misplacedSlotContent(node)
+
   const componentKey = findComponentKey(scope, node.tag)
   if (componentKey) return renderNestedComponent(componentKey, node, scope, fx, shadow)
 
@@ -618,6 +916,13 @@ const renderNode = (node: TemplateNode, outerScope: Record<string, any>, fx: Eff
       const options = allowedExpr !== undefined ? { allowUrl: normalizeAllowUrl(evalExpr(allowedExpr, scope)) } : undefined
       el.innerHTML = sanitizeHTML(String(evalExpr(htmlExpr, scope) ?? ""), options)
     })
+  } else if (el instanceof HTMLTemplateElement) {
+    // a plain nested <template> stays what HTML says it is: an inert element
+    // whose children live in .content, which is where whoever clones it looks
+    // for them. They render (bindings and all) and go there - appended as
+    // childNodes they would be in the DOM but in no document fragment, seen by
+    // nothing and rendered by nobody
+    el.content.appendChild(renderNodes(node.children, scope, fx, shadow))
   } else {
     el.appendChild(renderNodes(node.children, scope, fx, shadow))
   }
@@ -889,6 +1194,15 @@ type ComponentParts = {
   // where this component came from (a URL for fetch(), a path for the vite
   // plugin). Names the setup scripts in devtools - see scriptSourceUrl
   filename?: string
+  // the components the file's <template name="..."> blocks declared, by name.
+  // Every component parsed out of one file holds this same map - itself
+  // included - which is what makes a sibling usable without an import, and
+  // what lets a <template name="TreeNode"> render a <TreeNode>
+  siblings?: Record<string, Component79>
+  // which of the file's components this is: a template's name, or undefined
+  // for the file's own. The file is the hot-reload unit, so a reparse hands
+  // each live instance the parts belonging to the component it is
+  name?: string
 }
 
 const VOID_ELEMENTS = new Set([
@@ -897,8 +1211,10 @@ const VOID_ELEMENTS = new Set([
 ])
 
 // a self-closing tag with its attributes; quoted attribute values are matched
-// as whole chunks so a "/>" inside one doesn't end the tag early
-const SELF_CLOSING_RE = /<([A-Za-z][\w-]*)((?:"[^"]*"|'[^']*'|[^>"'])*?)\/>/g
+// as whole chunks so a "/>" inside one doesn't end the tag early. The tag name
+// admits a dot for the named forms of a tag - <slot.header /> - which is a
+// legal HTML tag name (the tokenizer reads to the first space, "/" or ">")
+const SELF_CLOSING_RE = /<([A-Za-z][\w.-]*)((?:"[^"]*"|'[^']*'|[^>"'])*?)\/>/g
 const RAW_BLOCK_RE = /(<script[\s\S]*?<\/script\s*>|<style[\s\S]*?<\/style\s*>)/gi
 
 // expands self-closing tags (<MyComponent />, <div />) into explicit
@@ -921,7 +1237,7 @@ const expandSelfClosingTags = (src: string): string =>
 // a start tag with its attributes, quote-aware so a ">" inside a value doesn't
 // end it early; and a single spread attribute in name position (preceded by
 // start-or-whitespace), its expression an identifier or member path
-const OPEN_TAG_RE = /<([A-Za-z][\w-]*)((?:"[^"]*"|'[^']*'|[^>"'])*)>/g
+const OPEN_TAG_RE = /<([A-Za-z][\w.-]*)((?:"[^"]*"|'[^']*'|[^>"'])*)>/g
 const ATTR_SPREAD_RE = /"[^"]*"|'[^']*'|(^|\s)\.\.\.([A-Za-z_$][\w$.]*)/g
 
 // `...expr` as an attribute is sugar for :props="expr" (spread an object's
@@ -1015,9 +1331,16 @@ const scopeCss = (css: string, scope: string): string => {
   return Array.from(sheet.cssRules).map(rule => rule.cssText).join("\n")
 }
 
+// a component name has to be PascalCase to be usable: findComponentKey only
+// ever considers capitalized scope keys, so a lowercase name would declare a
+// component no tag could reference. It is also what keeps the named exports
+// from colliding with a definition's own fields, which are all lowercase
+const COMPONENT_NAME_RE = /^[A-Z][A-Za-z0-9]*$/
+
 // converts a string of HTML into an AST representation of the component:
 // - template: the non-script/style top-level elements, as TemplateNodes
 // - scripts/styles: { attrs, content } blocks in source order
+// - siblings: the components its top-level <template name="..."> declared
 const parseComponentString = (component: string): ComponentParts => {
   // example
   // <script :setup="{ fname, lname }">
@@ -1043,11 +1366,64 @@ const parseComponentString = (component: string): ComponentParts => {
   const parsedDOM = new DOMParser().parseFromString(`<template>${prepared}</template>`, "text/html")
   const root = parsedDOM.querySelector("template") as HTMLTemplateElement
 
+  // a top-level <template> declares another component of this file; everything
+  // else is this one's own
+  const own: Element[] = []
+  const declarations: HTMLTemplateElement[] = []
+  Array.from(root.content.children).forEach(el => {
+    if (el.tagName === "TEMPLATE") declarations.push(el as HTMLTemplateElement)
+    else own.push(el)
+  })
+
+  // the file's own component hashes the whole file: every component in it
+  // re-renders on any edit anyway (the file is the hot-reload unit), so a
+  // stamp that changes when a sibling is edited costs nothing, and scopeHash
+  // gets to keep hashing the source it was handed
+  const parts = componentPartsFrom(own, component)
+
+  // one map, shared by reference: it is filled below, after each definition
+  // has already been handed it, so every component of the file sees all the
+  // others *and itself* - which is what makes a recursive component possible
+  const siblings: Record<string, Component79> = {}
+  declarations.forEach(el => {
+    const name = el.getAttribute("name")
+    // ignored rather than fatal, like every other malformed thing here: a bad
+    // save mid-typing must not take the page down, least of all under HMR
+    if (name === null) {
+      console.warn("jq79: a top-level <template> without a name declares nothing and was ignored")
+      return
+    }
+    if (!COMPONENT_NAME_RE.test(name)) {
+      console.warn(
+        `jq79: <template name="${name}"> was ignored - a component name has to be PascalCase, ` +
+        "or no tag could ever reference it (only capitalized names resolve as components)"
+      )
+      return
+    }
+    if (name in siblings) {
+      console.warn(`jq79: two <template name="${name}"> in one file; the second was ignored`)
+      return
+    }
+    // its own source is its own scope: a named template is a shadow root
+    // inside a shadow root, so the file's scoped rules stop at its boundary
+    // and its own stop there too
+    siblings[name] = new Component79({ ...componentPartsFrom(Array.from(el.content.children), el.innerHTML), siblings, name })
+  })
+  if (Object.keys(siblings).length) parts.siblings = siblings
+
+  return parts
+}
+
+// the script/style/markup split of one component's top-level elements, with
+// <style scoped> resolved against the source those elements came from - the
+// whole file for its own component, a <template>'s contents for a named one,
+// so the two get different stamps and neither can style the other
+const componentPartsFrom = (elements: Element[], hashSource: string): ComponentParts => {
   const scripts: TagBlock[] = []
   const styles: TagBlock[] = []
   const template: TemplateNode[] = []
 
-  Array.from(root.content.children).forEach(el => {
+  elements.forEach(el => {
     const block: TagBlock = { attrs: elementAttrs(el), content: el.textContent ?? "" }
 
     if (el.tagName === "SCRIPT") scripts.push(block)
@@ -1074,7 +1450,7 @@ const parseComponentString = (component: string): ComponentParts => {
   // in something that isn't CSS yet would only garble what devtools shows
   const isScoped = (style: TagBlock) => "scoped" in style.attrs && !("lang" in style.attrs)
   if (styles.some(isScoped)) {
-    const scope = scopeHash(component)
+    const scope = scopeHash(hashSource)
     stampScope(template, scope)
     styles.forEach(style => {
       if (isScoped(style)) style.scoped = scopeCss(style.content, scope)
@@ -1193,6 +1569,50 @@ const declareProps = (store: Record<string, any>, props: PropDecl[] | null) => {
   })
 }
 
+// every prop name a component's scripts declare, across both script modes.
+// Read before the store exists, because what a component declares decides
+// which of its file's sibling components it can still see: declaring a name
+// says it comes from the parent, so the file's own definition of that name is
+// deliberately not in this component's scope
+const declaredPropNames = (scripts: TagBlock[]): Set<string> => {
+  const names = new Set<string>()
+  scripts.forEach(script => {
+    const declarations = parseFactoryProps(script.content) ?? parsePropsPattern(script.attrs[":setup"])
+    declarations?.forEach(({ name }) => names.add(name))
+  })
+  return names
+}
+
+// the sibling components this one resolves by name, or null when there are
+// none left to resolve. They go on the store's *prototype* rather than in it:
+// the component-key scan walks the chain, so <Row> resolves; they stay out of
+// the data, so Object.keys, snapshots and spreads never see them; and an own
+// key shadows a prototype one, so a prop the parent did pass wins for free
+const siblingsInScope = (
+  siblings: Record<string, Component79> | undefined,
+  declared: Set<string>
+): Record<string, Component79> | null => {
+  if (!siblings) return null
+  // null-prototype, for the same reason storeApi is: `key in scope` must not
+  // start answering true for toString, constructor and the rest
+  const inScope: Record<string, Component79> = Object.create(null)
+  let any = false
+  Object.entries(siblings).forEach(([name, component]) => {
+    if (declared.has(name)) return
+    inScope[name] = component
+    any = true
+  })
+  return any ? inScope : null
+}
+
+// names a component declared as props and the parent passed nothing for. Such
+// a name can never become a component later - there is no binding on the tag
+// to update it - so a <Tag> reading one is a wiring mistake that can be named
+// on sight, unlike the `undefined` of an import still in flight. Symbol-keyed
+// and non-enumerable: it rides the scope chain (so an :each item scope finds
+// it too) without ever showing up as data
+const UNFILLED_PROPS = Symbol("jq79.unfilledProps")
+
 // 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)
@@ -1297,6 +1717,13 @@ export const hotUpdate = (filename: string, src: string): number => {
   // parsed once and shared by every instance - which is already what a
   // definition and the clones :component makes from it do
   const parts = parseComponentString(src)
+  // the file is the hot-reload unit, so one reparse serves every component it
+  // declares: an instance is handed the parts of the component it *is*, by
+  // name. A name that is no longer in the file (a <template> renamed or
+  // deleted) has no parts to be given, and only a reload can fix the page
+  let orphaned = false
+  const partsFor = (instance: Component79): ComponentParts | null =>
+    instance.name === undefined ? parts : parts.siblings?.[instance.name] ?? null
 
   let rerendered = 0
   for (const [name, refs] of hotRegistry) {
@@ -1307,11 +1734,16 @@ export const hotUpdate = (filename: string, src: string): number => {
         refs.delete(ref) // collected since the last update
         continue
       }
-      if (instance.hotReplace(parts)) rerendered++
+      const next = partsFor(instance)
+      if (!next) {
+        orphaned = true
+        continue
+      }
+      if (instance.hotReplace(next)) rerendered++
     }
     if (!refs.size) hotRegistry.delete(name)
   }
-  return rerendered
+  return orphaned ? 0 : rerendered
 }
 
 // starts tracking instances, so hotUpdate can find them. jq79/dev's client
@@ -1324,6 +1756,14 @@ export const enableHotReload = (): void => {
 
 type EmitListener = (event: CustomEvent, payload: any) => void
 
+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}`)
+  // the URL names the component's scripts in devtools, and is where the
+  // browser will look for the source when a breakpoint lands in one
+  return new Component79(await response.text(), { filename: url })
+}
+
 // a parsed single-file component. Typical lifecycle:
 //
 //   const jq79 = new Component79(src)   // or await Component79.fetch(url)
@@ -1341,6 +1781,20 @@ export class Component79 {
   modules?: Record<string, any>
   // the component's origin, used to name its scripts in devtools
   filename?: string
+  // the other components declared in the same file, by name (see
+  // ComponentParts.siblings). They are also this definition's own properties,
+  // so `const { Row } = await Component79.fetch(url)` reaches them
+  siblings?: Record<string, Component79>
+  // this component's name inside its file, for the components a <template>
+  // declared; the file's own component has none - it is the default, and a
+  // default is named by whoever imports it
+  name?: string
+  // the content the usage site handed this instance, by slot name (see the
+  // slots section). Not part of a definition - it belongs to the tag that
+  // wrote it - so renderNestedComponent sets it on the instance it creates,
+  // and every render reads it from here: a hot reload re-renders from a data
+  // snapshot, which a symbol on the store would not survive
+  slots?: SlotMap
 
   data: ReactiveDeepData<Record<string, any>> | null = null
 
@@ -1372,9 +1826,29 @@ export class Component79 {
     this.styles = parts.styles
     this.modules = options.modules ?? (typeof src === "string" ? undefined : src.modules)
     this.filename = options.filename ?? (typeof src === "string" ? undefined : src.filename)
+    this.siblings = parts.siblings
+    this.name = parts.name
+    this.adoptSiblings()
     hotRegister(this) // a no-op unless the page enabled hot reload
   }
 
+  // the parser builds a file's sibling definitions before anyone has told it
+  // where the file came from, so whoever holds the parse hands its origin down
+  // - and keeps doing it after a hot reload, which parses the file afresh.
+  // Without it a reloaded child would have no filename, and an instance with
+  // no filename is not tracked: the next edit would never reach it
+  private adoptSiblings() {
+    if (!this.siblings) return
+    Object.entries(this.siblings).forEach(([name, sibling]) => {
+      sibling.filename ??= this.filename
+      sibling.modules ??= this.modules
+      // the file's own component also *is* the file: its named components hang
+      // off it as properties, which is what `const { Row } = …` reads (and
+      // what the bundler re-exports by name)
+      if (!this.name) (this as any)[name] = sibling
+    })
+  }
+
   // swaps this component's parsed parts for `src`'s and, if it is on the page,
   // re-renders it where it stands - seeded with a snapshot of its data, so
   // props and store values survive (the setup script runs again, so whatever it
@@ -1410,6 +1884,11 @@ export class Component79 {
     this.template = parts.template
     this.scripts = parts.scripts
     this.styles = parts.styles
+    // the file's other components as they are now: the next render resolves
+    // <Row> against these, so a parent picks up an edited child even when the
+    // child's own instances are patched separately
+    this.siblings = parts.siblings
+    this.adoptSiblings()
     if (!rendered) return false // a definition: its clones re-render themselves
 
     this.renderWith(data, shadow)
@@ -1424,12 +1903,13 @@ export class Component79 {
     return true
   }
 
-  static async fetch(url: string): Promise<Component79> {
-    const response = await fetch(url)
-    if (!response.ok) throw new Error(`failed to fetch component from ${url}: ${response.status}`)
-    // the URL names the component's scripts in devtools, and is where the
-    // browser will look for the source when a breakpoint lands in one
-    return new Component79(await response.text(), { filename: url })
+  static fetch(url: string): Promise<Component79>
+  static fetch(urls: string[]): Promise<Component79[]>
+  // an array of URLs fetches them all at once and resolves to the components in
+  // the same order, so one await destructures them - and, like Promise.all, the
+  // first failure rejects the whole thing
+  static fetch(urls: string | string[]): Promise<Component79 | Component79[]> {
+    return Array.isArray(urls) ? Promise.all(urls.map(fetchComponent)) : fetchComponent(urls)
   }
 
   // subscribes to this instance's $emit events, on top of the DOM CustomEvent
@@ -1460,7 +1940,23 @@ export class Component79 {
   private renderWith(data: Record<string, any>, shadow: boolean): this {
     this.destroy()
 
-    const store = $reactive({ ...data })
+    // what this component can see of its file's other components, and which of
+    // its declared props arrived empty - both decided by the signature, before
+    // the store exists (see siblingsInScope / UNFILLED_PROPS)
+    const declared = declaredPropNames(this.scripts)
+    const siblingScope = siblingsInScope(this.siblings, declared)
+    const raw: Record<string, any> = siblingScope
+      ? Object.assign(Object.create(siblingScope), data)
+      : { ...data }
+    const unfilled = new Set([...declared].filter(name => !(name in data)))
+    if (unfilled.size) Object.defineProperty(raw, UNFILLED_PROPS, { value: unfilled })
+    // the slot content, for the <slot>s the template renders, and the static
+    // map of which names were filled, for the component to ask about
+    // (`<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 })
+
+    const store = $reactive(raw)
     const fx = createEffectScope(store)
     this.data = store
     this.fx = fx
@@ -1528,6 +2024,20 @@ export class Component79 {
     const $import = (url: string): Promise<any> =>
       modules && url in modules ? Promise.resolve(modules[url]) : importResource(url)
 
+    // the names a component answers on top of its store: $emit, so an inline
+    // handler can emit without routing through a setup function
+    // (@input="$emit('update', $event.target.value)"), and $slots, the static
+    // map of the names the usage site filled, so a wrapper can be dropped when
+    // nothing filled it (<footer :if="$slots.footer">). Both reach the
+    // template (through templateScope, below) and both script modes (as
+    // instance helpers), and a same-named store key shadows either.
+    // Null-prototype, for the same reason storeApi is: `key in injected` must
+    // not start answering true for toString, constructor and the rest
+    const injected: Record<string, any> = Object.assign(Object.create(null), {
+      $emit,
+      $slots: Object.fromEntries(Object.keys(this.slots ?? {}).map(name => [name, true])),
+    })
+
     // scripts run before the template renders so `$:` values are initialized;
     // a `:mounted` script defers entirely until mount() instead. A top-level
     // `export default` switches the script to factory mode (plain lexical JS)
@@ -1536,7 +2046,13 @@ export class Component79 {
     const defer = (code: string) => `await $mounted();${code}`
 
     this.scripts.forEach((script, index) => {
-      const instanceHelpers = { $emit, $mounted, $self, $$self }
+      // 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
+      // resolve to nothing at all. In setup mode this composes with `with` -
+      // scriptScope's `has` declines any name that is a helper, so the
+      // parameter is what the name resolves to
+      const instanceHelpers = { $mounted, $self, $$self, ...injected, ...siblingScope }
       const at: ScriptLocation = { filename: this.filename, index }
       const factoryCode = transformFactoryScript(script.content)
       if (factoryCode !== null) {
@@ -1555,16 +2071,16 @@ export class Component79 {
     })
 
     const content = document.createDocumentFragment()
-    // the template renders under a scope that also answers $emit (unless the
-    // store shadows the name), so an inline handler can emit without routing
-    // through a setup function: @input="$emit('update', $event.target.value)".
-    // has/get only - never an own key - so Object.keys, snapshot spreads and
-    // the component-key scan don't see it, and every read still forwards
-    // through the reactive store, keeping dependency tracking intact
+    // the injected names, served by has/get only - never as own keys - so
+    // Object.keys, snapshot spreads and the component-key scan don't see them,
+    // and every read still forwards through the reactive store, keeping
+    // dependency tracking intact
     const templateScope = new Proxy(store as Record<string, any>, {
-      has: (target, key) => key === "$emit" || Reflect.has(target, key),
+      has: (target, key) => (typeof key === "string" && key in injected) || Reflect.has(target, key),
       get: (target, key, receiver) =>
-        key === "$emit" && !Reflect.has(target, key) ? $emit : Reflect.get(target, key, receiver),
+        typeof key === "string" && key in injected && !Reflect.has(target, key)
+          ? injected[key]
+          : Reflect.get(target, key, receiver),
     })
     content.append(this.startMarker, renderNodes(this.template, templateScope, fx, shadow), this.endMarker)
     this.content = content