@sanbus/galley 0.0.1

package/README.md

@@ -0,0 +1,14 @@
+# Universal Galley JavaScript Bindings
+
+`@sanbus/galley-core` over native libraries (Node, Bun, Deno) with WebAssembly
+fallback, selected per runtime. No native dependencies beyond the built
+parser artifacts.
+
+Call `await init()` once, then use the synchronous `Session` API; under
+Node and Bun the backend also resolves synchronously on first use. When no
+native library is found the WebAssembly backend serves instead (with a
+one-time performance notice), otherwise `init()` explains how to build one.
+
+See `docs/bindings_js_universal.md` for the consumer flow.
+
+One module embeds one parser; sessions are not thread-safe.

package/build.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * Single build entry for the Galley JavaScript bindings.
+ *
+ * Usage:
+ *   galley build <language-dir> [--native-only|--wasm-only]
+ *
+ * Builds both artifacts next to the grammar by default: the canonical
+ * shared native library (serves the Node, Bun, and Deno adapters) and the
+ * wasm module (serves browsers and the universal fallback leg). The
+ * per-adapter builders (`@sanbus/galley-node`, `@sanbus/galley-bun`,
+ * `@sanbus/galley-wasm`, the Deno `build.ts`) remain as thin wrappers over the
+ * same shared gate for single-leg builds.
+ *
+ * Environment: `ZIG_EXECUTABLE` (default `zig`) and `GALLEY_CHECKOUT`
+ * (required): an existing Galley working tree holding `build.zig`. To
+ * fetch a checkout for convenience, use
+ * `examples/scripts/fetch-galley.sh` (examples-only, not core).
+ */
+
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  NATIVE_LIBRARY_BASE,
+  WASM_LIBRARY_BASE,
+  buildParserArtifact,
+} from "@sanbus/galley-core/build/builder.mjs";
+
+function fatal(message) {
+  console.error(`galley-bindings: ${message}`);
+  process.exit(1);
+}
+
+const USAGE = "usage: galley build <language-dir> [--native-only|--wasm-only]";
+
+async function main() {
+  const argumentList = process.argv.slice(2);
+  if (argumentList.length < 2 || argumentList[0] !== "build") fatal(USAGE);
+  const flagList = argumentList.slice(2);
+  for (const flag of flagList) {
+    if (flag !== "--native-only" && flag !== "--wasm-only") fatal(`unknown flag ${flag}; ${USAGE}`);
+  }
+  const nativeOnly = flagList.includes("--native-only");
+  const wasmOnly = flagList.includes("--wasm-only");
+  if (nativeOnly && wasmOnly) fatal(`pass at most one of --native-only, --wasm-only; ${USAGE}`);
+
+  const languageDirectory = argumentList[1];
+  const bindingsDirectory = path.dirname(fileURLToPath(import.meta.url));
+  if (!wasmOnly) {
+    await buildParserArtifact({
+      languageDirectory,
+      libraryName: NATIVE_LIBRARY_BASE,
+      bindingsDirectory,
+      dependencyName: "@sanbus/galley-core",
+    });
+  }
+  if (!nativeOnly) {
+    await buildParserArtifact({
+      languageDirectory,
+      libraryName: WASM_LIBRARY_BASE,
+      wasm: true,
+      posixOnly: false,
+      bindingsDirectory,
+      dependencyName: "@sanbus/galley-core",
+    });
+  }
+}
+
+main().catch((error) => fatal(error?.message ?? String(error)));

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Universal Galley JavaScript bindings — public surface.
+ *
+ * One package for Node, Bun, Deno, and browsers over `@sanbus/galley-core`,
+ * with native-first backend selection and WebAssembly fallback. Call
+ * `await init()` once, then use the synchronous `Session` API; under Node
+ * and Bun the backend also resolves synchronously on first use.
+ */
+import { Session } from "./session.ts";
+export * from "@sanbus/galley-core";
+export { Session };
+export { init, backend, currentBackend, detectRuntime, type InitOptions, type Runtime, type Backend, } from "./loader.ts";
+export type { UniversalSessionOptions } from "./session.ts";
+export type { SessionOptions, WalkStep, Diagnostic, TreeSnapshot } from "@sanbus/galley-core";
+export declare function version(): string;
+export declare function parserType(): number;
+export declare function errorRecoveryMode(): number;
+export declare function hasAst(): boolean;
+export declare function hasProcedures(): boolean;
+export declare function allowsNoAstTreeProcedures(): boolean;
+export declare function sourceRetentionEnabled(): boolean;
+export declare function hasPositionTracking(): boolean;
+export declare function hasInputStreaming(): boolean;
+export declare function usesVerbatim(): boolean;
+export declare function stackOverflowRecoveryAvailable(): boolean;
+export declare function symbolCount(): number;
+export declare function variableCount(): number;
+export declare function statusString(status: number): string | null;
+export declare const has_ast: typeof hasAst;
+export declare const has_procedures: typeof hasProcedures;
+export declare const has_position_tracking: typeof hasPositionTracking;

package/dist/index.js

@@ -0,0 +1,62 @@
+/**
+ * Universal Galley JavaScript bindings — public surface.
+ *
+ * One package for Node, Bun, Deno, and browsers over `@sanbus/galley-core`,
+ * with native-first backend selection and WebAssembly fallback. Call
+ * `await init()` once, then use the synchronous `Session` API; under Node
+ * and Bun the backend also resolves synchronously on first use.
+ */
+import { ensureSync } from "./loader.js";
+import { Session } from "./session.js";
+// Core surface (Session base is shadowed by the adapter subclass below).
+export * from "@sanbus/galley-core";
+export { Session };
+export { init, backend, currentBackend, detectRuntime, } from "./loader.js";
+// Module-level queries (mirror galley.h)
+export function version() {
+    return ensureSync().version();
+}
+export function parserType() {
+    return ensureSync().parserType();
+}
+export function errorRecoveryMode() {
+    return ensureSync().errorRecoveryMode();
+}
+export function hasAst() {
+    return ensureSync().hasAst();
+}
+export function hasProcedures() {
+    return ensureSync().hasProcedures();
+}
+export function allowsNoAstTreeProcedures() {
+    return ensureSync().allowsNoAstTreeProcedures();
+}
+export function sourceRetentionEnabled() {
+    return ensureSync().sourceRetentionEnabled();
+}
+export function hasPositionTracking() {
+    return ensureSync().hasPositionTracking();
+}
+export function hasInputStreaming() {
+    return ensureSync().hasInputStreaming();
+}
+export function usesVerbatim() {
+    return ensureSync().usesVerbatim();
+}
+export function stackOverflowRecoveryAvailable() {
+    return ensureSync().stackOverflowRecoveryAvailable();
+}
+export function symbolCount() {
+    return ensureSync().symbolCount();
+}
+export function variableCount() {
+    return ensureSync().variableCount();
+}
+export function statusString(status) {
+    return ensureSync().statusString(status);
+}
+// Preserve original Python naming aliases for docs parity
+export const has_ast = hasAst;
+export const has_procedures = hasProcedures;
+export const has_position_tracking = hasPositionTracking;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,yEAAyE;AACzE,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,CAAC;AACnB,OAAO,EACL,IAAI,EACJ,OAAO,EACP,cAAc,EACd,aAAa,GAId,MAAM,aAAa,CAAC;AAIrB,yCAAyC;AACzC,MAAM,UAAU,OAAO;IACrB,OAAO,UAAU,EAAE,CAAC,OAAO,EAAE,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,OAAO,UAAU,EAAE,CAAC,UAAU,EAAE,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,OAAO,UAAU,EAAE,CAAC,iBAAiB,EAAE,CAAC;AAC1C,CAAC;AAED,MAAM,UAAU,MAAM;IACpB,OAAO,UAAU,EAAE,CAAC,MAAM,EAAE,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,OAAO,UAAU,EAAE,CAAC,aAAa,EAAE,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,yBAAyB;IACvC,OAAO,UAAU,EAAE,CAAC,yBAAyB,EAAE,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,sBAAsB;IACpC,OAAO,UAAU,EAAE,CAAC,sBAAsB,EAAE,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,OAAO,UAAU,EAAE,CAAC,mBAAmB,EAAE,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,OAAO,UAAU,EAAE,CAAC,iBAAiB,EAAE,CAAC;AAC1C,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,OAAO,UAAU,EAAE,CAAC,YAAY,EAAE,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,8BAA8B;IAC5C,OAAO,UAAU,EAAE,CAAC,8BAA8B,EAAE,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,WAAW;IACzB,OAAO,UAAU,EAAE,CAAC,WAAW,EAAE,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,OAAO,UAAU,EAAE,CAAC,aAAa,EAAE,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,OAAO,UAAU,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;AAC3C,CAAC;AAED,0DAA0D;AAC1D,MAAM,CAAC,MAAM,OAAO,GAAG,MAAM,CAAC;AAC9B,MAAM,CAAC,MAAM,cAAc,GAAG,aAAa,CAAC;AAC5C,MAAM,CAAC,MAAM,qBAAqB,GAAG,mBAAmB,CAAC"}

package/dist/loader.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Universal loader for the Galley JavaScript bindings.
+ *
+ * Binds the runtime-neutral `@sanbus/galley-core` to one of four backends —
+ * the Node, Bun, and Deno native adapters, or the WebAssembly adapter —
+ * selected per runtime with native-first ordering:
+ *
+ * - Node: koffi native → wasm → compile error.
+ * - Bun: `bun:ffi` native → wasm → compile error.
+ * - Deno: `Deno.dlopen` native → wasm → compile error.
+ * - Browser: wasm only.
+ *
+ * Adapters are imported dynamically by specifier string (never resolved
+ * statically), so bundlers only ever see the backends that are actually
+ * imported, and a backend missing from `node_modules` degrades to
+ * "unavailable" instead of failing the load. Each adapter resolves exactly
+ * one named artifact or throws `MissingArtifactError`; the loader catches
+ * exactly that class to try the next engine. A present-but-broken library
+ * throws anything else and fails loudly instead of silently falling back.
+ */
+import type { FfiPort } from "@sanbus/galley-core";
+export type Runtime = "node" | "bun" | "deno" | "browser";
+export type Backend = "native" | "wasm";
+export type NativeRuntime = "node" | "bun" | "deno";
+export interface InitOptions {
+    /** Grammar artifact path. A `.wasm` suffix forces the wasm backend. */
+    libraryPath?: string;
+    /** Explicit wasm module path (fallback source when native is missing). */
+    wasmPath?: string;
+    /** Module URL for `fetch` (browsers). */
+    url?: string | URL;
+    /** Raw module bytes (browsers, tests). */
+    wasmBytes?: Uint8Array;
+    /** Suppress the one-time WebAssembly performance notice. */
+    quiet?: boolean;
+}
+/** Detect the current JavaScript runtime. Bun and Deno are checked before
+ * Node: Bun emulates `process.versions.node`. */
+export declare function detectRuntime(): Runtime;
+/** A resolved backend: the port plus which leg of the chain served it. */
+export interface ResolvedBackend {
+    port: FfiPort;
+    backend: Backend;
+}
+/**
+ * Resolve and initialize the backend for `options`, caching the result.
+ * Order: explicit `.wasm` path pins wasm; otherwise native first, then
+ * wasm discovery, then a compile-guidance error. Browsers skip native
+ * attempts (no FFI); non-Node runtimes without a prior `init()` cannot
+ * synchronously initialize wasm and surface the adapter's NeedInitError.
+ */
+export declare function init(options?: InitOptions): Promise<ResolvedBackend>;
+/** The initialized backend, or null when `init()` has not completed. */
+export declare function currentBackend(): ResolvedBackend | null;
+/** Backend selected by the last `init()` (`"native"`, `"wasm"`, or null). */
+export declare function backend(): Backend | null;
+/**
+ * Synchronous resolution for Node and Bun (dynamic `import()` is async,
+ * so other runtimes must `await init()` first). Used by the `Session`
+ * constructor and module-level queries.
+ */
+export declare function ensureSync(options?: InitOptions): FfiPort;
+/** Test-only: clear cached resolution and the fallback notice. */
+export declare function __resetLoader(): void;

package/dist/loader.js

@@ -0,0 +1,261 @@
+/**
+ * Universal loader for the Galley JavaScript bindings.
+ *
+ * Binds the runtime-neutral `@sanbus/galley-core` to one of four backends —
+ * the Node, Bun, and Deno native adapters, or the WebAssembly adapter —
+ * selected per runtime with native-first ordering:
+ *
+ * - Node: koffi native → wasm → compile error.
+ * - Bun: `bun:ffi` native → wasm → compile error.
+ * - Deno: `Deno.dlopen` native → wasm → compile error.
+ * - Browser: wasm only.
+ *
+ * Adapters are imported dynamically by specifier string (never resolved
+ * statically), so bundlers only ever see the backends that are actually
+ * imported, and a backend missing from `node_modules` degrades to
+ * "unavailable" instead of failing the load. Each adapter resolves exactly
+ * one named artifact or throws `MissingArtifactError`; the loader catches
+ * exactly that class to try the next engine. A present-but-broken library
+ * throws anything else and fails loudly instead of silently falling back.
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { createRequire } from "node:module";
+import { MissingArtifactError } from "@sanbus/galley-core";
+/** Detect the current JavaScript runtime. Bun and Deno are checked before
+ * Node: Bun emulates `process.versions.node`. */
+export function detectRuntime() {
+    const globals = globalThis;
+    if (typeof globals.Bun !== "undefined")
+        return "bun";
+    if (typeof globals.Deno !== "undefined")
+        return "deno";
+    const processValue = globals.process;
+    if (typeof processValue !== "undefined" && typeof processValue.versions?.node === "string") {
+        return "node";
+    }
+    return "browser";
+}
+const NATIVE_ADAPTERS = {
+    node: { module: "@sanbus/galley-node", port: "getNodePort" },
+    bun: { module: "@sanbus/galley-bun", port: "getBunPort" },
+    deno: { module: "@sanbus/galley-deno", port: "getDenoPort" },
+};
+const WASM_MODULE = "@sanbus/galley-wasm";
+function isWasmPath(value) {
+    return !!value && value.toLowerCase().endsWith(".wasm");
+}
+async function loadNativeAdapter(runtime) {
+    const { module: specifier, port } = NATIVE_ADAPTERS[runtime];
+    let loaded;
+    try {
+        // Specifier is a string on purpose: bundlers must not statically
+        // resolve backends that may be absent, and tsc must not require
+        // their type declarations to exist yet.
+        loaded = (await import(__rewriteRelativeImportExtension(specifier)));
+    }
+    catch {
+        return null;
+    }
+    const getPort = loaded[port];
+    if (typeof getPort !== "function")
+        return null;
+    return { getPort: getPort };
+}
+async function loadWasmAdapter() {
+    try {
+        const loaded = (await import(__rewriteRelativeImportExtension(WASM_MODULE)));
+        if (typeof loaded["init"] !== "function" ||
+            typeof loaded["getWasmPort"] !== "function" ||
+            typeof loaded["NeedInitError"] !== "function") {
+            return null;
+        }
+        return loaded;
+    }
+    catch {
+        return null;
+    }
+}
+let ready = null;
+let warnedWasm = false;
+function compileGuidance() {
+    return new Error("galley: no parser artifact found (tried native library, then WebAssembly).\n" +
+        "Build one first: npx galley build <language-dir>\n" +
+        "or set GALLEY_LIBRARY_PATH to the built artifact.");
+}
+function noteWasmFallback(quiet) {
+    if (quiet || warnedWasm)
+        return;
+    warnedWasm = true;
+    console.warn("galley: using the WebAssembly backend (no native library found); " +
+        "throughput trails native codegen (roughly three quarters). " +
+        "Build a native library for full speed. Silence with { quiet: true }.");
+}
+/** Try the native leg. A missing artifact yields null; a present-but-broken
+ * library throws loudly (an ABI mismatch is a user error, not a
+ * fallback case). */
+async function tryNative(runtime, libraryPath) {
+    const adapter = await loadNativeAdapter(runtime);
+    if (!adapter)
+        return null;
+    try {
+        return adapter.getPort(libraryPath);
+    }
+    catch (error) {
+        if (MissingArtifactError.is(error))
+            return null;
+        throw error;
+    }
+}
+/** Try the wasm leg through the shared adapter. */
+async function tryWasm(options) {
+    const wasm = await loadWasmAdapter();
+    if (!wasm)
+        return null;
+    const explicit = options.wasmPath ?? (isWasmPath(options.libraryPath) ? options.libraryPath : undefined);
+    try {
+        await wasm.init({ libraryPath: explicit, url: options.url, bytes: options.wasmBytes });
+    }
+    catch (error) {
+        if (error instanceof wasm.NeedInitError)
+            throw error;
+        if (MissingArtifactError.is(error))
+            return null;
+        throw error;
+    }
+    return wasm.getWasmPort(explicit);
+}
+/**
+ * Resolve and initialize the backend for `options`, caching the result.
+ * Order: explicit `.wasm` path pins wasm; otherwise native first, then
+ * wasm discovery, then a compile-guidance error. Browsers skip native
+ * attempts (no FFI); non-Node runtimes without a prior `init()` cannot
+ * synchronously initialize wasm and surface the adapter's NeedInitError.
+ */
+export async function init(options = {}) {
+    const runtime = detectRuntime();
+    if (isWasmPath(options.libraryPath)) {
+        const wasm = await loadWasmAdapter();
+        if (!wasm)
+            throw compileGuidance();
+        await wasm.init({ libraryPath: options.libraryPath, url: options.url, bytes: options.wasmBytes });
+        noteWasmFallback(options.quiet);
+        ready = { port: wasm.getWasmPort(options.libraryPath), backend: "wasm" };
+        return ready;
+    }
+    if (runtime !== "browser") {
+        const native = await tryNative(runtime, options.libraryPath);
+        if (native) {
+            ready = { port: native, backend: "native" };
+            return ready;
+        }
+    }
+    const wasmPort = await tryWasm(options);
+    if (wasmPort) {
+        noteWasmFallback(options.quiet);
+        ready = { port: wasmPort, backend: "wasm" };
+        return ready;
+    }
+    throw compileGuidance();
+}
+/** The initialized backend, or null when `init()` has not completed. */
+export function currentBackend() {
+    return ready;
+}
+/** Backend selected by the last `init()` (`"native"`, `"wasm"`, or null). */
+export function backend() {
+    return ready?.backend ?? null;
+}
+/**
+ * Synchronous resolution for Node and Bun (dynamic `import()` is async,
+ * so other runtimes must `await init()` first). Used by the `Session`
+ * constructor and module-level queries.
+ */
+export function ensureSync(options = {}) {
+    if (ready && !options.libraryPath && !options.wasmPath && !options.url && !options.wasmBytes) {
+        return ready.port;
+    }
+    const runtime = detectRuntime();
+    if (runtime !== "node" && runtime !== "bun") {
+        throw new Error("galley: call await init() before using the bindings on this runtime; " +
+            "synchronous initialization is only available under Node and Bun.");
+    }
+    if (!isWasmPath(options.libraryPath)) {
+        const native = tryNativeSync(runtime, options.libraryPath);
+        if (native) {
+            ready = { port: native, backend: "native" };
+            return native;
+        }
+    }
+    const wasmPort = tryWasmSync(options);
+    if (wasmPort) {
+        noteWasmFallback(options.quiet);
+        ready = { port: wasmPort, backend: "wasm" };
+        return wasmPort;
+    }
+    throw compileGuidance();
+}
+function requireAdapterModule(specifier) {
+    try {
+        // Synchronous require: this branch runs under Node and Bun only.
+        // Falls back to null when the package is absent.
+        const require = createRequire(import.meta.url);
+        return require(specifier);
+    }
+    catch {
+        return null;
+    }
+}
+/** Synchronous native attempt (Node/Bun only). */
+function tryNativeSync(runtime, libraryPath) {
+    const { module: specifier, port } = NATIVE_ADAPTERS[runtime];
+    const loaded = requireAdapterModule(specifier);
+    if (!loaded)
+        return null;
+    const getPort = loaded[port];
+    if (typeof getPort !== "function")
+        return null;
+    try {
+        return getPort(libraryPath);
+    }
+    catch (error) {
+        if (MissingArtifactError.is(error))
+            return null;
+        throw error;
+    }
+}
+/** Synchronous wasm attempt through the shared adapter (Node/Bun only:
+ * the wasm adapter reads files and instantiates synchronously there). */
+function tryWasmSync(options) {
+    const loaded = requireAdapterModule(WASM_MODULE);
+    if (!loaded || typeof loaded["initSync"] !== "function")
+        return null;
+    const wasm = loaded;
+    const explicit = options.wasmPath ?? (isWasmPath(options.libraryPath) ? options.libraryPath : undefined);
+    if (options.url !== undefined && options.wasmBytes === undefined)
+        return null;
+    try {
+        wasm.initSync({ libraryPath: explicit, bytes: options.wasmBytes });
+    }
+    catch (error) {
+        if (MissingArtifactError.is(error))
+            return null;
+        throw error;
+    }
+    const getWasmPort = loaded["getWasmPort"];
+    if (typeof getWasmPort !== "function")
+        return null;
+    return getWasmPort(explicit);
+}
+/** Test-only: clear cached resolution and the fallback notice. */
+export function __resetLoader() {
+    ready = null;
+    warnedWasm = false;
+}
+//# sourceMappingURL=loader.js.map

package/dist/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"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"}

package/dist/session.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Universal `Session`: the core session bound to the resolved backend.
+ *
+ * Under Node and Bun the backend resolves synchronously on first use;
+ * elsewhere `await init()` must complete first.
+ */
+import { Session as CoreSession } from "@sanbus/galley-core";
+import type { SessionOptions } from "@sanbus/galley-core";
+import { type InitOptions } from "./loader.ts";
+export type UniversalSessionOptions = SessionOptions & InitOptions;
+export type { SessionOptions };
+export declare class Session extends CoreSession {
+    constructor(options?: UniversalSessionOptions);
+}

package/dist/session.js

@@ -0,0 +1,14 @@
+/**
+ * Universal `Session`: the core session bound to the resolved backend.
+ *
+ * Under Node and Bun the backend resolves synchronously on first use;
+ * elsewhere `await init()` must complete first.
+ */
+import { Session as CoreSession } from "@sanbus/galley-core";
+import { ensureSync } from "./loader.js";
+export class Session extends CoreSession {
+    constructor(options = {}) {
+        super(ensureSync(options), options);
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAE7D,OAAO,EAAE,UAAU,EAAoB,MAAM,aAAa,CAAC;AAK3D,MAAM,OAAO,OAAQ,SAAQ,WAAW;IACtC,YAAY,OAAO,GAA4B,EAAE;QAC/C,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC;CACF"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@sanbus/galley",
+  "version": "0.0.1",
+  "description": "Universal Galley JavaScript bindings: one package for Node, Bun, Deno, and browsers over @sanbus/galley-core, with native-first backend selection and WebAssembly fallback",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "build.mjs",
+    "README.md"
+  ],
+  "bin": {
+    "galley": "./build.mjs"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepare": "tsc -p tsconfig.json --noCheck --types \"\"",
+    "prepublishOnly": "npm run build",
+    "test": "node tests/test_loader.mjs"
+  },
+  "keywords": [
+    "galley",
+    "parser",
+    "javascript",
+    "typescript",
+    "ffi",
+    "wasm"
+  ],
+  "dependencies": {
+    "@sanbus/galley-core": "0.0.1",
+    "@sanbus/galley-node": "0.0.1",
+    "@sanbus/galley-bun": "0.0.1",
+    "@sanbus/galley-deno": "0.0.1",
+    "@sanbus/galley-wasm": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/src/index.ts

@@ -0,0 +1,88 @@
+/**
+ * Universal Galley JavaScript bindings — public surface.
+ *
+ * One package for Node, Bun, Deno, and browsers over `@sanbus/galley-core`,
+ * with native-first backend selection and WebAssembly fallback. Call
+ * `await init()` once, then use the synchronous `Session` API; under Node
+ * and Bun the backend also resolves synchronously on first use.
+ */
+
+import { ensureSync } from "./loader.ts";
+import { Session } from "./session.ts";
+
+// Core surface (Session base is shadowed by the adapter subclass below).
+export * from "@sanbus/galley-core";
+export { Session };
+export {
+  init,
+  backend,
+  currentBackend,
+  detectRuntime,
+  type InitOptions,
+  type Runtime,
+  type Backend,
+} from "./loader.ts";
+export type { UniversalSessionOptions } from "./session.ts";
+export type { SessionOptions, WalkStep, Diagnostic, TreeSnapshot } from "@sanbus/galley-core";
+
+// Module-level queries (mirror galley.h)
+export function version(): string {
+  return ensureSync().version();
+}
+
+export function parserType(): number {
+  return ensureSync().parserType();
+}
+
+export function errorRecoveryMode(): number {
+  return ensureSync().errorRecoveryMode();
+}
+
+export function hasAst(): boolean {
+  return ensureSync().hasAst();
+}
+
+export function hasProcedures(): boolean {
+  return ensureSync().hasProcedures();
+}
+
+export function allowsNoAstTreeProcedures(): boolean {
+  return ensureSync().allowsNoAstTreeProcedures();
+}
+
+export function sourceRetentionEnabled(): boolean {
+  return ensureSync().sourceRetentionEnabled();
+}
+
+export function hasPositionTracking(): boolean {
+  return ensureSync().hasPositionTracking();
+}
+
+export function hasInputStreaming(): boolean {
+  return ensureSync().hasInputStreaming();
+}
+
+export function usesVerbatim(): boolean {
+  return ensureSync().usesVerbatim();
+}
+
+export function stackOverflowRecoveryAvailable(): boolean {
+  return ensureSync().stackOverflowRecoveryAvailable();
+}
+
+export function symbolCount(): number {
+  return ensureSync().symbolCount();
+}
+
+export function variableCount(): number {
+  return ensureSync().variableCount();
+}
+
+export function statusString(status: number): string | null {
+  return ensureSync().statusString(status);
+}
+
+// Preserve original Python naming aliases for docs parity
+export const has_ast = hasAst;
+export const has_procedures = hasProcedures;
+export const has_position_tracking = hasPositionTracking;

package/src/loader.ts

@@ -0,0 +1,295 @@
+/**
+ * Universal loader for the Galley JavaScript bindings.
+ *
+ * Binds the runtime-neutral `@sanbus/galley-core` to one of four backends —
+ * the Node, Bun, and Deno native adapters, or the WebAssembly adapter —
+ * selected per runtime with native-first ordering:
+ *
+ * - Node: koffi native → wasm → compile error.
+ * - Bun: `bun:ffi` native → wasm → compile error.
+ * - Deno: `Deno.dlopen` native → wasm → compile error.
+ * - Browser: wasm only.
+ *
+ * Adapters are imported dynamically by specifier string (never resolved
+ * statically), so bundlers only ever see the backends that are actually
+ * imported, and a backend missing from `node_modules` degrades to
+ * "unavailable" instead of failing the load. Each adapter resolves exactly
+ * one named artifact or throws `MissingArtifactError`; the loader catches
+ * exactly that class to try the next engine. A present-but-broken library
+ * throws anything else and fails loudly instead of silently falling back.
+ */
+
+import { createRequire } from "node:module";
+import type { FfiPort } from "@sanbus/galley-core";
+import { MissingArtifactError } from "@sanbus/galley-core";
+
+export type Runtime = "node" | "bun" | "deno" | "browser";
+export type Backend = "native" | "wasm";
+export type NativeRuntime = "node" | "bun" | "deno";
+
+export interface InitOptions {
+  /** Grammar artifact path. A `.wasm` suffix forces the wasm backend. */
+  libraryPath?: string;
+  /** Explicit wasm module path (fallback source when native is missing). */
+  wasmPath?: string;
+  /** Module URL for `fetch` (browsers). */
+  url?: string | URL;
+  /** Raw module bytes (browsers, tests). */
+  wasmBytes?: Uint8Array;
+  /** Suppress the one-time WebAssembly performance notice. */
+  quiet?: boolean;
+}
+
+/** Detect the current JavaScript runtime. Bun and Deno are checked before
+ * Node: Bun emulates `process.versions.node`. */
+export function detectRuntime(): Runtime {
+  const globals = globalThis as Record<string, unknown>;
+  if (typeof globals.Bun !== "undefined") return "bun";
+  if (typeof globals.Deno !== "undefined") return "deno";
+  const processValue = globals.process as { versions?: { node?: unknown } } | undefined;
+  if (typeof processValue !== "undefined" && typeof processValue.versions?.node === "string") {
+    return "node";
+  }
+  return "browser";
+}
+
+interface NativeAdapter {
+  getPort(explicit?: string): FfiPort;
+}
+
+interface WasmAdapter {
+  init(options?: { libraryPath?: string; url?: string | URL; bytes?: Uint8Array }): Promise<void>;
+  initSync(options?: { libraryPath?: string; bytes?: Uint8Array }): void;
+  getWasmPort(libraryPath?: string): FfiPort;
+  NeedInitError: new (...args: Array<never>) => Error;
+}
+
+const NATIVE_ADAPTERS: Record<NativeRuntime, { module: string; port: string }> = {
+  node: { module: "@sanbus/galley-node", port: "getNodePort" },
+  bun: { module: "@sanbus/galley-bun", port: "getBunPort" },
+  deno: { module: "@sanbus/galley-deno", port: "getDenoPort" },
+};
+const WASM_MODULE = "@sanbus/galley-wasm";
+
+function isWasmPath(value: string | undefined): boolean {
+  return !!value && value.toLowerCase().endsWith(".wasm");
+}
+
+async function loadNativeAdapter(runtime: NativeRuntime): Promise<NativeAdapter | null> {
+  const { module: specifier, port } = NATIVE_ADAPTERS[runtime];
+  let loaded: Record<string, unknown>;
+  try {
+    // Specifier is a string on purpose: bundlers must not statically
+    // resolve backends that may be absent, and tsc must not require
+    // their type declarations to exist yet.
+    loaded = (await import(specifier)) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+  const getPort = loaded[port];
+  if (typeof getPort !== "function") return null;
+  return { getPort: getPort as NativeAdapter["getPort"] };
+}
+
+async function loadWasmAdapter(): Promise<WasmAdapter | null> {
+  try {
+    const loaded = (await import(WASM_MODULE)) as Record<string, unknown>;
+    if (
+      typeof loaded["init"] !== "function" ||
+      typeof loaded["getWasmPort"] !== "function" ||
+      typeof loaded["NeedInitError"] !== "function"
+    ) {
+      return null;
+    }
+    return loaded as unknown as WasmAdapter;
+  } catch {
+    return null;
+  }
+}
+
+/** A resolved backend: the port plus which leg of the chain served it. */
+export interface ResolvedBackend {
+  port: FfiPort;
+  backend: Backend;
+}
+
+let ready: ResolvedBackend | null = null;
+let warnedWasm = false;
+
+function compileGuidance(): Error {
+  return new Error(
+    "galley: no parser artifact found (tried native library, then WebAssembly).\n" +
+      "Build one first: npx galley build <language-dir>\n" +
+      "or set GALLEY_LIBRARY_PATH to the built artifact.",
+  );
+}
+
+function noteWasmFallback(quiet: boolean | undefined): void {
+  if (quiet || warnedWasm) return;
+  warnedWasm = true;
+  console.warn(
+    "galley: using the WebAssembly backend (no native library found); " +
+      "throughput trails native codegen (roughly three quarters). " +
+      "Build a native library for full speed. Silence with { quiet: true }.",
+  );
+}
+
+/** Try the native leg. A missing artifact yields null; a present-but-broken
+ * library throws loudly (an ABI mismatch is a user error, not a
+ * fallback case). */
+async function tryNative(
+  runtime: NativeRuntime,
+  libraryPath: string | undefined,
+): Promise<FfiPort | null> {
+  const adapter = await loadNativeAdapter(runtime);
+  if (!adapter) return null;
+  try {
+    return adapter.getPort(libraryPath);
+  } catch (error) {
+    if (MissingArtifactError.is(error)) return null;
+    throw error;
+  }
+}
+
+/** Try the wasm leg through the shared adapter. */
+async function tryWasm(options: InitOptions): Promise<FfiPort | null> {
+  const wasm = await loadWasmAdapter();
+  if (!wasm) return null;
+  const explicit = options.wasmPath ?? (isWasmPath(options.libraryPath) ? options.libraryPath : undefined);
+  try {
+    await wasm.init({ libraryPath: explicit, url: options.url, bytes: options.wasmBytes });
+  } catch (error) {
+    if (error instanceof wasm.NeedInitError) throw error;
+    if (MissingArtifactError.is(error)) return null;
+    throw error;
+  }
+  return wasm.getWasmPort(explicit);
+}
+
+/**
+ * Resolve and initialize the backend for `options`, caching the result.
+ * Order: explicit `.wasm` path pins wasm; otherwise native first, then
+ * wasm discovery, then a compile-guidance error. Browsers skip native
+ * attempts (no FFI); non-Node runtimes without a prior `init()` cannot
+ * synchronously initialize wasm and surface the adapter's NeedInitError.
+ */
+export async function init(options: InitOptions = {}): Promise<ResolvedBackend> {
+  const runtime = detectRuntime();
+  if (isWasmPath(options.libraryPath)) {
+    const wasm = await loadWasmAdapter();
+    if (!wasm) throw compileGuidance();
+    await wasm.init({ libraryPath: options.libraryPath, url: options.url, bytes: options.wasmBytes });
+    noteWasmFallback(options.quiet);
+    ready = { port: wasm.getWasmPort(options.libraryPath), backend: "wasm" };
+    return ready;
+  }
+  if (runtime !== "browser") {
+    const native = await tryNative(runtime, options.libraryPath);
+    if (native) {
+      ready = { port: native, backend: "native" };
+      return ready;
+    }
+  }
+  const wasmPort = await tryWasm(options);
+  if (wasmPort) {
+    noteWasmFallback(options.quiet);
+    ready = { port: wasmPort, backend: "wasm" };
+    return ready;
+  }
+  throw compileGuidance();
+}
+
+/** The initialized backend, or null when `init()` has not completed. */
+export function currentBackend(): ResolvedBackend | null {
+  return ready;
+}
+
+/** Backend selected by the last `init()` (`"native"`, `"wasm"`, or null). */
+export function backend(): Backend | null {
+  return ready?.backend ?? null;
+}
+
+/**
+ * Synchronous resolution for Node and Bun (dynamic `import()` is async,
+ * so other runtimes must `await init()` first). Used by the `Session`
+ * constructor and module-level queries.
+ */
+export function ensureSync(options: InitOptions = {}): FfiPort {
+  if (ready && !options.libraryPath && !options.wasmPath && !options.url && !options.wasmBytes) {
+    return ready.port;
+  }
+  const runtime = detectRuntime();
+  if (runtime !== "node" && runtime !== "bun") {
+    throw new Error(
+      "galley: call await init() before using the bindings on this runtime; " +
+        "synchronous initialization is only available under Node and Bun.",
+    );
+  }
+  if (!isWasmPath(options.libraryPath)) {
+    const native = tryNativeSync(runtime, options.libraryPath);
+    if (native) {
+      ready = { port: native, backend: "native" };
+      return native;
+    }
+  }
+  const wasmPort = tryWasmSync(options);
+  if (wasmPort) {
+    noteWasmFallback(options.quiet);
+    ready = { port: wasmPort, backend: "wasm" };
+    return wasmPort;
+  }
+  throw compileGuidance();
+}
+
+function requireAdapterModule(specifier: string): Record<string, unknown> | null {
+  try {
+    // Synchronous require: this branch runs under Node and Bun only.
+    // Falls back to null when the package is absent.
+    const require = createRequire(import.meta.url);
+    return require(specifier) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+/** Synchronous native attempt (Node/Bun only). */
+function tryNativeSync(runtime: NativeRuntime, libraryPath: string | undefined): FfiPort | null {
+  const { module: specifier, port } = NATIVE_ADAPTERS[runtime];
+  const loaded = requireAdapterModule(specifier);
+  if (!loaded) return null;
+  const getPort = loaded[port];
+  if (typeof getPort !== "function") return null;
+  try {
+    return (getPort as NativeAdapter["getPort"])(libraryPath);
+  } catch (error) {
+    if (MissingArtifactError.is(error)) return null;
+    throw error;
+  }
+}
+
+/** Synchronous wasm attempt through the shared adapter (Node/Bun only:
+ * the wasm adapter reads files and instantiates synchronously there). */
+function tryWasmSync(options: InitOptions): FfiPort | null {
+  const loaded = requireAdapterModule(WASM_MODULE);
+  if (!loaded || typeof loaded["initSync"] !== "function") return null;
+  const wasm = loaded as unknown as WasmAdapter & {
+    initSync(options?: { libraryPath?: string; bytes?: Uint8Array }): void;
+  };
+  const explicit = options.wasmPath ?? (isWasmPath(options.libraryPath) ? options.libraryPath : undefined);
+  if (options.url !== undefined && options.wasmBytes === undefined) return null;
+  try {
+    wasm.initSync({ libraryPath: explicit, bytes: options.wasmBytes });
+  } catch (error) {
+    if (MissingArtifactError.is(error)) return null;
+    throw error;
+  }
+  const getWasmPort = loaded["getWasmPort"];
+  if (typeof getWasmPort !== "function") return null;
+  return (getWasmPort as WasmAdapter["getWasmPort"])(explicit);
+}
+
+/** Test-only: clear cached resolution and the fallback notice. */
+export function __resetLoader(): void {
+  ready = null;
+  warnedWasm = false;
+}

package/src/session.ts

@@ -0,0 +1,19 @@
+/**
+ * Universal `Session`: the core session bound to the resolved backend.
+ *
+ * Under Node and Bun the backend resolves synchronously on first use;
+ * elsewhere `await init()` must complete first.
+ */
+
+import { Session as CoreSession } from "@sanbus/galley-core";
+import type { SessionOptions } from "@sanbus/galley-core";
+import { ensureSync, type InitOptions } from "./loader.ts";
+
+export type UniversalSessionOptions = SessionOptions & InitOptions;
+export type { SessionOptions };
+
+export class Session extends CoreSession {
+  constructor(options: UniversalSessionOptions = {}) {
+    super(ensureSync(options), options);
+  }
+}