jq79 0.7.4 → 0.7.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jq79",
-  "version": "0.7.4",
+  "version": "0.7.6",
   "description": "Mini reactive component library: single-file .html components, Svelte-style setup scripts, fine-grained proxy reactivity. No compiler, no bundler, no dependencies — works from any static host.",
   "keywords": [
     "reactive",

package/src/jq79.ts

@@ -1341,6 +1341,12 @@ const renderNestedComponent = (key: string, node: TemplateNode, scope: Record<st
     } finally {
       nestingDepth--
     }
+    // a child whose script holds its render paints later than this template:
+    // its owner's $mounted() waits for it. Absent under renderComponent(),
+    // where no instance owns the template
+    const box: PendingScripts | undefined = (scope as any)[PENDING_SCRIPTS]
+    if (box) instance.holdOwner(box.owner)
+
     // 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
@@ -3351,8 +3357,10 @@ const importResource = (url: string): Promise<any> =>
 // For the same reason a *root-absolute* specifier is resolved too, not passed
 // through: `/x.js` means the page's root to whoever wrote it, and the page is
 // the only base under which the two branches agree. Bare specifiers ("lodash")
-// are the exception that stays untouched - they belong to the import map or
-// the bundler, and resolving one would quietly turn it into a path.
+// are the exception that stays untouched here - they belong to the import map
+// or the bundler, and resolving one against a base would quietly turn it into
+// a path. A bare *.html* one still reaches the map: fetchComponent asks it,
+// since fetch() cannot (see resolveBare)
 //
 // The base is absolutized first, the way hotKey does and for the same reason:
 // the filename may itself be relative ("./card.html", from an import() in a
@@ -3715,9 +3723,13 @@ const UNFILLED_PROPS = Symbol("jq79.unfilledProps")
 // awaited $mounted() is exactly the case the count keeps quiet. Read live, so
 // an :if that opens after everything settled is judged against the scripts as
 // they are then, not as they were at the first paint
+//
+// It also names the instance whose render generation it belongs to, so a
+// nested component rendered anywhere in that template - an :each row, slot
+// content - can tell its owner it hasn't painted yet (see holdOwner)
 const PENDING_SCRIPTS = Symbol("jq79.pendingScripts")
 
-type PendingScripts = { count: number }
+type PendingScripts = { count: number; owner: Component79 }
 
 // default-import interop for factory scripts: real modules expose .default,
 // while importing an .html component resolves to the Component79 itself
@@ -3837,6 +3849,11 @@ export const hotUpdate = (filename: string, src: string): number => {
   // parsed once and shared by every instance - which is already what a
   // definition and the clones :component makes from it do
   const parts = parseComponentString(src)
+  // the next fetch of this file - a component mounted after the edit - gets the
+  // edit, not the source the cache held from before it
+  componentCache?.forEach((_, url) => {
+    if (hotKey(url) === key) componentCache!.set(url, Promise.resolve(src))
+  })
   // the file is the hot-reload unit, so one reparse serves every component it
   // declares: an instance is handed the parts of the component it *is*, by
   // name. A name that is no longer in the file (a <template> renamed or
@@ -3902,16 +3919,77 @@ const warnIfStuck = (component: Component79, gates: Promise<void>[]) => {
   Promise.all(gates).then(() => clearTimeout(timer))
 }
 
-const fetchComponent = async (url: string): Promise<Component79> => {
+// a bare specifier belongs to the import map, and native import() reads one -
+// fetch() never does, so `fetch("@app/card.html")` asks the page's directory
+// for a folder named "@app". A bare URL is resolved here through the same map,
+// with the function import() itself would use, so the component gets the URL
+// its own relative imports, its precompiled script and its HMR key resolve
+// against. That includes a relative path written without "./" ("views/x.html"):
+// it reaches the map too, and changes only if the map names it. One the map
+// does not name throws, and goes on unchanged, as it did before.
+//
+// The map is read as this module sees it: a `scopes` entry applies when it
+// covers jq79.js, not the component. Guarded because the CJS and classic-script
+// builds (jq79.cjs, jq79.global.js) have no import.meta, and there bare URLs go
+// to fetch() as they are
+const resolveBare = (url: string): string => {
+  if (RESOLVABLE_SPECIFIER_RE.test(url)) return url
+  const resolve = (import.meta as { resolve?: (spec: string) => string }).resolve
+  if (typeof resolve !== "function") return url
+  try {
+    return resolve(url)
+  } catch {
+    return url
+  }
+}
+
+// a component's source by the absolute URL it came from, so a file that a
+// page fetches, fetchAll()s and import()s from a dozen setup scripts is
+// downloaded once (Component79.cache). The text, not the component: each
+// fetch still hands back an instance of its own, as it always has - mounting
+// one never touches another. A promise, so two requests in flight share one
+// download; a failed one is dropped, and the next request tries again.
+// Under safeEval()'s worker the entry settles once the precompiled functions
+// are in too, so those load once per file as well
+let componentCache: Map<string, Promise<string>> | null = new Map()
+
+const cacheKey = (url: string): string => {
+  try {
+    return new URL(url, document.baseURI).href.replace(/#.*$/, "")
+  } catch {
+    return url
+  }
+}
+
+const downloadComponent = (url: string): Promise<string> =>
   // under safeEval()'s worker, the component's functions arrive beside it,
   // and both have to be in before anyone can render it
-  const [text] = await Promise.all([
+  Promise.all([
     fetch(url).then(response => {
       if (!response.ok) throw new Error(`failed to fetch component from ${url}: ${response.status}`)
       return response.text()
     }),
     safeEvalWorker?.then(() => loadPrecompiled(url)),
-  ])
+  ]).then(([text]) => text)
+
+const componentSource = (url: string): Promise<string> => {
+  if (!componentCache) return downloadComponent(url)
+  const key = cacheKey(url)
+  let text = componentCache.get(key)
+  if (!text) {
+    text = downloadComponent(url)
+    componentCache.set(key, text)
+    const pending = text
+    pending.catch(() => {
+      if (componentCache?.get(key) === pending) componentCache.delete(key)
+    })
+  }
+  return text
+}
+
+const fetchComponent = async (rawUrl: string): Promise<Component79> => {
+  const url = resolveBare(rawUrl)
+  const text = await componentSource(url)
   // the URL names the component's scripts in devtools, and is where the
   // browser will look for the source when a breakpoint lands in one
   return new Component79(text, { filename: url })
@@ -4055,6 +4133,14 @@ export class Component79 {
   // must not resolve on attach alone - a script awaiting it would wake to an
   // empty component and find nothing to query
   private renderDone = false
+  // how many components this generation's first render created that haven't
+  // painted yet - a child whose script awaits an import paints after this
+  // template does. $mounted() means the DOM below is there to query, so it
+  // waits for them too (RECORD/2026-10-22.mounted-waits-for-children.md)
+  private held = 0
+  // set by the usage site of a nested instance that hadn't painted when it was
+  // rendered: tells the owner it has, or that it never will (destroyed first)
+  private onPaint: (() => void) | null = null
   // what this render generation's scripts asked to run when it is torn down
   // ($destroyed). Created on the first call, and taken by destroy() before
   // anything else goes, so a hook still sees the DOM and the store
@@ -4244,6 +4330,24 @@ export class Component79 {
     return Promise.all(steps).then(() => undefined)
   }
 
+  // whether fetch(), fetchAll() and a setup script's import() of an .html
+  // download a file once and reuse its source after that. On by default:
+  //
+  //   Component79.cache()        // true - is it on?
+  //   Component79.cache(false)   // off, and what it held is dropped
+  //   Component79.clearCache()   // stays on, starts empty
+  //
+  // Returns the setting as it stands after the call
+  static cache(enabled?: boolean): boolean {
+    if (enabled === false) componentCache = null
+    else if (enabled === true) componentCache ??= new Map()
+    return !!componentCache
+  }
+
+  static clearCache(): void {
+    componentCache?.clear()
+  }
+
   static fetch(url: string): PendingComponent79 {
     if (Array.isArray(url)) throw new TypeError("Component79.fetch takes one URL; use fetchAll for an array")
     return new PendingComponent79(fetchComponent(url))
@@ -4307,7 +4411,7 @@ export class Component79 {
     // renders, so a component nested inside itself pays for it once per level -
     // and the depth guard at MAX_NESTING_DEPTH only beats a RangeError while
     // this function stays small (see the note in docs/development.md)
-    Object.defineProperty(raw, PENDING_SCRIPTS, { value: { count: 0 } as PendingScripts })
+    Object.defineProperty(raw, PENDING_SCRIPTS, { value: { count: 0, owner: this } as PendingScripts })
 
     const store = $reactive(raw)
     const fx = createEffectScope(store)
@@ -4362,6 +4466,7 @@ export class Component79 {
     const mounted = new Promise<void>(resolve => { resolveMounted = resolve })
     this.resolveMounted = resolveMounted
     this.renderDone = false
+    this.held = 0
 
     // $destroyed(fn) runs fn when this generation is torn down: destroy(), a
     // re-render, a hot reload, or a parent's :if/:each removing it - never
@@ -4773,8 +4878,27 @@ export class Component79 {
   // whichever lands last calls this. In the ordinary synchronous flow the render
   // is already done and this is the attach; for a component whose first render
   // a script held back, it is the other way round
+  //
+  // "Rendered" includes the components the template created: one whose own
+  // render a script held back counts in `held` until it paints
   private settleMounted() {
-    if (this.renderDone && this.mountRoot) this.resolveMounted?.()
+    if (!this.renderDone || this.held > 0) return
+    const onPaint = this.onPaint
+    this.onPaint = null
+    onPaint?.()
+    if (this.mountRoot) this.resolveMounted?.()
+  }
+
+  // Internal: called by the usage site right after rendering this instance
+  // into `owner`'s template. One that has painted already - every synchronous
+  // component - costs nothing more
+  holdOwner(owner: Component79) {
+    if (this.renderDone && this.held === 0) return
+    owner.held++
+    this.onPaint = () => {
+      owner.held--
+      owner.settleMounted()
+    }
   }
 
   // detaches from the DOM while keeping all state; a later mount() re-attaches
@@ -4810,6 +4934,14 @@ export class Component79 {
     const hooks = this.destroyHooks
     this.destroyHooks = null
     hooks?.forEach(fn => runHook(fn, "$destroyed"))
+    // before the children go: each one destroyed unpainted releases this
+    // instance, and that must not resolve a generation that is going away
+    this.resolveMounted = null
+    // and one destroyed before it painted releases its owner, which would
+    // otherwise wait for a paint that is never coming
+    const onPaint = this.onPaint
+    this.onPaint = null
+    onPaint?.()
     this.detach()
     this.fx?.dispose()
     this.fx = null