browser-module-runtime 0.0.0-stage → 0.0.2

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,74 @@
+/** HTML controller with opt-in observation; not coupled to any UI framework. */
+import {registerWebComponent} from '../web-components/index.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}`);}
+}
+
+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 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 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();}}
+  }
+  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,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);}};
+}

package/src/index.d.ts

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

package/src/index.js

@@ -0,0 +1,99 @@
+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];},
+    normalizeInlineSource(source,{type,id,element}={}) {
+      const owner=pipeline.owners.get(type);
+      const plugin=plugins.find(p=>p.name===owner?.plugin);
+      const normalize=plugin?.html?.normalizeInlineSource;
+      return normalize ? normalize(source,{type,id,element,runtime}) : source;
+    },
+    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);} };
+}

package/src/web-components/index.d.ts

@@ -0,0 +1,11 @@
+import type {Runtime} from '../../index.js';
+export type PropType='string'|'number'|'boolean'|'json';
+export type PropSchema=Record<string,PropType|{type:PropType;attribute?:string;default?:unknown}>;
+export interface WebComponentOptions {
+  tag:string;module:string;export?:string;props?:PropSchema;
+  /** Only light DOM is supported at this stage. */
+  shadow?:'none'|false;
+  document?:Document;
+}
+/** Register a native custom element backed by the shared runtime mounting API. */
+export declare function registerWebComponent(runtime:Runtime,options:WebComponentOptions):CustomElementConstructor;

package/src/web-components/index.js

@@ -0,0 +1,145 @@
+/** Native custom elements for any browser-module-runtime renderer. No framework imports. */
+const validName=/^[a-z][a-z0-9._-]*-[a-z0-9._-]+$/;
+const types=new Set(['string','number','boolean','json']);
+
+function normalizeSchema(input) {
+  if(input==null)return {};
+  if(typeof input!=='object'||Array.isArray(input))throw new TypeError('Web component props must be a schema object');
+  const schema={};
+  const attrs=new Set();
+  for(const [key,spec] of Object.entries(input)){
+    const config=typeof spec==='string'?{type:spec}:spec;
+    if(!config||typeof config!=='object'||!types.has(config.type))throw new TypeError(`Invalid prop type for ${key}; expected string, number, boolean, or json`);
+    const attribute=config.attribute||key.replace(/[A-Z]/g,c=>'-'+c.toLowerCase());
+    if(!/^[a-z][a-z0-9._-]*$/.test(attribute)||attrs.has(attribute))throw new TypeError(`Invalid or duplicate attribute: ${attribute}`);
+    attrs.add(attribute);
+    schema[key]={...config,attribute};
+  }
+  return schema;
+}
+function convertAttribute(value,spec,key) {
+  if(value===null)return spec.default!==undefined?spec.default:spec.type==='boolean'?false:undefined;
+  if(spec.type==='string')return value;
+  if(spec.type==='boolean')return true; // standard HTML boolean attribute presence semantics
+  if(spec.type==='number'){
+    if(value.trim()===''||!Number.isFinite(Number(value)))throw new TypeError(`Invalid number for attribute ${spec.attribute}: ${value}`);
+    return Number(value);
+  }
+  try{return JSON.parse(value);}catch(e){throw new TypeError(`Invalid JSON for attribute ${spec.attribute}: ${e.message}`);}
+}
+const inferAttribute=value=>{
+  if(value==='')return true;
+  if(value==='true')return true;
+  if(value==='false')return false;
+  if(/^[-+]?(?:\d+\.?\d*|\.\d+)(?:e[-+]?\d+)?$/i.test(value)&&Number.isFinite(Number(value)))return Number(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}));}
+
+/** Register a framework-rendered runtime module as a native custom element.
+ * v1 mounts in light DOM. Without renderer.updateProps, changes trigger a remount.
+ */
+export function registerWebComponent(runtime,options={}) {
+  const {tag,module,export:exportName='default',props:propsOption,shadow='none',document:doc=globalThis.document}=options;
+  if(!runtime||typeof runtime.mount!=='function')throw new TypeError('registerWebComponent requires a runtime with mount()');
+  if(typeof tag!=='string'||!validName.test(tag))throw new TypeError(`Invalid custom element name: ${String(tag)} (must contain a hyphen)`);
+  if(typeof module!=='string'||!module)throw new TypeError('registerWebComponent requires a module id');
+  if(shadow!=='none'&&shadow!==false)throw new Error('Shadow DOM is not supported yet; use shadow: "none" for light DOM');
+  const win=doc?.defaultView;
+  if(!win?.customElements)throw new TypeError('registerWebComponent requires a browser document with customElements');
+  if(win.customElements.get(tag))throw new Error(`Custom element already registered: ${tag}`);
+  const schema=normalizeSchema(propsOption);
+  const attributes=Object.values(schema).map(s=>s.attribute);
+  class RuntimeElement extends win.HTMLElement {
+    static get observedAttributes(){return attributes;}
+    constructor(){
+      super();
+      this._runtimeHandle=null;
+      this._mounting=null;
+      this._generation=0;
+      this._propertyValues=Object.create(null);
+      this._updateTask=Promise.resolve();
+      // Properties assigned before customElements.define() must survive upgrade.
+      this._preUpgrade=[];
+      for(const key of Object.keys(schema))if(Object.hasOwn(this,key)){
+        this._preUpgrade.push([key,this[key]]);delete this[key];
+      }
+    }
+    _collectProps(){
+      const props={};
+      if(!attributes.length){
+        for(const attr of this.attributes)props[attr.name]=inferAttribute(attr.value);
+      }
+      for(const [key,spec] of Object.entries(schema)){
+        const value=convertAttribute(this.getAttribute(spec.attribute),spec,key);
+        if(value!==undefined)props[key]=value;
+      }
+      Object.assign(props,this._propertyValues);
+      return props;
+    }
+    _report(error){dispatch(this,'runtime-error',{error,module,tag});}
+    connectedCallback(){
+      for(const [key,value] of this._preUpgrade.splice(0))this[key]=value;
+      const version=++this._generation;
+      queueMicrotask(()=>{if(this.isConnected&&version===this._generation)this._start(version);});
+    }
+    disconnectedCallback(){
+      const version=++this._generation;
+      queueMicrotask(()=>{
+        if(!this.isConnected&&version===this._generation)this._stop().catch(e=>this._report(e));
+      });
+    }
+    attributeChangedCallback(attr,oldValue,newValue){
+      if(oldValue===newValue)return;
+      const entry=Object.entries(schema).find(([,spec])=>spec.attribute===attr);
+      if(entry)delete this._propertyValues[entry[0]];
+      if(this.isConnected)this._scheduleUpdate();
+    }
+    _scheduleUpdate(){
+      this._updateTask=this._updateTask.catch(()=>{}).then(async()=>{
+        // Allow batched changes and a mount in progress to settle before applying changes.
+        if(this._mounting)await this._mounting;
+        if(!this.isConnected||!this._runtimeHandle)return;
+        const props=this._collectProps();
+        if(this._runtimeHandle.capabilities.updateProps){
+          await this._runtimeHandle.updateProps(props);
+        }else{
+          // An explicit remount is preferable to silently ignoring changed attributes.
+          await this._runtimeHandle.dispose();this._runtimeHandle=null;
+          await this._start(this._generation);
+        }
+      }).catch(e=>this._report(e));
+    }
+    async _start(version){
+      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});
+        this._mounting=mountPromise;
+        const handle=await mountPromise;
+        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{
+        this._mounting=null;
+        if(this.isConnected&&!this._runtimeHandle&&version!==this._generation)
+          queueMicrotask(()=>this._start(this._generation));
+      }
+    }
+    async _stop(){
+      // 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});}
+    }
+  }
+  for(const key of Object.keys(schema)){
+    Object.defineProperty(RuntimeElement.prototype,key,{
+      configurable:true,enumerable:true,
+      get(){return Object.hasOwn(this._propertyValues,key)?this._propertyValues[key]:convertAttribute(this.getAttribute(schema[key].attribute),schema[key],key);},
+      set(value){this._propertyValues[key]=value;if(this.isConnected)this._scheduleUpdate();}
+    });
+  }
+  win.customElements.define(tag,RuntimeElement);
+  return RuntimeElement;
+}

package/web-components.d.ts

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