@fossil-lang/wasm 0.3.0-alpha.7 → 0.3.0-alpha.9

package/README.md

@@ -2,7 +2,10 @@
 
 JS/TS wrapper around the `fossil-wasm` Rust crate's wasm-bindgen artefacts. Provides:
 
-- `initFossilWasm({ wasmUrl })` — consumer-controlled `.wasm` URL loader (memoised).
+- `openProgram(uri, { host, text })` — one program open for an editor, and the
+  call a host with an editor makes. See below.
+- `initFossilWasm()` — boots the module (memoised). Its `.wasm` ships in this
+  package and the host's bundler emits it as an asset; the host copies nothing.
 - `tokenize(text)` — calls the Rust lexer, returns `TokenRow[]`. The Rust lexer
   is the only lexer: no host reimplements one and drifts from the grammar.
 - `semanticLegend()` — returns the LSP semantic-tokens legend.
@@ -10,6 +13,29 @@ JS/TS wrapper around the `fossil-wasm` Rust crate's wasm-bindgen artefacts. Prov
   itself is native-only (stdio over crossbeam), so the browser gets this
   equivalent dispatch surface over the same `fossil-ide` functions.
 
+## One program in one editor: `openProgram`
+
+```typescript
+import { openProgram } from '@fossil-lang/wasm';
+import { fossil } from '@fossil-lang/codemirror-fossil';
+
+const program = await openProgram('job.fossil', { host, text });   // host: SourceHost
+const extensions = fossil({ ...program, onNavigate });
+
+program.registerDescriptor(descriptor);        // a host-introspected source, before a check
+const sources = await program.sources(text);   // what introspection DESCRIBEs
+```
+
+It boots the module, opens `uri` in its own workspace, and reads the documents
+the text names through `host`. The answer carries `fossil()`'s option names —
+`uri`, `tokenize`, `tokenKinds`, `check`, `hover`, `complete`, `definition` —
+and every one that answers about the program takes the text and pushes it
+first, comparing against what it last pushed so the common case costs a string
+comparison. `check` and `sources` also run `resolveDocuments`, which reads
+nothing when nothing is missing. That is the whole protocol an editor host used
+to write by hand; `workspace` is the `FossilPlayground` underneath, for a
+question this surface does not ask, and `close()` frees it.
+
 ## Documents and sources: fossil resolves, the host reads
 
 A program names shape documents (`io.shex("@vocab/person.shex")`) and data
@@ -41,47 +67,50 @@ const rows = pg.check();
   locator, catalogue row, reader option. Introspection DESCRIBEs these and
   registers each descriptor under `key` with `registerInferredDescriptor`.
 
-## 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. `--target bundler` was rejected
-because its output assumes the consumer's bundler resolves `.wasm` ESM imports,
-which a republished library cannot assume of a host's Vite/Next/Webpack config.
-
-## Consumer patterns
-
-### Vite host
+## Loading: the `.wasm` is an asset of this package
 
 ```typescript
 import { initFossilWasm, tokenize } from '@fossil-lang/wasm';
-import wasmUrl from '@fossil-lang/wasm/pkg/fossil_wasm_bg.wasm?url';
 
-await initFossilWasm({ wasmUrl });
+await initFossilWasm();
 const tokens = tokenize('User := io.csv("data/people.csv")');
 ```
 
-### Next.js host (in a Client Component)
+That is the whole host flow, in Vite, Next.js (webpack or Turbopack), a Web
+Worker or any bundler that understands `new URL('…', import.meta.url)`. The glue
+(`wasm-bindgen --target web`) locates `fossil_wasm_bg.wasm` with exactly that
+expression, the bundler copies the file into its output under a hashed name and
+rewrites the URL, and the browser fetches it from there. No copy script, no
+`public/` directory, no URL to keep in sync with a version.
+
+**Vite dev server, package installed from npm:** Vite's dependency optimizer
+pre-bundles the package into `node_modules/.vite/deps/` without its `.wasm`, and
+the URL then answers with `index.html`. Keep the three packages out of it —
+`vite build` needs nothing:
+
+```js
+// vite.config.js
+export default { optimizeDeps: { exclude: ['@fossil-lang/wasm', '@fossil-lang/executor', '@fossil-lang/corpus'] } };
+```
 
-```typescript
-'use client';
-import { initFossilWasm, tokenize } from '@fossil-lang/wasm';
+A workspace-linked package is never pre-bundled, which is why the playground needs
+no such line. Next.js needs none in either `next dev` or `next build`, webpack or
+Turbopack.
 
-// 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' });
-}, []);
-```
+`--target bundler` was rejected because it emits `import … from '*.wasm'` (the
+ESM-integration proposal), which each bundler gates behind its own experimental
+flag. `new URL(…, import.meta.url)` is the pattern they all support by default.
 
-### Web Worker
+**Without a bundler**, pass the module yourself — `initFossilWasm(wasm)` takes the
+glue's `InitInput` (`BufferSource`, `Response`, `URL`, `WebAssembly.Module`). Node
+is the case: its `fetch` rejects `file://`, so hand it the bytes:
 
 ```typescript
-// inside a Worker module:
-import { initFossilWasm, FossilPlayground } from '@fossil-lang/wasm';
-import wasmUrl from '@fossil-lang/wasm/pkg/fossil_wasm_bg.wasm?url';
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
 
-await initFossilWasm({ wasmUrl });
-const pg = new FossilPlayground();
+const path = createRequire(import.meta.url).resolve('@fossil-lang/wasm/pkg/fossil_wasm_bg.wasm');
+await initFossilWasm(await readFile(path));
 ```
 
 ## Build

package/dist/index.d.ts

@@ -3,10 +3,13 @@
  *
  * Public API (one of the @fossil-lang/* packages; `git ls-files packages` is
  * the list):
- * - {@link initFossilWasm} — consumer-controlled .wasm URL loader (memoised).
+ * - {@link initFossilWasm} — boots the module; its `.wasm` is a bundler asset (memoised).
  * - {@link tokenize} — calls the Rust lexer, returns TokenRow[].
  * - {@link tokenKinds} — the legend for TokenRow.kind: variant names by index.
  * - {@link semanticLegend} — returns the LSP SemanticTokensLegend.
+ * - {@link openProgram} — one program open for an editor: the workspace, the push-before-ask
+ *   discipline and the document resolution a host would otherwise write, shaped to spread into
+ *   `@fossil-lang/codemirror-fossil`'s `fossil()`. What a host with one editor calls.
  * - {@link FossilPlayground} — Workspace API class: open / update / close,
  *   `check`, the three position queries (`hover`, `completions`,
  *   `gotoDefinition`) an editor draws its IDE surface from, and the documents
@@ -15,16 +18,18 @@
  *
  * Consumer pattern (wasm-bindgen --target web):
  *
- *   import { initFossilWasm, tokenize } from '@fossil-lang/wasm';
- *   import wasmUrl from '@fossil-lang/wasm/pkg/fossil_wasm_bg.wasm?url';  // Vite
+ *   import { openProgram } from '@fossil-lang/wasm';
+ *   import { fossil } from '@fossil-lang/codemirror-fossil';
  *
- *   await initFossilWasm({ wasmUrl });
- *   const tokens = tokenize('User := io.csv("data/people.csv")');
+ *   const program = await openProgram('job.fossil', { host, text });
+ *   const extensions = fossil({ ...program, onNavigate });
  */
 export { initFossilWasm } from './load.js';
-export type { InitFossilWasmOpts } from './load.js';
+export type { InitInput } from './load.js';
 export { start_lsp_worker, tokenize, tokenKinds, semanticLegend, FossilPlayground, refs, providers, } from './client.js';
 export type { FileHandle } from './client.js';
+export { openProgram } from './program.js';
+export type { FossilProgram, OpenProgramOptions } from './program.js';
 /** One external reference a program makes — the typed lineage returned by
  *  {@link refs}. Mirrors `fossil_lineage::SourceRefInfo` (the SAME struct the
  *  native `fossil refs` emits). `connection` is the `@conn` alias the reference

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAQH,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,YAAY,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAEpD,OAAO,EACL,gBAAgB,EAChB,QAAQ,EACR,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,IAAI,EACJ,SAAS,GACV,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;4EAI4E;AAC5E,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC;CACzB;AAED;;oEAEoE;AACpE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,QAAQ,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;8EAE8E;AAC9E,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,GAAG,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1C;AAED;;;wDAGwD;AACxD,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,QAAQ,CAAC;CACjB;AAED;;;;;;;;;;;;;;aAca;AACb,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;gCAMgC;AAChC,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,QAAQ,CAAC;CACjB;AAYD;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB,GACzB,QAAQ,GACR,SAAS,GACT,OAAO,GACP,MAAM,GACN,MAAM,GACN,WAAW,GACX,MAAM,GACN,QAAQ,GACR,SAAS,CAAC;AAEd,kDAAkD;AAClD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,iBAAiB,CAAC;CAC9B;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;OAKG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,2EAA2E;IAC3E,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B;;;;;;OAMG;IACH,eAAe,EAAE,MAAM,CAAC;CACzB;AAKD,YAAY,EACV,QAAQ,EACR,oBAAoB,EACpB,UAAU,EACV,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,aAAa,GACd,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAQH,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,YAAY,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,OAAO,EACL,gBAAgB,EAChB,QAAQ,EACR,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,IAAI,EACJ,SAAS,GACV,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,YAAY,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEtE;;;;4EAI4E;AAC5E,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC;CACzB;AAED;;oEAEoE;AACpE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,QAAQ,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;8EAE8E;AAC9E,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,GAAG,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1C;AAED;;;wDAGwD;AACxD,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,QAAQ,CAAC;CACjB;AAED;;;;;;;;;;;;;;aAca;AACb,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;gCAMgC;AAChC,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,QAAQ,CAAC;CACjB;AAYD;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB,GACzB,QAAQ,GACR,SAAS,GACT,OAAO,GACP,MAAM,GACN,MAAM,GACN,WAAW,GACX,MAAM,GACN,QAAQ,GACR,SAAS,CAAC;AAEd,kDAAkD;AAClD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,iBAAiB,CAAC;CAC9B;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;OAKG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,2EAA2E;IAC3E,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B;;;;;;OAMG;IACH,eAAe,EAAE,MAAM,CAAC;CACzB;AAKD,YAAY,EACV,QAAQ,EACR,oBAAoB,EACpB,UAAU,EACV,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,aAAa,GACd,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -3,10 +3,13 @@
  *
  * Public API (one of the @fossil-lang/* packages; `git ls-files packages` is
  * the list):
- * - {@link initFossilWasm} — consumer-controlled .wasm URL loader (memoised).
+ * - {@link initFossilWasm} — boots the module; its `.wasm` is a bundler asset (memoised).
  * - {@link tokenize} — calls the Rust lexer, returns TokenRow[].
  * - {@link tokenKinds} — the legend for TokenRow.kind: variant names by index.
  * - {@link semanticLegend} — returns the LSP SemanticTokensLegend.
+ * - {@link openProgram} — one program open for an editor: the workspace, the push-before-ask
+ *   discipline and the document resolution a host would otherwise write, shaped to spread into
+ *   `@fossil-lang/codemirror-fossil`'s `fossil()`. What a host with one editor calls.
  * - {@link FossilPlayground} — Workspace API class: open / update / close,
  *   `check`, the three position queries (`hover`, `completions`,
  *   `gotoDefinition`) an editor draws its IDE surface from, and the documents
@@ -15,11 +18,11 @@
  *
  * Consumer pattern (wasm-bindgen --target web):
  *
- *   import { initFossilWasm, tokenize } from '@fossil-lang/wasm';
- *   import wasmUrl from '@fossil-lang/wasm/pkg/fossil_wasm_bg.wasm?url';  // Vite
+ *   import { openProgram } from '@fossil-lang/wasm';
+ *   import { fossil } from '@fossil-lang/codemirror-fossil';
  *
- *   await initFossilWasm({ wasmUrl });
- *   const tokens = tokenize('User := io.csv("data/people.csv")');
+ *   const program = await openProgram('job.fossil', { host, text });
+ *   const extensions = fossil({ ...program, onNavigate });
  */
 // The wasm-bindgen glue (`../pkg/fossil_wasm.js`) is imported ONLY from leaf
 // modules — `load.ts` (init) and `client.ts` (the lexer / LSP / Workspace API) —
@@ -29,4 +32,5 @@
 // codemirror tokenizer hit on the main thread). This entry only re-exports.
 export { initFossilWasm } from './load.js';
 export { start_lsp_worker, tokenize, tokenKinds, semanticLegend, FossilPlayground, refs, providers, } from './client.js';
+export { openProgram } from './program.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,6EAA6E;AAC7E,iFAAiF;AACjF,iFAAiF;AACjF,2EAA2E;AAC3E,yEAAyE;AACzE,4EAA4E;AAC5E,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAG3C,OAAO,EACL,gBAAgB,EAChB,QAAQ,EACR,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,IAAI,EACJ,SAAS,GACV,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,6EAA6E;AAC7E,iFAAiF;AACjF,iFAAiF;AACjF,2EAA2E;AAC3E,yEAAyE;AACzE,4EAA4E;AAC5E,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAG3C,OAAO,EACL,gBAAgB,EAChB,QAAQ,EACR,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,IAAI,EACJ,SAAS,GACV,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC"}

package/dist/load.d.ts

@@ -1,27 +1,19 @@
-/** 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;
-}
+import type { InitInput } from '../pkg/fossil_wasm.js';
+export type { InitInput };
 /**
  * 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.
  *
- * With `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.
+ * **Called with nothing, the module finds its own `.wasm`.** The glue resolves
+ * `new URL('fossil_wasm_bg.wasm', import.meta.url)`, which is the pattern Vite,
+ * webpack 5 and Turbopack all recognise and emit as an asset — so a bundled host
+ * writes `await initFossilWasm()` and copies nothing.
+ *
+ * `wasm` is for the host with no bundler to do that: Node, whose `fetch` rejects
+ * `file://`, hands the bytes (`BufferSource`) or a `Response`.
  */
-export declare function initFossilWasm(opts: InitFossilWasmOpts): Promise<unknown>;
+export declare function initFossilWasm(wasm?: InitInput): Promise<unknown>;
 /**
  * For tests + hot-reload — reset the memoised promise. NOT exported from the
  * package index (test-internal helper).

package/dist/load.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../src/load.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEvD,YAAY,EAAE,SAAS,EAAE,CAAC;AAI1B;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAMjE;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAEtC"}

package/dist/load.js

@@ -1,7 +1,6 @@
 // '../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).
+// It is gitignored (repo .gitignore `packages/wasm/pkg/`) but always present at build time and in
+// the published tarball. Its `.d.ts` is consumed via the file's `/* @ts-self-types */` pragma.
 import init from '../pkg/fossil_wasm.js';
 let _initPromise = null;
 /**
@@ -9,17 +8,18 @@ let _initPromise = null;
  * {@link tokenize}, {@link semanticLegend}, or instantiating
  * {@link FossilPlayground}. Memoised — subsequent calls return the same promise.
  *
- * With `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.
+ * **Called with nothing, the module finds its own `.wasm`.** The glue resolves
+ * `new URL('fossil_wasm_bg.wasm', import.meta.url)`, which is the pattern Vite,
+ * webpack 5 and Turbopack all recognise and emit as an asset — so a bundled host
+ * writes `await initFossilWasm()` and copies nothing.
+ *
+ * `wasm` is for the host with no bundler to do that: Node, whose `fetch` rejects
+ * `file://`, hands the bytes (`BufferSource`) or a `Response`.
  */
-export function initFossilWasm(opts) {
+export function initFossilWasm(wasm) {
     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 });
+        // The object form: the positional one still works but logs a deprecation warning.
+        _initPromise = init(wasm === undefined ? undefined : { module_or_path: wasm });
     }
     return _initPromise;
 }

package/dist/load.js.map

@@ -1 +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"}
+{"version":3,"file":"load.js","sourceRoot":"","sources":["../src/load.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,kGAAkG;AAClG,+FAA+F;AAC/F,OAAO,IAAI,MAAM,uBAAuB,CAAC;AAKzC,IAAI,YAAY,GAA4B,IAAI,CAAC;AAEjD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,cAAc,CAAC,IAAgB;IAC7C,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,kFAAkF;QAClF,YAAY,GAAG,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC,CAAC;IACjF,CAAC;IACD,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe;IAC7B,YAAY,GAAG,IAAI,CAAC;AACtB,CAAC"}

package/dist/program.d.ts

@@ -0,0 +1,94 @@
+/**
+ * One program, open in a workspace, answering an editor — what every host of the checker wrote by
+ * hand before this existed.
+ *
+ * `FossilPlayground` is the workspace and it is right that it stays general: it holds any number
+ * of files and answers about each. What a host with ONE program in ONE editor needs on top of it
+ * is always the same protocol, and two copies of it had already diverged in their comments:
+ *
+ * 1. **Push before you ask.** Four callers at four rates — the debounced linter, hover on pointer
+ *    rest, completion on nearly every keystroke, goto-def on a key — share one workspace, and all
+ *    four answer about the text of the last `updateFile`. So every entry point takes the text and
+ *    pushes it first, and a string comparison against what was last pushed makes that free in the
+ *    common case. `updateFile` is the one call that bumps the Salsa revision; calling it per
+ *    mouse-move would invalidate the memoised check the squiggles came from for nothing.
+ * 2. **Read what the program names before you check it.** The compiler performs no IO. An edit
+ *    can name a shape document the workspace has not read, so a check first runs
+ *    `resolveDocuments` over the host's {@link SourceHost} — which reads nothing when nothing is
+ *    missing.
+ *
+ * The result is shaped for `@fossil-lang/codemirror-fossil`'s `fossil()`: `tokenize`,
+ * `tokenKinds`, `uri`, `check`, `hover`, `complete` and `definition` are exactly its option
+ * names, so a host spreads it and adds what is its own to decide:
+ *
+ * ```ts
+ * const program = await openProgram('job.fossil', { host, text });
+ * const extensions = fossil({ ...program, onNavigate });
+ * ```
+ *
+ * One workspace rather than one per rate, for the reason `fossil()`'s own header gives: a second
+ * workspace for the position queries would answer from a different revision than the squiggles on
+ * screen. The position methods take a SHARED borrow on the Rust side, so they nest inside a live
+ * check rather than poisoning it.
+ */
+import { type ProgramSource, type SourceHost } from '@fossil-lang/types';
+import { FossilPlayground, tokenize, tokenKinds } from './client.js';
+import type { CheckRow, CompletionRow, DefinitionRow, HoverRow, InferredDescriptorJson } from './index.js';
+import { type InitInput } from './load.js';
+/** What {@link openProgram} takes beside the key. */
+export interface OpenProgramOptions {
+    /** The host's one capability: the connection map, and signing what the program names. */
+    host: SourceHost;
+    /** The buffer's text at open. Defaults to empty; every entry point takes the text anyway. */
+    text?: string;
+    /** How a signed document is read. Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+    /** The module's `.wasm`, for a host with no bundler — see {@link initFossilWasm}. */
+    wasm?: InitInput;
+}
+/**
+ * A program open in its own workspace. Every member that answers about the program takes the
+ * current text, and pushes it first — see the module header for why that repetition is the design.
+ */
+export interface FossilProgram {
+    /** The key the program is open under — `CheckRow.uri` and `DefinitionRow.uri` carry it. */
+    readonly uri: string;
+    /** The compiler's lexer, for highlighting. Needs no workspace, and is here so the spread works. */
+    readonly tokenize: typeof tokenize;
+    /** The legend for a token's `kind`. */
+    readonly tokenKinds: typeof tokenKinds;
+    /**
+     * Push the text, read every document it names that the workspace lacks, and check. No debounce:
+     * `fossil()`'s linter waits out its own delay AND waits for this to return before it schedules
+     * again, which is what an LSP client does with `didChange`.
+     */
+    check(text: string): Promise<CheckRow[]>;
+    /** The type under the cursor, and the type the target shape demands of it — or `null`. */
+    hover(text: string, line: number, character: number): HoverRow | null;
+    /** The candidates at the cursor, narrowed by the receiver's type. */
+    complete(text: string, line: number, character: number): CompletionRow[];
+    /** Where the name under the cursor is defined. Often in the shape document: read `uri`. */
+    definition(text: string, line: number, character: number): DefinitionRow[];
+    /**
+     * The data sources the program reads, as fossil resolved them — what introspection DESCRIBEs.
+     * Resolves the documents first, because a source's locator goes through the connection map.
+     */
+    sources(text: string): Promise<ProgramSource[]>;
+    /**
+     * A host-introspected input schema, registered under the URI the program wrote. The compiler
+     * never introspects a source itself; push this before the check that should see it.
+     */
+    registerDescriptor(descriptor: InferredDescriptorJson): void;
+    /** The workspace underneath, for the rare question this surface does not ask. */
+    readonly workspace: FossilPlayground;
+    /** Free the workspace. Every member fails after it. */
+    close(): void;
+}
+/**
+ * Boot the module, open `uri` in a fresh workspace, and read the documents its text names.
+ *
+ * One call and the answer goes straight into `fossil()`. The boot is memoised, so a second program
+ * in the same tab costs a workspace and nothing else.
+ */
+export declare function openProgram(uri: string, options: OpenProgramOptions): Promise<FossilProgram>;
+//# sourceMappingURL=program.d.ts.map

package/dist/program.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../src/program.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,EAAoB,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAE3F,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,KAAK,EACV,QAAQ,EACR,aAAa,EACb,aAAa,EACb,QAAQ,EACR,sBAAsB,EACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAkB,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3D,qDAAqD;AACrD,MAAM,WAAW,kBAAkB;IACjC,yFAAyF;IACzF,IAAI,EAAE,UAAU,CAAC;IACjB,6FAA6F;IAC7F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,qFAAqF;IACrF,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,2FAA2F;IAC3F,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,mGAAmG;IACnG,QAAQ,CAAC,QAAQ,EAAE,OAAO,QAAQ,CAAC;IACnC,uCAAuC;IACvC,QAAQ,CAAC,UAAU,EAAE,OAAO,UAAU,CAAC;IACvC;;;;OAIG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IACzC,0FAA0F;IAC1F,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAAC;IACtE,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,aAAa,EAAE,CAAC;IACzE,2FAA2F;IAC3F,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,aAAa,EAAE,CAAC;IAC3E;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IAChD;;;OAGG;IACH,kBAAkB,CAAC,UAAU,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAC7D,iFAAiF;IACjF,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAC;IACrC,uDAAuD;IACvD,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC,CAoDlG"}

package/dist/program.js

@@ -0,0 +1,93 @@
+/**
+ * One program, open in a workspace, answering an editor — what every host of the checker wrote by
+ * hand before this existed.
+ *
+ * `FossilPlayground` is the workspace and it is right that it stays general: it holds any number
+ * of files and answers about each. What a host with ONE program in ONE editor needs on top of it
+ * is always the same protocol, and two copies of it had already diverged in their comments:
+ *
+ * 1. **Push before you ask.** Four callers at four rates — the debounced linter, hover on pointer
+ *    rest, completion on nearly every keystroke, goto-def on a key — share one workspace, and all
+ *    four answer about the text of the last `updateFile`. So every entry point takes the text and
+ *    pushes it first, and a string comparison against what was last pushed makes that free in the
+ *    common case. `updateFile` is the one call that bumps the Salsa revision; calling it per
+ *    mouse-move would invalidate the memoised check the squiggles came from for nothing.
+ * 2. **Read what the program names before you check it.** The compiler performs no IO. An edit
+ *    can name a shape document the workspace has not read, so a check first runs
+ *    `resolveDocuments` over the host's {@link SourceHost} — which reads nothing when nothing is
+ *    missing.
+ *
+ * The result is shaped for `@fossil-lang/codemirror-fossil`'s `fossil()`: `tokenize`,
+ * `tokenKinds`, `uri`, `check`, `hover`, `complete` and `definition` are exactly its option
+ * names, so a host spreads it and adds what is its own to decide:
+ *
+ * ```ts
+ * const program = await openProgram('job.fossil', { host, text });
+ * const extensions = fossil({ ...program, onNavigate });
+ * ```
+ *
+ * One workspace rather than one per rate, for the reason `fossil()`'s own header gives: a second
+ * workspace for the position queries would answer from a different revision than the squiggles on
+ * screen. The position methods take a SHARED borrow on the Rust side, so they nest inside a live
+ * check rather than poisoning it.
+ */
+import { resolveDocuments } from '@fossil-lang/types';
+import { FossilPlayground, tokenize, tokenKinds } from './client.js';
+import { initFossilWasm } from './load.js';
+/**
+ * Boot the module, open `uri` in a fresh workspace, and read the documents its text names.
+ *
+ * One call and the answer goes straight into `fossil()`. The boot is memoised, so a second program
+ * in the same tab costs a workspace and nothing else.
+ */
+export async function openProgram(uri, options) {
+    const { host, text = '', fetch: fetchImpl = globalThis.fetch, wasm } = options;
+    await initFossilWasm(wasm);
+    const workspace = new FossilPlayground();
+    const handle = workspace.openFile(uri, text);
+    let pushed = text;
+    const sync = (next) => {
+        if (next === pushed)
+            return;
+        workspace.updateFile(handle, next);
+        pushed = next;
+    };
+    const settle = async (next) => {
+        sync(next);
+        await resolveDocuments(workspace.workspace(handle), host, fetchImpl);
+    };
+    await settle(text);
+    return {
+        uri,
+        tokenize,
+        tokenKinds,
+        async check(next) {
+            await settle(next);
+            return workspace.check();
+        },
+        hover(next, line, character) {
+            sync(next);
+            return workspace.hover(handle, line, character);
+        },
+        complete(next, line, character) {
+            sync(next);
+            return workspace.completions(handle, line, character);
+        },
+        definition(next, line, character) {
+            sync(next);
+            return workspace.gotoDefinition(handle, line, character);
+        },
+        async sources(next) {
+            await settle(next);
+            return workspace.sources(handle);
+        },
+        registerDescriptor(descriptor) {
+            workspace.registerInferredDescriptor(descriptor);
+        },
+        workspace,
+        close() {
+            workspace.free();
+        },
+    };
+}
+//# sourceMappingURL=program.js.map

package/dist/program.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.js","sourceRoot":"","sources":["../src/program.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,EAAE,gBAAgB,EAAuC,MAAM,oBAAoB,CAAC;AAE3F,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAQrE,OAAO,EAAE,cAAc,EAAkB,MAAM,WAAW,CAAC;AAqD3D;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,GAAW,EAAE,OAA2B;IACxE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,EAAE,EAAE,KAAK,EAAE,SAAS,GAAG,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC;IAC/E,MAAM,cAAc,CAAC,IAAI,CAAC,CAAC;IAE3B,MAAM,SAAS,GAAG,IAAI,gBAAgB,EAAE,CAAC;IACzC,MAAM,MAAM,GAAG,SAAS,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAC7C,IAAI,MAAM,GAAG,IAAI,CAAC;IAElB,MAAM,IAAI,GAAG,CAAC,IAAY,EAAQ,EAAE;QAClC,IAAI,IAAI,KAAK,MAAM;YAAE,OAAO;QAC5B,SAAS,CAAC,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QACnC,MAAM,GAAG,IAAI,CAAC;IAChB,CAAC,CAAC;IACF,MAAM,MAAM,GAAG,KAAK,EAAE,IAAY,EAAiB,EAAE;QACnD,IAAI,CAAC,IAAI,CAAC,CAAC;QACX,MAAM,gBAAgB,CAAC,SAAS,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;IACvE,CAAC,CAAC;IAEF,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;IAEnB,OAAO;QACL,GAAG;QACH,QAAQ;QACR,UAAU;QACV,KAAK,CAAC,KAAK,CAAC,IAAI;YACd,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;YACnB,OAAO,SAAS,CAAC,KAAK,EAAE,CAAC;QAC3B,CAAC;QACD,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS;YACzB,IAAI,CAAC,IAAI,CAAC,CAAC;YACX,OAAO,SAAS,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;QAClD,CAAC;QACD,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS;YAC5B,IAAI,CAAC,IAAI,CAAC,CAAC;YACX,OAAO,SAAS,CAAC,WAAW,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;QACxD,CAAC;QACD,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS;YAC9B,IAAI,CAAC,IAAI,CAAC,CAAC;YACX,OAAO,SAAS,CAAC,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;QAC3D,CAAC;QACD,KAAK,CAAC,OAAO,CAAC,IAAI;YAChB,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;YACnB,OAAO,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACnC,CAAC;QACD,kBAAkB,CAAC,UAAU;YAC3B,SAAS,CAAC,0BAA0B,CAAC,UAAU,CAAC,CAAC;QACnD,CAAC;QACD,SAAS;QACT,KAAK;YACH,SAAS,CAAC,IAAI,EAAE,CAAC;QACnB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fossil-lang/wasm",
-  "version": "0.3.0-alpha.7",
+  "version": "0.3.0-alpha.9",
   "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": {
@@ -33,7 +33,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@fossil-lang/types": "0.3.0-alpha.7"
+    "@fossil-lang/types": "0.3.0-alpha.9"
   },
   "devDependencies": {
     "typescript": "^5.6.0",