frameassembly-wasm 1.5.0 → 2.0.0

package/README.md

@@ -1,20 +1,26 @@
-# FrameAssembly WebAssembly Compiler (`frameassembly-wasm` v1.5.0)
+# FrameAssembly WebAssembly Compiler (`frameassembly-wasm` v2.0.0)
 
-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. *(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) • [**API Reference**](#api-reference)
+
+WebAssembly compiler, `.pcap`/`.pcapng`-to-`.fasm` decompiler, packet ladder inspector, and UTF-16 IDE diagnostics for **FrameAssembly (`.fasm` v2.0.0)** — compiling `.fasm` code into `.pcapng` packet captures and decompiling existing captures back into `.fasm` code across 81 L2–L7 protocols in browser applications, VS Code Desktop & Web extensions, web cyber ranges, and Node.js test suites. Powers the official FrameAssembly interactive browser playground at [**frameassembly.ai.studio**](https://frameassembly.ai.studio/) and the official VS Code extension (`SteveWinschel.frameassembly-vscode`). *(Note: FrameAssembly is a network packet specification compiler, not x86 Flat Assembler).*
 
 ---
 
 ## 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 FrameAssembly Rust engine to WebAssembly, turning `.fasm` code into `.pcapng` byte streams, decompiling binary `.pcap` and `.pcapng` captures into strict-lowercase `.fasm` code via `reverse_pcap(pcapBytes)` / `reversePcap(pcapBytes)`, and emitting real-time Monaco, CodeMirror, and VS Code diagnostics directly in the browser or Node.js without a backend server:
 
 ```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
+    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 {
@@ -37,27 +43,27 @@ const source = `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
+    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)
 }`;
 
-// 1. Validate syntax & semantics for Monaco / CodeMirror editor markers
+// 1. Validate syntax & semantics for Monaco / CodeMirror / VS Code editor markers
 const diagnostics = validate_fasm(source);
 if (diagnostics.length === 0) {
-  // 2. Inspect individual packet headers and hex payloads
+  // 2. Inspect individual packet ladder rows, protocol labels, summaries, and hex payloads
   const previews = inspect_fasm(source);
-  console.log(`Synthesized ${previews.length} frames.`);
+  console.log(`Synthesized ${previews.length} frames (${previews[0].protocol}: ${previews[0].summary}).`);
 
   // 3. Compile to binary PCAPNG Uint8Array
   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
+  // 4. Decompile binary PCAP/PCAPNG bytes back into strict-lowercase .fasm code
   const reversed = reversePcap(pcapngBytes);
   console.log(`Reversed ${reversed.packetCount} frames across ${reversed.hostCount} hosts:\n${reversed.fasm}`);
 }
@@ -84,10 +90,10 @@ npm install frameassembly-wasm
     inspect_fasm,
     compile_fasm_to_pcapng,
     reversePcap,
-  } from "https://cdn.jsdelivr.net/npm/frameassembly-wasm@1.5.0/frameassembly_wasm.js";
+  } from "https://cdn.jsdelivr.net/npm/frameassembly-wasm@2.0.0/frameassembly_wasm.js";
 
   await init();
-  console.log("FrameAssembly WebAssembly engine v1.5.0 loaded successfully.");
+  console.log("FrameAssembly WebAssembly engine v2.0.0 loaded successfully.");
 </script>
 ```
 
@@ -118,7 +124,7 @@ await init({ module_or_path: wasmUrl });
 ## API Reference
 
 ### `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.
+Parses, validates, and test-compiles `.fasm` source code, returning zero-based UTF-16 line and column spans ready for Monaco Editor, CodeMirror 6, or VS Code diagnostic markers (including v2.0.0 strict-lowercase quick-fix remediation hints in `help`). Returns an empty array `[]` when the source compiles cleanly.
 
 ```ts
 interface IdeDiagnostic {
@@ -127,12 +133,12 @@ interface IdeDiagnostic {
   end_line: number;   // 0-based UTF-16 line index
   end_col: number;    // 0-based UTF-16 character column
   message: string;    // Human-readable diagnostic message
-  help?: string;      // Actionable "Did you mean...?" remediation hint
+  help?: string;      // Actionable remediation or 1-click quick-fix hint
 }
 ```
 
 ### `inspect_fasm(source: string): PacketPreview[]`
-Compiles `.fasm` source code into an array of packet inspection summaries, including relative nanosecond timestamps, frame lengths, and lowercase space-delimited hex byte dumps. Throws a JavaScript `Error` if compilation fails.
+Compiles `.fasm` source code into an array of packet ladder inspection entries, including relative millisecond timestamps, endpoint pairs (`source_dest`), protocol labels (`protocol`), decoded Ethernet/VLAN/QinQ/MPLS/L3/L4/L7 summaries (`summary`), frame lengths, and lowercase space-delimited hex byte dumps. Throws a JavaScript `Error` if compilation fails.
 
 ```ts
 interface PacketPreview {
@@ -140,21 +146,24 @@ interface PacketPreview {
   timestamp_ms: number;  // Relative timestamp in milliseconds
   length: number;        // Total packet length in bytes
   hex: string;           // Space-separated lowercase hex byte dump
+  source_dest: string;   // Formatted "src -> dst" IPv4, IPv6, or MAC pair
+  protocol: string;      // Highest-layer protocol label (e.g. "DNS", "SNMP", "MODBUS")
+  summary: string;       // Decoded L2/L3/L4/L7 frame summary string
 }
 ```
 
 ### `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.
+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 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.
+### `reverse_pcap(pcap_bytes: Uint8Array): ReverseJsResult` / `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 strict-lowercase `.fasm` code (`host1`, `host2`, ... 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
+  fasm: string;         // Strict-lowercase .fasm source code
   packetCount: number;  // Total number of reversed packets
-  hostCount: number;    // Total number of host_N declarations emitted
+  hostCount: number;    // Total number of host1, host2, ... declarations emitted
 }
 
 type ReverseJsResult = ReversePcapResult;
@@ -200,15 +209,15 @@ export async function importCaptureFile(file: File): Promise<string> {
 
 ## Features & Engine Capabilities
 
-- **Zero Server Dependencies**: Executes 100% locally in WebAssembly inside Chrome, Firefox, Safari, Edge, Web Workers, and Node.js.
-- **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.
+- **Zero Server Dependencies**: Executes 100% locally in WebAssembly inside Chrome, Firefox, Safari, Edge, Web Workers, VS Code Desktop/Web, and Node.js.
+- **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, QUIC, 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.
+- **Sub-Millisecond Compilation**: Small to medium captures compile and decompile in `< 5ms`, making real-time live typing diagnostics, packet ladder previews, and drag-and-drop PCAP import instantaneous in web and IDE editors.
 
 ---
 
 ## Disambiguation: FrameAssembly vs. Flat Assembler
 
-**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.
+**FrameAssembly** (`.fasm`, media type `text/vnd.frameassembly`) is a network packet specification compiler for generating and decompiling `.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

@@ -15,6 +15,9 @@ export interface PacketPreview {
     timestamp_ms: number;
     length: number;
     hex: string;
+    source_dest: string;
+    protocol: string;
+    summary: string;
 }
 
 export interface ReversePcapResult {
@@ -45,10 +48,19 @@ export function compileFasm(source: string): Uint8Array;
 export function compile_fasm_to_pcapng(source: string): Uint8Array;
 
 /**
- * Returns decoded frame metadata and hex strings for a browser packet inspector.
+ * Returns decoded frame metadata, endpoint/protocol summaries, and hex strings for packet ladder inspectors.
  */
 export function inspect_fasm(source: string): PacketPreview[];
 
+/**
+ * Decompiles an in-memory `.pcap` or `.pcapng` capture (`reversePcap` camelCase alias).
+ *
+ * # 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;
+
 /**
  * Decompiles an in-memory `.pcap` or `.pcapng` capture (`Uint8Array`) into canonical `.fasm`
  * source code and summary counts (`{ success: true, fasm, packetCount, hostCount }`).
@@ -57,7 +69,7 @@ export function inspect_fasm(source: string): PacketPreview[];
  * 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;
+export function reverse_pcap(pcap_bytes: Uint8Array | number[]): ReversePcapResult;
 
 /**
  * Validates `.fasm` source and returns UTF-16 line/column diagnostics (`validateFasm` alias).
@@ -65,7 +77,7 @@ export function reversePcap(pcap_bytes: Uint8Array | number[]): ReversePcapResul
 export function validateFasm(source: string): IdeDiagnostic[];
 
 /**
- * Validates `.fasm` source and returns UTF-16 line/column diagnostics for Monaco/CodeMirror.
+ * Validates `.fasm` source and returns UTF-16 line/column diagnostics for Monaco, CodeMirror, and VS Code.
  */
 export function validate_fasm(source: string): IdeDiagnostic[];
 
@@ -77,6 +89,7 @@ export interface InitOutput {
     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 reverse_pcap: (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;

package/frameassembly_wasm.js

@@ -35,7 +35,7 @@ export function compile_fasm_to_pcapng(source) {
 }
 
 /**
- * Returns decoded frame metadata and hex strings for a browser packet inspector.
+ * Returns decoded frame metadata, endpoint/protocol summaries, and hex strings for packet ladder inspectors.
  * @param {string} source
  * @returns {PacketPreview[]}
  */
@@ -50,8 +50,7 @@ export function inspect_fasm(source) {
 }
 
 /**
- * Decompiles an in-memory `.pcap` or `.pcapng` capture (`Uint8Array`) into canonical `.fasm`
- * source code and summary counts (`{ success: true, fasm, packetCount, hostCount }`).
+ * Decompiles an in-memory `.pcap` or `.pcapng` capture (`reversePcap` camelCase alias).
  *
  * # Errors
  * Returns a structured `JsValue` error object (`{ success: false, error, message }`) if
@@ -69,6 +68,26 @@ export function reversePcap(pcap_bytes) {
     return takeFromExternrefTable0(ret[0]);
 }
 
+/**
+ * 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 reverse_pcap(pcap_bytes) {
+    const ptr0 = passArray8ToWasm0(pcap_bytes, wasm.__wbindgen_malloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.reverse_pcap(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
@@ -85,7 +104,7 @@ export function validateFasm(source) {
 }
 
 /**
- * Validates `.fasm` source and returns UTF-16 line/column diagnostics for Monaco/CodeMirror.
+ * Validates `.fasm` source and returns UTF-16 line/column diagnostics for Monaco, CodeMirror, and VS Code.
  * @param {string} source
  * @returns {IdeDiagnostic[]}
  */

package/package.json

@@ -4,8 +4,8 @@
   "collaborators": [
     "Steve Winschel"
   ],
-  "description": "WebAssembly compiler, PCAP/PCAPNG decompiler, packet inspector, and IDE diagnostics for the FrameAssembly (.fasm) network packet synthesis DSL",
-  "version": "1.5.0",
+  "description": "Compile .fasm network traffic code to .pcapng and decompile .pcap/.pcapng packet captures in WebAssembly across 81 L2-L7 protocols with live IDE diagnostics and frame inspection.",
+  "version": "2.0.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -17,16 +17,31 @@
     "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/*"
   ],
   "keywords": [
     "frameassembly",
+    "fasm",
     "pcap",
     "pcapng",
+    "wasm",
+    "webassembly",
     "wireshark",
-    "wasm"
+    "packet-generator",
+    "pcap-decompiler",
+    "pcap-parser",
+    "tcpreplay",
+    "suricata",
+    "zeek",
+    "snmpv3",
+    "firewall-testing",
+    "network-testing",
+    "cybersecurity",
+    "pentesting",
+    "packets-as-code",
+    "modbus"
   ]
 }