browser-module-runtime 0.0.8 → 0.0.9

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.9
 ```
 
+## Runtime-bound HTML integration (0.0.9)
+
+```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

@@ -66,6 +66,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[];

package/package.json

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

package/src/html/index.js

@@ -124,10 +124,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 +190,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 +202,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={}) {
@@ -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;