@markii/host 0.0.0-stage → 0.17.0-next.2

package/dist/browser.d.ts

@@ -0,0 +1,57 @@
+import type { NetProvider } from '@markii/lua';
+import type { HostIsolate } from './host/adapter.js';
+/** Builds the provider for one run from the job's host allowlist, byte cap and pin policy (the policy is meaningless in a browser and ignored). */
+export type BrowserNetProviderFactory = (netAllowlist: string[], maxFetchBytes: number, netPolicy: unknown) => NetProvider;
+export interface FetchNetProviderOptions {
+    /**
+     * The origins (`https://api.example.com`, `http://127.0.0.1:8080`) a
+     * script may reach. Anything else is denied. Missing or empty denies
+     * every request. Entries that do not parse as an http(s) URL are ignored.
+     */
+    allowedOrigins?: readonly string[];
+    /** How a policy refusal is built. Defaults to a plain `Error`; the isolate bridge marks every refusal as a denial on the wire either way. */
+    denial?: (message: string) => Error;
+    /** The `fetch` to use. Defaults to the global one; injectable for tests. */
+    fetch?: typeof fetch;
+}
+/**
+ * The page-side half of the network bridge for a browser: a request goes
+ * out with `fetch` only when its origin is in `allowedOrigins`. Everything
+ * else is refused with a denial before any request is made.
+ *
+ * The grant flow and the tier gate run in front of this (they are shared
+ * with every host), so a script still needs the user's grant for the host
+ * it names. This allowlist is the second, host-owned boundary.
+ *
+ * What a browser cannot do, stated plainly: there is NO address pinning
+ * here. A page cannot choose which IP a hostname connects to, so the
+ * DNS-rebinding and private-range protection the Node provider adds
+ * (docs/security.md) does not exist in this provider. The browser's own
+ * rules apply instead: CORS decides whether a response is readable, and
+ * the same-origin policy stops credentials leaving (requests are sent with
+ * `credentials: 'omit'`). Redirects are not followed: the browser hides a
+ * manual redirect's target, so it cannot be checked against the allowlist,
+ * and a redirect is therefore a denial.
+ *
+ * Returns a factory because the byte cap arrives per job.
+ */
+export declare function createFetchNetProvider(options?: FetchNetProviderOptions): BrowserNetProviderFactory;
+export interface BrowserHostIsolateOptions {
+    /** Where the module worker lives. Defaults to `browser-worker.js` beside this file. A host that embeds the bytes (a blob URL) passes its own. */
+    workerUrl?: string | URL;
+    /** Where wasmoon's `glue.wasm` lives. Defaults to `glue.wasm` beside this file. Sent on every job, so the Lua engine never falls back to a CDN. */
+    wasmUrl?: string | URL;
+    /** How the worker script is loaded. Defaults to `module`, which the packaged `browser-worker.js` is. A host that embeds a classic (IIFE) bundle behind a blob URL passes `classic`. */
+    workerType?: 'module' | 'classic';
+    /** Serves `net.*` for each run. Defaults to a provider with an empty allowlist, which denies every request. */
+    netProvider?: BrowserNetProviderFactory;
+}
+/**
+ * A `HostIsolate` of kind `browser`: each run starts a MODULE Web Worker
+ * and the job carries the `glue.wasm` URL. A Web Worker takes no heap cap,
+ * so a runaway allocation inside it is bounded only by the browser; Lua's
+ * own limits and the external watchdog still apply (docs/security.md).
+ */
+export declare function createBrowserHostIsolate(options?: BrowserHostIsolateOptions): Extract<HostIsolate, {
+    kind: 'browser';
+}>;

package/dist/browser.js

@@ -0,0 +1,167 @@
+// @markii/host/browser: the browser PLATFORM entry, the twin of
+// `@markii/host/node`.
+//
+// The main entry (`./index.ts`) is environment-neutral. This entry adds the
+// two things a page needs to run scripts:
+// - a Web Worker isolate that starts the packaged module worker and hands it
+//   the packaged `glue.wasm` URL on every job;
+// - a `fetch`-backed network provider that serves `net.*` calls on the
+//   worker's behalf, against an explicit allowlist of ORIGINS.
+//
+// Nothing reachable from here imports `node:*` (executed probe:
+// `apps/vscode/src/browser-entry.probe.test.ts`). In the published package
+// `browser-worker.js` and `glue.wasm` sit next to `browser.js`, so the
+// `new URL(..., import.meta.url)` references below resolve in a consumer's
+// bundler without configuration where that bundler treats them as assets.
+import { createBrowserIsolate } from './run/browser-isolate.js';
+function originOf(entry) {
+    try {
+        const url = new URL(entry);
+        if (url.protocol !== 'http:' && url.protocol !== 'https:')
+            return undefined;
+        return url.origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readCapped(response, maxBytes, denial) {
+    const declared = Number(response.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > maxBytes) {
+        void response.body?.cancel();
+        throw denial(`response declares ${declared} bytes, exceeding the ${maxBytes}-byte cap`);
+    }
+    if (!response.body)
+        return '';
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > maxBytes) {
+            void reader.cancel();
+            throw denial(`response exceeds the ${maxBytes}-byte cap`);
+        }
+        chunks.push(value);
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new TextDecoder().decode(bytes);
+}
+/**
+ * The page-side half of the network bridge for a browser: a request goes
+ * out with `fetch` only when its origin is in `allowedOrigins`. Everything
+ * else is refused with a denial before any request is made.
+ *
+ * The grant flow and the tier gate run in front of this (they are shared
+ * with every host), so a script still needs the user's grant for the host
+ * it names. This allowlist is the second, host-owned boundary.
+ *
+ * What a browser cannot do, stated plainly: there is NO address pinning
+ * here. A page cannot choose which IP a hostname connects to, so the
+ * DNS-rebinding and private-range protection the Node provider adds
+ * (docs/security.md) does not exist in this provider. The browser's own
+ * rules apply instead: CORS decides whether a response is readable, and
+ * the same-origin policy stops credentials leaving (requests are sent with
+ * `credentials: 'omit'`). Redirects are not followed: the browser hides a
+ * manual redirect's target, so it cannot be checked against the allowlist,
+ * and a redirect is therefore a denial.
+ *
+ * Returns a factory because the byte cap arrives per job.
+ */
+export function createFetchNetProvider(options = {}) {
+    const allowed = new Set((options.allowedOrigins ?? [])
+        .map(originOf)
+        .filter((origin) => origin !== undefined));
+    const denial = options.denial ?? ((message) => new Error(message));
+    return (netAllowlist, maxFetchBytes) => {
+        // The run's granted hosts, re-checked here on the page side: the worker
+        // checks them too, but the worker is the isolate a hostile script runs
+        // in, so the page is the boundary (the same rule the Node provider
+        // follows). A request must pass BOTH this and the origin allowlist.
+        const granted = new Set(netAllowlist.map((host) => host.toLowerCase()));
+        async function request(rawUrl, method, body) {
+            let url;
+            try {
+                url = new URL(rawUrl);
+            }
+            catch {
+                throw denial(`"${rawUrl}" is not a valid URL`);
+            }
+            if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+                throw denial(`scheme "${url.protocol}" is not allowed`);
+            }
+            if (url.username !== '' || url.password !== '') {
+                throw denial(`URL "${rawUrl}" embeds credentials, which is not allowed`);
+            }
+            if (!granted.has(url.hostname.toLowerCase())) {
+                throw denial(`host "${url.hostname}" is not on the run's allowlist`);
+            }
+            if (!allowed.has(url.origin)) {
+                throw denial(`origin "${url.origin}" is not on the host's allowlist`);
+            }
+            const doFetch = options.fetch ?? fetch;
+            let response;
+            try {
+                response = await doFetch(url.href, {
+                    method,
+                    ...(body !== undefined
+                        ? { body, headers: { 'content-type': 'text/plain;charset=UTF-8' } }
+                        : {}),
+                    redirect: 'manual',
+                    credentials: 'omit',
+                    referrerPolicy: 'no-referrer',
+                });
+            }
+            catch (error) {
+                throw denial(`request failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            if (response.type === 'opaqueredirect') {
+                throw denial('redirects are not followed in a browser');
+            }
+            if (response.status >= 300 && response.status < 400) {
+                throw denial('redirects are not followed in a browser');
+            }
+            return {
+                status: response.status,
+                body: await readCapped(response, maxFetchBytes, denial),
+            };
+        }
+        return {
+            get: (url) => request(url, 'GET', undefined),
+            post: (url, requestBody) => request(url, 'POST', requestBody),
+            patch: (url, requestBody) => request(url, 'PATCH', requestBody),
+        };
+    };
+}
+/**
+ * A `HostIsolate` of kind `browser`: each run starts a MODULE Web Worker
+ * and the job carries the `glue.wasm` URL. A Web Worker takes no heap cap,
+ * so a runaway allocation inside it is bounded only by the browser; Lua's
+ * own limits and the external watchdog still apply (docs/security.md).
+ */
+export function createBrowserHostIsolate(options = {}) {
+    const netProvider = options.netProvider ?? createFetchNetProvider({ allowedOrigins: [] });
+    return {
+        kind: 'browser',
+        spawner: async () => {
+            const workerUrl = options.workerUrl ?? new URL('./browser-worker.js', import.meta.url);
+            const wasmUrl = options.wasmUrl ?? new URL('./glue.wasm', import.meta.url);
+            return createBrowserIsolate({
+                createWorker: () => options.workerType === 'classic'
+                    ? new Worker(workerUrl)
+                    : new Worker(workerUrl, { type: 'module' }),
+                netProvider,
+                wasmUri: String(wasmUrl),
+            });
+        },
+        dispose: () => { },
+    };
+}

package/dist/conformance/host/01-plain-open/expected.json

@@ -0,0 +1,5 @@
+{
+  "outcomes": [{ "kind": "opened" }],
+  "diagnostics": [],
+  "prompts": []
+}

package/dist/conformance/host/01-plain-open/note.mk.md

@@ -0,0 +1,8 @@
+# A plain note
+
+Nothing here needs a script or a pack: just markdown and one standard
+component.
+
+::callout{tone=info}
+Nothing to run.
+::

package/dist/conformance/host/01-plain-open/scenario.json

@@ -0,0 +1,6 @@
+{
+  "id": "plain-open",
+  "invariant": "a note with no scripts and no packs opens, renders, and writes no diagnostics",
+  "clock": 1700000000000,
+  "actions": [{ "type": "open" }]
+}

package/dist/conformance/host/02-run-manual-grant-accepted/expected.json

@@ -0,0 +1,16 @@
+{
+  "outcomes": [
+    { "kind": "opened" },
+    {
+      "kind": "ran",
+      "values": { "total": 3 },
+      "failureKinds": [],
+      "traceOk": true
+    }
+  ],
+  "diagnostics": [
+    "manual run: net declaration mismatch",
+    "uses net access to api.example.com"
+  ],
+  "prompts": ["This note's scripts can send data to api.example.com. Allow?"]
+}

package/dist/conformance/host/02-run-manual-grant-accepted/note.mk.md

@@ -0,0 +1,5 @@
+# Manual run, one host, grant accepted
+
+```lua {name=total}
+return net.fetch_json("https://api.example.com/orders")
+```

package/dist/conformance/host/02-run-manual-grant-accepted/scenario.json

@@ -0,0 +1,14 @@
+{
+  "id": "run-manual-grant-accepted",
+  "invariant": "a manual run prompts once, worded with the canonical wording, and a granted host's value lands",
+  "clock": 1700000000000,
+  "actions": [
+    { "type": "open" },
+    {
+      "type": "run",
+      "trigger": "manual",
+      "answers": ["allow"],
+      "simulate": { "name": "total", "value": 3, "requiresHost": "api.example.com" }
+    }
+  ]
+}

package/dist/conformance/host/03-run-manual-grant-refused/expected.json

@@ -0,0 +1,18 @@
+{
+  "outcomes": [
+    { "kind": "opened" },
+    {
+      "kind": "ran",
+      "values": {},
+      "failureKinds": ["capability-denied"],
+      "traceOk": false
+    }
+  ],
+  "diagnostics": [
+    "manual run finished with 1 script failure(s)",
+    "total (capability-denied)",
+    "manual run: net declaration mismatch",
+    "uses net access to api.example.com"
+  ],
+  "prompts": ["This note's scripts can send data to api.example.com. Allow?"]
+}

package/dist/conformance/host/03-run-manual-grant-refused/note.mk.md

@@ -0,0 +1,5 @@
+# Manual run, one host, grant refused
+
+```lua {name=total}
+return net.fetch_json("https://api.example.com/orders")
+```

package/dist/conformance/host/03-run-manual-grant-refused/scenario.json

@@ -0,0 +1,14 @@
+{
+  "id": "run-manual-grant-refused",
+  "invariant": "the same prompt, refused, leaves the host reaching nothing and reports the failure on both surfaces",
+  "clock": 1700000000000,
+  "actions": [
+    { "type": "open" },
+    {
+      "type": "run",
+      "trigger": "manual",
+      "answers": ["deny"],
+      "simulate": { "name": "total", "value": 3, "requiresHost": "api.example.com" }
+    }
+  ]
+}

package/dist/conformance/host/04-run-auto-write-denied/expected.json

@@ -0,0 +1,16 @@
+{
+  "outcomes": [
+    { "kind": "opened" },
+    {
+      "kind": "ran",
+      "values": {},
+      "failureKinds": ["tier-blocked"],
+      "traceOk": false
+    }
+  ],
+  "diagnostics": [
+    "auto run finished with 1 script failure(s)",
+    "counter (tier-blocked)"
+  ],
+  "prompts": []
+}

package/dist/conformance/host/04-run-auto-write-denied/note.mk.md

@@ -0,0 +1,10 @@
+# Auto trigger, a write attempt
+
+Runs on open, on a timer, or manually. This script only ever attempts an
+effect (a write), never a network call, so the tier gate is the only
+thing that can deny it.
+
+```lua {name=counter}
+store.set("counter", 1)
+return store.get("counter")
+```

package/dist/conformance/host/04-run-auto-write-denied/scenario.json

@@ -0,0 +1,13 @@
+{
+  "id": "run-auto-write-denied",
+  "invariant": "an auto trigger is read-only: a write attempt is denied by the tier gate, not by luck, and never prompts",
+  "clock": 1700000000000,
+  "actions": [
+    { "type": "open" },
+    {
+      "type": "run",
+      "trigger": "auto",
+      "simulate": { "name": "counter", "requiresManualTier": true }
+    }
+  ]
+}

package/dist/conformance/host/05-export-html-pack-directive/expected.json

@@ -0,0 +1,14 @@
+{
+  "outcomes": [
+    {
+      "kind": "exported",
+      "contains": ["mk-unknown", "ana_timeline"],
+      "excludes": ["<script"]
+    }
+  ],
+  "diagnostics": [
+    "Export wrote",
+    "Rendered with the static engine because no pack components are loaded"
+  ],
+  "prompts": []
+}

package/dist/conformance/host/05-export-html-pack-directive/note.mk.md

@@ -0,0 +1,8 @@
+# Export with a pack directive
+
+A plain export never loads packs, so this directive from the (not
+installed here) "ana" pack falls back to the unknown-component box.
+
+::ana_timeline
+No timeline data in a plain export.
+::

package/dist/conformance/host/05-export-html-pack-directive/scenario.json

@@ -0,0 +1,6 @@
+{
+  "id": "export-html-pack-directive",
+  "invariant": "a pack directive the host did not load exports as the unknown-component fallback, and the export excludes script machinery",
+  "clock": 1700000000000,
+  "actions": [{ "type": "exportHtml" }]
+}

package/dist/conformance/host/06-install-pack-then-render/expected.json

@@ -0,0 +1,18 @@
+{
+  "outcomes": [
+    { "kind": "opened" },
+    { "kind": "installed", "namespace": "ana", "replaced": false },
+    { "kind": "loaded", "namespaces": ["ana"] },
+    { "kind": "installed", "namespace": "ana", "replaced": true }
+  ],
+  "diagnostics": [
+    "Install pack from file installed pack \"ana\" from \"files/ana-1.0.0\"",
+    "Loaded pack \"ana\" (namespace: ana, 1 component)",
+    "replacing the previous install"
+  ],
+  "prompts": [
+    "Installing \"ana\" lets its code run inside",
+    "Installing \"ana\" lets its code run inside",
+    "A pack named \"ana\" is already installed. Replacing it removes the installed copy and cannot be undone."
+  ]
+}

package/dist/conformance/host/06-install-pack-then-render/files/ana-1.0.0/pack.json

@@ -0,0 +1,13 @@
+{
+  "name": "ana",
+  "engine": "react",
+  "version": "1.0.0",
+  "components": {
+    "timeline": {
+      "sources": {
+        "react": "./Timeline.tsx",
+        "ansi": "./Timeline.ansi.tsx"
+      }
+    }
+  }
+}

package/dist/conformance/host/06-install-pack-then-render/files/ana-1.0.0/webview.js

@@ -0,0 +1 @@
+window.__markiiRegisterPack(() => ({}));

package/dist/conformance/host/06-install-pack-then-render/note.mk.md

@@ -0,0 +1,5 @@
+# Install a pack, then load it
+
+::ana_timeline
+Rendered once "ana" is installed and loaded.
+::

package/dist/conformance/host/06-install-pack-then-render/scenario.json

@@ -0,0 +1,15 @@
+{
+  "id": "install-pack-then-render",
+  "invariant": "installing a .mkp loads its namespace; a second install of the same namespace asks before replacing",
+  "clock": 1700000000000,
+  "actions": [
+    { "type": "open" },
+    { "type": "installPack", "archive": "files/ana-1.0.0", "answers": ["allow"] },
+    { "type": "loadPacks" },
+    {
+      "type": "installPack",
+      "archive": "files/ana-1.0.0",
+      "answers": ["allow", "allow"]
+    }
+  ]
+}

package/dist/conformance/host/07-complete-in-directive/expected.json

@@ -0,0 +1,14 @@
+{
+  "outcomes": [
+    {
+      "kind": "completions",
+      "labels": ["callout"],
+      "replaceStart": 0,
+      "replaceEnd": 6,
+      "tokenStart": 3,
+      "fenceEditCount": 0
+    }
+  ],
+  "diagnostics": [],
+  "prompts": []
+}

package/dist/conformance/host/07-complete-in-directive/note.mk.md

@@ -0,0 +1,3 @@
+# Completion inside a directive
+
+:::cal

package/dist/conformance/host/07-complete-in-directive/scenario.json

@@ -0,0 +1,6 @@
+{
+  "id": "complete-in-directive",
+  "invariant": "completion inside a directive returns the standard set",
+  "clock": 1700000000000,
+  "actions": [{ "type": "completeAt", "line": 2, "column": 6 }]
+}

package/dist/conformance/host/08-hover-standard-component/expected.json

@@ -0,0 +1,5 @@
+{
+  "outcomes": [{ "kind": "hover", "contains": "callout", "start": 2, "end": 9 }],
+  "diagnostics": [],
+  "prompts": []
+}

package/dist/conformance/host/08-hover-standard-component/note.mk.md

@@ -0,0 +1,5 @@
+# Hover on a standard component
+
+::callout{tone=info}
+Hover over the directive name above.
+::

package/dist/conformance/host/08-hover-standard-component/scenario.json

@@ -0,0 +1,6 @@
+{
+  "id": "hover-standard-component",
+  "invariant": "hover on a standard component returns its documented attributes",
+  "clock": 1700000000000,
+  "actions": [{ "type": "hoverAt", "line": 2, "column": 5 }]
+}

package/dist/conformance/host/09-insert-skeleton/expected.json

@@ -0,0 +1,5 @@
+{
+  "outcomes": [{ "kind": "inserted" }],
+  "diagnostics": [],
+  "prompts": []
+}

package/dist/conformance/host/09-insert-skeleton/note.mk.md

@@ -0,0 +1,4 @@
+# Insert a skeleton
+
+::card
+::

package/dist/conformance/host/09-insert-skeleton/scenario.json

@@ -0,0 +1,6 @@
+{
+  "id": "insert-skeleton",
+  "invariant": "inserting a component applies one undoable edit",
+  "clock": 1700000000000,
+  "actions": [{ "type": "insertComponent", "name": "callout" }]
+}

package/dist/conformance/host/10-scripts-disabled/expected.json

@@ -0,0 +1,11 @@
+{
+  "outcomes": [
+    { "kind": "opened" },
+    {
+      "kind": "declined",
+      "reasonContains": "script execution is off"
+    }
+  ],
+  "diagnostics": ["run (manual) blocked: script execution is off on this device"],
+  "prompts": []
+}

package/dist/conformance/host/10-scripts-disabled/note.mk.md

@@ -0,0 +1,5 @@
+# The device switch is off
+
+```lua {name=total}
+return net.fetch_json("https://api.example.com/orders")
+```

package/dist/conformance/host/10-scripts-disabled/scenario.json

@@ -0,0 +1,9 @@
+{
+  "id": "scripts-disabled",
+  "invariant": "the device switch blocks the run before the isolate, and says so on both surfaces",
+  "clock": 1700000000000,
+  "actions": [
+    { "type": "open" },
+    { "type": "run", "trigger": "manual", "scriptsDisabled": true }
+  ]
+}

package/dist/conformance/host/11-complete-closing-fence/expected.json

@@ -0,0 +1,5 @@
+{
+  "outcomes": [{ "kind": "none" }],
+  "diagnostics": [],
+  "prompts": []
+}

package/dist/conformance/host/11-complete-closing-fence/note.mk.md

@@ -0,0 +1,5 @@
+# Closing fence
+
+:::callout
+Body.
+:::

package/dist/conformance/host/11-complete-closing-fence/scenario.json

@@ -0,0 +1,12 @@
+{
+  "id": "complete-closing-fence",
+  "invariant": "a bare colon run that closes an open container offers no completions, and says so without failing",
+  "clock": 1700000000000,
+  "actions": [
+    {
+      "type": "completeAt",
+      "line": 4,
+      "column": 3
+    }
+  ]
+}

package/dist/conformance/host/12-complete-nested-container/expected.json

@@ -0,0 +1,5 @@
+{
+  "outcomes": [{ "kind": "completions", "labels": ["callout"], "fenceEditCount": 2 }],
+  "diagnostics": [],
+  "prompts": []
+}

package/dist/conformance/host/12-complete-nested-container/note.mk.md

@@ -0,0 +1,5 @@
+# Nested container
+
+:::card
+:::cal
+:::

package/dist/conformance/host/12-complete-nested-container/scenario.json

@@ -0,0 +1,12 @@
+{
+  "id": "complete-nested-container",
+  "invariant": "completion of a container inside an equal-length container carries the fence edits that keep the pair legal",
+  "clock": 1700000000000,
+  "actions": [
+    {
+      "type": "completeAt",
+      "line": 3,
+      "column": 6
+    }
+  ]
+}

package/dist/conformance/host/13-install-pack-declined/expected.json

@@ -0,0 +1,12 @@
+{
+  "outcomes": [
+    { "kind": "opened" },
+    { "kind": "declined", "step": "consent" },
+    { "kind": "not-installed", "namespace": "ana" }
+  ],
+  "diagnostics": [
+    "Install pack from file cancelled for",
+    "Remove pack found no installed pack \"ana\""
+  ],
+  "prompts": ["Installing \"ana\" lets its code run inside"]
+}