@rsvelte/vite-plugin-svelte-native 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yuichiro Yamashita
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,23 @@
+# @rsvelte/vite-plugin-svelte
+
+Workspace package and changesets version anchor for the Vite plugin that delegates to the rsvelte compiler.
+
+## Status
+
+`private: true` until distribution is decided. The Rust side already exposes the napi bindings the plugin will use (`compile`, `preprocess`, `hmrDiff`, `resolveId` in `src/napi.rs`; helpers in `src/vps/`).
+
+The plan in `docs/ecosystem-implementation-plan.md` (Wave 3) splits this into two npm packages:
+
+- `@rsvelte/vite-plugin-svelte` (this directory) — the JS-side Vite plugin façade. Maintains the same public API as `@sveltejs/vite-plugin-svelte`, loads the native module, and translates Vite hooks into NAPI calls.
+- `@rsvelte/vite-plugin-svelte-native` — the napi-rs prebuilt-binary package set (one per platform triple), produced by a matrix build.
+
+To go live:
+
+1. Add the napi-rs platform matrix build to CI (target the rsvelte crate with `--features napi`).
+2. Create the `@rsvelte/vite-plugin-svelte-native` workspace package and its per-triple siblings.
+3. Add the JS entrypoint here that imports from `@rsvelte/vite-plugin-svelte-native`.
+4. Flip `private` to `false` on both packages.
+
+## Release flow
+
+Versioning is handled by the same changesets pipeline as `@rsvelte/compiler`. See `.github/workflows/release.yml`. While this package is `private`, `changeset version` still updates its `version` and `CHANGELOG.md`, but `changeset publish` skips it.

package/envelope.js

@@ -0,0 +1,335 @@
+// Lazy decoder for the Rust↔JS raw-transfer envelope produced by
+// `binding.compileEnvelope`. The byte format is owned by
+// `src/napi_raw.rs`; keep both ends in sync.
+//
+// The returned object is shaped like the legacy `compile()` result
+// (`{ js: { code, map }, css: {…}|null, warnings: […], metadata, ast }`)
+// but its leaf strings, sourcemap JSON, and warnings array are
+// realised on first read. That keeps the hot path (Vite reads
+// `result.js.code` and `result.js.map`) down to two `Buffer.toString`
+// calls and one `JSON.parse`, with no upfront V8 object tree
+// construction.
+
+'use strict';
+
+const MAGIC = 0x31565352; // "RSV1" little-endian
+const VERSION = 1;
+const HEADER_LEN = 60;
+
+const FLAG_HAS_CSS = 1 << 0;
+const FLAG_RUNES = 1 << 1;
+const FLAG_CSS_HAS_GLOBAL = 1 << 2;
+
+const WARN_HAS_FILENAME = 1 << 0;
+const WARN_HAS_START = 1 << 1;
+const WARN_HAS_END = 1 << 2;
+const WARN_HAS_FRAME = 1 << 3;
+
+/**
+ * Decode an envelope produced by `compileEnvelope` / `compileModuleEnvelope`.
+ *
+ * @param {Buffer|Uint8Array} buf
+ * @returns {object} CompileResult-shaped object with lazy fields
+ */
+function decodeEnvelope(buf) {
+	if (!buf || buf.byteLength < HEADER_LEN) {
+		throw new Error(
+			`[rsvelte] envelope too small (${buf ? buf.byteLength : 0} bytes, ` +
+				`expected at least ${HEADER_LEN})`,
+		);
+	}
+
+	const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+	const magic = view.getUint32(0, true);
+	if (magic !== MAGIC) {
+		throw new Error(
+			`[rsvelte] envelope magic mismatch (got 0x${magic.toString(16)}, ` +
+				`expected 0x${MAGIC.toString(16)})`,
+		);
+	}
+	const version = view.getUint32(4, true);
+	if (version !== VERSION) {
+		throw new Error(
+			`[rsvelte] unsupported envelope version ${version} (this build expects ${VERSION})`,
+		);
+	}
+	const totalLen = view.getUint32(8, true);
+	if (totalLen !== buf.byteLength) {
+		throw new Error(
+			`[rsvelte] envelope size mismatch (header says ${totalLen}, buffer is ${buf.byteLength})`,
+		);
+	}
+
+	const flags = view.getUint32(12, true);
+	const jsCodeOff = view.getUint32(16, true);
+	const jsCodeLen = view.getUint32(20, true);
+	const jsMapOff = view.getUint32(24, true);
+	const jsMapLen = view.getUint32(28, true);
+	const cssCodeOff = view.getUint32(32, true);
+	const cssCodeLen = view.getUint32(36, true);
+	const cssMapOff = view.getUint32(40, true);
+	const cssMapLen = view.getUint32(44, true);
+	const warningsOff = view.getUint32(48, true);
+	const warningsCount = view.getUint32(52, true);
+
+	const hasCss = (flags & FLAG_HAS_CSS) !== 0;
+	const runes = (flags & FLAG_RUNES) !== 0;
+
+	// `buf.toString('utf8', start, end)` is the V8 fast path for
+	// Buffer→string and is consistently faster than wrapping in a
+	// TextDecoder; fall back to TextDecoder for plain Uint8Array.
+	const slice = bufferIsNodeBuffer(buf)
+		? (off, len) => buf.toString('utf8', off, off + len)
+		: utf8SliceFromUint8Array.bind(null, buf);
+
+	// js — eagerly construct the wrapper object, but defer string/JSON
+	// realisation. Vite always touches `js.code`; the map is only
+	// touched when emitting sourcemaps.
+	const js = makeCodeMapObject(buf, slice, jsCodeOff, jsCodeLen, jsMapOff, jsMapLen);
+
+	let css = null;
+	if (hasCss) {
+		css = makeCodeMapObject(buf, slice, cssCodeOff, cssCodeLen, cssMapOff, cssMapLen);
+		css.hasGlobal = (flags & FLAG_CSS_HAS_GLOBAL) !== 0;
+	}
+
+	const result = {
+		js,
+		css,
+		metadata: { runes },
+		ast: null,
+	};
+
+	// Warnings: realised lazily — most compilations produce zero, so
+	// the common path never enters this branch. Once decoded, the
+	// result is cached.
+	let warningsCache = null;
+	Object.defineProperty(result, 'warnings', {
+		enumerable: true,
+		configurable: true,
+		get() {
+			if (warningsCache === null) {
+				warningsCache = decodeWarnings(buf, view, warningsOff, warningsCount, slice);
+			}
+			return warningsCache;
+		},
+	});
+
+	return result;
+}
+
+function makeCodeMapObject(buf, slice, codeOff, codeLen, mapOff, mapLen) {
+	const obj = {};
+	let codeCache = null;
+	// `code` and `map` need setters as well as getters — upstream
+	// `svelte/compiler` returns them as plain writable strings, and
+	// vite-plugin-svelte mutates `compiled.js.code` to wire the CSS
+	// import (see compile.js:131, `compiled.js.code += ...`). Without
+	// a setter the assignment throws `Cannot set property code of
+	// #<Object> which has only a getter` under the strict-mode rolldown
+	// runtime and the docs build fails.
+	Object.defineProperty(obj, 'code', {
+		enumerable: true,
+		configurable: true,
+		get() {
+			if (codeCache === null) codeCache = slice(codeOff, codeLen);
+			return codeCache;
+		},
+		set(value) {
+			codeCache = value;
+		},
+	});
+	const hasMap = mapOff !== 0;
+	let mapCache = hasMap ? undefined : null;
+	Object.defineProperty(obj, 'map', {
+		enumerable: true,
+		configurable: true,
+		get() {
+			if (mapCache === undefined) {
+				// Parse the sourcemap JSON on first read. Returning the
+				// parsed object matches the legacy compile() shape —
+				// callers that just want the raw JSON to write to disk
+				// should prefer `mapBytes` / `mapText` (no JSON.parse).
+				mapCache = JSON.parse(slice(mapOff, mapLen));
+			}
+			return mapCache;
+		},
+		set(value) {
+			mapCache = value;
+		},
+	});
+	// `mapBytes` returns a zero-copy view into the envelope (Node Buffer
+	// or Uint8Array depending on what the caller passed in). Use this
+	// when emitting the sourcemap straight to disk / a network stream
+	// — no JSON.parse, no UTF-16 string materialisation.
+	Object.defineProperty(obj, 'mapBytes', {
+		enumerable: false,
+		configurable: true,
+		get() {
+			if (!hasMap) return null;
+			return buf.subarray
+				? buf.subarray(mapOff, mapOff + mapLen)
+				: new Uint8Array(buf.buffer, buf.byteOffset + mapOff, mapLen);
+		},
+	});
+	// `mapText` returns the raw sourcemap JSON as a string without the
+	// `JSON.parse` round-trip. Useful when downstream tooling immediately
+	// `JSON.stringify`s the map again (Vite's asset emit path).
+	Object.defineProperty(obj, 'mapText', {
+		enumerable: false,
+		configurable: true,
+		get() {
+			if (!hasMap) return null;
+			return slice(mapOff, mapLen);
+		},
+	});
+	return obj;
+}
+
+function decodeWarnings(buf, view, off, count, slice) {
+	const out = new Array(count);
+	let p = off;
+	for (let i = 0; i < count; i++) {
+		const codeLen = view.getUint32(p, true);
+		p += 4;
+		const code = slice(p, codeLen);
+		p += codeLen;
+		const msgLen = view.getUint32(p, true);
+		p += 4;
+		const message = slice(p, msgLen);
+		p += msgLen;
+		const flags = view.getUint8(p);
+		p += 1;
+
+		const w = { code, message };
+		if (flags & WARN_HAS_FILENAME) {
+			const len = view.getUint32(p, true);
+			p += 4;
+			w.filename = slice(p, len);
+			p += len;
+		}
+		if (flags & WARN_HAS_START) {
+			w.start = {
+				line: view.getUint32(p, true),
+				column: view.getUint32(p + 4, true),
+				character: view.getUint32(p + 8, true),
+			};
+			p += 12;
+		}
+		if (flags & WARN_HAS_END) {
+			w.end = {
+				line: view.getUint32(p, true),
+				column: view.getUint32(p + 4, true),
+				character: view.getUint32(p + 8, true),
+			};
+			p += 12;
+		}
+		if (w.start && w.end) {
+			w.position = [w.start.character, w.end.character];
+		}
+		if (flags & WARN_HAS_FRAME) {
+			const len = view.getUint32(p, true);
+			p += 4;
+			w.frame = slice(p, len);
+			p += len;
+		}
+		out[i] = w;
+	}
+	return out;
+}
+
+function bufferIsNodeBuffer(buf) {
+	return typeof Buffer !== 'undefined' && Buffer.isBuffer(buf);
+}
+
+let cachedDecoder = null;
+function utf8SliceFromUint8Array(u8, off, len) {
+	if (cachedDecoder === null) cachedDecoder = new TextDecoder('utf-8');
+	return cachedDecoder.decode(u8.subarray(off, off + len));
+}
+
+// =============================================================================
+// Batch envelope
+// =============================================================================
+
+const BATCH_MAGIC = 0x42565352; // "RSVB" little-endian
+const BATCH_VERSION = 1;
+const BATCH_HEADER_LEN = 16;
+const BATCH_ENTRY_LEN = 12;
+const BATCH_STATUS_OK = 0;
+const BATCH_STATUS_ERR = 1;
+
+/**
+ * Decode a batch envelope produced by `compileBatch`. Returns an
+ * array the same length as the input, where each slot is either a
+ * `CompileResult` (decoded lazily on first read, like {@link decodeEnvelope})
+ * or an `Error` carrying the per-entry failure message.
+ *
+ * @param {Buffer|Uint8Array} buf
+ * @returns {Array<object|Error>}
+ */
+function decodeBatch(buf) {
+	if (!buf || buf.byteLength < BATCH_HEADER_LEN) {
+		throw new Error(
+			`[rsvelte] batch envelope too small (${buf ? buf.byteLength : 0} bytes, ` +
+				`expected at least ${BATCH_HEADER_LEN})`,
+		);
+	}
+
+	const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+	const magic = view.getUint32(0, true);
+	if (magic !== BATCH_MAGIC) {
+		throw new Error(
+			`[rsvelte] batch magic mismatch (got 0x${magic.toString(16)}, ` +
+				`expected 0x${BATCH_MAGIC.toString(16)})`,
+		);
+	}
+	const version = view.getUint32(4, true);
+	if (version !== BATCH_VERSION) {
+		throw new Error(
+			`[rsvelte] unsupported batch envelope version ${version} (this build expects ${BATCH_VERSION})`,
+		);
+	}
+	const totalLen = view.getUint32(8, true);
+	if (totalLen !== buf.byteLength) {
+		throw new Error(
+			`[rsvelte] batch envelope size mismatch (header says ${totalLen}, buffer is ${buf.byteLength})`,
+		);
+	}
+	const count = view.getUint32(12, true);
+
+	const out = new Array(count);
+	for (let i = 0; i < count; i++) {
+		const entryOff = BATCH_HEADER_LEN + i * BATCH_ENTRY_LEN;
+		const status = view.getUint32(entryOff, true);
+		const payloadOff = view.getUint32(entryOff + 4, true);
+		const payloadLen = view.getUint32(entryOff + 8, true);
+		// Subarray gives a zero-copy view into the same underlying
+		// ArrayBuffer; `decodeEnvelope` walks it without further allocation.
+		const slice = buf.subarray
+			? buf.subarray(payloadOff, payloadOff + payloadLen)
+			: new Uint8Array(buf.buffer, buf.byteOffset + payloadOff, payloadLen);
+		if (status === BATCH_STATUS_OK) {
+			out[i] = decodeEnvelope(slice);
+		} else if (status === BATCH_STATUS_ERR) {
+			const msg = bufferIsNodeBuffer(slice)
+				? slice.toString('utf8')
+				: utf8SliceFromUint8Array(slice, 0, slice.byteLength);
+			out[i] = new Error(msg);
+		} else {
+			out[i] = new Error(`[rsvelte] unknown batch entry status ${status} at index ${i}`);
+		}
+	}
+	return out;
+}
+
+module.exports = {
+	decodeEnvelope,
+	decodeBatch,
+	HEADER_LEN,
+	MAGIC,
+	VERSION,
+	BATCH_HEADER_LEN,
+	BATCH_MAGIC,
+	BATCH_VERSION,
+};

package/index.cjs

@@ -0,0 +1,134 @@
+// Resolve the rsvelte NAPI binding for the current platform and re-export it.
+// Mirrors the loader pattern napi-rs generates: resolve a platform-specific
+// dependency that ships a single `rsvelte.node` artifact.
+
+const { decodeEnvelope, decodeBatch } = require('./envelope.js');
+
+const { platform, arch } = process;
+
+function resolveTriple() {
+	if (platform === 'darwin') {
+		if (arch === 'arm64') return 'darwin-arm64';
+		if (arch === 'x64') return 'darwin-x64';
+	} else if (platform === 'linux') {
+		// Node 18+ exposes the runtime glibc version in the report header. An
+		// empty value means we're on musl (Alpine, distroless, etc.).
+		let isMusl = false;
+		try {
+			const header = process.report.getReport().header;
+			isMusl = !header.glibcVersionRuntime;
+		} catch {
+			isMusl = false;
+		}
+		const libc = isMusl ? 'musl' : 'gnu';
+		if (arch === 'x64') return `linux-x64-${libc}`;
+		if (arch === 'arm64') return `linux-arm64-${libc}`;
+	} else if (platform === 'win32') {
+		if (arch === 'x64') return 'win32-x64-msvc';
+	}
+	return null;
+}
+
+const triple = resolveTriple();
+if (!triple) {
+	throw new Error(
+		`[@rsvelte/vite-plugin-svelte-native] Unsupported platform: ${platform}-${arch}. ` +
+			`Open an issue at https://github.com/baseballyama/rsvelte/issues if you'd like it supported.`,
+	);
+}
+
+const pkgName = `@rsvelte/vite-plugin-svelte-native-${triple}`;
+let binding;
+try {
+	binding = require(`${pkgName}/rsvelte.node`);
+} catch (err) {
+	throw new Error(
+		`[@rsvelte/vite-plugin-svelte-native] Couldn't load the native binding "${pkgName}".\n` +
+			`This usually means npm/pnpm skipped the optional dependency for your platform.\n` +
+			`Try reinstalling: npm install --include=optional ${pkgName}\n\n` +
+			`Original error: ${err.message}`,
+	);
+}
+
+// `compile` / `compileModule` are wrapped to route through the
+// raw-transfer envelope (`compileEnvelope`): the Rust side hands us
+// one `Buffer`, the JS side lazy-decodes only the fields the caller
+// reads. This avoids the V8 string copy + `serde_json` round-trip
+// that the legacy JSON path pays for every call.
+//
+// Callers that need the raw envelope (e.g. to ship it across a worker
+// boundary without re-encoding) can still grab `binding.compileEnvelope`
+// directly. The legacy JSON path is preserved as `compileLegacy` for
+// parity testing and as an escape hatch.
+function compile(source, options) {
+	return decodeEnvelope(binding.compileEnvelope(source, options));
+}
+
+function compileModule(source, options) {
+	return decodeEnvelope(binding.compileModuleEnvelope(source, options));
+}
+
+// `compileBatch([{source, options}, …])` compiles N files in
+// parallel (rayon on the Rust side) and crosses the NAPI boundary
+// exactly once. The returned array is the same length as the input;
+// each slot is either a `CompileResult` or an `Error` (parse
+// failures don't abort the whole batch).
+function compileBatch(inputs) {
+	return decodeBatch(binding.compileBatch(inputs));
+}
+
+// `compileAsync` / `compileBatchAsync` release the JS event loop
+// while the Rust side compiles on a libuv worker thread. Useful
+// for plugins that interleave compilation with other async work
+// (Vite middleware, SSR pre-render) — the await yields control
+// instead of blocking V8.
+async function compileAsync(source, options) {
+	return decodeEnvelope(await binding.compileEnvelopeAsync(source, options));
+}
+
+async function compileBatchAsync(inputs) {
+	return decodeBatch(await binding.compileBatchAsync(inputs));
+}
+
+// Re-export every NAPI function as its own named binding so node's
+// `cjs-module-lexer` can pick them up when this file is imported via
+// ESM (e.g. `import { compile, preprocess, VERSION } from …`). A bare
+// `module.exports = binding` would only expose the default export
+// reliably; explicit `module.exports.X = …` lines are what the lexer
+// scans for.
+//
+// The static list mirrors `src/napi.rs`'s `#[napi(js_name = ...)]`
+// attributes — keep it in sync when adding/removing NAPI exports.
+module.exports.compile = compile;
+module.exports.compileModule = compileModule;
+module.exports.compileLegacy = binding.compile;
+module.exports.compileModuleLegacy = binding.compileModule;
+module.exports.compileEnvelope = binding.compileEnvelope;
+module.exports.compileModuleEnvelope = binding.compileModuleEnvelope;
+// Zero-copy variants: same envelope format, but the returned Buffer
+// is a view into bumpalo arena memory (no Vec copy). Use these when
+// you know the buffer will be consumed once and discarded — the
+// arena is freed when the Buffer is GC'd. For long-lived buffers
+// passed across worker boundaries, prefer `compileEnvelope` which
+// hands you an owned Vec.
+module.exports.compileEnvelopeZeroCopy = binding.compileEnvelopeZeroCopy;
+module.exports.compileModuleEnvelopeZeroCopy = binding.compileModuleEnvelopeZeroCopy;
+module.exports.compileBuffers = binding.compileBuffers;
+module.exports.compileModuleBuffers = binding.compileModuleBuffers;
+module.exports.compileBatch = compileBatch;
+module.exports.compileBatchRaw = binding.compileBatch;
+module.exports.compileAsync = compileAsync;
+module.exports.compileBatchAsync = compileBatchAsync;
+module.exports.compileEnvelopeAsync = binding.compileEnvelopeAsync;
+module.exports.compileBatchAsyncRaw = binding.compileBatchAsync;
+module.exports.decodeEnvelope = decodeEnvelope;
+module.exports.decodeBatch = decodeBatch;
+module.exports.preprocess = binding.preprocess;
+module.exports.svelte2tsx = binding.svelte2tsx;
+module.exports.hmrDiff = binding.hmrDiff;
+module.exports.resolveId = binding.resolveId;
+// Upstream Svelte version this binding emits code for — used by
+// downstream consumers (the `@rsvelte/vite-plugin-svelte` fork, etc.)
+// for `gte(VERSION, '5.36.0')`-style feature detection. Synced
+// manually against `submodules/svelte/packages/svelte/package.json`.
+module.exports.VERSION = '5.51.3';

package/index.d.ts

@@ -0,0 +1,377 @@
+// Public surface of the rsvelte NAPI binding. Mirrors the `#[napi]` exports in
+// `src/napi.rs`. The structural types below match the upstream Svelte
+// (`svelte/compiler`) names where they map cleanly, so consumers — including
+// the `@rsvelte/vite-plugin-svelte` fork — can stay drop-in compatible with
+// the official surface.
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+/**
+ * Component compile options. Loosely follows `svelte/compiler#CompileOptions`.
+ */
+export interface CompileOptions {
+	/** Enable dev mode (instrumentation, warnings, etc.). */
+	dev?: boolean;
+	/** Generate client- or server-side code, or skip codegen. */
+	generate?: 'client' | 'server' | false;
+	/** Source filename. Used in source maps and error frames. */
+	filename?: string;
+	/** Project root, used to compute relative source-map paths. */
+	rootDir?: string;
+	/** Component identifier hint. */
+	name?: string;
+	/** Compile as a custom element. */
+	customElement?: boolean;
+	/** Generate `accessors`. */
+	accessors?: boolean;
+	/** HTML namespace. */
+	namespace?: 'html' | 'svg' | 'mathml';
+	/** Hint that bindings are immutable. */
+	immutable?: boolean;
+	/** Output CSS injected into the bundle or as an external asset. */
+	css?: 'injected' | 'external';
+	/** Custom hash function for CSS scoping — currently honored as a string-mapper. */
+	cssHash?: (args: {
+		hash: (input: string) => string;
+		css: string;
+		name: string;
+		filename: string | undefined;
+	}) => string;
+	/** Preserve HTML comments in output. */
+	preserveComments?: boolean;
+	/** Preserve whitespace in the template. */
+	preserveWhitespace?: boolean;
+	/** Force runes mode (`true`), legacy (`false`), or auto-detect (`undefined`). */
+	runes?: boolean;
+	/** Disclose the compiler version in the output banner. */
+	discloseVersion?: boolean;
+	/** Source-map options (forwarded through magic-string). */
+	sourcemap?: object | string;
+	/** Output JS filename for `file` in the JS source map. */
+	outputFilename?: string;
+	/** Output CSS filename for `file` in the CSS source map. */
+	cssOutputFilename?: string;
+	/** Enable HMR-friendly output (used by `@rsvelte/vite-plugin-svelte`). */
+	hmr?: boolean;
+	/** Emit the modern AST shape (default). */
+	modernAst?: boolean;
+	/** Filter compiler warnings. */
+	warningFilter?: (warning: Warning) => boolean;
+}
+
+/**
+ * Module compile options. Subset of {@link CompileOptions} that applies to
+ * `.svelte.js` / `.svelte.ts` modules.
+ */
+export interface ModuleCompileOptions {
+	dev?: boolean;
+	generate?: 'client' | 'server' | false;
+	filename?: string;
+	rootDir?: string;
+	warningFilter?: (warning: Warning) => boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Diagnostics
+// ---------------------------------------------------------------------------
+
+export interface SourcePosition {
+	line: number;
+	column: number;
+	character: number;
+}
+
+/** Compiler warning matching `svelte/compiler#Warning`. */
+export interface Warning {
+	code: string;
+	message: string;
+	filename?: string;
+	start?: SourcePosition;
+	end?: SourcePosition;
+	position?: [number, number];
+	frame?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Compile result
+// ---------------------------------------------------------------------------
+
+export interface CompileResultJs {
+	code: string;
+	/**
+	 * A standard SourceMap v3 JSON object. Accessing this triggers a
+	 * one-time `JSON.parse` of the underlying envelope bytes. For
+	 * callers that immediately re-serialize (writing to disk,
+	 * sending over the wire) prefer {@link mapBytes} / {@link mapText}
+	 * to skip the parse round-trip.
+	 */
+	map: unknown;
+	/**
+	 * Zero-copy `Buffer` / `Uint8Array` view over the raw sourcemap
+	 * JSON bytes in the envelope. `null` if no map was produced. Stable
+	 * for the lifetime of the parent `CompileResult` (becomes invalid
+	 * once a `compileEnvelopeZeroCopy` buffer is GC'd).
+	 */
+	mapBytes: Buffer | Uint8Array | null;
+	/** Raw sourcemap JSON as a string — no `JSON.parse`. `null` if no map. */
+	mapText: string | null;
+}
+
+export interface CompileResultCss {
+	code: string;
+	/** See {@link CompileResultJs.map}. */
+	map: unknown;
+	mapBytes: Buffer | Uint8Array | null;
+	mapText: string | null;
+	hasGlobal: boolean;
+}
+
+export interface CompileResult {
+	js: CompileResultJs;
+	css: CompileResultCss | null;
+	warnings: Warning[];
+	metadata: { runes?: boolean } & Record<string, unknown>;
+	ast: unknown;
+}
+
+/**
+ * Compile a Svelte component. Internally goes through the raw-transfer
+ * envelope (`compileEnvelope` + `decodeEnvelope`) so that heavy strings
+ * (generated code, sourcemap JSON) are read out of the underlying
+ * `Buffer` only when the caller touches `.code` / `.map`. The shape
+ * matches `svelte/compiler#compile`.
+ */
+export function compile(source: string, options?: CompileOptions): CompileResult;
+export function compileModule(
+	source: string,
+	options?: ModuleCompileOptions,
+): CompileResult;
+
+/**
+ * Lower-level raw-transfer entry point. Returns a single `Buffer`
+ * containing the entire compile result in the rsvelte envelope format
+ * (see `src/napi_raw.rs`). Pair with {@link decodeEnvelope} to obtain
+ * the legacy {@link CompileResult} shape; or pass the buffer through
+ * worker `postMessage` (transferable) to avoid a copy.
+ */
+export function compileEnvelope(source: string, options?: CompileOptions): Buffer;
+export function compileModuleEnvelope(
+	source: string,
+	options?: ModuleCompileOptions,
+): Buffer;
+
+/**
+ * Zero-copy variant. Returns a `Buffer` view over `bumpalo` arena
+ * memory rather than an owned `Vec<u8>` — no copy whatsoever at the
+ * Rust↔JS boundary. The arena is freed when V8 garbage-collects the
+ * Buffer, so the data stays valid for as long as JS holds a reference.
+ *
+ * Trade-offs vs {@link compileEnvelope}:
+ *
+ * - **Faster:** skips Rust's `Vec` allocation; pre-sized arena slice.
+ * - **Limited transferability:** if you `postMessage` the buffer with
+ *   `transfer:` between workers, V8 may need to detach the underlying
+ *   storage. The arena finalizer only runs when V8 actually GCs the
+ *   Buffer wrapper, so detach semantics are safe but may surprise
+ *   callers used to `Buffer` semantics.
+ */
+export function compileEnvelopeZeroCopy(
+	source: string,
+	options?: CompileOptions,
+): Buffer;
+export function compileModuleEnvelopeZeroCopy(
+	source: string,
+	options?: ModuleCompileOptions,
+): Buffer;
+
+/** Decode a buffer produced by {@link compileEnvelope}. */
+export function decodeEnvelope(buf: Buffer | Uint8Array): CompileResult;
+
+/**
+ * Single entry in a {@link compileBatch} worklist. `options` is
+ * forwarded to the underlying compile as if you had called
+ * `compile(source, options)`.
+ */
+export interface CompileBatchInput {
+	source: string;
+	options?: CompileOptions;
+}
+
+/**
+ * Compile multiple Svelte components in one NAPI call. The Rust side
+ * dispatches across rayon workers; the JS side gets one `Buffer`
+ * back containing all N results. Per-entry failures surface as
+ * `Error` instances at the corresponding slot — they don't abort
+ * the rest of the batch.
+ *
+ * Use this when you'd otherwise loop `compile()` over many files
+ * (Vite dev server, SSR pre-render). For one-off compiles the
+ * per-call overhead of `compile()` is already small.
+ */
+export function compileBatch(
+	inputs: CompileBatchInput[],
+): Array<CompileResult | Error>;
+
+/**
+ * Lower-level entry point: returns the raw batch envelope as a single
+ * `Buffer`. Pair with {@link decodeBatch} to obtain the same array
+ * {@link compileBatch} would, or pass through worker `postMessage`.
+ */
+export function compileBatchRaw(inputs: CompileBatchInput[]): Buffer;
+
+/** Decode a batch envelope produced by {@link compileBatchRaw}. */
+export function decodeBatch(buf: Buffer | Uint8Array): Array<CompileResult | Error>;
+
+/**
+ * Async variant of {@link compile}. The Rust side runs on a libuv
+ * worker thread; the JS thread stays free to handle other callbacks.
+ * Returned `Promise<CompileResult>` resolves when the envelope has
+ * been encoded and decoded.
+ */
+export function compileAsync(
+	source: string,
+	options?: CompileOptions,
+): Promise<CompileResult>;
+
+/** Async variant of {@link compileBatch}. */
+export function compileBatchAsync(
+	inputs: CompileBatchInput[],
+): Promise<Array<CompileResult | Error>>;
+
+/** Lower-level: returns `Promise<Buffer>` (the raw envelope). */
+export function compileEnvelopeAsync(
+	source: string,
+	options?: CompileOptions,
+): Promise<Buffer>;
+
+/** Lower-level: returns `Promise<Buffer>` (the raw batch envelope). */
+export function compileBatchAsyncRaw(inputs: CompileBatchInput[]): Promise<Buffer>;
+
+/**
+ * Step-1 variant of {@link compile}: returns the same shape but with
+ * `js.code` / `js.map` / `css.code` / `css.map` as raw `Buffer`s. The
+ * envelope path ({@link compile}) supersedes this for most callers; it
+ * stays exported as an escape hatch for callers that want structured
+ * access without the envelope decode.
+ */
+export interface CompileBuffersResult {
+	js: { code: Buffer; map: Buffer | null };
+	css: { code: Buffer; map: Buffer | null; hasGlobal: boolean } | null;
+	warnings: Warning[];
+	runes: boolean;
+}
+export function compileBuffers(
+	source: string,
+	options?: CompileOptions,
+): CompileBuffersResult;
+export function compileModuleBuffers(
+	source: string,
+	options?: ModuleCompileOptions,
+): CompileBuffersResult;
+
+/**
+ * The legacy JSON-on-the-boundary path. Kept exported for parity tests
+ * and as an escape hatch — production callers should use {@link compile}.
+ */
+export function compileLegacy(source: string, options?: CompileOptions): CompileResult;
+export function compileModuleLegacy(
+	source: string,
+	options?: ModuleCompileOptions,
+): CompileResult;
+
+// ---------------------------------------------------------------------------
+// svelte2tsx
+// ---------------------------------------------------------------------------
+
+export interface Svelte2TsxResult {
+	code: string;
+	map: unknown;
+	exportedNames: { props: string[]; all: string[] };
+	events: Record<string, unknown>;
+}
+export function svelte2tsx(
+	source: string,
+	options?: Record<string, unknown>,
+): Svelte2TsxResult;
+
+// ---------------------------------------------------------------------------
+// HMR / resolver
+// ---------------------------------------------------------------------------
+
+export interface HmrDiff {
+	change: 'hot-update' | 'full-reload' | 'unchanged';
+	instanceChanged: boolean;
+	moduleChanged: boolean;
+}
+export function hmrDiff(prev: string, curr: string): HmrDiff;
+
+export function resolveId(
+	importee: string,
+	importer: string | null | undefined,
+	options?: Record<string, unknown>,
+): string | null;
+
+// ---------------------------------------------------------------------------
+// Preprocess
+// ---------------------------------------------------------------------------
+
+/** Options the preprocessor pipeline forwards to each callback. */
+export interface MarkupPreprocessorOptions {
+	content: string;
+	filename?: string;
+}
+
+export interface PreprocessorOptions {
+	content: string;
+	filename?: string;
+	attributes: Record<string, string | boolean>;
+	markup?: string;
+}
+
+/** Result returned by a preprocessor callback. `undefined`/`null` is a no-op. */
+export interface Processed {
+	code: string;
+	map?: string | object;
+	dependencies?: string[];
+	attributes?: Record<string, string | boolean>;
+	toString?: () => string;
+}
+
+export type MarkupPreprocessor = (
+	options: MarkupPreprocessorOptions,
+) => Processed | void | null | undefined | Promise<Processed | void | null | undefined>;
+
+export type Preprocessor = (
+	options: PreprocessorOptions,
+) => Processed | void | null | undefined | Promise<Processed | void | null | undefined>;
+
+export interface PreprocessorGroup {
+	name?: string;
+	markup?: MarkupPreprocessor;
+	script?: Preprocessor;
+	style?: Preprocessor;
+}
+
+/**
+ * Run the preprocessor pipeline. Accepts a single group or an array of
+ * groups, matching the upstream `svelte/compiler#preprocess` contract.
+ */
+export function preprocess(
+	source: string,
+	groups: PreprocessorGroup | PreprocessorGroup[],
+	options?: { filename?: string },
+): Promise<Processed>;
+
+// ---------------------------------------------------------------------------
+// Version
+// ---------------------------------------------------------------------------
+
+/**
+ * Upstream Svelte version this binding emits code for. Consumers (the
+ * `@rsvelte/vite-plugin-svelte` fork, etc.) use this for feature
+ * detection (`gte(VERSION, '5.36.0')`), so it follows the *upstream*
+ * Svelte semver — not the rsvelte version.
+ */
+export const VERSION: string;

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@rsvelte/vite-plugin-svelte-native",
+  "version": "0.1.0",
+  "description": "NAPI bindings to the rsvelte compiler — used by the @rsvelte vite-plugin-svelte shim",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/baseballyama/rsvelte.git",
+    "directory": "npm/vite-plugin-svelte-native"
+  },
+  "homepage": "https://github.com/baseballyama/rsvelte/tree/main/npm/vite-plugin-svelte-native#readme",
+  "bugs": {
+    "url": "https://github.com/baseballyama/rsvelte/issues"
+  },
+  "keywords": [
+    "svelte",
+    "vite",
+    "vite-plugin",
+    "rust",
+    "napi"
+  ],
+  "main": "./index.cjs",
+  "types": "./index.d.ts",
+  "files": [
+    "envelope.js",
+    "index.cjs",
+    "index.d.ts"
+  ],
+  "optionalDependencies": {
+    "@rsvelte/vite-plugin-svelte-native-darwin-arm64": "^0.1.0",
+    "@rsvelte/vite-plugin-svelte-native-linux-x64-gnu": "^0.1.0",
+    "@rsvelte/vite-plugin-svelte-native-linux-arm64-gnu": "^0.1.0",
+    "@rsvelte/vite-plugin-svelte-native-darwin-x64": "^0.1.0",
+    "@rsvelte/vite-plugin-svelte-native-win32-x64-msvc": "^0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}