frameassembly-wasm 1.4.6 → 1.5.1

package/README.md

@@ -1,18 +1,39 @@
-# FrameAssembly WebAssembly Compiler (`frameassembly-wasm` v1.4.6)
+# FrameAssembly WebAssembly Compiler (`frameassembly-wasm` v1.5.1)
 
-High-performance WebAssembly compiler, frame inspector, and UTF-16 IDE diagnostics for **FrameAssembly (`.fasm`)** — the **Packets as Code** domain-specific language for compiling `.fasm` code into deterministic `.pcapng` packet captures across 81 L2–L7 protocols for pentesting labs, testing firewall rules, simulating SNMPv1/v2c/v3 traps, and validating network monitoring and cybersecurity solutions in browser applications, web cyber ranges, and Node.js test suites. *(Note: FrameAssembly is a network protocol DSL, not x86 Flat Assembler).*
+[![Website & Playground](https://img.shields.io/badge/web%20app-frameassembly.ai.studio-0ea5e9.svg)](https://frameassembly.ai.studio/)
+[![NPM](https://img.shields.io/npm/v/frameassembly-wasm.svg)](https://www.npmjs.com/package/frameassembly-wasm)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/SteveWinschel/FrameAssembly/blob/main/LICENSE)
+
+[**Try in Browser (`frameassembly.ai.studio`)**](https://frameassembly.ai.studio/) • [**Installation**](#installation) • [**Vite, React & Next.js**](#initialization-vite-react-nextjs--google-ai-studio) • [**TypeScript API**](#typescript-api-reference)
+
+WebAssembly compiler, `.pcap`/`.pcapng`-to-`.fasm` decompiler, frame inspector, and UTF-16 IDE diagnostics for **FrameAssembly (`.fasm`)** — compiling `.fasm` code into `.pcapng` packet captures and decompiling existing captures back into `.fasm` code across 81 L2–L7 protocols in browser applications, web cyber ranges, and Node.js test suites. Powers the official FrameAssembly interactive browser playground at [**frameassembly.ai.studio**](https://frameassembly.ai.studio/). *(Note: FrameAssembly is a network protocol DSL, not x86 Flat Assembler).*
 
 ---
 
-## Client-Side `.fasm` to `.pcapng` Compilation in the Browser & Node.js
+## Client-Side `.fasm` to `.pcapng` Compilation & PCAP Decompilation in the Browser & Node.js
+
+`frameassembly-wasm` compiles the FrameAssembly Rust engine to WebAssembly, turning `.fasm` code into `.pcapng` byte streams, decompiling binary `.pcap` and `.pcapng` captures into `.fasm` code via `reversePcap(pcapBytes)`, and emitting real-time Monaco/CodeMirror syntax diagnostics directly in the browser or Node.js without a backend server:
 
-`frameassembly-wasm` compiles the complete FrameAssembly Rust engine directly to WebAssembly, turning `.fasm` code into nanosecond-precision `.pcapng` byte streams and real-time Monaco/CodeMirror syntax diagnostics entirely in the browser or Node.js—with no backend packet-crafting server, root privileges (`CAP_NET_RAW`), Python `Scapy` runtime, manual `text2pcap` hex offsets, or native `libpcap` dependencies required:
+```frameassembly
+host client { ip 192.168.1.10 mac 00:11:22:33:44:55 }
+host server { ip 8.8.8.8 mac aa:bb:cc:dd:ee:ff }
+
+flow dns_query(c, s) {
+    c -> s dns query txid 0x1234 qname "example.com" qtype "A" wait 1ms
+    c <- s dns response txid 0x1234 qname "example.com" qtype "A" rdata 93.184.216.34 wait 1ms
+}
+
+compile {
+    dns_query(client, server)
+}
+```
 
 ```ts
 import init, {
   compile_fasm_to_pcapng,
   validate_fasm,
   inspect_fasm,
+  reversePcap,
 } from "frameassembly-wasm";
 
 // Initialize WASM module once at startup
@@ -23,7 +44,7 @@ host server { ip 8.8.8.8 mac aa:bb:cc:dd:ee:ff }
 
 flow dns_query(c, s) {
     c -> s dns query txid 0x1234 qname "example.com" qtype "A" wait 1ms
-    c <- s dns response txid 0x1234 qname "example.com" qtype "A" rdata "93.184.216.34" wait 1ms
+    c <- s dns response txid 0x1234 qname "example.com" qtype "A" rdata 93.184.216.34 wait 1ms
 }
 
 compile {
@@ -41,6 +62,10 @@ if (diagnostics.length === 0) {
   const pcapngBytes = compile_fasm_to_pcapng(source);
   const blob = new Blob([pcapngBytes], { type: "application/vnd.tcpdump.pcap" });
   console.log(`Generated PCAPNG: ${blob.size} bytes`);
+
+  // 4. Decompile binary PCAP/PCAPNG bytes back into canonical .fasm code
+  const reversed = reversePcap(pcapngBytes);
+  console.log(`Reversed ${reversed.packetCount} frames across ${reversed.hostCount} hosts:\n${reversed.fasm}`);
 }
 ```
 
@@ -64,10 +89,11 @@ npm install frameassembly-wasm
     validate_fasm,
     inspect_fasm,
     compile_fasm_to_pcapng,
-  } from "https://cdn.jsdelivr.net/npm/frameassembly-wasm@1.4.6/frameassembly_wasm.js";
+    reversePcap,
+  } from "https://cdn.jsdelivr.net/npm/frameassembly-wasm@1.5.1/frameassembly_wasm.js";
 
   await init();
-  console.log("FrameAssembly WebAssembly engine loaded successfully.");
+  console.log("FrameAssembly WebAssembly engine v1.5.1 loaded successfully.");
 </script>
 ```
 
@@ -82,8 +108,10 @@ import init, {
   validate_fasm,
   inspect_fasm,
   compile_fasm_to_pcapng,
+  reversePcap,
   type IdeDiagnostic,
   type PacketPreview,
+  type ReversePcapResult,
 } from "frameassembly-wasm";
 import wasmUrl from "frameassembly-wasm/frameassembly_wasm_bg.wasm?url";
 
@@ -95,7 +123,7 @@ await init({ module_or_path: wasmUrl });
 
 ## API Reference
 
-### `validate_fasm(source: string): IdeDiagnostic[]`
+### `validate_fasm(source: string): IdeDiagnostic[]` / `validateFasm(source: string): IdeDiagnostic[]`
 Parses and validates `.fasm` source code, returning zero-based UTF-16 line and column spans ready for Monaco Editor or CodeMirror 6 diagnostic markers. Returns an empty array `[]` when the source compiles cleanly.
 
 ```ts
@@ -114,22 +142,36 @@ Compiles `.fasm` source code into an array of packet inspection summaries, inclu
 
 ```ts
 interface PacketPreview {
-  index: number;         // 0-based frame index
+  index: number;         // 1-based frame index
   timestamp_ms: number;  // Relative timestamp in milliseconds
   length: number;        // Total packet length in bytes
   hex: string;           // Space-separated lowercase hex byte dump
 }
 ```
 
-### `compile_fasm_to_pcapng(source: string): Uint8Array`
+### `compile_fasm_to_pcapng(source: string): Uint8Array` / `compileFasm(source: string): Uint8Array`
 Compiles `.fasm` source code into a binary `Uint8Array` containing a valid, standards-compliant PCAPNG byte stream with nanosecond timestamp precision (`IfTsResol = 9`). Throws a JavaScript `Error` with rich diagnostic context if compilation fails.
 
+### `reversePcap(pcap_bytes: Uint8Array): ReverseJsResult`
+Decompiles an in-memory `.pcap` or `.pcapng` byte array (`Uint8Array`) across all 81 native Layer 2 through Layer 7 protocols into canonical lowercase `.fasm` code (`host` declarations and an inline `compile` block), returning summary statistics (`packetCount`, `hostCount`). Throws a structured error object (`{ success: false, error, message }`) if `pcap_bytes` is not a valid packet capture.
+
+```ts
+interface ReversePcapResult {
+  success: boolean;     // true when decompilation succeeds
+  fasm: string;         // Canonical lowercase .fasm source code
+  packetCount: number;  // Total number of reversed packets
+  hostCount: number;    // Total number of host_N declarations emitted
+}
+
+type ReverseJsResult = ReversePcapResult;
+```
+
 ---
 
 ## Complete Browser Playground & Download Example
 
 ```ts
-import init, { compile_fasm_to_pcapng, validate_fasm } from "frameassembly-wasm";
+import init, { compile_fasm_to_pcapng, reversePcap, validate_fasm } from "frameassembly-wasm";
 
 export async function downloadCapture(fasmCode: string, filename = "capture.pcapng") {
   await init();
@@ -151,6 +193,13 @@ export async function downloadCapture(fasmCode: string, filename = "capture.pcap
   document.body.removeChild(a);
   URL.revokeObjectURL(url);
 }
+
+export async function importCaptureFile(file: File): Promise<string> {
+  await init();
+  const bytes = new Uint8Array(await file.arrayBuffer());
+  const result = reversePcap(bytes);
+  return result.fasm;
+}
 ```
 
 ---
@@ -158,14 +207,14 @@ export async function downloadCapture(fasmCode: string, filename = "capture.pcap
 ## Features & Engine Capabilities
 
 - **Zero Server Dependencies**: Executes 100% locally in WebAssembly inside Chrome, Firefox, Safari, Edge, Web Workers, and Node.js.
-- **81 Native Protocols**: Complete coverage across L2–L7 (Ethernet, 802.1Q VLAN, QinQ, MPLS, ARP, IPv4/IPv6, ICMP, TCP, UDP, SCTP, SNMPv1/v2c/v3 USM, DNS, DHCP, HTTP, TLS, Modbus, DNP3, and more).
-- **Nanosecond Fidelity**: Compiles deterministic PCAPNG captures with nanosecond-resolution Section and Interface Description Blocks (`IfTsResol(9)`).
-- **Sub-Millisecond Compilation**: Small to medium captures compile in `< 5ms`, making real-time live typing diagnostics instantaneous in web editors.
+- **81 Native Protocols (Forward & Reverse)**: Complete compilation and `.pcap`/`.pcapng` decompilation coverage across L2–L7 (Ethernet, 802.1Q VLAN, QinQ, MPLS, ARP, IPv4/IPv6, ICMP, TCP, UDP, SCTP, SNMPv1/v2c/v3 USM, DNS, DHCP, HTTP, TLS, Modbus, DNP3, and more), including pure Layer-2 MAC-only switch topologies and inline `compile` statements.
+- **Nanosecond Fidelity**: Compiles and reverses deterministic PCAP/PCAPNG captures with nanosecond-resolution Section and Interface Description Blocks (`IfTsResol(9)`).
+- **Sub-Millisecond Compilation**: Small to medium captures compile and decompile in `< 5ms`, making real-time live typing diagnostics and drag-and-drop PCAP import instantaneous in web editors.
 
 ---
 
 ## Disambiguation: FrameAssembly vs. Flat Assembler
 
-**FrameAssembly** (`.fasm`, media type `text/vnd.frameassembly`) is a domain-specific network protocol specification language for synthesizing deterministic `.pcap` and `.pcapng` packet captures. It is completely unrelated to x86 Flat Assembler (`fasm.net`) and SymbiFlow / F4PGA FPGA bitstream FASM tools.
+**FrameAssembly** (`.fasm`, media type `text/vnd.frameassembly`) is a domain-specific network protocol specification language for synthesizing and decompiling deterministic `.pcap` and `.pcapng` packet captures. It is completely unrelated to x86 Flat Assembler (`fasm.net`) and SymbiFlow / F4PGA FPGA bitstream FASM tools.
 
-Full documentation, grammar specifications, and 2,611 verified examples: https://github.com/SteveWinschel/FrameAssembly
+Full documentation, interactive browser playground ([https://frameassembly.ai.studio/](https://frameassembly.ai.studio/)), grammar specifications, and 2,611 verified examples: https://github.com/SteveWinschel/FrameAssembly

package/frameassembly_wasm.d.ts

@@ -17,10 +17,30 @@ export interface PacketPreview {
     hex: string;
 }
 
+export interface ReversePcapResult {
+    success: boolean;
+    fasm: string;
+    packetCount: number;
+    hostCount: number;
+}
+
+export type ReverseJsResult = ReversePcapResult;
+
+export interface ReversePcapError {
+    success: boolean;
+    error: string;
+    message: string;
+}
+
 
 
 /**
- * Compiles .fasm source into a standards-compliant PCAPNG byte array (JS Uint8Array).
+ * Compiles `.fasm` source into a standards-compliant PCAPNG byte array (`compileFasm` alias).
+ */
+export function compileFasm(source: string): Uint8Array;
+
+/**
+ * Compiles `.fasm` source into a standards-compliant PCAPNG byte array (JS `Uint8Array`).
  */
 export function compile_fasm_to_pcapng(source: string): Uint8Array;
 
@@ -30,7 +50,22 @@ export function compile_fasm_to_pcapng(source: string): Uint8Array;
 export function inspect_fasm(source: string): PacketPreview[];
 
 /**
- * Validates .fasm source and returns UTF-16 line/column diagnostics for Monaco/CodeMirror.
+ * Decompiles an in-memory `.pcap` or `.pcapng` capture (`Uint8Array`) into canonical `.fasm`
+ * source code and summary counts (`{ success: true, fasm, packetCount, hostCount }`).
+ *
+ * # Errors
+ * Returns a structured `JsValue` error object (`{ success: false, error, message }`) if
+ * `pcap_bytes` is not a valid `.pcap` or `.pcapng` capture.
+ */
+export function reversePcap(pcap_bytes: Uint8Array | number[]): ReversePcapResult;
+
+/**
+ * Validates `.fasm` source and returns UTF-16 line/column diagnostics (`validateFasm` alias).
+ */
+export function validateFasm(source: string): IdeDiagnostic[];
+
+/**
+ * Validates `.fasm` source and returns UTF-16 line/column diagnostics for Monaco/CodeMirror.
  */
 export function validate_fasm(source: string): IdeDiagnostic[];
 
@@ -38,8 +73,11 @@ export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembl
 
 export interface InitOutput {
     readonly memory: WebAssembly.Memory;
+    readonly compileFasm: (a: number, b: number) => [number, number, number, number];
     readonly compile_fasm_to_pcapng: (a: number, b: number) => [number, number, number, number];
     readonly inspect_fasm: (a: number, b: number) => [number, number, number];
+    readonly reversePcap: (a: number, b: number) => [number, number, number];
+    readonly validateFasm: (a: number, b: number) => [number, number, number];
     readonly validate_fasm: (a: number, b: number) => [number, number, number];
     readonly __wbindgen_malloc: (a: number, b: number) => number;
     readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;

package/frameassembly_wasm.js

@@ -1,7 +1,24 @@
 /* @ts-self-types="./frameassembly_wasm.d.ts" */
 
 /**
- * Compiles .fasm source into a standards-compliant PCAPNG byte array (JS Uint8Array).
+ * Compiles `.fasm` source into a standards-compliant PCAPNG byte array (`compileFasm` alias).
+ * @param {string} source
+ * @returns {Uint8Array}
+ */
+export function compileFasm(source) {
+    const ptr0 = passStringToWasm0(source, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.compileFasm(ptr0, len0);
+    if (ret[3]) {
+        throw takeFromExternrefTable0(ret[2]);
+    }
+    var v2 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
+    wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+    return v2;
+}
+
+/**
+ * Compiles `.fasm` source into a standards-compliant PCAPNG byte array (JS `Uint8Array`).
  * @param {string} source
  * @returns {Uint8Array}
  */
@@ -33,7 +50,42 @@ export function inspect_fasm(source) {
 }
 
 /**
- * Validates .fasm source and returns UTF-16 line/column diagnostics for Monaco/CodeMirror.
+ * Decompiles an in-memory `.pcap` or `.pcapng` capture (`Uint8Array`) into canonical `.fasm`
+ * source code and summary counts (`{ success: true, fasm, packetCount, hostCount }`).
+ *
+ * # Errors
+ * Returns a structured `JsValue` error object (`{ success: false, error, message }`) if
+ * `pcap_bytes` is not a valid `.pcap` or `.pcapng` capture.
+ * @param {Uint8Array | number[]} pcap_bytes
+ * @returns {ReversePcapResult}
+ */
+export function reversePcap(pcap_bytes) {
+    const ptr0 = passArray8ToWasm0(pcap_bytes, wasm.__wbindgen_malloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.reversePcap(ptr0, len0);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
+/**
+ * Validates `.fasm` source and returns UTF-16 line/column diagnostics (`validateFasm` alias).
+ * @param {string} source
+ * @returns {IdeDiagnostic[]}
+ */
+export function validateFasm(source) {
+    const ptr0 = passStringToWasm0(source, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.validateFasm(ptr0, len0);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
+/**
+ * Validates `.fasm` source and returns UTF-16 line/column diagnostics for Monaco/CodeMirror.
  * @param {string} source
  * @returns {IdeDiagnostic[]}
  */
@@ -133,6 +185,13 @@ function getUint8ArrayMemory0() {
     return cachedUint8ArrayMemory0;
 }
 
+function passArray8ToWasm0(arg, malloc) {
+    const ptr = malloc(arg.length * 1, 1) >>> 0;
+    getUint8ArrayMemory0().set(arg, ptr / 1);
+    WASM_VECTOR_LEN = arg.length;
+    return ptr;
+}
+
 function passStringToWasm0(arg, malloc, realloc) {
     if (realloc === undefined) {
         const buf = cachedTextEncoder.encode(arg);

package/package.json

@@ -4,8 +4,8 @@
   "collaborators": [
     "Steve Winschel"
   ],
-  "description": "WebAssembly compiler, packet inspector, and IDE diagnostics for the FrameAssembly (.fasm) network packet synthesis DSL",
-  "version": "1.4.6",
+  "description": "WebAssembly compiler, PCAP/PCAPNG decompiler, packet inspector, and IDE diagnostics for the FrameAssembly (.fasm) network packet synthesis DSL",
+  "version": "1.5.1",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -17,7 +17,7 @@
     "frameassembly_wasm.d.ts"
   ],
   "main": "frameassembly_wasm.js",
-  "homepage": "https://github.com/SteveWinschel/FrameAssembly",
+  "homepage": "https://frameassembly.ai.studio/",
   "types": "frameassembly_wasm.d.ts",
   "sideEffects": [
     "./snippets/*"