teptris 0.0.0-stage → 0.3.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 leptris contributors
+
+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

@@ -1,3 +1,59 @@
-# Temporary Holding Version
+# teptris (JavaScript/TypeScript)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+TOML for JavaScript at libteptris speed — the engine compiled to
+WebAssembly (emscripten, ES module), no fallback.
+
+```js
+import { init } from "teptris";
+
+const teptris = await init();
+teptris.loads('a = 1');               // → { a: 1 }
+teptris.dump(obj);                    // → canonical TOML string
+teptris.dumpJson(obj);                // → natural JSON string
+teptris.engineVersion();              // → the libteptris inside
+```
+
+TypeScript ships first-class: `src/index.d.ts` types the full surface
+(`init`, `TeptrisApi`, `TomlTable`, `TeptrisError` with
+`line`/`column`) — strict `tsc` consumers are part of the test suite.
+For custom instantiation (bundler-managed wasm loading), `initApi(mod)`
+wraps an already-instantiated emscripten module.
+
+**Surface (v1, engine 0.3.0):** `loads` uses the natural-JSON emit —
+real numbers, booleans, RFC 3339 datetime strings, non-finite floats
+as `null`. `dump` emits canonical TOML through the builder; `dumpJson`
+emits the same tree as natural JSON — the string a host hands straight
+to JSON consumers, and the engine's fastest emit mode. Errors carry
+`message`/`line`/`column`.
+
+## Performance (JS tier)
+
+Best-of-40 on darwin/arm64, node 24, over the engine bench corpus
+(`benchmark/js_tier.mjs` — runs in CI as a report-only lane):
+
+- **vs @iarna/toml** (the ecosystem's long-standing standard): 2–4×
+  faster on loads — and it rejects two corpus shapes outright (it
+  still enforces a pre-1.0 single-type-array rule; the corpus is
+  legal TOML 1.0).
+- **vs smol-toml** (the modern fast pure-JS parser): roughly parity
+  — teptris wins the datetime-heavy shapes (1.5×) and deep tables;
+  smol wins scalar-string-heavy inputs, where the wasm→JS bridge
+  (natural-JSON emit + `JSON.parse`) prices every string.
+- **dumpJson vs `JSON.stringify`**: the native baseline is 3–6×
+  faster — same verdict as the ruby/python tiers. The API's value is
+  the one-pass TOML→JSON contract, not beating the platform's JSON.
+
+The JS tier's edge is the engine's correctness: full TOML 1.1 draft
+grammar and the same parse/emit behavior as the ruby, python and
+rust bindings.
+
+## Build
+
+```sh
+ENGINESRC=../teptris/src ./build.sh   # emscripten required
+npm test
+```
+
+The bridge copies input bytes INTO the wasm heap; the engine's
+zero-copy buffer-lifetime contract stays internal — the host never
+holds a heap pointer past the call.

package/dist/teptris.mjs

@@ -0,0 +1,16 @@
+
+var Module = (() => {
+  var _scriptName = import.meta.url;
+  
+  return (
+async function(moduleArg = {}) {
+  var moduleRtn;
+
+var Module=moduleArg;var readyPromiseResolve,readyPromiseReject;var readyPromise=new Promise((resolve,reject)=>{readyPromiseResolve=resolve;readyPromiseReject=reject});var ENVIRONMENT_IS_WEB=typeof window=="object";var ENVIRONMENT_IS_WORKER=typeof WorkerGlobalScope!="undefined";var ENVIRONMENT_IS_NODE=typeof process=="object"&&typeof process.versions=="object"&&typeof process.versions.node=="string"&&process.type!="renderer";if(ENVIRONMENT_IS_NODE){const{createRequire}=await import("module");let dirname=import.meta.url;if(dirname.startsWith("data:")){dirname="/"}var require=createRequire(dirname)}var moduleOverrides=Object.assign({},Module);var arguments_=[];var thisProgram="./this.program";var quit_=(status,toThrow)=>{throw toThrow};var scriptDirectory="";function locateFile(path){if(Module["locateFile"]){return Module["locateFile"](path,scriptDirectory)}return scriptDirectory+path}var readAsync,readBinary;if(ENVIRONMENT_IS_NODE){var fs=require("fs");var nodePath=require("path");if(!import.meta.url.startsWith("data:")){scriptDirectory=nodePath.dirname(require("url").fileURLToPath(import.meta.url))+"/"}readBinary=filename=>{filename=isFileURI(filename)?new URL(filename):filename;var ret=fs.readFileSync(filename);return ret};readAsync=async(filename,binary=true)=>{filename=isFileURI(filename)?new URL(filename):filename;var ret=fs.readFileSync(filename,binary?undefined:"utf8");return ret};if(!Module["thisProgram"]&&process.argv.length>1){thisProgram=process.argv[1].replace(/\\/g,"/")}arguments_=process.argv.slice(2);quit_=(status,toThrow)=>{process.exitCode=status;throw toThrow}}else if(ENVIRONMENT_IS_WEB||ENVIRONMENT_IS_WORKER){if(ENVIRONMENT_IS_WORKER){scriptDirectory=self.location.href}else if(typeof document!="undefined"&&document.currentScript){scriptDirectory=document.currentScript.src}if(_scriptName){scriptDirectory=_scriptName}if(scriptDirectory.startsWith("blob:")){scriptDirectory=""}else{scriptDirectory=scriptDirectory.substr(0,scriptDirectory.replace(/[?#].*/,"").lastIndexOf("/")+1)}{readAsync=async url=>{var response=await fetch(url,{credentials:"same-origin"});if(response.ok){return response.arrayBuffer()}throw new Error(response.status+" : "+response.url)}}}else{}var out=Module["print"]||console.log.bind(console);var err=Module["printErr"]||console.error.bind(console);Object.assign(Module,moduleOverrides);moduleOverrides=null;if(Module["arguments"])arguments_=Module["arguments"];if(Module["thisProgram"])thisProgram=Module["thisProgram"];var wasmBinary=Module["wasmBinary"];var wasmMemory;var ABORT=false;var HEAP8,HEAPU8,HEAP16,HEAPU16,HEAP32,HEAPU32,HEAPF32,HEAP64,HEAPU64,HEAPF64;function updateMemoryViews(){var b=wasmMemory.buffer;Module["HEAP8"]=HEAP8=new Int8Array(b);Module["HEAP16"]=HEAP16=new Int16Array(b);Module["HEAPU8"]=HEAPU8=new Uint8Array(b);Module["HEAPU16"]=HEAPU16=new Uint16Array(b);Module["HEAP32"]=HEAP32=new Int32Array(b);Module["HEAPU32"]=HEAPU32=new Uint32Array(b);Module["HEAPF32"]=HEAPF32=new Float32Array(b);Module["HEAPF64"]=HEAPF64=new Float64Array(b);Module["HEAP64"]=HEAP64=new BigInt64Array(b);Module["HEAPU64"]=HEAPU64=new BigUint64Array(b)}var __ATPRERUN__=[];var __ATINIT__=[];var __ATPOSTRUN__=[];var runtimeInitialized=false;function preRun(){if(Module["preRun"]){if(typeof Module["preRun"]=="function")Module["preRun"]=[Module["preRun"]];while(Module["preRun"].length){addOnPreRun(Module["preRun"].shift())}}callRuntimeCallbacks(__ATPRERUN__)}function initRuntime(){runtimeInitialized=true;callRuntimeCallbacks(__ATINIT__)}function postRun(){if(Module["postRun"]){if(typeof Module["postRun"]=="function")Module["postRun"]=[Module["postRun"]];while(Module["postRun"].length){addOnPostRun(Module["postRun"].shift())}}callRuntimeCallbacks(__ATPOSTRUN__)}function addOnPreRun(cb){__ATPRERUN__.unshift(cb)}function addOnInit(cb){__ATINIT__.unshift(cb)}function addOnPostRun(cb){__ATPOSTRUN__.unshift(cb)}var runDependencies=0;var dependenciesFulfilled=null;function addRunDependency(id){runDependencies++;Module["monitorRunDependencies"]?.(runDependencies)}function removeRunDependency(id){runDependencies--;Module["monitorRunDependencies"]?.(runDependencies);if(runDependencies==0){if(dependenciesFulfilled){var callback=dependenciesFulfilled;dependenciesFulfilled=null;callback()}}}function abort(what){Module["onAbort"]?.(what);what="Aborted("+what+")";err(what);ABORT=true;what+=". Build with -sASSERTIONS for more info.";var e=new WebAssembly.RuntimeError(what);readyPromiseReject(e);throw e}var dataURIPrefix="data:application/octet-stream;base64,";var isDataURI=filename=>filename.startsWith(dataURIPrefix);var isFileURI=filename=>filename.startsWith("file://");function findWasmBinary(){if(Module["locateFile"]){var f="teptris.wasm";if(!isDataURI(f)){return locateFile(f)}return f}return new URL("teptris.wasm",import.meta.url).href}var wasmBinaryFile;function getBinarySync(file){if(file==wasmBinaryFile&&wasmBinary){return new Uint8Array(wasmBinary)}if(readBinary){return readBinary(file)}throw"both async and sync fetching of the wasm failed"}async function getWasmBinary(binaryFile){if(!wasmBinary){try{var response=await readAsync(binaryFile);return new Uint8Array(response)}catch{}}return getBinarySync(binaryFile)}async function instantiateArrayBuffer(binaryFile,imports){try{var binary=await getWasmBinary(binaryFile);var instance=await WebAssembly.instantiate(binary,imports);return instance}catch(reason){err(`failed to asynchronously prepare wasm: ${reason}`);abort(reason)}}async function instantiateAsync(binary,binaryFile,imports){if(!binary&&typeof WebAssembly.instantiateStreaming=="function"&&!isDataURI(binaryFile)&&!ENVIRONMENT_IS_NODE&&typeof fetch=="function"){try{var response=fetch(binaryFile,{credentials:"same-origin"});var instantiationResult=await WebAssembly.instantiateStreaming(response,imports);return instantiationResult}catch(reason){err(`wasm streaming compile failed: ${reason}`);err("falling back to ArrayBuffer instantiation")}}return instantiateArrayBuffer(binaryFile,imports)}function getWasmImports(){return{a:wasmImports}}async function createWasm(){function receiveInstance(instance,module){wasmExports=instance.exports;wasmMemory=wasmExports["c"];updateMemoryViews();addOnInit(wasmExports["d"]);removeRunDependency("wasm-instantiate");return wasmExports}addRunDependency("wasm-instantiate");function receiveInstantiationResult(result){receiveInstance(result["instance"])}var info=getWasmImports();if(Module["instantiateWasm"]){try{return Module["instantiateWasm"](info,receiveInstance)}catch(e){err(`Module.instantiateWasm callback failed with error: ${e}`);readyPromiseReject(e)}}wasmBinaryFile??=findWasmBinary();try{var result=await instantiateAsync(wasmBinary,wasmBinaryFile,info);receiveInstantiationResult(result);return result}catch(e){readyPromiseReject(e);return}}class ExitStatus{name="ExitStatus";constructor(status){this.message=`Program terminated with exit(${status})`;this.status=status}}var callRuntimeCallbacks=callbacks=>{while(callbacks.length>0){callbacks.shift()(Module)}};var noExitRuntime=Module["noExitRuntime"]||true;var UTF8Decoder=typeof TextDecoder!="undefined"?new TextDecoder:undefined;var UTF8ArrayToString=(heapOrArray,idx=0,maxBytesToRead=NaN)=>{var endIdx=idx+maxBytesToRead;var endPtr=idx;while(heapOrArray[endPtr]&&!(endPtr>=endIdx))++endPtr;if(endPtr-idx>16&&heapOrArray.buffer&&UTF8Decoder){return UTF8Decoder.decode(heapOrArray.subarray(idx,endPtr))}var str="";while(idx<endPtr){var u0=heapOrArray[idx++];if(!(u0&128)){str+=String.fromCharCode(u0);continue}var u1=heapOrArray[idx++]&63;if((u0&224)==192){str+=String.fromCharCode((u0&31)<<6|u1);continue}var u2=heapOrArray[idx++]&63;if((u0&240)==224){u0=(u0&15)<<12|u1<<6|u2}else{u0=(u0&7)<<18|u1<<12|u2<<6|heapOrArray[idx++]&63}if(u0<65536){str+=String.fromCharCode(u0)}else{var ch=u0-65536;str+=String.fromCharCode(55296|ch>>10,56320|ch&1023)}}return str};var UTF8ToString=(ptr,maxBytesToRead)=>ptr?UTF8ArrayToString(HEAPU8,ptr,maxBytesToRead):"";var ___assert_fail=(condition,filename,line,func)=>abort(`Assertion failed: ${UTF8ToString(condition)}, at: `+[filename?UTF8ToString(filename):"unknown filename",line,func?UTF8ToString(func):"unknown function"]);var getHeapMax=()=>2147483648;var alignMemory=(size,alignment)=>Math.ceil(size/alignment)*alignment;var growMemory=size=>{var b=wasmMemory.buffer;var pages=(size-b.byteLength+65535)/65536|0;try{wasmMemory.grow(pages);updateMemoryViews();return 1}catch(e){}};var _emscripten_resize_heap=requestedSize=>{var oldSize=HEAPU8.length;requestedSize>>>=0;var maxHeapSize=getHeapMax();if(requestedSize>maxHeapSize){return false}for(var cutDown=1;cutDown<=4;cutDown*=2){var overGrownHeapSize=oldSize*(1+.2/cutDown);overGrownHeapSize=Math.min(overGrownHeapSize,requestedSize+100663296);var newSize=Math.min(maxHeapSize,alignMemory(Math.max(requestedSize,overGrownHeapSize),65536));var replacement=growMemory(newSize);if(replacement){return true}}return false};var stringToUTF8Array=(str,heap,outIdx,maxBytesToWrite)=>{if(!(maxBytesToWrite>0))return 0;var startIdx=outIdx;var endIdx=outIdx+maxBytesToWrite-1;for(var i=0;i<str.length;++i){var u=str.charCodeAt(i);if(u>=55296&&u<=57343){var u1=str.charCodeAt(++i);u=65536+((u&1023)<<10)|u1&1023}if(u<=127){if(outIdx>=endIdx)break;heap[outIdx++]=u}else if(u<=2047){if(outIdx+1>=endIdx)break;heap[outIdx++]=192|u>>6;heap[outIdx++]=128|u&63}else if(u<=65535){if(outIdx+2>=endIdx)break;heap[outIdx++]=224|u>>12;heap[outIdx++]=128|u>>6&63;heap[outIdx++]=128|u&63}else{if(outIdx+3>=endIdx)break;heap[outIdx++]=240|u>>18;heap[outIdx++]=128|u>>12&63;heap[outIdx++]=128|u>>6&63;heap[outIdx++]=128|u&63}}heap[outIdx]=0;return outIdx-startIdx};var stringToUTF8=(str,outPtr,maxBytesToWrite)=>stringToUTF8Array(str,HEAPU8,outPtr,maxBytesToWrite);var lengthBytesUTF8=str=>{var len=0;for(var i=0;i<str.length;++i){var c=str.charCodeAt(i);if(c<=127){len++}else if(c<=2047){len+=2}else if(c>=55296&&c<=57343){len+=4;++i}else{len+=3}}return len};var wasmImports={a:___assert_fail,b:_emscripten_resize_heap};var wasmExports;createWasm();var ___wasm_call_ctors=()=>(___wasm_call_ctors=wasmExports["d"])();var _teptris_wasm_load=Module["_teptris_wasm_load"]=(a0,a1)=>(_teptris_wasm_load=Module["_teptris_wasm_load"]=wasmExports["e"])(a0,a1);var _teptris_wasm_last_error=Module["_teptris_wasm_last_error"]=()=>(_teptris_wasm_last_error=Module["_teptris_wasm_last_error"]=wasmExports["f"])();var _teptris_wasm_last_error_line=Module["_teptris_wasm_last_error_line"]=()=>(_teptris_wasm_last_error_line=Module["_teptris_wasm_last_error_line"]=wasmExports["g"])();var _teptris_wasm_last_error_column=Module["_teptris_wasm_last_error_column"]=()=>(_teptris_wasm_last_error_column=Module["_teptris_wasm_last_error_column"]=wasmExports["h"])();var _teptris_wasm_json=Module["_teptris_wasm_json"]=()=>(_teptris_wasm_json=Module["_teptris_wasm_json"]=wasmExports["i"])();var _teptris_wasm_json_len=Module["_teptris_wasm_json_len"]=()=>(_teptris_wasm_json_len=Module["_teptris_wasm_json_len"]=wasmExports["j"])();var _teptris_wasm_free=Module["_teptris_wasm_free"]=a0=>(_teptris_wasm_free=Module["_teptris_wasm_free"]=wasmExports["k"])(a0);var _teptris_wasm_builder_new=Module["_teptris_wasm_builder_new"]=()=>(_teptris_wasm_builder_new=Module["_teptris_wasm_builder_new"]=wasmExports["l"])();var _teptris_wasm_builder_free=Module["_teptris_wasm_builder_free"]=a0=>(_teptris_wasm_builder_free=Module["_teptris_wasm_builder_free"]=wasmExports["m"])(a0);var _teptris_wasm_builder_put_string=Module["_teptris_wasm_builder_put_string"]=(a0,a1,a2)=>(_teptris_wasm_builder_put_string=Module["_teptris_wasm_builder_put_string"]=wasmExports["n"])(a0,a1,a2);var _teptris_wasm_builder_put_integer=Module["_teptris_wasm_builder_put_integer"]=(a0,a1,a2)=>(_teptris_wasm_builder_put_integer=Module["_teptris_wasm_builder_put_integer"]=wasmExports["o"])(a0,a1,a2);var _teptris_wasm_builder_put_float=Module["_teptris_wasm_builder_put_float"]=(a0,a1,a2)=>(_teptris_wasm_builder_put_float=Module["_teptris_wasm_builder_put_float"]=wasmExports["p"])(a0,a1,a2);var _teptris_wasm_builder_put_boolean=Module["_teptris_wasm_builder_put_boolean"]=(a0,a1,a2)=>(_teptris_wasm_builder_put_boolean=Module["_teptris_wasm_builder_put_boolean"]=wasmExports["q"])(a0,a1,a2);var _teptris_wasm_builder_put_datetime=Module["_teptris_wasm_builder_put_datetime"]=(a0,a1,a2,a3,a4,a5,a6,a7,a8,a9,a10)=>(_teptris_wasm_builder_put_datetime=Module["_teptris_wasm_builder_put_datetime"]=wasmExports["r"])(a0,a1,a2,a3,a4,a5,a6,a7,a8,a9,a10);var _teptris_wasm_builder_open_table=Module["_teptris_wasm_builder_open_table"]=(a0,a1)=>(_teptris_wasm_builder_open_table=Module["_teptris_wasm_builder_open_table"]=wasmExports["s"])(a0,a1);var _teptris_wasm_builder_open_array=Module["_teptris_wasm_builder_open_array"]=(a0,a1)=>(_teptris_wasm_builder_open_array=Module["_teptris_wasm_builder_open_array"]=wasmExports["t"])(a0,a1);var _teptris_wasm_builder_close=Module["_teptris_wasm_builder_close"]=a0=>(_teptris_wasm_builder_close=Module["_teptris_wasm_builder_close"]=wasmExports["u"])(a0);var _teptris_wasm_builder_finish=Module["_teptris_wasm_builder_finish"]=a0=>(_teptris_wasm_builder_finish=Module["_teptris_wasm_builder_finish"]=wasmExports["v"])(a0);var _teptris_wasm_builder_finish_json_natural=Module["_teptris_wasm_builder_finish_json_natural"]=a0=>(_teptris_wasm_builder_finish_json_natural=Module["_teptris_wasm_builder_finish_json_natural"]=wasmExports["w"])(a0);var _teptris_wasm_toml=Module["_teptris_wasm_toml"]=()=>(_teptris_wasm_toml=Module["_teptris_wasm_toml"]=wasmExports["x"])();var _teptris_wasm_toml_len=Module["_teptris_wasm_toml_len"]=()=>(_teptris_wasm_toml_len=Module["_teptris_wasm_toml_len"]=wasmExports["y"])();var _malloc=Module["_malloc"]=a0=>(_malloc=Module["_malloc"]=wasmExports["A"])(a0);var _teptris_version_string=Module["_teptris_version_string"]=()=>(_teptris_version_string=Module["_teptris_version_string"]=wasmExports["B"])();Module["UTF8ToString"]=UTF8ToString;Module["stringToUTF8"]=stringToUTF8;Module["lengthBytesUTF8"]=lengthBytesUTF8;var calledRun;dependenciesFulfilled=function runCaller(){if(!calledRun)run();if(!calledRun)dependenciesFulfilled=runCaller};function run(){if(runDependencies>0){return}preRun();if(runDependencies>0){return}function doRun(){if(calledRun)return;calledRun=true;Module["calledRun"]=true;if(ABORT)return;initRuntime();readyPromiseResolve(Module);Module["onRuntimeInitialized"]?.();postRun()}if(Module["setStatus"]){Module["setStatus"]("Running...");setTimeout(()=>{setTimeout(()=>Module["setStatus"](""),1);doRun()},1)}else{doRun()}}if(Module["preInit"]){if(typeof Module["preInit"]=="function")Module["preInit"]=[Module["preInit"]];while(Module["preInit"].length>0){Module["preInit"].pop()()}}run();moduleRtn=readyPromise;
+
+
+  return moduleRtn;
+}
+);
+})();
+export default Module;

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "teptris",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.4",
+  "description": "TOML for JavaScript/TypeScript at libteptris speed (WebAssembly, no fallback) - version tracks the engine ({engine}.{iteration}; npm semver is 3-part)",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "./build.sh",
+    "test": "node --test test/test.mjs test/package.test.mjs"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/leptris/teptris-ts.git"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "types": "src/index.d.ts",
+  "devDependencies": {
+    "@iarna/toml": "^2.2.5",
+    "smol-toml": "^1.9.1"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * teptris — TOML 1.1 for JavaScript/TypeScript at libteptris
+ * speed (WebAssembly, no fallback).
+ *
+ *   const teptris = await init();
+ *   const doc = teptris.loads('title = "demo"');
+ *   const toml = teptris.dump(doc);
+ *   const json = teptris.dumpJson(doc);
+ */
+
+/** A parsed TOML value: datetimes are RFC 3339 strings, non-finite
+ *  floats (nan/inf) are null. */
+export type TomlValue =
+  | string
+  | number
+  | boolean
+  | null
+  | TomlTable
+  | TomlValue[];
+
+/** A TOML table: string keys, insertion-ordered. */
+export interface TomlTable {
+  [key: string]: TomlValue;
+}
+
+/** Parse errors carry the engine's line/column (1-based). */
+export interface TeptrisError extends Error {
+  line: number;
+  column: number;
+}
+
+export interface TeptrisApi {
+  /** Parse TOML into a JS object (natural-JSON view: real numbers,
+   *  booleans, RFC 3339 datetime strings, non-finite floats as
+   *  null). Throws TeptrisError on invalid input. */
+  loads(toml: string): TomlTable;
+
+  /** Serialize a table to canonical TOML via the engine builder.
+   *  RFC 3339 strings re-enter as datetimes. Throws TypeError for
+   *  non-table roots, Error for unsupported values. */
+  dump(value: TomlTable): string;
+
+  /** Serialize a table to natural JSON (the engine's fastest emit
+   *  mode): real numbers, booleans, RFC 3339 datetime strings,
+   *  non-finite floats as null. */
+  dumpJson(value: TomlTable): string;
+
+  /** The libteptris engine version inside this build. */
+  engineVersion(): string;
+}
+
+/** Instantiate the WebAssembly engine and return the API. */
+export function init(): Promise<TeptrisApi>;
+
+/** Advanced: wrap an already-instantiated engine module (custom
+ *  instantiation, browser bundlers with special wasm loading). */
+export function initApi(mod: unknown): TeptrisApi;
+
+export default init;

package/src/index.js

@@ -0,0 +1,213 @@
+// The public surface: natural-JSON loads + builder-driven dumps.
+// Engine FFI through ../dist/teptris.mjs (built by build.sh).
+
+const KIND_OFFSET = 4, KIND_LOCAL_DT = 5, KIND_DATE = 6, KIND_TIME = 7;
+
+function cstr(mod, s) {
+  const bytes = mod.lengthBytesUTF8(s) + 1;
+  const ptr = mod._malloc(bytes);
+  mod.stringToUTF8(s, ptr, bytes);
+  return ptr;
+}
+
+function freeCstr(mod, ptr) { mod._teptris_wasm_free(ptr); }
+
+// RFC 3339-ish (the four TOML shapes) back into builder fields
+function parseDateTime(str) {
+  let m = str.match(
+    /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?(Z|[+-]\d{2}:\d{2})?$/);
+  if (m) {
+    const kind = m[8] ? KIND_OFFSET : KIND_LOCAL_DT;
+    let offset = 0;
+    if (m[8] && m[8] !== "Z") {
+      const sign = m[8][0] === "-" ? -1 : 1;
+      const hh = parseInt(m[8].slice(1, 3), 10);
+      const mm = parseInt(m[8].slice(4, 6), 10);
+      offset = sign * (hh * 3600 + mm * 60);
+    }
+    return {
+      kind, year: +m[1], month: +m[2], day: +m[3], hour: +m[4],
+      minute: +m[5], second: +m[6],
+      nanosecond: m[7] ? Math.floor(+("0." + m[7]) * 1e9) : 0,
+      offset_seconds: offset,
+    };
+  }
+  m = str.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+  if (m) {
+    return { kind: KIND_DATE, year: +m[1], month: +m[2], day: +m[3],
+             hour: 0, minute: 0, second: 0, nanosecond: 0,
+             offset_seconds: 0 };
+  }
+  m = str.match(/^(\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?$/);
+  if (m) {
+    return { kind: KIND_TIME, year: 0, month: 0, day: 0, hour: +m[1],
+             minute: +m[2], second: +m[3],
+             nanosecond: m[4] ? Math.floor(+("0." + m[4]) * 1e9) : 0,
+             offset_seconds: 0 };
+  }
+  return null;
+}
+
+const RFC3339 =
+  /^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?)?$|^\d{2}:\d{2}:\d{2}(\.\d+)?$/;
+
+function buildValue(mod, b, key, v, errs) {
+  const kp = key == null ? 0 : cstr(mod, key);
+  try {
+    if (v === null || v === undefined) {
+      throw new Error("null/undefined cannot round-trip through TOML");
+    }
+    switch (typeof v) {
+      case "number":
+        if (Number.isInteger(v)) {
+          mod._teptris_wasm_builder_put_integer(b, kp, BigInt(v));
+        } else {
+          mod._teptris_wasm_builder_put_float(b, kp, v);
+        }
+        return;
+      case "boolean":
+        mod._teptris_wasm_builder_put_boolean(b, kp, v ? 1 : 0);
+        return;
+      case "string":
+        // RFC 3339 strings from loads() re-enter as datetimes; a
+        // plain string stays a string
+        if (RFC3339.test(v)) {
+          const dt = parseDateTime(v);
+          mod._teptris_wasm_builder_put_datetime(
+            b, kp, dt.kind, dt.year, dt.month, dt.day, dt.hour,
+            dt.minute, dt.second, dt.nanosecond, dt.offset_seconds);
+          return;
+        }
+        const vp = cstr(mod, v);
+        mod._teptris_wasm_builder_put_string(b, kp, vp);
+        freeCstr(mod, vp);
+        return;
+      default:
+        break;
+    }
+    if (Array.isArray(v)) {
+      mod._teptris_wasm_builder_open_array(b, kp);
+      for (const item of v) buildValue(mod, b, null, item, errs);
+      mod._teptris_wasm_builder_close(b);
+      return;
+    }
+    if (typeof v === "object") {
+      // open_table with a NULL key = element of the current array
+      // (array-of-tables); the root table itself is implicit (see
+      // dump - it iterates root entries directly)
+      mod._teptris_wasm_builder_open_table(b, kp);
+      for (const [k, item] of Object.entries(v)) {
+        buildValue(mod, b, k, item, errs);
+      }
+      mod._teptris_wasm_builder_close(b);
+      return;
+    }
+    errs.push(new Error(`unsupported value: ${String(v)}`));
+  } finally {
+    if (kp) freeCstr(mod, kp);
+  }
+}
+
+import createModule from "../dist/teptris.mjs";
+
+export function initApi(mod) {
+  const { UTF8ToString, stringToUTF8, lengthBytesUTF8 } = mod;
+
+  function loads(toml) {
+    if (typeof toml !== "string") {
+      throw new TypeError("loads expects a string");
+    }
+    const ptr = cstr(mod, toml);
+    const st = mod._teptris_wasm_load(ptr, lengthBytesUTF8(toml));
+    let value = null, error = null;
+    if (st === 0) {
+      const jptr = mod._teptris_wasm_json();
+      value = JSON.parse(UTF8ToString(jptr));
+      mod._teptris_wasm_free(jptr);
+    } else {
+      error = {
+        message: UTF8ToString(mod._teptris_wasm_last_error()),
+        line: mod._teptris_wasm_last_error_line(),
+        column: mod._teptris_wasm_last_error_column(),
+        status: st,
+      };
+    }
+    freeCstr(mod, ptr);
+    if (error) {
+      const e = new Error(
+        `${error.message} (line ${error.line}, column ${error.column})`);
+      e.line = error.line;
+      e.column = error.column;
+      throw e;
+    }
+    return value;
+  }
+
+  function buildTree(obj) {
+    if (obj === null || typeof obj !== "object" || Array.isArray(obj)) {
+      throw new TypeError("dump expects a table object (TOML roots are tables)");
+    }
+    const b = mod._teptris_wasm_builder_new();
+    const errs = [];
+    // the root table is implicit: entries attach directly
+    for (const [k, item] of Object.entries(obj)) {
+      buildValue(mod, b, k, item, errs);
+    }
+    if (errs.length) {
+      mod._teptris_wasm_builder_free(b);
+      throw errs[0];
+    }
+    return b;
+  }
+
+  function readOut(ptr) {
+    const out = UTF8ToString(ptr);
+    mod._teptris_wasm_free(ptr);
+    return out;
+  }
+
+  function dump(obj) {
+    const b = buildTree(obj);
+    try {
+      const st = mod._teptris_wasm_builder_finish(b);
+      if (st !== 0) {
+        throw new Error(`dump failed (status ${st})`);
+      }
+      return readOut(mod._teptris_wasm_toml());
+    } finally {
+      mod._teptris_wasm_builder_free(b);
+    }
+  }
+
+  // Natural JSON (engine 0.3.0): real numbers, booleans, RFC 3339
+  // datetime strings; non-finite floats become null. The string a
+  // host can hand straight to JSON consumers.
+  function dumpJson(obj) {
+    const b = buildTree(obj);
+    try {
+      const st = mod._teptris_wasm_builder_finish_json_natural(b);
+      if (st !== 0) {
+        throw new Error(`dumpJson failed (status ${st})`);
+      }
+      return readOut(mod._teptris_wasm_toml());
+    } finally {
+      mod._teptris_wasm_builder_free(b);
+    }
+  }
+
+  function engineVersion() {
+    return UTF8ToString(mod._teptris_version_string());
+  }
+
+  return { loads, dump, dumpJson, engineVersion };
+}
+
+// The consumer entry: instantiate the engine once, get the API.
+//   const teptris = await init();
+//   teptris.loads("a = 1");
+export async function init() {
+  const mod = await createModule();
+  return initApi(mod);
+}
+
+export default init;

package/src/teptris_wasm.c

@@ -0,0 +1,165 @@
+/* The wasm surface: one contained bridge over the zero-copy core.
+ * Input bytes are copied INTO the wasm heap; the document's views live
+ * inside the heap for the duration of the call; the JSON answer leaves
+ * before the document is freed. The host never holds a heap pointer
+ * past the call - the C buffer-lifetime contract stays internal. */
+#include <emscripten/emscripten.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "teptris/teptris.h"
+
+static char *g_json;
+static size_t g_json_len;
+
+static char last_error[256];
+static int last_error_line;
+static int last_error_column;
+
+EMSCRIPTEN_KEEPALIVE
+int teptris_wasm_load(const char *data, size_t len) {
+    teptris_document *doc = NULL;
+    teptris_status st = teptris_parse(data, len, NULL, &doc);
+    if (st != TEPTRIS_OK || doc == NULL) {
+        if (doc != NULL) {
+            /* read the error BEFORE the free - it points into the doc */
+            const teptris_error *e = teptris_document_error(doc);
+            snprintf(last_error, sizeof last_error, "%s", e->message);
+            last_error_line = (int)e->line;
+            last_error_column = (int)e->column;
+            teptris_document_free(doc);
+        } else {
+            snprintf(last_error, sizeof last_error, "parse failed");
+            last_error_line = 0;
+            last_error_column = 0;
+        }
+        return (int)st;
+    }
+    st = teptris_document_emit_json_natural(doc, &g_json, &g_json_len);
+    teptris_document_free(doc);
+    return (int)st;
+}
+
+EMSCRIPTEN_KEEPALIVE
+const char *teptris_wasm_last_error(void) { return last_error; }
+
+EMSCRIPTEN_KEEPALIVE
+int teptris_wasm_last_error_line(void) { return last_error_line; }
+
+EMSCRIPTEN_KEEPALIVE
+int teptris_wasm_last_error_column(void) { return last_error_column; }
+
+EMSCRIPTEN_KEEPALIVE
+const char *teptris_wasm_json(void) { return g_json; }
+
+EMSCRIPTEN_KEEPALIVE
+int teptris_wasm_json_len(void) { return (int)g_json_len; }
+
+EMSCRIPTEN_KEEPALIVE
+void teptris_wasm_free(void *p) { free(p); }
+
+/* ---- builder surface (the dump side) ----------------------------- *
+ * 1:1 with teptris_builder_*: the JS wrapper drives the same stack
+ * discipline (open/close, NULL key = array element) the C and Rust
+ * bindings use, so the emitter stays the single formatting truth. */
+
+EMSCRIPTEN_KEEPALIVE
+void *teptris_wasm_builder_new(void) { return teptris_builder_new(); }
+
+EMSCRIPTEN_KEEPALIVE
+void teptris_wasm_builder_free(void *b) { teptris_builder_free(b); }
+
+EMSCRIPTEN_KEEPALIVE
+int teptris_wasm_builder_put_string(void *b, const char *key,
+                                    const char *val) {
+    return teptris_builder_put_string(b, key, key ? strlen(key) : 0,
+                                      val, strlen(val));
+}
+
+EMSCRIPTEN_KEEPALIVE
+int teptris_wasm_builder_put_integer(void *b, const char *key,
+                                     int64_t v) {
+    return teptris_builder_put_integer(b, key, key ? strlen(key) : 0, v);
+}
+
+EMSCRIPTEN_KEEPALIVE
+int teptris_wasm_builder_put_float(void *b, const char *key, double v) {
+    return teptris_builder_put_float(b, key, key ? strlen(key) : 0, v);
+}
+
+EMSCRIPTEN_KEEPALIVE
+int teptris_wasm_builder_put_boolean(void *b, const char *key, int v) {
+    return teptris_builder_put_boolean(b, key, key ? strlen(key) : 0,
+                                       v != 0);
+}
+
+EMSCRIPTEN_KEEPALIVE
+int teptris_wasm_builder_put_datetime(void *b, const char *key, int kind,
+                                      int32_t year, uint8_t month,
+                                      uint8_t day, uint8_t hour,
+                                      uint8_t minute, uint8_t second,
+                                      uint32_t nanosecond,
+                                      int32_t offset_seconds) {
+    teptris_datetime dt = {year, month, day, hour, minute, second,
+                           nanosecond, offset_seconds};
+    return teptris_builder_put_datetime(
+        b, key, key ? strlen(key) : 0, (teptris_kind)kind, &dt);
+}
+
+EMSCRIPTEN_KEEPALIVE
+int teptris_wasm_builder_open_table(void *b, const char *key) {
+    return teptris_builder_open_table(b, key, key ? strlen(key) : 0);
+}
+
+EMSCRIPTEN_KEEPALIVE
+int teptris_wasm_builder_open_array(void *b, const char *key) {
+    return teptris_builder_open_array(b, key, key ? strlen(key) : 0);
+}
+
+EMSCRIPTEN_KEEPALIVE
+int teptris_wasm_builder_close(void *b) {
+    return teptris_builder_close(b);
+}
+
+/* finish -> emit into a global buffer (same accessor pattern as the
+ * parse-side JSON): the dump path offers canonical TOML and the
+ * host-facing natural JSON (engine 0.3.0). */
+static char *g_toml;
+static size_t g_toml_len;
+
+static int finish_with(void *b,
+                       teptris_status (*emit)(const teptris_document *,
+                                              char **, size_t *)) {
+    teptris_document *doc = NULL;
+    teptris_status st = teptris_builder_finish(b, &doc);
+    if (st != TEPTRIS_OK) {
+        return (int)st;
+    }
+    char *buf = NULL;
+    size_t len = 0;
+    st = emit(doc, &buf, &len);
+    teptris_document_free(doc);
+    if (st != TEPTRIS_OK) {
+        return (int)st;
+    }
+    g_toml = buf;
+    g_toml_len = len;
+    return TEPTRIS_OK;
+}
+
+EMSCRIPTEN_KEEPALIVE
+int teptris_wasm_builder_finish(void *b) {
+    return finish_with(b, teptris_document_emit);
+}
+
+EMSCRIPTEN_KEEPALIVE
+int teptris_wasm_builder_finish_json_natural(void *b) {
+    return finish_with(b, teptris_document_emit_json_natural);
+}
+
+EMSCRIPTEN_KEEPALIVE
+const char *teptris_wasm_toml(void) { return g_toml; }
+
+EMSCRIPTEN_KEEPALIVE
+int teptris_wasm_toml_len(void) { return (int)g_toml_len; }