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/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:
 

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

@@ -4,7 +4,7 @@ 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.
 

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

@@ -4,7 +4,7 @@ Learn how to use default parameter values in Swift functions and constructors ex
 
 ## 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 default parameter values for Swift functions and class constructors exported to JavaScript. When you specify default values in your Swift code, they are automatically applied in the generated JavaScript bindings.
 
@@ -64,7 +64,7 @@ Constructor parameters also support default values, making it easy to create ins
     @JS var name: String
     @JS var timeout: Int
     @JS var retries: Int
-    
+
     @JS init(name: String = "default", timeout: Int = 30, retries: Int = 3) {
         self.name = name
         self.timeout = timeout

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

@@ -4,7 +4,7 @@ Learn how to export Swift enums 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/).
 
 BridgeJS supports two output styles for enums, controlled by the `enumStyle` parameter: