@fossil-lang/wasm 0.3.0-alpha.1

package/README.md

@@ -0,0 +1,70 @@
+# @fossil-lang/wasm
+
+JS/TS wrapper around the `fossil-wasm` Rust crate's wasm-bindgen artefacts. Provides:
+
+- `initFossilWasm({ wasmUrl })` — consumer-controlled `.wasm` URL loader (memoised).
+- `tokenize(text)` — calls the Rust lexer, returns `TokenRow[]` (ADR-0030).
+- `semanticLegend()` — returns the LSP semantic-tokens legend (Phase 6 plan 06-07).
+- `FossilPlayground` — the Workspace API class (ADR-0024) for LSP + compile.
+
+## Why explicit `init({ wasmUrl })` and not auto-load?
+
+We use `wasm-bindgen --target web` (NOT `--target bundler`). This means consumers
+control the `.wasm` URL resolution — works in Vite, Next.js, Webpack, Rspack, or
+plain `new URL(...)` in a Web Worker context. See `08-RESEARCH.md` Pitfall 1
+(this monorepo's phase-8 research) for why `--target bundler` was rejected.
+
+## Consumer patterns
+
+### Vite host
+
+```typescript
+import { initFossilWasm, tokenize } from '@fossil-lang/wasm';
+import wasmUrl from '@fossil-lang/wasm/pkg/fossil_wasm_bg.wasm?url';
+
+await initFossilWasm({ wasmUrl });
+const tokens = tokenize('prefix ex: <https://example.org/>');
+```
+
+### Next.js host (in a Client Component)
+
+```typescript
+'use client';
+import { initFossilWasm, tokenize } from '@fossil-lang/wasm';
+
+// Put fossil_wasm_bg.wasm in public/wasm/ at build time (next.config.mjs copies it)
+useEffect(() => {
+  void initFossilWasm({ wasmUrl: '/wasm/fossil_wasm_bg.wasm' });
+}, []);
+```
+
+### Web Worker
+
+```typescript
+// inside a Worker module:
+import { initFossilWasm, FossilPlayground } from '@fossil-lang/wasm';
+import wasmUrl from '@fossil-lang/wasm/pkg/fossil_wasm_bg.wasm?url';
+
+await initFossilWasm({ wasmUrl });
+const pg = new FossilPlayground();
+```
+
+## Build
+
+```bash
+# From repo root
+pnpm --filter @fossil-lang/wasm build:wasm   # → packages/wasm/pkg/
+pnpm --filter @fossil-lang/wasm build         # = build:wasm + tsc
+```
+
+Requires: Rust 1.90 toolchain (per `rust-toolchain.toml` at repo root) +
+`wasm-bindgen-cli` 0.2.120 (`cargo install --version 0.2.120 wasm-bindgen-cli`).
+Optionally `wasm-opt` (binaryen) for size reduction.
+
+## Source of truth
+
+- Rust crate: `crates/fossil-wasm/`
+- tokenize ADR: `decisions/0030-wasm-exported-tokenizer.md`
+- Workspace API ADR: `decisions/0024-fossil-wasm-workspace-api.md`
+- Distribution pattern: `decisions/0028-playground-as-react-library.md`
+  (this package is one of the six in the `@fossil-lang/*` family)

package/dist/index.d.ts

@@ -0,0 +1,246 @@
+/**
+ * @fossil-lang/wasm — JS/TS wrapper around the fossil-wasm wasm-bindgen artifacts.
+ *
+ * Public API (one of the six @fossil-lang/* packages per ADR-0028):
+ * - {@link initFossilWasm} — consumer-controlled .wasm URL loader (memoised).
+ * - {@link tokenize} — calls the Rust lexer, returns TokenRow[] (ADR-0030).
+ * - {@link semanticLegend} — returns the LSP SemanticTokensLegend (Phase-6 06-07).
+ * - {@link FossilPlayground} — Workspace API class (ADR-0024) for the LSP.
+ *
+ * Consumer pattern (wasm-bindgen --target web — RESEARCH.md Pattern 3):
+ *
+ *   import { initFossilWasm, tokenize } from '@fossil-lang/wasm';
+ *   import wasmUrl from '@fossil-lang/wasm/pkg/fossil_wasm_bg.wasm?url';  // Vite
+ *
+ *   await initFossilWasm({ wasmUrl });
+ *   const tokens = tokenize('prefix ex: <https://example.org/>');
+ */
+import { FileHandle as RawFileHandle } from '../pkg/fossil_wasm.js';
+import type { TokenRow, SemanticTokensLegend } from '@fossil-lang/types';
+export { initFossilWasm } from './load.js';
+export type { InitFossilWasmOpts } from './load.js';
+/**
+ * Install the LSP-over-postMessage dispatcher on the current Worker scope.
+ *
+ * Per ADR-0024 (`fossil-wasm` IS the LSP server-side) + Phase 7 plan 07-03
+ * (the 16-route dispatch loop). The Rust function (re-exported from
+ * `crates/fossil-wasm/src/lsp_worker.rs`) installs `self.onmessage` on the
+ * Worker scope and owns LSP JSON-RPC dispatch from that point forward —
+ * including per-file `textDocument/publishDiagnostics` drains (B3 fix from
+ * 07-03), `textDocument/semanticTokens/full` (06-07), hover, completion,
+ * definition, references, rename, formatting, code actions, document
+ * symbols, signature help.
+ *
+ * MUST be called inside a Web Worker scope, AFTER {@link initFossilWasm} has
+ * resolved. Calling it on the main thread is a no-op (the dispatcher needs
+ * `DedicatedWorkerGlobalScope.onmessage`).
+ *
+ * Consumed by `@fossil-lang/playground`'s `src/workers/lsp.worker.ts` —
+ * the React component's LSP Worker entry boots the WASM module then calls
+ * this function once.
+ */
+export declare function start_lsp_worker(): void;
+/**
+ * Opaque file-handle returned by {@link FossilPlayground.openFile}. Pass it
+ * back into the matching `updateFile` / `closeFile` / `diagnosticsFor`
+ * calls. JS code cannot construct one directly (the wasm-bindgen
+ * class has a private constructor) — that is intentional per ADR-0024:
+ * handles are minted only by `openFile` on the Rust side, where they index a
+ * `HashMap<FileHandle, SourceFile>` keyed by a `u32` newtype.
+ */
+export type FileHandle = RawFileHandle;
+/**
+ * Tokenize a Fossil source string. Returns the byte-range tokens from the
+ * canonical Rust lexer (`fossil_syntax::lexer::raw_lex`) — single grammar
+ * source of truth per ADR-0030.
+ *
+ * MUST be called after {@link initFossilWasm} has resolved; otherwise the
+ * underlying wasm-bindgen function throws (the wasm module is not yet
+ * instantiated).
+ */
+export declare function tokenize(text: string): TokenRow[];
+/**
+ * Returns the LSP `SemanticTokensLegend` (token types + modifiers list) the
+ * editor uses to map LSP `semanticTokens/full` response indices to highlight
+ * categories. Re-export of `fossil_ide::semantic_legend` (Phase-6 06-07) over
+ * the wasm-bindgen boundary — NO duplicate legend definition lives here.
+ *
+ * MUST be called after {@link initFossilWasm} has resolved.
+ */
+export declare function semanticLegend(): SemanticTokensLegend;
+/** Diagnostic row returned by {@link FossilPlayground.check} and
+ *  {@link FossilPlayground.diagnosticsFor} — mirrors `fossil-wasm`'s
+ *  `CheckRow` JSON shape (the LSP `Diagnostic` projected through
+ *  `fossil_ide::LineIndex` for UTF-16 ranges).
+ */
+export interface CheckRow {
+    uri: string;
+    range: {
+        start: {
+            line: number;
+            character: number;
+        };
+        end: {
+            line: number;
+            character: number;
+        };
+    };
+    severity: number;
+    message: string;
+}
+/** Stdlib classification entry returned by {@link FossilPlayground.classification}.
+ *  `wasm_class` indicates whether a stdlib function can execute in-browser
+ *  (`"pure_sql"`) or requires the native runtime (`"native_udf_only"`). The
+ *  playground reads this once at startup to render `native_udf_only` functions
+ *  as disabled (STDL-07 / SC#1 playground half).
+ */
+export interface StdlibClass {
+    name: string;
+    wasm_class: 'pure_sql' | 'native_udf_only';
+}
+/**
+ * Canonical primitive names for inferred-descriptor columns. Must match the
+ * lookup table in `fossil-hir::infer::primitive_from_name` (ADR-0037). Names
+ * map 1:1 to the `Primitive` enum in HIR (Integer, Float, String, Bool, Date,
+ * DateTime, Time, GYear, AnyURI).
+ *
+ * Unknown / non-canonical strings are accepted on the wire — the Rust side
+ * coerces them to `String` and emits a `D-INFERRED-UNKNOWN-DATATYPE`
+ * diagnostic. Hosts SHOULD canonicalise their DuckDB `DESCRIBE` output to
+ * these names before registering.
+ */
+export type InferredPrimitive = 'String' | 'Integer' | 'Float' | 'Bool' | 'Date' | 'DateTime' | 'Time' | 'GYear' | 'AnyURI';
+/** One column from a host-introspected source. */
+export interface InferredColumnJson {
+    name: string;
+    primitive: InferredPrimitive;
+}
+/**
+ * Host-introspected input schema. Produced by the playground's browser-side
+ * `DuckDB-WASM` `DESCRIBE read_csv_auto('<url>')` call (see plan 13-04b);
+ * consumed by the Rust compiler via
+ * {@link FossilPlayground.registerInferredDescriptor}. See ADR-0037 for the
+ * full architectural rationale (drop user-facing CSVW; host-side
+ * introspection feeds the compiler ahead of `compile()`).
+ */
+export interface InferredDescriptorJson {
+    /** Source binding name (e.g. `"users"` for `users := io.csv(...)`). */
+    source_name: string;
+    /** Ordered columns — order is significant for column-position fallback. */
+    columns: InferredColumnJson[];
+    /**
+     * Opaque content-hash. Empty string means "let the Rust side derive a
+     * deterministic hash from the column tuple list" (used for Salsa keying).
+     * Hosts that already maintain a per-file content-hash (e.g. resolver-side)
+     * MAY supply it.
+     */
+    content_hash: string;
+}
+/**
+ * Workspace API class (ADR-0024). Thin TS wrapper around the wasm-bindgen
+ * `FossilPlayground` that exposes camelCase method names for JS idiom + better
+ * TS inference (the raw bindings use snake_case from the Rust impl block).
+ *
+ * One instance per browser tab / Node process — the instance owns the Salsa
+ * store + `Arc<OutputDescriptorKind>` for the schema slot. Subsequent
+ * `openFile` calls intern fresh `SourceFile` inputs under the same Salsa
+ * revision so `updateFile` benefits from incremental memoisation.
+ *
+ * The Phase 7 LSP Worker (07-03) drives this class via postMessage; the React
+ * component in `@fossil-lang/playground` (08-09) does the same via the
+ * WorkerTransport adapter.
+ *
+ * NOTE: {@link FileHandle} is opaque — JS cannot construct one. Callers receive
+ * a handle from `openFile` and pass it back to subsequent operations. The Rust
+ * side keeps a `HashMap<FileHandle, SourceFile>` indexed by a `u32` newtype;
+ * the wasm-bindgen wrapper exposes that as a class with `private constructor()`.
+ */
+export declare class FossilPlayground {
+    private _inner;
+    constructor();
+    /**
+     * Free the underlying WASM-side Salsa store. Call when the playground is no
+     * longer needed (e.g. component unmount). Idempotent in spirit — subsequent
+     * method calls on a freed playground throw.
+     */
+    free(): void;
+    /**
+     * Return the stdlib classification manifest (STDL-07). The playground reads
+     * this once at startup to render `native_udf_only` functions as disabled
+     * with a "native-only — unavailable in the browser" tooltip.
+     */
+    classification(): StdlibClass[];
+    /**
+     * Open a file in the workspace. Returns the {@link FileHandle} subsequent
+     * `updateFile` / `closeFile` / `diagnosticsFor` calls key
+     * on. `path` is the URI / virtual path diagnostics carry back to the LSP
+     * client (e.g. `"file:///tmp/a.fossil"` or `"untitled:Untitled-1"`).
+     *
+     * Mirrors `ty_wasm::Workspace::open_file` (Astral). Interns a fresh
+     * `fossil_base::SourceFile` under the current Salsa revision.
+     */
+    openFile(path: string, contents: string): FileHandle;
+    /**
+     * Apply an edit to an open file. Mutates the SAME `SourceFile` via the
+     * Salsa `Setter` (`set_text`) — this BUMPS THE REVISION (ADR-0022), the
+     * real cancellation trigger. NO new `SourceFile` is interned, so memoised
+     * downstream queries (`def_map`, `typecheck_mapping`) invalidate
+     * incrementally instead of falling off a cliff.
+     */
+    updateFile(handle: FileHandle, contents: string): void;
+    /**
+     * Close a file in the workspace. Strict in signal: closing an unknown /
+     * already-closed handle throws so JS-side bugs surface loudly (mirrors
+     * `ty_wasm`).
+     */
+    closeFile(handle: FileHandle): void;
+    /**
+     * Workspace-wide diagnostic drain. Runs `parse → def_map →
+     * typecheck_mapping` across every open file and returns a flat array of
+     * {@link CheckRow}. The LSP Worker (07-03) republishes these grouped by URI
+     * as `textDocument/publishDiagnostics` notifications.
+     */
+    check(): CheckRow[];
+    /**
+     * Per-file diagnostic drain — the B3 follow-up accessor the LSP Worker uses
+     * for its per-file `publishDiagnostics` notifications. `check()` returns
+     * the workspace-wide flat array; `diagnosticsFor` returns just one file's
+     * rows so 07-03 can dispatch one notification per affected URI without
+     * partitioning the workspace array on the JS side.
+     */
+    diagnosticsFor(handle: FileHandle): CheckRow[];
+    /**
+     * Install a user-supplied ShEx schema as the active output descriptor. On
+     * parse failure the previously-installed descriptor is RETAINED (no
+     * half-applied state — same contract as `fossil-lsp::load_sibling_shex` in
+     * 06-09). Future `fossil-ide` feature calls (hover, completion) reading
+     * `HirDb::output_descriptor_kind` see the new schema atomically.
+     */
+    setTargetShex(text: string): void;
+    /**
+     * Register an {@link InferredDescriptorJson} for a source binding name
+     * BEFORE invoking {@link check}. The Rust compiler reads from this
+     * registration during forward type propagation (Phase 3 CORE-05 rewired in
+     * plan 13-02).
+     *
+     * The browser-side orchestration runs DuckDB-WASM
+     * `DESCRIBE read_csv_auto('<resolved-url>')` for each `io.csv("...")`
+     * reference in the source, canonicalises the columns to the
+     * {@link InferredPrimitive} catalog, and calls this method with the
+     * resulting descriptor before {@link check}. See ADR-0037 for the full
+     * architectural rationale.
+     *
+     * Keyed by source-binding name (e.g. `"users"` for
+     * `users := io.csv("...")`), NOT by URL. Idempotent — re-registering with
+     * the same `source_name` overwrites the previous entry.
+     *
+     * @throws Error if the descriptor JSON fails to deserialise on the Rust
+     *         side (e.g. missing required fields). The error message includes
+     *         the underlying serde_json diagnostic.
+     *
+     * @see ADR-0037 — drop user-facing CSVW; infer via DuckDB DESCRIBE
+     */
+    registerInferredDescriptor(descriptor: InferredDescriptorJson): void;
+}
+export type { TokenRow, SemanticTokensLegend } from '@fossil-lang/types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,OAAO,EAEL,UAAU,IAAI,aAAa,EAI5B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAEzE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,YAAY,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,aAAa,CAAC;AAEvC;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,EAAE,CAMjD;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,IAAI,oBAAoB,CAErD;AAED;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE;QACL,KAAK,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAA;SAAE,CAAC;QAC3C,GAAG,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAA;SAAE,CAAC;KAC1C,CAAC;IACF,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,UAAU,GAAG,iBAAiB,CAAC;CAC5C;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,iBAAiB,GACzB,QAAQ,GACR,SAAS,GACT,OAAO,GACP,MAAM,GACN,MAAM,GACN,UAAU,GACV,MAAM,GACN,OAAO,GACP,QAAQ,CAAC;AAEb,kDAAkD;AAClD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,iBAAiB,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAsB;IACrC,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAsB;;IAMpC;;;;OAIG;IACH,IAAI,IAAI,IAAI;IAIZ;;;;OAIG;IACH,cAAc,IAAI,WAAW,EAAE;IAI/B;;;;;;;;OAQG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU;IAIpD;;;;;;OAMG;IACH,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAItD;;;;OAIG;IACH,SAAS,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAInC;;;;;OAKG;IACH,KAAK,IAAI,QAAQ,EAAE;IAInB;;;;;;OAMG;IACH,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,QAAQ,EAAE;IAI9C;;;;;;OAMG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIjC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,0BAA0B,CAAC,UAAU,EAAE,sBAAsB,GAAG,IAAI;CAKrE;AAKD,YAAY,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,201 @@
+/**
+ * @fossil-lang/wasm — JS/TS wrapper around the fossil-wasm wasm-bindgen artifacts.
+ *
+ * Public API (one of the six @fossil-lang/* packages per ADR-0028):
+ * - {@link initFossilWasm} — consumer-controlled .wasm URL loader (memoised).
+ * - {@link tokenize} — calls the Rust lexer, returns TokenRow[] (ADR-0030).
+ * - {@link semanticLegend} — returns the LSP SemanticTokensLegend (Phase-6 06-07).
+ * - {@link FossilPlayground} — Workspace API class (ADR-0024) for the LSP.
+ *
+ * Consumer pattern (wasm-bindgen --target web — RESEARCH.md Pattern 3):
+ *
+ *   import { initFossilWasm, tokenize } from '@fossil-lang/wasm';
+ *   import wasmUrl from '@fossil-lang/wasm/pkg/fossil_wasm_bg.wasm?url';  // Vite
+ *
+ *   await initFossilWasm({ wasmUrl });
+ *   const tokens = tokenize('prefix ex: <https://example.org/>');
+ */
+// '../pkg/fossil_wasm.js' is a wasm-bindgen --target web output emitted by `pnpm run build:wasm`.
+// Gitignored at the repo root (`packages/wasm/pkg/`) but always present at build time. The accompanying
+// .d.ts is consumed via the file's `/* @ts-self-types="./fossil_wasm.d.ts" */` pragma.
+import { FossilPlayground as RawFossilPlayground, FileHandle as RawFileHandle, tokenize as rawTokenize, semantic_legend as rawSemanticLegend, start_lsp_worker as rawStartLspWorker, } from '../pkg/fossil_wasm.js';
+export { initFossilWasm } from './load.js';
+/**
+ * Install the LSP-over-postMessage dispatcher on the current Worker scope.
+ *
+ * Per ADR-0024 (`fossil-wasm` IS the LSP server-side) + Phase 7 plan 07-03
+ * (the 16-route dispatch loop). The Rust function (re-exported from
+ * `crates/fossil-wasm/src/lsp_worker.rs`) installs `self.onmessage` on the
+ * Worker scope and owns LSP JSON-RPC dispatch from that point forward —
+ * including per-file `textDocument/publishDiagnostics` drains (B3 fix from
+ * 07-03), `textDocument/semanticTokens/full` (06-07), hover, completion,
+ * definition, references, rename, formatting, code actions, document
+ * symbols, signature help.
+ *
+ * MUST be called inside a Web Worker scope, AFTER {@link initFossilWasm} has
+ * resolved. Calling it on the main thread is a no-op (the dispatcher needs
+ * `DedicatedWorkerGlobalScope.onmessage`).
+ *
+ * Consumed by `@fossil-lang/playground`'s `src/workers/lsp.worker.ts` —
+ * the React component's LSP Worker entry boots the WASM module then calls
+ * this function once.
+ */
+export function start_lsp_worker() {
+    rawStartLspWorker();
+}
+/**
+ * Tokenize a Fossil source string. Returns the byte-range tokens from the
+ * canonical Rust lexer (`fossil_syntax::lexer::raw_lex`) — single grammar
+ * source of truth per ADR-0030.
+ *
+ * MUST be called after {@link initFossilWasm} has resolved; otherwise the
+ * underlying wasm-bindgen function throws (the wasm module is not yet
+ * instantiated).
+ */
+export function tokenize(text) {
+    // The wasm-bindgen wrapper returns a `JsValue` typed as `any`; the Rust side
+    // (crates/fossil-wasm/src/tokenize.rs) serializes `Vec<TokenRow>` via
+    // `serde_wasm_bindgen::to_value`, so the shape matches `{ kind, start, end }`
+    // exactly. Cast is safe because the Rust ↔ JS contract is enforced upstream.
+    return rawTokenize(text);
+}
+/**
+ * Returns the LSP `SemanticTokensLegend` (token types + modifiers list) the
+ * editor uses to map LSP `semanticTokens/full` response indices to highlight
+ * categories. Re-export of `fossil_ide::semantic_legend` (Phase-6 06-07) over
+ * the wasm-bindgen boundary — NO duplicate legend definition lives here.
+ *
+ * MUST be called after {@link initFossilWasm} has resolved.
+ */
+export function semanticLegend() {
+    return rawSemanticLegend();
+}
+/**
+ * Workspace API class (ADR-0024). Thin TS wrapper around the wasm-bindgen
+ * `FossilPlayground` that exposes camelCase method names for JS idiom + better
+ * TS inference (the raw bindings use snake_case from the Rust impl block).
+ *
+ * One instance per browser tab / Node process — the instance owns the Salsa
+ * store + `Arc<OutputDescriptorKind>` for the schema slot. Subsequent
+ * `openFile` calls intern fresh `SourceFile` inputs under the same Salsa
+ * revision so `updateFile` benefits from incremental memoisation.
+ *
+ * The Phase 7 LSP Worker (07-03) drives this class via postMessage; the React
+ * component in `@fossil-lang/playground` (08-09) does the same via the
+ * WorkerTransport adapter.
+ *
+ * NOTE: {@link FileHandle} is opaque — JS cannot construct one. Callers receive
+ * a handle from `openFile` and pass it back to subsequent operations. The Rust
+ * side keeps a `HashMap<FileHandle, SourceFile>` indexed by a `u32` newtype;
+ * the wasm-bindgen wrapper exposes that as a class with `private constructor()`.
+ */
+export class FossilPlayground {
+    _inner;
+    constructor() {
+        this._inner = new RawFossilPlayground();
+    }
+    /**
+     * Free the underlying WASM-side Salsa store. Call when the playground is no
+     * longer needed (e.g. component unmount). Idempotent in spirit — subsequent
+     * method calls on a freed playground throw.
+     */
+    free() {
+        this._inner.free();
+    }
+    /**
+     * Return the stdlib classification manifest (STDL-07). The playground reads
+     * this once at startup to render `native_udf_only` functions as disabled
+     * with a "native-only — unavailable in the browser" tooltip.
+     */
+    classification() {
+        return this._inner.classification();
+    }
+    /**
+     * Open a file in the workspace. Returns the {@link FileHandle} subsequent
+     * `updateFile` / `closeFile` / `diagnosticsFor` calls key
+     * on. `path` is the URI / virtual path diagnostics carry back to the LSP
+     * client (e.g. `"file:///tmp/a.fossil"` or `"untitled:Untitled-1"`).
+     *
+     * Mirrors `ty_wasm::Workspace::open_file` (Astral). Interns a fresh
+     * `fossil_base::SourceFile` under the current Salsa revision.
+     */
+    openFile(path, contents) {
+        return this._inner.open_file(path, contents);
+    }
+    /**
+     * Apply an edit to an open file. Mutates the SAME `SourceFile` via the
+     * Salsa `Setter` (`set_text`) — this BUMPS THE REVISION (ADR-0022), the
+     * real cancellation trigger. NO new `SourceFile` is interned, so memoised
+     * downstream queries (`def_map`, `typecheck_mapping`) invalidate
+     * incrementally instead of falling off a cliff.
+     */
+    updateFile(handle, contents) {
+        this._inner.update_file(handle, contents);
+    }
+    /**
+     * Close a file in the workspace. Strict in signal: closing an unknown /
+     * already-closed handle throws so JS-side bugs surface loudly (mirrors
+     * `ty_wasm`).
+     */
+    closeFile(handle) {
+        this._inner.close_file(handle);
+    }
+    /**
+     * Workspace-wide diagnostic drain. Runs `parse → def_map →
+     * typecheck_mapping` across every open file and returns a flat array of
+     * {@link CheckRow}. The LSP Worker (07-03) republishes these grouped by URI
+     * as `textDocument/publishDiagnostics` notifications.
+     */
+    check() {
+        return this._inner.check();
+    }
+    /**
+     * Per-file diagnostic drain — the B3 follow-up accessor the LSP Worker uses
+     * for its per-file `publishDiagnostics` notifications. `check()` returns
+     * the workspace-wide flat array; `diagnosticsFor` returns just one file's
+     * rows so 07-03 can dispatch one notification per affected URI without
+     * partitioning the workspace array on the JS side.
+     */
+    diagnosticsFor(handle) {
+        return this._inner.diagnostics_for(handle);
+    }
+    /**
+     * Install a user-supplied ShEx schema as the active output descriptor. On
+     * parse failure the previously-installed descriptor is RETAINED (no
+     * half-applied state — same contract as `fossil-lsp::load_sibling_shex` in
+     * 06-09). Future `fossil-ide` feature calls (hover, completion) reading
+     * `HirDb::output_descriptor_kind` see the new schema atomically.
+     */
+    setTargetShex(text) {
+        this._inner.set_target_shex(text);
+    }
+    /**
+     * Register an {@link InferredDescriptorJson} for a source binding name
+     * BEFORE invoking {@link check}. The Rust compiler reads from this
+     * registration during forward type propagation (Phase 3 CORE-05 rewired in
+     * plan 13-02).
+     *
+     * The browser-side orchestration runs DuckDB-WASM
+     * `DESCRIBE read_csv_auto('<resolved-url>')` for each `io.csv("...")`
+     * reference in the source, canonicalises the columns to the
+     * {@link InferredPrimitive} catalog, and calls this method with the
+     * resulting descriptor before {@link check}. See ADR-0037 for the full
+     * architectural rationale.
+     *
+     * Keyed by source-binding name (e.g. `"users"` for
+     * `users := io.csv("...")`), NOT by URL. Idempotent — re-registering with
+     * the same `source_name` overwrites the previous entry.
+     *
+     * @throws Error if the descriptor JSON fails to deserialise on the Rust
+     *         side (e.g. missing required fields). The error message includes
+     *         the underlying serde_json diagnostic.
+     *
+     * @see ADR-0037 — drop user-facing CSVW; infer via DuckDB DESCRIBE
+     */
+    registerInferredDescriptor(descriptor) {
+        // The wasm-bindgen wrapper exposes `registerInferredDescriptor(string)` —
+        // it accepts a JSON string. Serialise here so callers pass a typed object.
+        this._inner.registerInferredDescriptor(JSON.stringify(descriptor));
+    }
+}
+//# 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;;;;;;;;;;;;;;;;GAgBG;AAEH,kGAAkG;AAClG,wGAAwG;AACxG,uFAAuF;AACvF,OAAO,EACL,gBAAgB,IAAI,mBAAmB,EACvC,UAAU,IAAI,aAAa,EAC3B,QAAQ,IAAI,WAAW,EACvB,eAAe,IAAI,iBAAiB,EACpC,gBAAgB,IAAI,iBAAiB,GACtC,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAG3C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,gBAAgB;IAC9B,iBAAiB,EAAE,CAAC;AACtB,CAAC;AAYD;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,6EAA6E;IAC7E,sEAAsE;IACtE,8EAA8E;IAC9E,6EAA6E;IAC7E,OAAO,WAAW,CAAC,IAAI,CAAe,CAAC;AACzC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,iBAAiB,EAA0B,CAAC;AACrD,CAAC;AA8ED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,gBAAgB;IACnB,MAAM,CAAsB;IAEpC;QACE,IAAI,CAAC,MAAM,GAAG,IAAI,mBAAmB,EAAE,CAAC;IAC1C,CAAC;IAED;;;;OAIG;IACH,IAAI;QACF,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACrB,CAAC;IAED;;;;OAIG;IACH,cAAc;QACZ,OAAO,IAAI,CAAC,MAAM,CAAC,cAAc,EAAmB,CAAC;IACvD,CAAC;IAED;;;;;;;;OAQG;IACH,QAAQ,CAAC,IAAY,EAAE,QAAgB;QACrC,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC/C,CAAC;IAED;;;;;;OAMG;IACH,UAAU,CAAC,MAAkB,EAAE,QAAgB;QAC7C,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC5C,CAAC;IAED;;;;OAIG;IACH,SAAS,CAAC,MAAkB;QAC1B,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;IACjC,CAAC;IAED;;;;;OAKG;IACH,KAAK;QACH,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,EAAgB,CAAC;IAC3C,CAAC;IAED;;;;;;OAMG;IACH,cAAc,CAAC,MAAkB;QAC/B,OAAO,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,MAAM,CAAe,CAAC;IAC3D,CAAC;IAED;;;;;;OAMG;IACH,aAAa,CAAC,IAAY;QACxB,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,0BAA0B,CAAC,UAAkC;QAC3D,0EAA0E;QAC1E,2EAA2E;QAC3E,IAAI,CAAC,MAAM,CAAC,0BAA0B,CAAC,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC;IACrE,CAAC;CACF"}

package/dist/load.d.ts

@@ -0,0 +1,30 @@
+/** Options for {@link initFossilWasm}. */
+export interface InitFossilWasmOpts {
+    /**
+     * URL or path to `fossil_wasm_bg.wasm`. Consumers control resolution:
+     *  - Vite: `import wasmUrl from '@fossil-lang/wasm/pkg/fossil_wasm_bg.wasm?url'`
+     *  - Next.js: serve from `public/` and pass the static URL (e.g. `'/wasm/fossil_wasm_bg.wasm'`)
+     *  - Web Worker: `new URL('@fossil-lang/wasm/pkg/fossil_wasm_bg.wasm', import.meta.url)`
+     *  - Node test: a `file://` URL resolved from `import.meta.url`
+     *
+     * Accepts `string` (a URL string), `URL`, a `Request`, or a `Response` —
+     * matching `wasm-bindgen --target web`'s init signature.
+     */
+    wasmUrl: string | URL | Request | Response;
+}
+/**
+ * Boot the fossil-wasm module. MUST be awaited before calling any of
+ * {@link tokenize}, {@link semanticLegend}, or instantiating
+ * {@link FossilPlayground}. Memoised — subsequent calls return the same promise.
+ *
+ * Per 08-RESEARCH.md Pattern 3 (wasm-bindgen --target web), consumers control
+ * the `.wasm` URL — this avoids tying library users to a specific bundler's
+ * `.wasm` import magic. See `packages/wasm/README.md` for consumer patterns.
+ */
+export declare function initFossilWasm(opts: InitFossilWasmOpts): Promise<unknown>;
+/**
+ * For tests + hot-reload — reset the memoised promise. NOT exported from the
+ * package index (test-internal helper).
+ */
+export declare function __resetForTests(): void;
+//# sourceMappingURL=load.d.ts.map

package/dist/load.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../src/load.ts"],"names":[],"mappings":"AAMA,0CAA0C;AAC1C,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;OASG;IACH,OAAO,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,GAAG,QAAQ,CAAC;CAC5C;AAID;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CASzE;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAEtC"}

package/dist/load.js

@@ -0,0 +1,33 @@
+// '../pkg/fossil_wasm.js' is a wasm-bindgen --target web output emitted by `pnpm run build:wasm`.
+// It is gitignored (per 08-01 .gitignore + repo .gitignore `packages/wasm/pkg/`) but always present at build time.
+// The accompanying fossil_wasm.d.ts is consumed via the file's `/* @ts-self-types="./fossil_wasm.d.ts" */` pragma —
+// TS 5.6 resolves the `import` to that side-channel `.d.ts` automatically (no `@ts-expect-error` needed).
+import init from '../pkg/fossil_wasm.js';
+let _initPromise = null;
+/**
+ * Boot the fossil-wasm module. MUST be awaited before calling any of
+ * {@link tokenize}, {@link semanticLegend}, or instantiating
+ * {@link FossilPlayground}. Memoised — subsequent calls return the same promise.
+ *
+ * Per 08-RESEARCH.md Pattern 3 (wasm-bindgen --target web), consumers control
+ * the `.wasm` URL — this avoids tying library users to a specific bundler's
+ * `.wasm` import magic. See `packages/wasm/README.md` for consumer patterns.
+ */
+export function initFossilWasm(opts) {
+    if (!_initPromise) {
+        // wasm-bindgen 0.2.120 init() prefers the `{ module_or_path }` object form;
+        // passing the URL/Request/Response/BufferSource as a positional argument
+        // still works but logs a deprecation warning ("pass a single object
+        // instead"). We use the object form to stay on the maintained path.
+        _initPromise = init({ module_or_path: opts.wasmUrl });
+    }
+    return _initPromise;
+}
+/**
+ * For tests + hot-reload — reset the memoised promise. NOT exported from the
+ * package index (test-internal helper).
+ */
+export function __resetForTests() {
+    _initPromise = null;
+}
+//# sourceMappingURL=load.js.map

package/dist/load.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.js","sourceRoot":"","sources":["../src/load.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,mHAAmH;AACnH,oHAAoH;AACpH,0GAA0G;AAC1G,OAAO,IAAI,MAAM,uBAAuB,CAAC;AAiBzC,IAAI,YAAY,GAA4B,IAAI,CAAC;AAEjD;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,IAAwB;IACrD,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,4EAA4E;QAC5E,yEAAyE;QACzE,oEAAoE;QACpE,oEAAoE;QACpE,YAAY,GAAG,IAAI,CAAC,EAAE,cAAc,EAAE,IAAI,CAAC,OAAgB,EAAE,CAAC,CAAC;IACjE,CAAC;IACD,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe;IAC7B,YAAY,GAAG,IAAI,CAAC;AACtB,CAAC"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@fossil-lang/wasm",
+  "version": "0.3.0-alpha.1",
+  "description": "JS/TS wrapper around the fossil-wasm wasm-bindgen artifacts (--target web). Exposes initFossilWasm + tokenize + semanticLegend + FossilPlayground class for downstream @fossil-lang/* packages.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kanzo-tech/fossil.git",
+    "directory": "packages/wasm"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./pkg/fossil_wasm_bg.wasm": "./pkg/fossil_wasm_bg.wasm"
+  },
+  "files": [
+    "dist/",
+    "pkg/fossil_wasm.js",
+    "pkg/fossil_wasm.d.ts",
+    "pkg/fossil_wasm_bg.wasm",
+    "pkg/fossil_wasm_bg.wasm.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@fossil-lang/types": "0.3.0-alpha.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^2.0.0"
+  },
+  "scripts": {
+    "build:wasm": "bash scripts/build-wasm.sh",
+    "build": "pnpm run build:wasm && tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit"
+  }
+}