@lix-js/sdk 0.8.4 → 0.10.0

package/README.md

@@ -22,6 +22,72 @@ console.log(result.rows[0]?.get("message"));
 await lix.close();
 ```
 
+## Remote workspaces
+
+Use the same Lix client as a thin client against a hosted workspace:
+
+```ts
+const lix = await openLix({
+	server: {
+		mode: "remote",
+		url: "https://lixray.com/@namespace/workspace",
+		headers: async () => ({
+			Authorization: `Bearer ${await accessToken()}`,
+		}),
+	},
+});
+
+const files = lix.observe("SELECT path FROM lix_file ORDER BY path");
+const initial = await files.next();
+
+await lix.execute(
+	"INSERT INTO lix_file (path, content) VALUES ($1, $2)",
+	["/hello.txt", new TextEncoder().encode("hello")],
+);
+const update = await files.next();
+
+files.close();
+await lix.close();
+```
+
+Without `storage`, remote mode uses the server for all persistence and does not
+open a local engine. Dynamic headers are resolved for every request and
+observation reconnect. An injected `fetch` can route requests through a service
+binding or another authorized server-side transport.
+
+Browser clients can opt into private, durable client state with the local
+storage adapter:
+
+```ts
+import { openLix } from "@lix-js/sdk";
+import { LocalStorage } from "@lix-js/sdk/local-storage-adapter";
+
+const lix = await openLix({
+	server: {
+		mode: "remote",
+		url: "https://lixray.com/@namespace/workspace",
+	},
+	storage: new LocalStorage(),
+});
+
+const previousUiState = lix.clientState.get("atelier-ui");
+await lix.clientState.set("atelier-ui", { sidebar: "history" });
+```
+
+`lix.clientState` is hydrated before `openLix()` resolves, so reads are
+synchronous. Its JSON values and the client's active branch are stored in a
+private local Lix snapshot; workspace SQL continues to execute only on the
+server. Reopening the same remote URL with the same storage restores both. Each
+remote server session is branch-pinned, so switching one client does not switch
+another client.
+
+After a remote branch switch succeeds, saving that branch as the next-reopen
+preference is best effort: a client-storage failure does not turn the completed
+server switch into a rejected operation. Explicit `lix.clientState.set()` and
+`.delete()` calls report durability failures to their caller. Because the local
+Rust transaction has already committed, `get()` continues to expose that live
+session value; a later successful snapshot save can make it durable.
+
 Filesystem sync and SQLite persistence use native Node.js dependencies:
 
 ```ts
@@ -35,20 +101,37 @@ const lix = await openLix({
 });
 
 await lix.execute(
-	"INSERT INTO lix_file (path, data) VALUES ($1, $2) ON CONFLICT (path) DO UPDATE SET data = excluded.data",
+	"INSERT INTO lix_file (path, content) VALUES ($1, $2) ON CONFLICT (path) DO UPDATE SET content = excluded.content",
 	["/hello.txt", new TextEncoder().encode("world")],
 );
 
-const result = await lix.execute("SELECT data FROM lix_file WHERE path = $1", [
+const result = await lix.execute("SELECT content FROM lix_file WHERE path = $1", [
 	"/hello.txt",
 ]);
-const bytes = result.rows[0]?.value("data").asBytes();
+const bytes = result.rows[0]?.value("content").asBytes();
 
 console.log(bytes && new TextDecoder().decode(bytes));
 
 await lix.close();
 ```
 
+## Discover the SQL contract
+
+Lix extends the standard `information_schema.columns` relation with
+`lix_value_kind` and `lix_insert_policy`. Inspect it before generating writes:
+
+```sql
+SELECT table_name, column_name, data_type, is_nullable, column_default,
+       lix_value_kind, lix_insert_policy
+FROM information_schema.columns
+WHERE table_name = 'lix_file'
+ORDER BY ordinal_position;
+```
+
+`lix_insert_policy` distinguishes `REQUIRED`, `DEFAULT`, `CONDITIONAL`, and
+`READ_ONLY` columns. For the complete table and history-function map, see
+[SQL Surfaces](https://lix.dev/docs/surfaces).
+
 ## Branches
 
 ```ts
@@ -57,7 +140,7 @@ const draft = await lix.createBranch({ name: "Draft" });
 
 await lix.switchBranch({ branchId: draft.id });
 await lix.execute(
-	"INSERT INTO lix_file (path, data) VALUES ($1, $2) ON CONFLICT (path) DO UPDATE SET data = excluded.data",
+	"INSERT INTO lix_file (path, content) VALUES ($1, $2) ON CONFLICT (path) DO UPDATE SET content = excluded.content",
 	["/status.txt", new TextEncoder().encode("draft")],
 );
 
@@ -73,11 +156,11 @@ const tx = await lix.beginTransaction();
 
 try {
 	await tx.execute(
-		"INSERT INTO lix_file (path, data) VALUES ($1, $2) ON CONFLICT (path) DO UPDATE SET data = excluded.data",
+		"INSERT INTO lix_file (path, content) VALUES ($1, $2) ON CONFLICT (path) DO UPDATE SET content = excluded.content",
 		["/a.txt", new TextEncoder().encode("1")],
 	);
 	await tx.execute(
-		"INSERT INTO lix_file (path, data) VALUES ($1, $2) ON CONFLICT (path) DO UPDATE SET data = excluded.data",
+		"INSERT INTO lix_file (path, content) VALUES ($1, $2) ON CONFLICT (path) DO UPDATE SET content = excluded.content",
 		["/b.txt", new TextEncoder().encode("2")],
 	);
 	await tx.commit();
@@ -93,36 +176,36 @@ try {
 - Pass `new LocalFilesystem({ path, lixDir, syncAllFiles: true })` for filesystem sync with repository metadata in an external `.lix` directory and no workspace `.lix` directory.
 - Pass `syncAllFiles: false` to start filesystem sync with no regular workspace files, then call `storage.importPaths(["notes/today.md"])` on the `LocalFilesystem` instance to sync selected files. Imported paths are exact workspace-relative file paths, not directories or globs.
 - Use `new SQLite({ path })` when a single SQLite-backed `.lix` file is the application document itself, for example when defining a new file format and using Lix as the application's file format.
-- In browsers, `openLix()` loads the Rust engine as WebAssembly and uses the
-  in-memory storage.
+- In browsers, local mode and remote mode with client storage load the Rust
+  engine as WebAssembly. Supplying a snapshot storage adapter persists that
+  local Lix; in remote mode, the local engine contains only client state.
 - `LocalFilesystem` and `SQLite` are Node.js-only. Constructing them is safe in
   shared code, but passing one to `openLix()` in a browser throws an error.
 - The package is ESM-only.
 - The package uses conditional ESM imports internally: Node.js resolves the
   native N-API binding, while browsers and other runtimes resolve the portable
   WebAssembly binding. Vite follows this split without consumer configuration.
-- Every `openLix()` owns one dedicated worker. The engine, storage, and
-  installed WASM plugin components all run in that worker in both Node.js and
-  browsers, so database and plugin work does not block the page's main thread.
-- Installed WASM plugin components are transpiled with JCO and executed by the
-  worker's WebAssembly runtime in both environments. Plugin execution does not
-  yet enforce the declared fuel, timeout, or memory limits, so only install
-  trusted plugins.
+- Every browser `openLix()` owns one dedicated worker, so database work does
+  not block the page's main thread. Node.js uses the native binding's actor.
+- Node.js executes installed Component API v1 plugins with the Rust SDK's
+  Wasmtime runtime. The browser and Workerd bindings currently open without a
+  component runtime: they can use ordinary Lix storage and SQL, but do not
+  execute installed plugins. A browser Component host is a separate follow-up.
 - A page Content Security Policy only needs to permit the package's same-origin
-  worker. WebAssembly compilation and JCO's generated `data:` module imports
-  happen inside that worker, so they can be scoped to the worker script's HTTP
-  response instead of being allowed by the document:
+  worker. WebAssembly compilation happens inside that worker, so the required
+  permission can be scoped to the worker script's HTTP response instead of
+  being allowed by the document:
 
   ```http
   # HTML document response
   Content-Security-Policy: default-src 'self'; script-src 'self'; worker-src 'self'
 
   # Lix worker response (Vite emits assets/entry.browser-<hash>.js)
-  Content-Security-Policy: default-src 'none'; script-src 'self' data: 'wasm-unsafe-eval'; connect-src 'self'
+  Content-Security-Policy: default-src 'none'; script-src 'self' 'wasm-unsafe-eval'; connect-src 'self'
   ```
 
   Hosts that apply one policy to every response can use
-  `script-src 'self' data: 'wasm-unsafe-eval'; worker-src 'self'` globally
+  `script-src 'self' 'wasm-unsafe-eval'; worker-src 'self'` globally
   instead. Worker-scoped headers keep those permissions out of the page.
 - SQL parameters use normal JavaScript values: `string`, finite `number`, `boolean`, `Uint8Array`, `null`, JSON-compatible arrays, and JSON-compatible plain objects.
 - Use `Value.integer(...)`, `Value.real(...)`, `Value.text(...)`, `Value.json(...)`, or `Value.blob(...)` only when you need to pass an explicit native Lix value.
@@ -141,8 +224,8 @@ npm run test:browser
 
 `npm run test:browser:production` additionally packs the SDK, installs the
 tarball into a minimal Vite app, makes a production build, and exercises SQL
-plus both bundled plugins in Chromium. It runs with both worker-scoped and
-global strict CSP headers.
+plus bundled-plugin archive loading in Chromium. It runs with both
+worker-scoped and global strict CSP headers.
 
 Use `npm run build:wasm:dev` while iterating on the Rust bridge when release
 optimization is unnecessary.

package/dist/binding-types.d.ts

@@ -1,4 +1,4 @@
-import type { CreateBranchOptions, CreateBranchReceipt, ExecuteOptions, MergeBranchOptions, MergeBranchPreview, MergeBranchReceipt, SwitchBranchOptions, SwitchBranchReceipt } from "./types.js";
+import type { CreateBranchOptions, CreateBranchReceipt, CreateCheckpointReceipt, UndoReceipt, RedoReceipt, ExecuteOptions, LixBatchOptions, MergeBranchOptions, MergeBranchPreview, MergeBranchReceipt, SwitchBranchOptions, SwitchBranchReceipt, LixTelemetrySpan, JsonValue } from "./types.js";
 import type { NativeLixValue } from "./value.js";
 export type BindingExecuteResult = {
     columns: string[];
@@ -16,17 +16,35 @@ export type BindingObserveEvent = {
     rows: BindingExecuteResult;
 };
 export type BindingParam = NativeLixValue;
+export type BindingBatchStatement = {
+    sql: string;
+    params: BindingParam[];
+};
 export type LixBinding = {
     execute(sql: string, params: BindingParam[], options?: ExecuteOptions): Promise<BindingExecuteResult>;
+    executeBatch(statements: BindingBatchStatement[], options?: LixBatchOptions): Promise<BindingExecuteResult[]>;
     observe(sql: string, params: BindingParam[]): Promise<ObserveEventsBinding>;
     beginTransaction(): Promise<LixTransactionBinding>;
     activeBranchId(): Promise<string>;
+    activeAccountId(): Promise<string>;
+    clientStateEntries?(): Promise<Array<{
+        key: string;
+        value: JsonValue;
+    }>>;
+    clientStateGet?(key: string): Promise<JsonValue | undefined>;
+    clientStateSet?(key: string, value: JsonValue): Promise<void>;
+    clientStateDelete?(key: string): Promise<void>;
     createBranch(options: CreateBranchOptions): Promise<CreateBranchReceipt>;
+    createCheckpoint(): Promise<CreateCheckpointReceipt>;
+    undo(): Promise<UndoReceipt>;
+    redo(): Promise<RedoReceipt>;
     switchBranch(options: SwitchBranchOptions): Promise<SwitchBranchReceipt>;
     importFilesystemPaths(paths: string[]): Promise<void>;
     mergeBranchPreview(options: MergeBranchOptions): Promise<MergeBranchPreview>;
     mergeBranch(options: MergeBranchOptions): Promise<MergeBranchReceipt>;
     syncDiskToLix(): Promise<void>;
+    /** Internal snapshot capability implemented by browser memory bindings. */
+    exportSnapshot?(): Promise<Uint8Array>;
     close(): Promise<void>;
 };
 export type LixTransactionBinding = {
@@ -38,9 +56,10 @@ export type ObserveEventsBinding = {
     next(): Promise<BindingObserveEvent | null | undefined>;
     close(): void;
 };
-export type PluginRuntimeDispatch = (request: unknown) => Promise<unknown>;
+export type TelemetryDispatch = (span: LixTelemetrySpan) => void;
 export type LixStorageConfig = {
     kind: "memory";
+    snapshot?: Uint8Array;
 } | {
     kind: "sqlite";
     path: string;

package/dist/binding.browser.d.ts

@@ -1,2 +1,2 @@
-import type { LixStorageConfig, LixBinding, PluginRuntimeDispatch } from "./binding-types.js";
-export declare function openLixBinding(storage: LixStorageConfig, dispatch: PluginRuntimeDispatch): Promise<LixBinding>;
+import type { LixStorageConfig, LixBinding, TelemetryDispatch } from "./binding-types.js";
+export declare function openLixBinding(storage: LixStorageConfig, telemetry?: TelemetryDispatch): Promise<LixBinding>;

package/dist/binding.browser.js

@@ -1,14 +1,14 @@
 // Generated before TypeScript compilation and emitted beside this module.
 // @ts-expect-error Generated by build:wasm.
-import initWasm, { openMemory } from "./wasm/lix_js_sdk.js";
+import initWasm, { openMemoryFromSnapshot } from "./wasm/lix_js_sdk.js";
 let wasmInitialized;
 function initializeWasm() {
     return (wasmInitialized ??= initWasm());
 }
-export async function openLixBinding(storage, dispatch) {
+export async function openLixBinding(storage, telemetry) {
     if (storage.kind !== "memory") {
         throw new Error(`${storage.kind === "localFilesystem" ? "LocalFilesystem" : "SQLite"} is only available in Node.js`);
     }
     await initializeWasm();
-    return openMemory(dispatch);
+    return openMemoryFromSnapshot(telemetry, storage.snapshot);
 }

package/dist/binding.node.d.ts

@@ -1,2 +1,2 @@
-import type { LixStorageConfig, LixBinding, PluginRuntimeDispatch } from "./binding-types.js";
-export declare function openLixBinding(storage: LixStorageConfig, dispatch: PluginRuntimeDispatch): Promise<LixBinding>;
+import type { LixStorageConfig, LixBinding, TelemetryDispatch } from "./binding-types.js";
+export declare function openLixBinding(storage: LixStorageConfig, telemetry?: TelemetryDispatch): Promise<LixBinding>;

package/dist/binding.node.js

@@ -39,13 +39,27 @@ catch (cause) {
     error.cause = cause;
     throw error;
 }
-export function openLixBinding(storage, dispatch) {
+export function openLixBinding(storage, telemetry) {
+    const nativeTelemetry = telemetry
+        ? (spanJson) => telemetry(JSON.parse(spanJson))
+        : undefined;
     switch (storage.kind) {
         case "memory":
-            return addon.Lix.openMemory(dispatch);
+            if (storage.snapshot !== undefined) {
+                throw new Error("Memory snapshots are only available in the browser binding");
+            }
+            if (nativeTelemetry)
+                return addon.Lix.openMemory(nativeTelemetry);
+            return addon.Lix.openMemory();
         case "sqlite":
-            return addon.Lix.openSQLite(storage.path, dispatch);
+            if (nativeTelemetry) {
+                return addon.Lix.openSQLite(storage.path, nativeTelemetry);
+            }
+            return addon.Lix.openSQLite(storage.path);
         case "localFilesystem":
-            return addon.Lix.openLocalFilesystem(storage.path, storage.lixDir, storage.syncAllFiles, dispatch);
+            if (nativeTelemetry) {
+                return addon.Lix.openLocalFilesystem(storage.path, storage.lixDir, storage.syncAllFiles, nativeTelemetry);
+            }
+            return addon.Lix.openLocalFilesystem(storage.path, storage.lixDir, storage.syncAllFiles);
     }
 }

package/dist/bundled-plugins.js

@@ -1,7 +1,7 @@
 const BUNDLED_PLUGIN_MANIFEST = [
     {
-        key: "plugin_md_v2",
-        fileName: "plugin_md_v2.lixplugin",
+        key: "plugin_markdown",
+        fileName: "plugin_markdown.lixplugin",
     },
     {
         key: "plugin_csv",

package/dist/client-state.d.ts

@@ -0,0 +1,53 @@
+import type { LixBinding } from "./binding-types.js";
+import type { JsonValue, LixSnapshotStorage } from "./types.js";
+export declare const ACTIVE_BRANCH_CLIENT_STATE_KEY = "lix_active_branch_id";
+export declare const ACTIVE_ACCOUNT_CLIENT_STATE_KEY = "lix_active_account_id";
+export type LixClientState = {
+    /** Returns the hydrated client-local value without a network round trip. */
+    get<T extends JsonValue = JsonValue>(key: string): T | undefined;
+    /** Persists a client-local value in the configured client storage. */
+    set(key: string, value: JsonValue): Promise<void>;
+    /** Deletes a client-local value from the configured client storage. */
+    delete(key: string): Promise<void>;
+    /** Subscribes to successful mutations made through this client-state handle. */
+    subscribe(listener: () => void): () => void;
+};
+export type ManagedClientState = LixClientState & {
+    close(): Promise<void>;
+};
+export declare function unavailableClientState(): LixClientState;
+type ClientStateBinding = LixBinding & {
+    exportSnapshot?: () => Promise<Uint8Array>;
+};
+export type OpenClientStateOptions = {
+    readonly binding: ClientStateBinding;
+    readonly saveSnapshot?: (snapshot: Uint8Array) => Promise<void>;
+    readonly closeBinding?: boolean;
+};
+/**
+ * Opens the typed client-state facade over a private local Rust Lix.
+ *
+ * Values are ordinary global, untracked `lix_key_value` rows. The physical
+ * prefix is intentionally private so built-in Lix key/value rows never leak
+ * through this small API.
+ */
+export declare function openClientState(options: OpenClientStateOptions): Promise<ManagedLixClientState>;
+export declare class ManagedLixClientState implements LixClientState {
+    #private;
+    constructor(options: OpenClientStateOptions, initial: Map<string, JsonValue>);
+    get<T extends JsonValue = JsonValue>(key: string): T | undefined;
+    set(key: string, value: JsonValue): Promise<void>;
+    delete(key: string): Promise<void>;
+    subscribe(listener: () => void): () => void;
+    close(): Promise<void>;
+}
+/**
+ * Opens client state directly over snapshot storage without starting a local
+ * Lix runtime. This is used by remote Lix connections, where the storage
+ * option persists client-local state rather than the remote workspace.
+ */
+export declare function openStoredClientState(options: {
+    readonly storage: LixSnapshotStorage;
+    readonly namespace: string;
+}): Promise<ManagedClientState>;
+export {};