browser-module-runtime 0.0.4 → 0.0.6

package/README.md

@@ -64,3 +64,16 @@ await handle.dispose();
 - `browser-module-runtime/cache`: compile-cache implementations
 
 `<runtime-render>` mounts framework plugins into its own element. This new generic API is distinct from the older `solid-tag-runtime` and `<solid-render>` APIs; use those packages for applications requiring their existing behavior.
+
+### Scoped HTML (development branch)
+
+```js
+import {registerHTML} from 'browser-module-runtime/html';
+registerHTML(runtime,{scope:'app',root:document}); // No initial scan or observer
+```
+
+```html
+<runtime-render scope="app" module="/Counter.jsx" props='{"initial":5}'></runtime-render>
+```
+
+The custom element waits for the runtime and module automatically. For already parsed inert script declarations use an explicit `await html.registerExisting()`; choose `observe:true` only when discovering uncontrolled future script insertions is necessary. Use `html.appendAndRegister(script)` for controlled injection. See `docs/SCOPED_HTML.md` in the workspace. These behaviors are **not** part of previously published npm `0.0.4` without a new release.

package/html.d.ts

@@ -1,4 +1,36 @@
 import type {Runtime} from './index.js';
 import type {WebComponentOptions} from './web-components.js';
-export interface HTMLController {readonly name:string;readonly runtime:Runtime;defineElement(tag:string,options:Omit<WebComponentOptions,'tag'>):CustomElementConstructor;registerExisting():Promise<void>;scan():Promise<void>;disconnect():Promise<void>}
-export declare function registerHTML(runtime:Runtime,options?:{name?:string;root?:Document|Element;observe?:boolean}):HTMLController;
+export interface HTMLController {
+  /** Scope name; `name` is a backwards compatible alias. */
+  readonly name:string;
+  readonly scope:string;
+  readonly root:Document|Element;
+  readonly appendTarget:Document|Element;
+  readonly runtime:Runtime;
+  defineElement(tag:string,options:Omit<WebComponentOptions,'tag'>):CustomElementConstructor;
+  /** Registers an existing inert declaration without scanning. */
+  registerScript(script:HTMLScriptElement):Promise<boolean>;
+  /** Append only (no auto-registration). */
+  appendScript(script:HTMLScriptElement,target?:Document|Element):Promise<HTMLScriptElement>;
+  /** Controlled append and register without a subtree scan. */
+  appendAndRegister(script:HTMLScriptElement,target?:Document|Element):Promise<HTMLScriptElement>;
+  /** Explicit one-time discovery of scripts under root. */
+  registerExisting():Promise<void>;
+  /** Alias for registerExisting. */
+  scan():Promise<void>;
+  setRoot(root:Document|Element,options?:{registerExisting?:boolean}):Promise<Document|Element>;
+  moveTo(root:Document|Element,options?:{registerExisting?:boolean}):Promise<Document|Element>;
+  disconnect():Promise<void>;
+}
+export interface RegisterHTMLOptions {
+  scope?:string;
+  /** Backward compatible alias for scope. */
+  name?:string;
+  root?:Document|Element;
+  /** Whether an element without an explicit scope can be owned by this controller. */
+  acceptUnscoped?:boolean;
+  /** Opt-in DOM observation of newly inserted inert source declarations. Default false. */
+  observe?:boolean;
+}
+/** Does not scan automatically. <runtime-render> itself is an autonomous custom element. */
+export declare function registerHTML(runtime:Runtime,options?:RegisterHTMLOptions):HTMLController;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-module-runtime",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "type": "module",
   "exports": {
     ".": {

package/src/html/index.js

@@ -1,74 +1,185 @@
-/** HTML controller with opt-in observation; not coupled to any UI framework. */
+/** Scoped HTML integration: autonomous rendering, explicit discovery, opt-in observation. */
 import {registerWebComponent} from '../web-components/index.js';
+import {getScopeRegistry,requestedScope,containsRoot} from './scopes.js';
+import {parseObjectProps as parseObject} from './props.js';
 
-const registries=new WeakMap();
-
-function parseSchema(value,context){
-  if(!value)return undefined;
-  try {const parsed=JSON.parse(value);if(!parsed||typeof parsed!=='object'||Array.isArray(parsed))throw new Error('expected an object');return parsed;}
-  catch(error){throw new Error(`Invalid prop schema in ${context}: ${error.message}`);}
+function emit(el,type,detail){const win=el.ownerDocument.defaultView;el.dispatchEvent(new win.CustomEvent(type,{detail,bubbles:true,composed:true}));}
+function state(el,value){el.setAttribute('data-runtime-state',value);}
+function rootDocument(root){return root?.nodeType===9?root:root?.ownerDocument;}
+function targetsWithin(root,selector){
+  return [...(root.matches?.(selector)?[root]:[]),...(root.querySelectorAll?.(selector)||[])];
 }
+function elementOptions(el){return {module:el.getAttribute('module'),export:el.getAttribute('component')||'default',props:parseObject(el.getAttribute('element-props')||el.getAttribute('props'),`${el.localName} prop schema`),shadow:el.getAttribute('shadow')||'none'};}
 
-export function registerHTML(runtime,{name='default',root=globalThis.document,observe=false}={}) {
+function defineAutonomousElements(doc){
+  const win=doc.defaultView;
+  if(!win?.customElements)return;
+  if(!win.customElements.get('runtime-render')){
+    class RuntimeRender extends win.HTMLElement {
+      static get observedAttributes(){return ['scope','runtime','data-runtime','module','component','props'];}
+      constructor(){super();this._owner=null;this._handle=null;this._abort=null;this._generation=0;this._unsubscribe=null;this._pending=null;this._lastProps='';this._reported=null;}
+      connectedCallback(){
+        if(!this._unsubscribe)this._unsubscribe=getScopeRegistry(doc).subscribe(()=>this._reconcile());
+        this._reconcile();
+      }
+      disconnectedCallback(){
+        const generation=++this._generation;
+        if(this._pending&&!this._handle){this._key=null;this._abort?.abort();}
+        queueMicrotask(()=>{if(!this.isConnected&&generation===this._generation){this._unsubscribe?.();this._unsubscribe=null;this._key=null;this._pending=null;this._release().catch(e=>this._report(e));state(this,'disposed');}});
+      }
+      attributeChangedCallback(name,oldValue,newValue){if(oldValue!==newValue&&this.isConnected)this._reconcile();}
+      _report(error){state(this,'error');if(this._reported!==error){this._reported=error;emit(this,'runtime-error',{error,module:this.getAttribute('module'),scope:requestedScope(this)});}}
+      async _release(){
+        this._abort?.abort();this._abort=null;
+        const handle=this._handle;this._handle=null;
+        if(handle){await handle.dispose();emit(this,'runtime-disposed',{module:this.getAttribute('module')});}
+      }
+      _reconcile(){
+        if(!this.isConnected)return;
+        const match=getScopeRegistry(doc).resolve(this);
+        const id=this.getAttribute('module')||'';
+        const exportName=this.getAttribute('component')||'default';
+        const propsText=this.getAttribute('props')||'{}';
+        const key=match.controller&&`${match.controller.id}|${id}|${exportName}`;
+        // Reconcile only on meaningful changes, not unrelated registry notifications.
+        if(match.error&&this._lastErrorMessage===match.error.message)return;
+        this._lastErrorMessage=match.error?.message||null;
+        if(!match.error&&this._key===key&&this._lastProps===propsText&&(this._handle||this._pending||!match.controller))return;
+        this._key=key;this._lastProps=propsText;
+        const generation=++this._generation;
+        this._abort?.abort();
+        this._pending=null;
+        const previous=this._handle;this._handle=null;
+        const controller=match.controller;
+        this._owner=controller;
+        if(match.error){this._report(match.error);if(previous)previous.dispose().catch(e=>this._report(e));return;}
+        if(!controller||!id){state(this,'pending');if(previous)previous.dispose().catch(e=>this._report(e));return;}
+        let props;
+        try{props=parseObject(propsText,'runtime-render props');}catch(e){this._report(e);if(previous)previous.dispose().catch(err=>this._report(err));return;}
+        this._reported=null;
+        if(previous&&this._previousKey===key){
+          // Update props in place where supported, otherwise remount.
+          if(previous.capabilities?.updateProps){
+            state(this,'mounting');
+            const task=Promise.resolve().then(()=>previous.updateProps(props)).then(async()=>{
+              if(generation!==this._generation||!this.isConnected){await previous.dispose();return;}
+              this._handle=previous;state(this,'ready');
+            }).catch(e=>this._report(e));
+            this._pending=task;task.finally(()=>{if(this._pending===task)this._pending=null;});return;
+          }
+        }
+        const abort=new AbortController();this._abort=abort;
+        state(this,'pending');
+        const task=(async()=>{
+          if(previous)await previous.dispose();
+          await controller.runtime.ready;
+          await controller.runtime.waitForModule(id,{signal:abort.signal});
+          if(abort.signal.aborted||generation!==this._generation||!this.isConnected)return;
+          state(this,'mounting');
+          const handle=await controller.runtime.mount({module:id,export:exportName,target:this,props});
+          if(abort.signal.aborted||generation!==this._generation||!this.isConnected){await handle.dispose();return;}
+          this._handle=handle;this._previousKey=key;state(this,'ready');emit(this,'runtime-ready',{module:id,scope:controller.scope,handle});
+        })().catch(e=>{if(!abort.signal.aborted&&generation===this._generation)this._report(e);});
+        this._pending=task;task.finally(()=>{if(this._pending===task)this._pending=null;});
+      }
+    }
+    win.customElements.define('runtime-render',RuntimeRender);
+  }
+  if(!win.customElements.get('runtime-element')){
+    class RuntimeElementDefinition extends win.HTMLElement {
+      static get observedAttributes(){return ['scope','runtime','data-runtime','tag','module','component','props','element-props'];}
+      constructor(){super();this._unsubscribe=null;this._registered=false;}
+      connectedCallback(){
+        if(!this._unsubscribe)this._unsubscribe=getScopeRegistry(doc).subscribe(()=>this._register());
+        this._register();
+      }
+      disconnectedCallback(){queueMicrotask(()=>{if(!this.isConnected){this._unsubscribe?.();this._unsubscribe=null;}});}
+      attributeChangedCallback(){if(this.isConnected)this._register();}
+      _register(){
+        if(!this.isConnected||this._registered)return;
+        const match=getScopeRegistry(doc).resolve(this);
+        if(match.error){emit(this,'runtime-error',{error:match.error});return;}
+        if(!match.controller){state(this,'pending');return;}
+        if(!this.getAttribute('tag')||!this.getAttribute('module'))return;
+        try{match.controller.defineElement(this.getAttribute('tag'),elementOptions(this));this._registered=true;this.hidden=true;state(this,'ready');emit(this,'runtime-ready',{tag:this.getAttribute('tag')});}
+        catch(error){state(this,'error');emit(this,'runtime-error',{error});}
+      }
+    }
+    win.customElements.define('runtime-element',RuntimeElementDefinition);
+  }
+}
+let sequence=0;
+/** Register a scoped HTML controller. Never scans automatically. */
+export function registerHTML(runtime,options={}){
+  const {name,scope,root=globalThis.document,observe=false,acceptUnscoped=true}=options;
   if(!root)throw new TypeError('registerHTML requires a DOM root');
-  const doc=root.ownerDocument||root;
-  let registry=registries.get(doc);
-  if(!registry){registry=new Map();registries.set(doc,registry);}
-  if(registry.has(name))throw new Error(`Runtime HTML name already registered: ${name}`);
-  registry.set(name,runtime);
-  const active=new Map();
-  let observer;
-  let alive=true;
-  let pending=Promise.resolve();
+  const doc=rootDocument(root);
+  if(!doc)throw new TypeError('registerHTML root must belong to a document');
+  const registry=getScopeRegistry(doc);
+  defineAutonomousElements(doc);
+  const resolvedScope=scope||name||'default';
+  let alive=true,observer=null,currentRoot=root,appendTarget=root,pending=Promise.resolve();
+  const controller={id:++sequence,scope:resolvedScope,get root(){return currentRoot;},acceptUnscoped,runtime,get alive(){return alive;},defineElement};
   function defineElement(tag,config){return registerWebComponent(runtime,{...config,tag,document:doc});}
-  function elementOptions(el){
-    return {
-      module:el.getAttribute('module'),
-      export:el.getAttribute('component')||'default',
-      props:parseSchema(el.getAttribute('element-props')||el.getAttribute('props'),el.tagName.toLowerCase()),
-      shadow:el.getAttribute('shadow')||'none'
-    };
+  function owned(el){const match=registry.resolve(el);return match.controller===controller;}
+  async function registerScript(el){
+    if(!alive||!owned(el)||el.dataset.runtimeRegistered==='true')return false;
+    const type=el.getAttribute('type');
+    if(!runtime.getSupportedTypes().includes(type))return false;
+    const id=el.getAttribute('module');if(!id)return false;
+    if(el.hasAttribute('data-src'))await runtime.loadSource(id,{type,url:el.getAttribute('data-src')});
+    else runtime.define(id,runtime.normalizeInlineSource(el.textContent,{type,id,element:el}),{type});
+    if(el.hasAttribute('custom-element')){
+      defineElement(el.getAttribute('custom-element'),elementOptions(el));
+    }
+    el.dataset.runtimeRegistered='true';
+    return true;
   }
-  function isOwned(node) {return node.getAttribute('data-runtime')===name || node.getAttribute('runtime')===name || (!node.hasAttribute('data-runtime')&&!node.hasAttribute('runtime')&&name==='default');}
   async function scan(){
     if(!alive)return;
-    for(const el of root.querySelectorAll('script[type][module]')){
-      if(!isOwned(el)||el.dataset.runtimeRegistered==='true')continue;
-      const type=el.getAttribute('type');
-      if(!runtime.getSupportedTypes().includes(type))continue;
-      const id=el.getAttribute('module');
-      if(el.hasAttribute('data-src'))await runtime.loadSource(id,{type,url:el.getAttribute('data-src')});
-      else runtime.define(id,runtime.normalizeInlineSource(el.textContent,{type,id,element:el}),{type});
-      if(el.hasAttribute('custom-element')){
-        defineElement(el.getAttribute('custom-element'),elementOptions(el));
-      }
-      el.dataset.runtimeRegistered='true';
-    }
-    for(const el of root.querySelectorAll('runtime-element[tag][module]')){
-      if(!isOwned(el)||el.dataset.runtimeRegistered==='true')continue;
-      defineElement(el.getAttribute('tag'),elementOptions(el));
-      el.dataset.runtimeRegistered='true';
-      el.hidden=true;
-    }
-    const targets=root.querySelectorAll('runtime-render');
-    for(const el of targets){
-      if(!isOwned(el)||active.has(el))continue;
-      let props={};
-      try {props=JSON.parse(el.getAttribute('props')||'{}');}catch(e){throw new Error(`Invalid props JSON in runtime-render: ${e.message}`);}
-      if(!props||typeof props!=='object'||Array.isArray(props))throw new Error('runtime-render props must be a JSON object');
-      const module=el.getAttribute('module');if(!module)continue;
-      const token={cancelled:false,handle:null};active.set(el,token);
-      try {token.handle=await runtime.mount({module,target:el,props,export:el.getAttribute('component')||'default'});if(token.cancelled)await token.handle.dispose();}
-      catch(e){active.delete(el);el.dispatchEvent(new CustomEvent('runtime-error',{detail:e}));throw e;}
-    }
-    for(const [el,token] of active){if(!el.isConnected||!root.contains(el)){active.delete(el);token.cancelled=true;await token.handle?.dispose();}}
+    for(const el of targetsWithin(currentRoot,'script[type][module]'))await registerScript(el);
+    // runtime-element and runtime-render are autonomous, not scan work.
   }
   function scheduleScan(){pending=pending.catch(()=>{}).then(scan);return pending;}
-  if(observe){observer=new MutationObserver(()=>scheduleScan());observer.observe(root,{subtree:true,childList:true});}
-  // Explicitly register this custom element only once per browser window.
-  const win=doc.defaultView;
-  if(win?.customElements&&!win.customElements.get('runtime-render')){
-    win.customElements.define('runtime-render',class extends win.HTMLElement {});
+  function enableObservation(){
+    if(observer)observer.disconnect();observer=null;
+    if(!observe)return;
+    const Observer=doc.defaultView?.MutationObserver;
+    if(!Observer)return;
+    observer=new Observer(records=>{
+      for(const record of records)for(const node of record.addedNodes){
+        if(node.nodeType!==1)continue;
+        if(node.matches?.('script[type][module]')||node.querySelector?.('script[type][module]')){
+          scheduleScan();return;
+        }
+      }
+    });
+    observer.observe(currentRoot,{subtree:true,childList:true});
+  }
+  async function appendScript(script,target=appendTarget){
+    if(script.localName!=='script')throw new TypeError('appendScript expects a script element');
+    const parent=target.nodeType===9?(target.head||target.body||target.documentElement):target;
+    parent.append(script);return script;
+  }
+  async function appendAndRegister(script,target=appendTarget){
+    await appendScript(script,target);
+    await registerScript(script);
+    return script;
+  }
+  async function setRoot(nextRoot,{registerExisting=false}={}){
+    if(!alive)throw new Error('HTML controller is disconnected');
+    if(rootDocument(nextRoot)!==doc)throw new Error('HTML root must remain in the same document');
+    if(observer)observer.disconnect();currentRoot=nextRoot;registry.notify();enableObservation();
+    if(registerExisting)await scheduleScan();
+    return nextRoot;
+  }
+  async function moveTo(nextRoot,opts){const moved=await setRoot(nextRoot,opts);appendTarget=nextRoot;return moved;}
+  async function disconnect(){
+    if(!alive)return;
+    alive=false;observer?.disconnect();registry.remove(controller);
+    await pending.catch(()=>{});
   }
-  return {name,runtime,defineElement,registerExisting:scheduleScan,scan:scheduleScan,async disconnect(){if(!alive)return;alive=false;observer?.disconnect();await pending.catch(()=>{});for(const token of active.values()){token.cancelled=true;await token.handle?.dispose();}active.clear();registry.delete(name);}};
+  registry.add(controller);
+  enableObservation();
+  return {name:resolvedScope,scope:resolvedScope,runtime,defineElement,registerScript,appendScript,appendAndRegister,registerExisting:scheduleScan,scan:scheduleScan,setRoot,moveTo,disconnect,get root(){return currentRoot;},get appendTarget(){return appendTarget;}};
 }

package/src/html/props.js

@@ -0,0 +1,112 @@
+/** Parse declarative object props without eval or executing JavaScript.
+ * Accepts JSON and a safe JS-literal subset (unquoted keys, single-quoted
+ * strings, trailing commas, nested arrays/objects). No expressions or code.
+ */
+export function parseObjectProps(value, context = 'props') {
+  if (value == null || value.trim() === '') return {};
+  if (value.length > 100_000) throw new SyntaxError(`${context}: props literal is too large`);
+  let offset = 0;
+  const error = (message) => { throw new SyntaxError(`${context}: ${message} at character ${offset + 1}`); };
+  const peek = () => value[offset];
+  const space = () => { while (offset < value.length && /\s/.test(peek())) offset++; };
+  const forbidKey = (key) => {
+    if (key === '__proto__' || key === 'constructor' || key === 'prototype') error(`Forbidden object key ${key}`);
+    return key;
+  };
+  function str() {
+    const quote = value[offset++];
+    let result = '';
+    while (offset < value.length) {
+      let c = value[offset++];
+      if (c === quote) return result;
+      if (c === '\n' || c === '\r') error('Unterminated string');
+      if (c !== '\\') { result += c; continue; }
+      if (offset >= value.length) error('Unterminated string escape');
+      c = value[offset++];
+      const escapes = {n:'\n', r:'\r', t:'\t', b:'\b', f:'\f', v:'\v', '0':'\0'};
+      if (Object.hasOwn(escapes, c)) { result += escapes[c]; continue; }
+      if (c === 'u' || c === 'x') {
+        const count = c === 'u' ? 4 : 2;
+        const hex = value.slice(offset, offset + count);
+        if (!new RegExp(`^[a-fA-F0-9]{${count}}$`).test(hex)) error('Invalid hex string escape');
+        result += String.fromCharCode(parseInt(hex, 16)); offset += count; continue;
+      }
+      if ('\\\'"/'.includes(c)) { result += c; continue; }
+      error(`Unsupported string escape \\${c}`);
+    }
+    error('Unterminated string');
+  }
+  function readValue(depth = 0) {
+    if (depth > 40) error('Props nesting is too deep');
+    space();
+    const c = peek();
+    if (c === '{') return object(depth + 1);
+    if (c === '[') return array(depth + 1);
+    if (c === '"' || c === "'") return str();
+    const next = value.slice(offset);
+    const number = next.match(/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/);
+    if (number) {
+      offset += number[0].length;
+      const n = Number(number[0]);
+      if (!Number.isFinite(n)) error('Numbers must be finite');
+      return n;
+    }
+    for (const [word, literal] of [['true',true],['false',false],['null',null]]) {
+      if (next.startsWith(word) && !/[\w$]/.test(next[word.length] ?? '')) {
+        offset += word.length; return literal;
+      }
+    }
+    error('Expected a literal value (no expressions or functions)');
+  }
+  function key() {
+    space();
+    if (peek() === '"' || peek() === "'") return forbidKey(str());
+    const token = value.slice(offset).match(/^[A-Za-z_$][A-Za-z0-9_$]*/);
+    if (!token) error('Expected an object key');
+    offset += token[0].length;
+    return forbidKey(token[0]);
+  }
+  function object(depth) {
+    offset++; space();
+    const result = {};
+    if (peek() === '}') { offset++; return result; }
+    while (offset < value.length) {
+      const prop = key();space();
+      if (value[offset++] !== ':') error('Expected : after an object key');
+      const val = readValue(depth);
+      if (Object.hasOwn(result, prop)) error(`Duplicate object key ${prop}`);
+      result[prop] = val;
+      space();
+      const delimiter = value[offset++];
+      if (delimiter === '}') return result;
+      if (delimiter !== ',') error('Expected , or }');
+      space();
+      if (peek() === '}') { offset++; return result; }
+    }
+    error('Unclosed object');
+  }
+  function array(depth) {
+    offset++; space();
+    const result = [];
+    if (peek() === ']') { offset++; return result; }
+    while (offset < value.length) {
+      result.push(readValue(depth));space();
+      const delimiter = value[offset++];
+      if (delimiter === ']') return result;
+      if (delimiter !== ',') error('Expected , or ]');
+      space();
+      if (peek() === ']') { offset++; return result; }
+    }
+    error('Unclosed array');
+  }
+  space();
+  if (peek() !== '{') {
+    // Preserve the old object-only error wording for callers relying on it.
+    try { const json = JSON.parse(value); if (json === null || typeof json !== 'object' || Array.isArray(json)) throw new Error(`${context} must be a JSON object or safe object literal`); }
+    catch (e) { if (e.message.includes('must be a JSON object')) throw e; }
+    error('Props must be a JSON object or safe object literal');
+  }
+  const result = readValue();space();
+  if (offset !== value.length) error('Unexpected trailing content');
+  return result;
+}

package/src/html/scopes.js

@@ -0,0 +1,51 @@
+/** Framework-neutral, document-owned HTML controller routing. No DOM observer or polling. */
+const documents=new WeakMap();
+const scopeAttributeNames=['scope','runtime','data-runtime'];
+
+export function getScopeRegistry(doc){
+  if(!doc)throw new TypeError('HTML scope registry requires a document');
+  let registry=documents.get(doc);
+  if(!registry){
+    const controllers=new Set(),listeners=new Set();
+    registry={
+      controllers,
+      subscribe(fn){listeners.add(fn);return ()=>listeners.delete(fn);},
+      notify(){for(const fn of [...listeners])fn();},
+      add(controller){controllers.add(controller);registry.notify();},
+      remove(controller){if(controllers.delete(controller))registry.notify();},
+      resolve(element){return resolveScope([...controllers].filter(c=>c.alive),element);}
+    };
+    documents.set(doc,registry);
+  }
+  return registry;
+}
+export function requestedScope(element){
+  for(const attr of scopeAttributeNames){
+    const value=element.getAttribute?.(attr)?.trim();
+    if(value)return value;
+  }
+  return null;
+}
+export function containsRoot(root,element){
+  if(root===element)return true;
+  return Boolean(root?.contains?.(element));
+}
+export function resolveScope(controllers,element){
+  const explicit=requestedScope(element);
+  const possible=controllers.filter(c=>explicit ? c.scope===explicit : c.acceptUnscoped!==false);
+  const matches=possible.filter(c=>containsRoot(c.root,element));
+  if(matches.length===0){
+    // A completely missing scope is a pending dependency; a scope that exists
+    // but does not contain the element is a configuration error, as in solid-render.
+    if(possible.length){
+      return {controller:null,pending:false,error:new Error(explicit
+        ? `HTML runtime scope ${JSON.stringify(explicit)} is registered but no matching controller root contains this element.`
+        : 'No eligible HTML runtime has a root containing this unscoped element.')};
+    }
+    return {controller:null,pending:true,reason:explicit?`Waiting for HTML scope ${JSON.stringify(explicit)}`:'Waiting for an eligible HTML runtime'};
+  }
+  const specific=matches.filter(candidate=>matches.every(other=>candidate===other||!containsRoot(candidate.root,other.root)));
+  if(specific.length===1)return {controller:specific[0],pending:false};
+  const names=matches.map(c=>c.scope).join(', ');
+  return {controller:null,pending:false,error:new Error(`Ambiguous HTML runtime ownership${explicit?` for scope ${JSON.stringify(explicit)}`:''}: ${names}. Use a distinct scope or non-overlapping roots.`)};
+}

package/src/web-components/index.js

@@ -57,6 +57,7 @@ export function registerWebComponent(runtime,options={}) {
       super();
       this._runtimeHandle=null;
       this._mounting=null;
+      this._waitController=null;
       this._generation=0;
       this._propertyValues=Object.create(null);
       this._updateTask=Promise.resolve();
@@ -82,6 +83,7 @@ export function registerWebComponent(runtime,options={}) {
     connectedCallback(){
       for(const [key,value] of this._preUpgrade.splice(0))this[key]=value;
       const version=++this._generation;
+      if(this._mounting)this._waitController?.abort();
       queueMicrotask(()=>{if(this.isConnected&&version===this._generation)this._start(version);});
     }
     disconnectedCallback(){
@@ -115,19 +117,29 @@ export function registerWebComponent(runtime,options={}) {
       if(this._runtimeHandle||this._mounting||!this.isConnected||version!==this._generation)return;
       try{
         const props=this._collectProps();
-        const mountPromise=runtime.mount({module,export:exportName,target:this,props});
+        const waitController=new AbortController();
+        this._waitController=waitController;
+        const mountPromise=(async()=>{
+          await runtime.ready;
+          if(typeof runtime.waitForModule==='function')await runtime.waitForModule(module,{signal:waitController.signal});
+          if(waitController.signal.aborted||version!==this._generation||!this.isConnected)return null;
+          return runtime.mount({module,export:exportName,target:this,props});
+        })();
         this._mounting=mountPromise;
         const handle=await mountPromise;
+        if(!handle)return;
         if(!this.isConnected||version!==this._generation){await handle.dispose();return;}
         this._runtimeHandle=handle;
         dispatch(this,'runtime-ready',{module,tag,handle});
-      }catch(e){this._report(e);}finally{
+      }catch(e){if(e?.name!=='AbortError')this._report(e);}finally{
+        if(this._waitController?.signal.aborted || version===this._generation)this._waitController=null;
         this._mounting=null;
         if(this.isConnected&&!this._runtimeHandle&&version!==this._generation)
           queueMicrotask(()=>this._start(this._generation));
       }
     }
     async _stop(){
+      this._waitController?.abort();this._waitController=null;
       // A pending mount observes generation changes and disposes itself.
       const handle=this._runtimeHandle;this._runtimeHandle=null;
       if(handle){await handle.dispose();dispatch(this,'runtime-disposed',{module,tag});}