@earendil-works/djs 0.0.0-stage → 0.1.0

package/LICENSE-APACHE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Earendil Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,89 @@
-# Temporary Holding Version
+# @earendil-works/djs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+djs is a small JavaScript and TypeScript engine compiled to WebAssembly, made for running
+untrusted scripts inside a host: agent tool scripts, plugins, user code. Every sandbox is
+its own wasm instance with its own heap, so sandboxes share nothing. Scripts get only the
+host functions you give them, run under a fuel budget and a memory cap, and a run that
+waits on the host can be suspended into a dump, a plain JavaScript file, and continued
+later in another process.
+
+The module has no imports and the package no dependencies: it runs in node (20 or newer),
+Bun, Deno, browsers and web workers.
+
+## Install
+
+```sh
+npm install @earendil-works/djs
+```
+
+## Use
+
+```js
+import { Sandbox } from "@earendil-works/djs";
+
+const sandbox = await Sandbox.create({
+  asyncFunctions: { "tools.search": async (q) => search(q) },
+  maxFuel: 50_000_000,
+  memoryLimit: 64 << 20,
+});
+
+// A script is the body of an async function: its parameters are the keys of the second
+// argument, and `await` and `return` work at the top level.
+const hits = await sandbox.runAsync("return (await tools.search(query)).slice(0, 3)", { query: "djs" });
+sandbox.run("return a + b", { a: 40, b: 2 }); // 42
+sandbox.dispose();
+```
+
+Options include `typescript: true` (scripts are TypeScript), `console` (where
+`console.log` goes), `globals`, `deterministic` (repeatable runs) and `frozenBuiltins`.
+Errors are `SandboxError`s with a `kind`: `threw`, `syntax`, `fuel`, `memory`, ...
+
+## Entry points
+
+| import | module | for |
+| --- | --- | --- |
+| `@earendil-works/djs` | `wasm/djs.wasm` | every host |
+| `@earendil-works/djs/slim` | `wasm/djs-slim.wasm` | hosts that count kilobytes: no typed arrays, BigInt, iterator helpers and other families scripts rarely use |
+| `@earendil-works/djs/dump` | `wasm/djs-dump.wasm` | hosts that suspend runs into dumps: the main module plus the dumper |
+| `@earendil-works/djs/dump-runtime` | | the helpers a dump needs to continue in a JavaScript engine other than djs |
+
+Each entry point exports the same API, with its own module as the default. To dump runs
+while running them in the smaller main module, give the sandbox the dump module as its
+`dumpModule`:
+
+```js
+import { Sandbox } from "@earendil-works/djs";
+import { loadModule as loadDumpModule } from "@earendil-works/djs/dump";
+
+const sandbox = await Sandbox.create({ frozenBuiltins: true, dumpModule: await loadDumpModule(), asyncFunctions });
+const task = sandbox.start(code, params);
+const dump = await task.suspend(); // later, anywhere: (await Sandbox.resume(dump, options)).result
+```
+
+## Loading the module
+
+`Sandbox.create` loads its entry point's module once per process and caches it;
+`loadModule(location)` loads another one and `new Sandbox({ module })` uses it. In node,
+Bun and Deno the module is read from the package's `wasm/` directory (`$DJS_WASM` names
+another main module). In a browser it is fetched from the URL
+`new URL("../wasm/djs.wasm", import.meta.url)`, a pattern that webpack and Vite recognize
+and copy into the build. In Vite's dev server, exclude the package from dependency
+pre-bundling, which would move the code away from its modules:
+
+```js
+// vite.config.js
+export default { optimizeDeps: { exclude: ["@earendil-works/djs"] } };
+```
+
+In Deno, allow reading the package's directory (`--allow-read`). With a bundler that does
+not know the pattern, serve the `.wasm` file yourself and pass its URL:
+`Sandbox.create({ module: await loadModule("/assets/djs.wasm") })`.
+
+## Documentation
+
+The guide, with the whole API, the language djs runs, limits, determinism and dumps:
+https://earendil-works.github.io/djs/js-api.html
+
+## License
+
+MIT or Apache-2.0, at your option.

package/dist/base.d.ts

@@ -0,0 +1,33 @@
+/** The exports of an instance that `provideBase` and `rememberBase` use. */
+export interface BaseExports {
+    memory: WebAssembly.Memory;
+    djs_base_ptr(): number;
+    djs_base_len(): number;
+    djs_base_inject_ptr?(len: number): number;
+    djs_base_inject?(): number;
+    djs_base_coded_ptr?(len: number): number;
+}
+/**
+ * Hands a fresh instance of `module` its coded base, the module's custom section
+ * `djs_base` (D2541): the module keeps it out of its linear memory, and an instance
+ * decodes it when it needs the base and has none injected. `provideBase` and
+ * `rememberBase` call it; a host that drives the exports itself calls it right after
+ * instantiating, before anything creates a VM or reads the base. Returns whether the
+ * instance took the bytes (false if it has its base, or the module has no such section).
+ */
+export declare function provideCodedBase(module: WebAssembly.Module, exports: BaseExports): boolean;
+/**
+ * Gives a fresh instance of `module` the base snapshot an earlier instance of it decoded
+ * (D2252): the module ships the base coded, and an instance decodes it at its first use
+ * (a few ms) unless the host provides it. Call right after instantiating, before anything
+ * that creates a VM or reads the base; and `rememberBase` once a VM exists, so that later
+ * instances get it. The instance checks the bytes (length and hash). Returns whether the
+ * instance took them; if not (refused, or no instance remembered the base yet), it gets
+ * the coded base to decode its own (`provideCodedBase`).
+ */
+export declare function provideBase(module: WebAssembly.Module, exports: BaseExports): boolean;
+/**
+ * Keeps the base of `module` (from this instance, once per module) for `provideBase`. Call
+ * before the instance's first `vm_new`, which takes the bytes as its arena (D2060).
+ */
+export declare function rememberBase(module: WebAssembly.Module, exports: BaseExports): void;

package/dist/base.js

@@ -0,0 +1,71 @@
+// The module's base snapshot (D1321) on the host side: the module ships it coded in its
+// custom section `djs_base` (D2252, D2541), every instance needs it decoded before its
+// first VM, and decoding takes a few ms. So the host hands each fresh instance the coded
+// section, or the bytes an earlier instance of the same module decoded (checked by the
+// instance), and keeps those bytes once per module.
+/** The decoded base of each module, as an earlier instance of it decoded it. */
+const bases = new WeakMap();
+const codedSections = new WeakMap();
+/**
+ * Hands a fresh instance of `module` its coded base, the module's custom section
+ * `djs_base` (D2541): the module keeps it out of its linear memory, and an instance
+ * decodes it when it needs the base and has none injected. `provideBase` and
+ * `rememberBase` call it; a host that drives the exports itself calls it right after
+ * instantiating, before anything creates a VM or reads the base. Returns whether the
+ * instance took the bytes (false if it has its base, or the module has no such section).
+ */
+export function provideCodedBase(module, exports) {
+    if (exports.djs_base_coded_ptr === undefined)
+        return false;
+    let coded = codedSections.get(module);
+    if (coded === undefined) {
+        const [section] = WebAssembly.Module.customSections(module, "djs_base");
+        if (section === undefined)
+            return false;
+        coded = new Uint8Array(section);
+        codedSections.set(module, coded);
+    }
+    const at = exports.djs_base_coded_ptr(coded.length);
+    if (at === 0)
+        return false;
+    new Uint8Array(exports.memory.buffer, at, coded.length).set(coded);
+    return true;
+}
+/**
+ * Gives a fresh instance of `module` the base snapshot an earlier instance of it decoded
+ * (D2252): the module ships the base coded, and an instance decodes it at its first use
+ * (a few ms) unless the host provides it. Call right after instantiating, before anything
+ * that creates a VM or reads the base; and `rememberBase` once a VM exists, so that later
+ * instances get it. The instance checks the bytes (length and hash). Returns whether the
+ * instance took them; if not (refused, or no instance remembered the base yet), it gets
+ * the coded base to decode its own (`provideCodedBase`).
+ */
+export function provideBase(module, exports) {
+    const bytes = bases.get(module);
+    if (bytes !== undefined && exports.djs_base_inject_ptr !== undefined && exports.djs_base_inject !== undefined) {
+        const at = exports.djs_base_inject_ptr(bytes.length);
+        if (at !== 0) {
+            new Uint8Array(exports.memory.buffer, at, bytes.length).set(bytes);
+            if (exports.djs_base_inject() === 1)
+                return true;
+        }
+    }
+    // The instance decodes its own, from the coded base.
+    provideCodedBase(module, exports);
+    return false;
+}
+/**
+ * Keeps the base of `module` (from this instance, once per module) for `provideBase`. Call
+ * before the instance's first `vm_new`, which takes the bytes as its arena (D2060).
+ */
+export function rememberBase(module, exports) {
+    if (bases.has(module))
+        return;
+    provideCodedBase(module, exports);
+    // The pointer first: an instance decodes its base at the first use (D2252), which may
+    // grow (and detach) its memory buffer.
+    const at = exports.djs_base_ptr();
+    if (at === 0)
+        throw new Error("djs-wasm has no base snapshot (no djs_base section?)");
+    bases.set(module, new Uint8Array(exports.memory.buffer, at, exports.djs_base_len()).slice());
+}

package/dist/dump-runtime.d.ts

@@ -0,0 +1,16 @@
+// The declarations of dump-runtime.js (generated from Rust, D2834): what a host uses. The
+// single helpers stay undeclared: a dump reaches them through `$djs`, a host through
+// `helpers`.
+
+/**
+ * The helpers a plain dump calls as `$djs.NAME`, by name. To continue a dump outside djs:
+ * `globalThis.$djs = { ...helpers, seed, resume, source, host }`, run the dump as a Script,
+ * then delete `$djs` and `$dump`.
+ */
+export declare const helpers: Readonly<Record<string, (...args: any[]) => any>>;
+
+/** The same as a Script whose completion value is `helpers`. */
+export declare const script: string;
+
+/** `script` with only the helpers `dump` names and the ones those name. */
+export declare function scriptFor(dump: string): string;

package/dist/dump-runtime.js

@@ -0,0 +1,107 @@
+// The plain dump runtime (D2834, D2903): the helpers a plain dump calls as `$djs.NAME`.
+// To run a dump outside djs, set `globalThis.$djs` to these and the host's hooks
+// (`seed`, `resume`, `source`, `host`; see docs/plain-js-dumps.md, "The host interface"), then run the
+// dump as a Script, and delete `$djs` and `$dump` after it. Generated from crates/djs-core/src/vm/dump_runtime.rs:
+//   DJS_UPDATE_DUMP_RUNTIME=1 cargo test -p djs-core dump_runtime
+
+const matchAll = RegExp.prototype[Symbol.matchAll];
+export const R = Reflect.apply;
+export const G = Reflect.get;
+export const C = Reflect.construct;
+export const D = (o, k, v) => Object.defineProperty(o, k, { value: v, writable: true, enumerable: true, configurable: true });
+export const A = Object.assign;
+export const L = (it, next) => { let first = true; const r = { next() { if (first) { first = false; return { value: undefined, done: false }; } return Reflect.apply(next ?? it.next, it, []); }, get return() { const m = it.return; return m == null ? m : (...v) => Reflect.apply(m, it, v); }, set(i, n) { it = i; next = n; }, [Symbol.iterator]() { return r; } }; return r; };
+export const I = (it, next) => { const r = { next() { return Reflect.apply(next ?? it.next, it, []); }, get return() { const m = it.return; return m == null ? m : (...v) => Reflect.apply(m, it, v); }, [Symbol.iterator]() { return r; } }; return r; };
+export const E = () => ({ [Symbol.iterator]() { return { next() { return { value: undefined, done: true }; } }; } });
+export const Y = (it, next, a, ...first) => { const r2 = a > 1; let ph = r2 || !first.length; const m = (k) => { if (r2 && k == 'return' && first.length) { const p = first.pop(); return () => p; } const f = it[k]; return f == null ? f : (...v) => Reflect.apply(f, it, v); }; const r = { next(...v) { if (!r2 && first.length) return first.pop(); if (ph) { ph = false; return { value: undefined, done: false }; } return Reflect.apply(next, it, v); }, get throw() { return m('throw'); }, get return() { return m('return'); }, [a ? Symbol.asyncIterator : Symbol.iterator]() { return r; } }; return r; };
+export const DD = (o, src) => { for (const k of Reflect.ownKeys(src)) { const d = Reflect.getOwnPropertyDescriptor(src, k); if ('get' in d) { if (d.get === undefined) delete d.get; if (d.set === undefined) delete d.set; } Object.defineProperty(o, k, d); } return o; };
+export const U = ($djs_v, $djs_m, k) => k === 4 ? { [Symbol.asyncDispose]: () => Reflect.apply($djs_m, $djs_v, []) } : { [Symbol.dispose]: () => Reflect.apply($djs_m, $djs_v, []) };
+export const M = ($djs_f, $djs_k) => (x, i) => Reflect.apply($djs_f, undefined, [x, i + $djs_k]);
+export const FM = (it, next, $djs_f, k, inner, innerNext) => { const $djs_k = k - 1, $djs_in = { [Symbol.iterator]: () => L(inner, innerNext) }; const h = Iterator.prototype.flatMap.call(L(it, next), (x, i) => i === 0 ? $djs_in : Reflect.apply($djs_f, undefined, [x, i + $djs_k])); h.next(); return h; };
+export const CC = (cur, curNext, items) => { const h = Iterator.concat({ [Symbol.iterator]: () => L(cur, curNext) }, ...items); h.next(); return h; };
+export const CI = ($djs_m, $djs_o) => ({ [Symbol.iterator]: () => Reflect.apply($djs_m, $djs_o, []) });
+export const HD = () => { const h = Iterator.prototype.map.call({ next: () => ({ value: undefined, done: true }) }, (x) => x); h.next(); return h; };
+export const P = (k) => Reflect.ownKeys({ [k]: 0 })[0];
+export const S = (o, ex) => { const r = {}, f = Object(o), ks = Reflect.ownKeys(f); for (let i = 0; i < ks.length; i++) { const k = ks[i]; let skip = false; for (let j = 0; j < ex.length; j++) if (ex[j] === k) skip = true; if (skip) continue; const d = Reflect.getOwnPropertyDescriptor(f, k); if (d && d.enumerable) Object.defineProperty(r, k, { value: f[k], writable: true, enumerable: true, configurable: true }); } return r; };
+export const N = (it, next, ...first) => { const r = { next() { return first.length ? first.pop() : Reflect.apply(next, it, []); }, get return() { const m = it.return; return m == null ? m : (...v) => Reflect.apply(m, it, v); }, [Symbol.asyncIterator]() { return r; } }; return r; };
+export const X = (it) => { let p; try { const m = it.return; if (m == null) return; p = Promise.resolve(Reflect.apply(m, it, [])); } catch { return; } return p.then(() => {}, () => {}); };
+export const O = (r) => { if (Object(r) !== r) throw new TypeError('iterator must return an object'); };
+export const fromSync = (it, next) => { const q = () => { try { const m = it.return; if (m != null) Reflect.apply(m, it, []); } catch {} }; const step = (f, close) => new Promise((res, rej) => { const r = f(); if (Object(r) !== r) throw new TypeError('iterator must return an object'); const done = !!r.done; let w; try { w = Promise.resolve(r.value); } catch (e) { if (!done && close) q(); throw e; } w.then((v) => res({ value: v, done }), !done && close ? (e) => { q(); rej(e); } : rej); }); return { next: (...a) => step(() => Reflect.apply(next, it, a), true), return: (...a) => { const m = it.return; return m == null ? Promise.resolve({ value: a[0], done: true }) : step(() => Reflect.apply(m, it, a), false); }, throw: (...a) => { const m = it.throw; if (m != null) return step(() => Reflect.apply(m, it, a), true); try { const c = it.return; if (c != null) { const r = Reflect.apply(c, it, []); if (Object(r) !== r) throw new TypeError('iterator must return an object'); } throw new TypeError('throw is not a method'); } catch (e) { return Promise.reject(e); } } }; };
+export const Q = (a, ...v) => { let n = a.length; for (const x of v) Object.defineProperty(a, n++, { value: x, writable: true, enumerable: true, configurable: true }); return a; };
+export const regexpIterator = (re, s, f) => { const it = Reflect.apply(matchAll, re, [s]); if (f & 4) while (!it.next().done); return it; };
+export const closeThrow = (it) => (e) => { try { const m = it.return; if (m != null) Reflect.apply(m, it, []); } catch {} throw e; };
+export const forIn = (o, keys) => { let i = 0; const r = { next() { while (i < keys.length) { const k = keys[i++]; if (o == null || k in o) return { value: k, done: false }; } return { value: undefined, done: true }; }, [Symbol.iterator]() { return r; } }; return r; };
+export const advance = (it, n) => { const next = it.next; for (let i = 0; i < n; i++) Reflect.apply(next, it, []); return it; };
+export const fn = (o) => { const d = Object.getOwnPropertyDescriptor(o, Reflect.ownKeys(o)[0]); return 'value' in d ? d.value : d.get ?? d.set; };
+export const spent = (k) => { let f; new Promise((a, b) => { f = k ? b : a; a(); }); return f; };
+export const rejected = (e) => { const p = Promise.reject(e); p.then(undefined, () => {}); return p; };
+export const fromAsync = (p, mapfn, thisArg, it, next, A, k, phase, items, len, error) => new Promise((resolve, reject) => { const put = (v) => { if (!Reflect.defineProperty(A, k, { value: v, writable: true, enumerable: true, configurable: true })) throw new TypeError('cannot define the element'); }; const wait = (v, ph) => { phase = ph; Promise.prototype.then.call(Promise.resolve(v), ok, bad); }; const close = (e) => { error = e; try { const m = it.return; if (m == null) { reject(e); return; } wait(Reflect.apply(m, it, []), 3); } catch { reject(error); } }; const step = () => { try { if (k >= 9007199254740991) { close(new TypeError('Array too long')); return; } wait(Reflect.apply(next, it, []), 1); } catch (e) { reject(e); } }; const store = (v) => { try { put(v); } catch (e) { close(e); return; } k++; step(); }; const result = (r) => { let v; try { if (Object(r) !== r) throw new TypeError('iterator must return an object'); if (r.done) { A.length = k; resolve(A); return; } v = r.value; } catch (e) { reject(e); return; } if (mapfn === undefined) { store(v); return; } try { wait(Reflect.apply(mapfn, thisArg, [v, k]), 2); } catch (e) { close(e); } }; const element = () => { try { if (k < len) { wait(items[k], 4); return; } A.length = len; resolve(A); } catch (e) { reject(e); } }; const value = (v) => { try { if (phase === 4 && mapfn !== undefined) { wait(Reflect.apply(mapfn, thisArg, [v, k]), 5); return; } put(v); k++; } catch (e) { reject(e); return; } element(); }; const ok = (v) => { if (phase === 1) result(v); else if (phase === 2) store(v); else if (phase === 3) reject(error); else value(v); }; const bad = (e) => { if (phase === 2) close(e); else if (phase === 3) reject(error); else reject(e); }; Promise.prototype.then.call(p, ok, bad); });
+export const bytes = (b) => Uint8Array.fromBase64(b).buffer;
+export const k = (K, f, at, r, h, p) => { Object.defineProperty(K, '$djs', { value: [f, at, r, h] }); if (p !== undefined) K.prototype = p; else if ('prototype' in K) K.prototype = f.prototype; return K; };
+export const keep = (o, keys) => { for (const k of Reflect.ownKeys(o)) if (!['length', 'name', 'prototype', 'constructor'].includes(k) && !keys.includes(k) && !delete o[k]) throw new TypeError('keep'); };
+
+/** The helpers by name: `globalThis.$djs = { ...helpers, seed, resume }`. */
+export const helpers = { R, G, C, D, A, L, I, E, Y, DD, U, M, FM, CC, CI, HD, P, S, N, X, O, fromSync, Q, regexpIterator, closeThrow, forIn, advance, fn, spent, rejected, fromAsync, bytes, k, keep };
+
+/** The same as a Script whose completion value is `helpers`, for a host that evaluates it in
+ * a djs VM itself (`vm_dump_runtime`). */
+export const script = `"use strict";
+(() => {
+const matchAll = RegExp.prototype[Symbol.matchAll];
+const R = Reflect.apply;
+const G = Reflect.get;
+const C = Reflect.construct;
+const D = (o, k, v) => Object.defineProperty(o, k, { value: v, writable: true, enumerable: true, configurable: true });
+const A = Object.assign;
+const L = (it, next) => { let first = true; const r = { next() { if (first) { first = false; return { value: undefined, done: false }; } return Reflect.apply(next ?? it.next, it, []); }, get return() { const m = it.return; return m == null ? m : (...v) => Reflect.apply(m, it, v); }, set(i, n) { it = i; next = n; }, [Symbol.iterator]() { return r; } }; return r; };
+const I = (it, next) => { const r = { next() { return Reflect.apply(next ?? it.next, it, []); }, get return() { const m = it.return; return m == null ? m : (...v) => Reflect.apply(m, it, v); }, [Symbol.iterator]() { return r; } }; return r; };
+const E = () => ({ [Symbol.iterator]() { return { next() { return { value: undefined, done: true }; } }; } });
+const Y = (it, next, a, ...first) => { const r2 = a > 1; let ph = r2 || !first.length; const m = (k) => { if (r2 && k == 'return' && first.length) { const p = first.pop(); return () => p; } const f = it[k]; return f == null ? f : (...v) => Reflect.apply(f, it, v); }; const r = { next(...v) { if (!r2 && first.length) return first.pop(); if (ph) { ph = false; return { value: undefined, done: false }; } return Reflect.apply(next, it, v); }, get throw() { return m('throw'); }, get return() { return m('return'); }, [a ? Symbol.asyncIterator : Symbol.iterator]() { return r; } }; return r; };
+const DD = (o, src) => { for (const k of Reflect.ownKeys(src)) { const d = Reflect.getOwnPropertyDescriptor(src, k); if ('get' in d) { if (d.get === undefined) delete d.get; if (d.set === undefined) delete d.set; } Object.defineProperty(o, k, d); } return o; };
+const U = ($djs_v, $djs_m, k) => k === 4 ? { [Symbol.asyncDispose]: () => Reflect.apply($djs_m, $djs_v, []) } : { [Symbol.dispose]: () => Reflect.apply($djs_m, $djs_v, []) };
+const M = ($djs_f, $djs_k) => (x, i) => Reflect.apply($djs_f, undefined, [x, i + $djs_k]);
+const FM = (it, next, $djs_f, k, inner, innerNext) => { const $djs_k = k - 1, $djs_in = { [Symbol.iterator]: () => L(inner, innerNext) }; const h = Iterator.prototype.flatMap.call(L(it, next), (x, i) => i === 0 ? $djs_in : Reflect.apply($djs_f, undefined, [x, i + $djs_k])); h.next(); return h; };
+const CC = (cur, curNext, items) => { const h = Iterator.concat({ [Symbol.iterator]: () => L(cur, curNext) }, ...items); h.next(); return h; };
+const CI = ($djs_m, $djs_o) => ({ [Symbol.iterator]: () => Reflect.apply($djs_m, $djs_o, []) });
+const HD = () => { const h = Iterator.prototype.map.call({ next: () => ({ value: undefined, done: true }) }, (x) => x); h.next(); return h; };
+const P = (k) => Reflect.ownKeys({ [k]: 0 })[0];
+const S = (o, ex) => { const r = {}, f = Object(o), ks = Reflect.ownKeys(f); for (let i = 0; i < ks.length; i++) { const k = ks[i]; let skip = false; for (let j = 0; j < ex.length; j++) if (ex[j] === k) skip = true; if (skip) continue; const d = Reflect.getOwnPropertyDescriptor(f, k); if (d && d.enumerable) Object.defineProperty(r, k, { value: f[k], writable: true, enumerable: true, configurable: true }); } return r; };
+const N = (it, next, ...first) => { const r = { next() { return first.length ? first.pop() : Reflect.apply(next, it, []); }, get return() { const m = it.return; return m == null ? m : (...v) => Reflect.apply(m, it, v); }, [Symbol.asyncIterator]() { return r; } }; return r; };
+const X = (it) => { let p; try { const m = it.return; if (m == null) return; p = Promise.resolve(Reflect.apply(m, it, [])); } catch { return; } return p.then(() => {}, () => {}); };
+const O = (r) => { if (Object(r) !== r) throw new TypeError('iterator must return an object'); };
+const fromSync = (it, next) => { const q = () => { try { const m = it.return; if (m != null) Reflect.apply(m, it, []); } catch {} }; const step = (f, close) => new Promise((res, rej) => { const r = f(); if (Object(r) !== r) throw new TypeError('iterator must return an object'); const done = !!r.done; let w; try { w = Promise.resolve(r.value); } catch (e) { if (!done && close) q(); throw e; } w.then((v) => res({ value: v, done }), !done && close ? (e) => { q(); rej(e); } : rej); }); return { next: (...a) => step(() => Reflect.apply(next, it, a), true), return: (...a) => { const m = it.return; return m == null ? Promise.resolve({ value: a[0], done: true }) : step(() => Reflect.apply(m, it, a), false); }, throw: (...a) => { const m = it.throw; if (m != null) return step(() => Reflect.apply(m, it, a), true); try { const c = it.return; if (c != null) { const r = Reflect.apply(c, it, []); if (Object(r) !== r) throw new TypeError('iterator must return an object'); } throw new TypeError('throw is not a method'); } catch (e) { return Promise.reject(e); } } }; };
+const Q = (a, ...v) => { let n = a.length; for (const x of v) Object.defineProperty(a, n++, { value: x, writable: true, enumerable: true, configurable: true }); return a; };
+const regexpIterator = (re, s, f) => { const it = Reflect.apply(matchAll, re, [s]); if (f & 4) while (!it.next().done); return it; };
+const closeThrow = (it) => (e) => { try { const m = it.return; if (m != null) Reflect.apply(m, it, []); } catch {} throw e; };
+const forIn = (o, keys) => { let i = 0; const r = { next() { while (i < keys.length) { const k = keys[i++]; if (o == null || k in o) return { value: k, done: false }; } return { value: undefined, done: true }; }, [Symbol.iterator]() { return r; } }; return r; };
+const advance = (it, n) => { const next = it.next; for (let i = 0; i < n; i++) Reflect.apply(next, it, []); return it; };
+const fn = (o) => { const d = Object.getOwnPropertyDescriptor(o, Reflect.ownKeys(o)[0]); return 'value' in d ? d.value : d.get ?? d.set; };
+const spent = (k) => { let f; new Promise((a, b) => { f = k ? b : a; a(); }); return f; };
+const rejected = (e) => { const p = Promise.reject(e); p.then(undefined, () => {}); return p; };
+const fromAsync = (p, mapfn, thisArg, it, next, A, k, phase, items, len, error) => new Promise((resolve, reject) => { const put = (v) => { if (!Reflect.defineProperty(A, k, { value: v, writable: true, enumerable: true, configurable: true })) throw new TypeError('cannot define the element'); }; const wait = (v, ph) => { phase = ph; Promise.prototype.then.call(Promise.resolve(v), ok, bad); }; const close = (e) => { error = e; try { const m = it.return; if (m == null) { reject(e); return; } wait(Reflect.apply(m, it, []), 3); } catch { reject(error); } }; const step = () => { try { if (k >= 9007199254740991) { close(new TypeError('Array too long')); return; } wait(Reflect.apply(next, it, []), 1); } catch (e) { reject(e); } }; const store = (v) => { try { put(v); } catch (e) { close(e); return; } k++; step(); }; const result = (r) => { let v; try { if (Object(r) !== r) throw new TypeError('iterator must return an object'); if (r.done) { A.length = k; resolve(A); return; } v = r.value; } catch (e) { reject(e); return; } if (mapfn === undefined) { store(v); return; } try { wait(Reflect.apply(mapfn, thisArg, [v, k]), 2); } catch (e) { close(e); } }; const element = () => { try { if (k < len) { wait(items[k], 4); return; } A.length = len; resolve(A); } catch (e) { reject(e); } }; const value = (v) => { try { if (phase === 4 && mapfn !== undefined) { wait(Reflect.apply(mapfn, thisArg, [v, k]), 5); return; } put(v); k++; } catch (e) { reject(e); return; } element(); }; const ok = (v) => { if (phase === 1) result(v); else if (phase === 2) store(v); else if (phase === 3) reject(error); else value(v); }; const bad = (e) => { if (phase === 2) close(e); else if (phase === 3) reject(error); else reject(e); }; Promise.prototype.then.call(p, ok, bad); });
+const bytes = (b) => Uint8Array.fromBase64(b).buffer;
+const k = (K, f, at, r, h, p) => { Object.defineProperty(K, '$djs', { value: [f, at, r, h] }); if (p !== undefined) K.prototype = p; else if ('prototype' in K) K.prototype = f.prototype; return K; };
+const keep = (o, keys) => { for (const k of Reflect.ownKeys(o)) if (!['length', 'name', 'prototype', 'constructor'].includes(k) && !keys.includes(k) && !delete o[k]) throw new TypeError('keep'); };
+return { R, G, C, D, A, L, I, E, Y, DD, U, M, FM, CC, CI, HD, P, S, N, X, O, fromSync, Q, regexpIterator, closeThrow, forIn, advance, fn, spent, rejected, fromAsync, bytes, k, keep };
+})();
+`;
+
+/** `script` with only the helpers `dump` names (`$djs.NAME`) and the ones their texts name:
+ * a load compiles a few helpers instead of all of them. */
+export function scriptFor(dump) {
+  const lines = script.split("\n");
+  const def = (l) => (l.startsWith("const ") && !l.startsWith("const matchAll ") ? l.slice(6, l.indexOf(" = ")) : undefined);
+  const defs = new Map(lines.filter(def).map((l) => [def(l), l]));
+  const want = new Set();
+  const add = (n) => {
+    if (!defs.has(n) || want.has(n)) return;
+    want.add(n);
+    for (const w of defs.get(n).slice(n.length + 9).split(/[^\w$]+/)) add(w);
+  };
+  for (const m of dump.split("$djs.").slice(1)) add(/^[\w$]*/.exec(m)[0]);
+  const names = [...defs.keys()].filter((n) => want.has(n));
+  return lines
+    .filter((l) => def(l) === undefined || want.has(def(l)))
+    .map((l) => (l.startsWith("return { ") ? `return { ${names.join(", ")} };` : l))
+    .join("\n");
+}

package/dist/dump.d.ts

@@ -0,0 +1,10 @@
+import { Sandbox as Base } from "./sandbox.js";
+export * from "./sandbox.js";
+/** This entry point's module: the package's djs-dump.wasm. */
+export declare function defaultWasmPath(): string | URL;
+/** Compiles djs-wasm once per location and caches it; default: this entry point's module. */
+export declare function loadModule(location?: string | URL): Promise<WebAssembly.Module>;
+/** The Sandbox, with this entry point's module as the default. */
+export declare class Sandbox extends Base {
+    static defaultModule(): string | URL;
+}

package/dist/dump.js

@@ -0,0 +1,21 @@
+// The package's `./dump` entry point: the Sandbox API with the dump module,
+// wasm/djs-dump.wasm (the shipped module plus the dumper), as its default: a sandbox that dumps
+// itself, or the `dumpModule` of a sandbox of the main entry point (D3106).
+// Each entry point loads only its own module, so a bundler copies only the modules an
+// application imports.
+import { Sandbox as Base, loadModule as load } from "./sandbox.js";
+export * from "./sandbox.js";
+/** This entry point's module: the package's djs-dump.wasm. */
+export function defaultWasmPath() {
+    return new URL("../wasm/djs-dump.wasm", import.meta.url);
+}
+/** Compiles djs-wasm once per location and caches it; default: this entry point's module. */
+export function loadModule(location = defaultWasmPath()) {
+    return load(location);
+}
+/** The Sandbox, with this entry point's module as the default. */
+export class Sandbox extends Base {
+    static defaultModule() {
+        return defaultWasmPath();
+    }
+}

package/dist/env.d.ts

@@ -0,0 +1,5 @@
+/**
+ * `$name` of the host's environment (node, Bun, Deno), or undefined where there is none or
+ * the host may not read it: Deno without `--allow-env` would prompt or throw.
+ */
+export declare function envVar(name: string): string | undefined;

package/dist/env.js

@@ -0,0 +1,17 @@
+// The host environment, as far as the package reads it.
+/**
+ * `$name` of the host's environment (node, Bun, Deno), or undefined where there is none or
+ * the host may not read it: Deno without `--allow-env` would prompt or throw.
+ */
+export function envVar(name) {
+    const g = globalThis;
+    try {
+        if (g.Deno !== undefined) {
+            return g.Deno.permissions.querySync?.({ name: "env", variable: name }).state === "granted" ? g.Deno.env.get(name) : undefined;
+        }
+        return g.process?.env?.[name];
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import { Sandbox as Base } from "./sandbox.js";
+export * from "./sandbox.js";
+/** This entry point's module: `$DJS_WASM`, else the package's djs.wasm. */
+export declare function defaultWasmPath(): string | URL;
+/** Compiles djs-wasm once per location and caches it; default: this entry point's module. */
+export declare function loadModule(location?: string | URL): Promise<WebAssembly.Module>;
+/** The Sandbox, with this entry point's module as the default. */
+export declare class Sandbox extends Base {
+    static defaultModule(): string | URL;
+}