browser-module-runtime 0.0.0-stage → 0.0.1

package/src/engine/url-backend.js

@@ -0,0 +1,40 @@
+function isNodeLike() {
+  return typeof process !== "undefined" && !!process.versions?.node;
+}
+
+export function createDefaultModuleUrlBackend() {
+  if (!isNodeLike() && typeof Blob !== "undefined" && typeof URL?.createObjectURL === "function") {
+    return createBlobModuleUrlBackend();
+  }
+
+  return createDataModuleUrlBackend();
+}
+
+export function createBlobModuleUrlBackend() {
+  return {
+    kind: "blob",
+    create(code) {
+      return URL.createObjectURL(new Blob([code], { type: "text/javascript" }));
+    },
+    revoke(url) {
+      URL.revokeObjectURL(url);
+    },
+  };
+}
+
+export function createDataModuleUrlBackend() {
+  let sequence = 0;
+
+  return {
+    kind: "data",
+    create(code) {
+      // Native ESM caches modules by URL. Recreating the same data: URL after
+      // invalidation would otherwise return the previously evaluated module.
+      // Give every backend create() call a fresh module identity, matching the
+      // naturally unique identity of URL.createObjectURL() in the blob backend.
+      const identity = ++sequence;
+      return `data:text/javascript;charset=utf-8,${encodeURIComponent(code)}#browser-module-runtime-${identity}`;
+    },
+    revoke() {},
+  };
+}

package/src/html/index.d.ts

@@ -0,0 +1 @@
+export * from '../../html.js';

package/src/html/index.js

@@ -0,0 +1,48 @@
+/** HTML controller with opt-in observation; not coupled to any UI framework. */
+const registries=new WeakMap();
+
+export function registerHTML(runtime,{name='default',root=globalThis.document,observe=false}={}) {
+  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();
+  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,el.textContent,{type});
+      el.dataset.runtimeRegistered='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();}}
+  }
+  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 {});
+  }
+  return {name,runtime,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);}};
+}

package/src/index.d.ts

@@ -0,0 +1 @@
+export * from '../index.js';

package/src/index.js

@@ -0,0 +1,93 @@
+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';
+
+/** Framework-neutral, synchronous factory. Async plugin setup is available on `.ready`. */
+export function createRuntime(options={}) {
+  const plugins=options.plugins||[];
+  const artifactById=new Map();
+  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 styles=createStyleManager();
+  const mounts=new Set();
+  let disposed=false;
+  const runtime={
+    ...core,
+    ready:null,
+    define(id,source,config={}) {
+      const type=pipeline.detectType(id,config.type||config.format);
+      metadata.set(id,{type});
+      return core.define(id,source,{...config,format:type});
+    },
+    defineMany(definitions) {
+      return definitions.map(({id,source,...opts})=>runtime.define(id,source,opts));
+    },
+    update(id,source,config={}) {
+      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});
+    },
+    remove(id,opts){metadata.delete(id);artifactById.delete(id);return core.remove(id,opts);},
+    clear(opts){const ids=core.clear(opts);for(const id of ids){metadata.delete(id);artifactById.delete(id);}return ids;},
+    getModuleInfo(id){const info=core.getModuleInfo(id);return info?{...info,type:metadata.get(id)?.type}:info;},
+    getBuildArtifact(id){return artifactById.get(id);},
+    getSourceType(id){return metadata.get(id)?.type;},
+    getSupportedTypes(){return [...pipeline.formats];},
+    async loadSource(id,{type,url=id}={}) {
+      await runtime.ready;
+      let source;
+      for(const plugin of plugins)if(plugin.load){source=await plugin.load({id,url,type}, {runtime});if(source!=null)break;}
+      if(source==null) {
+        const response=await fetch(url);
+        if(!response.ok)throw new Error(`Failed loading ${url}: HTTP ${response.status}`);
+        source=await response.text();
+      }
+      runtime.define(id, typeof source==='string'?source:source.code,{type});
+      return id;
+    },
+    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={}}) {
+      await runtime.ready;
+      if(typeof target==='string')target=document.querySelector(target);
+      if(!target)throw new TypeError(`Mount target not found: ${String(target)}`);
+      const type=metadata.get(id)?.type;
+      if(!type)throw new Error(`Module ${id} has no registered source type; define it before mounting.`);
+      const owner=pipeline.owners.get(type);
+      const adapter=plugins.find(p=>p.name===owner?.plugin);
+      const renderer=adapter?.renderers?.find(r=>(r.types||[]).includes(type));
+      if(!renderer)throw new Error(`No renderer registered for ${type}`);
+      const built=await runtime.compile(id);
+      const ns=await runtime.import(id);
+      if(!(exportName in ns))throw new Error(`Module ${id} does not export ${exportName}`);
+      const releases=[];
+      let handle;
+      try {
+        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});
+      }catch(error){releases.forEach(fn=>fn());throw error;}
+      let closed=false;
+      const out={ready:Promise.resolve(),capabilities:{updateProps:typeof handle?.updateProps==='function'},
+        async updateProps(next){if(closed)throw new Error('Mount is disposed');if(typeof handle?.updateProps!=='function')throw new Error(`Renderer ${renderer.name||adapter.name} does not support updateProps`);return handle.updateProps(next);},
+        async dispose(){if(closed)return;closed=true;mounts.delete(out);try{await handle?.dispose?.();}finally{releases.forEach(fn=>fn());}}
+      };
+      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?.();}
+  };
+  runtime.ready=Promise.resolve().then(async()=>{for(const plugin of plugins)await plugin.configure?.({runtime,pipeline});});
+  return runtime;
+}
+
+export {analyzeImports} from './build/analyze.js';
+export {BuildPhaseError,createBuildPipeline} from './build/pipeline.js';
+export {createStyleManager} from './resources/styles.js';
+export {createPackagePolicy,PackageVersionResolutionError,parsePackageSpecifier} from './engine/package-resolution/index.js';
+export {createMemoryCompileCache,createLocalStorageCompileCache,createIndexedDBCompileCache} from './engine/compile-cache.js';
+export {createDefaultModuleUrlBackend,createBlobModuleUrlBackend,createDataModuleUrlBackend} from './engine/url-backend.js';

package/src/plugins/package-entries.js

@@ -0,0 +1,30 @@
+/** Merge framework-owned package entries into the ordinary per-runtime policy.
+ * This is link-time configuration, not a browser import-map mutation. */
+import {createPackagePolicy,PackageVersionResolutionError} from '../engine/package-resolution/index.js';
+
+export function mergePluginPackageEntries(packages,plugins=[]) {
+  const source=packages??{};
+  const versions={...(source.versions??{})};
+  const entries={...(source.entries??{})};
+  for(const plugin of plugins) {
+    for(const [name,descriptor] of Object.entries(plugin.packageEntries??{})) {
+      const pluginPolicy=createPackagePolicy({entries:{[name]:descriptor}});
+      const provided=pluginPolicy.inspect(name);
+      if(Object.hasOwn(versions,name)||Object.hasOwn(entries,name)) {
+        const userPolicy=createPackagePolicy({
+          provider:source.provider,
+          ...(Object.hasOwn(versions,name)?{versions:{[name]:versions[name]}}:{entries:{[name]:entries[name]}}),
+        });
+        const selected=userPolicy.inspect(name);
+        if(selected?.url!==provided.url) {
+          throw new PackageVersionResolutionError('PACKAGE_VERSION_CONFLICT',
+            `Plugin ${JSON.stringify(plugin.name)} requires ${JSON.stringify(name)} from ${JSON.stringify(provided.url)}, but the runtime specifies ${JSON.stringify(selected?.url)}. Align the versions/providers instead of loading two framework runtimes.`,
+            {packageName:name,plugin:plugin.name,expected:provided.url,actual:selected?.url});
+        }
+        continue;
+      }
+      entries[name]=descriptor;
+    }
+  }
+  return {...source,versions,entries};
+}

package/src/resources/styles.js

@@ -0,0 +1,18 @@
+/** Per-resource-target stylesheet refcounts. Styles survive until final release. */
+export function createStyleManager() {
+  const sheets = new Map();
+  function acquire({id,content},target = document) {
+    if(!target?.createElement && !target?.ownerDocument)throw new TypeError('A DOM document or shadow root is required for styles.');
+    const doc = target.ownerDocument || target;
+    const root = target.head || target;
+    let byTarget=sheets.get(root);if(!byTarget){byTarget=new Map();sheets.set(root,byTarget);}
+    const key=String(id);let entry=byTarget.get(key);
+    if(entry && entry.content!==content)throw new Error(`CSS asset conflict: ${key}`);
+    if(!entry){const element=doc.createElement('style');element.setAttribute('data-runtime-style',key);element.textContent=content;root.append(element);entry={element,count:0,content};byTarget.set(key,entry);}
+    entry.count++;
+    let released=false;
+    return ()=>{if(released)return;released=true;if(--entry.count===0){entry.element.remove();byTarget.delete(key);if(!byTarget.size)sheets.delete(root);}};
+  }
+  function dispose(){for(const records of sheets.values())for(const entry of records.values())entry.element.remove();sheets.clear();}
+  return { acquire,dispose,get size(){return [...sheets.values()].reduce((n,group)=>n+group.size,0);} };
+}