browser-module-runtime 0.0.1 → 0.0.2

package/html.d.ts

@@ -1,3 +1,4 @@
 import type {Runtime} from './index.js';
-export interface HTMLController {readonly name:string;readonly runtime:Runtime;registerExisting():Promise<void>;scan():Promise<void>;disconnect():Promise<void>}
+import type {WebComponentOptions} from './web-components.js';
+export interface HTMLController {readonly name:string;readonly runtime:Runtime;defineElement(tag:string,options:Omit<WebComponentOptions,'tag'>):CustomElementConstructor;registerExisting():Promise<void>;scan():Promise<void>;disconnect():Promise<void>}
 export declare function registerHTML(runtime:Runtime,options?:{name?:string;root?:Document|Element;observe?:boolean}):HTMLController;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-module-runtime",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "type": "module",
   "exports": {
     ".": {
@@ -12,13 +12,18 @@
       "import": "./src/html/index.js"
     },
     "./packages": "./src/engine/package-resolution/index.js",
-    "./cache": "./src/engine/compile-cache.js"
+    "./cache": "./src/engine/compile-cache.js",
+    "./web-components": {
+      "types": "./web-components.d.ts",
+      "import": "./src/web-components/index.js"
+    }
   },
   "files": [
     "src",
     "index.d.ts",
     "html.d.ts",
-    "README.md"
+    "README.md",
+    "web-components.d.ts"
   ],
   "engines": {
     "node": ">=20"

package/src/html/index.js

@@ -1,6 +1,14 @@
 /** 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;
@@ -12,6 +20,15 @@ export function registerHTML(runtime,{name='default',root=globalThis.document,ob
   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;
@@ -21,8 +38,17 @@ export function registerHTML(runtime,{name='default',root=globalThis.document,ob
       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});
+      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){
@@ -44,5 +70,5 @@ export function registerHTML(runtime,{name='default',root=globalThis.document,ob
   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);}};
+  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.js

@@ -36,6 +36,12 @@ export function createRuntime(options={}) {
     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;

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';