@hara-lang/native-browser 0.1.9

package/README.md

@@ -0,0 +1,101 @@
+# @hara-lang/native-browser
+
+Embeddable Hara runtime for browsers and CDN scripts.
+
+```js
+import { start } from "@hara-lang/native-browser/vm";
+
+const hara = await start();
+console.log(hara.eval("(+ 19 23)"));
+```
+
+The package root remains an alias for `/vm`. Heavy-duty whole-function
+WebAssembly compilation is available from `@hara-lang/native-browser/full`. The
+compiler runs inside the browser runtime and the resulting module executes on
+the browser's own WebAssembly engine:
+
+```js
+import { start } from "@hara-lang/native-browser/full";
+const hara = await start();
+const compiled = await hara.compileWholeWasm(
+  "(loop [i 0 acc 0] (if (< i 5000) (recur (+ i 1) (+ acc i)) acc))"
+);
+console.log(compiled.call()); // 12497500n
+```
+
+The full package owns dynamic constants and persistent values in the outer Hara
+runtime while generated scalar and specialized collection work runs directly
+inside the browser's WebAssembly engine.
+
+The release also provides an IIFE bundle for a plain script tag:
+
+```html
+<script src="https://unpkg.com/@hara-lang/native-browser@0.1.9/dist/native-vm/hara.js"></script>
+<script>
+  Hara.start().then((hara) => console.log(hara.eval("(+ 19 23)")));
+</script>
+```
+
+The default browser runtime is the small core evaluator. Foundation and other
+semantic package families are opt-in, so a page can choose the exact lock and
+load only the capabilities it needs. Host resources can still be registered
+before requiring them:
+
+```js
+const hara = await Hara.start({
+  resources: {
+    "app.config": "(ns app.config) (def answer 42)"
+  }
+});
+```
+
+Locked Hara packages can be fetched from an immutable package host (including
+`packages.*`) or a release asset and installed before application evaluation:
+
+```js
+import { installLockedPackages, start } from "@hara-lang/native-browser";
+
+const hara = await start();
+const lock = await fetch(projectLockUrl).then((response) => response.text());
+await installLockedPackages(hara, lock);
+hara.require("my.world");
+```
+
+The same selection can happen during isolated startup. `targets` accepts a
+semantic package name, an exact lock coordinate, or a namespace:
+
+```js
+const hara = await start({
+  lock,
+  targets: ["lang.model.v1.postgres"],
+  packageOptions: { origin: "https://packages.example" }
+});
+```
+
+HARP archives may contain a verified `bytecode/package.hbx`. The loader checks
+its manifest digest and installs the HBX0 index when the VM runtime exposes the
+bundle seam; otherwise the verified HAL resources remain the source fallback.
+Package selection is described by the package's signed lock. The source package
+defines semantic profiles and dependency conventions; this host only verifies
+and activates the selected archive set.
+
+Memory-backed Wasm packages use the explicit `memory.v1` binding route. The
+manifest, canonical interface, and canonical `bindings.edn` plan are verified
+before the module is instantiated:
+
+```js
+hara.installMemoryWasmBinding(manifest, interfaceSource, bindingsSource, wasmBytes);
+hara.require("my.wasm.package");
+```
+
+Only format-2 locks are accepted. The loader verifies the HARP archive digest,
+optional archive size, every file declared by `package.edn`, safe archive paths,
+and unique HAL namespaces. Resources are registered only after the complete
+lock has passed verification. A lock entry may use `:distribution/url`,
+`:packages/url`, `:release-url`, or `:url`; package distribution URLs take
+precedence and the lock digest remains authoritative.
+
+Verified `:hta` extensions select only their prebuilt `:browser` web-worker
+target. Declared assets are loaded from the archive, and unsupported
+capabilities fail during installation; no Cargo, Maven, or compiler step is
+performed.

package/dist/native-full/hara.d.ts

@@ -0,0 +1,88 @@
+export interface StartOptions {
+  /** Override the default adjacent hara_wasm_bg.wasm URL. */
+  wasmUrl?: RequestInfo | URL | ArrayBuffer | WebAssembly.Module | Uint8Array;
+  /** Host resources registered before the first require. */
+  resources?: Map<string, string> | Record<string, string>;
+  /** Exact lock used to install semantic packages before the runtime is returned. */
+  lock?: string;
+  /** Semantic package names, coordinates, or namespaces selected from the lock. */
+  targets?: string[];
+  /** Fetch, capability, host, and browser-worker policy for package installation. */
+  packageOptions?: LockedPackageOptions;
+}
+
+export interface HaraRuntime {
+  eval(source: string): string;
+  require(namespace: string): string;
+  registerResource(namespace: string, source: string): void;
+  installDirectWasmImport(logical: string, bytes: Uint8Array): void;
+  installMemoryWasmBinding(
+    manifest: string,
+    interfaceSource: string,
+    bindingsSource: string,
+    bytes: Uint8Array
+  ): void;
+  unregisterResource(namespace: string): void;
+  evalInNamespace(namespace: string, source: string): string;
+  currentNamespace(): string;
+  compileBytecode(source: string): Uint8Array;
+  evalBytecode(artifact: Uint8Array): string;
+  evalBytecodeBundle(artifact: Uint8Array): void;
+  installPackages(lockSource: string, options?: LockedPackageOptions): Promise<string[]>;
+  compileWholeWasm(source: string): Promise<WholeWasmModule>;
+  compileWholeWasmProduct(source: string): WholeWasmProduct;
+  loadWholeWasm(
+    product: WholeWasmProduct | Uint8Array | ArrayBuffer
+  ): Promise<WholeWasmModule>;
+  installHostHandler(handler: Function): void;
+  dispose(): Promise<void>;
+  readonly raw: unknown;
+}
+
+export interface WholeWasmModule {
+  call(...arguments: Array<number | bigint>): bigint;
+  callFunction(functionId: number, ...arguments: Array<number | bigint>): bigint;
+  readonly manifest: Readonly<Record<string, unknown>> | null;
+  readonly module: WebAssembly.Module;
+  readonly instance: WebAssembly.Instance;
+}
+
+export interface WholeWasmProduct {
+  readonly artifact: Uint8Array;
+  readonly manifest: Readonly<Record<string, unknown>>;
+}
+
+export interface LockedPackageOptions {
+  fetch?: typeof globalThis.fetch;
+  origin?: string;
+  targets?: string[];
+  capabilities?: string[];
+  hostCalls?: Record<string, Function | Record<string, Function>>;
+  workerFactory?: (url: string, options: WorkerOptions) => Worker;
+  createObjectURL?: (blob: Blob) => string;
+  revokeObjectURL?: (url: string) => void;
+  Blob?: typeof Blob;
+}
+
+export function loadLockedPackageResources(
+  lockSource: string,
+  request?: typeof globalThis.fetch
+): Promise<Record<string, string>>;
+
+export function installLockedPackages(
+  runtime: Pick<HaraRuntime, "registerResource"> & Partial<Pick<HaraRuntime, "evalBytecodeBundle">>,
+  lockSource: string,
+  options?: LockedPackageOptions
+): Promise<string[]>;
+
+export function installPackageProvider(
+  runtime: HaraRuntime,
+  lockSource: string,
+  options?: LockedPackageOptions
+): { readonly active: ReadonlySet<string>; readonly handler: Function };
+
+export function disposeBrowserPackageProviders(runtime: HaraRuntime): Promise<void>;
+
+export function start(options?: StartOptions): Promise<HaraRuntime>;
+export const ready: Promise<HaraRuntime>;
+export default start;