@wuyuchentr/webassembly-runtime-embed 4.0.0 → 5.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wuyuchentr/webassembly-runtime-embed",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "description": "Embed WebAssembly runtime in Node.js with WASI support, multi-instance isolation, resource limits, and remote loading with cache.",
   "bin": {
     "webassembly-runtime-embed": "bin/cli.js"

package/src/component.js

@@ -0,0 +1,728 @@
+const COMPONENT_MAGIC = Buffer.from([0x00, 0x61, 0x73, 0x6d, 0x0a, 0x00, 0x01, 0x00]);
+const CORE_MAGIC = Buffer.from([0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00]);
+
+const SECTION_COMPONENT_TYPE_SORT = 0x50;
+const SECTION_COMPONENT_IMPORT_SORT = 0x03;
+const SECTION_COMPONENT_EXPORT_SORT = 0x07;
+const SECTION_COMPONENT_INSTANCE = 0x01;
+const SECTION_COMPONENT_ALIAS = 0x02;
+const SECTION_COMPONENT_CANON = 0x0a;
+const SECTION_COMPONENT_START = 0x0c;
+
+const TYPE_STRING = 'string';
+const TYPE_BOOL = 'bool';
+const TYPE_U8 = 'u8';
+const TYPE_U16 = 'u16';
+const TYPE_U32 = 'u32';
+const TYPE_U64 = 'u64';
+const TYPE_S8 = 's8';
+const TYPE_S16 = 's16';
+const TYPE_S32 = 's32';
+const TYPE_S64 = 's64';
+const TYPE_F32 = 'float32';
+const TYPE_F64 = 'float64';
+const TYPE_CHAR = 'char';
+const TYPE_LIST = 'list';
+const TYPE_RECORD = 'record';
+const TYPE_TUPLE = 'tuple';
+const TYPE_VARIANT = 'variant';
+const TYPE_OPTION = 'option';
+const TYPE_RESULT = 'result';
+const TYPE_ENUM = 'enum';
+const TYPE_FLAGS = 'flags';
+
+const PRIMITIVE_SIZES = {
+  [TYPE_BOOL]: 1,
+  [TYPE_U8]: 1, [TYPE_U16]: 2, [TYPE_U32]: 4, [TYPE_U64]: 8,
+  [TYPE_S8]: 1, [TYPE_S16]: 2, [TYPE_S32]: 4, [TYPE_S64]: 8,
+  [TYPE_F32]: 4, [TYPE_F64]: 8, [TYPE_CHAR]: 4,
+};
+
+class ComponentType {
+  constructor(def) {
+    this.kind = def.kind || def;
+    this.options = def.options || {};
+    this.fields = def.fields || [];
+    this.cases = def.cases || [];
+    this.element = def.element || null;
+    this.ok = def.ok || null;
+    this.err = def.err || null;
+    this.inner = def.inner || null;
+    this.align = def.align || 1;
+  }
+
+  size(memory) {
+    switch (this.kind) {
+      case TYPE_STRING: return 8;
+      case TYPE_LIST: return 8;
+      case TYPE_BOOL: case TYPE_U8: case TYPE_S8: return 1;
+      case TYPE_U16: case TYPE_S16: return 2;
+      case TYPE_U32: case TYPE_S32: case TYPE_F32: case TYPE_CHAR: return 4;
+      case TYPE_U64: case TYPE_S64: case TYPE_F64: return 8;
+      case TYPE_RECORD: return this.fields.reduce((s, f) => s + this._fieldType(f).size(memory), 0);
+      case TYPE_TUPLE: return this.inner.reduce((s, t) => s + t.size(memory), 0);
+      case TYPE_VARIANT: return 4 + Math.max(0, ...this.cases.map(c => { const t = this._caseType(c); return t ? t.size(memory) : 0; }));
+      case TYPE_OPTION: return 4 + (this.inner ? this.inner.size(memory) : 0);
+      case TYPE_RESULT: return 4 + Math.max(
+        this.ok ? this.ok.size(memory) : 0,
+        this.err ? this.err.size(memory) : 0
+      );
+      case TYPE_ENUM: return 1;
+      case TYPE_FLAGS: return Math.ceil(this.options.flagCount / 8);
+      default: return 4;
+    }
+  }
+
+  _fieldType(field) {
+    return field.type instanceof ComponentType ? field.type : new ComponentType(field.type);
+  }
+
+  _caseType(caseDef) {
+    if (!caseDef || !caseDef.type) return null;
+    return caseDef.type instanceof ComponentType ? caseDef.type : new ComponentType(caseDef.type);
+  }
+}
+
+function isComponent(bytes) {
+  if (bytes.length < 8) return false;
+  return bytes.slice(0, 8).equals(COMPONENT_MAGIC);
+}
+
+class ComponentInfo {
+  constructor(bytes) {
+    this.bytes = bytes;
+    this.isComponent = isComponent(bytes);
+    this.imports = [];
+    this.exports = [];
+    this.typeDefs = new Map();
+
+    if (this.isComponent) {
+      this._parse();
+    }
+  }
+
+  _parse() {
+    let offset = 8;
+    while (offset < this.bytes.length) {
+      const sectionId = this.bytes[offset++];
+      const sectionLen = this._leb128(offset);
+      offset += this._leb128Size(this.bytes, offset - 1);
+      const sectionEnd = offset + sectionLen;
+      if (sectionId === SECTION_COMPONENT_TYPE_SORT) {
+        this._parseTypes(offset, sectionEnd);
+      } else if (sectionId === SECTION_COMPONENT_IMPORT_SORT) {
+        this._parseImports(offset, sectionEnd);
+      } else if (sectionId === SECTION_COMPONENT_EXPORT_SORT) {
+        this._parseExports(offset, sectionEnd);
+      }
+      offset = sectionEnd;
+    }
+  }
+
+  _parseTypes(offset, end) {
+    const count = this._leb128(offset);
+    offset += this._leb128Size(this.bytes, offset);
+    for (let i = 0; i < count && offset < end; i++) {
+      const typeByte = this.bytes[offset++];
+      if (typeByte === 0x01) {
+        offset = this._parseFuncType(offset, i);
+      } else if (typeByte === 0x02) {
+        offset = this._parseComponentType(offset, i);
+      } else if (typeByte === 0x03) {
+        offset = this._parseInstanceType(offset, i);
+      }
+    }
+  }
+
+  _parseComponentType(offset, idx) {
+    const typeByte = this.bytes[offset++];
+    if (typeByte === 0x00) {
+      this.typeDefs.set(idx, 'defined');
+      return offset;
+    }
+    if (typeByte === 0x01) {
+      const count = this._leb128(offset);
+      offset += this._leb128Size(this.bytes, offset);
+      this.typeDefs.set(idx, { kind: TYPE_RECORD, fields: [] });
+      return offset;
+    }
+    if (typeByte === 0x02) {
+      this.typeDefs.set(idx, { kind: TYPE_FLAGS, options: { flagCount: 0 } });
+      return offset;
+    }
+    if (typeByte === 0x03) {
+      this.typeDefs.set(idx, { kind: TYPE_ENUM });
+      return offset;
+    }
+    if (typeByte === 0x04) {
+      const count = this._leb128(offset);
+      offset += this._leb128Size(this.bytes, offset);
+      this.typeDefs.set(idx, { kind: TYPE_VARIANT, cases: [] });
+      return offset;
+    }
+    if (typeByte === 0x05) {
+      const count = this._leb128(offset);
+      offset += this._leb128Size(this.bytes, offset);
+      this.typeDefs.set(idx, { kind: TYPE_TUPLE, inner: [] });
+      return offset;
+    }
+    if (typeByte === 0x06) {
+      this.typeDefs.set(idx, { kind: TYPE_LIST, element: null });
+      return offset;
+    }
+    if (typeByte === 0x07) {
+      this.typeDefs.set(idx, { kind: TYPE_OPTION, inner: null });
+      return offset;
+    }
+    if (typeByte === 0x08) {
+      this.typeDefs.set(idx, { kind: TYPE_RESULT, ok: null, err: null });
+      return offset;
+    }
+    if (typeByte === 0x09) {
+      this.typeDefs.set(idx, { kind: 'borrow' });
+      return offset;
+    }
+    if (typeByte === 0x10) {
+      this.typeDefs.set(idx, { kind: TYPE_STRING });
+      return offset;
+    }
+    if (typeByte === 0x11) {
+      this.typeDefs.set(idx, { kind: TYPE_BOOL });
+      return offset;
+    }
+    if (typeByte === 0x12) {
+      this.typeDefs.set(idx, { kind: TYPE_U8 });
+      return offset;
+    }
+    if (typeByte === 0x13) {
+      this.typeDefs.set(idx, { kind: TYPE_U16 });
+      return offset;
+    }
+    if (typeByte === 0x14) {
+      this.typeDefs.set(idx, { kind: TYPE_U32 });
+      return offset;
+    }
+    if (typeByte === 0x15) {
+      this.typeDefs.set(idx, { kind: TYPE_U64 });
+      return offset;
+    }
+    if (typeByte === 0x16) {
+      this.typeDefs.set(idx, { kind: TYPE_S8 });
+      return offset;
+    }
+    if (typeByte === 0x17) {
+      this.typeDefs.set(idx, { kind: TYPE_S16 });
+      return offset;
+    }
+    if (typeByte === 0x18) {
+      this.typeDefs.set(idx, { kind: TYPE_S32 });
+      return offset;
+    }
+    if (typeByte === 0x19) {
+      this.typeDefs.set(idx, { kind: TYPE_S64 });
+      return offset;
+    }
+    if (typeByte === 0x1a) {
+      this.typeDefs.set(idx, { kind: TYPE_F32 });
+      return offset;
+    }
+    if (typeByte === 0x1b) {
+      this.typeDefs.set(idx, { kind: TYPE_F64 });
+      return offset;
+    }
+    if (typeByte === 0x1c) {
+      this.typeDefs.set(idx, { kind: TYPE_CHAR });
+      return offset;
+    }
+    if (typeByte === 0x1d) {
+      this.typeDefs.set(idx, { kind: TYPE_STRING });
+      return offset;
+    }
+    return offset;
+  }
+
+  _parseImports(offset, end) {
+    const count = this._leb128(offset);
+    offset += this._leb128Size(this.bytes, offset);
+    for (let i = 0; i < count && offset < end; i++) {
+      const sort = this.bytes[offset++];
+      const nameLen = this._leb128(offset);
+      offset += this._leb128Size(this.bytes, offset);
+      let name = this.bytes.toString('utf8', offset, offset + nameLen);
+      offset += nameLen;
+      this.imports.push({ sort, name, typeIdx: 0 });
+      if (sort === 0x00) {
+        const typeIdx = this._leb128(offset);
+        offset += this._leb128Size(this.bytes, offset);
+        this.imports[this.imports.length - 1].typeIdx = typeIdx;
+      } else if (sort === 0x01) {
+        const typeIdx = this._leb128(offset);
+        offset += this._leb128Size(this.bytes, offset);
+        this.imports[this.imports.length - 1].typeIdx = typeIdx;
+      } else if (sort === 0x02) {
+        const instanceIdx = this._leb128(offset);
+        offset += this._leb128Size(this.bytes, offset);
+        this.imports[this.imports.length - 1].instanceIdx = instanceIdx;
+      }
+    }
+  }
+
+  _parseExports(offset, end) {
+    const count = this._leb128(offset);
+    offset += this._leb128Size(this.bytes, offset);
+    for (let i = 0; i < count && offset < end; i++) {
+      const sort = this.bytes[offset++];
+      const nameLen = this._leb128(offset);
+      offset += this._leb128Size(this.bytes, offset);
+      let name = this.bytes.toString('utf8', offset, offset + nameLen);
+      offset += nameLen;
+      if (sort === 0x00) {
+        const funcIdx = this._leb128(offset);
+        offset += this._leb128Size(this.bytes, offset);
+        this.exports.push({ sort, name, funcIdx });
+      } else if (sort === 0x01) {
+        const typeIdx = this._leb128(offset);
+        offset += this._leb128Size(this.bytes, offset);
+        this.exports.push({ sort, name, typeIdx });
+      } else if (sort === 0x03) {
+        const instanceIdx = this._leb128(offset);
+        offset += this._leb128Size(this.bytes, offset);
+        this.exports.push({ sort, name, instanceIdx });
+      }
+    }
+  }
+
+  _parseFuncType(offset, idx) {
+    const paramCount = this._leb128(offset);
+    offset += this._leb128Size(this.bytes, offset);
+    const params = [];
+    for (let i = 0; i < paramCount; i++) {
+      const paramNameLen = this._leb128(offset);
+      offset += this._leb128Size(this.bytes, offset);
+      const paramName = this.bytes.toString('utf8', offset, offset + paramNameLen);
+      offset += paramNameLen;
+      const valType = this.bytes[offset++];
+      params.push({ name: paramName, valType });
+    }
+    const resultCount = this._leb128(offset);
+    offset += this._leb128Size(this.bytes, offset);
+    if (resultCount === 1) {
+      offset++;
+    }
+    this.typeDefs.set(idx, { kind: 'func', params, results: resultCount });
+    return offset;
+  }
+
+  _parseInstanceType(offset, idx) {
+    const count = this._leb128(offset);
+    offset += this._leb128Size(this.bytes, offset);
+    for (let i = 0; i < count && offset < this.bytes.length; i++) {
+      const exportSort = this.bytes[offset++];
+      const nameLen = this._leb128(offset);
+      offset += this._leb128Size(this.bytes, offset);
+      offset += nameLen;
+      if (exportSort === 0x00) {
+        const typeIdx = this._leb128(offset);
+        offset += this._leb128Size(this.bytes, offset);
+      } else if (exportSort === 0x01) {
+        const typeIdx = this._leb128(offset);
+        offset += this._leb128Size(this.bytes, offset);
+      }
+    }
+    return offset;
+  }
+
+  _leb128(offset) {
+    let result = 0, shift = 0;
+    while (true) {
+      const byte = this.bytes[offset];
+      result |= (byte & 0x7f) << shift;
+      if (!(byte & 0x80)) break;
+      shift += 7;
+      offset++;
+    }
+    return result;
+  }
+
+  _leb128Size(buf, offset) {
+    let size = 0;
+    while (true) {
+      const byte = buf[offset + size];
+      size++;
+      if (!(byte & 0x80)) break;
+    }
+    return size;
+  }
+}
+
+class ComponentAdapter {
+  static lift(type, memoryView, ptr, options = {}) {
+    const t = type instanceof ComponentType ? type : new ComponentType(type);
+    switch (t.kind) {
+      case TYPE_STRING: return ComponentAdapter._liftString(memoryView, ptr);
+      case TYPE_BOOL: return memoryView.readU8(ptr) !== 0;
+      case TYPE_U8: return memoryView.readU8(ptr);
+      case TYPE_U16: return memoryView.readU16(ptr);
+      case TYPE_U32: case TYPE_CHAR: case TYPE_S32: return memoryView.readU32(ptr);
+      case TYPE_U64: case TYPE_S64: return Number(memoryView.readU32(ptr)) + (Number(memoryView.readU32(ptr + 4)) * 4294967296);
+      case TYPE_F32: return memoryView.readF32(ptr);
+      case TYPE_F64: return memoryView.readF64(ptr);
+      case TYPE_S8: return memoryView.readU8(ptr) << 24 >> 24;
+      case TYPE_S16: return memoryView.readU16(ptr) << 16 >> 16;
+      case TYPE_LIST: return ComponentAdapter._liftList(t.element, memoryView, ptr);
+      case TYPE_RECORD: return ComponentAdapter._liftRecord(t, memoryView, ptr);
+      case TYPE_TUPLE: return ComponentAdapter._liftTuple(t, memoryView, ptr);
+      case TYPE_VARIANT: return ComponentAdapter._liftVariant(t, memoryView, ptr);
+      case TYPE_OPTION: return ComponentAdapter._liftOption(t, memoryView, ptr);
+      case TYPE_RESULT: return ComponentAdapter._liftResult(t, memoryView, ptr);
+      case TYPE_ENUM: return memoryView.readU8(ptr);
+      case TYPE_FLAGS: {
+        const flagBytes = Math.ceil(t.options.flagCount / 8);
+        let val = 0;
+        for (let i = 0; i < flagBytes; i++) val |= memoryView.readU8(ptr + i) << (i * 8);
+        return val;
+      }
+      default: return memoryView.readU32(ptr);
+    }
+  }
+
+  static lower(type, memoryView, ptr, value) {
+    const t = type instanceof ComponentType ? type : new ComponentType(type);
+    switch (t.kind) {
+      case TYPE_STRING: return ComponentAdapter._lowerString(memoryView, ptr, value);
+      case TYPE_BOOL: memoryView.writeU8(ptr, value ? 1 : 0); return 1;
+      case TYPE_U8: case TYPE_S8: memoryView.writeU8(ptr, value); return 1;
+      case TYPE_U16: case TYPE_S16: memoryView.writeU16(ptr, value); return 2;
+      case TYPE_U32: case TYPE_S32: case TYPE_CHAR: memoryView.writeU32(ptr, value); return 4;
+      case TYPE_F32: memoryView.writeF32(ptr, value); return 4;
+      case TYPE_F64: memoryView.writeF64(ptr, value); return 8;
+      case TYPE_LIST: return ComponentAdapter._lowerList(t.element, memoryView, ptr, value);
+      case TYPE_RECORD: return ComponentAdapter._lowerRecord(t, memoryView, ptr, value);
+      case TYPE_TUPLE: return ComponentAdapter._lowerTuple(t, memoryView, ptr, value);
+      case TYPE_VARIANT: return ComponentAdapter._lowerVariant(t, memoryView, ptr, value);
+      case TYPE_OPTION: return ComponentAdapter._lowerOption(t, memoryView, ptr, value);
+      case TYPE_RESULT: return ComponentAdapter._lowerResult(t, memoryView, ptr, value);
+      case TYPE_ENUM: memoryView.writeU8(ptr, value); return 1;
+      default: memoryView.writeU32(ptr, value); return 4;
+    }
+  }
+
+  static _liftString(mem, ptr) {
+    const dataPtr = mem.readU32(ptr);
+    const len = mem.readU32(ptr + 4);
+    return mem.readString(dataPtr, len);
+  }
+
+  static _lowerString(mem, ptr, str) {
+    const bytes = new TextEncoder().encode(String(str));
+    const dataPtr = mem.alloc(bytes.length);
+    mem.writeBytes(dataPtr, bytes);
+    mem.writeU32(ptr, dataPtr);
+    mem.writeU32(ptr + 4, bytes.length);
+    return 8;
+  }
+
+  static _liftList(elemType, mem, ptr) {
+    const dataPtr = mem.readU32(ptr);
+    const len = mem.readU32(ptr + 4);
+    const result = [];
+    const elemT = elemType ? (elemType instanceof ComponentType ? elemType : new ComponentType(elemType)) : new ComponentType({ kind: TYPE_U32 });
+    const elemSize = elemT.size();
+    for (let i = 0; i < len; i++) {
+      result.push(ComponentAdapter.lift(elemT, mem, dataPtr + i * elemSize));
+    }
+    return result;
+  }
+
+  static _lowerList(elemType, mem, ptr, arr) {
+    arr = arr || [];
+    const elemT = elemType ? (elemType instanceof ComponentType ? elemType : new ComponentType(elemType)) : new ComponentType({ kind: TYPE_U32 });
+    const elemSize = elemT.size();
+    const dataPtr = mem.alloc(arr.length * elemSize);
+    for (let i = 0; i < arr.length; i++) {
+      ComponentAdapter.lower(elemT, mem, dataPtr + i * elemSize, arr[i]);
+    }
+    mem.writeU32(ptr, dataPtr);
+    mem.writeU32(ptr + 4, arr.length);
+    return 8;
+  }
+
+  static _liftRecord(type, mem, ptr) {
+    const result = {};
+    let offset = 0;
+    for (const field of type.fields) {
+      const fieldT = field.type instanceof ComponentType ? field.type : new ComponentType(field.type);
+      result[field.name] = ComponentAdapter.lift(fieldT, mem, ptr + offset);
+      offset += fieldT.size();
+    }
+    return result;
+  }
+
+  static _lowerRecord(type, mem, ptr, value) {
+    let written = 0;
+    for (const field of type.fields) {
+      const fieldT = field.type instanceof ComponentType ? field.type : new ComponentType(field.type);
+      ComponentAdapter.lower(fieldT, mem, ptr + written, value ? value[field.name] : undefined);
+      written += fieldT.size();
+    }
+    return written;
+  }
+
+  static _liftTuple(type, mem, ptr) {
+    const result = [];
+    let offset = 0;
+    for (const elemT of type.inner) {
+      const t = elemT instanceof ComponentType ? elemT : new ComponentType(elemT);
+      result.push(ComponentAdapter.lift(t, mem, ptr + offset));
+      offset += t.size();
+    }
+    return result;
+  }
+
+  static _lowerTuple(type, mem, ptr, value) {
+    value = value || [];
+    let written = 0;
+    for (let i = 0; i < type.inner.length; i++) {
+      const t = type.inner[i] instanceof ComponentType ? type.inner[i] : new ComponentType(type.inner[i]);
+      ComponentAdapter.lower(t, mem, ptr + written, value[i]);
+      written += t.size();
+    }
+    return written;
+  }
+
+  static _liftVariant(type, mem, ptr) {
+    const disc = mem.readU32(ptr);
+    const caseDef = type.cases[disc];
+    if (!caseDef) return { tag: disc };
+    if (!caseDef.type) return { tag: disc, value: undefined };
+    const caseT = caseDef.type instanceof ComponentType ? caseDef.type : new ComponentType(caseDef.type);
+    const value = ComponentAdapter.lift(caseT, mem, ptr + 4);
+    return { tag: disc, value };
+  }
+
+  static _lowerVariant(type, mem, ptr, value) {
+    const tag = value.tag !== undefined ? value.tag : 0;
+    mem.writeU32(ptr, tag);
+    const caseDef = type.cases[tag];
+    if (caseDef && caseDef.type && value.value !== undefined) {
+      const caseT = caseDef.type instanceof ComponentType ? caseDef.type : new ComponentType(caseDef.type);
+      ComponentAdapter.lower(caseT, mem, ptr + 4, value.value);
+    }
+    return 4 + (caseDef && caseDef.type ? caseDef.type.size() : 0);
+  }
+
+  static _liftOption(type, mem, ptr) {
+    const disc = mem.readU32(ptr);
+    if (disc === 0) return null;
+    if (type.inner) {
+      const innerT = type.inner instanceof ComponentType ? type.inner : new ComponentType(type.inner);
+      return ComponentAdapter.lift(innerT, mem, ptr + 4);
+    }
+    return true;
+  }
+
+  static _lowerOption(type, mem, ptr, value) {
+    if (value === null || value === undefined) {
+      mem.writeU32(ptr, 0);
+      return 4;
+    }
+    mem.writeU32(ptr, 1);
+    if (type.inner) {
+      const innerT = type.inner instanceof ComponentType ? type.inner : new ComponentType(type.inner);
+      ComponentAdapter.lower(innerT, mem, ptr + 4, value);
+      return 4 + innerT.size();
+    }
+    return 4;
+  }
+
+  static _liftResult(type, mem, ptr) {
+    const disc = mem.readU32(ptr);
+    if (disc === 0 && type.ok) {
+      const okT = type.ok instanceof ComponentType ? type.ok : new ComponentType(type.ok);
+      return { ok: ComponentAdapter.lift(okT, mem, ptr + 4) };
+    }
+    if (disc === 1 && type.err) {
+      const errT = type.err instanceof ComponentType ? type.err : new ComponentType(type.err);
+      return { err: ComponentAdapter.lift(errT, mem, ptr + 4) };
+    }
+    return disc === 0 ? { ok: null } : { err: null };
+  }
+
+  static _lowerResult(type, mem, ptr, value) {
+    if (value && value.err !== undefined) {
+      mem.writeU32(ptr, 1);
+      if (type.err && value.err !== null) {
+        const errT = type.err instanceof ComponentType ? type.err : new ComponentType(type.err);
+        ComponentAdapter.lower(errT, mem, ptr + 4, value.err);
+        return 4 + errT.size();
+      }
+      return 4;
+    }
+    mem.writeU32(ptr, 0);
+    if (type.ok && value && value.ok !== undefined && value.ok !== null) {
+      const okT = type.ok instanceof ComponentType ? type.ok : new ComponentType(type.ok);
+      ComponentAdapter.lower(okT, mem, ptr + 4, value.ok);
+      return 4 + okT.size();
+    }
+    return 4;
+  }
+}
+
+class ComponentInstance {
+  constructor(runtime, componentInfo, options = {}) {
+    this.runtime = runtime;
+    this.info = componentInfo;
+    this.options = options;
+    this._coreInstance = null;
+    this._exports = new Map();
+    this._loaded = false;
+  }
+
+  async instantiate(imports = {}) {
+    const bytes = this.info.bytes;
+    const module = await WebAssembly.compile(bytes);
+    const importObj = this._buildImportObject(imports);
+    this._coreInstance = await WebAssembly.instantiate(module, importObj);
+    if (this._coreInstance.exports.memory) {
+      this._memory = this._coreInstance.exports.memory;
+      const { MemoryView } = require('./memory.js');
+      this._memoryView = new MemoryView(this._memory);
+    }
+    this._resolveExports();
+    this._loaded = true;
+    return this;
+  }
+
+  _buildImportObject(imports) {
+    if (!this.info.imports || this.info.imports.length === 0) return imports;
+    const result = {};
+    for (const imp of this.info.imports) {
+      if (imp.sort === 0x00) {
+        const mod = imp.name;
+        if (!result[mod]) result[mod] = {};
+        const provided = imports[mod] || {};
+        result[mod][imp.name] = provided[imp.name] || (() => {});
+      }
+    }
+    return Object.keys(result).length > 0 ? result : imports;
+  }
+
+  _resolveExports() {
+    if (!this._coreInstance) return;
+    const exports = this._coreInstance.exports;
+    for (const exp of this.info.exports || []) {
+      if (exp.sort === 0x00 && typeof exports[exp.name] === 'function') {
+        this._exports.set(exp.name, {
+          func: exports[exp.name],
+          paramTypes: (exp.paramTypes || []).map(t => new ComponentType(t)),
+          resultType: exp.resultType ? new ComponentType(exp.resultType) : null,
+        });
+      }
+    }
+  }
+
+  async call(name, ...args) {
+    const exportDef = this._exports.get(name);
+    if (!exportDef) {
+      if (this._coreInstance && typeof this._coreInstance.exports[name] === 'function') {
+        return this._coreInstance.exports[name](...args);
+      }
+      throw new Error(`Component export '${name}' not found`);
+    }
+
+    if (!this._memoryView) {
+      return exportDef.func(...args);
+    }
+
+    const mem = this._memoryView;
+    const snapshot = mem.snapshot();
+    const paramTypes = exportDef.paramTypes || [];
+    const loweredArgs = [];
+    let argOffset = 0;
+
+    for (let i = 0; i < paramTypes.length; i++) {
+      const pt = paramTypes[i];
+      const size = pt.size();
+      if (pt.kind === TYPE_STRING || pt.kind === TYPE_LIST) {
+        ComponentAdapter.lower(pt, mem, argOffset, args[i]);
+        loweredArgs.push(mem.readU32(argOffset), mem.readU32(argOffset + 4));
+        argOffset += size;
+      } else {
+        loweredArgs.push(args[i]);
+      }
+    }
+
+    const result = exportDef.func(...loweredArgs);
+
+    const resultType = exportDef.resultType;
+    if (resultType && (resultType.kind === TYPE_STRING || resultType.kind === TYPE_LIST)) {
+      const lifted = ComponentAdapter.lift(resultType, mem, 0);
+      mem.restore(snapshot);
+      return lifted;
+    }
+
+    mem.restore(snapshot);
+    return result;
+  }
+
+  getMemory() {
+    return this._memoryView;
+  }
+
+  hasExport(name) {
+    return this._exports.has(name) || (this._coreInstance && name in this._coreInstance.exports);
+  }
+
+  exportNames() {
+    const names = Array.from(this._exports.keys());
+    if (this._coreInstance) {
+      names.push(...Object.keys(this._coreInstance.exports).filter(n => !names.includes(n)));
+    }
+    return names;
+  }
+}
+
+class ComponentLinker {
+  constructor(runtime, options = {}) {
+    this.runtime = runtime;
+    this.components = new Map();
+    this.instances = [];
+  }
+
+  register(name, componentInfo) {
+    this.components.set(name, componentInfo);
+  }
+
+  async instantiate(name, providedImports = {}) {
+    const info = this.components.get(name);
+    if (!info) throw new Error(`Component '${name}' not registered`);
+    const imports = { ...providedImports };
+    for (const imp of info.imports) {
+      if (imp.sort === 0x03) {
+        const depName = imp.name;
+        if (!imports[depName] && this.instances.length > 0) {
+          const depInst = this.instances.find(i => i.info === this.components.get(depName));
+          if (depInst) {
+            if (!imports[depName]) imports[depName] = {};
+            for (const exp of (this.components.get(depName) || {}).exports || []) {
+              imports[depName][depName] = depInst._coreInstance.exports[depName];
+            }
+          }
+        }
+      }
+    }
+    const inst = new ComponentInstance(this.runtime, info, {});
+    await inst.instantiate(imports);
+    this.instances.push(inst);
+    return inst;
+  }
+}
+
+module.exports = {
+  isComponent,
+  ComponentInfo,
+  ComponentType,
+  ComponentAdapter,
+  ComponentInstance,
+  ComponentLinker,
+};

package/src/index.js

@@ -6,6 +6,7 @@ const { WasiContext } = require('./wasi.js');
 const { WasmPool, InstanceLease } = require('./pool.js');
 const { HotReload } = require('./watcher.js');
 const { WasmWorker, WasmClient, WasmCluster } = require('./cluster.js');
+const { ComponentInfo, ComponentInstance, ComponentLinker, ComponentAdapter, ComponentType, isComponent } = require('./component.js');
 const loader = require('./loader.js');
 
 function createRuntime(options = {}) {
@@ -33,5 +34,11 @@ module.exports = {
   WasmWorker,
   WasmClient,
   WasmCluster,
+  ComponentInfo,
+  ComponentInstance,
+  ComponentLinker,
+  ComponentAdapter,
+  ComponentType,
+  isComponent,
   loader,
 };

package/src/runtime.js

@@ -4,6 +4,7 @@ const { ResourceLimits } = require('./limits.js');
 const { WasmPool } = require('./pool.js');
 const { HotReload } = require('./watcher.js');
 const { WasmWorker, WasmClient, WasmCluster } = require('./cluster.js');
+const { ComponentInfo, ComponentInstance, ComponentLinker, isComponent } = require('./component.js');
 const loader = require('./loader.js');
 
 class WasmInstance {
@@ -162,6 +163,26 @@ class WasmRuntime {
     return new WasmCluster(options);
   }
 
+  async loadComponent(source, options = {}) {
+    let bytes;
+    if (Buffer.isBuffer(source)) {
+      bytes = source;
+    } else if (source.startsWith('http://') || source.startsWith('https://')) {
+      const result = await loader.loadFromUrl(source, options);
+      bytes = result.bytes;
+    } else {
+      const result = await loader.loadFromFile(source);
+      bytes = result.bytes;
+    }
+    const info = new ComponentInfo(bytes);
+    const inst = new ComponentInstance(this, info, options);
+    return inst;
+  }
+
+  createLinker(options = {}) {
+    return new ComponentLinker(this, options);
+  }
+
   getStats() {
     return {
       instances: this.instances.length,