BridgeJS: Prepare for MVP release for documentation and relaxing feature gates (#630)

* BridgeJS: Make `@JSClass`, `@JSFunction`, etc generally available without @_spi(Experimental)

* BridgeJS: Remove JAVASCRIPTKIT_EXPERIMENTAL_BRIDGEJS feature gate

* BridgeJS: Update documentation for MVP release

* [skip ci] Update READMEs

Author: kateinoigakukun

Benchmarks/README.md

@@ -7,7 +7,7 @@ This directory contains performance benchmarks for JavaScriptKit.
 Before running the benchmarks, you need to build the test suite:
 
 ```bash
-JAVASCRIPTKIT_EXPERIMENTAL_BRIDGEJS=1 swift package --swift-sdk $SWIFT_SDK_ID js -c release
+swift package --swift-sdk $SWIFT_SDK_ID js -c release
 ```
 
 ## Running Benchmarks

Benchmarks/Sources/Generated/BridgeJS.Macros.swift

@@ -4,7 +4,7 @@
 // To update this file, just rebuild your project or run
 // `swift package bridge-js`.
 
-@_spi(Experimental) @_spi(BridgeJS) import JavaScriptKit
+@_spi(BridgeJS) import JavaScriptKit
 
 @JSFunction func benchmarkHelperNoop() throws(JSException) -> Void
 

Examples/ExportSwift/README.md

@@ -5,7 +5,7 @@ This example demonstrates how to export Swift functions to JavaScript.
 
 1. Build the project:
    ```sh
-   env JAVASCRIPTKIT_EXPERIMENTAL_BRIDGEJS=1 swift package --swift-sdk $SWIFT_SDK_ID js --use-cdn
+   swift package --swift-sdk $SWIFT_SDK_ID js --use-cdn
    ```
 
 2. Serve the files:

Examples/PlayBridgeJS/Sources/PlayBridgeJS/Generated/BridgeJS.Macros.swift

@@ -4,7 +4,7 @@
 // To update this file, just rebuild your project or run
 // `swift package bridge-js`.
 
-@_spi(Experimental) @_spi(BridgeJS) import JavaScriptKit
+@_spi(BridgeJS) import JavaScriptKit
 
 @JSFunction func createTS2Swift() throws(JSException) -> TS2Swift
 

Examples/PlayBridgeJS/build.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
 set -euxo pipefail
-env JAVASCRIPTKIT_EXPERIMENTAL_BRIDGEJS=1 swift package --swift-sdk "${SWIFT_SDK_ID_wasm32_unknown_wasip1:-${SWIFT_SDK_ID:-wasm32-unknown-wasip1}}" \
+swift package --swift-sdk "${SWIFT_SDK_ID_wasm32_unknown_wasip1:-${SWIFT_SDK_ID:-wasm32-unknown-wasip1}}" \
     plugin --allow-writing-to-package-directory \
     js --use-cdn --output ./Bundle -c "${1:-debug}"

Makefile

@@ -16,7 +16,7 @@ unittest:
 		echo "SWIFT_SDK_ID is not set. Run 'swift sdk list' and pass a matching SDK, e.g. 'make unittest SWIFT_SDK_ID=<id>'."; \
 		exit 2; \
 	}
-	env JAVASCRIPTKIT_EXPERIMENTAL_BRIDGEJS=1 swift package --swift-sdk "$(SWIFT_SDK_ID)" \
+	swift package --swift-sdk "$(SWIFT_SDK_ID)" \
 	    $(TRACING_ARGS) \
 	    --disable-sandbox \
 	    js test --prelude ./Tests/prelude.mjs -Xnode --expose-gc

Plugins/BridgeJS/README.md

@@ -1,17 +1,17 @@
 # BridgeJS
 
 > [!IMPORTANT]
-> This feature is still experimental, and the API may change frequently. Use at your own risk with `JAVASCRIPTKIT_EXPERIMENTAL_BRIDGEJS=1` environment variable.
+> This feature is still experimental, and the API may change frequently. Use at your own risk.
 
 > [!NOTE]
-> This documentation is intended for JavaScriptKit developers, not JavaScriptKit users. For user documentation, see [Exporting Swift to JavaScript](https://swiftpackageindex.com/swiftwasm/JavaScriptKit/documentation/javascriptkit/exporting-swift-to-javascript) and [Importing TypeScript into Swift](https://swiftpackageindex.com/swiftwasm/JavaScriptKit/documentation/javascriptkit/importing-typescript-into-swift).
+> This documentation is intended for JavaScriptKit developers, not JavaScriptKit users. For user documentation, see [Introducing BridgeJS](https://swiftpackageindex.com/swiftwasm/JavaScriptKit/documentation/javascriptkit/introducing-bridgejs), [Setting up BridgeJS](https://swiftpackageindex.com/swiftwasm/JavaScriptKit/documentation/javascriptkit/setting-up-bridgejs), [Exporting Swift to JavaScript](https://swiftpackageindex.com/swiftwasm/JavaScriptKit/documentation/javascriptkit/exporting-swift-to-javascript), [Importing JavaScript into Swift](https://swiftpackageindex.com/swiftwasm/JavaScriptKit/documentation/javascriptkit/importing-javascript-into-swift), and [Generating bindings from TypeScript](https://swiftpackageindex.com/swiftwasm/JavaScriptKit/documentation/javascriptkit/generating-from-typescript).
 
 ## Overview
 
 BridgeJS provides easy interoperability between Swift and JavaScript/TypeScript. It enables:
 
-1. **Importing TypeScript APIs into Swift**: Use TypeScript/JavaScript APIs directly from Swift code
-2. **Exporting Swift APIs to JavaScript**: Make your Swift APIs available to JavaScript code
+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:
 
@@ -161,7 +161,7 @@ Return values use direct Wasm returns for primitives, and imported intrinsic fun
 - **Structs/Arrays/Enums**: Copy semantics - data serialized across boundary. No cleanup needed.
 - **Closures**: Boxed on source side, released when GC'd on either side.
 
-For detailed semantics, see the [How It Works sections](https://swiftpackageindex.com/swiftwasm/JavaScriptKit/documentation/javascriptkit/exporting-swift-class#How-It-Works) in the user documentation.
+For detailed semantics, see the [How It Works sections](https://swiftpackageindex.com/swiftwasm/JavaScriptKit/documentation/javascriptkit/exporting-swift-class#how-it-works) in the user documentation.
 
 ## Testing
 

Plugins/BridgeJS/Sources/TS2Swift/JavaScript/src/cli.js

@@ -123,7 +123,7 @@ export function run(filePath, options) {
         "// To update this file, just rebuild your project or run",
         "// `swift package bridge-js`.",
         "",
-        "@_spi(Experimental) @_spi(BridgeJS) import JavaScriptKit",
+        "@_spi(BridgeJS) import JavaScriptKit",
         "",
         "",
     ].join("\n");

Plugins/BridgeJS/Sources/TS2Swift/JavaScript/test/__snapshots__/ts2swift.test.js.snap

@@ -7,7 +7,7 @@ exports[`ts2swift > snapshots Swift output for ArrayParameter.d.ts > ArrayParame
 // To update this file, just rebuild your project or run
 // \`swift package bridge-js\`.
 
-@_spi(Experimental) @_spi(BridgeJS) import JavaScriptKit
+@_spi(BridgeJS) import JavaScriptKit
 
 @JSFunction func processNumbers(_ values: [Double]) throws(JSException) -> Void
 
@@ -30,7 +30,7 @@ exports[`ts2swift > snapshots Swift output for Async.d.ts > Async 1`] = `
 // To update this file, just rebuild your project or run
 // \`swift package bridge-js\`.
 
-@_spi(Experimental) @_spi(BridgeJS) import JavaScriptKit
+@_spi(BridgeJS) import JavaScriptKit
 
 @JSFunction func asyncReturnVoid() throws(JSException) -> JSPromise
 
@@ -55,7 +55,7 @@ exports[`ts2swift > snapshots Swift output for Documentation.d.ts > Documentatio
 // To update this file, just rebuild your project or run
 // \`swift package bridge-js\`.
 
-@_spi(Experimental) @_spi(BridgeJS) import JavaScriptKit
+@_spi(BridgeJS) import JavaScriptKit
 
 /// Return a greeting for a user.
 ///
@@ -112,7 +112,7 @@ exports[`ts2swift > snapshots Swift output for Interface.d.ts > Interface 1`] =
 // To update this file, just rebuild your project or run
 // \`swift package bridge-js\`.
 
-@_spi(Experimental) @_spi(BridgeJS) import JavaScriptKit
+@_spi(BridgeJS) import JavaScriptKit
 
 @JSFunction func returnAnimatable() throws(JSException) -> Animatable
 
@@ -130,7 +130,7 @@ exports[`ts2swift > snapshots Swift output for InvalidPropertyNames.d.ts > Inval
 // To update this file, just rebuild your project or run
 // \`swift package bridge-js\`.
 
-@_spi(Experimental) @_spi(BridgeJS) import JavaScriptKit
+@_spi(BridgeJS) import JavaScriptKit
 
 @JSFunction func createArrayBuffer() throws(JSException) -> ArrayBufferLike
 
@@ -178,7 +178,7 @@ exports[`ts2swift > snapshots Swift output for MultipleImportedTypes.d.ts > Mult
 // To update this file, just rebuild your project or run
 // \`swift package bridge-js\`.
 
-@_spi(Experimental) @_spi(BridgeJS) import JavaScriptKit
+@_spi(BridgeJS) import JavaScriptKit
 
 @JSFunction func createDatabaseConnection(_ config: JSValue) throws(JSException) -> DatabaseConnection
 
@@ -215,7 +215,7 @@ exports[`ts2swift > snapshots Swift output for ObjectLikeTypes.d.ts > ObjectLike
 // To update this file, just rebuild your project or run
 // \`swift package bridge-js\`.
 
-@_spi(Experimental) @_spi(BridgeJS) import JavaScriptKit
+@_spi(BridgeJS) import JavaScriptKit
 
 @JSFunction func acceptObject(_ v: JSObject) throws(JSException) -> Void
 "
@@ -228,7 +228,7 @@ exports[`ts2swift > snapshots Swift output for OptionalNullUndefined.d.ts > Opti
 // To update this file, just rebuild your project or run
 // \`swift package bridge-js\`.
 
-@_spi(Experimental) @_spi(BridgeJS) import JavaScriptKit
+@_spi(BridgeJS) import JavaScriptKit
 
 @JSFunction func roundTripNumberNull(_ value: Optional<Double>) throws(JSException) -> Optional<Double>
 
@@ -269,7 +269,7 @@ exports[`ts2swift > snapshots Swift output for PrimitiveParameters.d.ts > Primit
 // To update this file, just rebuild your project or run
 // \`swift package bridge-js\`.
 
-@_spi(Experimental) @_spi(BridgeJS) import JavaScriptKit
+@_spi(BridgeJS) import JavaScriptKit
 
 @JSFunction func check(_ a: Double, _ b: Bool) throws(JSException) -> Void
 "
@@ -282,7 +282,7 @@ exports[`ts2swift > snapshots Swift output for PrimitiveReturn.d.ts > PrimitiveR
 // To update this file, just rebuild your project or run
 // \`swift package bridge-js\`.
 
-@_spi(Experimental) @_spi(BridgeJS) import JavaScriptKit
+@_spi(BridgeJS) import JavaScriptKit
 
 @JSFunction func checkNumber() throws(JSException) -> Double
 
@@ -297,7 +297,7 @@ exports[`ts2swift > snapshots Swift output for ReExportFrom.d.ts > ReExportFrom
 // To update this file, just rebuild your project or run
 // \`swift package bridge-js\`.
 
-@_spi(Experimental) @_spi(BridgeJS) import JavaScriptKit
+@_spi(BridgeJS) import JavaScriptKit
 
 @JSFunction func jsRoundTripNumber(_ v: Double) throws(JSException) -> Double
 
@@ -315,7 +315,7 @@ exports[`ts2swift > snapshots Swift output for RecordDictionary.d.ts > RecordDic
 // To update this file, just rebuild your project or run
 // \`swift package bridge-js\`.
 
-@_spi(Experimental) @_spi(BridgeJS) import JavaScriptKit
+@_spi(BridgeJS) import JavaScriptKit
 
 @JSFunction func takeRecord(_ value: [String: Double]) throws(JSException) -> Void
 
@@ -345,7 +345,7 @@ exports[`ts2swift > snapshots Swift output for StringEnum.d.ts > StringEnum 1`]
 // To update this file, just rebuild your project or run
 // \`swift package bridge-js\`.
 
-@_spi(Experimental) @_spi(BridgeJS) import JavaScriptKit
+@_spi(BridgeJS) import JavaScriptKit
 
 enum FeatureFlag: String {
     case foo = "foo"
@@ -366,7 +366,7 @@ exports[`ts2swift > snapshots Swift output for StringParameter.d.ts > StringPara
 // To update this file, just rebuild your project or run
 // \`swift package bridge-js\`.
 
-@_spi(Experimental) @_spi(BridgeJS) import JavaScriptKit
+@_spi(BridgeJS) import JavaScriptKit
 
 @JSFunction func checkString(_ a: String) throws(JSException) -> Void
 
@@ -381,7 +381,7 @@ exports[`ts2swift > snapshots Swift output for StringReturn.d.ts > StringReturn
 // To update this file, just rebuild your project or run
 // \`swift package bridge-js\`.
 
-@_spi(Experimental) @_spi(BridgeJS) import JavaScriptKit
+@_spi(BridgeJS) import JavaScriptKit
 
 @JSFunction func checkString() throws(JSException) -> String
 "
@@ -394,7 +394,7 @@ exports[`ts2swift > snapshots Swift output for TS2SkeletonLike.d.ts > TS2Skeleto
 // To update this file, just rebuild your project or run
 // \`swift package bridge-js\`.
 
-@_spi(Experimental) @_spi(BridgeJS) import JavaScriptKit
+@_spi(BridgeJS) import JavaScriptKit
 
 @JSFunction func createTS2Skeleton() throws(JSException) -> TypeScriptProcessor
 
@@ -420,7 +420,7 @@ exports[`ts2swift > snapshots Swift output for TypeAlias.d.ts > TypeAlias 1`] =
 // To update this file, just rebuild your project or run
 // \`swift package bridge-js\`.
 
-@_spi(Experimental) @_spi(BridgeJS) import JavaScriptKit
+@_spi(BridgeJS) import JavaScriptKit
 
 @JSFunction func checkSimple(_ a: Double) throws(JSException) -> Void
 "
@@ -433,7 +433,7 @@ exports[`ts2swift > snapshots Swift output for TypeAliasObject.d.ts > TypeAliasO
 // To update this file, just rebuild your project or run
 // \`swift package bridge-js\`.
 
-@_spi(Experimental) @_spi(BridgeJS) import JavaScriptKit
+@_spi(BridgeJS) import JavaScriptKit
 
 @JSFunction func console() throws(JSException) -> Console
 
@@ -452,7 +452,7 @@ exports[`ts2swift > snapshots Swift output for TypeScriptClass.d.ts > TypeScript
 // To update this file, just rebuild your project or run
 // \`swift package bridge-js\`.
 
-@_spi(Experimental) @_spi(BridgeJS) import JavaScriptKit
+@_spi(BridgeJS) import JavaScriptKit
 
 @JSClass struct Greeter {
     @JSGetter var name: String
@@ -473,7 +473,7 @@ exports[`ts2swift > snapshots Swift output for VoidParameterVoidReturn.d.ts > Vo
 // To update this file, just rebuild your project or run
 // \`swift package bridge-js\`.
 
-@_spi(Experimental) @_spi(BridgeJS) import JavaScriptKit
+@_spi(BridgeJS) import JavaScriptKit
 
 @JSFunction func check() throws(JSException) -> Void
 "
@@ -486,7 +486,7 @@ exports[`ts2swift > snapshots Swift output for WebIDLDOMDocs.d.ts > WebIDLDOMDoc
 // To update this file, just rebuild your project or run
 // \`swift package bridge-js\`.
 
-@_spi(Experimental) @_spi(BridgeJS) import JavaScriptKit
+@_spi(BridgeJS) import JavaScriptKit
 
 /// [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document)
 @JSGetter var document: Document

Plugins/PackageToJS/Sources/PackageToJS.swift

@@ -589,11 +589,6 @@ struct PackagingPlanner {
         packageInputs.append(packageJsonTask)
 
         if skeletons.count > 0 {
-            if ProcessInfo.processInfo.environment["JAVASCRIPTKIT_EXPERIMENTAL_BRIDGEJS"] == nil {
-                fatalError(
-                    "BridgeJS is still an experimental feature. Set the environment variable JAVASCRIPTKIT_EXPERIMENTAL_BRIDGEJS=1 to enable."
-                )
-            }
             let bridgeJs = outputDir.appending(path: "bridge-js.js")
             let bridgeDts = outputDir.appending(path: "bridge-js.d.ts")
             packageInputs.append(