jq79 0.7.2 → 0.7.4

package/src/precompile.ts

@@ -0,0 +1,238 @@
+import { parseHTML, type HTMLNode, type HTMLElementNode } from "./html"
+import { transformSetupScript, transformFactoryScript, parsePropsPattern, parseFactoryProps } from "./transform"
+import {
+  COMPONENT_NAME_RE, COMPONENT_TAG_ATTR, EACH_PATTERN, EXPR_PARAMS, INSTANCE_HELPER_NAMES, PRECOMPILED_QUEUE,
+  SETUP_HELPER_NAMES, functionText,
+  assignment, declaredPropNames, defer, factoryBody, factoryParams, functionKey, isControlAttr, isSlotTag,
+  kebabToCamel, prepareSource, readSetupSignature, scopedBody, setupBody, setupParams, splitText, withBody,
+  type TagBlock, type TemplateNode,
+} from "./source"
+
+// ---------------------------------------------------------------------------
+// precompile
+//
+// Every function the runtime would build for a component, found without
+// rendering it: each expression in its template, each of its scripts, each
+// prop default - as the [params, body] pairs makeFunction would be handed, so
+// a table of them answers its lookups (see "safe eval" in jq79.ts). What renders
+// nothing still counts: a branch not taken, a handler never clicked, a :each
+// over an empty list are all here because each *could* run.
+//
+// It reads a file the way parseComponentString does - the same pre-parse
+// rewrites, the same split into the file's own component and its named
+// <template>s - with parseHTML standing in for DOMParser, which node and a
+// worker don't have. It reads a template the way the renderer does, directive
+// by directive, and builds each body with the same functions the runtime
+// compiles with (withBody, scopedBody, setupBody, factoryBody), so a key can
+// only match. Where the renderer's answer depends on the page - which scope
+// key a component tag resolves to - it takes every plausible one: an extra
+// function is an entry nobody looks up. What it can't see is a miss, and safe
+// mode reports a miss by name. tests/precompile.test.ts holds it against what
+// the runtime actually compiles
+// ---------------------------------------------------------------------------
+
+export type Precompiled = [params: string[], body: string]
+
+const isElementNode = (node: HTMLNode): node is HTMLElementNode => typeof node !== "string"
+
+// mirrors elementToAST: the component stamp lifted off attrs into a field
+const toTemplateNode = (el: HTMLElementNode): TemplateNode => {
+  const { [COMPONENT_TAG_ATTR]: component, ...attrs } = el.attrs
+  return {
+    tag: el.tag,
+    attrs,
+    ...(component === undefined ? {} : { component }),
+    children: el.children.map(child => (typeof child === "string" ? child : toTemplateNode(child))),
+  }
+}
+
+const textOf = (el: HTMLElementNode): string => el.children.map(child => (typeof child === "string" ? child : textOf(child))).join("")
+
+// the scope keys a tag can resolve to. findComponentKey matches any
+// capitalized key that equals the tag once dashes and case are gone, so the
+// key itself comes from the page; these are the spellings the file offers -
+// the tag as written, its PascalCase, and every capitalized name the file
+// declares that matches
+const componentKeyCandidates = (node: TemplateNode, known: string[]): string[] => {
+  const tag = node.component ?? node.tag
+  const normalized = tag.replace(/-/g, "").toLowerCase()
+  const keys = new Set(known.filter(name => /^[A-Z]/.test(name) && name.replace(/-/g, "").toLowerCase() === normalized))
+  keys.add(node.component ?? kebabToCamel(node.tag).replace(/^./, c => c.toUpperCase()))
+  return [...keys]
+}
+
+type AddExpression = (expr: string, extras?: string[]) => void
+
+// every expression a template can evaluate, walked as renderNodes, renderNode,
+// renderEach, renderConditional, renderSlot and renderNestedComponent would
+// walk it - each clause names the one it follows
+const collectExpressions = (nodes: (TemplateNode | string)[], known: string[], add: AddExpression) => {
+  for (const node of nodes) {
+    // renderNodes: text with an interpolation in it
+    if (typeof node === "string") {
+      if (node.includes("{{")) splitText(node).forEach(part => { if (typeof part !== "string") add(part.expr) })
+      continue
+    }
+    const attrs = node.attrs
+    // renderConditional (chainOf), renderEach, and :with in renderNode - on any node
+    if (":if" in attrs) add(attrs[":if"])
+    if (":elseif" in attrs) add(attrs[":elseif"])
+    if (":each" in attrs) {
+      const match = attrs[":each"].match(EACH_PATTERN)
+      if (match) add(match[3])
+      if (":key" in attrs) add(attrs[":key"])
+    }
+    if (":with" in attrs) add(attrs[":with"])
+    // bindSlotProps: a :slot binder's defaults, on a component tag or its <template>
+    for (const attr in attrs) {
+      if (attr === ":slot" || attr.startsWith(":slot.")) {
+        parsePropsPattern(attrs[attr] || undefined)?.forEach(({ default: fallback }) => { if (fallback !== undefined) add(fallback) })
+      }
+    }
+
+    if (isSlotTag(node.tag)) {
+      // renderSlot: a <slot>'s props - read by name, not camelCased
+      for (const attr in attrs) {
+        if (isControlAttr(attr) || attr.startsWith("@") || !attr.startsWith(":")) continue
+        add(attrs[attr] || attr.slice(1))
+      }
+    } else {
+      // renderNestedComponent, for a tag that is or may become a component: the
+      // key it resolves through, its props, spreads, models and tag events
+      if (node.component !== undefined || node.tag.includes("-")) {
+        componentKeyCandidates(node, known).forEach(key => add(key))
+        for (const attr in attrs) {
+          const value = attrs[attr]
+          if (attr === ":props" || attr.startsWith(":props.")) add(value)
+          else if (isControlAttr(attr)) continue
+          else if (attr.startsWith("@")) add(value, ["$event"])
+          else if (attr === ":model" || attr.startsWith(":model.")) {
+            const expr = value || (attr === ":model" ? "model" : kebabToCamel(attr.slice(":model.".length)))
+            add(expr)
+            add(assignment(expr), ["$value"])
+          } else if (attr.startsWith(":")) add(value || kebabToCamel(attr.slice(1)))
+          else add(JSON.stringify(value))
+        }
+      }
+      // renderNode, for the element it renders as (and a component tag renders
+      // as, until it resolves): events, bindings, and the control directives
+      for (const attr in attrs) {
+        const value = attrs[attr]
+        if (attr.startsWith("@")) add(value, ["$event"])
+        else if (attr === ":model" || attr.startsWith(":model.")) continue
+        else if (attr === ":class" || attr.startsWith(":class.") || attr === ":text" || attr === ":html" ||
+          attr === ":html.allowed" || attr === ":value" || attr === ":checked" || attr === ":selected") add(value)
+        else if (isControlAttr(attr)) continue
+        else if (attr.startsWith(":")) add(value || kebabToCamel(attr.slice(1)))
+      }
+    }
+    collectExpressions(node.children, known, add)
+  }
+}
+
+// every function the runtime would build for the component in `source`, as
+// the [params, body] makeFunction would be handed - see the note above
+export const precompile = (source: string): Precompiled[] => {
+  const found = new Map<string, Precompiled>()
+  const add = (params: string[], body: string) => { found.set(functionKey(params, body), [params, body]) }
+  // an expression compiles to its scoped form first, and falls back to (or is
+  // demoted to) the `with` form - both, where the scoped one exists
+  const addExpression: AddExpression = (expr, extras = []) => {
+    const params = [...EXPR_PARAMS, ...extras]
+    const scoped = scopedBody(expr, extras)
+    if (scoped !== null) add(params, scoped)
+    add(params, withBody(expr))
+  }
+
+  // parseComponentString's split: a top-level <template> declares another
+  // component of the file (a valid name, first one wins), everything else is
+  // the file's own
+  const top = parseHTML(prepareSource(source)).filter(isElementNode)
+  const siblings: string[] = []
+  const components: HTMLElementNode[][] = [top.filter(el => el.tag !== "template")]
+  top.filter(el => el.tag === "template").forEach(el => {
+    const name = el.attrs.name
+    if (name === undefined || !COMPONENT_NAME_RE.test(name) || siblings.includes(name)) return
+    siblings.push(name)
+    components.push(el.children.filter(isElementNode))
+  })
+
+  components.forEach(elements => precompileComponent(elements, siblings, add, addExpression))
+
+  return [...found.values()]
+}
+
+const precompileComponent = (
+  elements: HTMLElementNode[],
+  siblings: string[],
+  add: (params: string[], body: string) => void,
+  addExpression: AddExpression
+) => {
+  const scripts: TagBlock[] = elements
+    .filter(el => el.tag === "script")
+    .map(el => ({ attrs: el.attrs, content: textOf(el) }))
+  const template = elements.filter(el => el.tag !== "script" && el.tag !== "style").map(toTemplateNode)
+
+  // the helper names a script is compiled with: renderWith's
+  // { ...SETUP_HELPERS, ...instanceHelpers }, where instanceHelpers is
+  // { $mounted, $destroyed, $attached, $detached, $computed, $self, $$self,
+  // ...injected, ...siblingScope } - key order included, because the
+  // parameters are positional (built as objects, so a sibling named like a
+  // helper keeps the helper's place, as it does there)
+  //
+  // Reading the signatures is also the first thing renderWith does, and where
+  // it refuses a component - a factory destructuring a ctx name out of props
+  // throws there, before anything compiles. Such a component has nothing to
+  // precompile, and returning here leaves its error to the runtime, which is
+  // where the page sees it, rather than failing the build (or the worker) on
+  // its behalf
+  let declared: Set<string>
+  try {
+    declared = declaredPropNames(scripts, readSetupSignature)
+  } catch {
+    return
+  }
+  const siblingScope = Object.fromEntries(siblings.filter(name => !declared.has(name)).map(name => [name, true]))
+  const helperNames = Object.keys({
+    ...Object.fromEntries(SETUP_HELPER_NAMES.map(name => [name, true])),
+    ...Object.fromEntries(INSTANCE_HELPER_NAMES.map(name => [name, true])),
+    ...siblingScope,
+  })
+
+  // the names the file declares, for the component tags that resolve to one
+  const known = [...siblings]
+  scripts.forEach(script => {
+    const deferred = ":mounted" in script.attrs
+    const factoryCode = transformFactoryScript(script.content)
+    if (factoryCode !== null) {
+      const props = parseFactoryProps(script.content)
+      props?.forEach(({ name, default: fallback }) => { known.push(name); if (fallback !== undefined) addExpression(fallback) })
+      add(factoryParams(helperNames), factoryBody(deferred ? defer(factoryCode) : factoryCode))
+    } else {
+      const { vars, code } = transformSetupScript(script.content)
+      known.push(...vars)
+      readSetupSignature(script)?.forEach(({ name, default: fallback }) => { known.push(name); if (fallback !== undefined) addExpression(fallback) })
+      add(setupParams(helperNames), setupBody(deferred ? defer(code) : code))
+    }
+  })
+
+  collectExpressions(template, known, addExpression)
+}
+
+// a component's precompiled functions as the classic script that registers
+// them - classic, because they compile under `with`, which is a SyntaxError in
+// strict code and every module is strict.
+//
+// `parses` says whether a function's text parses as that one function: `new
+// Function` where eval is at hand (the Vite plugin, on node), a JavaScript
+// parser where it isn't (the service worker). One that doesn't parse ships as
+// null - the runtime's cached syntax error, which renders nothing, as it does
+// under eval. And because only text that parses as a single function is ever
+// written, no expression can close its function early and run what follows
+// when the script loads
+export const precompiledScript = (entries: Precompiled[], parses: (params: string[], body: string) => boolean): string => {
+  const items = entries.map(([params, body]) =>
+    `[${JSON.stringify(params)}, ${JSON.stringify(body)}, ${parses(params, body) ? functionText(params, body) : "null"}]`
+  )
+  return `(self.${PRECOMPILED_QUEUE} = self.${PRECOMPILED_QUEUE} || []).push(\n${items.join(",\n")}\n)\n`
+}

package/src/reactive.ts

@@ -173,19 +173,32 @@ const STORE = Symbol("jq79.store")
 const isStore = (value: any): boolean =>
   value !== null && typeof value === "object" && value[STORE] === true
 
+// the effect the last $effect call made, set as that call returns - after its
+// first run, so the effects that run created don't leave theirs here instead.
+// How a Scope gets hold of the record behind the disposer $effect hands back,
+// without $effect returning anything more than it always has (see Scope.effect)
+let created: Effect | null = null
+
 // active $effect() runs, innermost last - a module-level stack (rather than
 // one per store) so nested effects across stores still nest correctly; reads
 // during a proxy's `get` trap are attributed to whichever run is on top
 const trackerStack: Set<string>[] = []
 
+// the effect whose run is on top of trackerStack, or null while tracking is
+// suspended. A store read by an effect it doesn't hold adopts it (see adopt)
+let activeEffect: Effect | null = null
+
 // runs fn with dependency tracking suspended - reads inside it are attributed
 // to a throwaway set instead of the currently running effect
 export const untracked = <T>(fn: () => T): T => {
   trackerStack.push(new Set())
+  const outer = activeEffect
+  activeEffect = null
   try {
     return fn()
   } finally {
     trackerStack.pop()
+    activeEffect = outer
   }
 }
 
@@ -193,7 +206,39 @@ export const untracked = <T>(fn: () => T): T => {
 // own, plus any it was attached to), each keeping that store's trie in step
 // with the deps of the last settled run. It lives on the effect rather than
 // in a per-store map because `run` has to reach it without a lookup
-export type Effect = { deps: Set<string>; run: () => void; reindex: Set<(deps: Set<string>) => void>; deep: boolean; order: number }
+//
+// `home` is the effect set of the store that created it, which is what lets a
+// read skip the adoption check with one comparison. `adopted` maps every other
+// store that took it on (by that store's effect set) to the handle detaching
+// it, and `read` collects the ones the current run read - a store the settled
+// run didn't read lets go of it (see adopt)
+export type Effect = {
+  deps: Set<string>
+  run: () => void
+  reindex: Set<(deps: Set<string>) => void>
+  deep: boolean
+  order: number
+  home: Set<Effect>
+  adopted: Map<Set<Effect>, Unsubscribe> | null
+  read: Set<Set<Effect>> | null
+}
+
+// the settled run read none of these stores: they stop waking the effect.
+// `current = second` must leave `first` with nothing of it, or a write to the
+// store it dropped still re-runs it - it is indexed there under the same
+// namespace-free paths it reads off `second`
+const releaseUnread = (effect: Effect) => {
+  effect.adopted!.forEach((detach, store) => {
+    if (effect.read?.has(store)) return
+    detach()
+    effect.adopted!.delete(store)
+  })
+}
+
+const releaseAll = (effect: Effect) => {
+  effect.adopted?.forEach(detach => detach())
+  effect.adopted = null
+}
 
 // creation order, module-wide. The flat `effects` set used to give this for
 // free - iterating it ran effects oldest-first, so a parent's bindings always
@@ -227,12 +272,25 @@ const NO_DEPS: ReadonlySet<string> = new Set()
 // never a stale render
 const ATTACH = "$__attach"
 
+// whether an effect is registered with this store - the holder of a bridge
+// asks, so it doesn't wake what the nested store already will (see effectsFor)
+const HOLDS = "$__holds"
+
 // the extra stores every effect created off a scope must be attached to. Read
 // by createEffectScope off the scope it is given, so a scope can hand the
 // arrangement down to whatever renders inside it (nested :each item scopes,
 // a nested component's prop-sync effects) without every call site knowing
 export const ALSO_WAKEN_BY = Symbol("jq79.alsoWakenBy")
 
+// the effect scope that owns everything rendered under a data scope - set on a
+// keyed :each row's item scope, pointing at that row's scope. Read the same
+// way ALSO_WAKEN_BY is, off the data scope a new effect scope is created over,
+// so every scope made anywhere inside the row registers with it: an :if branch,
+// a nested :each and its rows, a component's prop sync, and slot content the
+// row hands a child component, which is created by the child but closes over
+// the row's names. That registry is what EffectScope.rerun walks
+export const OWNER = Symbol("jq79.owner")
+
 export const $reactive = <T extends Record<string, any>>(data: T): ReactiveDeepData<T> => {
   const exactListeners = new Map<string, Set<ChangeListener>>()
   const anyListeners = new Set<AnyChangeListener>()
@@ -339,7 +397,12 @@ export const $reactive = <T extends Record<string, any>>(data: T): ReactiveDeepD
       eachDeep(node, effect => matched.add(effect))
       // a nested store sits here: an effect that read through it holds this
       // path and nothing below it, so its own set is the whole channel
-      if (bridges.has(path)) eachOwn(node, effect => matched.add(effect))
+      //
+      // ...except an effect the nested store already wakes itself: one that
+      // read into it was adopted there (see adopt), and matches its own paths
+      // precisely. Waking it here too ran it twice per write
+      const bridged = bridges.get(path)
+      if (bridged) eachOwn(node, effect => { if (!bridged.store[HOLDS](effect)) matched.add(effect) })
       // ...whereas an array's length stands for the array: everything that
       // read an element has to hear a truncation, and those deps are below
       if (depth === segments.length - 2 && segments[depth + 1] === "length") {
@@ -774,6 +837,7 @@ export const $reactive = <T extends Record<string, any>>(data: T): ReactiveDeepD
       // KEYS_SEGMENT), so adds and deletes wake exactly the effects enumerating
       ownKeys(target) {
         trackerStack[trackerStack.length - 1]?.add(keysPath(path))
+        if (activeEffect !== null && activeEffect.home !== effects) adopt(activeEffect)
         return Reflect.ownKeys(target)
       },
       get(target, key, receiver) {
@@ -784,6 +848,7 @@ export const $reactive = <T extends Record<string, any>>(data: T): ReactiveDeepD
 
         const dotKey = path ? `${path}.${key}` : key
         trackerStack[trackerStack.length - 1]?.add(dotKey)
+        if (activeEffect !== null && activeEffect.home !== effects) adopt(activeEffect)
 
         // nested objects are wrapped here rather than up front, so the object
         // handed to $reactive is never rewritten
@@ -904,6 +969,9 @@ export const $reactive = <T extends Record<string, any>>(data: T): ReactiveDeepD
       reindex: new Set(),
       deep,
       order: effectsCreated++,
+      home: effects,
+      adopted: null,
+      read: null,
       run: () => {
         if (running) {
           dirty = true
@@ -914,12 +982,16 @@ export const $reactive = <T extends Record<string, any>>(data: T): ReactiveDeepD
           let cycles = 0
           do {
             dirty = false
+            effect.read = null
             const deps = new Set<string>()
             trackerStack.push(deps)
+            const outer = activeEffect
+            activeEffect = effect
             try {
               run()
             } finally {
               trackerStack.pop()
+              activeEffect = outer
               effect.deps = deps
             }
           } while (dirty && ++cycles < 100)
@@ -928,6 +1000,7 @@ export const $reactive = <T extends Record<string, any>>(data: T): ReactiveDeepD
           if (dirty) console.error("jq79: an effect re-woke itself 100 times in a row (it writes what it reads); giving up on it settling")
         } finally {
           running = false
+          if (effect.adopted) releaseUnread(effect)
           // the settled deps are the only ones worth indexing: the repeats of
           // a dirty run overwrite each other, and a notify that lands mid-run
           // is queued rather than dispatched, so nothing reads the index in
@@ -942,6 +1015,7 @@ export const $reactive = <T extends Record<string, any>>(data: T): ReactiveDeepD
     const forget = () => {
       effects.delete(effect)
       stopIndexing()
+      releaseAll(effect)
     }
     // the shared case is rare (only slot content asks for it) and this
     // function is on the stack for as long as whatever it renders - a
@@ -949,6 +1023,7 @@ export const $reactive = <T extends Record<string, any>>(data: T): ReactiveDeepD
     // shape it had, and the extra bookkeeping lives in its own frame
     if (alsoWakenBy?.length) return attachAndRun(effect, alsoWakenBy, forget)
     effect.run()
+    created = effect
     return forget
   }
 
@@ -957,6 +1032,7 @@ export const $reactive = <T extends Record<string, any>>(data: T): ReactiveDeepD
   const attachAndRun = (effect: Effect, alsoWakenBy: Record<string, any>[], forget: Unsubscribe): Unsubscribe => {
     const detach = alsoWakenBy.map(store => store?.[ATTACH]?.(effect)).filter(Boolean) as Unsubscribe[]
     effect.run()
+    created = effect
     return () => {
       forget()
       detach.forEach(drop => drop())
@@ -972,9 +1048,29 @@ export const $reactive = <T extends Record<string, any>>(data: T): ReactiveDeepD
     }
   }
 
+  // an effect of another store just read this one. Tracking spans stores -
+  // the deps it recorded are this store's paths - but waking did not: the
+  // effect sat in its own store's index alone, where `list.1.busy` means
+  // nothing, so a write here reached it only if it had also read the path
+  // this store sits at in its own, and then through the bridge's catch-all.
+  // A `:each` row reads its item directly and never does, so it never updated.
+  // Registered here like slot content is (see ATTACH), and detached when the
+  // effect is disposed
+  //
+  // Only an effect that isn't already registered here some other way: slot
+  // content is attached to both its stores for as long as it lives, and is
+  // not this function's to release
+  const adopt = (effect: Effect) => {
+    ;(effect.read ??= new Set()).add(effects)
+    if (effect.adopted?.has(effects) || effects.has(effect)) return
+    ;(effect.adopted ??= new Map()).set(effects, $__attach(effect))
+  }
+
   const $dispose = () => {
     bridges.forEach(({ unsubscribe }) => unsubscribe())
     bridges.clear()
+    // ...and the stores that adopted this one's effects by being read
+    effects.forEach(effect => { if (effect.home === effects) releaseAll(effect) })
   }
 
   storeApi.$on = $on
@@ -982,6 +1078,7 @@ export const $reactive = <T extends Record<string, any>>(data: T): ReactiveDeepD
   storeApi.$effect = $effect
   storeApi.$dispose = $dispose
   storeApi[ATTACH] = $__attach
+  storeApi[HOLDS] = (effect: Effect) => effects.has(effect)
 
   return reactive
 }
@@ -997,9 +1094,20 @@ export type EffectScope = {
   onDispose: (fn: Unsubscribe) => void
   // re-runs every effect registered on this scope, nested scopes excluded:
   // how :each tells a reused, repositioned entry's dep-less bindings (the
-  // `{{ $index }}`-only case) about their move. Deps stay as they were -
-  // callers run it untracked
+  // `{{ $index }}`-only case) about their move. Each run tracks its own deps,
+  // as a woken one does; callers run it untracked, so none of them land on
+  // the list effect that asked
   refresh: () => void
+  // re-runs every effect on this scope and on every scope registered with it
+  // (see OWNER), tracking each run as if a write had woken it. How a keyed
+  // :each row that was handed a new item for the same key updates in place:
+  // the loop name is a plain scope var, so nothing it read can wake the
+  // bindings, and the deps they hold are the old item's
+  rerun: () => void
+  // registers this scope with the row owning `scope` as well (see OWNER):
+  // slot content's own chain is the parent's, but the slot props it reads
+  // come from wherever the child put the <slot>, which can be a keyed row
+  ownedBy: (scope: Record<string, any>) => void
   dispose: () => void
 }
 
@@ -1019,10 +1127,17 @@ export type EffectScope = {
 // function (`runSetupScript(..., fx.effect, ...)` did) must wrap it instead
 // (`run => fx.effect(run)`). Both such call sites are in renderComponent
 class Scope implements EffectScope {
-  // built on first use: `runs` in particular is only ever read by refresh(),
-  // which only a :each whose template names a position ever calls
+  // built on first use: `runs` in particular is only ever read by refresh()
+  // and rerun(), which only a :each calls - for a row that moved and names a
+  // position, or a keyed row handed a new item
   private disposers: Unsubscribe[] | null = null
-  private runs: (() => void)[] | null = null
+  private runs: Effect[] | null = null
+  // the scopes created under this one's data scope, when this one owns it
+  // (see OWNER), and the owners this one registered with - two for slot
+  // content written in one keyed row and placed in another (see ownedBy).
+  // Neither exists outside a keyed :each row
+  private children: Set<Scope> | null = null
+  private owners: Scope[] | null = null
   // one options object for the whole scope instead of one per effect - $effect
   // destructures it on entry and keeps nothing. Left undefined on the common
   // path, which is $effect's own fast path
@@ -1033,11 +1148,21 @@ class Scope implements EffectScope {
     // it today): the stores this scope's effects belong to besides their own
     const alsoWakenBy: Record<string, any>[] | undefined = (scope as any)[ALSO_WAKEN_BY]
     this.options = deep || alsoWakenBy ? { deep, alsoWakenBy } : undefined
+    this.ownedBy(scope)
+  }
+
+  ownedBy(scope: Record<string, any>) {
+    const owner: Scope | undefined = (scope as any)[OWNER]
+    if (!owner || this.owners?.includes(owner)) return
+    ;(this.owners ??= []).push(owner)
+    ;(owner.children ??= new Set()).add(this)
   }
 
+  // the effect record rather than `run`: a re-run through it tracks, so the
+  // deps it settles on are the ones the run actually read
   effect(run: () => void) {
     ;(this.disposers ??= []).push(this.scope.$effect(run, this.options))
-    ;(this.runs ??= []).push(run)
+    ;(this.runs ??= []).push(created!)
   }
 
   onDispose(fn: Unsubscribe) {
@@ -1045,7 +1170,19 @@ class Scope implements EffectScope {
   }
 
   refresh() {
-    this.runs?.forEach(run => run())
+    this.runs?.forEach(effect => effect.run())
+  }
+
+  // this scope's own effects first, then the scopes under it, in the order
+  // they were created - parents before what they rendered, as a write would
+  // wake them. Both lists are copied before anything runs: an :if that switches
+  // branch disposes one child scope and renders another, already up to date,
+  // and a disposed scope has nothing left to run
+  rerun() {
+    const runs = this.runs ? [...this.runs] : null
+    const children = this.children ? [...this.children] : null
+    runs?.forEach(effect => { if (this.runs) effect.run() })
+    children?.forEach(child => child.rerun())
   }
 
   dispose() {
@@ -1055,8 +1192,40 @@ class Scope implements EffectScope {
     const disposers = this.disposers
     this.disposers = null
     this.runs = null
+    this.children = null
+    this.owners?.forEach(owner => owner.children?.delete(this))
+    this.owners = null
     if (disposers) for (let i = 0; i < disposers.length; i++) disposers[i]()
   }
 }
 
 export const createEffectScope = (scope: Record<string, any>, deep = false): EffectScope => new Scope(scope, deep)
+
+// a derived value: `get`'s result on `.value`, recomputed whenever anything it
+// read changes - in any store, the way any effect is woken. What comes back is
+// a store, so it does everything one does (passed as a prop, held in another
+// store and bridged there, $on("value")), seen through a read-only view: a
+// write would be overwritten by the next recompute, so it is refused aloud
+// instead (see RECORD/2026-10-01.computed.md)
+export type Computed<T> = ReactiveDeepData<{ readonly value: T }>
+
+export const $computed = <T>(get: () => T): Computed<T> => {
+  const box = $reactive({ value: undefined as T })
+  box.$effect(() => {
+    let value: T
+    try {
+      value = get()
+    } catch (error) {
+      // left to propagate, it would throw out of whatever write woke it -
+      // `cart.items.push(x)` failing for code that has nothing to do with it
+      console.error("jq79: error in $computed, keeping its last value", error)
+      return
+    }
+    box.value = value
+  })
+  const refuse = (_target: object, key: string | symbol): boolean => {
+    console.warn(`jq79: a $computed is read-only - the write to ${String(key)} was ignored`)
+    return true
+  }
+  return new Proxy(box, { set: refuse, deleteProperty: refuse, defineProperty: refuse }) as Computed<T>
+}