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

package/README.md

@@ -2,6 +2,8 @@
 
 JS/TS wrapper around the `fossil-wasm` Rust crate's wasm-bindgen artefacts. Provides:
 
+- `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
@@ -11,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

package/dist/index.d.ts

@@ -7,6 +7,9 @@
  * - {@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,15 +18,18 @@
  *
  * Consumer pattern (wasm-bindgen --target web):
  *
- *   import { initFossilWasm, tokenize } from '@fossil-lang/wasm';
+ *   import { openProgram } from '@fossil-lang/wasm';
+ *   import { fossil } from '@fossil-lang/codemirror-fossil';
  *
- *   await initFossilWasm();
- *   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 { 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;;;;;;;;;;;;;;;;;;;;;GAqBG;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;;;;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

@@ -7,6 +7,9 @@
  * - {@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,10 +18,11 @@
  *
  * Consumer pattern (wasm-bindgen --target web):
  *
- *   import { initFossilWasm, tokenize } from '@fossil-lang/wasm';
+ *   import { openProgram } from '@fossil-lang/wasm';
+ *   import { fossil } from '@fossil-lang/codemirror-fossil';
  *
- *   await initFossilWasm();
- *   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) —
@@ -28,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;;;;;;;;;;;;;;;;;;;;;GAqBG;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/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.8",
+  "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.8"
+    "@fossil-lang/types": "0.3.0-alpha.9"
   },
   "devDependencies": {
     "typescript": "^5.6.0",