Documentation tweaks

Author: kateinoigakukun

Plugins/BridgeJS/README.md

@@ -10,8 +10,8 @@
 
 BridgeJS provides easy interoperability between Swift and JavaScript/TypeScript. It enables:
 
-1. **Export Swift to JavaScript** – Expose Swift functions, classes, and types to JavaScript; the plugin generates TypeScript definitions (`.d.ts`) for the exported API.
-2. **Import JavaScript into Swift** – Make JavaScript/TypeScript APIs callable from Swift with macro-annotated bindings or bindings generated from a TypeScript declaration file (`bridge-js.d.ts`).
+1. **Export Swift to JavaScript** - Expose Swift functions, classes, and types to JavaScript; the plugin generates TypeScript definitions (`.d.ts`) for the exported API.
+2. **Import JavaScript into Swift** - Make JavaScript/TypeScript APIs callable from Swift with macro-annotated bindings or bindings generated from a TypeScript declaration file (`bridge-js.d.ts`).
 
 The workflow is:
 
@@ -174,7 +174,7 @@ For detailed semantics, see the [How It Works sections](https://swiftpackageinde
 `BridgeJSToolInternal` exposes pipeline stages for debugging:
 
 - `emit-skeleton` - Parse Swift files (or `-` for stdin) and print the BridgeJS skeleton as JSON.
-- `emit-swift-thunks` — Read skeleton JSON (from a file or `-` for stdin) and print the generated Swift glue (export and import thunks).
+- `emit-swift-thunks` - Read skeleton JSON (from a file or `-` for stdin) and print the generated Swift glue (export and import thunks).
 - `emit-js` / `emit-dts` - Read skeleton JSON files (or `-` for stdin) and print the .js/.d.ts
 
 Use these to inspect parser output and generated code without running the full generate/link pipeline.

README.md

@@ -48,14 +48,14 @@ _ = document.body.appendChild(button)
 
 BridgeJS provides easy interoperability between Swift and JavaScript/TypeScript. It enables:
 
-- **Export Swift to JavaScript** – Expose Swift functions, classes, and types to JavaScript; the plugin also generates TypeScript definitions (`.d.ts`) for the exported API.
-- **Import JavaScript into Swift** – Make JavaScript/TypeScript APIs (functions, classes, globals like `document` or `console`) callable from Swift with type-safe bindings. You can declare bindings with macros in Swift or generate them from a TypeScript declaration file (`bridge-js.d.ts`).
+- **Export Swift to JavaScript** - Expose Swift functions, classes, and types to JavaScript; the plugin also generates TypeScript definitions (`.d.ts`) for the exported API.
+- **Import JavaScript into Swift** - Make JavaScript/TypeScript APIs (functions, classes, globals like `document` or `console`) callable from Swift with type-safe bindings. You can declare bindings with macros in Swift or generate them from a TypeScript declaration file (`bridge-js.d.ts`).
 
 For architecture details, see the [BridgeJS Plugin README](Plugins/BridgeJS/README.md). For package and build setup, see [Setting up BridgeJS](https://swiftpackageindex.com/swiftwasm/JavaScriptKit/documentation/javascriptkit/setting-up-bridgejs) in the documentation.
 
 ### Exporting Swift to JavaScript
 
-Mark Swift code with `@JS` (the ``JS(namespace:enumStyle:)`` attribute) to make it callable from JavaScript:
+Mark Swift code with `@JS` to make it callable from JavaScript:
 
 ```swift
 import JavaScriptKit

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

@@ -1,10 +1,10 @@
 # Introducing BridgeJS
 
-Faster, easier Swift–JavaScript bridging for WebAssembly.
+Faster, easier Swift-JavaScript bridging for WebAssembly.
 
 ## Overview
 
-**BridgeJS** is a layer underneath JavaScriptKit that makes Swift–JavaScript interop **faster and easier**: you declare the shape of the API in Swift (or in TypeScript, which generates Swift), and the tool generates glue code.
+**BridgeJS** is a layer underneath JavaScriptKit that makes Swift-JavaScript interop **faster and easier**: you declare the shape of the API in Swift (or in TypeScript, which generates Swift), and the tool generates glue code.
 
 Benefits over the dynamic `JSObject` / `JSValue` APIs include:
 

Sources/JavaScriptKit/Documentation.docc/Articles/BridgeJS/Unsupported-Features.md

@@ -0,0 +1,28 @@
+# Unsupported Features in BridgeJS
+
+Limitations and unsupported patterns when using BridgeJS.
+
+## Overview
+
+BridgeJS generates glue code per Swift target (module). Some patterns that are valid in Swift or TypeScript are not supported across the bridge today. This article summarizes the main limitations so you can design your APIs accordingly.
+
+## Type usage crossing module boundary
+
+BridgeJS does **not** support using a type across module boundaries in the following situations.
+
+### Exporting Swift: types from another Swift module
+
+If you have multiple Swift targets (e.g. a library and an app), you **cannot** use a type defined in one target in an exported API of another target.
+
+**Unsupported example:** Module `App` exports a function that takes or returns a type defined in module `Lib`:
+
+```swift
+// In module Lib
+@JS public struct LibPoint {
+    let x: Double
+    let y: Double
+}
+
+// In module App (depends on Lib) - unsupported
+@JS public func transform(_ p: LibPoint) -> LibPoint { ... }
+```

Sources/JavaScriptKit/Documentation.docc/Articles/FAQ.md

@@ -9,7 +9,7 @@ Initialization is asynchronous because the runtime must **fetch and instantiate
 1. **Fetching** the `.wasm` binary (e.g. over the network or from disk).
 2. **Instantiating** it with `WebAssembly.instantiate()` (or `instantiateStreaming()`), which compiles the module and allocates the linear memory and table.
 
-Until that completes, there is no WebAssembly instance to call into, so the entry point that sets up the Swift–JavaScript bridge has to be `async` and must be `await`ed from the JavaScript host (e.g. in your `index.js` or HTML script). This matches the standard WebAssembly JavaScript API, which is promise-based.
+Until that completes, there is no WebAssembly instance to call into, so the entry point that sets up the Swift-JavaScript bridge has to be `async` and must be `await`ed from the JavaScript host (e.g. in your `index.js` or HTML script). This matches the standard WebAssembly JavaScript API, which is promise-based.
 
 ## Why does every imported JavaScript interface via BridgeJS declare `throws(JSException)`?
 
@@ -25,4 +25,4 @@ That can lead to **inconsistent memory state** and **resource leaks**. To avoid
 - You explicitly decide how to react to JavaScript exceptions (e.g. `try`/`catch`, or propagating `throws`).
 - Epilogues and cleanup run in a well-defined way when you handle the error in Swift.
 
-So the “everything throws” rule is there to keep behavior predictable and safe when crossing the Swift–JavaScript boundary.
+So the “everything throws” rule is there to keep behavior predictable and safe when crossing the Swift-JavaScript boundary.

Sources/JavaScriptKit/Documentation.docc/Documentation.md

@@ -72,6 +72,7 @@ Check out the [examples](https://github.com/swiftwasm/JavaScriptKit/tree/main/Ex
 - <doc:Supported-Types>
 - <doc:BridgeJS-Configuration>
 - <doc:Ahead-of-Time-Code-Generation>
+- <doc:Unsupported-Features>
 - <doc:BridgeJS-Internals>
 - ``JS(namespace:enumStyle:)``
 - ``JSFunction(jsName:from:)``