browser-module-runtime 0.0.3 → 0.0.5

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/index.d.ts

@@ -39,6 +39,8 @@ export interface RuntimePlugin {
   cacheKey?: string;
   /** Framework-owned exact package roots merged into the runtime package policy. */
   packageEntries?: NonNullable<PackageOptions['entries']>;
+  /** Optional coordinated package URL family; precedence/conflict validated at factory creation. */
+  packageFamilyRules?: Record<string,{url:string;version:string;provider:string;subpathUrl?:(subpath:string)=>string}>;
   compilers?: CompilerAdapter[];
   renderers?: RendererAdapter[];
   preprocess?: TransformHook[];

package/package.json

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

package/src/html/index.js

@@ -1,74 +1,191 @@
-/** 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';
 
-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 parseObject(value,context){
+  if(value==null||value==='')return {};
+  let result;
+  try{result=JSON.parse(value);}catch(e){throw new Error(`Invalid JSON in ${context}: ${e.message}`);}
+  if(!result||typeof result!=='object'||Array.isArray(result))throw new Error(`${context} must be a JSON object`);
+  return result;
+}
+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/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/index.js

@@ -1,7 +1,8 @@
 import {createRuntime as createModuleEngine} from './engine/runtime.js';
 import {createBuildPipeline} from './build/pipeline.js';
 import {createStyleManager} from './resources/styles.js';
-import {mergePluginPackageEntries} from './plugins/package-entries.js';
+import {mergePluginPackageEntries,mergePluginPackageFamilyRules} from './plugins/package-entries.js';
+import {parsePackageSpecifier,PackageVersionResolutionError} from './engine/package-resolution/index.js';
 
 /** Framework-neutral, synchronous factory. Async plugin setup is available on `.ready`. */
 export function createRuntime(options={}) {
@@ -10,22 +11,35 @@ export function createRuntime(options={}) {
   const metadata=new Map();
   const pipeline=createBuildPipeline({plugins,defaultType:options.defaultType||'javascript',onArtifact:(id,artifact)=>artifactById.set(id,artifact)});
   const effectivePackages=mergePluginPackageEntries(options.packages,plugins);
-  const core=createModuleEngine({...options,packages:effectivePackages,compiler:pipeline});
+  const familyRules=mergePluginPackageFamilyRules(effectivePackages,plugins,options._solidFamilyRules,options.modules);
+  const protectedRoots=new Set(plugins.flatMap(plugin=>Object.keys(plugin.packageFamilyRules??{})));
+  function rejectProtected(id){
+    const name=parsePackageSpecifier(String(id))?.packageName;
+    if(name && protectedRoots.has(name))throw new PackageVersionResolutionError('PACKAGE_VERSION_CONFLICT',
+      `${JSON.stringify(id)} belongs to a framework-managed package family; use host mode to override its modules.`,{packageName:name});
+  }
+  for(const id of Object.keys(options.urls??{}))rejectProtected(id);
+  const core=createModuleEngine({...options,packages:effectivePackages,_solidFamilyRules:familyRules,compiler:pipeline});
   const styles=createStyleManager();
   const mounts=new Set();
   let disposed=false;
   const runtime={
     ...core,
     ready:null,
+    defineModule(id,namespace){rejectProtected(id);return core.defineModule(id,namespace);},
+    defineUrl(id,url){rejectProtected(id);return core.defineUrl(id,url);},
     define(id,source,config={}) {
+      rejectProtected(id);
       const type=pipeline.detectType(id,config.type||config.format);
       metadata.set(id,{type});
       return core.define(id,source,{...config,format:type});
     },
     defineMany(definitions) {
+      definitions.forEach(({id})=>rejectProtected(id));
       return definitions.map(({id,source,...opts})=>runtime.define(id,source,opts));
     },
     update(id,source,config={}) {
+      rejectProtected(id);
       const type=pipeline.detectType(id,config.type||config.format||metadata.get(id)?.type);
       metadata.set(id,{type});
       return core.update(id,source,{...config,format:type});

package/src/plugins/package-entries.js

@@ -28,3 +28,33 @@ export function mergePluginPackageEntries(packages,plugins=[]) {
   }
   return {...source,versions,entries};
 }
+
+
+/** Runtime-local provider rules for package families with strict identity
+ * requirements (e.g. Solid 2). Plugins own their family membership; the
+ * generic module engine only sees a regular root -> URL/subpath resolver map.
+ */
+export function mergePluginPackageFamilyRules(packages, plugins=[], explicitRules={}, modules={}) {
+  const rules={...(explicitRules??{})};
+  const pinned=createPackagePolicy(packages);
+  for(const plugin of plugins){
+    for(const [name,rule] of Object.entries(plugin.packageFamilyRules??{})){
+      const previous=rules[name];
+      if(previous && (previous.url!==rule.url || previous.version!==rule.version))
+        throw new PackageVersionResolutionError('PACKAGE_VERSION_CONFLICT',
+          `Plugin ${JSON.stringify(plugin.name)} requires ${JSON.stringify(name)} from ${rule.url}, but another provider requires ${previous.url}.`,
+          {packageName:name,plugin:plugin.name,expected:rule.url,actual:previous.url});
+      const selected=pinned.inspect(name);
+      if(selected && selected.url!==rule.url)
+        throw new PackageVersionResolutionError('PACKAGE_VERSION_CONFLICT',
+          `Plugin ${JSON.stringify(plugin.name)} owns ${JSON.stringify(name)} at ${rule.url}, but the runtime pins ${selected.url}. Remove the duplicate family pin.`,
+          {packageName:name,plugin:plugin.name,expected:rule.url,actual:selected.url});
+      if(Object.hasOwn(modules,name))
+        throw new PackageVersionResolutionError('PACKAGE_VERSION_CONFLICT',
+          `Plugin ${JSON.stringify(plugin.name)} owns ${JSON.stringify(name)}; a caller-owned module namespace cannot guarantee the same framework identity. Use host mode.`,
+          {packageName:name,plugin:plugin.name});
+      rules[name]=rule;
+    }
+  }
+  return rules;
+}

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});}