watr 3.2.1 → 3.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "watr",
-  "version": "3.2.1",
+  "version": "3.3.0",
   "description": "Ligth & fast WAT compiler",
   "main": "watr.js",
   "exports": {

package/readme.md

@@ -77,25 +77,22 @@ print(src, {
 ## Status
 
 * [x] core
-* [x] [mutable globals](https://github.com/WebAssembly/mutable-global), [extended const](https://github.com/WebAssembly/extended-const/blob/main/proposals/extended-const/Overview.md), [nontrapping float to int](https://github.com/WebAssembly/nontrapping-float-to-int-conversions), [sign extension](https://github.com/WebAssembly/sign-extension-ops)
-* [x] [multi-value](https://github.com/WebAssembly/spec/blob/master/proposals/multi-value/Overview.md), [bulk memory ops](https://github.com/WebAssembly/bulk-memory-operations/blob/master/proposals/bulk-memory-operations/Overview.md), [multiple memories](https://github.com/WebAssembly/multi-memory/blob/master/proposals/multi-memory/Overview.md)
+* [x] [mutable globals](https://github.com/WebAssembly/mutable-global), [extended const](https://github.com/WebAssembly/extended-const/blob/main/proposals/extended-const/Overview.md), [sign extension](https://github.com/WebAssembly/sign-extension-ops), [nontrapping float to int](https://github.com/WebAssembly/nontrapping-float-to-int-conversions)
+* [x] [multi-value](https://github.com/WebAssembly/spec/blob/master/proposals/multi-value/Overview.md), [bulk memory ops](https://github.com/WebAssembly/bulk-memory-operations/blob/master/proposals/bulk-memory-operations/Overview.md), [multiple memories](https://github.com/WebAssembly/multi-memory/blob/main/proposals/multi-memory/Overview.md)
 * [x] [simd](https://github.com/WebAssembly/simd/blob/master/proposals/simd/SIMD.md), [relaxed simd](https://github.com/WebAssembly/relaxed-simd), [fixed-width simd](https://github.com/WebAssembly/simd/blob/master/proposals/simd/SIMD.md)
 * [x] [tail_call](https://github.com/WebAssembly/tail-call)
-* [x] [ref types](https://github.com/WebAssembly/reference-types/blob/master/proposals/reference-types/Overview.md), [func refs](https://github.com/WebAssembly/function-references/blob/main/proposals/function-references/Overview.md)
-* [x] [gc](https://github.com/WebAssembly/gc)
-* [ ] [exceptions](https://github.com/WebAssembly/exception-handling)
-* [ ] [memory64](https://github.com/WebAssembly/memory64)
-* [ ] [annotations](https://github.com/WebAssembly/annotations), [code_metadata](https://github.com/WebAssembly/tool-conventions/blob/main/CodeMetadata.md)
-* [ ] [js strings](https://github.com/WebAssembly/js-string-builtins/blob/main/proposals/js-string-builtins/Overview.md)
+* [x] [ref types](https://github.com/WebAssembly/reference-types/blob/master/proposals/reference-types/Overview.md), [func refs](https://github.com/WebAssembly/function-references/blob/main/proposals/function-references/Overview.md), [gc](https://github.com/WebAssembly/gc)
+* [x] [annotations](https://github.com/WebAssembly/annotations), [code_metadata](https://github.com/WebAssembly/tool-conventions/blob/main/CodeMetadata.md)
+* [ ] [exceptions](https://github.com/WebAssembly/exception-handling), [memory64](https://github.com/WebAssembly/memory64), [js strings](https://github.com/WebAssembly/js-string-builtins/blob/main/proposals/js-string-builtins/Overview.md), wide arithmetic, threads, custom page size, wasm 3
 
 ## Alternatives
 
   | Size (gzipped) | Performance
 ---|---|---
-watr | 6.2 kb | 11.6 op/s
-[spec/wast.js](https://github.com/WebAssembly/spec/tree/main/interpreter#javascript-library) | 216 kb | 7.1 op/s
-[wabt](https://github.com/WebAssembly/wabt) | 282 kb | 2.3 op/s
-[wat-compiler](https://github.com/stagas/wat-compiler) | 7.7 kb | 1.34 op/s
+watr | 7.5 kb | 6.0 op/s
+[spec/wast.js](https://github.com/WebAssembly/spec/tree/main/interpreter#javascript-library) | 216 kb | 2.2 op/s
+[wabt](https://github.com/WebAssembly/wabt) | 282 kb | 1.2 op/s
+[wat-compiler](https://github.com/stagas/wat-compiler) | 7.7 kb | 0.7 op/s
 
 <!--
 ## Projects using watr

package/src/compile.js

@@ -1,12 +1,14 @@
 import * as encode from './encode.js'
 import { uleb, i32, i64 } from './encode.js'
-import { SECTION, TYPE, KIND, INSTR, HEAPTYPE, DEFTYPE, RECTYPE, REFTYPE } from './const.js'
+import { SECTION, TYPE, KIND, INSTR, HEAPTYPE, DEFTYPE, RECTYPE, REFTYPE, ESCAPE } from './const.js'
 import parse from './parse.js'
-import { clone, err } from './util.js'
+import { clone, err, str } from './util.js'
 
 // build instructions index
 INSTR.forEach((op, i) => INSTR[op] = i >= 0x133 ? [0xfd, i - 0x133] : i >= 0x11b ? [0xfc, i - 0x11b] : i >= 0xfb ? [0xfb, i - 0xfb] : [i]);
 
+// recursively strip all annotation nodes from AST, except @custom and @metadata.code.*
+const unannot = (node) => Array.isArray(node) ? (node[0]?.[0] === '@' && node[0] !== '@custom' && !node[0]?.startsWith?.('@metadata.code.') ? null : node.map(unannot).filter(n => n != null)) : node
 
 /**
  * Converts a WebAssembly Text Format (WAT) tree to a WebAssembly binary format (WASM).
@@ -20,6 +22,9 @@ export default function watr(nodes) {
   if (typeof nodes === 'string') nodes = parse(nodes);
   else nodes = clone(nodes)
 
+  // strip annotations (text-format only), except @custom which becomes binary custom sections
+  nodes = unannot(nodes) || []
+
   // module abbr https://webassembly.github.io/spec/core/text/modules.html#id10
   if (nodes[0] === 'module') nodes.shift(), nodes[0]?.[0] === '$' && nodes.shift()
   // single node, not module
@@ -28,12 +33,12 @@ export default function watr(nodes) {
   // binary abbr "\00" "\0x61" ...
   if (nodes[0] === 'binary') {
     nodes.shift()
-    return Uint8Array.from(str(nodes.map(i => i.slice(1, -1)).join('')))
+    return Uint8Array.from(str(...nodes))
   }
   // quote "a" "b"
   else if (nodes[0] === 'quote') {
     nodes.shift()
-    return watr(nodes.map(i => i.slice(1, -1)).join(''))
+    return watr(nodes.map(s => s.slice(1, -1)).join(''))
   }
 
   // scopes are aliased by key as well, eg. section.func.$name = section[SECTION.func] = idx
@@ -48,7 +53,7 @@ export default function watr(nodes) {
       // convert rec type into regular type (first subtype) with stashed subtypes length
       // add rest of subtypes as regular type nodes with subtype flag
       for (let i = 0; i < node.length; i++) {
-        let [,...subnode] = node[i]
+        let [, ...subnode] = node[i]
         alias(subnode, ctx.type);
         (subnode = typedef(subnode, ctx)).push(i ? true : [ctx.type.length, node.length])
         ctx.type.push(subnode)
@@ -62,64 +67,75 @@ export default function watr(nodes) {
       alias(node, ctx.type);
       ctx.type.push(typedef(node, ctx));
     }
+    // (@custom "name" placement? data)
+    else if (kind === '@custom') {
+      ctx.custom.push(node)  // node is just the arguments, not including @custom
+    }
     // other sections may have id
     else if (kind === 'start' || kind === 'export') ctx[kind].push(node)
 
     else return true
   })
 
-  // prepare/normalize nodes
-  .forEach(([kind, ...node]) => {
-    let imported // if node needs to be imported
+    // prepare/normalize nodes
+    .forEach(([kind, ...node]) => {
+      let imported // if node needs to be imported
 
-    // import abbr
-    // (import m n (table|memory|global|func id? type)) -> (table|memory|global|func id? (import m n) type)
-    if (kind === 'import') [kind, ...node] = (imported = node).pop()
+      // import abbr
+      // (import m n (table|memory|global|func id? type)) -> (table|memory|global|func id? (import m n) type)
+      if (kind === 'import') [kind, ...node] = (imported = node).pop()
 
-    // index, alias
-    let items = ctx[kind];
-    let name = alias(node, items);
+      // index, alias
+      let items = ctx[kind];
+      let name = alias(node, items);
 
-    // export abbr
-    // (table|memory|global|func id? (export n)* ...) -> (table|memory|global|func id ...) (export n (table|memory|global|func id))
-    while (node[0]?.[0] === 'export') ctx.export.push([node.shift()[1], [kind, items.length]])
+      // export abbr
+      // (table|memory|global|func id? (export n)* ...) -> (table|memory|global|func id ...) (export n (table|memory|global|func id))
+      while (node[0]?.[0] === 'export') ctx.export.push([node.shift()[1], [kind, items?.length]])
 
-    // for import nodes - redirect output to import
-    if (node[0]?.[0] === 'import') [, ...imported] = node.shift()
+      // for import nodes - redirect output to import
+      if (node[0]?.[0] === 'import') [, ...imported] = node.shift()
 
-    // table abbr
-    if (kind === 'table') {
-      // (table id? reftype (elem ...{n})) -> (table id? n n reftype) (elem (table id) (i32.const 0) reftype ...)
-      if (node[1]?.[0] === 'elem') {
-        let [reftype, [, ...els]] = node
-        node = [els.length, els.length, reftype]
-        ctx.elem.push([['table', name || items.length], ['i32.const', '0'], reftype, ...els])
+      // table abbr
+      if (kind === 'table') {
+        // (table id? reftype (elem ...{n})) -> (table id? n n reftype) (elem (table id) (i32.const 0) reftype ...)
+        if (node[1]?.[0] === 'elem') {
+          let [reftype, [, ...els]] = node
+          node = [els.length, els.length, reftype]
+          ctx.elem.push([['table', name || items.length], ['i32.const', '0'], reftype, ...els])
+        }
       }
-    }
 
-    // data abbr
-    // (memory id? (data str)) -> (memory id? n n) (data (memory id) (i32.const 0) str)
-    else if (kind === 'memory' && node[0]?.[0] === 'data') {
-      let [, ...data] = node.shift(), m = '' + Math.ceil(data.map(s => s.slice(1, -1)).join('').length / 65536) // FIXME: figure out actual data size
-      ctx.data.push([['memory', items.length], ['i32.const', 0], ...data])
-      node = [m, m]
-    }
+      // data abbr
+      // (memory id? (data str)) -> (memory id? n n) (data (memory id) (i32.const 0) str)
+      else if (kind === 'memory' && node[0]?.[0] === 'data') {
+        let [, ...data] = node.shift(), m = '' + Math.ceil(data.map(s => s.slice(1, -1)).join('').length / 65536) // FIXME: figure out actual data size
+        ctx.data.push([['memory', items.length], ['i32.const', 0], ...data])
+        node = [m, m]
+      }
 
-    // dupe to code section, save implicit type
-    else if (kind === 'func') {
-      let [idx, param, result] = typeuse(node, ctx);
-      idx ??= regtype(param, result, ctx)
+      // dupe to code section, save implicit type
+      else if (kind === 'func') {
+        let [idx, param, result] = typeuse(node, ctx);
+        idx ??= regtype(param, result, ctx)
 
-      // we save idx because type can be defined after
-      !imported && ctx.code.push([[idx, param, result], ...plain(node, ctx)]) // pass param since they may have names
-      node.unshift(['type', idx])
-    }
+        // we save idx because type can be defined after
+        !imported && ctx.code.push([[idx, param, result], ...plain(node, ctx)]) // pass param since they may have names
+        node.unshift(['type', idx])
+      }
+
+      // tag has a type similar to func
+      else if (kind === 'tag') {
+        let [idx, param] = typeuse(node, ctx);
+        idx ??= regtype(param, [], ctx)
+        node.unshift(['type', idx])
+      }
 
-    // import writes to import section amd adds placeholder for (kind) section
-    if (imported) ctx.import.push([...imported, [kind, ...node]]), node = null
+      // import writes to import section amd adds placeholder for (kind) section
+      if (imported) ctx.import.push([...imported, [kind, ...node]]), node = null
 
-    items.push(node)
-  })
+      items?.push(node)
+    })
 
   // convert nodes to bytes
   const bin = (kind, count = true) => {
@@ -128,11 +144,14 @@ export default function watr(nodes) {
       .map(item => build[kind](item, ctx))
       .filter(Boolean)  // filter out unrenderable things (subtype or data.length)
 
+    // Custom sections - each is output as separate section with own header
+    if (kind === SECTION.custom) return items.flatMap(content => [kind, ...vec(content)])
+
     return !items.length ? [] : [kind, ...vec(count ? vec(items) : items)]
   }
 
   // build final binary
-  return Uint8Array.from([
+  const out = [
     0x00, 0x61, 0x73, 0x6d, // magic
     0x01, 0x00, 0x00, 0x00, // version
     ...bin(SECTION.custom),
@@ -141,20 +160,35 @@ export default function watr(nodes) {
     ...bin(SECTION.func),
     ...bin(SECTION.table),
     ...bin(SECTION.memory),
+    ...bin(SECTION.tag),
     ...bin(SECTION.global),
     ...bin(SECTION.export),
     ...bin(SECTION.start, false),
     ...bin(SECTION.elem),
     ...bin(SECTION.datacount, false),
-    ...bin(SECTION.code),
-    ...bin(SECTION.data)
-  ])
+  ]
+
+  // Build code section first (populates ctx.meta)
+  const codeSection = bin(SECTION.code)
+
+  // Build code metadata custom sections: metadata.code.<type>
+  for (const type in ctx.meta) {
+    const name = vec(str(`"metadata.code.${type}"`))
+    const content = vec(ctx.meta[type].map(([funcIdx, instances]) =>
+      [...uleb(funcIdx), ...vec(instances.map(([pos, data]) => [...uleb(pos), ...vec(str(data))]))]
+    ))
+    out.push(0, ...vec([...name, ...content]))
+  }
+
+  out.push(...codeSection, ...bin(SECTION.data))
+
+  return Uint8Array.from(out)
 }
 
 // consume name eg. $t ...
 const alias = (node, list) => {
   let name = (node[0]?.[0] === '$' || node[0]?.[0] == null) && node.shift();
-  if (name) name in list ? err(`Duplicate ${list.name} ${name}`) : list[name] = list.length; // save alias
+  if (name && list) name in list ? err(`Duplicate ${list.name} ${name}`) : list[name] = list.length; // save alias
   return name
 }
 
@@ -179,7 +213,7 @@ const typedef = ([dfn], ctx) => {
 }
 
 // register (implicit) type
-const regtype = (param, result, ctx, idx='$' + param + '>' + result) => (
+const regtype = (param, result, ctx, idx = '$' + param + '>' + result) => (
   (ctx.type[idx] ??= ctx.type.push(['func', [param, result]]) - 1),
   idx
 )
@@ -194,7 +228,7 @@ const typeuse = (nodes, ctx, names) => {
     [, idx] = nodes.shift();
     [param, result] = paramres(nodes, names);
 
-    const [,srcParamRes] = ctx.type[id(idx, ctx.type)] ?? err(`Unknown type ${idx}`)
+    const [, srcParamRes] = ctx.type[id(idx, ctx.type)] ?? err(`Unknown type ${idx}`)
 
     // check type consistency (excludes forward refs)
     if ((param.length || result.length) && srcParamRes.join('>') !== param + '>' + result) err(`Type ${idx} mismatch`)
@@ -259,10 +293,20 @@ const blocktype = (nodes, ctx) => {
 // https://webassembly.github.io/spec/core/text/instructions.html#folded-instructions
 const plain = (nodes, ctx) => {
   let out = [], stack = [], label
+  // helper: check if node is immediate (not array operand)
+  const isImm = n => typeof n === 'string' || typeof n === 'number'
 
   while (nodes.length) {
     let node = nodes.shift()
 
+    // code metadata annotations - pass through as marker with metadata type and data
+    // (@metadata.code.<type> data:str)
+    if (Array.isArray(node) && node[0]?.startsWith?.('@metadata.code.')) {
+      let type = node[0].slice(15) // remove '@metadata.code.' prefix
+      out.push(['@metadata', type, node[1]])
+      continue
+    }
+
     // lookup is slower than sequence of known ifs
     if (typeof node === 'string') {
       out.push(node)
@@ -278,7 +322,7 @@ const plain = (nodes, ctx) => {
       // else $label
       // end $label - make sure it matches block label
       else if (node === 'else' || node === 'end') {
-        if (nodes[0]?.[0] === '$') (node === 'end' ? stack.pop() : label) !== (label = nodes.shift()) && err(`Mismatched label ${label}`)
+        if (nodes[0]?.[0] === '$') (node === 'end' ? stack.pop() : label) !== (label = nodes.shift()) && err(`Mismatched ${node} label ${label}`)
       }
 
       // select (result i32 i32 i32)?
@@ -297,6 +341,18 @@ const plain = (nodes, ctx) => {
       // mark datacount section as required
       else if (node === 'memory.init' || node === 'data.drop' || node === 'array.new_data' || node === 'array.init_data') {
         ctx.datacount[0] = true
+        // memory.init memidx? dataidx
+        if (node === 'memory.init') out.push(isImm(nodes[1]) ? nodes.shift() : 0, isImm(nodes[0]) ? nodes.shift() : 0)
+      }
+
+      // memory.* memidx? - multi-memory proposal
+      else if (node === 'memory.size' || node === 'memory.grow' || node === 'memory.fill') {
+        out.push(isImm(nodes[0]) ? nodes.shift() : 0)
+      }
+
+      // memory.copy dstmem? srcmem?
+      else if (node === 'memory.copy') {
+        out.push(isImm(nodes[0]) ? nodes.shift() : 0, isImm(nodes[0]) ? nodes.shift() : 0)
       }
 
       // table.init tableidx? elemidx -> table.init tableidx elemidx
@@ -319,6 +375,9 @@ const plain = (nodes, ctx) => {
 
       // (if ...) -> if ... end
       else if (node[0] === 'if') {
+        // Pop pending metadata (branch_hint) if present
+        let meta = out[out.length - 1]?.[0] === '@metadata' && out.pop()
+
         let then = [], els = [], immed = [node.shift()]
         // (if label? blocktype? cond*? (then instr*) (else instr*)?) -> cond*? if label? blocktype? instr* else instr*? end
         // https://webassembly.github.io/spec/core/text/instructions.html#control-instructions
@@ -338,7 +397,8 @@ const plain = (nodes, ctx) => {
 
         if (typeof node[0] === 'string') err('Unfolded condition')
 
-        out.push(...plain(node, ctx), ...immed, ...then, ...els, 'end')
+        // conditions, metadata (if any), if, then, else, end
+        out.push(...plain(node, ctx), ...(meta ? [meta] : []), ...immed, ...then, ...els, 'end')
       }
       else out.push(plain(node, ctx))
     }
@@ -349,7 +409,21 @@ const plain = (nodes, ctx) => {
 
 
 // build section binary [by section codes] (non consuming)
-const build = [,
+const build = [
+  // (@custom "name" placement? data)
+  // placement is optional: (before|after section) or (before first)|(after last)
+  // For now we ignore placement and just output the custom section
+  ([name, ...rest], ctx) => {
+    // Check if second arg is placement directive
+    let data = rest
+    if (rest[0]?.[0] === 'before' || rest[0]?.[0] === 'after') {
+      // Skip placement for now - would need more complex section ordering
+      data = rest.slice(1)
+    }
+
+    // Custom section format: name (vec string) + raw content bytes
+    return [...vec(str(name)), ...str(...data)]
+  },
   // type kinds
   // (func params result)
   // (array i8)
@@ -392,6 +466,10 @@ const build = [,
       let [[, typeidx]] = dfn
       details = uleb(id(typeidx, ctx.type))
     }
+    else if (kind === 'tag') {
+      let [[, typeidx]] = dfn
+      details = [0x00, ...uleb(id(typeidx, ctx.type))]
+    }
     else if (kind === 'memory') {
       details = limits(dfn)
     }
@@ -403,7 +481,7 @@ const build = [,
     }
     else err(`Unknown kind ${kind}`)
 
-    return ([...vec(str(mod.slice(1, -1))), ...vec(str(field.slice(1, -1))), KIND[kind], ...details])
+    return ([...vec(str(mod)), ...vec(str(field)), KIND[kind], ...details])
   },
 
   // (func $name? ...params result ...body)
@@ -422,7 +500,7 @@ const build = [,
   ([t, init], ctx) => [...fieldtype(t, ctx), ...expr(init, ctx)],
 
   //  (export "name" (func|table|mem $name|idx))
-  ([nm, [kind, l]], ctx) => ([...vec(str(nm.slice(1, -1))), KIND[kind], ...uleb(id(l, ctx[kind]))]),
+  ([nm, [kind, l]], ctx) => ([...vec(str(nm)), KIND[kind], ...uleb(id(l, ctx[kind]))]),
 
   // (start $main)
   ([l], ctx) => uleb(id(l, ctx.func)),
@@ -523,6 +601,10 @@ const build = [,
     ctx.local.name = 'local'
     ctx.block.name = 'block'
 
+    // Track current code index for code metadata
+    if (ctx._codeIdx === undefined) ctx._codeIdx = 0
+    let codeIdx = ctx._codeIdx++
+
     // collect locals
     while (body[0]?.[0] === 'local') {
       let [, ...types] = body.shift()
@@ -534,10 +616,21 @@ const build = [,
       ctx.local.push(...types)
     }
 
+    ctx._meta = null
     const bytes = []
     while (body.length) bytes.push(...instr(body, ctx))
     bytes.push(0x0b)
 
+    // Extract metadata placeholders (arrays), group by type
+    const metaByType = {}, cleanBytes = []
+    for (const b of bytes)
+      if (Array.isArray(b)) for (const [type, data] of b) (metaByType[type] ??= []).push([cleanBytes.length, data])
+      else cleanBytes.push(b)
+
+    // Store metadata for this function, grouped by type
+    const funcIdx = ctx.import.filter(imp => imp[2][0] === 'func').length + codeIdx
+    for (const type in metaByType) ((ctx.meta ??= {})[type] ??= []).push([funcIdx, metaByType[type]])
+
     // squash locals into (n:u32 t:valtype)*, n is number and t is type
     // we skip locals provided by params
     let loctypes = ctx.local.slice(param.length).reduce((a, type) => (type == a[a.length - 1]?.[1] ? a[a.length - 1][0]++ : a.push([1, type]), a), [])
@@ -546,7 +639,7 @@ const build = [,
     ctx.local = ctx.block = null
 
     // https://webassembly.github.io/spec/core/binary/modules.html#code-section
-    return vec([...vec(loctypes.map(([n, t]) => [...uleb(n), ...reftype(t, ctx)])), ...bytes])
+    return vec([...vec(loctypes.map(([n, t]) => [...uleb(n), ...reftype(t, ctx)])), ...cleanBytes])
   },
 
   // (data (i32.const 0) "\aa" "\bb"?)
@@ -562,10 +655,10 @@ const build = [,
     }
 
     // (offset (i32.const 0)) or (i32.const 0)
-    if (typeof inits[0] !== 'string') {
+    if (typeof inits[0] !== 'string' && inits[0]) {
       offset = inits.shift()
-      if (offset[0] === 'offset') [, offset] = offset
-      offset ?? err('Bad offset', offset)
+      if (offset?.[0] === 'offset') [, offset] = offset
+      else offset ?? err('Bad offset', offset)
     }
 
     return ([
@@ -577,7 +670,7 @@ const build = [,
             // passive: 1
             [1]
       ),
-      ...vec(str(inits.map(i => i.slice(1, -1)).join('')))
+      ...vec(str(...inits))
     ])
   },
 
@@ -585,6 +678,9 @@ const build = [,
   (nodes, ctx) => uleb(ctx.data.length)
 ]
 
+// (tag $id? (param i32)*) - tags for exception handling
+build[SECTION.tag] = ([[, typeidx]], ctx) => [0x00, ...uleb(id(typeidx, ctx.type))]
+
 // build reftype, either direct absheaptype or wrapped heaptype https://webassembly.github.io/gc/core/binary/types.html#reference-types
 const reftype = (t, ctx) => (
   t[0] === 'ref' ?
@@ -599,17 +695,26 @@ const reftype = (t, ctx) => (
 const fieldtype = (t, ctx, mut = t[0] === 'mut' ? 1 : 0) => [...reftype(mut ? t[1] : t, ctx), mut];
 
 
-
 // consume one instruction from nodes sequence
 const instr = (nodes, ctx) => {
   if (!nodes?.length) return []
 
   let out = [], op = nodes.shift(), immed, code
+  const isImm = n => typeof n === 'string' || typeof n === 'number'
+
+  // Handle code metadata marker - store for next instruction
+  // ['@metadata', type, data]
+  if (op?.[0] === '@metadata') {
+    ;(ctx._meta ??= []).push(op.slice(1))
+    return nodes.length ? instr(nodes, ctx) : []
+  }
 
   // consume group
   if (Array.isArray(op)) {
     immed = instr(op, ctx)
     while (op.length) out.push(...instr(op, ctx))
+    // Insert metadata placeholder before instruction
+    if (ctx._meta) out.push(ctx._meta), ctx._meta = null
     out.push(...immed)
     return out
   }
@@ -632,7 +737,9 @@ const instr = (nodes, ctx) => {
       // array.new_fixed $t n
       else if (code === 8) immed.push(...uleb(nodes.shift()))
       // array.new_data|init_data $t $d
-      else if (code === 9 || code === 18) immed.push(...uleb(id(nodes.shift(), ctx.data)))
+      else if (code === 9 || code === 18) {
+        immed.push(...uleb(id(isImm(nodes[0]) ? nodes.shift() : 0, ctx.data)))
+      }
       // array.new_elem|init_elem $t $e
       else if (code === 10 || code === 19) immed.push(...uleb(id(nodes.shift(), ctx.elem)))
       // array.copy $t $t
@@ -641,7 +748,7 @@ const instr = (nodes, ctx) => {
     // ref.test|cast (ref null? $t|heaptype)
     else if (code >= 20 && code <= 23) {
       let ht = reftype(nodes.shift(), ctx)
-      if (ht[0] !== REFTYPE.ref) immed.push(code = immed.pop()+1) // ref.test|cast (ref null $t) is next op
+      if (ht[0] !== REFTYPE.ref) immed.push(code = immed.pop() + 1) // ref.test|cast (ref null $t) is next op
       if (ht.length > 1) ht.shift() // pop ref
       immed.push(...ht)
     }
@@ -651,7 +758,7 @@ const instr = (nodes, ctx) => {
         ht1 = reftype(nodes.shift(), ctx),
         ht2 = reftype(nodes.shift(), ctx),
         castflags = ((ht2[0] !== REFTYPE.ref) << 1) | (ht1[0] !== REFTYPE.ref)
-        immed.push(castflags, ...uleb(i), ht1.pop(), ht2.pop()) // we take only abstype or
+      immed.push(castflags, ...uleb(i), ht1.pop(), ht2.pop()) // we take only abstype or
     }
   }
 
@@ -661,14 +768,23 @@ const instr = (nodes, ctx) => {
   else if (code == 0xfc) {
     [, code] = immed
 
-    // memory.init idx, data.drop idx,
-    if (code === 0x08 || code === 0x09) {
+    // memory.init memidx dataidx (binary: dataidx memidx)
+    if (code === 0x08) {
+      let m = isImm(nodes[0]) ? nodes.shift() : 0, d = isImm(nodes[0]) ? nodes.shift() : 0
+      immed.push(...uleb(id(d, ctx.data)), ...uleb(id(m, ctx.memory)))
+    }
+    // data.drop idx
+    else if (code === 0x09) {
       immed.push(...uleb(id(nodes.shift(), ctx.data)))
     }
-
-    // memory placeholders
-    if (code == 0x08 || code == 0x0b) immed.push(0)
-    else if (code === 0x0a) immed.push(0, 0)
+    // memory.copy dstmem srcmem
+    else if (code === 0x0a) {
+      immed.push(...uleb(id(isImm(nodes[0]) ? nodes.shift() : 0, ctx.memory)), ...uleb(id(isImm(nodes[0]) ? nodes.shift() : 0, ctx.memory)))
+    }
+    // memory.fill memidx
+    else if (code === 0x0b) {
+      immed.push(...uleb(id(isImm(nodes[0]) ? nodes.shift() : 0, ctx.memory)))
+    }
 
     // elem.drop elemidx
     if (code === 0x0d) {
@@ -848,10 +964,10 @@ const instr = (nodes, ctx) => {
     immed.push(...encode[op.split('.')[0]](nodes.shift()))
   }
 
-  // memory.grow|size $idx - mandatory 0x00
+  // memory.grow|size memidx
   // https://webassembly.github.io/spec/core/binary/instructions.html#memory-instructions
   else if (code == 0x3f || code == 0x40) {
-    immed.push(0)
+    immed.push(...uleb(id(isImm(nodes[0]) ? nodes.shift() : 0, ctx.memory)))
   }
 
   // table.get|set $id
@@ -859,6 +975,9 @@ const instr = (nodes, ctx) => {
     immed.push(...uleb(id(nodes.shift(), ctx.table)))
   }
 
+  // Insert metadata placeholder before instruction in flat form
+  if (ctx._meta) out.push(ctx._meta), ctx._meta = null
+
   out.push(...immed)
 
   return out
@@ -880,10 +999,12 @@ const blockid = (nm, block, i) => (
 // consume align/offset params
 const memarg = (args) => {
   let align, offset, k, v
-  while (args[0]?.includes('=')) [k, v] = args.shift().split('='), k === 'offset' ? offset = +v : k === 'align' ? align = +v : err(`Unknown param ${k}=${v}`)
-
-  if (offset < 0 || offset > 0xffffffff) err(`Bad offset ${offset}`)
-  if (align <= 0 || align > 0xffffffff) err(`Bad align ${align}`)
+  while (args[0]?.includes('=')) {
+    [k, v] = args.shift().split('='), v = v.replaceAll('_', '')
+    k === 'offset' ? offset = +v : k === 'align' ? align = +v : err(`Unknown param ${k}=${v}`)
+  }
+  if ((offset < 0 || offset > 0xffffffff)) err(`Bad offset ${offset}`)
+  if ((align <= 0 || align > 0xffffffff)) err(`Bad align ${align}`)
   if (align) ((align = Math.log2(align)) % 1) && err(`Bad align ${align}`)
   return [align, offset]
 }
@@ -912,20 +1033,5 @@ const limits = (node) => (
 // we put extra condition for index ints for tests complacency
 const parseUint = (v, max = 0xFFFFFFFF) => (typeof v === 'string' && v[0] !== '+' ? (typeof max === 'bigint' ? i64 : i32).parse(v) : typeof v === 'number' ? v : err(`Bad int ${v}`)) > max ? err(`Value out of range ${v}`) : v
 
-
-// escape codes
-const escape = { n: 10, r: 13, t: 9, v: 1, '"': 34, "'": 39, '\\': 92 }
-
-// build string binary
-const str = str => {
-  let res = [], i = 0, c, BSLASH = 92
-  // https://webassembly.github.io/spec/core/text/values.html#strings
-  for (; i < str.length;) {
-    c = str.charCodeAt(i++)
-    res.push(c === BSLASH ? escape[str[i++]] || parseInt(str.slice(i - 1, ++i), 16) : c)
-  }
-  return res
-}
-
 // serialize binary array
 const vec = a => [...uleb(a.length), ...a.flat()]

package/src/const.js

@@ -49,17 +49,19 @@ export const INSTR = [
   // relaxed SIMD instructions
   'i8x16.relaxed_swizzle', 'i32x4.relaxed_trunc_f32x4_s', 'i32x4.relaxed_trunc_f32x4_u', 'i32x4.relaxed_trunc_f64x2_s_zero', 'i32x4.relaxed_trunc_f64x2_u_zero', 'f32x4.relaxed_madd', 'f32x4.relaxed_nmadd', 'f64x2.relaxed_madd', 'f64x2.relaxed_nmadd', 'i8x16.relaxed_laneselect', 'i16x8.relaxed_laneselect', 'i32x4.relaxed_laneselect', 'i64x2.relaxed_laneselect', 'f32x4.relaxed_min', 'f32x4.relaxed_max', 'f64x2.relaxed_min', 'f64x2.relaxed_max', 'i16x8.relaxed_q15mulr_s', 'i16x8.relaxed_dot_i8x16_i7x16_s', 'i32x4.relaxed_dot_i8x16_i7x16_add_s'
 ],
-  SECTION = { custom: 0, type: 1, import: 2, func: 3, table: 4, memory: 5, global: 6, export: 7, start: 8, elem: 9, datacount: 12, code: 10, data: 11 },
+  SECTION = { custom: 0, type: 1, import: 2, func: 3, table: 4, memory: 5, global: 6, tag: 13, export: 7, start: 8, elem: 9, datacount: 12, code: 10, data: 11 },
   RECTYPE = { sub: 0x50, subfinal: 0x4F, rec: 0x4E },
   DEFTYPE = { func: 0x60, struct: 0x5F, array: 0x5E, ...RECTYPE },
-  HEAPTYPE = { nofunc: 0x73, noextern: 0x72, none: 0x71, func: 0x70, extern: 0x6F, any: 0x6E, eq: 0x6D, i31: 0x6C, struct: 0x6B, array: 0x6A },
+  HEAPTYPE = { nofunc: 0x73, noextern: 0x72, noexn: 0x74, none: 0x71, func: 0x70, extern: 0x6F, exn: 0x75, any: 0x6E, eq: 0x6D, i31: 0x6C, struct: 0x6B, array: 0x6A },
   REFTYPE = {
     // absheaptype abbrs
     nullfuncref: HEAPTYPE.nofunc,
     nullexternref: HEAPTYPE.noextern,
+    nullexnref: HEAPTYPE.noexn,
     nullref: HEAPTYPE.none,
     funcref: HEAPTYPE.func,
     externref: HEAPTYPE.extern,
+    exnref: HEAPTYPE.exn,
     anyref: HEAPTYPE.any,
     eqref: HEAPTYPE.eq,
     i31ref: HEAPTYPE.i31,
@@ -70,4 +72,6 @@ export const INSTR = [
     ref: 0x64 /* -0x1c */, refnull: 0x63 /* -0x1d */
   },
   TYPE = { i8: 0x78, i16: 0x77, i32: 0x7f, i64: 0x7e, f32: 0x7d, f64: 0x7c, void: 0x40, v128: 0x7B, ...HEAPTYPE, ...REFTYPE },
-  KIND = { func: 0, table: 1, memory: 2, global: 3 }
+  KIND = { func: 0, table: 1, memory: 2, global: 3, tag: 4 },
+  // WAT escape codes: https://webassembly.github.io/spec/core/text/values.html#strings
+  ESCAPE = { n: 10, r: 13, t: 9, v: 11, '"': 34, "'": 39, '\\': 92 }

package/src/parse.js

@@ -1,5 +1,8 @@
+import { unescape } from "./util.js"
+
 const OPAREN = 40, CPAREN = 41, OBRACK = 91, CBRACK = 93, SPACE = 32, DQUOTE = 34, PERIOD = 46,
-  _0 = 48, _9 = 57, SEMIC = 59, NEWLINE = 32, PLUS = 43, MINUS = 45, COLON = 58, BSLASH = 39
+  _0 = 48, _9 = 57, SEMIC = 59, NEWLINE = 32, PLUS = 43, MINUS = 45, COLON = 58, BACKSLASH = 92, AT = 64
+
 
 /**
  * Parses a wasm text string and constructs a nested array structure (AST).
@@ -17,22 +20,23 @@ export default (str, o={ comments: false }) => {
   )
 
   const parseLevel = () => {
-    for (let c, root, q; i < str.length;) {
+    for (let c, root, q, id; i < str.length;) {
 
       c = str.charCodeAt(i)
       if (q) {
         buf += str[i++]
-        if (str[i-1] === '\\') buf += str[i++]
-        else if (c === DQUOTE) commit(), q = 0
+        if (c === BACKSLASH) buf += str[i++]
+        else if (c === DQUOTE) id && (buf = '$' + unescape(buf)), commit(), q = id = 0
       }
       else if (c === DQUOTE) {
-        commit(), q = c, buf += str[i++]
+        q = c, id = buf == '$', !id && commit(), buf = '"', i++
       }
       else if (c === OPAREN) {
         if (str.charCodeAt(i + 1) === SEMIC) comment = str.slice(i, i = str.indexOf(';)', i) + 2), o.comments && level.push(comment) // (; ... ;)
+        else if (str.charCodeAt(i + 1) === AT) commit(), i += 2, buf = '@', (root = level).push(level = []), parseLevel(), level = root // (@annotid ...)
         else commit(), i++, (root = level).push(level = []), parseLevel(), level = root
       }
-      else if (c === SEMIC) comment = str.slice(i, i = str.indexOf('\n', i) + 1 || str.length), o.comments && level.push(comment)  // ; ...
+      else if (c === SEMIC && str.charCodeAt(i + 1) === SEMIC) comment = str.slice(i, i = str.indexOf('\n', i) + 1 || str.length), o.comments && level.push(comment)  // ;; ...
       else if (c <= SPACE) commit(), i++
       else if (c === CPAREN) return commit(), i++
       else buf += str[i++]

package/src/util.js

@@ -1,3 +1,4 @@
+import { ESCAPE } from './const.js'
 
 export const err = text => { throw Error(text) }
 
@@ -6,3 +7,48 @@ export const clone = items => items.map(item => Array.isArray(item) ? clone(item
 export const sepRE = /^_|_$|[^\da-f]_|_[^\da-f]/i
 
 export const intRE = /^[+-]?(?:0x[\da-f]+|\d+)$/i
+
+// build string binary - convert WAT string to byte array
+const enc = new TextEncoder()
+export const str = (...parts) => {
+  let s = parts.map(s => s[0] === '"' ? s.slice(1, -1) : s).join(''), res = []
+
+  for (let i = 0; i < s.length; i++) {
+    let c = s.charCodeAt(i)
+    if (c === 92) { // backslash
+      let n = s[i + 1]
+      // \u{...} unicode - decode and UTF-8 encode
+      if (n === 'u' && s[i + 2] === '{') {
+        let hex = s.slice(i + 3, i = s.indexOf('}', i + 3))
+        res.push(...enc.encode(String.fromCodePoint(parseInt(hex, 16))))
+        // i now points to '}', loop i++ will move past it
+      }
+      // Named escape
+      else if (ESCAPE[n]) {
+        res.push(ESCAPE[n])
+        i++ // skip the named char, loop i++ will move past backslash
+      }
+      // \xx hex byte (raw byte, not UTF-8 decoded)
+      else {
+        res.push(parseInt(s.slice(i + 1, i + 3), 16))
+        i += 2 // skip two hex digits, loop i++ will complete the skip
+      }
+    }
+    // Multi-byte char - UTF-8 encode
+    else if (c > 255) {
+      res.push(...enc.encode(s[i]))
+    }
+    // Raw byte
+    else res.push(c)
+  }
+  return res
+}
+
+/**
+ * Unescapes a WAT string literal by parsing escapes to bytes, then UTF-8 decoding.
+ * Reuses str() for escape parsing to eliminate duplication.
+ *
+ * @param {string} s - String with quotes and escapes, e.g. '"hello\\nworld"'
+ * @returns {string} Unescaped string without quotes, e.g. 'hello\nworld'
+ */
+export const unescape = s => new TextDecoder().decode(new Uint8Array(str(s)))