browser-module-runtime 0.0.8 → 0.0.10

package/README.md

@@ -5,9 +5,22 @@ A framework-neutral browser module runtime with a native ESM linker, independent
 ## Install
 
 ```sh
-npm install browser-module-runtime@0.0.8
+npm install browser-module-runtime@0.0.10
 ```
 
+## Runtime-bound HTML integration (0.0.10)
+
+```js
+import {createRuntime} from 'browser-module-runtime';
+const runtime=createRuntime({plugins:[/* solid(), svelte(), octane() or vue() */]});
+await runtime.html.process({scope:'demo'}); // process inert HTML declarations once
+// Alternatively, without initial discovery:
+const controller=await runtime.html.create({scope:'demo'});
+// await controller.process(); // optional explicit later scan
+```
+
+The stable `runtime.html` facade loads the browser HTML adapter lazily, reuses scoped controllers for the same runtime/root/scope, and disconnects facade-owned controllers when `runtime.dispose()` runs. No browser DOM access, scanning, or observer starts merely from `createRuntime()`. Advanced standalones remain available: `import {createHTMLRuntime,processHTML} from 'browser-module-runtime/html'`. Controllers remain autonomous for `<runtime-render>` and `<runtime-element>`, while inert source `<script>` declarations need `process()` or opt-in `observe:true`.
+
 ## Define, import and update modules
 
 ```js

package/index.d.ts

@@ -11,10 +11,21 @@ export interface CompilerAdapter {
   compile(source: string, context: BuildContext): string | BuildState | Promise<string | BuildState>;
   analyze?(code: string, context: BuildContext): Array<{specifier:string;start:number;end:number;kind:string}> | Promise<Array<{specifier:string;start:number;end:number;kind:string}>>;
 }
+/** Immutable handle to authored native custom-element light-DOM default children.
+ * The source nodes are retained by the custom-element host and never exposed.
+ * Each nodes() call returns newly cloned nodes for the renderer to own.
+ */
+export interface ChildContentSnapshot {
+  readonly count: number;
+  nodes(): Node[];
+  html(): string;
+}
 export interface MountContext<Props = Record<string, unknown>> {
   component: unknown;
   target: Element;
   props: Props;
+  /** Present for native Web Components with authored default children. */
+  children?: ChildContentSnapshot | null;
   runtime: Runtime;
   id: string;
 }
@@ -66,6 +77,13 @@ export interface RuntimeOptions {
   fallbackResolve?(specifier:string,importer?:string):string | undefined;
 }
 export interface Runtime {
+  /** Lazy, runtime-bound HTML integration. Requires a DOM only when called. */
+  html: {
+    /** Create or reuse controller without processing existing declarations. */
+    create(options?:import('./html.js').HTMLRuntimeOptions):Promise<import('./html.js').HTMLController>;
+    /** Create or reuse controller and process existing inert script declarations. */
+    process(options?:import('./html.js').HTMLRuntimeOptions):Promise<import('./html.js').HTMLController>;
+  };
   ready: Promise<void>;
   define(id:string,source:string,config?:{type?:string;format?:string;imports?:Record<string,unknown>}):string;
   defineMany(definitions:ModuleSource[]):string[];
@@ -75,7 +93,7 @@ export interface Runtime {
   loadSource(id:string,options?:{type?:string;url?:string}):Promise<string>;
   import(id:string):Promise<Record<string,any>>;
   compile(id:string,options?:Record<string,unknown>):Promise<{id:string;code?:string;url?:string;dependencies:string[];diagnostics:Diagnostic[];assets?:EmittedAsset[]}>;
-  mount(options:{module:string;export?:string;target:Element|string;props?:Record<string,unknown>}):Promise<MountHandle>;
+  mount(options:{module:string;export?:string;target:Element|string;props?:Record<string,unknown>;children?:ChildContentSnapshot|null}):Promise<MountHandle>;
   remove(id:string,opts?:Record<string,unknown>):boolean;
   clear(opts?:Record<string,unknown>):string[];
   has(id:string):boolean;

package/package.json

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

package/src/html/index.js

@@ -3,7 +3,11 @@ import {registerWebComponent} from '../web-components/index.js';
 import {getScopeRegistry,requestedScope,containsRoot} from './scopes.js';
 import {parseObjectProps as parseObject,readRenderProps,renderPropFingerprint} from './props.js';
 
-function emit(el,type,detail){const win=el.ownerDocument.defaultView;el.dispatchEvent(new win.CustomEvent(type,{detail,bubbles:true,composed:true}));}
+function emit(el,type,detail){const win=el.ownerDocument.defaultView;return el.dispatchEvent(new win.CustomEvent(type,{detail,bubbles:true,composed:true,cancelable:type==='runtime-error'}));}
+function report(el,error,detail={}){
+  state(el,'error');
+  if(emit(el,'runtime-error',{error,...detail}))el.ownerDocument.defaultView.console?.error?.(`[browser-module-runtime] <${el.localName}> failed:`,error);
+}
 function state(el,value){el.setAttribute('data-runtime-state',value);}
 function rootDocument(root){return root?.nodeType===9?root:root?.ownerDocument;}
 function targetsWithin(root,selector){
@@ -36,7 +40,7 @@ function defineAutonomousElements(doc){
         queueMicrotask(()=>{if(!this.isConnected&&generation===this._generation){this._unsubscribe?.();this._unsubscribe=null;this._propObserver?.disconnect();this._propObserver=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)});}}
+      _report(error){if(this._reported!==error){this._reported=error;report(this,error,{module:this.getAttribute('module'),scope:requestedScope(this)});}}
       async _release(){
         this._abort?.abort();this._abort=null;
         const handle=this._handle;this._handle=null;
@@ -106,11 +110,11 @@ function defineAutonomousElements(doc){
       _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.error){report(this,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});}
+        catch(error){report(this,error);}
       }
     }
     win.customElements.define('runtime-element',RuntimeElementDefinition);
@@ -124,10 +128,13 @@ export function createHTMLRuntime(runtime,options={}){
   const doc=rootDocument(root);
   if(!doc)throw new TypeError('createHTMLRuntime root must belong to a document');
   const registry=getScopeRegistry(doc);
+  if([...registry.controllers].some(c=>c.alive&&c.runtime===runtime&&c.scope===scope&&c.root===root)){
+    throw new Error(`HTML controller already exists for scope ${JSON.stringify(scope)} and the same runtime/root; use runtime.html.create() to reuse it`);
+  }
   defineAutonomousElements(doc);
   const resolvedScope=scope;
   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};
+  const controller={id:++sequence,scope:resolvedScope,get root(){return currentRoot;},acceptUnscoped,observe,runtime,get alive(){return alive;},defineElement};
   function defineElement(tag,config){return registerWebComponent(runtime,{...config,tag,document:doc});}
   function owned(el){const match=registry.resolve(el);return match.controller===controller;}
   async function registerScript(el){
@@ -187,9 +194,11 @@ export function createHTMLRuntime(runtime,options={}){
     alive=false;observer?.disconnect();registry.remove(controller);
     await pending.catch(()=>{});
   }
+  Object.assign(controller,{registerScript,appendScript,appendAndRegister,process:scheduleScan,setRoot,moveTo,disconnect});
+  Object.defineProperty(controller,'appendTarget',{get(){return appendTarget;}});
   registry.add(controller);
   enableObservation();
-  return {scope:resolvedScope,runtime,defineElement,registerScript,appendScript,appendAndRegister,process:scheduleScan,setRoot,moveTo,disconnect,get root(){return currentRoot;},get appendTarget(){return appendTarget;}};
+  return controller;
 }
 
 /** Create a scoped HTML controller and process existing source declarations once.
@@ -197,12 +206,37 @@ export function createHTMLRuntime(runtime,options={}){
  * Returns the controller so callers can use appendAndRegister(), setRoot() or disconnect().
  */
 export async function processHTML(runtime,options={}){
-  const controller=createHTMLRuntime(runtime,options);
+  const {controller,created}=getOrCreateHTMLRuntime(runtime,options);
   try{
     await controller.process();
     return controller;
   }catch(error){
-    await controller.disconnect();
+    if(created)await controller.disconnect();
     throw error;
   }
 }
+
+/** Locate an existing controller in the authoritative document scope registry.
+ * Unlike the low-level creator, this never silently adds a second owner for
+ * the same runtime, scope and root. Used by the lazy runtime.html facade.
+ */
+export function getOrCreateHTMLRuntime(runtime,options={}){
+  const root=options.root??globalThis.document;
+  if(!root||![1,9].includes(root.nodeType))throw new TypeError('runtime.html requires a Document or Element root (browser DOM)');
+  const doc=rootDocument(root);
+  if(!doc)throw new TypeError('runtime.html root must belong to a document');
+  const scope=options.scope??'default';
+  if(typeof scope!=='string'||!scope.trim())throw new TypeError('HTML scope must be a non-empty string');
+  const controllers=[...getScopeRegistry(doc).controllers].filter(c=>c.alive&&c.runtime===runtime&&c.scope===scope&&c.root===root);
+  if(controllers.length>1)throw new Error(`Duplicate HTML controllers for scope ${JSON.stringify(scope)} and the same runtime/root`);
+  const existing=controllers[0];
+  if(existing){
+    for(const key of ['observe','acceptUnscoped']){
+      if(Object.prototype.hasOwnProperty.call(options,key)&&options[key]!==existing[key]){
+        throw new Error(`HTML controller configuration conflict for scope ${JSON.stringify(scope)}: ${key} cannot change; disconnect the old controller first`);
+      }
+    }
+    return {controller:existing,created:false};
+  }
+  return {controller:createHTMLRuntime(runtime,{...options,scope,root}),created:true};
+}

package/src/index.js

@@ -23,9 +23,56 @@ export function createRuntime(options={}) {
   const styles=createStyleManager();
   const mounts=new Set();
   let disposed=false;
+  // A stable, DOM-free facade. Loading the optional HTML adapter and creating
+  // custom elements are deferred until the first explicit HTML call.
+  const htmlOwners=new Set();
+  const htmlProcesses=new WeakMap();
+  const obtainHTML=async(options={})=>{
+    if(disposed)throw new Error('Runtime is disposed');
+    const {getOrCreateHTMLRuntime}=await import('./html/index.js');
+    if(disposed)throw new Error('Runtime is disposed');
+    const result=getOrCreateHTMLRuntime(runtime,options);
+    if(result.created)htmlOwners.add(result.controller);
+    return result;
+  };
+  const html={
+    async create(options={}){
+      return (await obtainHTML(options)).controller;
+    },
+    async process(options={}){
+      const {controller,created}=await obtainHTML(options);
+      // The authoritative registry handles identity; this queue only orders
+      // explicit processing passes for the same controller.
+      const previous=htmlProcesses.get(controller)||Promise.resolve();
+      const job=previous.catch(()=>{}).then(async()=>{
+        if(disposed||!controller.alive)throw new Error('HTML controller or runtime is disposed');
+        await runtime.ready;
+        if(disposed||!controller.alive)throw new Error('HTML controller or runtime is disposed');
+        await controller.process();
+        return controller;
+      });
+      htmlProcesses.set(controller,job);
+      try{return await job;}
+      catch(error){
+        // Only the call which CREATED the controller may undo it after an
+        // initial scan failure. Existing owners (especially external) survive.
+        if(created&&htmlOwners.has(controller)){
+          htmlOwners.delete(controller);
+          await controller.disconnect();
+        }
+        throw error;
+      }
+    }
+  };
+  const disposeOwnedHTML=async()=>{
+    const controllers=[...htmlOwners];
+    htmlOwners.clear();
+    await Promise.allSettled(controllers.map(c=>c.disconnect()));
+  };
   const runtime={
     ...core,
     ready:null,
+    html,
     defineModule(id,namespace){rejectProtected(id);return core.defineModule(id,namespace);},
     defineUrl(id,url){rejectProtected(id);return core.defineUrl(id,url);},
     define(id,source,config={}) {
@@ -70,7 +117,7 @@ export function createRuntime(options={}) {
     },
     async import(id){await runtime.ready;return core.import(id);},
     async compile(id,opts){await runtime.ready;return core.compile(id,opts);},
-    async mount({module:id,export:exportName='default',target,props={}}) {
+    async mount({module:id,export:exportName='default',target,props={},children=null}) {
       await runtime.ready;
       if(typeof target==='string')target=document.querySelector(target);
       if(!target)throw new TypeError(`Mount target not found: ${String(target)}`);
@@ -89,7 +136,7 @@ export function createRuntime(options={}) {
         for(const asset of built.assets||[]) {
           if(asset.type==='css')releases.push(styles.acquire({id:asset.id||`${id}:css`,content:asset.content},target.getRootNode?.()||target.ownerDocument));
         }
-        handle=await renderer.mount({component:ns[exportName],target,props,runtime,id});
+        handle=await renderer.mount({component:ns[exportName],target,props,children,runtime,id});
       }catch(error){releases.forEach(fn=>fn());throw error;}
       let closed=false;
       const out={ready:Promise.resolve(),capabilities:{updateProps:typeof handle?.updateProps==='function'},
@@ -99,7 +146,7 @@ export function createRuntime(options={}) {
       mounts.add(out);
       return out;
     },
-    async dispose(){if(disposed)return;disposed=true;await Promise.allSettled([...mounts].map(m=>m.dispose()));styles.dispose();core.dispose();for(const plugin of [...plugins].reverse())await plugin.dispose?.();}
+    async dispose(){if(disposed)return;disposed=true;await disposeOwnedHTML();await Promise.allSettled([...mounts].map(m=>m.dispose()));styles.dispose();core.dispose();for(const plugin of [...plugins].reverse())await plugin.dispose?.();}
   };
   runtime.ready=Promise.resolve().then(async()=>{for(const plugin of plugins)await plugin.configure?.({runtime,pipeline});});
   return runtime;

package/src/web-components/index.js

@@ -35,7 +35,26 @@ const inferAttribute=value=>{
   if(/^[\[{]/.test(value))try{return JSON.parse(value);}catch{}
   return value;
 };
-function dispatch(element,name,detail){element.dispatchEvent(new (element.ownerDocument.defaultView.CustomEvent)(name,{detail,bubbles:true,composed:true}));}
+
+/** Stable framework-neutral snapshot of the authored default content.
+ * The original nodes remain parked in `fragment` for restoration and are NEVER
+ * handed to a renderer. Consumers receive fresh clones on every request.
+ */
+function snapshotChildren(fragment,doc){
+  const originals=[...fragment.childNodes];
+  const meaningful=originals.filter(n=>n.nodeType!==8&&(n.nodeType!==3||n.nodeValue?.trim()));
+  if(!meaningful.length)return null;
+  return Object.freeze({
+    count: meaningful.length,
+    nodes(){return meaningful.map(n=>n.cloneNode(true));},
+    html(){
+      const wrapper=doc.createElement('div');
+      for(const node of meaningful)wrapper.appendChild(node.cloneNode(true));
+      return wrapper.innerHTML;
+    }
+  });
+}
+function dispatch(element,name,detail){return element.dispatchEvent(new (element.ownerDocument.defaultView.CustomEvent)(name,{detail,bubbles:true,composed:true,cancelable:true}));}
 
 /** Register a framework-rendered runtime module as a native custom element.
  * v1 mounts in light DOM. Without renderer.updateProps, changes trigger a remount.
@@ -56,6 +75,9 @@ export function registerWebComponent(runtime,options={}) {
     constructor(){
       super();
       this._runtimeHandle=null;
+      this._renderTarget=null;
+      this._authoredFragment=null;
+      this._childrenSnapshot=null;
       this._mounting=null;
       this._waitController=null;
       this._generation=0;
@@ -70,7 +92,7 @@ export function registerWebComponent(runtime,options={}) {
     _collectProps(){
       const props={};
       if(!attributes.length){
-        for(const attr of this.attributes)props[attr.name]=inferAttribute(attr.value);
+        for(const attr of this.attributes)if(attr.name!=='data-runtime-state')props[attr.name]=inferAttribute(attr.value);
       }
       for(const [key,spec] of Object.entries(schema)){
         const value=convertAttribute(this.getAttribute(spec.attribute),spec,key);
@@ -79,7 +101,45 @@ export function registerWebComponent(runtime,options={}) {
       Object.assign(props,this._propertyValues);
       return props;
     }
-    _report(error){dispatch(this,'runtime-error',{error,module,tag});}
+    _report(error){
+      this.setAttribute('data-runtime-state','error');
+      // Custom events may be consumed by the app; absent explicit handling, a
+      // failed asynchronous mount must not disappear without a console error.
+      if(dispatch(this,'runtime-error',{error,module,tag})){
+        this.ownerDocument.defaultView.console?.error?.(
+          `[browser-module-runtime] <${tag}> could not render ${module}:`,error);
+      }
+    }
+    _captureAuthoredContent(){
+      if(this._authoredFragment)return this._childrenSnapshot;
+      const fragment=this.ownerDocument.createDocumentFragment();
+      // Content belongs to the component only after its source has resolved;
+      // before that it remains visible as a pending/loading fallback.
+      for(const node of [...this.childNodes]){
+        if(node!==this._renderTarget)fragment.appendChild(node);
+      }
+      this._authoredFragment=fragment;
+      this._childrenSnapshot=snapshotChildren(fragment,this.ownerDocument);
+      return this._childrenSnapshot;
+    }
+    _restoreAuthoredContent(){
+      if(!this._authoredFragment)return;
+      this._renderTarget?.remove();this._renderTarget=null;
+      this.appendChild(this._authoredFragment); // Moves original nodes back, including listeners.
+      this._authoredFragment=null;
+      this._childrenSnapshot=null;
+    }
+    _mountTarget(){
+      if(this._renderTarget?.parentNode===this)return this._renderTarget;
+      // Render output stays isolated; captured authored HTML is provided to
+      // adapters as framework-native children rather than being left visible.
+      const target=this.ownerDocument.createElement('span');
+      target.setAttribute('data-runtime-mount','');
+      target.style.display='contents';
+      this.appendChild(target);
+      this._renderTarget=target;
+      return target;
+    }
     connectedCallback(){
       for(const [key,value] of this._preUpgrade.splice(0))this[key]=value;
       const version=++this._generation;
@@ -106,9 +166,12 @@ export function registerWebComponent(runtime,options={}) {
         const props=this._collectProps();
         if(this._runtimeHandle.capabilities.updateProps){
           await this._runtimeHandle.updateProps(props);
+          this.setAttribute('data-runtime-state','ready');
         }else{
           // An explicit remount is preferable to silently ignoring changed attributes.
           await this._runtimeHandle.dispose();this._runtimeHandle=null;
+          this._renderTarget?.remove();this._renderTarget=null;
+          // Keep parked authored content across a fallback remount.
           await this._start(this._generation);
         }
       }).catch(e=>this._report(e));
@@ -123,15 +186,18 @@ export function registerWebComponent(runtime,options={}) {
           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.setAttribute('data-runtime-state','mounting');
+          const children=this._captureAuthoredContent();
+          return runtime.mount({module,export:exportName,target:this._mountTarget(),props,children});
         })();
         this._mounting=mountPromise;
         const handle=await mountPromise;
         if(!handle)return;
         if(!this.isConnected||version!==this._generation){await handle.dispose();return;}
         this._runtimeHandle=handle;
+        this.setAttribute('data-runtime-state','ready');
         dispatch(this,'runtime-ready',{module,tag,handle});
-      }catch(e){if(e?.name!=='AbortError')this._report(e);}finally{
+      }catch(e){if(e?.name!=='AbortError'){this._restoreAuthoredContent();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)
@@ -143,6 +209,9 @@ export function registerWebComponent(runtime,options={}) {
       // 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});}
+      this._restoreAuthoredContent();
+      this._renderTarget?.remove();this._renderTarget=null;
+      this.removeAttribute('data-runtime-state');
     }
   }
   for(const key of Object.keys(schema)){