jq79 0.6.3 → 0.6.5

package/src/jq79.ts

@@ -3,7 +3,7 @@ import { $, $$, $create, sanitizeHTML, allowedHosts } from "./dom"
 import type { AllowUrl } from "./dom"
 import { $reactive, $toRaw, untracked, createEffectScope, ALSO_WAKEN_BY } from "./reactive"
 import type { ReactiveDeepData, EffectScope } from "./reactive"
-import { transformSetupScript, transformFactoryScript, parsePropsPattern, parseFactoryProps, type PropDecl } from "./transform"
+import { transformSetupScript, transformFactoryScript, parsePropsPattern, parseFactoryProps, freeIdentifiers, type PropDecl } from "./transform"
 
 export { $, $$, $create } from "./dom"
 export { $reactive, $toRaw } from "./reactive"
@@ -25,6 +25,13 @@ type TemplateNode = {
   // parse (see stampComponentTag) and lifted off attrs here, where it stops
   // looking like an attribute to every loop downstream
   component?: string
+  // the element's namespace, present only when it is NOT HTML - an <svg>
+  // subtree, or MathML. Read straight off the parsed tree, because the HTML
+  // parser has already run the foreign-content algorithm over it and knows
+  // things a tag name cannot say: whether this <title> is SVG's or HTML's, and
+  // where a <foreignObject> hands the namespace back. Absent is the common
+  // case and means HTML, so an ordinary node is exactly the shape it was
+  ns?: string
 }
 
 type TagBlock = {
@@ -51,17 +58,25 @@ 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 HTML_NS = "http://www.w3.org/1999/xhtml"
+
 const elementToAST = (el: Element): TemplateNode => {
   const attrs = elementAttrs(el)
+  // `tagName` is uppercase for HTML and as-authored for everything else, so the
+  // lowercasing that normalizes <DIV> would destroy <clipPath>, <linearGradient>
+  // and <feGaussianBlur>, whose names are case-sensitive
+  const ns = el.namespaceURI
   // 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]
+  const foreign = ns !== null && ns !== HTML_NS
   return {
-    tag: el.tagName.toLowerCase(),
+    tag: foreign ? el.tagName : el.tagName.toLowerCase(),
     attrs,
     ...(component === undefined ? {} : { component }),
+    ...(foreign ? { ns } : {}),
     children: Array.from((el instanceof HTMLTemplateElement ? el.content : el).childNodes).flatMap((node): (TemplateNode | string)[] => {
       if (node.nodeType === Node.TEXT_NODE) {
         const text = node.textContent ?? ""
@@ -89,24 +104,107 @@ const elementToAST = (el: Element): TemplateNode => {
 // expression compiled with and without $event is two different functions. A
 // syntactically invalid expression caches its failure (null) so it isn't
 // recompiled, and rethrown as undefined, exactly as before
-const compiled = new Map<string, Function | null>()
+// One entry per (extras, expression). `scoped` says which form `fn` is, so the
+// evaluation path never rebuilds the key to ask - it is a string concatenation
+// per evaluation, and this is the hottest loop in the library
+type CompiledExpr = { fn: Function | null; scoped: boolean }
 
-const compileExpr = (expr: string, params: string[]): Function | null => {
-  const key = `${params.join(",")}|${expr}`
-  let fn = compiled.get(key)
-  if (fn === undefined) {
-    try {
-      // the newline before `)` ends a trailing line comment in the
-      // expression ({{ msg // greeting }}); ASI doesn't apply inside parens,
-      // so everything else is untouched. Without it the comment eats the
-      // rest of this single-line body and the expression never compiles
-      fn = new Function("$scope", ...params, `with ($scope) { return (${expr}\n); }`)
-    } catch {
-      fn = null // a syntax error: it will never compile, so don't try again
-    }
-    compiled.set(key, fn)
+const compiled = new Map<string, CompiledExpr>()
+
+// Resolves a name the `const` prologue could not: its fast read came back
+// undefined, which means one of three different things. `with` told them apart
+// by consulting [[HasProperty]] on every read of every name; this consults it
+// only here, which is why the fast path has no `has` trap in it at all
+//
+// The `in scope` branch is load-bearing beyond "declared but undefined": a
+// deleted key leaves a tombstone the store still claims, so `user ? user.name :
+// "none"` takes its else branch instead of dying against globalThis (see
+// RECORD/2026-08-23.narrow-the-wake-rule.md)
+const resolveName = (scope: Record<string, any>, name: string): any => {
+  if (name in scope) return undefined
+  if (name in globalThis) return (globalThis as any)[name]
+  // the same error `with` threw, with the same wording, so reportExprError's
+  // MISSING_NAME_RE reads it exactly as it always has
+  throw new ReferenceError(`${name} is not defined`)
+}
+
+// the newline before `)` ends a trailing line comment in the expression
+// ({{ msg // greeting }}); ASI doesn't apply inside parens, so everything else
+// is untouched. Without it the comment eats the rest of this single-line body
+// and the expression never compiles
+const compileWith = (expr: string, params: string[]): Function | null => {
+  try {
+    return new Function("$scope", "$r", ...params, `with ($scope) { return (${expr}\n); }`)
+  } catch {
+    return null // a syntax error: it will never compile, so don't try again
+  }
+}
+
+// The same evaluation with the names resolved by hand: each free identifier
+// becomes a `const` read straight off the scope, and the expression's own text
+// is left exactly as authored inside the return. One proxy `get` per name -
+// the same read `with` would have made, so the deps tracked are the same ones.
+// Worth 63% of a one-name evaluation and 72% of a two-name one, measured in
+// RECORD/2026-08-27.name-resolution-without-with.md
+//
+// Returns null for anything freeIdentifiers refuses (an assignment, an arrow,
+// a declaration, a called name - handlers, mostly, where an evaluation's cost
+// does not matter), and for a prologue that will not compile: the caller falls
+// back to `with`.
+//
+// A name the extractor MISSES is not that benign, and a sabotage measured it:
+// the prologue does not declare it, so the expression reads it off globalThis.
+// Where nothing is there it throws and runExpr demotes the whole expression to
+// `with` - slower, same answer - but where the page has a global of that name
+// (`name`, `status`, `length`, `top`, `event` ... window has hundreds) it reads
+// the global instead of the store, and nothing throws. So the extractor's
+// misses are a correctness surface, not only a performance one, and the
+// differential in tests/expressions.test.ts is what stands behind it
+const compileScoped = (expr: string, params: string[]): Function | null => {
+  if (!debugFlags.scopedNames) return null
+  const free = freeIdentifiers(expr)
+  if (free === null) return null
+  // an extra is already a parameter of this function: declaring it again would
+  // shadow the value the caller passed in
+  const names = free.filter(name => !params.includes(name))
+  const prologue = names.length === 0 ? "" : `let $t; ${names.map(name =>
+    `const ${name} = ($t = $scope.${name}) !== undefined ? $t : $r($scope, ${JSON.stringify(name)});`).join(" ")}`
+  try {
+    return new Function("$scope", "$r", ...params, `${prologue} return (${expr}\n);`)
+  } catch {
+    return null
+  }
+}
+
+const entryFor = (key: string, expr: string, params: string[]): CompiledExpr => {
+  let entry = compiled.get(key)
+  if (entry === undefined) {
+    const scoped = compileScoped(expr, params)
+    entry = scoped ? { fn: scoped, scoped: true } : { fn: compileWith(expr, params), scoped: false }
+    compiled.set(key, entry)
   }
-  return fn
+  return entry
+}
+
+const exprKey = (expr: string, params: string[]): string => `${params.join(",")}|${expr}`
+
+const compileExpr = (expr: string, params: string[]): Function | null =>
+  entryFor(exprKey(expr, params), expr, params).fn
+
+// The safety net under the extractor. A free name it fails to collect is not
+// declared by the prologue, so the expression reaches for it against globalThis
+// and throws - and that is indistinguishable, from here, from the name being
+// genuinely undeclared. So the first ReferenceError out of a scoped function
+// demotes that expression to `with` permanently and evaluates it again: a name
+// the scanner missed costs one wasted evaluation, and a name that really is
+// missing throws again from `with`, reported exactly as before.
+//
+// The retry can run a call in the expression twice, which is why it happens
+// once per expression and never for the `with` form
+const demoteToWith = (key: string, expr: string, params: string[]): Function | null => {
+  const fallback = compileWith(expr, params)
+  compiled.set(key, { fn: fallback, scoped: false })
+  return fallback
 }
 
 // a template expression is re-evaluated constantly - once per effect run, once
@@ -225,9 +323,20 @@ const reportExprError = (expr: string, scope: Record<string, any>, error: unknow
 }
 
 const runExpr = (expr: string, scope: Record<string, any>, extras?: Record<string, any>): any => {
-  const fn = compileExpr(expr, extras ? Object.keys(extras) : [])
-  if (!fn) return undefined // a syntax error: compileExpr cached the failure, and it stays undefined
-  return fn(scope, ...(extras ? Object.values(extras) : []))
+  const params = extras ? Object.keys(extras) : []
+  const key = exprKey(expr, params)
+  const { fn, scoped } = entryFor(key, expr, params)
+  if (!fn) return undefined // a syntax error: the failure is cached, and it stays undefined
+  const args = extras ? Object.values(extras) : []
+  if (!scoped) return fn(scope, resolveName, ...args)
+  try {
+    return fn(scope, resolveName, ...args)
+  } catch (error) {
+    if (!(error instanceof ReferenceError)) throw error
+    const fallback = demoteToWith(key, expr, params)
+    if (!fallback) throw error
+    return fallback(scope, resolveName, ...args)
+  }
 }
 
 const evalExpr = (expr: string, scope: Record<string, any>, extras?: Record<string, any>): any => {
@@ -312,7 +421,7 @@ const renderText = (parts: TextPart[], scope: Record<string, any>): string => {
 }
 
 
-const CONTROL_ATTRS = new Set([":attrs", ":class", ":value", ":checked", ":selected", ":if", ":elseif", ":else", ":each", ":key", ":with", ":text", ":html", ":html.allowed", ":props"])
+const CONTROL_ATTRS = new Set([":class", ":value", ":checked", ":selected", ":if", ":elseif", ":else", ":each", ":key", ":with", ":text", ":html", ":html.allowed", ":props"])
 
 // a control attribute is one the static-attr loop and nested-component prop
 // collection must skip. The set holds the fixed names; `:class.<name>` (the
@@ -417,7 +526,7 @@ const removeRange = ({ first, last }: NodeRange) => {
 // removes several ranges that sit next to each other, in one DOM call each run
 // rather than one per node. A list dropping all its rows hands them over as a
 // single span: unlinking 10,000 rows one at a time is 40% of that operation,
-// profiled - see TODOS/2026-08-23.batch-range-removal.md. Runs are built by the
+// profiled - see RECORD/2026-08-23.batch-range-removal.md. Runs are built by the
 // caller, which is the only place that knows what else is going
 const removeRuns = (runs: NodeRange[]) => {
   runs.forEach(run => {
@@ -491,7 +600,7 @@ const scanComponentKey = (scope: Record<string, any>, tag: string): string | nul
 // a template renders before its setup script settles, so `const Row = await
 // $import(...)` arrives as a new store key *after* elements are on the page -
 // and a cached "no component called Row" that outlived the pass would never be
-// revisited. See TODOS/2026-08-23.component-key-scan.md
+// revisited. See RECORD/2026-08-23.component-key-scan.md
 // The memo answers for one *base* scope - the one the pass was opened with -
 // and nothing below it. A lookup walks from wherever it starts up to that base,
 // checking own keys as it goes (an :each item scope has two or three, a :with
@@ -534,6 +643,31 @@ const closeRenderPass = (outer: RenderPass) => {
   memoBase = outer.base
 }
 
+// which scope key a tag resolves to, and the only place that decides it. Two
+// spellings reach a component and nothing else does:
+//
+// - **the name the author capitalized**, read off `component` rather than off
+//   the tag, because the tag no longer holds it: the pre-parse rewrite renames
+//   <Circle /> to <c79-circle> precisely so the parser cannot build a native
+//   element from it (see componentTagName)
+// - **a dashed tag** - <drop-area> resolves DropArea - which is custom-element
+//   shaped and so cannot collide with a native element either
+//
+// An undashed lowercase tag resolves to nothing, whatever is in scope. That is
+// the other half of the capture this closes: a `Td` in scope no longer turns
+// every <td> under it into a component, and <mychip> no longer becomes MyChip
+// when the key arrives. See RECORD/2026-08-25.component-tag-prefix.md
+const componentKeyOf = (node: TemplateNode, scope: Record<string, any>): string | null =>
+  node.component !== undefined
+    ? findComponentKey(scope, node.component)
+    : node.tag.includes("-")
+      ? findComponentKey(scope, node.tag)
+      : null
+
+// what to call a tag in a message: the name the author wrote. A component tag's
+// `tag` is the renamed c79-* one, which nobody typed and nobody should read
+const tagLabel = (node: TemplateNode): string => node.component ?? node.tag
+
 const findComponentKey = (scope: Record<string, any>, tag: string): string | null => {
   if (!tagMemo) return scanComponentKey(scope, tag)
   const normalized = tag.replace(/-/g, "").toLowerCase()
@@ -679,7 +813,7 @@ const partitionSlots = (node: TemplateNode): Record<string, SlotContent> => {
     // 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`)
+      console.warn(`jq79: two <template ${slotAttrName(name)}> in <${tagLabel(node)}>; the second was ignored`)
       return
     }
     contents[name] = { nodes: child.children, binder: child.attrs[attr] || undefined }
@@ -688,7 +822,7 @@ const partitionSlots = (node: TemplateNode): Record<string, SlotContent> => {
   const hasLoose = loose.some(isMeaningful)
   if (hasLoose && "default" in contents) {
     console.warn(
-      `jq79: <${node.tag}> has both a <template :slot> and content outside it - ` +
+      `jq79: <${tagLabel(node)}> 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) {
@@ -809,6 +943,44 @@ const renderSlot = (node: TemplateNode, scope: Record<string, any>, fx: EffectSc
   return wrapper
 }
 
+// the element a component instance renders in - <c79-user-card> - and the
+// reason step 2 of the tag rename exists: a component stops being a pair of
+// comments around loose content and becomes a box that names itself in the
+// inspector and can be addressed by name in CSS.
+//
+// Named after the *component*, not the usage site, so `<UserCard />` and
+// `<user-card>` render the same box and a stylesheet has one name to target.
+//
+// It carries the PARENT's scope stamp, which is not an arbitrary pick: a
+// <style scoped> is rewritten to demand the stamp of whoever wrote it, and
+// `Circle { … }` is written by the parent. The stamp is already on the node -
+// stampScope walks the parent's template and the component tag is part of it -
+// and today it is dropped for want of an element to put it on. The child's own
+// root still carries no stamp from the parent, so a parent gets the box and
+// never what is inside it.
+//
+// EXCEPT inside <svg> or <math>: SVG's rendering model renders neither an
+// unknown element nor its children, and `display: contents` is not the escape
+// hatch there that it is in HTML, so a wrapper could turn a diagram into a
+// blank. A foreign-namespace usage site keeps the anchors alone, as it always
+// had. See RECORD/2026-08-25.the-wrapper-and-the-css-rename.md
+const COMPONENT_BOX_ATTR = "data-c79-box"
+
+const componentBox = (key: string, node: TemplateNode, shadow: boolean): DocumentFragment | HTMLElement => {
+  if (node.ns !== undefined) return document.createDocumentFragment()
+  const box = document.createElement(componentTagName(key))
+  // the marker the default stylesheet selects on. A tag name cannot be
+  // prefix-matched in CSS, and one attribute is one rule for every box on the
+  // page - see wrapperStyle()
+  box.setAttribute(COMPONENT_BOX_ATTR, "")
+  const stamp = node.attrs[SCOPE_ATTR]
+  if (stamp !== undefined) box.setAttribute(SCOPE_ATTR, stamp)
+  // a shadow-rendered tree leaves document.head alone - its copy of the rule
+  // rides with the instance's own styles instead (see renderWith)
+  if (!shadow) ensureWrapperStyle()
+  return box
+}
+
 // <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
@@ -822,15 +994,51 @@ const renderSlot = (node: TemplateNode, scope: Record<string, any>, fx: EffectSc
 // <style> has to go in there with it - document.head can't reach into a shadow
 // tree, and a style that never applies to its own component would still be
 // restyling the page around it
+// once per usage site, not per instance: a :each of 1,000 rows shares one AST
+// node, and the message is about the position rather than the row
+const warnedForeignRoots = new WeakSet<TemplateNode>()
+
+// A namespace is a PARSE-time fact and a usage site is a RENDER-time one, and a
+// nested component is the first thing that separates them: a definition's
+// template is parsed on its own, so a template rooted at a bare <circle> comes
+// out of the parser in HTML - it lands inside the <svg> and never draws, in
+// every engine. Nothing about that is visible: no error, no gap, an element in
+// the DOM with nothing on the screen.
+//
+// A component's template decides its own namespace, which is the answer this
+// project chose (RECORD/2026-08-26.the-namespace-of-a-component.md): a component
+// used inside an <svg> roots its template at <svg>. This is what says so when it
+// does not, instead of leaving a blank diagram
+const warnForeignRoot = (node: TemplateNode, definition: Component79) => {
+  if (node.ns === undefined || warnedForeignRoots.has(node)) return
+  const root = definition.template.find(child => typeof child === "object") as TemplateNode | undefined
+  if (root === undefined || root.ns !== undefined) return
+  warnedForeignRoots.add(node)
+  const wrapper = node.ns === "http://www.w3.org/1998/Math/MathML" ? "<math>" : "<svg>"
+  console.warn(
+    `jq79: <${tagLabel(node)}> is used inside ${wrapper} and its template starts with <${root.tag.toLowerCase()}>, ` +
+    `which is parsed as HTML - it renders and never draws. A component's template decides its own namespace, ` +
+    `so root it at ${wrapper}`
+  )
+}
+
 const renderNestedComponent = (key: string, node: TemplateNode, scope: Record<string, any>, fx: EffectScope, shadow: boolean): Node => {
-  // two anchors bracketing everything this usage site ever renders: the
-  // instance's DOM is dynamic (the definition can resolve late or be swapped),
-  // so a caller that needs to move or remove this chunk later can't hold any
-  // of it - it holds the anchors, which never move on their own (see boundsOf)
-  const anchor = document.createComment(key)
-  const endAnchor = document.createComment(`/${key}`)
-  const wrapper = document.createDocumentFragment()
-  wrapper.append(anchor, endAnchor)
+  // What this usage site ever renders needs stable bounds: the instance's DOM
+  // is dynamic (the definition can resolve late or be swapped), so a caller
+  // that moves or removes the chunk later cannot hold any of it.
+  //
+  // The BOX is those bounds where there is one - it is created once here and
+  // never replaced, and boundsOf resolves an element as { first: el, last: el }.
+  // So a boxed usage site renders no anchors at all: two comment nodes per
+  // instance that nothing read (RECORD/2026-08-25.retire-the-anchors.md).
+  //
+  // In a foreign namespace there is no box (componentBox returns a fragment,
+  // because a wrapper inside <svg> takes the drawing with it - measured in
+  // three engines), and there the anchors are still doing the whole job
+  const wrapper = componentBox(key, node, shadow)
+  const boxed = !(wrapper instanceof DocumentFragment)
+  const endAnchor = boxed ? null : document.createComment(`/${key}`)
+  if (!boxed) wrapper.append(document.createComment(key), 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
@@ -899,14 +1107,14 @@ const renderNestedComponent = (key: string, node: TemplateNode, scope: Record<st
   Object.entries(models).forEach(([name, expr]) => {
     const prop = modelProp(name)
     if (props[prop] !== undefined) {
-      console.warn(`jq79: <${node.tag}> binds prop "${prop}" through both :${prop} and ${modelAttr(name)} - ${modelAttr(name)} wins`)
+      console.warn(`jq79: <${tagLabel(node)}> binds prop "${prop}" through both :${prop} and ${modelAttr(name)} - ${modelAttr(name)} wins`)
     }
     props[prop] = expr
     // an expression that can't be an assignment target is a wiring mistake -
     // say so now, not on the first update that silently goes nowhere
     if (compileExpr(assignment(expr), ["$value"]) === null) {
       unassignable.add(name)
-      console.warn(`jq79: ${modelAttr(name)}="${expr}" is not assignable - updates from <${node.tag}> will be dropped`)
+      console.warn(`jq79: ${modelAttr(name)}="${expr}" is not assignable - updates from <${tagLabel(node)}> will be dropped`)
     }
   })
 
@@ -947,14 +1155,14 @@ const renderNestedComponent = (key: string, node: TemplateNode, scope: Record<st
       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. ` +
+        `jq79: <${tagLabel(node)}> 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`)
+    console.error(`jq79: <${tagLabel(node)}> is ${typeof value}, not a component - nothing renders here`)
   }
 
   fx.effect(() => {
@@ -970,6 +1178,8 @@ const renderNestedComponent = (key: string, node: TemplateNode, scope: Record<st
     currentDef = nextDef
     if (!nextDef) return
 
+    warnForeignRoot(node, nextDef)
+
     // a fresh instance per usage site: the definition's parsed parts (and
     // pre-resolved modules) are shared, but store/effects/DOM are per instance
     const instance = new Component79({
@@ -1005,7 +1215,7 @@ const renderNestedComponent = (key: string, node: TemplateNode, scope: Record<st
         if (expr === undefined) {
           if (!warned.has(name)) {
             warned.add(name)
-            console.warn(`jq79: <${node.tag}> has no ${modelAttr(name)} - bound: ${Object.keys(models).map(modelAttr).join(", ")}`)
+            console.warn(`jq79: <${tagLabel(node)}> has no ${modelAttr(name)} - bound: ${Object.keys(models).map(modelAttr).join(", ")}`)
           }
           return false
         }
@@ -1043,7 +1253,7 @@ const renderNestedComponent = (key: string, node: TemplateNode, scope: Record<st
     // 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. ` +
+        `jq79: <${tagLabel(node)}> 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
@@ -1054,7 +1264,12 @@ const renderNestedComponent = (key: string, node: TemplateNode, scope: Record<st
     } finally {
       nestingDepth--
     }
-    endAnchor.parentNode!.insertBefore(holder, endAnchor)
+    // the box holds this instance and nothing else, so appending is the whole
+    // of it; without one, the end anchor is the only fixed point there is - and
+    // its parentNode is the fragment before this site is inserted and the real
+    // parent after, which is why it is read here rather than captured
+    if (endAnchor) endAnchor.parentNode!.insertBefore(holder, endAnchor)
+    else wrapper.appendChild(holder)
 
     // deep: a prop sync forwards whatever the expression evaluates to, whole,
     // into the child's store - it reads `user`, never `user.name`, so it can't
@@ -1177,8 +1392,9 @@ const BOOLEAN_ATTRS = new Set([
   "playsinline", "readonly", "required", "reversed", "selected",
 ])
 
-// the one value rule, shared by `:attr="expr"` and `:attrs` so the two forms
-// can never disagree:
+// the value rule for `:attr="expr"`. It was shared with `:attrs` until that
+// directive was retired (RECORD/2026-08-27.retiring-attrs.md), which is why it
+// reads like a contract rather than an implementation detail:
 //
 // - a boolean attribute is removed by ANY falsy value and set to "" when
 //   truthy, so `:disabled="items.length"` enables the button on an empty list
@@ -1194,14 +1410,91 @@ const BOOLEAN_ATTRS = new Set([
 // browser doesn't have - and `readonly`/`novalidate`/`ismap` reflect under
 // camelCase property names no kebab->camel pass can produce, failing toward
 // `readonly="false"`, which is read-only
+// the one place an element is built, so the interpreted path and the cloner
+// cannot disagree about what a tag means. `ns` is set only for a foreign
+// element (see TemplateNode) - and creating one in its own namespace is what
+// makes `viewBox` keep its case, because setAttribute only lowercases a
+// qualified name on an HTML element
+const createFor = (node: TemplateNode): Element =>
+  node.ns === undefined ? document.createElement(node.tag) : document.createElementNS(node.ns, node.tag)
+
+// A bound camelCase SVG attribute, resolved by asking the parser.
+//
+// expandNameCase rewrites `:viewBox` to `:view-box` before the parse, because
+// the HTML parser lowercases attribute names and `:firstName` has to survive
+// it. For SVG's camelCase attributes that is wrong: `view-box` is not an
+// attribute SVG has, and it was wrong in silence.
+//
+// The HTML parser carries its own table for adjusting foreign attribute names -
+// it is what makes a written-out `viewBox="0 0 10 10"` survive at all. So ask
+// that table rather than shipping a copy of it: write the name into markup in
+// the element's own namespace, and read back what the parser called it. The
+// answer comes from the engine that will render the page, so it cannot disagree
+// with what that same engine does with the attribute written out.
+//
+// This is not the IDL trick RECORD/2026-08-24.svg-namespace.md buried. That one
+// asked "which family does this name belong to", a question with no ground
+// truth, and Chromium answered wrong for stdDeviation, attributeName and
+// repeatCount. This asks the table that decides the static case, and it is
+// right for all three - see RECORD/2026-08-25.svg-attribute-names.md.
+const FOREIGN_PROBES: Record<string, [wrapper: string, tag: string]> = {
+  "http://www.w3.org/2000/svg": ["svg", "feGaussianBlur"],
+  "http://www.w3.org/1998/Math/MathML": ["math", "mi"],
+}
+
+// one parse per namespace per name, ever - measured at 0.027ms, against
+// 0.000019ms for a hit. Only SVG and MathML have an adjustment table, so every
+// other namespace (and every HTML element) skips this entirely
+const adjustedNames = new Map<string, string>()
+
+const adjustedName = (ns: string, flat: string): string => {
+  const key = `${ns} ${flat}`
+  const cached = adjustedNames.get(key)
+  if (cached !== undefined) return cached
+
+  const probe = FOREIGN_PROBES[ns]
+  let adjusted = flat
+  // the name goes into markup, so it is checked rather than trusted - and a
+  // name the table could adjust is plain letters by construction. No DOMParser
+  // (a non-browser host) falls back to the name as written, which is what
+  // shipped before this existed
+  if (probe !== undefined && typeof DOMParser !== "undefined" && /^[a-z][a-z0-9]*$/.test(flat)) {
+    const [wrapper, tag] = probe
+    const doc = new DOMParser().parseFromString(`<${wrapper}><${tag} ${flat}="x"/></${wrapper}>`, "text/html")
+    adjusted = doc.querySelector(tag)?.getAttributeNames().find(name => name.toLowerCase() === flat) ?? flat
+  }
+  adjustedNames.set(key, adjusted)
+  return adjusted
+}
+
+// `name` is what the rewrite left: kebab, whichever way the author spelled it.
+// Both spellings converge on purpose, so this has to be a pure function of the
+// kebab name and the namespace - which makes a collision the only thing that
+// could break it, a real kebab attribute whose de-dashed form the table claims.
+// Measured over 58 dashed SVG names (every presentation attribute, plus data-*
+// and aria-*): none collides
+const foreignAttrName = (el: Element, name: string): string => {
+  const ns = el.namespaceURI
+  if (ns === null || ns === HTML_NS) return name
+  // no shortcut for a name without a dash: `:viewbox` is a spelling somebody
+  // writes, the parser adjusts it written out, and skipping the lookup left the
+  // bound form dead where the static one worked. What it costs is a memoised
+  // Map hit per foreign binding - 83 undashed names measured, none claimed
+  const flat = name.replace(/-/g, "").toLowerCase()
+  const adjusted = adjustedName(ns, flat)
+  // unchanged means the parser does not claim this name, so the author wrote a
+  // real kebab attribute (`stroke-width`) and it stays exactly as written
+  return adjusted === flat ? name : adjusted
+}
+
 const applyAttr = (el: Element, name: string, value: any) => {
   const boolean = BOOLEAN_ATTRS.has(name)
   if (boolean ? !value : value == null) el.removeAttribute(name)
   else el.setAttribute(name, boolean ? "" : String(value))
 }
 
-// renders a single element node: static attrs, @event listeners, a reactive
-// :attrs object, and its content - :text/:html override the element's own
+// renders a single element node: static attrs, @event listeners, `:name`
+// attribute bindings, and its content - :text/:html override the element's own
 // children with a reactive textContent/innerHTML, otherwise children render
 // normally. :if/:elseif/:else/:each are handled by renderNodes, which decides
 // *whether*/*how many times* a node is rendered before calling this. Tags
@@ -1221,22 +1514,31 @@ const applyAttr = (el: Element, name: string, value: any) => {
 //
 // Worth -20 to -49% of create1k depending on how much fixed structure a row
 // has, and nothing at all on a row that has none. Measured, with the method and
-// the caveats, in TODOS/2026-08-24.clone-skeletons-measured.md.
+// the caveats, in RECORD/2026-08-24.clone-skeletons-measured.md.
 //
 // Two rules keep this from becoming the bug it could be:
 //
 // 1. **The holes are an allowlist, never a denylist.** `plannableAttr` names
-//    the four things a skeleton knows how to fill; every other attribute makes
-//    the subtree unplannable. So a directive added to renderNode later is
-//    *slower* until somebody teaches it here - never silently mis-rendered,
-//    which is the failure a second render path invites.
+//    what a skeleton knows how to fill; every other attribute makes the subtree
+//    unplannable. So a directive added to renderNode later is *slower* until
+//    somebody teaches it here - never silently mis-rendered, which is the
+//    failure a second render path invites.
+//
+//    The allowlist is where the one divergence found so far came from, and it
+//    came from *widening* rather than from renderNode growing: `:model` is the
+//    single directive renderNode treats specially that CONTROL_ATTRS does not
+//    name, so it slipped through the generic `:<name>` clause. Adding to this
+//    list is the dangerous edit in this file - see
+//    RECORD/2026-08-24.more-holes-in-the-cloner.md.
 // 2. **The interpreted path stays the fallback for everything else**, including
 //    every tag that could still turn into a component. The upgrade watch and
 //    the unresolved-component throw are not reimplemented here; they are never
 //    reached from here.
 //
-// tests/skeleton.test.ts renders a corpus both ways and diffs the DOM, which is
-// what makes rule 1 enforceable rather than a promise.
+// tests/skeleton.test.ts renders a corpus both ways and diffs the DOM *and the
+// order the bindings register in*, which is what makes rule 1 enforceable
+// rather than a promise. The order axis is not decoration: :value on a <select>
+// has to run after its <option>s are bound, and no DOM diff can see that.
 // ---------------------------------------------------------------------------
 
 // Flipping this must never change what renders, only how - which is what
@@ -1246,7 +1548,7 @@ const applyAttr = (el: Element, name: string, value: any) => {
 // rebuild: a page that renders wrong is a bug report either way, but one whose
 // reporter can say "it goes away with cloning off" is a bug report that names
 // the file
-const debugFlags: DebugFlags = { cloneSkeletons: true }
+const debugFlags: DebugFlags = { cloneSkeletons: true, scopedNames: true }
 
 // What `Component79.debug()` can switch. One flag today; the shape is an object
 // so the next one does not change the call
@@ -1255,9 +1557,28 @@ export type DebugFlags = {
   // instead of walking the AST for every instance of it. Off means every
   // element goes through renderNode, exactly as before this existed
   cloneSkeletons: boolean
+
+  // resolve an expression's free names with a `const` prologue instead of
+  // `with ($scope)`. Off means every expression is compiled the way it always
+  // was, which is what makes the two forms comparable on one build - both in
+  // tests/expressions.test.ts and in `npm run benchmark:ab -- --flags`
+  scopedNames: boolean
 }
 
-// The four things a hole can be, in the order renderNode registers them.
+// the control attributes a skeleton knows how to fill. The rest of
+// CONTROL_ATTRS stays rejected on purpose: :if/:elseif/:else/:each/:key change
+// the shape rather than filling a hole, :with changes the scope its subtree
+// evaluates in, and :props belongs to a component tag.
+//
+// `:html` is here and `:html.allowed` is not, which is the whole of why the
+// warning renderNode emits for an `:html.allowed` with no `:html` is not this
+// list's problem: `:html.allowed` is rejected by the two clauses below (a
+// control attr, and a dotted name), so an element carrying one is never planned
+// and renderNode stays the only place that warning can fire from - once per
+// render, as before. See RECORD/2026-08-25.html-in-the-cloner.md
+const PLANNABLE_CONTROL_ATTRS = new Set([":text", ":html", ":value", ":checked", ":selected"])
+
+// What a hole can be, in the order renderNode registers them.
 // A `:` attribute with a dot in it is rejected wholesale except `:class.`:
 // `:model.`, `:props.`, `:slot.` and `:html.allowed` all live in that shape, and
 // so would the next directive family somebody invents
@@ -1265,17 +1586,35 @@ const plannableAttr = (name: string): boolean => {
   if (name.startsWith("@")) return true
   if (name === ":class") return true
   if (name.startsWith(":class.")) return true
+  if (PLANNABLE_CONTROL_ATTRS.has(name)) return true
   if (!name.startsWith(":")) return name !== COMPONENT_TAG_ATTR // a static attribute
+  // `:model` is the one directive renderNode treats specially that CONTROL_ATTRS
+  // does not name, so the clause below would let it through as a generic
+  // `:<name>` binding and the skeleton would write `model="..."` where the
+  // interpreted path warns and writes nothing (`:model` binds component tags
+  // only). `:model.<name>` is caught by the dot; the bare form needs saying
+  if (name === ":model") return false
   return !isControlAttr(name) && !name.includes(".")
 }
 
 const plannableNode = (node: TemplateNode): boolean => {
   if (node.component || node.tag.includes("-")) return false
   if (isSlotTag(node.tag) || node.tag === "template") return false
-  // an unknown tag may still become a component, and <svg> is one of them:
-  // createElement builds SVG names in the HTML namespace (see renderNode)
-  if (document.createElement(node.tag) instanceof HTMLUnknownElement) return false
+  // an unknown tag stays interpreted. It can no longer become a component - the
+  // upgrade watch narrowed to a stamped or dashed tag, both of which are
+  // rejected above - so this is a conservative rule rather than a load-bearing
+  // one: an undashed name the parser does not know is a typo or a custom
+  // element that can never register, and nothing is measured to be gained by
+  // cloning it. A *foreign* element skips the test rather than failing it:
+  // <circle> is an HTMLUnknownElement when built with createElement, which is
+  // exactly the mistake this used to make
+  if (node.ns === undefined && document.createElement(node.tag) instanceof HTMLUnknownElement) return false
   for (const key in node.attrs) if (!plannableAttr(key)) return false
+  // an element with :text or :html has no children on either path (see
+  // buildSkeleton), so what the source wrote inside it cannot make the subtree
+  // unplannable - a component tag under a :text is markup nobody renders, not
+  // markup the clone path would get wrong
+  if (node.attrs[":text"] !== undefined || node.attrs[":html"] !== undefined) return true
   return node.children.every(child => typeof child === "string" || plannableNode(child))
 }
 
@@ -1288,15 +1627,19 @@ type SkeletonOp =
   | { kind: "event"; path: number[]; attr: string; expr: string }
   | { kind: "attr"; path: number[]; name: string; expr: string }
   | { kind: "class"; path: number[]; classExpr?: string; toggles: [string, string][] | null; staticClasses: Set<string> }
+  | { kind: "textContent"; path: number[]; expr: string }
+  | { kind: "html"; path: number[]; expr: string }
+  | { kind: "value"; path: number[]; expr: string }
+  | { kind: "checked"; path: number[]; expr: string }
+  | { kind: "selected"; path: number[]; expr: string }
 
-type SkeletonPlan = { skeleton: Element; ops: SkeletonOp[]; tags: string[] }
+type SkeletonPlan = { skeleton: Element; ops: SkeletonOp[] }
 
 // mirrors renderNode's own order: the attribute walk (events and attribute
 // bindings as they appear), then :class, then the children. Effects run in
 // registration order, so this is not cosmetic
-const buildSkeleton = (node: TemplateNode, path: number[], ops: SkeletonOp[], tags: Set<string>): Element => {
-  tags.add(node.tag)
-  const el = document.createElement(node.tag)
+const buildSkeleton = (node: TemplateNode, path: number[], ops: SkeletonOp[]): Element => {
+  const el = createFor(node)
 
   let classExpr: string | undefined
   let toggles: [string, string][] | null = null
@@ -1305,16 +1648,31 @@ const buildSkeleton = (node: TemplateNode, path: number[], ops: SkeletonOp[], ta
     if (key.startsWith("@")) ops.push({ kind: "event", path, attr: key, expr: value })
     else if (key === ":class") classExpr = value
     else if (key.startsWith(":class.")) (toggles ??= []).push([key.slice(":class.".length), value])
+    // a directive of its own, bound below - the same skip renderNode's walk
+    // makes, and for the same reason: without it :text would be written out as
+    // an attribute named `text`. :class/:class. are control attrs too and are
+    // already caught above
+    else if (isControlAttr(key)) { /* handled after the walk */ }
     else if (key.startsWith(":")) {
       const name = key.slice(1)
-      ops.push({ kind: "attr", path, name, expr: value || kebabToCamel(name) })
+      // resolved here rather than per instance: the skeleton's element already
+      // exists, so its namespace is known once per definition
+      ops.push({ kind: "attr", path, name: foreignAttrName(el, name), expr: value || kebabToCamel(name) })
     } else el.setAttribute(key, value)
   }
   if (classExpr !== undefined || toggles) {
     ops.push({ kind: "class", path, classExpr, toggles, staticClasses: new Set(classNames(node.attrs.class ?? "")) })
   }
 
-  node.children.forEach((child, index) => {
+  // :text and :html replace the element's content, and renderNode never renders
+  // the children of an element carrying either. So the skeleton gives it none
+  // either: both are leaves on both paths, whatever the source wrote inside
+  // them. The else-if order is renderNode's - :text wins when both are written
+  const textExpr = node.attrs[":text"]
+  const htmlExpr = node.attrs[":html"]
+  if (textExpr !== undefined) ops.push({ kind: "textContent", path, expr: textExpr })
+  else if (htmlExpr !== undefined) ops.push({ kind: "html", path, expr: htmlExpr })
+  else node.children.forEach((child, index) => {
     if (typeof child === "string") {
       // an interpolated text node is a hole; the skeleton holds the empty node
       // it will be written into, so the child indices match either way
@@ -1324,9 +1682,21 @@ const buildSkeleton = (node: TemplateNode, path: number[], ops: SkeletonOp[], ta
       } else el.appendChild(document.createTextNode(child))
       return
     }
-    el.appendChild(buildSkeleton(child, [...path, index], ops, tags))
+    el.appendChild(buildSkeleton(child, [...path, index], ops))
   })
 
+  // after the children, because renderNode registers them there and for its
+  // reason: :value on a <select> can only pick an <option> that already exists.
+  // `ops` is flat and in registration order, and this is the recursive call's
+  // tail, so a parent's form-state ops land after every op of every descendant -
+  // which is exactly what renderNode's own recursion does
+  const valueExpr = node.attrs[":value"]
+  if (valueExpr !== undefined) ops.push({ kind: "value", path, expr: valueExpr })
+  const checkedExpr = node.attrs[":checked"]
+  if (checkedExpr !== undefined) ops.push({ kind: "checked", path, expr: checkedExpr })
+  const selectedExpr = node.attrs[":selected"]
+  if (selectedExpr !== undefined) ops.push({ kind: "selected", path, expr: selectedExpr })
+
   return el
 }
 
@@ -1336,21 +1706,51 @@ const buildSkeleton = (node: TemplateNode, path: number[], ops: SkeletonOp[], ta
 // and a regression on a row whose only fragments are that small
 const MIN_SKELETON_ELEMENTS = 3
 
+// children under a :text or an :html are not built by either path, so they are
+// not elements this threshold should be counting - a <p :text="v"> with two
+// <span>s written inside it is one element's worth of cloning, not three
 const countElements = (node: TemplateNode): number =>
-  1 + node.children.reduce((total, child) => total + (typeof child === "string" ? 0 : countElements(child)), 0)
+  node.attrs[":text"] !== undefined || node.attrs[":html"] !== undefined
+    ? 1
+    : 1 + node.children.reduce((total, child) => total + (typeof child === "string" ? 0 : countElements(child)), 0)
 
 const skeletonPlans = new WeakMap<TemplateNode, SkeletonPlan | null>()
 
+// A definition rendered ONCE pays for a plan it never reuses: +23% at
+// MIN_SKELETON_ELEMENTS, +11.5% at six elements, measured in
+// RECORD/2026-08-24.one-shot-render-measured.md. So the plan is built on the
+// SECOND render, not the first - a one-shot definition never builds one at all,
+// and a :each of 1,000 rows interprets row 1 and clones the other 999.
+//
+// The element count could not answer this. It is a proxy for "will this be
+// rendered again", and raising it to protect the one-shot case would take a
+// 9-element list row - which amortizes beautifully - off the clone path. This
+// keys on the thing itself.
+//
+// renderEach calls renderNode per row and renderNode calls planOf, so the list
+// case needs no special handling; it falls out.
+//
+// The third state is a WeakSet rather than a sentinel in the map, so the map's
+// type keeps saying what it means: absent is "never seen", null is "examined,
+// not plannable"
+const seenOnce = new WeakSet<TemplateNode>()
+
 const planOf = (node: TemplateNode): SkeletonPlan | null => {
   const cached = skeletonPlans.get(node)
   if (cached !== undefined) return cached
 
+  // first sighting: interpret it, and decide nothing. Examining it here is the
+  // cost the one-shot case was paying
+  if (!seenOnce.has(node)) {
+    seenOnce.add(node)
+    return null
+  }
+
   let plan: SkeletonPlan | null = null
   if (plannableNode(node) && countElements(node) >= MIN_SKELETON_ELEMENTS) {
     const ops: SkeletonOp[] = []
-    const tags = new Set<string>()
-    const skeleton = buildSkeleton(node, [], ops, tags)
-    plan = { skeleton, ops, tags: Array.from(tags) }
+    const skeleton = buildSkeleton(node, [], ops)
+    plan = { skeleton, ops }
   }
   skeletonPlans.set(node, plan)
   return plan
@@ -1365,6 +1765,9 @@ const atPath = (root: Node, path: number[]): Node => {
 const renderFromSkeleton = (plan: SkeletonPlan, scope: Record<string, any>, fx: EffectScope): Node => {
   const root = plan.skeleton.cloneNode(true) as Element
 
+  // ordered by how often a row actually carries the kind, not by when it was
+  // added: this chain runs once per op per instance, so the four holes a
+  // benchmark row is made of are matched before the five a form is
   for (const op of plan.ops) {
     const target = op.path.length === 0 ? root : atPath(root, op.path)
 
@@ -1381,7 +1784,7 @@ const renderFromSkeleton = (plan: SkeletonPlan, scope: Record<string, any>, fx:
       const el = target as Element
       const { name, expr } = op
       fx.effect(() => applyAttr(el, name, evalExpr(expr, scope)))
-    } else {
+    } else if (op.kind === "class") {
       const el = target as Element
       const { classExpr, toggles, staticClasses } = op
       let bound: string[] = []
@@ -1396,6 +1799,54 @@ const renderFromSkeleton = (plan: SkeletonPlan, scope: Record<string, any>, fx:
         el.classList.add(...next)
         bound = next
       })
+    } else if (op.kind === "textContent") {
+      const el = target as Element
+      const { expr } = op
+      // compared before it lands, like the text node above: an unchanged write
+      // still replaces the element's child text node, so a re-run that changed
+      // nothing would hand every observer a new node
+      fx.effect(() => {
+        const text = String(evalExpr(expr, scope) ?? "")
+        if (el.textContent !== text) el.textContent = text
+      })
+    } else if (op.kind === "html") {
+      // renderNode's effect with its `allowUrl` arm removed, because an element
+      // carrying :html.allowed is never planned - the attribute is rejected by
+      // plannableAttr, which is what keeps that directive's warning in exactly
+      // one place. RECORD/2026-08-25.html-in-the-cloner.md
+      const el = target as Element
+      const { expr } = op
+      fx.effect(() => { el.innerHTML = sanitizeHTML(String(evalExpr(expr, scope) ?? "")) })
+    } else if (op.kind === "value") {
+      // the property, not the attribute, and skipping a write that would not
+      // change it - renderNode's reasons apply here unchanged
+      const el = target as HTMLInputElement
+      const { expr } = op
+      fx.effect(() => {
+        const value = String(evalExpr(expr, scope) ?? "")
+        if (el.value !== value) el.value = value
+      })
+    } else if (op.kind === "checked") {
+      const el = target as HTMLInputElement
+      const { expr } = op
+      fx.effect(() => {
+        const checked = !!evalExpr(expr, scope)
+        if (el.checked !== checked) el.checked = checked
+      })
+    } else if (op.kind === "selected") {
+      const el = target as HTMLOptionElement
+      const { expr } = op
+      fx.effect(() => {
+        const selected = !!evalExpr(expr, scope)
+        if (el.selected !== selected) el.selected = selected
+      })
+    } else {
+      // every kind is named above, so this is unreachable - and the assignment
+      // is what makes the compiler say so. A kind added to SkeletonOp and
+      // forgotten here is the exact failure this whole file is arranged to
+      // prevent, and it is cheaper to catch it in tsc than in the corpus
+      const unhandled: never = op
+      void unhandled
     }
   }
 
@@ -1403,7 +1854,7 @@ const renderFromSkeleton = (plan: SkeletonPlan, scope: Record<string, any>, fx:
 }
 
 const renderNode = (node: TemplateNode, outerScope: Record<string, any>, fx: EffectScope, shadow: boolean): Node => {
-  // :with applies to the element's own bindings (@events, :attrs) and its
+  // :with applies to the element's own bindings (@events, :name) and its
   // whole subtree. On a :each element the item scope is already in place, so
   // :with="item" works
   const withExpr = node.attrs[":with"]
@@ -1415,63 +1866,78 @@ const renderNode = (node: TemplateNode, outerScope: Record<string, any>, fx: Eff
   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)
+  const componentKey = componentKeyOf(node, scope)
   if (componentKey) return renderNestedComponent(componentKey, node, scope, fx, shadow)
 
-  // A planned subtree is cloned - unless a scope key captures one of its tags.
-  // findComponentKey strips dashes and lowercases, and every PascalCase scope
-  // key participates, so a variable named `Td` makes every <td> under it a
-  // component and `Map`, `Data`, `Table`, `Form` and `Label` are all HTML tags
-  // somebody might name a component after. "It is a known HTML tag" is not on
-  // its own an answer; this is. It costs what the interpreted path already
-  // pays - one findComponentKey per distinct tag, memoized per render pass
+  // A planned subtree is cloned, and no scope key can take one of its tags away
+  // any more: a plannable tag is undashed, unstamped and a name the HTML parser
+  // knows, which is exactly the set componentKeyOf answers "no" to. This used
+  // to walk plan.tags calling findComponentKey for each, because a variable
+  // named `Td` made every <td> under it a component and `Map`, `Data`, `Table`,
+  // `Form` and `Label` are all HTML tags somebody might name a component after.
+  // The rename is what retires that check - see RECORD/2026-08-25.component-tag-prefix.md
   if (debugFlags.cloneSkeletons) {
     const plan = planOf(node)
-    if (plan && !plan.tags.some(tag => findComponentKey(scope, tag))) return renderFromSkeleton(plan, scope, fx)
+    if (plan) return renderFromSkeleton(plan, scope, fx)
   }
 
-  const el = document.createElement(node.tag)
+  const el = createFor(node)
 
-  // <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.
+  // <UserCrad /> - written as a component (node.component) and resolving to
+  // none. 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.
+  // Two conditions now, where there were three. The capitalization still
+  // carries the claim - <lable>, <svg> and <my-widget> are not judged - but the
+  // element check is gone with the rename: a stamped tag is a c79-* one, so it
+  // is never the element it was named after, and <DIV> is judged like any other
+  // capitalized tag. It is a component claim that resolves to nothing, and it
+  // says so instead of quietly rendering a div.
   //
-  // 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.
+  // The pending count still carries the rest: without it 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 its own 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) {
+  if (node.component !== undefined && ((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
-  // no deps, so it only re-runs on the store's new-key sweep, and swaps the
-  // placeholder element for the component exactly once
-  // dashes included, because findComponentKey matches them case-insensitively
-  // with dashes stripped: <drop-area> resolves DropArea, so a dashed tag is a
-  // possible component too, not only a custom element
-  const mayUpgrade = el instanceof HTMLUnknownElement || node.tag.includes("-")
+  // a tag that may still name a component whose key has not arrived yet (an
+  // async factory script exposing an imported component after `await`). Watch
+  // for the key: the effect tracks no deps, so it only re-runs on the store's
+  // new-key sweep, and swaps the placeholder element for the component exactly
+  // once.
+  //
+  // The two spellings componentKeyOf accepts, and no others - a capitalized tag
+  // (which is a c79-* element here, since it resolved to nothing) and a dashed
+  // one, because <drop-area> resolves DropArea. An unknown *undashed* lowercase
+  // tag no longer waits: <mychip> is a typo or a custom element that never
+  // registered, not a component that has yet to arrive.
+  //
+  // Never for a foreign element, and the dash clause is why that has to be said
+  // out loud: <annotation-xml> is the one MathML or SVG tag with a hyphen in it,
+  // and without this it is a real element treated as a custom one - its
+  // : bindings held verbatim as parameters for a component, and the element
+  // itself replaced the moment something named AnnotationXml enters scope. The
+  // namespace is the parser's answer to "where was this written", so ns !== undefined
+  // means inside a <math> or an <svg>, where no component can live - the same
+  // argument plannableNode makes. See RECORD/2026-08-24.mathml.md
+  const mayUpgrade = node.ns === undefined && (node.component !== undefined || node.tag.includes("-"))
   if (mayUpgrade) {
     let upgraded = false
     fx.effect(() => {
       if (upgraded) return
-      const key = findComponentKey(scope, node.tag)
+      const key = componentKeyOf(node, scope)
       if (!key) return
       upgraded = true
       const replacement = renderNestedComponent(key, node, scope, fx, shadow)
@@ -1488,23 +1954,23 @@ const renderNode = (node: TemplateNode, outerScope: Record<string, any>, fx: Eff
   // entries form allocates one array of pairs plus one two-element array per
   // attribute *per instance*. Nothing here reads the pairs as pairs, so the
   // allocation buys nothing and the garbage it makes is measurable - see
-  // TODOS/2026-08-23.where-the-create-time-goes.md
+  // RECORD/2026-08-23.where-the-create-time-goes.md
   for (const key in node.attrs) {
     const value = node.attrs[key]
     if (key.startsWith("@")) bindEvent(el, key, value, scope)
     else if (key === ":model" || key.startsWith(":model.")) {
-      // :model binds component tags only (see TODOS/2026-07-15.model-directive.md;
+      // :model binds component tags only (see RECORD/2026-07-15.model-directive.md;
       // the native-element form is parked there). Warn on a real element, but
       // not on a tag that may still upgrade into a component - the upgrade
       // re-renders through renderNestedComponent, models and all
       if (!mayUpgrade) {
-        console.warn(`jq79: ${key} on <${node.tag}> does nothing - :model binds component tags only (for now)`)
+        console.warn(`jq79: ${key} on <${tagLabel(node)}> does nothing - :model binds component tags only (for now)`)
       }
     } else if (isControlAttr(key)) {
       // a directive of its own, bound further down (or by renderNodes)
     } else if (key.startsWith(":")) {
       // :name="expr" binds that one attribute, reactively - the single-key
-      // case :attrs="{ name: expr }" was carrying. `:name` alone is shorthand
+      // case :attrs="{ name: expr }" used to carry. `:name` alone is shorthand
       // for `:name="name"`, like props and :model.<name>, and the shorthand
       // reads the camelCase variable while the attribute keeps its written
       // (kebab) name: `:aria-expanded` binds `ariaExpanded`, because
@@ -1513,28 +1979,19 @@ const renderNode = (node: TemplateNode, outerScope: Record<string, any>, fx: Eff
       // On a tag that may still upgrade this is a *parameter*, not an
       // attribute: leave it written verbatim, as before, so the upgrade's
       // renderNestedComponent still finds it. A component tag has no single
-      // root for an attribute to land on anyway (TODOS/2026-07-15.class-directive.md)
+      // root for an attribute to land on anyway (RECORD/2026-07-15.class-directive.md)
       if (mayUpgrade) el.setAttribute(key, value)
       else {
-        const name = key.slice(1)
-        const expr = value || kebabToCamel(name)
+        const written = key.slice(1)
+        const expr = value || kebabToCamel(written)
+        // outside the effect: the name a binding writes is fixed by the source
+        // and the element, and neither moves between runs
+        const name = foreignAttrName(el, written)
         fx.effect(() => applyAttr(el, name, evalExpr(expr, scope)))
       }
     } else el.setAttribute(key, value)
   }
 
-  const bindExpr = node.attrs[":attrs"]
-  if (bindExpr !== undefined) {
-    let boundKeys: string[] = []
-
-    fx.effect(() => {
-      boundKeys.forEach(key => el.removeAttribute(key))
-      const bound = evalExpr(bindExpr, scope)
-      boundKeys = bound && typeof bound === "object" ? Object.keys(bound) : []
-      boundKeys.forEach(key => applyAttr(el, key, bound[key]))
-    })
-  }
-
   // :class="expr" adds classes on top of the static `class` attribute, and
   // :class.<name>="expr" is the single-flag shorthand for `{ <name>: expr }`
   // (the name routed through classNames, so an empty `:class.` can't reach
@@ -1584,7 +2041,10 @@ const renderNode = (node: TemplateNode, outerScope: Record<string, any>, fx: Eff
     console.warn("jq79: :html.allowed without :html on the same element does nothing")
   }
   if (textExpr !== undefined) {
-    fx.effect(() => { el.textContent = String(evalExpr(textExpr, scope) ?? "") })
+    fx.effect(() => {
+      const text = String(evalExpr(textExpr, scope) ?? "")
+      if (el.textContent !== text) el.textContent = text
+    })
   } else if (htmlExpr !== undefined) {
     fx.effect(() => {
       const options = allowedExpr !== undefined ? { allowUrl: normalizeAllowUrl(evalExpr(allowedExpr, scope)) } : undefined
@@ -1603,8 +2063,8 @@ const renderNode = (node: TemplateNode, outerScope: Record<string, any>, fx: Eff
 
   // :value / :checked / :selected write the DOM *property*, not the
   // attribute - the attribute is only a form control's default, and detaches
-  // the moment the user interacts (which is why :attrs="{ value }" stops
-  // driving a typed-in input). One-way, store -> DOM: the way back stays an
+  // the moment the user interacts (which is why writing the value ATTRIBUTE
+  // stops driving a typed-in input). One-way, store -> DOM: the way back stays an
   // explicit @input/@change. :value skips the write when the property
   // already holds the string, so an unrelated re-run can't move the caret of
   // the input the user is typing into. Registered after the children render:
@@ -1619,14 +2079,20 @@ const renderNode = (node: TemplateNode, outerScope: Record<string, any>, fx: Eff
   // written out rather than looped over a literal array: the loop allocated the
   // array *and* its closure for every element rendered - 8,000 of each per
   // create1k, almost all of them to find nothing. Same reason the attribute
-  // walk above is a `for...in` (TODOS/2026-08-23.where-the-create-time-goes.md)
+  // walk above is a `for...in` (RECORD/2026-08-23.where-the-create-time-goes.md)
   const checkedExpr = node.attrs[":checked"]
   if (checkedExpr !== undefined) {
-    fx.effect(() => { (el as HTMLInputElement).checked = !!evalExpr(checkedExpr, scope) })
+    fx.effect(() => {
+      const checked = !!evalExpr(checkedExpr, scope)
+      if ((el as HTMLInputElement).checked !== checked) (el as HTMLInputElement).checked = checked
+    })
   }
   const selectedExpr = node.attrs[":selected"]
   if (selectedExpr !== undefined) {
-    fx.effect(() => { (el as HTMLOptionElement).selected = !!evalExpr(selectedExpr, scope) })
+    fx.effect(() => {
+      const selected = !!evalExpr(selectedExpr, scope)
+      if ((el as HTMLOptionElement).selected !== selected) (el as HTMLOptionElement).selected = selected
+    })
   }
 
   return el
@@ -1823,7 +2289,7 @@ const eachPlanOf = (node: TemplateNode): EachPlan | null => {
   // one key per row, so a 1,000-row list paid 1,000 `with`-scoped calls through
   // the store proxy to discover that nothing had changed: most of the 37% of a
   // pass that goes on evaluating expressions
-  // (TODOS/2026-08-23.where-the-list-operations-go.md). Anything else - a call,
+  // (RECORD/2026-08-23.where-the-list-operations-go.md). Anything else - a call,
   // an index, a deeper path, a name from the outer scope - still goes through
   // evalExpr, and so does a non-object item, which keeps every diagnostic a
   // property read of a null row would have raised
@@ -1842,7 +2308,7 @@ const eachPlanOf = (node: TemplateNode): EachPlan | null => {
   // it was 9ms of removeRow's 25ms. Decided once, from the template, rather
   // than per row per render. The item name is deliberately not in this list:
   // nearly every binding reads it, and it is not what goes stale.
-  // See TODOS/2026-08-23.positional-refresh.md
+  // See RECORD/2026-08-23.positional-refresh.md
   const positionalNames = ["$index", ...(atName ? [atName] : [])]
   const readsPosition = mentionsAny(itemNode, positionalNames)
 
@@ -1864,7 +2330,7 @@ const renderEach = (node: TemplateNode, scope: Record<string, any>, fx: EffectSc
   // one key per row, so a 1,000-row list paid 1,000 `with`-scoped calls through
   // the store proxy to discover that nothing had changed: most of the 37% of a
   // pass that goes on evaluating expressions
-  // (TODOS/2026-08-23.where-the-list-operations-go.md). Anything else - a call,
+  // (RECORD/2026-08-23.where-the-list-operations-go.md). Anything else - a call,
   // an index, a deeper path, a name from the outer scope - still goes through
   // evalExpr, and so does a non-object item, which keeps every diagnostic a
   // property read of a null row would have raised
@@ -2063,7 +2529,7 @@ const warnChainAttrs = (node: TemplateNode) => {
   // allocated only on the way to a warning, never on the path that finds none
   const present = [hasIf ? ":if" : null, hasElseif ? ":elseif" : null, hasElse ? ":else" : null].filter(Boolean)
   console.warn(
-    `jq79: ${present.join(" and ")} on the same <${node.tag}> - only ${present[0]} applies; ` +
+    `jq79: ${present.join(" and ")} on the same <${tagLabel(node)}> - only ${present[0]} applies; ` +
     "the branches of a chain are sibling elements, one directive each"
   )
 }
@@ -2076,13 +2542,107 @@ const warnOrphanBranch = (node: TemplateNode, afterClosedChain: boolean) => {
   const attr = ":elseif" in node.attrs ? ":elseif" : ":else"
   console.warn(
     afterClosedChain
-      ? `jq79: a second ${attr} on <${node.tag}> - the chain before it already ended with :else, ` +
+      ? `jq79: a second ${attr} on <${tagLabel(node)}> - the chain before it already ended with :else, ` +
         "which closes it. One :if, any number of :elseif, at most one :else"
-      : `jq79: ${attr} on <${node.tag}> continues no :if - it renders unconditionally. ` +
+      : `jq79: ${attr} on <${tagLabel(node)}> continues no :if - it renders unconditionally. ` +
         "A chain is :if, then :elseif, then :else, on adjacent siblings: anything but whitespace between them breaks it"
   )
 }
 
+// A directive on a *nested* <template> says something it does not mean, in two
+// different ways, and neither is a rendering bug to fix.
+//
+// Bare, the element is native and inert: its children live in .content and
+// never reach the page, so `<template :if="show"><li>uno</li></template>`
+// decides whether an empty <template> is inserted and shows nothing in either
+// state. With a :slot attribute the directive is not merely invisible but
+// *dropped* - partitionSlots finds the node by slotAttrOf and takes its
+// children as the slot's content, and nothing on that path looks at :if, so a
+// :slot filler renders whatever its condition says.
+//
+// The directive is the discriminant, and nothing else is: a bare nested
+// <template> is the legitimate native use and must stay silent. A top-level one
+// never arrives here at all - parseComponentString lifts declarations out
+// before componentPartsFrom runs - so the position needs no exclusion.
+// See RECORD/2026-08-24.template-directive-warning.md
+const TEMPLATE_DIRECTIVES = [":if", ":elseif", ":else", ":each"]
+
+const warnTemplateDirective = (node: TemplateNode, parent: TemplateNode | undefined) => {
+  // an HTML <template> only: inside an <svg> the tag is a plain namespaced
+  // element with ordinary children, so they render and the message below - that
+  // they live in a .content nobody reads - would be false
+  if (node.tag !== "template" || node.ns !== undefined) return
+  const directive = TEMPLATE_DIRECTIVES.find(attr => attr in node.attrs)
+  if (directive === undefined) return
+
+  if (slotAttrOf(node) !== undefined) {
+    // A <template :slot> fills a slot only as a direct child of a component
+    // tag - anywhere else it is misplaced, and misplacedSlotContent says so in
+    // its own words. There the directive is NOT dropped: renderNodes groups the
+    // :if into a chain like any other element's, so a false branch renders
+    // nothing and the message below would be wrong twice over. Say nothing and
+    // leave the position to the diagnostic that is about the position
+    if (parent?.component === undefined) return
+    console.warn(
+      `jq79: ${directive} on <template ${slotAttrOf(node)}> is ignored - a slot is filled with its children as written. ` +
+      `Put ${directive} on the elements inside it, or on the component's tag`
+    )
+    return
+  }
+  console.warn(
+    `jq79: ${directive} on a nested <template> shows nothing - a <template>'s children live in its .content ` +
+    `and never reach the page. Put ${directive} on the elements themselves`
+  )
+}
+
+// The directive names a `:` attribute can be a misspelling OF. Derived from
+// CONTROL_ATTRS rather than written out, plus the two families that are not in
+// it (`:model`, `:slot`) - so there is no second list to keep in step.
+const DIRECTIVE_NAMES = [...CONTROL_ATTRS, ":model", ":slot"].map(attr => attr.slice(1))
+
+// `:iff="ready"` renders the element unconditionally and writes iff="true", and
+// until now said nothing - because since RECORD/2026-08-07.attribute-directive.md
+// an unrecognized `:name` is not an error at all: it BINDS that attribute, which
+// is what makes `:src`, `:disabled` and `:aria-expanded` work. So there is no
+// "unknown directive" to report in general, and the only typo worth a word is
+// one that starts with a directive's own name: `:iff`, `:eachh`, `:classs`.
+//
+// A prefix, deliberately, and not an edit distance: the rule is derived from the
+// directive list itself, so nothing here is a table of near-misses to maintain
+// A name that WAS a directive and is not one any more. Bare removal would be
+// the silent kind: `:attrs` is now an ordinary binding, so it would write
+// attrs="[object Object]" on an element and pass a prop nobody declared to a
+// component. One entry, and the message carries the migration
+const RETIRED_DIRECTIVES: Record<string, string> = {
+  ":attrs": `:attrs was removed in 0.7 - it now binds an attribute called "attrs". ` +
+    `Bind them one at a time (:disabled="x", :title="y"), or :class for classes`,
+}
+
+const warnRetiredDirective = (node: TemplateNode) => {
+  for (const attr in node.attrs) {
+    const message = RETIRED_DIRECTIVES[attr]
+    if (message !== undefined) console.warn(`jq79: ${message}`)
+  }
+}
+
+const warnDirectiveTypo = (node: TemplateNode) => {
+  // on a component tag every `:name` is a prop by design, and on a tag that may
+  // still become one it is a parameter waiting for a definition
+  if (node.component !== undefined || node.tag.includes("-")) return
+
+  for (const attr in node.attrs) {
+    if (!attr.startsWith(":") || isControlAttr(attr) || attr === ":model" || attr.startsWith(":model.")) continue
+    const name = attr.slice(1)
+    const directive = DIRECTIVE_NAMES.find(known => name !== known && name.startsWith(known))
+    if (directive === undefined) continue
+    console.warn(
+      `jq79: ${attr} is not a directive - it bound an attribute named "${name}". ` +
+      `A ":name" jq79 does not recognize binds that attribute (which is what :src and :disabled are). ` +
+      `If you meant :${directive}, that is the spelling`
+    )
+  }
+}
+
 // Checks one node list's chains, and every list below it, against that grammar.
 // Run once per definition from componentPartsFrom, not per render: a template
 // says what it says before any data exists, so a stray :else is reported when
@@ -2094,9 +2654,17 @@ const warnOrphanBranch = (node: TemplateNode, afterClosedChain: boolean) => {
 // The dispatch mirrors renderNodes' loop, because that is what decides which
 // node ends up a branch of what: a :each node is claimed before the chain
 // grouping ever sees it, which is exactly why it breaks a chain
-const validateChains = (nodes: (TemplateNode | string)[]) => {
+const validateChains = (nodes: (TemplateNode | string)[], parent?: TemplateNode) => {
   nodes.forEach(node => {
-    if (typeof node !== "string") validateChains(node.children)
+    if (typeof node === "string") return
+    // before the loop below, which skips a :each node early - and a
+    // <template :each> is one of the two shapes this reports. The parent comes
+    // with it because a <template :slot> means one thing under a component tag
+    // and something else anywhere else
+    warnTemplateDirective(node, parent)
+    warnRetiredDirective(node)
+    warnDirectiveTypo(node)
+    validateChains(node.children, node)
   })
 
   // the chain that ended immediately before this point closed itself with an
@@ -2365,12 +2933,10 @@ const SLOT_TAG_RE = /^slot\./i
 // <script>/<style> bodies split out, only start-tag interiors scanned, quoted
 // values consumed whole.
 //
-// Two name positions, not one: attribute names (`:model.firstName`) and the
-// dotted tag names (`<slot.firstName>`), whose closing halves are rewritten
-// too or the parser sees a mismatched pair. Component tags are deliberately
-// left alone - findComponentKey already matches them case-insensitively with
-// dashes stripped, so <UserCard> needs no help and rewriting it would only
-// obscure what the author wrote
+// Three name positions, not one: attribute names (`:model.firstName`), the
+// dotted tag names (`<slot.firstName>`) and component tags (`<UserCard>`,
+// renamed by componentTagName below). The last two have closing halves that are
+// rewritten too, or the parser sees a mismatched pair
 const kebabTagName = (tag: string): string =>
   SLOT_TAG_RE.test(tag) ? `slot.${camelToKebab(tag.slice("slot.".length))}` : tag
 
@@ -2391,6 +2957,41 @@ const kebabTagName = (tag: string): string =>
 const COMPONENT_TAG_ATTR = ":jq79-component"
 const COMPONENT_TAG_RE = /^[A-Z]/
 
+// A component tag is renamed to a name the HTML parser cannot resolve to an
+// element, because a PascalCase tag is lowercased by the parser and what comes
+// out is *the native element of that name*: <Circle /> inside an <svg> is a
+// circle, <Tr /> is a row placed inside its <tbody>, and 70 of 90 ordinary
+// one-word component names collide the same way. The claim the author made -
+// this is a component - survives in the stamp, and the tag stops being a name
+// anything downstream can mistake for an element's.
+//
+//   <Circle />    ->  <c79-circle :jq79-component="Circle" />
+//   </UserCard>   ->  </c79-user-card>
+//
+// Hyphenated, and that is not cosmetic: `c79-circle` is a valid custom element
+// name, so the parser builds an HTMLElement for it, where `c79circle` would be
+// an HTMLUnknownElement. The hyphen is the shape the platform reserves for what
+// is not native, which is the principle this rests on applied to our own tags -
+// and it reads for itself in the inspector, where a component that resolves to
+// nothing leaves <c79-circle> rather than a plausible-looking <circle>.
+//
+// Every capitalized tag, not only the colliding ones: today's safe name is
+// tomorrow's element. See RECORD/2026-08-25.component-tag-prefix.md
+const COMPONENT_TAG_PREFIX = "c79-"
+
+const componentTagName = (tag: string): string =>
+  `${COMPONENT_TAG_PREFIX}${camelToKebab(tag[0].toLowerCase() + tag.slice(1))}`
+
+const rewriteTagName = (tag: string): string =>
+  COMPONENT_TAG_RE.test(tag) ? componentTagName(tag) : kebabTagName(tag)
+
+// the closing half of the rename. OPEN_TAG_RE matches open tags only, which was
+// fine while both ends lowercased to the same name; rename one end and not the
+// other and `<c79-circle>` gets closed by `</circle>`, nesting everything that
+// follows inside it. </slot.x> keeps its own pass - it is lowercase and
+// unaffected by this one
+const CLOSE_COMPONENT_RE = /<\/([A-Z][\w.-]*)(\s*)>/g
+
 // 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
@@ -2415,9 +3016,10 @@ 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)}${stampComponentTag(tag, rewritten)}>`
+              return `<${rewriteTagName(tag)}${stampComponentTag(tag, rewritten)}>`
             })
             .replace(CLOSE_SLOT_RE, (_match, suffix: string, space: string) => `</slot.${camelToKebab(suffix)}${space}>`)
+            .replace(CLOSE_COMPONENT_RE, (_match, tag: string, space: string) => `</${componentTagName(tag)}${space}>`)
     )
     .join("")
 
@@ -2469,6 +3071,100 @@ const scopeRules = (rules: CSSRuleList, scope: string) => {
   })
 }
 
+// A component's name in a selector - `Circle { color: red }` - names the box
+// the component renders in (see renderNestedComponent), so it is rewritten to
+// the tag that box actually has. Same rename componentTagName does for markup,
+// so the author types the prefix in neither place.
+//
+// It runs on the SOURCE, before any CSS parser sees it, and that is not a
+// stylistic choice: in an HTML document a type selector matches
+// case-insensitively, and an engine is free to lowercase it when it serializes
+// `selectorText`. jsdom hands `Circle` back as written; an engine that hands
+// back `circle` would leave a rewrite made there matching nothing - green in
+// this repo's tests and inert in a browser. See
+// RECORD/2026-08-25.the-wrapper-and-the-css-rename.md
+//
+// Only a capitalized name with a lowercase letter in it is a component name
+// here: `DIV`, `A` and `SPAN` are shouty type selectors, which CSS has always
+// matched case-insensitively, and stay elements. That differs from the markup
+// rule on purpose - there, capitalization is the whole claim - and it leaves
+// one corner: a component named with no lowercase letter at all cannot be
+// styled by name
+const COMPONENT_SELECTOR_RE = /(^|[\s>+~,(])([A-Z][A-Za-z0-9]*)(?![\w-])/g
+const HAS_LOWER_RE = /[a-z]/
+
+const renameSelectorNames = (selectors: string): string =>
+  selectors.replace(COMPONENT_SELECTOR_RE, (whole, before: string, name: string) =>
+    HAS_LOWER_RE.test(name) ? `${before}${componentTagName(name)}` : whole
+  )
+
+// at-rules whose block holds rules rather than declarations, so what is inside
+// their braces is selector position again
+const NESTED_AT_RULE_RE = /^\s*@(media|supports|container|layer|scope|document)\b/i
+const AT_RULE_RE = /^\s*@/
+
+// the scan: strings, comments and nesting tracked so a rename only ever lands
+// in selector position. A declaration block is skipped whole (`content: "A"`,
+// `font-family: Georgia` are not selectors), and so is an at-rule's own prelude
+// (`@import url(Foo.css)` names a file, not a component).
+//
+// A string or a comment inside a selector is emitted verbatim and *ends* the
+// chunk being renamed, so `[title="a > Boo"]` keeps its Boo. The at-rule test
+// reads the whole prelude rather than the last chunk, or a `@supports
+// (font-family: "X")` would stop looking like one the moment its string was
+// split off
+const renameComponentSelectors = (css: string): string => {
+  let out = ""
+  let pending = "" // renamable text: selector source since the last verbatim run
+  let prelude = "" // everything since the last delimiter, for the at-rule test
+  const stack: boolean[] = [] // true = the block holds rules, not declarations
+  const inSelectorPosition = () => stack.length === 0 || stack[stack.length - 1]
+
+  const flush = () => {
+    out += inSelectorPosition() && !AT_RULE_RE.test(prelude) ? renameSelectorNames(pending) : pending
+    pending = ""
+  }
+  const verbatim = (text: string) => {
+    flush()
+    out += text
+    prelude += text
+  }
+  const delimiter = (char: string, holdsRules?: boolean) => {
+    flush()
+    out += char
+    prelude = ""
+    if (holdsRules !== undefined) stack.push(holdsRules)
+    else if (char === "}") stack.pop()
+  }
+
+  for (let i = 0; i < css.length; ) {
+    const char = css[i]
+    if (char === "/" && css[i + 1] === "*") {
+      const end = css.indexOf("*/", i + 2)
+      const stop = end === -1 ? css.length : end + 2
+      verbatim(css.slice(i, stop))
+      i = stop
+    } else if (char === '"' || char === "'") {
+      let j = i + 1
+      while (j < css.length && css[j] !== char) j += css[j] === "\\" ? 2 : 1
+      verbatim(css.slice(i, Math.min(j + 1, css.length)))
+      i = j + 1
+    } else if (char === "{") {
+      delimiter("{", NESTED_AT_RULE_RE.test(prelude))
+      i++
+    } else if (char === "}" || char === ";") {
+      delimiter(char)
+      i++
+    } else {
+      pending += char
+      prelude += char
+      i++
+    }
+  }
+  flush()
+  return out
+}
+
 // the CSS parser is the browser's own (no dependency, no hand-rolled parser).
 // Note browsers *silently drop* rules whose selector they can't parse, which
 // is what Vue's :deep()/::v-deep/>>> escape hatches are - unsupported here,
@@ -2499,7 +3195,7 @@ const parseComponentString = (component: string): ComponentParts => {
   //   const fullName = `${fname} ${lname}`
   // </script>
   //
-  // <div :attrs="{ fullName }"></div>
+  // <div :title="fullName"></div>
   // <div class="full-name">
   //  {{ fullName }}
   // </div>
@@ -2599,6 +3295,15 @@ const componentPartsFrom = (elements: Element[], hashSource: string): ComponentP
     }
   })
 
+  // a component's name in a selector becomes the tag its box actually has,
+  // once per definition and in `content` itself, so every path downstream gets
+  // it: document.head, the scoped rewrite below, and a shadow root (which uses
+  // `content` directly). A `lang` block is skipped for the same reason scoping
+  // skips it - it is not CSS yet
+  styles.forEach(style => {
+    if (!("lang" in style.attrs)) style.content = renameComponentSelectors(style.content)
+  })
+
   // scoping is resolved once, here: the stamped template and the scoped CSS
   // are what every instance of this definition renders and injects. An
   // uncompiled `lang` block is left as it was written - rewriting selectors
@@ -2703,6 +3408,30 @@ const sourceUrlComment = (filename: string | undefined, index: number): string =
 // nothing: the host element is outside the template, so it carries no stamp)
 const headStyle = (style: TagBlock): string => style.scoped ?? style.content
 
+// the one rule every component box needs: an element where there was none is a
+// box where there was none, and a component inside a flex or grid parent would
+// otherwise become an inline wrapper holding the real child. `display: contents`
+// removes the box and leaves the children in the parent's layout.
+//
+// `:where()` is load-bearing: it has zero specificity, so any author rule wins
+// without !important and without depending on which stylesheet the browser saw
+// first. `c79-panel { display: flex }` opts a component's box back into being a
+// box, which is the point of naming it.
+//
+// Not refcounted like a component's own styles: it is one constant rule for the
+// whole document, so it is injected on the first box and stays. The
+// isConnected check is what makes it survive a head somebody emptied
+const WRAPPER_STYLE = `:where([${COMPONENT_BOX_ATTR}]) { display: contents }`
+
+let wrapperStyleEl: HTMLStyleElement | null = null
+
+const ensureWrapperStyle = () => {
+  if (wrapperStyleEl?.isConnected) return
+  wrapperStyleEl = document.createElement("style")
+  wrapperStyleEl.textContent = WRAPPER_STYLE
+  document.head.appendChild(wrapperStyleEl)
+}
+
 // document.head styles are shared by content and refcounted, so N instances
 // of the same component (e.g. one per :each item) inject a single <style> tag
 // that goes away when the last instance is destroyed
@@ -3317,11 +4046,25 @@ export class Component79 {
   // nobody could debug
   static debug(options?: Partial<DebugFlags>): DebugFlags {
     if (options) {
+      // an expression is compiled once and cached for the life of the page, so
+      // flipping the form it compiles to has to drop what was compiled under
+      // the old one - otherwise "off" leaves every expression already rendered
+      // still running the prologue
+      const scopedBefore = debugFlags.scopedNames
       for (const key in options) {
         const value = options[key as keyof DebugFlags]
-        if (typeof value === "boolean") debugFlags[key as keyof DebugFlags] = value
+        // the key before the value: a typo carrying a boolean - `cloneSkeleton`
+        // for `cloneSkeletons` - used to pass this guard, land in the flags and
+        // come back in the return value, so a caller read "cloning is off" while
+        // it was still on. RECORD/2026-08-25.two-defects-a-review-found.md
+        // hasOwnProperty, not `in`: `in` walks the prototype chain, so
+        // `debug({ toString: false })` passed this guard and landed on the flags
+        if (!Object.prototype.hasOwnProperty.call(debugFlags, key)) {
+          console.warn(`jq79: Component79.debug does not know "${key}" - the flags it has are: ${Object.keys(debugFlags).join(", ")}`)
+        } else if (typeof value === "boolean") debugFlags[key as keyof DebugFlags] = value
         else console.warn(`jq79: Component79.debug ignored "${key}" - the flags are booleans, and the ones it knows are: ${Object.keys(debugFlags).join(", ")}`)
       }
+      if (debugFlags.scopedNames !== scopedBefore) compiled.clear()
     }
     return { ...debugFlags }
   }
@@ -3640,11 +4383,18 @@ export class Component79 {
     }
 
     if (shadow) {
-      this.styleEls = this.styles.map(style => {
+      // document.head cannot reach into a shadow root, so every component box
+      // rendered inside this one needs the wrapper rule here. It goes last, and
+      // the position carries nothing: :where() has no specificity, so an author
+      // rule wins wherever it sits. What it does buy is that "the shadow root's
+      // style" still means the component's own
+      const wrapperEl = document.createElement("style")
+      wrapperEl.textContent = WRAPPER_STYLE
+      this.styleEls = [...this.styles.map(style => {
         const el = document.createElement("style")
         el.textContent = style.content // the source: a shadow root scopes it already
         return el
-      })
+      }), wrapperEl]
     } else {
       this.styles.forEach(style => acquireStyle(headStyle(style)))
       this.ownsSharedStyles = true