BridgeJS: Update documentation for MVP release

Author: kateinoigakukun

Sources/JavaScriptKit/Documentation.docc/Articles/BridgeJS/Ahead-of-Time-Code-Generation.md

@@ -6,7 +6,7 @@ Learn how to improve build times by generating BridgeJS code ahead of time.
 
 > Important: This feature is still experimental. No API stability is guaranteed, and the API may change in future releases.
 
-The BridgeJS build plugin automatically processes `@JS` annotations and TypeScript definitions during each build. While convenient, this can significantly increase build times for larger projects. To address this, JavaScriptKit provides a command plugin that lets you generate the bridge code ahead of time.
+The BridgeJS build plugin automatically processes macro annotations and TypeScript definitions during each build. While convenient, this can significantly increase build times for larger projects. To address this, JavaScriptKit provides a command plugin that lets you generate the bridge code ahead of time.
 
 ## Using the Command Plugin
 
@@ -54,7 +54,7 @@ $ echo "{}" > Sources/MyApp/bridge-js.config.json
 
 ### Step 3: Create Your Swift Code with @JS Annotations
 
-Write your Swift code with `@JS` annotations as usual:
+Write your Swift code with macro annotations as usual:
 
 ```swift
 import JavaScriptKit
@@ -65,13 +65,13 @@ import JavaScriptKit
 
 @JS class Counter {
     private var count = 0
-    
+
     @JS init() {}
-    
+
     @JS func increment() {
         count += 1
     }
-    
+
     @JS func getValue() -> Int {
         return count
     }
@@ -104,14 +104,15 @@ swift package plugin bridge-js
 
 This command will:
 
-1. Process all Swift files with `@JS` annotations
+1. Process all Swift files with macro annotations
 2. Process any TypeScript definition files
 3. Generate Swift binding code in a `Generated` directory within your source folder
 
 For example, with a target named "MyApp", it will create:
 
 ```
-Sources/MyApp/Generated/BridgeJS.swift     # Generated code for both exports and imports
+Sources/MyApp/Generated/BridgeJS.swift            # Glue code for both exports and imports
+Sources/MyApp/Generated/BridgeJS.Macros.swift     # Bridging interface generated from bridge-js.d.ts
 Sources/MyApp/Generated/JavaScript/BridgeJS.json  # Unified skeleton JSON
 ```
 
@@ -173,4 +174,4 @@ git commit -m "Update generated BridgeJS code"
 2. **Version Control**: Always commit the generated files if using the command plugin
 3. **API Boundaries**: Try to stabilize your API boundaries to minimize regeneration
 4. **Documentation**: Document your approach in your project README
-5. **CI/CD**: If using the command plugin, consider verifying that generated code is up-to-date in CI 
+5. **CI/CD**: If using the command plugin, consider verifying that generated code is up-to-date in CI

Sources/JavaScriptKit/Documentation.docc/Articles/BridgeJS/BridgeJS-Configuration.md

@@ -42,7 +42,7 @@ Later files override settings from earlier files. This allows teams to commit a
 
 Controls whether exported Swift APIs are exposed to the JavaScript global namespace (`globalThis`).
 
-When `true`, exported functions, classes, and namespaces are available via `globalThis` in JavaScript. When `false`, they are only available through the exports object returned by `createExports()`. 
+When `true`, exported functions, classes, and namespaces are available via `globalThis` in JavaScript. When `false`, they are only available through the exports object returned by `createExports()`.
 Using Exports provides better module isolation and support multiple WebAssembly instances in the same JavaScript context.
 
 Example:

Sources/JavaScriptKit/Documentation.docc/Articles/BridgeJS/BridgeJS-Internals/BridgeJS-Internals.md

@@ -0,0 +1,11 @@
+# BridgeJS Internals
+
+Internal design, performance rationale, and low-level details for BridgeJS.
+
+## Overview
+
+This section is for maintainers and contributors who want to understand how BridgeJS works under the hood, why it is designed the way it is, and how it interacts with the JavaScript engine and ABI.
+
+## Topics
+
+- <doc:Design-Rationale>

Sources/JavaScriptKit/Documentation.docc/Articles/BridgeJS/BridgeJS-Internals/Design-Rationale.md

@@ -0,0 +1,38 @@
+# BridgeJS Design Rationale
+
+Why BridgeJS is faster than dynamic `JSObject`/`JSValue` APIs and how engine optimizations influence the design.
+
+## Overview
+
+BridgeJS generates **specialized** bridge code per exported or imported interface. That specialization, combined with stable call and property access patterns, allows JavaScript engines to optimize the boundary crossing much better than with generic dynamic code. This page explains the main performance rationale.
+
+## Why generated code is faster
+
+1. **Specialized code per interface** - Each bridged function or property gets its own glue path with known types. The engine does not need to handle arbitrary shapes or types at the call site.
+
+2. **Use of static type information** - The generator knows parameter and return types at compile time. It can avoid dynamic type checks and boxing where the dynamic API would require them.
+
+3. **IC-friendly access patterns** - Property and method accesses use stable, predictable shapes instead of a single generic subscript path. That keeps engine **inline caches (ICs)** effective instead of turning them **megamorphic**.
+
+## Inline caches (ICs) and megamorphic penalty
+
+JavaScript engines (and many other dynamic-language VMs) use **inline caches** at property and method access sites: they remember the object shape (e.g. “this property is at offset X”) so the next access with the same shape can take a fast path.
+
+- **Monomorphic** - One shape seen at a site → very fast, offset cached.
+- **Polymorphic** - A few shapes → still fast, small dispatch in the IC.
+- **Megamorphic** - Too many different shapes at the same site → the IC gives up and falls back to a generic property lookup, which is much slower.
+
+Engines typically allow only a small number of shapes per IC (e.g. on the order of a few) before marking the site megamorphic.
+
+## Why `JSObject` subscript is problematic
+
+`JSObject.subscript` (and similar dynamic property access) shares **one** code path for all property names and all object shapes. Every access goes through the same call site with varying keys and receiver shapes. That site therefore sees many different shapes and quickly becomes **megamorphic**, so the engine cannot cache property offsets and must do a generic lookup every time.
+
+So even if you cache the property name (e.g. with `CachedJSStrings`), you are still using the same generic subscript path; the call site stays megamorphic and pays the slow-path cost.
+
+BridgeJS avoids this by generating **separate** access paths per property or method. Each generated getter/setter or function call has a stable shape at the engine level, so the IC can stay monomorphic or polymorphic and the fast path is used.
+
+## What to read next
+
+- ABI and binary interface details will be documented in this section as they stabilize.
+- For using BridgeJS in your app, see <doc:Introducing-BridgeJS>, <doc:Importing-JavaScript-into-Swift>, and <doc:Exporting-Swift-to-JavaScript>.

Sources/JavaScriptKit/Documentation.docc/Articles/BridgeJS/Bringing-Swift-Closures-to-JavaScript.md

@@ -0,0 +1,80 @@
+# Bringing Swift Closures to JavaScript
+
+Use ``JSTypedClosure`` to pass or return Swift closures to the JavaScript world with BridgeJS-with type safety and explicit lifetime management.
+
+## Overview
+
+``JSTypedClosure`` wraps a **Swift closure** so you can **pass it or return it to JavaScript** through BridgeJS. The closure lives in Swift; JavaScript receives a function that calls back into that closure when invoked. Use it when:
+
+- You **pass** a Swift closure as an argument to a JavaScript API (e.g. an ``JSFunction(jsName:from:)`` that takes a callback parameter).
+- You **return** a Swift closure from Swift exported by ``JS(namespace:enumStyle:)`` so JavaScript can call it later.
+
+Unlike ``JSClosure``, which uses untyped ``JSValue`` arguments and return values, ``JSTypedClosure`` has a concrete **signature** (e.g. `(Int) -> Int` or `(String) -> Void`). BridgeJS generates the glue code for that signature, so you get compile-time type safety when crossing into the JS world.
+
+You **must call** ``JSTypedClosure/release()`` when the closure is no longer needed by JavaScript. After release, any attempt to invoke the closure from JavaScript throws an explicit JS exception.
+
+## Creating a JSTypedClosure
+
+BridgeJS generates an initializer for each closure signature used in your module. Wrap your Swift closure and pass or return it to JavaScript:
+
+```swift
+import JavaScriptKit
+
+// Pass a Swift closure to a JS function that expects a callback (Int) -> Int
+@JSFunction static func applyTransform(_ value: Int, _ transform: JSTypedClosure<(Int) -> Int>) throws(JSException) -> Int
+
+let double = JSTypedClosure<(Int) -> Int> { $0 * 2 }
+defer { double.release() }
+let result = try applyTransform(10, double)  // 20 - JS calls back into Swift
+```
+
+You can pass or return typed closures with other signatures the same way:
+
+```swift
+let sum = JSTypedClosure<(Int, Int) -> Int> { $0 + $1 }
+defer { sum.release() }
+
+let log = JSTypedClosure<(String) -> Void> { print($0) }
+defer { log.release() }
+```
+
+## Lifetime and release()
+
+A ``JSTypedClosure`` keeps the Swift closure alive and exposes a JavaScript function that calls into it. To avoid leaks and use-after-free:
+
+1. **Call `release()` exactly once** when the closure is no longer needed by JavaScript (e.g. when the callback is unregistered or the object that held it is released).
+2. Prefer **`defer { closure.release() }`** right after creating the closure so cleanup runs when the current scope exits.
+3. After `release()`, calling the closure from JavaScript throws an exception with a message that includes the file and line where the ``JSTypedClosure`` was created.
+
+A **FinalizationRegistry** on the JavaScript side may eventually release the Swift storage if you never call `release()`, but that is non-deterministic. Do not rely on it for timely cleanup.
+
+## Getting the underlying JavaScript function
+
+When you need to store or pass the function on the JavaScript side (e.g. to compare identity or attach to a DOM node), use the ``JSTypedClosure/jsObject`` property to get the ``JSObject`` that represents the JavaScript function.
+
+## JSTypedClosure vs JSClosure
+
+Both let you pass or return a Swift closure to the JavaScript world. The difference is how they are typed and which API you use:
+
+| | JSTypedClosure | JSClosure |
+|:--|:--|:--|
+| **API** | BridgeJS (macros, generated code) | Dynamic ``JSObject`` / ``JSValue`` |
+| **Types** | Typed signature, e.g. `(Int) -> Int` | Untyped `([JSValue]) -> JSValue` |
+| **Lifetime** | Explicit `release()` required | Explicit `release()` required |
+| **Use case** | Passing/returning closures at the BridgeJS boundary with a fixed signature | Passing Swift functions to JS via dynamic APIs (e.g. DOM events) |
+
+Use ``JSTypedClosure`` when you pass or return closures through BridgeJS-declared APIs. Use ``JSClosure`` when you pass a Swift function to JavaScript using the dynamic APIs (e.g. ``JSObject``, ``JSValue``) without generated glue.
+
+## JSTypedClosure vs auto-managed closures
+
+BridgeJS can also expose **plain** Swift closure types (e.g. `(String) -> String`) as parameters and return values; lifetime is then managed automatically via ``FinalizationRegistry`` and no `release()` is required. See <doc:Exporting-Swift-Closure>.
+
+**When returning** a closure from Swift to JavaScript, we **recommend** using ``JSTypedClosure`` and managing lifetime explicitly with `release()`, rather than returning a plain closure type. Explicit release makes cleanup predictable and avoids relying solely on JavaScript GC.
+
+## See also
+
+- ``JSTypedClosure``
+- ``JSClosure``
+- <doc:Exporting-Swift-Closure>
+- <doc:Importing-JavaScript-into-Swift>
+- <doc:Supported-Types>

Sources/JavaScriptKit/Documentation.docc/Articles/BridgeJS/Exporting-Swift-to-JavaScript.md

@@ -6,60 +6,11 @@ Learn how to make your Swift code callable from JavaScript.
 
 > Important: This feature is still experimental. No API stability is guaranteed, and the API may change in future releases.
 
-> Tip: You can quickly preview what interfaces will be exposed on the Swift/TypeScript sides using the [BridgeJS Playground](https://swiftwasm.org/JavaScriptKit/PlayBridgeJS/).
-
-BridgeJS allows you to expose Swift functions, classes, and methods to JavaScript by using the `@JS` attribute. This enables JavaScript code to call into Swift code running in WebAssembly.
-
-## Configuring the BridgeJS plugin
-
-To use the BridgeJS feature, you need to enable the experimental `Extern` feature and add the BridgeJS plugin to your package. Here's an example of a `Package.swift` file:
-
-```swift
-// swift-tools-version:6.0
-
-import PackageDescription
-
-let package = Package(
-    name: "MyApp",
-    dependencies: [
-        .package(url: "https://github.com/swiftwasm/JavaScriptKit.git", branch: "main")
-    ],
-    targets: [
-        .executableTarget(
-            name: "MyApp",
-            dependencies: ["JavaScriptKit"],
-            swiftSettings: [
-                // This is required because the generated code depends on @_extern(wasm)
-                .enableExperimentalFeature("Extern")
-            ],
-            plugins: [
-                // Add build plugin for processing @JS and generate Swift glue code
-                .plugin(name: "BridgeJS", package: "JavaScriptKit")
-            ]
-        )
-    ]
-)
-```
-
-The `BridgeJS` plugin will process your Swift code to find declarations marked with `@JS` and generate the necessary bridge code to make them accessible from JavaScript.
-
-### Building your package for JavaScript
-
-After configuring your `Package.swift`, you can build your package for JavaScript using the following command:
-
-```bash
-swift package --swift-sdk $SWIFT_SDK_ID js
-```
-
-This command will:
-
-1. Process all Swift files with `@JS` annotations
-2. Generate JavaScript bindings and TypeScript type definitions (`.d.ts`) for your exported Swift code
-3. Output everything to the `.build/plugins/PackageToJS/outputs/` directory
-
-> Note: For larger projects, you may want to generate the BridgeJS code ahead of time to improve build performance. See <doc:Ahead-of-Time-Code-Generation> for more information.
+> Tip: You can quickly preview what interfaces will be exposed on the Swift/JavaScript/TypeScript sides using the [BridgeJS Playground](https://swiftwasm.org/JavaScriptKit/PlayBridgeJS/).
 
+BridgeJS allows you to expose Swift functions, classes, and methods to JavaScript by using the ``JS(namespace:enumStyle:)`` attribute. This enables JavaScript code to call into Swift code running in WebAssembly.
 
+Configure your package and build for JavaScript as described in <doc:Setting-up-BridgeJS>. Then use the topics below to expose Swift types and functions to JavaScript.
 
 ## Topics
 
@@ -75,3 +26,7 @@ This command will:
 - <doc:Exporting-Swift-Static-Functions>
 - <doc:Exporting-Swift-Static-Properties>
 - <doc:Using-Namespace>
+
+## See Also
+
+- ``JS(namespace:enumStyle:)``

Sources/JavaScriptKit/Documentation.docc/Articles/BridgeJS/Exporting-Swift/Exporting-Swift-Array.md

@@ -4,7 +4,7 @@ Learn how to pass Swift arrays to and from JavaScript.
 
 ## Overview
 
-> Tip: You can quickly preview what interfaces will be exposed on the Swift/TypeScript sides using the [BridgeJS Playground](https://swiftwasm.org/JavaScriptKit/PlayBridgeJS/).
+> Tip: You can quickly preview what interfaces will be exposed on the Swift/JavaScript/TypeScript sides using the [BridgeJS Playground](https://swiftwasm.org/JavaScriptKit/PlayBridgeJS/).
 
 BridgeJS allows you to pass Swift arrays as function parameters and return values.
 

Sources/JavaScriptKit/Documentation.docc/Articles/BridgeJS/Exporting-Swift/Exporting-Swift-Class.md

@@ -4,7 +4,7 @@ Learn how to export Swift classes to JavaScript.
 
 ## Overview
 
-> Tip: You can quickly preview what interfaces will be exposed on the Swift/TypeScript sides using the [BridgeJS Playground](https://swiftwasm.org/JavaScriptKit/PlayBridgeJS/).
+> Tip: You can quickly preview what interfaces will be exposed on the Swift/JavaScript/TypeScript sides using the [BridgeJS Playground](https://swiftwasm.org/JavaScriptKit/PlayBridgeJS/).
 
 To export a Swift class, mark both the class and any members you want to expose:
 
@@ -51,6 +51,7 @@ cart.addItem("Laptop", 999.99, 1);
 cart.addItem("Mouse", 24.99, 2);
 console.log(`Items in cart: ${cart.getItemCount()}`);
 console.log(`Total: $${cart.getTotal().toFixed(2)}`);
+cart.release(); // Call release() when done; don't rely on FinalizationRegistry as much as possible
 ```
 
 The generated TypeScript declarations for this class would look like:
@@ -83,7 +84,7 @@ Classes use **reference semantics** when crossing the Swift/JavaScript boundary:
 1. **Object Creation**: When you create a class instance (via `new` in JS), the object lives on the Swift heap
 2. **Reference Passing**: JavaScript receives a reference (handle) to the Swift object, not a copy
 3. **Shared State**: Changes made through either Swift or JavaScript affect the same object
-4. **Memory Management**: `FinalizationRegistry` automatically releases Swift objects when they're garbage collected in JavaScript. You can optionally call `release()` for deterministic cleanup.
+4. **Memory Management**: `FinalizationRegistry` can release Swift objects when they're garbage collected in JavaScript, but you should **not rely on it** for cleanup. Call `release()` when an instance is no longer needed so that Swift memory is reclaimed deterministically. This is especially important for **short-lived instances**: GC may run late or not at all for objects that become unreachable quickly, so relying on `FinalizationRegistry` can delay or leak Swift-side resources.
 
 This differs from structs, which use copy semantics and transfer data by value.
 

Sources/JavaScriptKit/Documentation.docc/Articles/BridgeJS/Exporting-Swift/Exporting-Swift-Closure.md

@@ -4,9 +4,11 @@ Learn how to use closure/function types as parameters and return values in Bridg
 
 ## Overview
 
-> Tip: You can quickly preview what interfaces will be exposed on the Swift/TypeScript sides using the [BridgeJS Playground](https://swiftwasm.org/JavaScriptKit/PlayBridgeJS/).
+> Tip: You can quickly preview what interfaces will be exposed on the Swift/JavaScript/TypeScript sides using the [BridgeJS Playground](https://swiftwasm.org/JavaScriptKit/PlayBridgeJS/).
 
-BridgeJS supports typed closure parameters and return values, allowing you to pass functions between Swift and JavaScript with full type safety. This enables functional programming patterns like callbacks, higher-order functions, and function composition across the language boundary.
+BridgeJS supports typed closure parameters and return values, allowing you to pass or return Swift closures to JavaScript with full type safety. **Lifetime is automatic**: you use plain Swift closure types (e.g. `(String) -> String`); the runtime releases them when no longer needed-no manual `release()` required. This enables callbacks, higher-order functions, and function composition across the boundary.
+
+**Recommendation:** When **returning** a closure from Swift to JavaScript, prefer returning a ``JSTypedClosure`` and managing its lifetime explicitly (see <doc:Bringing-Swift-Closures-to-JavaScript>). Explicit `release()` makes cleanup predictable and avoids relying solely on JavaScript garbage collection. Use plain closure types (this article) when you want fully automatic lifetime or when passing closures only as parameters into your exported API.
 
 ## Example
 
@@ -99,6 +101,8 @@ Closures use **reference semantics** when crossing the Swift/JavaScript boundary
 
 This differs from structs and arrays, which use copy semantics and transfer data by value.
 
+When you **return** a closure to JavaScript, we recommend using ``JSTypedClosure`` and calling `release()` when the closure is no longer needed, instead of returning a plain closure type. See <doc:Bringing-Swift-Closures-to-JavaScript>.
+
 ## Supported Features
 
 | Swift Feature | Status |
@@ -113,4 +117,5 @@ This differs from structs and arrays, which use copy semantics and transfer data
 
 ## See Also
 
+- <doc:Bringing-Swift-Closures-to-JavaScript> - passing or returning closures with ``JSTypedClosure`` and explicit `release()`
 - <doc:Supported-Types>