@grayfalcon666/loom 1.0.0

package/index.js

@@ -0,0 +1,137 @@
+/**
+ * @grayfalcon/loom — entry point
+ *
+ * Exports:
+ *   init(wasmUrl?)  — async, returns LoomAPI (WASM is embedded as base64 by default)
+ *   default export  — same as named { init }
+ *
+ * Zero-config usage (WASM embedded, no extra files):
+ *   import { init } from '@grayfalcon/loom';
+ *   const loom = await init();
+ *
+ * Custom WASM URL (e.g. from /slim export):
+ *   import { init } from '@grayfalcon/loom/slim';
+ *   const loom = await init('/node_modules/@grayfalcon/loom/loom.wasm');
+ */
+
+import wasmExecJs from './wasm_exec.js';
+import { loomWasmB64 } from './embedded_wasm.js';
+
+/** @type {typeof import('./wasm_exec.js')} */
+const Go = wasmExecJs.Go;
+
+let _rawLoom = null;
+let _initPromise = null;
+
+/**
+ * @param {string} [wasmUrl]  Optional. If omitted, uses the embedded base64 WASM.
+ *                             Pass a URL to a loom.wasm file (useful for /slim export).
+ * @returns {Promise<import('./loom').LoomAPI>}
+ */
+export async function init(wasmUrl) {
+  if (_rawLoom) {
+    return buildAPI();
+  }
+
+  if (_initPromise) {
+    await _initPromise;
+    return buildAPI();
+  }
+
+  _initPromise = (async () => {
+    if (wasmUrl) {
+      // URL-based loading: fetch the .wasm file from the network
+      await loadWasmFromUrl(wasmUrl);
+    } else {
+      // Embedded loading: decode base64 WASM, no network request needed
+      await loadWasmFromBase64();
+    }
+  })();
+
+  await _initPromise;
+  return buildAPI();
+}
+
+async function loadWasmFromUrl(url) {
+  const go = new Go();
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`[loom] Failed to fetch WASM from ${url}: HTTP ${response.status}`);
+  }
+  const result = await WebAssembly.instantiateStreaming(response, go.importObject);
+  go.run(result.instance);
+  _rawLoom = await waitForLoom();
+}
+
+async function loadWasmFromBase64() {
+  // Decode base64 to Uint8Array — no fetch, no CORS, no extra files
+  const binaryString = atob(loomWasmB64);
+  const bytes = new Uint8Array(binaryString.length);
+  for (let i = 0; i < binaryString.length; i++) {
+    bytes[i] = binaryString.charCodeAt(i);
+  }
+
+  const go = new Go();
+  const result = await WebAssembly.instantiate(bytes, go.importObject);
+  go.run(result.instance);
+  _rawLoom = await waitForLoom();
+}
+
+async function waitForLoom() {
+  let attempts = 0;
+  while (!_rawLoom && attempts < 100) {
+    await new Promise(r => setTimeout(r, 20));
+    _rawLoom = globalThis.loom ?? null;
+    attempts++;
+  }
+  if (!_rawLoom) {
+    throw new Error('[loom] Go init() did not register the loom namespace within 2s');
+  }
+  return _rawLoom;
+}
+
+function buildAPI() {
+  const api = {
+    // Core API — camelCase (preferred)
+    newDocument:      (actorID)         => _rawLoom.newDocument(actorID),
+    freeDocument:     (docID)           => _rawLoom.freeDocument(docID),
+    set:               (docID, k, v)     => _rawLoom.set(docID, k, v),
+    get:               (docID, k)        => _rawLoom.get(docID, k),
+    addText:           (docID, k, tid)   => _rawLoom.addText(docID, k, tid),
+    insertChar:        (docID, tid, idx, code) => _rawLoom.insertChar(docID, tid, idx, code),
+    deleteChar:        (docID, tid, idx)       => _rawLoom.deleteChar(docID, tid, idx),
+    peekText:          (docID, tid)     => _rawLoom.peekText(docID, tid),
+    textString:        (docID, tid)     => _rawLoom.textString(docID, tid),
+    getText:           (docID, tid)      => _rawLoom.getText(docID, tid),
+    receive:           (docID, opJSON)   => _rawLoom.receive(docID, opJSON),
+    unwrapReceive:      (docID, opJSON)  => _rawLoom.unwrapReceive(docID, opJSON),
+    save:              (docID)           => _rawLoom.save(docID),
+    load:              (snapshotJSON)    => _rawLoom.load(snapshotJSON),
+    getActorID:        (docID)           => _rawLoom.getActorID(docID),
+
+    // Legacy / demo.html compatibility aliases
+    Loom_NewDocument:   (aid)    => _rawLoom.newDocument(aid),
+    Loom_FreeDocument:   (docID) => _rawLoom.freeDocument(docID),
+    Loom_Set:            (docID, k, v)   => _rawLoom.set(docID, k, v),
+    Loom_Get:            (docID, k)      => _rawLoom.get(docID, k),
+    Loom_AddText:        (docID, k, tid) => _rawLoom.addText(docID, k, tid),
+    Loom_InsertChar:     (docID, tid, idx, c) => _rawLoom.insertChar(docID, tid, idx, c),
+    Loom_DeleteChar:     (docID, tid, idx)    => _rawLoom.deleteChar(docID, tid, idx),
+    Loom_TextString:     (docID, tid)    => _rawLoom.textString(docID, tid),
+    Loom_PeekText:       (docID, tid)    => _rawLoom.peekText(docID, tid),
+    Loom_Receive:        (docID, op)     => _rawLoom.receive(docID, op),
+    Loom_UnwrapReceive:  (docID, op)     => _rawLoom.unwrapReceive(docID, op),
+    Loom_Save:           (docID)         => _rawLoom.save(docID),
+    Loom_Load:           (snap)          => _rawLoom.load(snap),
+    Loom_GetActorID:     (docID)         => _rawLoom.getActorID(docID),
+  };
+
+  // Also expose on globalThis for debug / non-module environments
+  globalThis.loom = api;
+  return api;
+}
+
+// Also patch globalThis.Loom for the legacy demo.html pattern
+globalThis.Loom = { init };
+
+export default { init };

package/loom.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Loom CRDT — TypeScript declarations
+ *
+ * The Loom CRDT engine runs in the browser as a WebAssembly module,
+ * powered by Go's syscall/js. A single call to Loom.init() loads
+ * the WASM binary and registers all functions.
+ *
+ * Basic usage:
+ *   import { init } from '@grayfalcon/loom';
+ *   const loom = await init();
+ *   const doc = loom.newDocument('alice');
+ *   loom.addText(doc, 'body', 'text-1');
+ *   const op = loom.insertChar(doc, 'text-1', 0, 'H'.charCodeAt(0));
+ *   ws.send(op);                        // send to your WS server
+ *   loom.unwrapReceive(otherDoc, op);   // apply remote op
+ *   console.log(loom.peekText(doc, 'text-1')); // 'H'
+ */
+
+export interface LoomAPI {
+  /**
+   * Create a new CRDT document for the given actor.
+   * Returns a numeric document ID used in all subsequent calls.
+   */
+  newDocument(actorID: string): number;
+
+  /** Free a document from WASM memory. Call when done. */
+  freeDocument(docID: number): void;
+
+  // ── LWWMap (key-value) ────────────────────────────────────────────────────
+
+  /** Set a key-value pair in the document's root map. Returns Op JSON string. */
+  set(docID: number, key: string, value: string): string | null;
+
+  /** Get the current value for a key in the root map. Returns JSON string or null. */
+  get(docID: number, key: string): string | null;
+
+  // ── RGA String (collaborative text) ───────────────────────────────────────
+
+  /**
+   * Declare a shared text object at a key under the root map.
+   * Call this on both local and remote documents before inserting characters.
+   * Returns Op JSON string (send this to your WS server so peers can call addText too).
+   */
+  addText(docID: number, key: string, textObjID: string): string | null;
+
+  /**
+   * Insert a character at a given index into the shared text object.
+   * Returns Op JSON string — send this to your WS server for distribution.
+   *
+   * @param docID     Document ID from newDocument()
+   * @param textObjID Text object ID, must match what addText() used
+   * @param index     Character index (0 = before first char, len = after last)
+   * @param charCode  Unicode code point (e.g. 'A'.charCodeAt(0) === 65)
+   */
+  insertChar(docID: number, textObjID: string, index: number, charCode: number): string | null;
+
+  /**
+   * Delete the character at a given index from the shared text object.
+   * Returns Op JSON string — send this to your WS server for distribution.
+   *
+   * @param index  0-based index of the character to delete
+   */
+  deleteChar(docID: number, textObjID: string, index: number): string | null;
+
+  /**
+   * Get the current text content as a plain JavaScript string.
+   * Aliases: peekText (identical), textString (identical)
+   */
+  peekText(docID: number, textObjID: string): string;
+
+  /** @deprecated Alias for peekText. Use peekText or getText instead. */
+  textString(docID: number, textObjID: string): string;
+
+  /** @deprecated Alias for peekText. Use peekText instead. */
+  getText(docID: number, textObjID: string): string;
+
+  // ── Remote Ops ─────────────────────────────────────────────────────────────
+
+  /**
+   * Apply a remote Op (received from a peer) to the local document.
+   * Handles all Op types: set, addText, insertChar, deleteChar.
+   * Alias: unwrapReceive (identical).
+   */
+  receive(docID: number, opJSON: string): void;
+
+  /** @deprecated Alias for receive. Use receive instead. */
+  unwrapReceive(docID: number, opJSON: string): void;
+
+  // ── Persistence ─────────────────────────────────────────────────────────────
+
+  /**
+   * Serialize the document to a JSON snapshot string.
+   * Use this to save document state to localStorage / your backend.
+   */
+  save(docID: number): string;
+
+  /**
+   * Load a document from a JSON snapshot (previously obtained via save()).
+   * Returns a new document ID.
+   */
+  load(snapshotJSON: string): number;
+
+  // ── Utilities ───────────────────────────────────────────────────────────────
+
+  /** Get the actor ID string for a document. */
+  getActorID(docID: number): string;
+
+  // ── Raw / Legacy aliases (used by demo.html) ──────────────────────────────
+  Loom_NewDocument: (actorID: string) => number;
+  Loom_FreeDocument: (docID: number) => void;
+  Loom_Set: (docID: number, key: string, value: string) => string | null;
+  Loom_Get: (docID: number, key: string) => string | null;
+  Loom_AddText: (docID: number, key: string, textObjID: string) => string | null;
+  Loom_InsertChar: (docID: number, textObjID: string, index: number, charCode: number) => string | null;
+  Loom_DeleteChar: (docID: number, textObjID: string, index: number) => string | null;
+  Loom_TextString: (docID: number, textObjID: string) => string;
+  Loom_PeekText: (docID: number, textObjID: string) => string;
+  Loom_Receive: (docID: number, opJSON: string) => void;
+  Loom_UnwrapReceive: (docID: number, opJSON: string) => void;
+  Loom_Save: (docID: number) => string;
+  Loom_Load: (snapshotJSON: string) => number;
+  Loom_GetActorID: (docID: number) => string;
+}
+
+/**
+ * Initialize the Loom WASM module.
+ *
+ * The WASM binary is embedded as a base64 data URL, so no extra file copy is needed —
+ * just `npm install` and call init(). No CORS issues.
+ *
+ * @param wasmUrl  Optional URL to a loom.wasm file.
+ *                 If omitted, uses the bundled base64-encoded WASM (recommended).
+ *                 Pass a custom URL only if you need to host the .wasm file yourself
+ *                 (e.g. for the /slim export).
+ */
+export function init(wasmUrl?: string): Promise<LoomAPI>;
+
+/** @deprecated Use the named export `init` instead. */
+export default { init };

package/loom.js

@@ -0,0 +1,94 @@
+/**
+ * loom.js — JavaScript wrapper for the Loom CRDT WASM module.
+ *
+ * Uses syscall/js API: Go registers loom.* functions via js.Global() in init().
+ * No manual memory management needed.
+ *
+ * Usage:
+ *   const loom = await Loom.init();
+ *   const docID = loom.newDocument("alice");
+ *   loom.set(docID, "title", "Hello");
+ */
+
+let _rawLoom = null;
+
+async function init(wasmPath = "./loom.wasm") {
+  if (typeof globalThis.WebAssembly === "undefined") {
+    throw new Error("WebAssembly is not supported");
+  }
+
+  const wasmExecPath = wasmPath.replace(/[^/\\]+$/, "wasm_exec.js");
+  await import(wasmExecPath);
+
+  const GoCtor = globalThis.Go;
+  if (typeof GoCtor !== "function") {
+    throw new Error("wasm_exec.js did not set globalThis.Go");
+  }
+
+  const go = new GoCtor();
+  let instance;
+  const response = await fetch(wasmPath);
+  if (!response.ok) throw new Error("HTTP " + response.status);
+  const result = await WebAssembly.instantiateStreaming(response, go.importObject);
+  instance = result.instance;
+
+  go.run(instance);
+
+  // Wait for Go init() to register loom.* functions
+  let attempts = 0;
+  while (!globalThis.loom && attempts < 20) {
+    await new Promise(r => setTimeout(r, 10));
+    attempts++;
+  }
+  if (!globalThis.loom) {
+    throw new Error("Go init() did not register loom namespace");
+  }
+
+  _rawLoom = globalThis.loom;
+
+  const api = {
+    newDocument(actorID)        { return _rawLoom.newDocument(actorID); },
+    freeDocument(docID)          { _rawLoom.freeDocument(docID); },
+    set(docID, key, value)      { return _rawLoom.set(docID, key, value); },
+    get(docID, key)              { return _rawLoom.get(docID, key); },
+    addText(docID, key, textID)  { return _rawLoom.addText(docID, key, textID); },
+    insertChar(docID, textID, idx, code) { return _rawLoom.insertChar(docID, textID, idx, code); },
+    deleteChar(docID, textID, idx)      { return _rawLoom.deleteChar(docID, textID, idx); },
+    textString(docID, textID)   { return _rawLoom.textString(docID, textID); },
+    receive(docID, opJSON)      { return _rawLoom.receive(docID, opJSON); },
+    save(docID)                 { return _rawLoom.save(docID); },
+    load(snapshotJSON)          { return _rawLoom.load(snapshotJSON); },
+    getActorID(docID)          { return _rawLoom.getActorID(docID); },
+    getText(docID, textID)     { return _rawLoom.getText(docID, textID); },
+
+    // Aliases for demo.html
+    peekText(docID, textID) {
+      return _rawLoom.peekText ? _rawLoom.peekText(docID, textID)
+                               : _rawLoom.textString(docID, textID);
+    },
+    unwrapReceive(docID, opJSON) { return _rawLoom.receive(docID, opJSON); },
+
+    Loom_Set:          (docID, k, v) => _rawLoom.set(docID, k, v),
+    Loom_InsertChar:   (docID, tid, idx, c) => _rawLoom.insertChar(docID, tid, idx, c),
+    Loom_DeleteChar:   (docID, tid, idx) => _rawLoom.deleteChar(docID, tid, idx),
+    Loom_Get:          (docID, k) => _rawLoom.get(docID, k),
+    Loom_AddText:      (docID, k, tid) => _rawLoom.addText(docID, k, tid),
+    Loom_TextString:   (docID, tid) => _rawLoom.textString(docID, tid),
+    Loom_PeekText:     (docID, tid) => api.peekText(docID, tid),
+    Loom_Receive:      (docID, op) => _rawLoom.receive(docID, op),
+    Loom_UnwrapReceive:(docID, op) => _rawLoom.receive(docID, op),
+    Loom_Save:         (docID) => _rawLoom.save(docID),
+    Loom_Load:         (snap) => _rawLoom.load(snap),
+    Loom_NewDocument:  (aid) => _rawLoom.newDocument(aid),
+    Loom_FreeDocument: (docID) => _rawLoom.freeDocument(docID),
+    Loom_GetActorID:  (docID) => _rawLoom.getActorID(docID),
+  };
+
+  globalThis.loom = api;
+  console.log("[loom] Ready. Functions:", Object.keys(_rawLoom).join(", "));
+  return api;
+}
+
+globalThis.Loom = { init };
+export { init };
+export default { init };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@grayfalcon666/loom",
+  "version": "1.0.0",
+  "description": "A Go/WASM CRDT engine for collaborative text editing — runs in the browser with no build step",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./loom.d.ts",
+  "exports": {
+    ".": {
+      "browser": "./index.js",
+      "node": "./index.js",
+      "default": "./index.js"
+    },
+    "./loom.js": "./loom.js",
+    "./loom.wasm": "./loom.wasm",
+    "./slim": "./loom.js"
+  },
+  "files": [
+    "index.js",
+    "loom.js",
+    "loom.wasm",
+    "loom.d.ts",
+    "wasm_exec.js",
+    "embedded_wasm.js"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepublishOnly": "node scripts/build.mjs"
+  },
+  "keywords": [
+    "crdt",
+    "collaborative",
+    "real-time",
+    "text-editing",
+    "wasm",
+    "automerge-alternative"
+  ],
+  "author": "grayfalcon",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/grayfalcon666/loom"
+  },
+  "peerDependencies": {},
+  "devDependencies": {
+    "esbuild": "^0.24.0"
+  }
+}