browser-module-runtime 0.0.7 → 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.7
+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
@@ -59,7 +72,7 @@ await handle.dispose();
 ### Public exports
 
 - `browser-module-runtime`: runtime, build pipeline, cache and resolver utilities
-- `browser-module-runtime/html`: `registerHTML` and generic `<runtime-render>` integration
+- `browser-module-runtime/html`: `createHTMLRuntime` and generic `<runtime-render>` integration
 - `browser-module-runtime/packages`: package policy utilities
 - `browser-module-runtime/cache`: compile-cache implementations
 
@@ -68,8 +81,8 @@ await handle.dispose();
 ### Scoped HTML (development branch)
 
 ```js
-import {registerHTML} from 'browser-module-runtime/html';
-registerHTML(runtime,{scope:'app',root:document}); // No initial scan or observer
+import {createHTMLRuntime} from 'browser-module-runtime/html';
+createHTMLRuntime(runtime,{scope:'app',root:document}); // No initial scan or observer
 ```
 
 ```html

package/html.d.ts

@@ -1,8 +1,6 @@
 import type {Runtime} from './index.js';
 import type {WebComponentOptions} from './web-components.js';
 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;
@@ -16,18 +14,12 @@ export interface HTMLController {
   appendAndRegister(script:HTMLScriptElement,target?:Document|Element):Promise<HTMLScriptElement>;
   /** Preferred explicit, repeatable processing of existing source declarations. */
   process():Promise<void>;
-  /** @deprecated Use process(). */
-  registerExisting():Promise<void>;
-  /** @deprecated Use process(). */
-  scan():Promise<void>;
-  setRoot(root:Document|Element,options?:{processExisting?:boolean;registerExisting?:boolean}):Promise<Document|Element>;
-  moveTo(root:Document|Element,options?:{processExisting?:boolean;registerExisting?:boolean}):Promise<Document|Element>;
+  setRoot(root:Document|Element,options?:{processExisting?:boolean}):Promise<Document|Element>;
+  moveTo(root:Document|Element,options?:{processExisting?:boolean}):Promise<Document|Element>;
   disconnect():Promise<void>;
 }
-export interface RegisterHTMLOptions {
+export interface HTMLRuntimeOptions {
   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;
@@ -35,9 +27,9 @@ export interface RegisterHTMLOptions {
   observe?:boolean;
 }
 /** Does not scan automatically. <runtime-render> itself is an autonomous custom element. */
-export declare function registerHTML(runtime:Runtime,options?:RegisterHTMLOptions):HTMLController;
+export declare function createHTMLRuntime(runtime:Runtime,options?:HTMLRuntimeOptions):HTMLController;
 
 /** High-level one-shot HTML discovery. Registers the controller and processes existing inert scripts.
  * Returns the controller for subsequent root, observer and lifecycle operations.
  */
-export declare function processHTML(runtime:Runtime,options?:RegisterHTMLOptions):Promise<HTMLController>;
+export declare function processHTML(runtime:Runtime,options?:HTMLRuntimeOptions):Promise<HTMLController>;

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.7",
+  "version": "0.0.9",
   "type": "module",
   "exports": {
     ".": {

package/src/html/index.js

@@ -118,16 +118,19 @@ function defineAutonomousElements(doc){
 }
 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');
+export function createHTMLRuntime(runtime,options={}){
+  const {scope="default",root=globalThis.document,observe=false,acceptUnscoped=true}=options;
+  if(!root)throw new TypeError('createHTMLRuntime requires a DOM root');
   const doc=rootDocument(root);
-  if(!doc)throw new TypeError('registerHTML root must belong to a document');
+  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||name||'default';
+  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){
@@ -174,13 +177,11 @@ export function registerHTML(runtime,options={}){
     await registerScript(script);
     return script;
   }
-  async function setRoot(nextRoot,{processExisting,registerExisting=false}={}){
-    // processExisting is preferred; registerExisting remains a legacy alias.
-    const shouldProcess=processExisting??registerExisting;
+  async function setRoot(nextRoot,{processExisting=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(shouldProcess)await scheduleScan();
+    if(processExisting)await scheduleScan();
     return nextRoot;
   }
   async function moveTo(nextRoot,opts){const moved=await setRoot(nextRoot,opts);appendTarget=nextRoot;return moved;}
@@ -189,22 +190,49 @@ export function registerHTML(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 {name:resolvedScope,scope:resolvedScope,runtime,defineElement,registerScript,appendScript,appendAndRegister,process:scheduleScan,registerExisting:scheduleScan,scan: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.
- * Unlike registerHTML(), this convenience function explicitly performs discovery.
+ * Unlike createHTMLRuntime(), this convenience function explicitly performs discovery.
  * Returns the controller so callers can use appendAndRegister(), setRoot() or disconnect().
  */
 export async function processHTML(runtime,options={}){
-  const controller=registerHTML(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;