substrate-lang 0.10.0 → 0.10.1

package/substrate/host/web/dom.mjs

@@ -10,6 +10,9 @@ const HEARD = 1;
 const IMAGE_LOADED = 2;
 const IMAGE_FAILED = 3;
 
+// The document's node number (std/web/patches.sub).
+const DOCUMENT = 1;
+
 const imageTypes = {
   png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp',
   avif: 'image/avif', bmp: 'image/bmp', svg: 'image/svg+xml',
@@ -17,9 +20,14 @@ const imageTypes = {
 
 export function dom(root) {
   const templates = new Map();
-  const nodes = new Map([[0, root]]);
+  const nodes = new Map([[0, root], [DOCUMENT, root.ownerDocument]]);
   const images = new Map();
-  let loading = 0;
+  const loading = new Map();
+  const counted = (tag, n) => {
+    const k = (loading.get(tag) || 0) + n;
+    if (k === 0) loading.delete(tag);
+    else loading.set(tag, k);
+  };
   let app = null;
   let caller = null;
 
@@ -30,6 +38,73 @@ export function dom(root) {
     return e && e.source === SOURCE ? e.data : null;
   };
 
+  const kinds = ['Node', 'Event', 'NodeList', 'HTMLCollection', 'DOMRectReadOnly', 'DOMTokenList',
+    'CSSStyleDeclaration', 'DOMStringMap', 'ValidityState', 'FileList', 'Blob', 'DataTransfer', 'TouchList', 'Touch',
+    'IntersectionObserverEntry'].map((name) => globalThis[name]).filter((kind) => kind !== undefined);
+  const reachable = (x) => kinds.some((kind) => x instanceof kind);
+
+  function guarded(path, f) {
+    try {
+      return f();
+    } catch (e) {
+      caller.trap(`dom: ${path}: ${e.message}`);
+    }
+  }
+
+  function step(x, name, path) {
+    if (!(name in Object(x))) caller.trap(`dom: ${path}: there is no ${name}`);
+    return guarded(path, () => x[name]);
+  }
+
+  function owner(root, path) {
+    const parts = path.split('.');
+    const last = parts.pop();
+    let x = root;
+    for (let k = 0; k < parts.length; k++) {
+      x = step(x, parts[k], path);
+      if (x === null || x === undefined) return [null, last];
+      if (!reachable(x)) {
+        caller.trap(`dom: ${path}: ${parts.slice(0, k + 1).join('.')} is not one of the page's objects`);
+      }
+    }
+    return [x, last];
+  }
+
+  function walk(root, path) {
+    const [x, last] = owner(root, path);
+    return x === null ? null : step(x, last, path);
+  }
+
+  function read(root, path) {
+    const v = walk(root, path);
+    const plain = v === null || v === undefined || ['number', 'string', 'boolean'].includes(typeof v);
+    if (!plain) caller.trap(`dom: ${path} is not a number, text, or true or false`);
+    return v;
+  }
+
+  function write(root, path, value) {
+    const [x, last] = owner(root, path);
+    if (x === null || !(last in x)) caller.trap(`dom: ${path}: there is no ${last} to set`);
+    guarded(path, () => { x[last] = value; });
+  }
+
+  function call(root, path, args) {
+    const [x, last] = owner(root, path);
+    if (x === null || typeof x[last] !== 'function') caller.trap(`dom: ${path} is not a method`);
+    const result = guarded(path, () => x[last](...args));
+    if (result && typeof result.catch === 'function') result.catch(() => {});
+  }
+
+  const numberOf = (v) => (v === null || v === undefined ? 0 : Number(v));
+  const textOf = (v) => (v === null || v === undefined ? '' : String(v));
+
+  const bits = new DataView(new ArrayBuffer(8));
+  const float64 = (low, high) => {
+    bits.setUint32(0, low, true);
+    bits.setUint32(4, high, true);
+    return bits.getFloat64(0, true);
+  };
+
   const listener = (e) => {
     const messages = e.currentTarget.subListeners;
     if (messages && e.type in messages) give(e, messages[e.type]);
@@ -66,12 +141,27 @@ export function dom(root) {
 
   const windowTarget = (type) => (type === 'pointerlockchange' || type === 'pointerlockerror' ? document : window);
 
+  const watched = new Map();
+  let observer = null;
+
+  function watch(node, message) {
+    observer ||= new IntersectionObserver((entries) => {
+      for (const entry of entries) if (watched.has(entry.target)) give(entry, watched.get(entry.target));
+    });
+    watched.set(node, message);
+    observer.observe(node);
+  }
+
   const unlisten = (id) => {
     const n = nodes.get(id);
     if (n instanceof Node && n.subListeners) {
       for (const message of Object.values(n.subListeners)) caller.forget(message);
       n.subListeners = null;
     }
+    if (watched.has(n)) {
+      observer.unobserve(n);
+      watched.delete(n);
+    }
     for (const { type, message, handler } of windowListeners.get(id) || []) {
       windowTarget(type).removeEventListener(type, handler);
       caller.forget(message);
@@ -260,68 +350,75 @@ export function dom(root) {
           const node = nodes.get(w[i + 1]);
           const type = string(i + 2);
           (node.subListeners ||= {})[type] = w[i + 4];
-          node.addEventListener(type, listener);
+          if (type === 'visibility') watch(node, w[i + 4]);
+          else node.addEventListener(type, listener);
           i += 5;
           break;
         }
-        case 10: {
-          const node = nodes.get(w[i + 1]);
-          after.push(() => node.focus());
-          i += 2;
-          break;
-        }
-        case 11: {
-          const node = nodes.get(w[i + 1]);
-          after.push(() => { node.scrollTop = node.scrollHeight; });
-          i += 2;
-          break;
-        }
-        case 12:
+        case 10:
           listenWindow(w[i + 1], string(i + 2), w[i + 4]);
           i += 5;
           break;
-        case 15: {
-          const node = nodes.get(w[i + 1]);
-          if (w[i + 2] !== 0) {
-            after.push(() => { const p = node.requestPointerLock(); if (p && p.catch) p.catch(() => {}); });
-          } else {
-            after.push(() => document.exitPointerLock());
-          }
-          i += 3;
+        case 11: {
+          const canvas = nodes.get(w[i + 1]);
+          const count = w[i + 2];
+          const f = new Float32Array(w.buffer, w.byteOffset, w.length);
+          draw(canvas.getContext('2d'), w, f, i + 3, i + 3 + count, string);
+          i += 3 + count;
           break;
         }
-        case 14: {
+        case 12: {
           const name = string(i + 2);
           const image = new Image();
           const bytes = app.files.get(resolvePath(app.cwd, name));
           const type = imageTypes[name.slice(name.lastIndexOf('.') + 1).toLowerCase()] || '';
           const url = bytes ? URL.createObjectURL(new Blob([bytes], { type })) : name;
           const id = w[i + 1];
+          const tag = w[i + 4];
           const finished = () => {
-            loading--;
+            counted(tag, -1);
             if (bytes) URL.revokeObjectURL(url);
           };
-          loading++;
+          counted(tag, 1);
           image.onload = () => {
             finished();
-            caller.event(IMAGE_LOADED, id, 0, 0);
+            caller.event(IMAGE_LOADED, id, tag, 0);
           };
           image.onerror = () => {
             finished();
             console.error(`dom: cannot load the image ${name}`);
-            caller.event(IMAGE_FAILED, id, 0, errors.missing, utf8.encode(`cannot load the image ${name}`));
+            caller.event(IMAGE_FAILED, id, tag, errors.missing, utf8.encode(`cannot load the image ${name}`));
           };
           image.src = url;
           images.set(w[i + 1], image);
-          i += 4;
+          i += 5;
           break;
         }
         case 13: {
-          const canvas = nodes.get(w[i + 1]);
-          const count = w[i + 2];
-          const f = new Float32Array(w.buffer, w.byteOffset, w.length);
-          draw(canvas.getContext('2d'), w, f, i + 3, i + 3 + count, string);
-          i += 3 + count;
+          const style = document.createElement('style');
+          style.textContent = string(i + 1);
+          root.ownerDocument.head.appendChild(style);
+          i += 3;
+          break;
+        }
+        case 14: {
+          const node = nodeOf(w[i + 1]);
+          const path = string(i + 2);
+          const value = w[i + 4] === 0 ? float64(w[i + 5], w[i + 6]) : string(i + 5);
+          after.push(() => write(node, path, value));
+          i += 7;
+          break;
+        }
+        case 15: {
+          const node = nodeOf(w[i + 1]);
+          const path = string(i + 2);
+          const args = [];
+          for (let k = 0; k < w[i + 4]; k++) {
+            const at = i + 5 + 3 * k;
+            args.push(w[at] === 0 ? float64(w[at + 1], w[at + 2]) : string(at + 1));
+          }
+          after.push(() => call(node, path, args));
+          i += 5 + 3 * w[i + 4];
           break;
         }
         default:
@@ -340,45 +437,49 @@ export function dom(root) {
     caller = theCaller;
     app = theApp;
     const given = (s, out) => caller.give(utf8.encode(s), out);
+    const current = () => {
+      const e = event();
+      if (!e) caller.trap('dom: there is no current event');
+      return e;
+    };
+    const known = (id) => {
+      if (!nodes.has(id)) caller.trap(`dom: there is no node ${id}`);
+      return nodeOf(id);
+    };
     return {
       source: SOURCE,
       apply(ptr, length) {
         apply(caller.memory(), caller.u(ptr), length);
       },
-      event_value(out) {
-        const e = event();
-        const target = e && e.target;
-        return given(target && typeof target.value === 'string' ? target.value : '', out);
+      event_number(ptr, length) {
+        return numberOf(read(current(), caller.string(ptr, length)));
       },
-      event_key(out) {
-        const e = event();
-        return given(e && typeof e.key === 'string' ? e.key : '', out);
+      event_text(ptr, length, out) {
+        return given(textOf(read(current(), caller.string(ptr, length))), out);
       },
-      event_flags() {
-        const e = event();
-        if (!e) return 0;
-        return (e.shiftKey ? 1 : 0) | (e.ctrlKey ? 2 : 0) | (e.altKey ? 4 : 0) | (e.metaKey ? 8 : 0) |
-          (e.target && e.target.checked === true ? 16 : 0) | (document.pointerLockElement ? 32 : 0);
+      event_call(ptr, length) {
+        call(current(), caller.string(ptr, length), []);
       },
-      event_number(which) {
-        const e = event();
-        if (!e) return 0;
-        switch (which) {
-          case 0: return e.timeStamp || 0;
-          case 1: return e.offsetX || 0;
-          case 2: return e.offsetY || 0;
-          case 3: return e.movementX || 0;
-          case 4: return e.movementY || 0;
-          case 5: return e.button || 0;
-          default: return 0;
-        }
+      event_is(node, ptr, length) {
+        return walk(current(), caller.string(ptr, length)) === known(node) ? 1 : 0;
+      },
+      read_number(node, ptr, length) {
+        return numberOf(read(known(node), caller.string(ptr, length)));
+      },
+      read_text(node, ptr, length, out) {
+        return given(textOf(read(known(node), caller.string(ptr, length))), out);
+      },
+      is(node, from, ptr, length) {
+        return walk(known(from), caller.string(ptr, length)) === known(node) ? 1 : 0;
       },
-      images_loading() {
-        return loading;
+      images_loading(tag) {
+        return loading.get(tag) || 0;
       },
-      prevent_default() {
-        const e = event();
-        if (e && e.preventDefault) e.preventDefault();
+      element(ptr, length, node) {
+        const found = root.ownerDocument.getElementById(caller.string(ptr, length));
+        if (!found) return 0;
+        nodes.set(node, found);
+        return 1;
       },
     };
   };

package/substrate/host/web/dom.sub

@@ -1,34 +1,16 @@
-;; The page: the host module "dom". A heard event carries the id and tag its listener was given. dom-event-flags gives
-;; the bits dom-shift to dom-locked. dom-event-number takes one of dom-time, dom-x, dom-y, dom-movement-x,
-;; dom-movement-y and dom-button, and gives that number for the current event.
-(provide dom-source dom-heard dom-image-loaded dom-image-failed
-         dom-shift dom-control dom-alt dom-meta dom-checked dom-locked
-         dom-time dom-x dom-y dom-movement-x dom-movement-y dom-button
-         dom-apply dom-event-value dom-event-key dom-event-flags dom-event-number dom-prevent-default dom-images-loading)
+;; The page: the host module "dom". A heard event carries the id and tag its listener was given. A visibility listener
+;; hears when its element comes into the viewport or leaves it. dom-bind-element gives the element with an id a node
+;; number, for dom-element (std/web/dom.sub). The reads of the page are in std/web/dom.sub too. dom-images-loading
+;; counts the images loading for a tag.
+(provide dom-source dom-heard dom-image-loaded dom-image-failed dom-apply dom-bind-element dom-images-loading)
 
 (const dom-source u32 1)
 (const dom-heard u32 1)
 (const dom-image-loaded u32 2)
 (const dom-image-failed u32 3)
 
-(const dom-shift u32 1)
-(const dom-control u32 2)
-(const dom-alt u32 4)
-(const dom-meta u32 8)
-(const dom-checked u32 16)
-(const dom-locked u32 32)
-
-(const dom-time i32 0)
-(const dom-x i32 1)
-(const dom-y i32 2)
-(const dom-movement-x i32 3)
-(const dom-movement-y i32 4)
-(const dom-button i32 5)
-
 (import dom-apply "dom" "apply" (i32 i32 ->))
-(import dom-event-value "dom" "event_value" (i32 -> i32))
-(import dom-event-key "dom" "event_key" (i32 -> i32))
-(import dom-event-flags "dom" "event_flags" (-> i32))
-(import dom-event-number "dom" "event_number" (i32 -> f64))
-(import dom-prevent-default "dom" "prevent_default" (->))
-(import dom-images-loading "dom" "images_loading" (-> i32))
+(import images-loading "dom" "images_loading" (i32 -> i32))
+(import dom-bind-element "dom" "element" (i32 i32 i32 -> i32))
+
+(define (dom-images-loading [tag (ptr void)]) -> u32 (cast u32 (images-loading (cast i32 tag))))

package/substrate/host/web/gpu.mjs

@@ -39,6 +39,8 @@ function unavailable(reason) {
     source: SOURCE,
     apply() { caller.trap(`gpu: WebGPU is not available: ${reason}`); },
     loading() { return 0; },
+    listen() { return 0; },
+    unlisten() {},
   });
   module.available = false;
   module.adapter = {};
@@ -71,17 +73,31 @@ export async function gpu(options = {}) {
   const layered = new Map();
   const bindGroups = new Map();
   const tables = { 1: surfaces, 2: shaders, 3: pipelines, 4: buffers, 5: textures, 6: samplers, 7: layouts, 8: bindGroups };
-  let loading = 0;
+  const loading = new Map();
+  const counted = (t, n) => {
+    const k = (loading.get(t) || 0) + n;
+    if (k === 0) loading.delete(t);
+    else loading.set(t, k);
+  };
 
   let app = null;
   let caller = null;
-  function event(kind, id, data) {
-    if (caller) caller.event(kind, id, 0, kind === ERROR ? errors.invalid : 0, data);
+  function event(kind, id, data, to = 0) {
+    if (caller) caller.event(kind, id, to, kind === ERROR ? errors.invalid : 0, data);
+  }
+  const error = (id, message, to = 0) => event(ERROR, id, utf8.encode(message), to);
+
+  let tag = 0;
+  const listeners = new Map();
+  let nextListener = 1;
+
+  function deviceError(message) {
+    if (listeners.size === 0) error(0, message);
+    for (const t of listeners.values()) error(0, message, t);
   }
-  const error = (id, message) => event(ERROR, id, utf8.encode(message));
 
-  device.addEventListener('uncapturederror', (e) => error(0, e.error.message));
-  device.lost.then((info) => error(0, `the device was lost (${info.reason}): ${info.message}`));
+  device.addEventListener('uncapturederror', (e) => deviceError(e.error.message));
+  device.lost.then((info) => deviceError(`the device was lost (${info.reason}): ${info.message}`));
 
   function get(kind, id) {
     const r = tables[kind].get(id);
@@ -100,7 +116,18 @@ export async function gpu(options = {}) {
     return v;
   };
 
-  function run(memory, w, f, string) {
+  function run(memory, w, f, string, batchTag) {
+    tag = batchTag;
+    device.pushErrorScope('validation');
+    try {
+      commands(memory, w, f, string);
+    } finally {
+      tag = 0;
+      device.popErrorScope().then((e) => { if (e) error(0, e.message, batchTag); });
+    }
+  }
+
+  function commands(memory, w, f, string) {
     const encoder = device.createCommandEncoder();
     let pass = null;
     let computing = false;
@@ -137,6 +164,7 @@ export async function gpu(options = {}) {
         }
         case 2: {
           const id = w[i + 1];
+          const to = tag;
           device.pushErrorScope('validation');
           const module = device.createShaderModule({ label: `shader ${id}`, code: string(i + 2) });
           shaders.set(id, module);
@@ -144,7 +172,7 @@ export async function gpu(options = {}) {
             if (!e) return;
             const errors = (await module.getCompilationInfo()).messages.filter((m) => m.type === 'error');
             error(id, errors.length === 0 ? e.message : `shader ${id} does not compile:\n` +
-              errors.map((m) => `  line ${m.lineNum}, column ${m.linePos}: ${m.message}`).join('\n'));
+              errors.map((m) => `  line ${m.lineNum}, column ${m.linePos}: ${m.message}`).join('\n'), to);
           });
           i += 4;
           break;
@@ -246,7 +274,7 @@ export async function gpu(options = {}) {
             usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.COPY_SRC,
           });
           textures.set(id, { texture: placeholder, format: 'rgba8unorm', width: 1, height: 1, layers: 1 });
-          loadTexture(id, name);
+          loadTexture(id, name, tag);
           i += 4;
           break;
         }
@@ -311,7 +339,7 @@ export async function gpu(options = {}) {
             entries.push({ binding: w[i], kind, id: w[i + 2], offset: w[i + 3], size: w[i + 4] });
             i += 5;
           }
-          const description = { id, layout, entries, layers: layoutId !== 0 ? layered.get(layoutId) : new Set() };
+          const description = { id, layout, entries, layers: layoutId !== 0 ? layered.get(layoutId) : new Set(), tag };
           description.group = makeBindGroup(description);
           bindGroups.set(id, description);
           break;
@@ -347,17 +375,19 @@ export async function gpu(options = {}) {
         }
         case 14: {
           const id = w[i + 1];
+          const to = tag;
           const read = readTexture(encoder, id, w[i + 2], w[i + 3], w[i + 4], w[i + 5], w[i + 6], w[i + 7]);
-          reads.push(() => read().then((bytes) => event(PIXELS, id, bytes), (e) => error(id, e.message)));
+          reads.push(() => read().then((bytes) => event(PIXELS, id, bytes, to), (e) => error(id, e.message, to)));
           i += 8;
           break;
         }
         case 15: {
           const id = w[i + 1];
+          const to = tag;
           const len = w[i + 3];
           const staging = device.createBuffer({ size: (len + 3) & ~3, usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ });
           encoder.copyBufferToBuffer(get(4, id), w[i + 2], staging, 0, (len + 3) & ~3);
-          reads.push(() => readStaging(staging, len).then((bytes) => event(BYTES, id, bytes), (e) => error(id, e.message)));
+          reads.push(() => readStaging(staging, len).then((bytes) => event(BYTES, id, bytes, to), (e) => error(id, e.message, to)));
           i += 4;
           break;
         }
@@ -499,10 +529,10 @@ export async function gpu(options = {}) {
     for (const read of reads) read();
   }
 
-  function checked(what, id, make) {
+  function checked(what, id, make, to = tag) {
     device.pushErrorScope('validation');
     const resource = make();
-    device.popErrorScope().then((e) => { if (e) error(id, `${what} is invalid: ${e.message}`); });
+    device.popErrorScope().then((e) => { if (e) error(id, `${what} is invalid: ${e.message}`, to); });
     return resource;
   }
 
@@ -529,8 +559,8 @@ export async function gpu(options = {}) {
     });
   }
 
-  async function loadTexture(id, name) {
-    loading++;
+  async function loadTexture(id, name, to) {
+    counted(to, 1);
     try {
       const bytes = app && app.files.get(resolvePath(app.cwd, name));
       const blob = bytes ? new Blob([bytes]) : await fetch(name).then((r) => {
@@ -564,15 +594,15 @@ export async function gpu(options = {}) {
         if (description.entries.some((e) => e.kind === 3 && e.id === id)) description.group = makeBindGroup(description);
       }
       t.texture.destroy();
-      event(LOADED, id, new Uint8Array(0));
+      event(LOADED, id, new Uint8Array(0), to);
     } catch (e) {
-      error(id, `cannot load the texture ${name}: ${e.message}`);
+      error(id, `cannot load the texture ${name}: ${e.message}`, to);
     } finally {
-      loading--;
+      counted(to, -1);
     }
   }
 
-  function makeBindGroup({ id, layout, entries, layers }) {
+  function makeBindGroup({ id, layout, entries, layers, tag: to }) {
     return checked(`bind group ${id}`, id, () => device.createBindGroup({
       label: `bind group ${id}`,
       layout,
@@ -590,7 +620,7 @@ export async function gpu(options = {}) {
         }
         return { binding: e.binding, resource };
       }),
-    }));
+    }), to);
   }
 
   function readTexture(encoder, id, mip, layer, x, y, width, height) {
@@ -624,17 +654,25 @@ export async function gpu(options = {}) {
     app = theApp;
     return {
       source: SOURCE,
-      apply(ptr, len) {
+      apply(ptr, len, t) {
         const memory = caller.memory();
         const w = ptr % 4 === 0
           ? new Uint32Array(memory.buffer, memory.byteOffset + ptr, len >>> 2)
           : new Uint32Array(memory.slice(ptr, ptr + len).buffer);
         const f = new Float32Array(w.buffer, w.byteOffset, w.length);
         const string = (at) => text.decode(memory.subarray(w[at], w[at] + w[at + 1]));
-        run(memory, w, f, string);
+        run(memory, w, f, string, t);
+      },
+      loading(t) {
+        return loading.get(t) || 0;
+      },
+      listen(t) {
+        const id = nextListener++;
+        listeners.set(id, t);
+        return id;
       },
-      loading() {
-        return loading;
+      unlisten(id) {
+        listeners.delete(id);
       },
     };
   };

package/substrate/host/web/gpu.sub

@@ -1,5 +1,8 @@
-;; WebGPU: the host module "gpu".
-(provide gpu-source gpu-error gpu-loaded gpu-pixels gpu-bytes gpu-apply gpu-loading)
+;; WebGPU: the host module "gpu". gpu-apply runs a batch of commands, and the events it causes go to its tag: errors,
+;; loaded texture files and finished reads. gpu-loading counts the texture files loading for a tag. Each listener's tag
+;; hears the errors about the whole device, such as its loss. gpu-listen gives the listener's number, and gpu-unlisten
+;; takes it.
+(provide gpu-source gpu-error gpu-loaded gpu-pixels gpu-bytes gpu-apply gpu-loading gpu-listen gpu-unlisten)
 
 (const gpu-source u32 2)
 (const gpu-error u32 1)
@@ -7,5 +10,16 @@
 (const gpu-pixels u32 3)
 (const gpu-bytes u32 4)
 
-(import gpu-apply "gpu" "apply" (i32 i32 ->))
-(import gpu-loading "gpu" "loading" (-> i32))
+(import apply "gpu" "apply" (i32 i32 i32 ->))
+(import loading "gpu" "loading" (i32 -> i32))
+(import listen "gpu" "listen" (i32 -> i32))
+(import unlisten "gpu" "unlisten" (i32 ->))
+
+(define (gpu-apply [commands (slice u8)] [tag (ptr void)])
+  (apply (cast i32 (-> commands items)) (cast i32 (-> commands length)) (cast i32 tag)))
+
+(define (gpu-loading [tag (ptr void)]) -> u32 (cast u32 (loading (cast i32 tag))))
+
+(define (gpu-listen [tag (ptr void)]) -> u32 (cast u32 (listen (cast i32 tag))))
+
+(define (gpu-unlisten [id u32]) (unlisten (cast i32 id)))

package/substrate/host/web/location.mjs

@@ -8,7 +8,12 @@ const CHANGED = 1;
 
 export function locationModule() {
   return (caller) => {
-    const popped = () => caller.event(CHANGED, 0, 0, 0, utf8.encode(globalThis.location.href));
+    const listeners = new Map();
+    let next = 1;
+    const popped = () => {
+      const url = utf8.encode(globalThis.location.href);
+      for (const [id, tag] of listeners) caller.event(CHANGED, id, tag, 0, url);
+    };
     addEventListener('popstate', popped);
     const move = (go, ptr, len, err) => {
       try {
@@ -30,6 +35,15 @@ export function locationModule() {
       back() {
         history.back();
       },
+      listen(tag) {
+        const id = next++;
+        listeners.set(id, tag);
+        return id;
+      },
+      unlisten(id) {
+        listeners.delete(id);
+        caller.forget(id);
+      },
     };
   };
 }

package/substrate/host/web/location.sub

@@ -1,11 +1,15 @@
-;; The page's URL and history: the host module "location". When the user goes back or forward, an untagged changed
-;; event brings the URL as its bytes.
-(provide location-source location-changed location-get location-push location-replace location-back)
+;; The page's URL and history: the host module "location". When the user goes back or forward, each listener's tag
+;; gets a changed event with the URL as its bytes. location-listen gives the listener's number, and location-unlisten
+;; takes it.
+(provide location-source location-changed location-get location-push location-replace location-back location-listen
+         location-unlisten)
 
 (import get "location" "get" (i32 -> i32))
 (import push "location" "push" (i32 i32 i32 -> i32))
 (import replace "location" "replace" (i32 i32 i32 -> i32))
 (import back "location" "back" (->))
+(import listen "location" "listen" (i32 -> i32))
+(import unlisten "location" "unlisten" (i32 ->))
 
 (const location-source u32 12)
 (const location-changed u32 1)
@@ -23,3 +27,7 @@
         (host-failed! (& why) err))))
 
 (define (location-back) (back))
+
+(define (location-listen [tag (ptr void)]) -> u32 (cast u32 (listen (cast i32 tag))))
+
+(define (location-unlisten [id u32]) (unlisten (cast i32 id)))