feat(ios): ship the xcframeworks through SwiftPM instead of npm

.github/workflows/build-native.yml

@@ -3,11 +3,11 @@
 #   artifact name          contents                              destination in the repo
 #   ---------------------  ------------------------------------  ---------------------------------------------
 #   canvas-android         canvas-release.aar                    packages/canvas/platforms/android/
-#   canvas-ios             CanvasNative.xcframework (tar.gz)     packages/canvas/platforms/ios/
+#   canvas-ios             CanvasNative.xcframework (tar.gz)     packages/canvas/platforms/ios/CanvasNativeBinary/
 #   canvas-svg-android     canvassvg-release.aar                 packages/canvas-svg/platforms/android/
-#   canvas-svg-ios         CanvasSVG.xcframework (tar.gz)        packages/canvas-svg/platforms/ios/
+#   canvas-svg-ios         CanvasSVG.xcframework (tar.gz)        packages/canvas-svg/platforms/ios/CanvasSVGBinary/
 #   audio-context-android  audiocontext-release.aar              packages/audio-context/platforms/android/
-#   audio-context-ios      AudioContextNative.xcframework        packages/audio-context/platforms/ios/
+#   audio-context-ios      AudioContextNative.xcframework        packages/audio-context/platforms/ios/AudioContextNativeBinary/
 #                          (tar.gz)
 #   canvas-windows-<arch>  canvasnative.node + ANGLE DLLs        packages/canvas/platforms/windows/<arch>/
 #   <module>-windows-      canvassvg.node, audiocontext.node,    packages/<module>/platforms/windows/<arch>/
@@ -113,7 +113,7 @@ jobs:
         working-directory: tools/scripts
         run: sh canvas-build.sh
       - name: Pack xcframework
-        run: tar -czf canvas-ios.tar.gz -C packages/canvas/platforms/ios CanvasNative.xcframework
+        run: tar -czf canvas-ios.tar.gz -C packages/canvas/platforms/ios/CanvasNativeBinary CanvasNative.xcframework
       - uses: ./.github/actions/skia-cache
         with:
           name: canvas-ios
@@ -199,7 +199,7 @@ jobs:
         run: sh canvas-svg-build.sh
       - name: Pack xcframework
         if: steps.svg-xcframework.outputs.cache-hit != 'true'
-        run: tar -czf canvas-svg-ios.tar.gz -C packages/canvas-svg/platforms/ios CanvasSVG.xcframework
+        run: tar -czf canvas-svg-ios.tar.gz -C packages/canvas-svg/platforms/ios/CanvasSVGBinary CanvasSVG.xcframework
       - uses: ./.github/actions/skia-cache
         if: steps.svg-xcframework.outputs.cache-hit != 'true'
         with:
@@ -285,7 +285,7 @@ jobs:
         run: sh audio-context-build.sh
       - name: Pack xcframework
         if: steps.audio-xcframework.outputs.cache-hit != 'true'
-        run: tar -czf audio-context-ios.tar.gz -C packages/audio-context/platforms/ios AudioContextNative.xcframework
+        run: tar -czf audio-context-ios.tar.gz -C packages/audio-context/platforms/ios/AudioContextNativeBinary AudioContextNative.xcframework
       - uses: actions/upload-artifact@v4
         with:
           name: audio-context-ios

.github/workflows/npm_release.yml

@@ -5,26 +5,25 @@
 # (or pick the tag under "Use workflow from"). The tag must match packages/canvas/package.json.
 #
 # Every native artifact build-native.yml produces (Android AARs, iOS/visionOS/tvOS
-# xcframeworks, Windows and Linux Node-API modules) is built from the tag and replaces the
-# committed copy before packaging, so npm ships what CI built from the tagged sources.
-# The committed binaries are only what local development uses. canvas-polyfill's
-# async-release.aar is the one native artifact that still ships as committed.
+# xcframeworks, Windows and Linux Node-API modules) is built from the tag and placed before
+# packaging, replacing any committed copy, so npm ships what CI built from the tagged
+# sources. The committed binaries are only what local development uses; the xcframeworks
+# are not committed at all. canvas-polyfill's async-release.aar is the one native artifact
+# that still ships as committed.
 #
 # Running on the tag also keeps the build's caches safe: a run can restore master's cache
 # entries but saves only into its own ref's scope, so nothing a release executes can
 # replace an entry that master's builds restore.
 #
-# iOS SwiftPM distribution: canvas and audio-context each ship the header-only
-# NativeScriptV8 SwiftPM shim (repo-root nativescript-v8/) INSIDE the npm
-# package at platforms/ios/NativeScriptV8, referenced by their
-# nativescript.config.ts as a local `path` package. Unlike font-manager, there
-# is no GitHub-release binaryTarget to stamp: SwiftPM clones a repository's
-# entire git history just to read Package.swift, and this repo's history is
-# several GB — so ANY repositoryURL reference (source or binary target) stalls
-# first builds for 20+ minutes. The shim is tiny (V8 headers + empty stub) and
-# the heavy CanvasNative.xcframework already ships in the npm package, so
-# nothing needs a release asset. The verify step below guards that the shim
-# actually made it into the built packages.
+# iOS SwiftPM distribution: canvas, canvas-svg and audio-context reference two local
+# `path` SwiftPM packages shipped inside the npm package (see their nativescript.config.ts):
+#   * platforms/ios/NativeScriptV8: the header-only V8 shim (repo-root nativescript-v8/).
+#   * platforms/ios/<Framework>Binary: a binaryTarget for the plugin's xcframework. The
+#     frameworks are too large for npm, so tools/scripts/release-ios-binaries.sh uploads
+#     them to the GitHub release for the tag and stamps the zip's url + checksum into
+#     Package.swift. SwiftPM then downloads just the zip.
+# Never a repositoryURL: SwiftPM clones a repository's entire git history just to read
+# Package.swift, and this repo's history is several GB, so first builds stall for 20+ min.
 #
 # Authentication uses npm Trusted Publishing (OIDC) — no NPM_TOKEN required.
 # This mirrors the proven publish flow in the @nativescript/ios and
@@ -91,7 +90,7 @@ jobs:
     if: ${{ !cancelled() && needs.version.result == 'success' && contains(fromJSON('["success","skipped"]'), needs.build-native.result) }}
     environment: npm-publish # must match the npm Trusted Publisher environment
     permissions:
-      contents: read
+      contents: write # upload the iOS xcframeworks to the GitHub release
       actions: read # download artifacts from native_run_id
       id-token: write # required for npm Trusted Publishing (OIDC) + provenance
     env:
@@ -145,7 +144,7 @@ jobs:
       - name: Verify iOS SwiftPM shim in built packages
         run: |
           set -euo pipefail
-          for pkg in canvas audio-context; do
+          for pkg in canvas canvas-svg audio-context; do
             dir="dist/packages/$pkg/platforms/ios/NativeScriptV8"
             # Check real files, not just the directories: Headers/ also holds
             # the committed inspector/ + libffi trees, so an `-e Headers` test
@@ -177,11 +176,11 @@ jobs:
           set -euo pipefail
           for f in \
             canvas/platforms/android/canvas-release.aar \
-            canvas/platforms/ios/CanvasNative.xcframework/Info.plist \
+            canvas/platforms/ios/CanvasNativeBinary/CanvasNative.xcframework/Info.plist \
             canvas-svg/platforms/android/canvassvg-release.aar \
-            canvas-svg/platforms/ios/CanvasSVG.xcframework/Info.plist \
+            canvas-svg/platforms/ios/CanvasSVGBinary/CanvasSVG.xcframework/Info.plist \
             audio-context/platforms/android/audiocontext-release.aar \
-            audio-context/platforms/ios/AudioContextNative.xcframework/Info.plist; do
+            audio-context/platforms/ios/AudioContextNativeBinary/AudioContextNative.xcframework/Info.plist; do
             [ -f "dist/packages/$f" ] || { echo "error: dist/packages/$f missing" >&2; exit 1; }
           done
           for arch in x64 arm64; do
@@ -195,6 +194,12 @@ jobs:
           done
           echo "ok: every package ships its native artifacts"
 
+      # Before publishing, so a published package never points at a missing asset.
+      - name: Move iOS xcframeworks to the GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: ./tools/scripts/release-ios-binaries.sh "${{ needs.version.outputs.version }}"
+
       # Publish each package at its committed version via OIDC. The setup-node
       # .npmrc and NODE_AUTH_TOKEN are cleared so npm performs the Trusted
       # Publishing token exchange (per package) and generates provenance.

.gitignore

@@ -93,3 +93,10 @@ tools/linux/*.tgz
 
 # The NativeScript CLI builds a plugin's <plugin>.aar from its platforms/android sources at app build time
 packages/*/platforms/android/canvas_*.aar
+
+# iOS native build output (xcframeworks + per-platform slices). Not committed; see the README's
+# "iOS native frameworks" section.
+/packages/canvas/src-native/canvas-ios/dist/
+/packages/canvas-svg/src-native/ios/dist/
+/packages/audio-context/src-native/ios/dist/
+/packages/audio-context/src-native/ios/AudioContextNative/dist/

README.md

@@ -30,6 +30,24 @@ If building only `localize`, type: `npm start` > `localize` (this will narrow do
 
 In general, when in doubt with what to do, just `npm start`.
 
+## iOS native frameworks
+
+The plugins' iOS frameworks (`CanvasNative`, `CanvasSVG`, `AudioContextNative`) are not committed. Each plugin references its framework through a local SwiftPM package at `packages/<plugin>/platforms/ios/<Framework>Binary`, so after cloning, put the frameworks there before building an iOS app:
+
+```bash
+# prebuilt, from the latest GitHub release (or pass a tag: npm run download.ios.frameworks -- 3.0.6)
+npm run download.ios.frameworks
+
+# or build them from source, when working on the native code
+npm run build.canvas.ios.framework.release
+npm run build.canvas.svg.ios.framework.release
+npm run build.audiocontext.ios.framework.release
+```
+
+A downloaded framework matches its release, not necessarily the plugin sources on your branch. If the app fails to link or crashes on a missing native method, build the framework from source.
+
+Published packages do not include the frameworks either: the npm Release workflow uploads them to the GitHub release for the tag, and SwiftPM downloads them on the app's first build.
+
 ## How to add a new package to workspace?
 
 ```bash

package.json

@@ -21,7 +21,8 @@
 		"build.canvas.ios.framework.debug": "nx run canvas:build.native.ios.framework.debug",
 		"build.canvas.svg.ios.framework.release": "nx run canvas-svg:build.native.ios.framework.release",
 		"build.canvas.svg.ios.framework.debug": "nx run canvas-svg:build.native.ios.framework.debug",
-		"build.audiocontext.ios.framework.release": "nx run audio-context:build.native.ios.framework.release"
+		"build.audiocontext.ios.framework.release": "nx run audio-context:build.native.ios.framework.release",
+		"download.ios.frameworks": "./tools/scripts/download-ios-frameworks.sh"
 	},
 	"private": true,
 	"devDependencies": {

packages/audio-context/nativescript.config.ts

@@ -1,37 +1,26 @@
 import { NativeScriptConfig } from '@nativescript/core';
 
-export default {
-	ios: {
-		SPMPackages: [
-			{
-				name: 'CanvasNative',
-				libs: ['NativeScriptV8'],
-				// Header-only SwiftPM shim (V8 headers + empty stub) shipped inside
-				// this npm package — same shim @nativescript/canvas ships. The CLI
-				// dedupes same-name packages across plugins, so installing both
-				// plugins adds it only once. Referenced by local path on purpose: a
-				// repositoryURL reference makes SwiftPM clone the canvas repo's
-				// entire multi-GB git history just to read Package.swift.
-				path: 'node_modules/@nativescript/audio-context/platforms/ios/NativeScriptV8',
-			},
-		],
-	},
-	visionos: {
-		SPMPackages: [
-			{
-				name: 'CanvasNative',
-				libs: ['NativeScriptV8'],
-				path: 'node_modules/@nativescript/audio-context/platforms/ios/NativeScriptV8',
-			},
-		],
+// Local path packages on purpose: a repositoryURL makes SwiftPM clone this repo's
+// multi-GB history before it reads Package.swift.
+//  - CanvasNative: header-only V8 shim shared by the canvas plugins. The CLI keeps
+//    the first plugin package of a given name, so every plugin ships the same one.
+//  - AudioContextNativeBinary: the xcframework. Published packages point it at the
+//    GitHub release zip, so SwiftPM downloads only the framework.
+const SPMPackages = [
+	{
+		name: 'CanvasNative',
+		libs: ['NativeScriptV8'],
+		path: 'node_modules/@nativescript/audio-context/platforms/ios/NativeScriptV8',
 	},
-	tvos: {
-		SPMPackages: [
-			{
-				name: 'CanvasNative',
-				libs: ['NativeScriptV8'],
-				path: 'node_modules/@nativescript/audio-context/platforms/ios/NativeScriptV8',
-			},
-		],
+	{
+		name: 'AudioContextNativeBinary',
+		libs: ['AudioContextNative'],
+		path: 'node_modules/@nativescript/audio-context/platforms/ios/AudioContextNativeBinary',
 	},
+];
+
+export default {
+	ios: { SPMPackages },
+	visionos: { SPMPackages },
+	tvos: { SPMPackages },
 } as NativeScriptConfig;

packages/audio-context/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nativescript/audio-context",
-	"version": "2.0.2",
+	"version": "2.0.3",
 	"description": "Web Audio API for NativeScript",
 	"main": "index",
 	"types": "index.d.ts",