pikelet-wasm 0.7.0

package/pancake.js

@@ -0,0 +1,254 @@
+'use strict';
+
+const loadEngine = require('./dist/engine.js');
+const loadScalarEngine = require('./dist/engine.scalar.js');
+const createPancakeApi = require('./pancake-core.js');
+const { PancakeError, PANCAKE_ERROR_CODES, pancakeError } = require('./pancake-errors.js');
+const { PancakeRangeArtifact, PancakeSketchArtifact, createSketchScanner, NodeFileRangeSource, buildRangeArtifact, buildRangeArtifactFile, buildSketchArtifact, buildSketchArtifactBytes, buildSketchArtifactFile } = require('./pancake-artifact.js');
+const { createCachedModuleLoader } = require('./pancake-loader.js');
+const _path = require('path');
+const _fs = require('fs');
+let _engineVariantPromise = null;
+
+const DEFAULT_JSON_FILE_BYTES = 64 * 1024 * 1024;
+const DEFAULT_SNAPSHOT_FILE_BYTES = 512 * 1024 * 1024;
+const SUPPORTED_SNAPSHOT_MAGICS = new Set([
+    0x504E434B, // PNCK envelope
+    0x464C4857, // FLHW raw float v0
+    0x464C4831, // FLH1 raw float v1
+    0x49384857, // I8HW raw uint8 v0
+    0x49384831, // I8H1 raw uint8 v1
+]);
+
+function readWasmBinary(fileName) {
+    try {
+        const wasmBinary = _fs.readFileSync(_path.join(__dirname, 'dist', fileName));
+        return wasmBinary.buffer.slice(
+            wasmBinary.byteOffset,
+            wasmBinary.byteOffset + wasmBinary.byteLength
+        );
+    } catch (error) {
+        const message = error && error.message ? error.message : String(error);
+        throw pancakeError(PANCAKE_ERROR_CODES.WASM_LOAD_FAILED, `Failed to load Pancake WASM binary (${fileName}): ${message}`, { fileName }, error);
+    }
+}
+
+function makeLoadError(message, error) {
+    const detail = error && error.message ? error.message : String(error);
+    return pancakeError(PANCAKE_ERROR_CODES.WASM_LOAD_FAILED, `${message}: ${detail}`, undefined, error);
+}
+
+const _moduleLoader = createCachedModuleLoader((variant) =>
+    readWasmBinary(variant === 'simd' ? 'engine.wasm' : 'engine.scalar.wasm')
+);
+
+function selectEngineVariant() {
+    _engineVariantPromise ??= _moduleLoader.supports('simd')
+        .then((supported) => supported ? 'simd' : 'scalar');
+    return _engineVariantPromise;
+}
+
+function parseJsonLines(text, filePath) {
+    const rows = [];
+    const lines = text.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (line.length === 0) continue;
+        try {
+            rows.push(JSON.parse(line));
+        } catch (error) {
+            const message = error && error.message ? error.message : String(error);
+            throw pancakeError(PANCAKE_ERROR_CODES.PARSE_FAILED, `Failed to parse JSONL in ${filePath} at line ${i + 1}: ${message}`, { filePath, line: i + 1 }, error);
+        }
+    }
+    return rows;
+}
+
+function inferJsonFormat(filePath) {
+    if (/\.json$/i.test(filePath)) return 'json';
+    if (/\.(jsonl|ndjson)$/i.test(filePath)) return 'jsonl';
+    throw pancakeError(PANCAKE_ERROR_CODES.INVALID_ARGUMENT, `loadJsonFile() could not infer format from '${filePath}'. Use a .json/.jsonl/.ndjson extension or pass opts.format.`, { filePath });
+}
+
+function remapJsonRows(rows, vectorKey, idKey) {
+    if (!Array.isArray(rows)) {
+        throw pancakeError(PANCAKE_ERROR_CODES.PARSE_FAILED, 'loadJsonFile() expects a JSON array or JSONL sequence of vectors/records');
+    }
+    return rows.map((row, i) => {
+        if (row instanceof Float32Array || Array.isArray(row)) {
+            return row;
+        }
+        if (!row || typeof row !== 'object') {
+            throw pancakeError(PANCAKE_ERROR_CODES.PARSE_FAILED, `loadJsonFile() expected an object or vector at index ${i}`, { index: i });
+        }
+        if (!(vectorKey in row)) {
+            throw pancakeError(PANCAKE_ERROR_CODES.PARSE_FAILED, `loadJsonFile() missing vectorKey '${vectorKey}' at index ${i}`, { index: i, vectorKey });
+        }
+        const mapped = { vector: row[vectorKey] };
+        if (Object.prototype.hasOwnProperty.call(row, idKey)) {
+            mapped.id = row[idKey];
+        }
+        return mapped;
+    });
+}
+
+function validateFilePath(filePath, helperName) {
+    if (typeof filePath !== 'string' || filePath.length === 0) {
+        throw pancakeError(PANCAKE_ERROR_CODES.INVALID_ARGUMENT, `${helperName}() requires a non-empty file path`);
+    }
+}
+
+function validateMaxFileBytes(maxFileBytes, helperName) {
+    if (!Number.isInteger(maxFileBytes) || maxFileBytes <= 0) {
+        throw pancakeError(PANCAKE_ERROR_CODES.INVALID_ARGUMENT, `${helperName}() maxFileBytes must be a positive integer`, { maxFileBytes });
+    }
+}
+
+function statRegularFile(filePath, helperName) {
+    let stat;
+    try {
+        stat = _fs.statSync(filePath);
+    } catch (error) {
+        const message = error && error.message ? error.message : String(error);
+        throw pancakeError(PANCAKE_ERROR_CODES.FILE_IO_FAILED, `${helperName}() could not stat ${filePath}: ${message}`, { filePath }, error);
+    }
+    if (!stat.isFile()) {
+        throw pancakeError(PANCAKE_ERROR_CODES.INVALID_ARGUMENT, `${helperName}() expected a regular file: ${filePath}`, { filePath });
+    }
+    return stat;
+}
+
+function enforceFileSize(stat, maxFileBytes, helperName, filePath) {
+    if (stat.size > maxFileBytes) {
+        throw pancakeError(PANCAKE_ERROR_CODES.INVALID_ARGUMENT, `${helperName}() file exceeds maxFileBytes (${stat.size} > ${maxFileBytes}): ${filePath}`, { filePath, fileBytes: stat.size, maxFileBytes });
+    }
+}
+
+function readUtf8FileWithLimit(filePath, helperName, maxFileBytes) {
+    validateFilePath(filePath, helperName);
+    validateMaxFileBytes(maxFileBytes, helperName);
+    const stat = statRegularFile(filePath, helperName);
+    enforceFileSize(stat, maxFileBytes, helperName, filePath);
+    try {
+        return _fs.readFileSync(filePath, 'utf8');
+    } catch (error) {
+        const message = error && error.message ? error.message : String(error);
+        throw pancakeError(PANCAKE_ERROR_CODES.FILE_IO_FAILED, `${helperName}() could not read ${filePath}: ${message}`, { filePath }, error);
+    }
+}
+
+function readBinaryFileWithLimit(filePath, helperName, maxFileBytes) {
+    validateFilePath(filePath, helperName);
+    validateMaxFileBytes(maxFileBytes, helperName);
+    const stat = statRegularFile(filePath, helperName);
+    enforceFileSize(stat, maxFileBytes, helperName, filePath);
+    try {
+        return _fs.readFileSync(filePath);
+    } catch (error) {
+        const message = error && error.message ? error.message : String(error);
+        throw pancakeError(PANCAKE_ERROR_CODES.FILE_IO_FAILED, `${helperName}() could not read ${filePath}: ${message}`, { filePath }, error);
+    }
+}
+
+function validateSnapshotBytes(snapshot, filePath) {
+    if (!snapshot || snapshot.byteLength < 4) {
+        throw pancakeError(PANCAKE_ERROR_CODES.SNAPSHOT_INVALID, `loadSnapshotFile() snapshot is too small to be valid: ${filePath}`, { filePath });
+    }
+    const view = new DataView(snapshot.buffer, snapshot.byteOffset, snapshot.byteLength);
+    const magic = view.getUint32(0, true);
+    if (!SUPPORTED_SNAPSHOT_MAGICS.has(magic)) {
+        throw pancakeError(PANCAKE_ERROR_CODES.SNAPSHOT_INVALID, `loadSnapshotFile() unsupported snapshot file type: ${filePath}`, { filePath, magic });
+    }
+}
+
+async function loadNodeEngine() {
+    const engineVariant = await selectEngineVariant();
+
+    if (engineVariant === 'scalar') {
+        try {
+            return await _moduleLoader.instantiate(loadScalarEngine, 'scalar');
+        } catch (error) {
+            throw makeLoadError('Pancake failed to load the scalar WASM engine', error);
+        }
+    }
+
+    try {
+        return await _moduleLoader.instantiate(loadEngine, 'simd');
+    } catch (simdError) {
+        try {
+            const engine = await _moduleLoader.instantiate(loadScalarEngine, 'scalar');
+            _engineVariantPromise = Promise.resolve('scalar');
+            return engine;
+        } catch (scalarError) {
+            throw makeLoadError(
+                `Pancake failed to load either the SIMD or scalar WASM engine (SIMD error: ${simdError && simdError.message ? simdError.message : String(simdError)})`,
+                scalarError
+            );
+        }
+    }
+}
+
+const Pancake = createPancakeApi(loadNodeEngine);
+
+Pancake.RangeArtifact = PancakeRangeArtifact;
+Pancake.NodeFileRangeSource = NodeFileRangeSource;
+Pancake.buildRangeArtifact = buildRangeArtifact;
+Pancake.buildRangeArtifactFile = buildRangeArtifactFile;
+
+Pancake.openRangeArtifactFile = async function openRangeArtifactFile(filePath, opts) {
+    validateFilePath(filePath, 'openRangeArtifactFile');
+    return PancakeRangeArtifact.openFile(filePath, opts);
+};
+
+Pancake.SketchArtifact = PancakeSketchArtifact;
+Pancake.createSketchScanner = (artifact, options) => createSketchScanner(loadNodeEngine, artifact, options);
+Pancake.buildSketchArtifact = buildSketchArtifact;
+Pancake.buildSketchArtifactBytes = buildSketchArtifactBytes;
+Pancake.buildSketchArtifactFile = buildSketchArtifactFile;
+
+Pancake.openSketchArtifactFile = async function openSketchArtifactFile(filePath, opts) {
+    validateFilePath(filePath, 'openSketchArtifactFile');
+    return PancakeSketchArtifact.openFile(filePath, opts);
+};
+
+Pancake.loadSnapshotFile = async function loadSnapshotFile(filePath, opts) {
+    const {
+        maxFileBytes = DEFAULT_SNAPSHOT_FILE_BYTES,
+        ...createOpts
+    } = opts || {};
+
+    const snapshot = readBinaryFileWithLimit(filePath, 'loadSnapshotFile', maxFileBytes);
+    validateSnapshotBytes(snapshot, filePath);
+    return Pancake.restore(snapshot, createOpts);
+};
+
+Pancake.loadJsonFile = async function loadJsonFile(filePath, opts = {}) {
+    const {
+        format = inferJsonFormat(filePath),
+        vectorKey = 'vector',
+        idKey = 'id',
+        maxFileBytes = DEFAULT_JSON_FILE_BYTES,
+        ...createOpts
+    } = opts;
+
+    if (format !== 'json' && format !== 'jsonl') {
+        throw pancakeError(PANCAKE_ERROR_CODES.INVALID_ARGUMENT, `loadJsonFile() format must be 'json' or 'jsonl', got '${format}'`, { format });
+    }
+
+    const text = readUtf8FileWithLimit(filePath, 'loadJsonFile', maxFileBytes);
+    let rows;
+    if (format === 'jsonl') {
+        rows = parseJsonLines(text, filePath);
+    } else {
+        try {
+            rows = JSON.parse(text);
+        } catch (error) {
+            const message = error && error.message ? error.message : String(error);
+            throw pancakeError(PANCAKE_ERROR_CODES.PARSE_FAILED, `Failed to parse JSON in ${filePath}: ${message}`, { filePath }, error);
+        }
+    }
+    return Pancake.fromVectors(remapJsonRows(rows, vectorKey, idKey), createOpts);
+};
+
+module.exports = Pancake;
+module.exports.default = Pancake;

package/pancake.node.mjs

@@ -0,0 +1,259 @@
+import { readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import loadEngine from './dist/engine.js';
+import loadScalarEngine from './dist/engine.scalar.js';
+import createPancakeApi from './pancake-core.js';
+import errorContract from './pancake-errors.js';
+import loaderContract from './pancake-loader.js';
+import artifactContract from './pancake-artifact.js';
+const { PancakeError, PANCAKE_ERROR_CODES, pancakeError } = errorContract;
+const { createCachedModuleLoader } = loaderContract;
+const { PancakeRangeArtifact, PancakeSketchArtifact, createSketchScanner, NodeFileRangeSource, buildRangeArtifact, buildRangeArtifactFile, buildSketchArtifact, buildSketchArtifactBytes, buildSketchArtifactFile } = artifactContract;
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+let engineVariantPromise = null;
+
+const DEFAULT_JSON_FILE_BYTES = 64 * 1024 * 1024;
+const DEFAULT_SNAPSHOT_FILE_BYTES = 512 * 1024 * 1024;
+const SUPPORTED_SNAPSHOT_MAGICS = new Set([
+  0x504E434B, // PNCK envelope
+  0x464C4857, // FLHW raw float v0
+  0x464C4831, // FLH1 raw float v1
+  0x49384857, // I8HW raw uint8 v0
+  0x49384831, // I8H1 raw uint8 v1
+]);
+
+function readWasmBinary(fileName) {
+  try {
+    const wasmBinary = readFileSync(path.join(__dirname, 'dist', fileName));
+    return wasmBinary.buffer.slice(
+      wasmBinary.byteOffset,
+      wasmBinary.byteOffset + wasmBinary.byteLength
+    );
+  } catch (error) {
+    const message = error && error.message ? error.message : String(error);
+    throw pancakeError(PANCAKE_ERROR_CODES.WASM_LOAD_FAILED, `Failed to load Pancake WASM binary (${fileName}): ${message}`, { fileName }, error);
+  }
+}
+
+function makeLoadError(message, error) {
+  const detail = error && error.message ? error.message : String(error);
+  return pancakeError(PANCAKE_ERROR_CODES.WASM_LOAD_FAILED, `${message}: ${detail}`, undefined, error);
+}
+
+const moduleLoader = createCachedModuleLoader((variant) =>
+  readWasmBinary(variant === 'simd' ? 'engine.wasm' : 'engine.scalar.wasm')
+);
+
+function selectEngineVariant() {
+  engineVariantPromise ??= moduleLoader.supports('simd')
+    .then((supported) => supported ? 'simd' : 'scalar');
+  return engineVariantPromise;
+}
+
+function parseJsonLines(text, filePath) {
+  const rows = [];
+  const lines = text.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (line.length === 0) continue;
+    try {
+      rows.push(JSON.parse(line));
+    } catch (error) {
+      const message = error && error.message ? error.message : String(error);
+      throw pancakeError(PANCAKE_ERROR_CODES.PARSE_FAILED, `Failed to parse JSONL in ${filePath} at line ${i + 1}: ${message}`, { filePath, line: i + 1 }, error);
+    }
+  }
+  return rows;
+}
+
+function inferJsonFormat(filePath) {
+  if (/\.json$/i.test(filePath)) return 'json';
+  if (/\.(jsonl|ndjson)$/i.test(filePath)) return 'jsonl';
+  throw pancakeError(PANCAKE_ERROR_CODES.INVALID_ARGUMENT, `loadJsonFile() could not infer format from '${filePath}'. Use a .json/.jsonl/.ndjson extension or pass opts.format.`, { filePath });
+}
+
+function remapJsonRows(rows, vectorKey, idKey) {
+  if (!Array.isArray(rows)) {
+    throw pancakeError(PANCAKE_ERROR_CODES.PARSE_FAILED, 'loadJsonFile() expects a JSON array or JSONL sequence of vectors/records');
+  }
+  return rows.map((row, i) => {
+    if (row instanceof Float32Array || Array.isArray(row)) {
+      return row;
+    }
+    if (!row || typeof row !== 'object') {
+      throw pancakeError(PANCAKE_ERROR_CODES.PARSE_FAILED, `loadJsonFile() expected an object or vector at index ${i}`, { index: i });
+    }
+    if (!(vectorKey in row)) {
+      throw pancakeError(PANCAKE_ERROR_CODES.PARSE_FAILED, `loadJsonFile() missing vectorKey '${vectorKey}' at index ${i}`, { index: i, vectorKey });
+    }
+    const mapped = { vector: row[vectorKey] };
+    if (Object.prototype.hasOwnProperty.call(row, idKey)) {
+      mapped.id = row[idKey];
+    }
+    return mapped;
+  });
+}
+
+function validateFilePath(filePath, helperName) {
+  if (typeof filePath !== 'string' || filePath.length === 0) {
+    throw pancakeError(PANCAKE_ERROR_CODES.INVALID_ARGUMENT, `${helperName}() requires a non-empty file path`);
+  }
+}
+
+function validateMaxFileBytes(maxFileBytes, helperName) {
+  if (!Number.isInteger(maxFileBytes) || maxFileBytes <= 0) {
+    throw pancakeError(PANCAKE_ERROR_CODES.INVALID_ARGUMENT, `${helperName}() maxFileBytes must be a positive integer`, { maxFileBytes });
+  }
+}
+
+function statRegularFile(filePath, helperName) {
+  let stat;
+  try {
+    stat = statSync(filePath);
+  } catch (error) {
+    const message = error && error.message ? error.message : String(error);
+    throw pancakeError(PANCAKE_ERROR_CODES.FILE_IO_FAILED, `${helperName}() could not stat ${filePath}: ${message}`, { filePath }, error);
+  }
+  if (!stat.isFile()) {
+    throw pancakeError(PANCAKE_ERROR_CODES.INVALID_ARGUMENT, `${helperName}() expected a regular file: ${filePath}`, { filePath });
+  }
+  return stat;
+}
+
+function enforceFileSize(stat, maxFileBytes, helperName, filePath) {
+  if (stat.size > maxFileBytes) {
+    throw pancakeError(PANCAKE_ERROR_CODES.INVALID_ARGUMENT, `${helperName}() file exceeds maxFileBytes (${stat.size} > ${maxFileBytes}): ${filePath}`, { filePath, fileBytes: stat.size, maxFileBytes });
+  }
+}
+
+function readUtf8FileWithLimit(filePath, helperName, maxFileBytes) {
+  validateFilePath(filePath, helperName);
+  validateMaxFileBytes(maxFileBytes, helperName);
+  const stat = statRegularFile(filePath, helperName);
+  enforceFileSize(stat, maxFileBytes, helperName, filePath);
+  try {
+    return readFileSync(filePath, 'utf8');
+  } catch (error) {
+    const message = error && error.message ? error.message : String(error);
+    throw pancakeError(PANCAKE_ERROR_CODES.FILE_IO_FAILED, `${helperName}() could not read ${filePath}: ${message}`, { filePath }, error);
+  }
+}
+
+function readBinaryFileWithLimit(filePath, helperName, maxFileBytes) {
+  validateFilePath(filePath, helperName);
+  validateMaxFileBytes(maxFileBytes, helperName);
+  const stat = statRegularFile(filePath, helperName);
+  enforceFileSize(stat, maxFileBytes, helperName, filePath);
+  try {
+    return readFileSync(filePath);
+  } catch (error) {
+    const message = error && error.message ? error.message : String(error);
+    throw pancakeError(PANCAKE_ERROR_CODES.FILE_IO_FAILED, `${helperName}() could not read ${filePath}: ${message}`, { filePath }, error);
+  }
+}
+
+function validateSnapshotBytes(snapshot, filePath) {
+  if (!snapshot || snapshot.byteLength < 4) {
+    throw pancakeError(PANCAKE_ERROR_CODES.SNAPSHOT_INVALID, `loadSnapshotFile() snapshot is too small to be valid: ${filePath}`, { filePath });
+  }
+  const view = new DataView(snapshot.buffer, snapshot.byteOffset, snapshot.byteLength);
+  const magic = view.getUint32(0, true);
+  if (!SUPPORTED_SNAPSHOT_MAGICS.has(magic)) {
+    throw pancakeError(PANCAKE_ERROR_CODES.SNAPSHOT_INVALID, `loadSnapshotFile() unsupported snapshot file type: ${filePath}`, { filePath, magic });
+  }
+}
+
+async function loadNodeEngine() {
+  const engineVariant = await selectEngineVariant();
+
+  if (engineVariant === 'scalar') {
+    try {
+      return await moduleLoader.instantiate(loadScalarEngine, 'scalar');
+    } catch (error) {
+      throw makeLoadError('Pancake failed to load the scalar WASM engine', error);
+    }
+  }
+
+  try {
+    return await moduleLoader.instantiate(loadEngine, 'simd');
+  } catch (simdError) {
+    try {
+      const engine = await moduleLoader.instantiate(loadScalarEngine, 'scalar');
+      engineVariantPromise = Promise.resolve('scalar');
+      return engine;
+    } catch (scalarError) {
+      throw makeLoadError(
+        `Pancake failed to load either the SIMD or scalar WASM engine (SIMD error: ${simdError && simdError.message ? simdError.message : String(simdError)})`,
+        scalarError
+      );
+    }
+  }
+}
+
+const Pancake = createPancakeApi(loadNodeEngine);
+export { PancakeError, PANCAKE_ERROR_CODES };
+
+Pancake.RangeArtifact = PancakeRangeArtifact;
+Pancake.NodeFileRangeSource = NodeFileRangeSource;
+Pancake.buildRangeArtifact = buildRangeArtifact;
+Pancake.buildRangeArtifactFile = buildRangeArtifactFile;
+
+Pancake.openRangeArtifactFile = async function openRangeArtifactFile(filePath, opts) {
+  validateFilePath(filePath, 'openRangeArtifactFile');
+  return PancakeRangeArtifact.openFile(filePath, opts);
+};
+
+Pancake.SketchArtifact = PancakeSketchArtifact;
+Pancake.createSketchScanner = (artifact, options) => createSketchScanner(loadNodeEngine, artifact, options);
+Pancake.buildSketchArtifact = buildSketchArtifact;
+Pancake.buildSketchArtifactBytes = buildSketchArtifactBytes;
+Pancake.buildSketchArtifactFile = buildSketchArtifactFile;
+
+Pancake.openSketchArtifactFile = async function openSketchArtifactFile(filePath, opts) {
+  validateFilePath(filePath, 'openSketchArtifactFile');
+  return PancakeSketchArtifact.openFile(filePath, opts);
+};
+
+Pancake.loadSnapshotFile = async function loadSnapshotFile(filePath, opts) {
+  const {
+    maxFileBytes = DEFAULT_SNAPSHOT_FILE_BYTES,
+    ...createOpts
+  } = opts || {};
+
+  const snapshot = readBinaryFileWithLimit(filePath, 'loadSnapshotFile', maxFileBytes);
+  validateSnapshotBytes(snapshot, filePath);
+  return Pancake.restore(snapshot, createOpts);
+};
+
+Pancake.loadJsonFile = async function loadJsonFile(filePath, opts = {}) {
+  const {
+    format = inferJsonFormat(filePath),
+    vectorKey = 'vector',
+    idKey = 'id',
+    maxFileBytes = DEFAULT_JSON_FILE_BYTES,
+    ...createOpts
+  } = opts;
+
+  if (format !== 'json' && format !== 'jsonl') {
+    throw pancakeError(PANCAKE_ERROR_CODES.INVALID_ARGUMENT, `loadJsonFile() format must be 'json' or 'jsonl', got '${format}'`, { format });
+  }
+
+  const text = readUtf8FileWithLimit(filePath, 'loadJsonFile', maxFileBytes);
+  let rows;
+  if (format === 'jsonl') {
+    rows = parseJsonLines(text, filePath);
+  } else {
+    try {
+      rows = JSON.parse(text);
+    } catch (error) {
+      const message = error && error.message ? error.message : String(error);
+      throw pancakeError(PANCAKE_ERROR_CODES.PARSE_FAILED, `Failed to parse JSON in ${filePath}: ${message}`, { filePath }, error);
+    }
+  }
+  return Pancake.fromVectors(remapJsonRows(rows, vectorKey, idKey), createOpts);
+};
+
+export default Pancake;

package/pancake.web.d.ts

@@ -0,0 +1,50 @@
+// Types for the browser / Cloudflare Workers entrypoints (`pikelet-wasm/web`).
+// These runtimes expose the portable API, including range-readable Search
+// Artifacts. Only PancakeError and PANCAKE_ERROR_CODES exist as named runtime
+// exports; every other re-export below is type-only. Node-only helpers
+// (NodeFileRangeSource, the build*/open*File functions, loadJsonFile /
+// loadSnapshotFile) are absent from this surface so using them is a compile
+// error rather than a runtime throw.
+export { PancakeError, PANCAKE_ERROR_CODES } from './pancake.js';
+export type {
+  Metric,
+  PancakeErrorCode,
+  VectorInput,
+  VectorRecord,
+  CreateOptions,
+  SearchOptions,
+  FromVectorsResult,
+  RestoreOptions,
+  SnapshotFormat,
+  SnapshotInspection,
+  SearchResult,
+  MemoryUsage,
+  ResolvedConfig,
+  PancakeIndex,
+  RangeReadSource,
+  RangeArtifactSearchOptions,
+  RangeArtifactNode,
+  RangeArtifactStats,
+  RangeArtifactRound,
+  RangeArtifactSearchResult,
+  RangeArtifactOpenOptions,
+  PancakeRangeArtifact,
+  PancakeRangeArtifactConstructor,
+  SketchTier,
+  SketchStageEvent,
+  SketchArtifactOpenOptions,
+  SketchScanner,
+  SketchScannerOptions,
+  SketchArtifactSearchOptions,
+  SketchArtifactSearchResult,
+  SketchArtifactStats,
+  PancakeSketchArtifact,
+  PancakeSketchArtifactConstructor,
+  PancakeApi,
+} from './pancake.js';
+
+import type { PancakeApi } from './pancake.js';
+
+declare const Pancake: PancakeApi;
+
+export default Pancake;

package/pancake.web.mjs

@@ -0,0 +1,88 @@
+import loadEngine from './dist/engine.js';
+import loadScalarEngine from './dist/engine.scalar.js';
+import simdWasmAsset from './dist/engine.wasm?url';
+import scalarWasmAsset from './dist/engine.scalar.wasm?url';
+import createPancakeApi from './pancake-core.js';
+import errorContract from './pancake-errors.js';
+import loaderContract from './pancake-loader.js';
+import artifactContract from './pancake-artifact.js';
+const { PancakeError, PANCAKE_ERROR_CODES, pancakeError } = errorContract;
+const { createCachedModuleLoader } = loaderContract;
+const { PancakeRangeArtifact, PancakeSketchArtifact, createSketchScanner } = artifactContract;
+let engineVariantPromise = null;
+
+function makeLoadError(message, error) {
+  const detail = error && error.message ? error.message : String(error);
+  return pancakeError(PANCAKE_ERROR_CODES.WASM_LOAD_FAILED, `${message}: ${detail}`, undefined, error);
+}
+
+function isUrlLikeWasmAsset(asset) {
+  return typeof asset === 'string' || asset instanceof URL;
+}
+
+async function loadWasmAsset(asset) {
+  if (!isUrlLikeWasmAsset(asset)) return asset;
+  const href = asset instanceof URL ? asset.href : asset;
+  const response = await fetch(href, { credentials: 'same-origin' });
+  if (!response.ok) {
+    throw pancakeError(PANCAKE_ERROR_CODES.WASM_LOAD_FAILED,
+      `${response.status} ${response.statusText}`.trim(), { status: response.status });
+  }
+  return response.arrayBuffer();
+}
+
+const moduleLoader = createCachedModuleLoader((variant) =>
+  loadWasmAsset(variant === 'simd' ? simdWasmAsset : scalarWasmAsset)
+);
+
+function selectEngineVariant() {
+  engineVariantPromise ??= moduleLoader.supports('simd')
+    .then((supported) => supported ? 'simd' : 'scalar')
+    .catch((error) => { throw makeLoadError('Failed to probe Pancake SIMD WASM support', error); });
+  return engineVariantPromise;
+}
+
+async function loadWebEngine() {
+  const engineVariant = await selectEngineVariant();
+
+  if (engineVariant === 'scalar') {
+    try {
+      return await moduleLoader.instantiate(loadScalarEngine, 'scalar');
+    } catch (error) {
+      throw makeLoadError('Pancake failed to load the scalar WASM engine', error);
+    }
+  }
+
+  try {
+    return await moduleLoader.instantiate(loadEngine, 'simd');
+  } catch (simdError) {
+    try {
+      const engine = await moduleLoader.instantiate(loadScalarEngine, 'scalar');
+      engineVariantPromise = Promise.resolve('scalar');
+      return engine;
+    } catch (scalarError) {
+      throw makeLoadError(
+        `Pancake failed to load either the SIMD or scalar WASM engine (SIMD error: ${simdError && simdError.message ? simdError.message : String(simdError)})`,
+        scalarError
+      );
+    }
+  }
+}
+
+const Pancake = createPancakeApi(loadWebEngine);
+export { PancakeError, PANCAKE_ERROR_CODES };
+
+Pancake.RangeArtifact = PancakeRangeArtifact;
+Pancake.SketchArtifact = PancakeSketchArtifact;
+Pancake.createSketchScanner = (artifact, options) => createSketchScanner(loadWebEngine, artifact, options);
+
+function unsupportedNodeFileHelper(name) {
+  return async function unsupported() {
+    throw pancakeError(PANCAKE_ERROR_CODES.INVALID_ARGUMENT, `${name}() is only available in the Node.js entrypoints`);
+  };
+}
+
+Pancake.loadSnapshotFile = unsupportedNodeFileHelper('loadSnapshotFile');
+Pancake.loadJsonFile = unsupportedNodeFileHelper('loadJsonFile');
+
+export default Pancake;