@swiftbrowser/cli 0.1.0 → 0.3.0

package/dist/stage.js

@@ -4,10 +4,48 @@
 // is never written to outside that folder.
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
+import { ASSET_SYMBOLS_FILE, assetSymbolsSource, declaredStaticMembers } from './assetSymbols.js';
+import { swiftSettingsEntries } from './buildSettings.js';
+import { compileLocalizations } from './strings.js';
+import { LINKED_FRAMEWORKS, importsOf } from './compat.js';
+import { ModelError, compileModel } from './coreml.js';
 import { ICU_TARGET, icuAssembly } from './icu.js';
-/** Where an app's staging package lives. */
+import { extensionOverrides, keyPathStrings, objcProtocols, optionalRequirementCalls, optionalRequirementNames } from './objc.js';
+import { planPackages } from './packages.js';
+/**
+ * `$SWIFTBROWSER_BUILD_ROOT`, resolved; unset by default. With it, every app is
+ * staged at `<root>/<App>/` and built with one SwiftPM scratch path,
+ * `<root>/.build`, so a run that compiles several apps compiles the
+ * SwiftBrowser package once. SwiftPM recompiles a dependency whenever the
+ * root package's parent directory changes, so apps staged in their own
+ * projects cannot share it even with a common scratch path. One build at a
+ * time per root: SwiftPM locks the scratch path.
+ */
+export function buildRoot() {
+    const root = process.env['SWIFTBROWSER_BUILD_ROOT'];
+    return root ? path.resolve(root) : undefined;
+}
+/** Where an app's staging package lives: `<project>/.swiftbrowser/<App>/`, or under the build root. */
 export function stagingDir(app) {
-    return path.join(app.root, '.swiftbrowser', app.name);
+    const root = buildRoot();
+    return root ? path.join(root, app.name) : path.join(app.root, '.swiftbrowser', app.name);
+}
+/**
+ * Where `swiftbrowser test` stages the app with its tests: beside the app's
+ * own staging (`<App>.tests/`), so that `test` and `dev` or `build` do not
+ * rewrite each other's package, and each stays incremental.
+ */
+export function testStagingDir(app) {
+    return `${stagingDir(app)}.tests`;
+}
+/** The staged folder of a test target's sources, relative to the staging package. */
+export function testTargetPath(name) {
+    return path.join('Tests', name);
+}
+/** The `swift build` arguments that select the shared scratch path under the build root, if any. */
+export function scratchPathArgs() {
+    const root = buildRoot();
+    return root ? ['--scratch-path', path.join(root, '.build')] : [];
 }
 /** The built module, optimized or not. */
 export function wasmOutput(app) {
@@ -16,55 +54,246 @@ export function wasmOutput(app) {
 /**
  * Adjusts one source for the shim without moving any line, so compiler
  * diagnostics keep their line numbers:
- * - `import SwiftUI` also imports the Foundation modules (lean: FoundationEssentials
- *   + FoundationLite; full: Foundation + FoundationBridge), as Apple's SwiftUI
- *   re-exports Foundation;
- * - lean: `import Foundation` → `import FoundationEssentials; import FoundationLite`,
- *   which is what the SwiftBrowser examples import by hand; in both modes the
- *   line also imports Observation (Apple's Foundation re-exports it, so
- *   `@Observable` works in a file that imports Foundation alone);
- * - full: `import FoundationLite` → `import FoundationBridge` (the examples'
- *   `#if canImport(FoundationEssentials)` branch, against the real Foundation);
+ * - `import SwiftUI` also imports Foundation, FoundationBridge and Observation,
+ *   as Apple's SwiftUI re-exports Foundation (and Foundation re-exports
+ *   Observation, so `@Observable` works in a file that imports either alone);
+ * - `import Foundation` also imports Observation, for the same reason, and
+ *   (`bridged`: in a module built against the bridge) FoundationBridge, whose
+ *   `URLSession`, `UserDefaults`… the alias file names: a public default
+ *   argument (`session: URLSession = .shared`) may only use a member of a
+ *   module its own file imports;
+ * - `import CoreImage.CIFilterBuiltins` → `import CoreImage`, and likewise
+ *   `import UIKit.UIImage`, `import os.log`, `import CoreGraphics.CGImage`:
+ *   on Apple platforms those are Clang submodules; the shim's frameworks are
+ *   Swift modules, which have no submodules to import;
+ * - `delegate?.urlSession?(…)` → `delegate?.urlSession(…)`: the delegate
+ *   methods are `@objc optional` on Apple platforms, plain requirements with
+ *   default implementations in FoundationBridge;
+ * - `ProcessInfo.processInfo.physicalMemory` → `_swiftBrowserPhysicalMemory` (the alias file's):
+ *   swift-foundation answers 0 on WASI, and limits sized from it refuse everything;
+ * - `import Dispatch` → `import FoundationBridge`: the SDK has no Dispatch on
+ *   WASI, and the bridge's queues run on the main actor (a package that
+ *   imports it is built from a copy, vendor.ts);
+ * - `import ObjectiveC` → `import FoundationBridge`, which has the associated
+ *   objects (CoreFoundation.swift), and `unsafeBitCast(Selector(…), to:
+ *   UnsafeRawPointer.self)` → `Selector(…)._uniquePointer`: on Apple platforms
+ *   a selector is a uniqued pointer, the usual key of an associated object;
+ *   here it is a struct, which the bit cast would trap on (`selectorPointers`;
+ *   a package that imports ObjectiveC is built from a copy, vendor.ts);
+ * - `import FoundationLite` → `import FoundationBridge`: FoundationLite was the
+ *   lean mode's formatting layer (Phase 14 folded it into Foundation); a file
+ *   that still names it gets the bridge, which holds what remains;
+ * - `configuration.delegateClass = SceneDelegate.self` records how to make
+ *   the scene delegate (`sceneDelegateClasses`);
+ * - `x as? AnyObject` → `x as? _AnyObjectValue` in a file that reads a number
+ *   off it (`.doubleValue`, `.intValue`…): Objective-C finds those members on
+ *   any object at run time, which the browser's Swift cannot (`numberCasts`);
+ * - `@objc` protocols become class-bound, with their `optional` requirements
+ *   as plain ones that have default implementations, and calls of those
+ *   requirements (`delegate?.method?(…)`, in any of the module's files:
+ *   `optionalRequirements`) plain calls; an `override` in an extension is
+ *   blanked; `#keyPath(Type.property)` becomes `"property"` (objc.ts);
+ * - `ProcessInfo()` → `ProcessInfo.processInfo`;
  * - `#Preview { … }` blocks (and `#Preview("name", traits: …) { … }`) become
  *   blank lines: the shim has no preview macro and previews are not part of
- *   the app.
+ *   the app. So do the older `struct …: PreviewProvider { … }` declarations,
+ *   which packages still carry (with preview-only modifiers inside).
  */
-export function transformSource(text, options) {
+export function transformSource(text, options = {}) {
     let foundationRewrites = 0;
     let out = text;
-    // On Apple platforms `import SwiftUI` re-exports Foundation (UUID, JSON,
-    // Date, UserDefaults are in scope without an import); the shim's SwiftUI
-    // does not, so the same modules are imported next to it.
-    const companions = options.foundation === 'lean' ? 'import FoundationEssentials; import FoundationLite; import Observation' : 'import Foundation; import FoundationBridge; import Observation';
-    out = out.replace(/^([ \t]*)import SwiftUI[ \t]*(\r?)$/gm, (_, indent, cr) => `${indent}import SwiftUI; ${companions}${cr}`);
-    if (options.foundation === 'lean') {
-        out = out.replace(/^([ \t]*)import Foundation[ \t]*(\r?)$/gm, (_, indent, cr) => {
-            foundationRewrites += 1;
-            return `${indent}import FoundationEssentials; import FoundationLite; import Observation${cr}`;
-        });
-    }
-    else {
-        out = out.replace(/^([ \t]*)import Foundation[ \t]*(\r?)$/gm, (_, indent, cr) => `${indent}import Foundation; import Observation${cr}`);
-        out = out.replace(/^([ \t]*)import FoundationLite[ \t]*(\r?)$/gm, (_, indent, cr) => {
-            foundationRewrites += 1;
-            return `${indent}import FoundationBridge${cr}`;
-        });
-    }
+    // On iOS `import SwiftUI` re-exports Foundation (UUID, JSON, Date,
+    // UserDefaults are in scope without an import) and UIKit (`UIColor`,
+    // `UIApplication.shared`); the shim's SwiftUI does not, so the same modules
+    // are imported next to it (and UIKit is linked wherever SwiftUI is, featuresOf).
+    // An access level on the import (`public import SwiftUI`, with
+    // `InternalImportsByDefault`) goes on its companions too.
+    const companions = ['Foundation', 'FoundationBridge', 'Observation', 'UIKit'];
+    out = out.replace(/^([ \t]*)((?:(?:public|package|internal|fileprivate|private)[ \t]+)?)import SwiftUI[ \t]*(\r?)$/gm, (_, indent, access, cr) => `${indent}${access}import SwiftUI; ${companions.map((module) => `${access}import ${module}`).join('; ')}${cr}`);
+    const foundationCompanions = options.bridged ? ['FoundationBridge', 'Observation'] : ['Observation'];
+    out = out.replace(/^([ \t]*)((?:(?:public|package|internal|fileprivate|private)[ \t]+)?)import Foundation[ \t]*(\r?)$/gm, (_, indent, access, cr) => `${indent}${access}import Foundation; ${foundationCompanions.map((module) => `${access}import ${module}`).join('; ')}${cr}`);
+    out = out.replace(SUBMODULE_IMPORT, (_, lead, module, cr) => `${lead}import ${module}${cr}`);
+    // URLSession's delegate methods are `@objc optional` on Apple platforms;
+    // FoundationBridge's are requirements with defaults (URLSession.swift).
+    out = out.replace(/\.urlSession\?\(/g, '.urlSession(');
+    // swift-foundation reports no physical memory on WASI (FoundationBridge/ProcessInfo.swift).
+    out = out.replace(/\bProcessInfo\.processInfo\.physicalMemory\b/g, '_swiftBrowserPhysicalMemory');
+    // The browser runs iOS apps: `#if os(iOS)` holds, as it does on the
+    // iPhone the page stands for (the build's real OS is WASI or Linux).
+    out = out.replace(IOS_CONDITION, (line) => line.replace(/\bos\(\s*iOS\s*\)/g, '(os(iOS) || SWIFTBROWSER)'));
+    // The SDK has no Dispatch on WASI: the bridge's queues stand in (Dispatch.swift).
+    out = out.replace(/^([ \t]*(?:@[A-Za-z_]+[ \t]+)*(?:(?:public|package|internal|fileprivate|private)[ \t]+)?)import Dispatch[ \t]*(\r?)$/gm, (_, lead, cr) => `${lead}import FoundationBridge${cr}`);
+    // Associated objects without the Objective-C runtime (FoundationBridge/CoreFoundation.swift).
+    out = out.replace(/^([ \t]*(?:@[A-Za-z_]+[ \t]+)*(?:(?:public|package|internal|fileprivate|private)[ \t]+)?)import ObjectiveC[ \t]*(\r?)$/gm, (_, lead, cr) => `${lead}import FoundationBridge${cr}`);
+    out = selectorPointers(out);
+    out = out.replace(/^([ \t]*)import FoundationLite[ \t]*(\r?)$/gm, (_, indent, cr) => {
+        foundationRewrites += 1;
+        return `${indent}import FoundationBridge${cr}`;
+    });
+    // Objective-C protocols and what Swift allows only with the runtime (objc.ts).
+    out = objcProtocols(out);
+    out = optionalRequirementCalls(out, options.optionalRequirements ?? optionalRequirementNames([text]));
+    out = extensionOverrides(out);
+    out = keyPathStrings(out);
+    // `ProcessInfo()` is the process's info on Apple platforms; corelibs' initializer is internal.
+    out = out.replace(/\bProcessInfo\(\)/g, 'ProcessInfo.processInfo');
+    out = rewriteObjC(out);
+    out = sceneDelegateClasses(out);
+    out = numberCasts(out);
     const stripped = stripPreviews(out);
     return { text: stripped.text, previewsStripped: stripped.count, foundationRewrites };
 }
-/** Replaces every `#Preview …{ … }` block with blank lines of the same count. */
+/**
+ * `configuration.delegateClass = SceneDelegate.self` →
+ * `configuration._setDelegateClass(SceneDelegate.self) { SceneDelegate() }`:
+ * UIKit makes the scene delegate through the Objective-C runtime, and Swift
+ * without it can only make an instance from a metatype through a `required`
+ * initializer (UIKit/SceneDelegates.swift). Same line, so diagnostics keep
+ * their places.
+ */
+export function sceneDelegateClasses(text) {
+    if (!text.includes('delegateClass'))
+        return text;
+    return text.replace(/(\b[A-Za-z_][\w.]*)\.delegateClass\s*=\s*([A-Z][\w.]*)\.self\b/g, '$1._setDelegateClass($2.self) { $2() }');
+}
+/**
+ * `as? AnyObject` → `as? _AnyObjectValue` where the file reads a number from
+ * the result: `(dict[key] as? AnyObject)?.doubleValue` looks the member up on
+ * any object through Objective-C (nil where there is none); FoundationBridge's
+ * `_AnyObjectValue` (Selector.swift) has those members, optional likewise, on
+ * the numbers, booleans and strings a dictionary of `Any` holds.
+ */
+export function numberCasts(text) {
+    if (!/\bas\?\s*AnyObject\b/.test(text))
+        return text;
+    if (!/\.(?:doubleValue|floatValue|intValue|integerValue|int64Value|uint64Value|uintValue|boolValue)\b/.test(text))
+        return text;
+    return text.replace(/\bas\?(\s*)AnyObject\b/g, 'as?$1_AnyObjectValue');
+}
+/** Whether a source uses the Objective-C runtime's selectors or attributes. */
+export function usesObjC(text) {
+    return /#selector\s*\(|@objc\b|@objcMembers\b/.test(text);
+}
+/**
+ * Whether a source calls POSIX mutex functions. WASI's libc module leaves
+ * `pthread.h` out, so a package that does is built from a copy: there
+ * `#if os(iOS)` holds (Darwin's `os_unfair_lock` branch) and FoundationBridge
+ * declares the mutex functions for the page's single thread (Locks.swift).
+ */
+/**
+ * `unsafeBitCast(Selector(#function), to: UnsafeRawPointer.self)` →
+ * `Selector(#function)._uniquePointer`: the address that stands for the
+ * selector's name (FoundationBridge/Selector.swift), which on Apple
+ * platforms the bit cast gives, the selector being a uniqued pointer.
+ */
+export function selectorPointers(text) {
+    if (!text.includes('unsafeBitCast'))
+        return text;
+    return text.replace(/\bunsafeBitCast\(\s*(Selector\((?:[^()]|\([^()]*\))*\))\s*,\s*to:\s*UnsafeRawPointer\.self\s*\)/g, '$1._uniquePointer');
+}
+/** Whether a source imports ObjectiveC, which the SDK does not have on WASI (transformSource). */
+export function importsObjectiveC(text) {
+    return importsOf(text).includes('ObjectiveC');
+}
+/** Whether a source imports Dispatch, which the SDK does not have on WASI (transformSource). */
+export function importsDispatch(text) {
+    return importsOf(text).includes('Dispatch');
+}
+export function usesPosixMutex(text) {
+    return /\bpthread_mutex(?:attr)?_(?!t\b)[a-z]+\s*\(/.test(text);
+}
+/**
+ * Objective-C without its runtime (FoundationBridge/Selector.swift). The
+ * browser's Swift has no Objective-C interop, so `@objc` (and the Interface
+ * Builder attributes that imply it) is dropped, and `#selector(handle(_:))`
+ * becomes `Selector(Self.handle(_:), name: "handle(_:)")`: the method itself,
+ * which the target/selector APIs call on their target. A qualified method
+ * (`Type.method`) is used as it is; one of another object
+ * (`#selector(model.refresh)`) is called bound; `getter:`/`setter:`
+ * selectors only have a name. A method the file declares `@MainActor` is
+ * bound to its target in a closure instead,
+ * `Selector(name: "tick", isolated: { (target: Self) in target.tick })`:
+ * Swift 6 rejects naming a main-actor method of a class that is not
+ * `Sendable` unapplied (Gifu's display link proxy).
+ */
+export function rewriteObjC(text) {
+    if (!usesObjC(text))
+        return text;
+    let out = text.replace(/@(?:objc\b(?:\([^)\n]*\))?|(?:objcMembers|IBAction|IBOutlet|IBInspectable|IBDesignable)\b)[ \t]*/g, '');
+    const mainActorMethods = new Set([...out.matchAll(/@MainActor\b(?:\s*@\w+(?:\([^)\n]*\))?)*\s*(?:(?:public|private|fileprivate|internal|open|final|override|dynamic|nonisolated)\s+)*func\s+`?([A-Za-z_][A-Za-z0-9_]*)/g)].map((m) => m[1]));
+    let result = '';
+    let index = 0;
+    const selectors = /#selector\s*\(/g;
+    for (;;) {
+        selectors.lastIndex = index;
+        const match = selectors.exec(out);
+        if (!match)
+            break;
+        const open = match.index + match[0].length - 1;
+        const close = matchingParen(out, open);
+        if (close < 0)
+            break;
+        const inner = out.slice(open + 1, close).trim();
+        const name = inner.replace(/\s+/g, '');
+        result += out.slice(index, match.index);
+        const accessor = /^(?:getter|setter)\s*:\s*(.+)$/s.exec(inner);
+        let method = inner.replace(/^self\s*\.\s*/, '');
+        const qualified = /^([A-Z][A-Za-z0-9_]*)\s*\.\s*(.+)$/s.exec(method);
+        const unqualified = method.replace(/^`?([A-Za-z_][A-Za-z0-9_]*)`?/, '$1');
+        const base = /^([A-Za-z_][A-Za-z0-9_]*)/.exec(qualified ? qualified[2] : unqualified)?.[1];
+        if (accessor) {
+            result += `Selector(${JSON.stringify(accessor[1].replace(/\s+/g, ''))})`;
+        }
+        else if (base && mainActorMethods.has(base) && (qualified || !/^[A-Za-z_][A-Za-z0-9_]*\s*\./.test(method))) {
+            const type = qualified ? qualified[1] : 'Self';
+            const member = (qualified ? qualified[2] : unqualified).replace(/\s+/g, '');
+            result += `Selector(name: ${JSON.stringify(name)}, isolated: { (target: ${type}) in target.${member} })`;
+        }
+        else if (/^[A-Z][A-Za-z0-9_]*\s*\./.test(method)) {
+            result += `Selector(${method}, name: ${JSON.stringify(name)})`;
+        }
+        else if (/^[A-Za-z_][A-Za-z0-9_]*\s*\./.test(method)) {
+            result += `Selector(bound: ${method}, name: ${JSON.stringify(name)})`;
+        }
+        else {
+            method = method.replace(/^`?([A-Za-z_][A-Za-z0-9_]*)`?/, '$1');
+            result += `Selector(Self.${method}, name: ${JSON.stringify(name)})`;
+        }
+        index = close + 1;
+    }
+    result += out.slice(index);
+    return result;
+}
+/** Index of the `)` closing the `(` at `open`; -1 when unbalanced. */
+function matchingParen(text, open) {
+    let depth = 0;
+    for (let i = open; i < text.length; i += 1) {
+        if (text[i] === '(')
+            depth += 1;
+        else if (text[i] === ')') {
+            depth -= 1;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return -1;
+}
+/** A `#if` or `#elseif` line that tests `os(iOS)`. */
+const IOS_CONDITION = /^[ \t]*#(?:if|elseif)\b[^\n]*\bos\(\s*iOS\s*\)[^\n]*$/gm;
+/** `import UIKit.UIImage`-style imports of the frameworks the shim provides as Swift modules. */
+const SUBMODULE_IMPORT = /^([ \t]*(?:@[A-Za-z_]+[ \t]+)*)import[ \t]+(CoreImage|UIKit|CoreGraphics|ImageIO|os)\.[A-Za-z_][A-Za-z0-9_.]*[ \t]*(\r?)$/gm;
+/** Replaces every `#Preview …{ … }` block and `PreviewProvider` struct with blank lines of the same count. */
 export function stripPreviews(text) {
     let count = 0;
     let result = '';
     let index = 0;
-    const pattern = /^[ \t]*#Preview\b/gm;
+    const pattern = /^[ \t]*(?:#Preview\b|(?:(?:@\w+(?:\([^)\n]*\))?|public|internal|fileprivate|private)\s+)*struct[ \t]+\w+[ \t]*:[^{\n]*\bPreviewProvider\b)/gm;
     for (;;) {
         pattern.lastIndex = index;
         const match = pattern.exec(text);
         if (!match)
             break;
-        const start = match.index;
+        let start = match.index;
         const open = text.indexOf('{', start);
         if (open < 0)
             break;
@@ -75,6 +304,16 @@ export function stripPreviews(text) {
         let end = close + 1;
         while (end < text.length && (text[end] === ' ' || text[end] === '\t'))
             end += 1;
+        // Attribute lines just above it (`@available(iOS 17, *)`) go with it.
+        for (;;) {
+            const lineEnd = start - 1;
+            if (lineEnd < index || text[lineEnd] !== '\n')
+                break;
+            const lineStart = text.lastIndexOf('\n', lineEnd - 1) + 1;
+            if (lineStart < index || !/^[ \t]*@\w+(?:\([^)\n]*\))?[ \t]*\r?$/.test(text.slice(lineStart, lineEnd)))
+                break;
+            start = lineStart;
+        }
         result += text.slice(index, start);
         const removed = text.slice(start, end);
         result += removed.replace(/[^\n]/g, '');
@@ -161,32 +400,76 @@ function skipString(text, start) {
     }
     return -1;
 }
-/** The Package.swift of the staging package. */
-export function packageManifest(app, swiftPackagePath) {
+/** The features `sources` (their text) call for. */
+export function featuresOf(sources) {
+    const imported = new Set(sources.flatMap((text) => importsOf(text)));
+    // `import SwiftUI` brings UIKit along, as on iOS (transformSource).
+    if (imported.has('SwiftUI'))
+        imported.add('UIKit');
+    return {
+        swiftData: imported.has('SwiftData'),
+        frameworks: LINKED_FRAMEWORKS.filter((framework) => imported.has(framework)),
+    };
+}
+/**
+ * The Package.swift of the staging package; with `tests` (the names of the
+ * app's test targets, for `swiftbrowser test`), a test target for each that
+ * depends on the app's.
+ */
+export function packageManifest(app, swiftPackagePath, features = { swiftData: false, frameworks: [] }, vendored = new Map(), tests = []) {
     const languageMode = app.swiftLanguageMode === '6' ? '.v6' : '.v5';
     const defines = ['SWIFTBROWSER', ...app.defines].map((d) => `.define(${JSON.stringify(d)})`).join(', ');
-    const products = app.foundation === 'lean' ? ['SwiftUI', 'Charts', 'FoundationLite'] : ['SwiftUI', 'Charts', 'FoundationBridge'];
-    const deps = [
+    // The Xcode target's concurrency settings (buildSettings.ts);
+    // `.defaultIsolation` needs tools version 6.2.
+    const concurrency = swiftSettingsEntries(app.swiftSettings);
+    const toolsVersion = app.swiftSettings?.defaultIsolationMainActor ? '6.2' : '6.0';
+    const swiftSettings = [defines, `.swiftLanguageMode(${languageMode})`, ...concurrency].join(', ');
+    const products = [...new Set(['SwiftUI', 'Charts', 'FoundationBridge', 'os', ...(features.swiftData ? ['SwiftData'] : []), ...features.frameworks])];
+    // The Xcode project's package dependencies that build for the browser are
+    // real dependencies; the ones the shim stands in for are linked above, by
+    // import (packages.ts). A package that imports SwiftUI is built from its
+    // copy, adjusted for the shim (vendor.ts); a copy the app does not depend on
+    // directly is declared too, so it takes the original's place deeper in the
+    // graph.
+    const packages = planPackages(app.packages).flatMap((plan) => (plan.kind === 'dependency' ? [plan] : []));
+    const copy = (identity) => {
+        const dir = vendored.get(identity)?.dir;
+        return dir ? `.package(path: ${JSON.stringify(dir)})` : undefined;
+    };
+    const transitive = [...vendored.keys()].filter((identity) => !packages.some((plan) => plan.identity === identity));
+    const linked = [
         ...products.map((p) => `.product(name: ${JSON.stringify(p)}, package: "SwiftBrowser")`),
-        ...(app.foundation === 'full' ? [JSON.stringify(ICU_TARGET)] : []),
-    ].join(',\n                ');
+        ...packages.flatMap((plan) => plan.package.products.map((p) => `.product(name: ${JSON.stringify(p)}, package: ${JSON.stringify(plan.identity)})`)),
+    ];
+    const deps = [...linked, JSON.stringify(ICU_TARGET)].join(',\n                ');
+    // A test module imports what the app's does (and `@testable import`s the app).
+    const testTargets = tests.map((name) => `
+        .testTarget(
+            name: ${JSON.stringify(name)},
+            dependencies: [
+                ${[JSON.stringify(app.name), ...linked].join(',\n                ')}
+            ],
+            path: ${JSON.stringify(testTargetPath(name).split(path.sep).join('/'))},
+            swiftSettings: [${swiftSettings}]
+        ),`).join('');
+    const packageDeps = [
+        `.package(name: "SwiftBrowser", path: ${JSON.stringify(swiftPackagePath)})`,
+        ...packages.map((plan) => copy(plan.identity) ?? plan.declaration),
+        ...transitive.map((identity) => copy(identity)),
+    ];
     // Locale.current follows the host's choice (SB_LOCALE): the two functions
     // that hard-code en_001 in swift-foundation are redirected to FoundationBridge.
-    const localeWrap = app.foundation === 'full'
-        ? `
-    // Full Foundation only: route swift-foundation's hard-coded current locale
-    // (and preferred languages) to FoundationBridge/Locale.swift.
+    const localeWrap = `
+    // Route swift-foundation's hard-coded current locale (and preferred
+    // languages) to FoundationBridge/Locale.swift.
     + ["-Xlinker", "--wrap=$s20FoundationEssentials11LocaleCacheV11preferencesAA0C11PreferencesV_SbtyF",
-       "-Xlinker", "--wrap=$s20FoundationEssentials6LocaleV18preferredLanguagesSaySSGvgZ"]`
-        : '';
-    const icuTarget = app.foundation === 'full'
-        ? `
+       "-Xlinker", "--wrap=$s20FoundationEssentials6LocaleV18preferredLanguagesSaySSGvgZ"]`;
+    const icuTarget = `
         // Foundation's ICU reads its locale data from a symbol this target
         // defines, trimmed to the app's languages, ahead of the SDK's 34 MB
         // original (see @swiftbrowser/cli src/icu.ts).
-        .target(name: ${JSON.stringify(ICU_TARGET)}, path: ${JSON.stringify(ICU_TARGET)}),`
-        : '';
-    return `// swift-tools-version: 6.0
+        .target(name: ${JSON.stringify(ICU_TARGET)}, path: ${JSON.stringify(ICU_TARGET)}),${testTargets}`;
+    return `// swift-tools-version: ${toolsVersion}
 // Generated by @swiftbrowser/cli for ${app.displayName}. Do not edit: it is
 // rewritten on every build. Sources/ holds the app's sources, adjusted for
 // the shim (see stage.ts); the SwiftBrowser package is referenced by path.
@@ -194,7 +477,8 @@ import PackageDescription
 
 // C-ABI entry points the browser renderer calls; the linker must keep them.
 let wasmExports = ["sb_event", "sb_ops_ptr", "sb_ops_len", "sb_ops_clear",
-                   "sb_alloc", "sb_event_json", "sb_state_ptr", "sb_state_len", "sb_run_jobs"]
+                   "sb_alloc", "sb_event_json", "sb_state_ptr", "sb_state_len", "sb_run_jobs",
+                   "sb_bytes", "sb_bytes_count", "sb_bytes_ptr", "sb_bytes_len"]
     .flatMap { ["-Xlinker", "--export=\\($0)"] }
     // The reconciler recurses once per view; 8 MB of stack like a native thread.
     + ["-Xlinker", "-z", "-Xlinker", "stack-size=8388608"]${localeWrap}
@@ -203,7 +487,7 @@ let package = Package(
     name: ${JSON.stringify(app.name)},
     platforms: [.macOS(.v14)],
     products: [.executable(name: ${JSON.stringify(app.name)}, targets: [${JSON.stringify(app.name)}])],
-    dependencies: [.package(name: "SwiftBrowser", path: ${JSON.stringify(swiftPackagePath)})],
+    dependencies: [${packageDeps.length === 1 ? packageDeps[0] : `\n        ${packageDeps.join(',\n        ')},\n    `}],
     targets: [
         .executableTarget(
             name: ${JSON.stringify(app.name)},
@@ -211,33 +495,61 @@ let package = Package(
                 ${deps}
             ],
             path: "Sources",
-            swiftSettings: [${defines}, .swiftLanguageMode(${languageMode})],
+            swiftSettings: [${swiftSettings}],
             linkerSettings: [.unsafeFlags(wasmExports, .when(platforms: [.wasi]))]
         ),${icuTarget}
     ]
 )
 `;
 }
+/** Where the compiled string tables go in the staging directory (`<language>.lproj` folders). */
+export const LOCALIZATION_DIR = 'Localization';
 /** The staged file that settles names declared by both the shim and Foundation. */
 export const FULL_FOUNDATION_FILE = '_SwiftBrowserFoundation.swift';
 /**
- * In full mode the app imports both the shim and the real Foundation, and
- * both declare a few names (the shim cannot import Foundation itself, which
- * would link it into every lean app; and a module does not shadow another's
- * declarations, only the current module's do). A typealias in the app module
- * does: these point the shared names at the shim's types (what its
- * `frame(width:)` and friends take) and at FoundationBridge's `Timer` and
- * `RunLoop`, which Foundation lacks on WASI (`RunLoop` is marked unavailable,
- * its `Timer` needs CFRunLoop and does not link).
+ * The app imports both the shim and Foundation, and both declare a few names
+ * (a module does not shadow another's declarations, only the current module's
+ * do). A typealias in the app module does: these point the shared names at
+ * the shim's types (what its `frame(width:)` and friends take) and at
+ * FoundationBridge's `Timer` and `RunLoop`, which Foundation lacks on WASI
+ * (`RunLoop` is marked unavailable, its `Timer` needs CFRunLoop and does not
+ * link).
  */
-export function fullFoundationSource() {
+export function fullFoundationSource(features = { swiftData: false, frameworks: [] }, declared = new Set()) {
+    // A name the module declares itself (an app's own `Operation` or `Timer`)
+    // is the module's: an alias of it would be a redeclaration.
+    const text = fullFoundationTemplate(features);
+    if (declared.size === 0)
+        return text;
+    return text
+        .split('\n')
+        .filter((line) => {
+        const alias = /^public typealias ([A-Za-z_][A-Za-z0-9_]*) = /.exec(line);
+        return !alias || !declared.has(alias[1]);
+    })
+        .join('\n');
+}
+/** The type names a module's sources declare at the top level (lines that start with the declaration). */
+export function declaredTypeNames(sources) {
+    const names = new Set();
+    const pattern = /^(?:@[A-Za-z_]+(?:\([^)\n]*\))?\s+)*(?:(?:public|package|internal|private|fileprivate|open|final|indirect)\s+)*(?:class|struct|enum|protocol|actor|typealias)\s+([A-Za-z_][A-Za-z0-9_]*)/gm;
+    for (const text of sources) {
+        for (const match of text.matchAll(pattern))
+            names.add(match[1]);
+    }
+    return names;
+}
+function fullFoundationTemplate(features) {
     return `// Generated by @swiftbrowser/cli; rewritten on every build.
 // The shim and Foundation both declare these names. A typealias in the app
 // module settles each in the shim's favor (SwiftUI's geometry) or on the
 // bridge (Timer and RunLoop, which the SDK's Foundation does not have on WASI).
-import SwiftUI
-import Foundation
-import FoundationBridge
+// The imports are public: a package may make imports internal by default
+// (\`InternalImportsByDefault\`), and public aliases need public imports.
+public import SwiftUI
+public import Foundation
+public import FoundationBridge
+public import os
 
 // Public, so the app's own public API may use the names (a public method of
 // a Layout returning CGSize, for one).
@@ -251,12 +563,101 @@ public typealias RunLoop = FoundationBridge.RunLoop
 // Foundation's own cannot persist on WASI, and its Bundle.main traps.
 public typealias UserDefaults = FoundationBridge.UserDefaults
 public typealias Bundle = FoundationBridge.Bundle
-`;
+// Networking runs over the browser's fetch; Foundation's own is unavailable on
+// WASI (it moved to FoundationNetworking, which the SDK does not ship).
+public typealias URLSession = FoundationBridge.URLSession
+public typealias URLSessionConfiguration = FoundationBridge.URLSessionConfiguration
+public typealias URLSessionTask = FoundationBridge.URLSessionTask
+public typealias URLSessionDataTask = FoundationBridge.URLSessionDataTask
+public typealias URLSessionUploadTask = FoundationBridge.URLSessionUploadTask
+public typealias URLSessionDelegate = FoundationBridge.URLSessionDelegate
+public typealias URLSessionTaskDelegate = FoundationBridge.URLSessionTaskDelegate
+public typealias URLSessionDataDelegate = FoundationBridge.URLSessionDataDelegate
+public typealias URLRequest = FoundationBridge.URLRequest
+public typealias URLResponse = FoundationBridge.URLResponse
+public typealias HTTPURLResponse = FoundationBridge.HTTPURLResponse
+public typealias URLError = FoundationBridge.URLError
+// The SDK has no Dispatch on WASI; the bridge's queues run on the main actor.
+public typealias DispatchQueue = FoundationBridge.DispatchQueue
+public typealias DispatchTime = FoundationBridge.DispatchTime
+public typealias DispatchTimeInterval = FoundationBridge.DispatchTimeInterval
+public typealias DispatchQoS = FoundationBridge.DispatchQoS
+public typealias DispatchSpecificKey = FoundationBridge.DispatchSpecificKey
+// Dispatch declares DispatchTime's arithmetic globally (so that .now() + 0.5
+// finds it); declared here, it reaches files that import only Foundation.
+func + (time: DispatchTime, seconds: Double) -> DispatchTime { time._adding(nanoseconds: seconds * 1_000_000_000) }
+func - (time: DispatchTime, seconds: Double) -> DispatchTime { time._adding(nanoseconds: -seconds * 1_000_000_000) }
+func + (time: DispatchTime, interval: DispatchTimeInterval) -> DispatchTime { FoundationBridge.DispatchTime._plus(time, interval) }
+func - (time: DispatchTime, interval: DispatchTimeInterval) -> DispatchTime { FoundationBridge.DispatchTime._minus(time, interval) }
+public typealias DispatchSource = FoundationBridge.DispatchSource
+public typealias DispatchWorkItem = FoundationBridge.DispatchWorkItem
+public typealias DispatchWorkItemFlags = FoundationBridge.DispatchWorkItemFlags
+public typealias DispatchGroup = FoundationBridge.DispatchGroup
+public typealias DispatchSourceProtocol = FoundationBridge.DispatchSourceProtocol
+public typealias DispatchSourceMemoryPressure = FoundationBridge.DispatchSourceMemoryPressure
+public typealias DispatchSourceTimer = FoundationBridge.DispatchSourceTimer
+// Nor Operation and OperationQueue (the bridge's run on the main actor), nor
+// the rest of URL loading's types.
+public typealias Operation = FoundationBridge.Operation
+public typealias BlockOperation = FoundationBridge.BlockOperation
+public typealias OperationQueue = FoundationBridge.OperationQueue
+public typealias URLCache = FoundationBridge.URLCache
+public typealias CachedURLResponse = FoundationBridge.CachedURLResponse
+public typealias URLSessionTaskMetrics = FoundationBridge.URLSessionTaskMetrics
+public typealias URLAuthenticationChallenge = FoundationBridge.URLAuthenticationChallenge
+public typealias URLCredential = FoundationBridge.URLCredential
+public typealias URLProtectionSpace = FoundationBridge.URLProtectionSpace
+public typealias URLSessionWebSocketTask = FoundationBridge.URLSessionWebSocketTask
+// Objective-C's selectors without its runtime (FoundationBridge/Selector.swift).
+public typealias Selector = FoundationBridge.Selector
+// WASI's Foundation keeps only the message-based center; the bridge has the classic one.
+public typealias NotificationCenter = FoundationBridge.NotificationCenter
+func NSSelectorFromString(_ name: String) -> FoundationBridge.Selector { FoundationBridge.NSSelectorFromString(name) }
+func NSStringFromSelector(_ selector: FoundationBridge.Selector) -> String { FoundationBridge.NSStringFromSelector(selector) }
+public typealias URLSessionWebSocketDelegate = FoundationBridge.URLSessionWebSocketDelegate
+// Nor RelativeDateTimeFormatter ("2 hr. ago").
+public typealias RelativeDateTimeFormatter = FoundationBridge.RelativeDateTimeFormatter
+// What Darwin's Foundation brings along: the Core Foundation clock, the
+// Objective-C runtime's autorelease pools and associated objects, and os's lock.
+public typealias CFAbsoluteTime = FoundationBridge.CFAbsoluteTime
+public typealias CFTimeInterval = FoundationBridge.CFTimeInterval
+func CFAbsoluteTimeGetCurrent() -> CFAbsoluteTime { FoundationBridge.CFAbsoluteTimeGetCurrent() }
+func autoreleasepool<Result>(invoking body: () throws -> Result) rethrows -> Result { try FoundationBridge.autoreleasepool(invoking: body) }
+public typealias objc_AssociationPolicy = FoundationBridge.objc_AssociationPolicy
+func objc_setAssociatedObject(_ object: Any, _ key: UnsafeRawPointer, _ value: Any?, _ policy: objc_AssociationPolicy) { FoundationBridge.objc_setAssociatedObject(object, key, value, policy) }
+func objc_getAssociatedObject(_ object: Any, _ key: UnsafeRawPointer) -> Any? { FoundationBridge.objc_getAssociatedObject(object, key) }
+func class_getInstanceSize(_ cls: AnyClass?) -> Int { FoundationBridge.class_getInstanceSize(cls) }
+func sysctlbyname(_ name: UnsafePointer<CChar>?, _ oldp: UnsafeMutableRawPointer?, _ oldlenp: UnsafeMutablePointer<Int>?, _ newp: UnsafeMutableRawPointer?, _ newlen: Int) -> Int32 { FoundationBridge.sysctlbyname(name, oldp, oldlenp, newp, newlen) }
+// ProcessInfo.processInfo.physicalMemory, which reads 0 on WASI (the staging rewrites it to this).
+var _swiftBrowserPhysicalMemory: UInt64 { FoundationBridge._physicalMemory }
+public typealias os_unfair_lock = os.os_unfair_lock
+public typealias os_unfair_lock_t = os.os_unfair_lock_t
+public typealias os_unfair_lock_s = os.os_unfair_lock_s
+func os_unfair_lock_lock(_ lock: os_unfair_lock_t) { os.os_unfair_lock_lock(lock) }
+func os_unfair_lock_unlock(_ lock: os_unfair_lock_t) { os.os_unfair_lock_unlock(lock) }
+func os_unfair_lock_trylock(_ lock: os_unfair_lock_t) -> Bool { os.os_unfair_lock_trylock(lock) }
+${features.swiftData ? SWIFTDATA_PREDICATE : ''}`;
 }
+/**
+ * For an app that imports SwiftData: `#Predicate` expands with SwiftData's
+ * copy of Foundation's macro, which accepts `localizedStandardContains`,
+ * `localizedCompare` and `caseInsensitiveCompare` as Apple's does (the
+ * open-source macro rejects them). A macro declared in the app module shadows
+ * Foundation's; the type `Predicate` stays Foundation's.
+ */
+const SWIFTDATA_PREDICATE = `
+// SwiftData: #Predicate as on Apple platforms (Sources/SwiftDataMacros/PredicateMacro.swift).
+@freestanding(expression)
+macro Predicate<each Input>(_ body: (repeat each Input) -> Bool) -> Foundation.Predicate<repeat each Input> = #externalMacro(module: "SwiftDataMacros", type: "PredicateMacro")
+`;
 /** The directory the staged sources keep their layout relative to. */
 export function commonSourceBase(app) {
-    let base = path.dirname(app.sources[0]);
-    for (const file of app.sources) {
+    return commonDirectory(app.sources);
+}
+/** The deepest directory holding every one of `files`. */
+export function commonDirectory(files) {
+    let base = path.dirname(files[0]);
+    for (const file of files) {
         while (!file.startsWith(`${base}${path.sep}`) && base !== path.dirname(base))
             base = path.dirname(base);
     }
@@ -287,19 +688,24 @@ function listFiles(dir, out = []) {
  * staged files whose source is gone are removed.
  */
 export function stage(app, swiftPackagePath, options = {}) {
-    const dir = stagingDir(app);
+    const tests = options.tests ? (app.tests ?? []) : [];
+    const dir = options.tests ? testStagingDir(app) : stagingDir(app);
     const sourcesDir = path.join(dir, 'Sources');
     mkdirSync(sourcesDir, { recursive: true });
-    writeIfChanged(path.join(dir, 'Package.swift'), packageManifest(app, swiftPackagePath));
+    const texts = new Map(app.sources.map((file) => [file, readFileSync(file, 'utf8')]));
+    const testTexts = new Map(tests.flatMap((target) => target.sources).map((file) => [file, readFileSync(file, 'utf8')]));
+    const models = compileModels(app.models ?? []);
+    // The generated model classes import CoreML, which links it; a test that
+    // imports a framework links it as well.
+    const features = featuresOf([...texts.values(), ...models.map((model) => model.source), ...testTexts.values()]);
+    const optionalRequirements = optionalRequirementNames(texts.values());
+    writeIfChanged(path.join(dir, 'Package.swift'), packageManifest(app, swiftPackagePath, features, options.vendored, tests.map((target) => target.name)));
     const icuDir = path.join(dir, ICU_TARGET);
-    if (app.foundation === 'full') {
-        writeIfChanged(path.join(icuDir, 'icudt.S'), icuAssembly(options.icu ?? null));
-        // SwiftPM insists on a public headers directory for a C target.
-        writeIfChanged(path.join(icuDir, 'include', `${ICU_TARGET}.h`), '// Nothing to include: the target holds data only.\n');
-    }
-    else {
-        rmSync(icuDir, { recursive: true, force: true });
-    }
+    // Tests link the SDK's whole ICU data: a test bundle links its
+    // dependencies' objects as one archive, after the SDK's (no trimmed data).
+    writeIfChanged(path.join(icuDir, 'icudt.S'), icuAssembly(options.tests ? null : (options.icu ?? null)));
+    // SwiftPM insists on a public headers directory for a C target.
+    writeIfChanged(path.join(icuDir, 'include', `${ICU_TARGET}.h`), '// Nothing to include: the target holds data only.\n');
     const base = commonSourceBase(app);
     const originals = new Map();
     const keep = new Set();
@@ -307,16 +713,26 @@ export function stage(app, swiftPackagePath, options = {}) {
     for (const file of app.sources) {
         const relative = path.relative(base, file);
         const staged = path.join(sourcesDir, relative);
-        const transformed = transformSource(readFileSync(file, 'utf8'), { foundation: app.foundation });
+        const transformed = transformSource(texts.get(file), { bridged: true, optionalRequirements });
         previewsStripped += transformed.previewsStripped;
         writeIfChanged(staged, transformed.text);
         originals.set(staged, file);
         keep.add(staged);
     }
-    if (app.foundation === 'full') {
-        const generated = path.join(sourcesDir, FULL_FOUNDATION_FILE);
-        writeIfChanged(generated, fullFoundationSource());
-        keep.add(generated);
+    const generated = path.join(sourcesDir, FULL_FOUNDATION_FILE);
+    writeIfChanged(generated, fullFoundationSource(features, declaredTypeNames([...texts.values()])));
+    keep.add(generated);
+    const assetSymbols = app.assetSymbols === false ? ''
+        : assetSymbolsSource(app.catalogs, { extensions: app.assetSymbols === 'extensions', declared: declaredStaticMembers([...texts.values()]) });
+    if (assetSymbols) {
+        const file = path.join(sourcesDir, ASSET_SYMBOLS_FILE);
+        writeIfChanged(file, assetSymbols);
+        keep.add(file);
+    }
+    for (const model of models) {
+        const file = path.join(sourcesDir, modelSourceName(model));
+        writeIfChanged(file, model.source);
+        keep.add(file);
     }
     for (const stale of listFiles(sourcesDir)) {
         if (!keep.has(stale))
@@ -324,7 +740,57 @@ export function stage(app, swiftPackagePath, options = {}) {
     }
     // Drop directories left empty by removals.
     pruneEmptyDirs(sourcesDir, sourcesDir);
-    return { dir, originals, previewsStripped };
+    // Each test target's sources, adjusted like the app's, with the alias file
+    // as well: a test module imports Foundation and the app, which both declare
+    // `UserDefaults`, `URLSession`…; its own aliases settle them as the app's do.
+    const testsDir = path.join(dir, 'Tests');
+    const keepTests = new Set();
+    for (const target of tests) {
+        const targetDir = path.join(dir, testTargetPath(target.name));
+        const targetBase = commonDirectory(target.sources);
+        const testRequirements = optionalRequirementNames([...texts.values(), ...target.sources.map((file) => testTexts.get(file))]);
+        for (const file of target.sources) {
+            const staged = path.join(targetDir, path.relative(targetBase, file));
+            const transformed = transformSource(testTexts.get(file), { bridged: true, optionalRequirements: testRequirements });
+            writeIfChanged(staged, transformed.text);
+            originals.set(staged, file);
+            keepTests.add(staged);
+        }
+        const aliases = path.join(targetDir, FULL_FOUNDATION_FILE);
+        writeIfChanged(aliases, fullFoundationSource(features, declaredTypeNames(target.sources.map((file) => testTexts.get(file)))));
+        keepTests.add(aliases);
+    }
+    if (existsSync(testsDir)) {
+        for (const stale of listFiles(testsDir)) {
+            if (!keepTests.has(stale))
+                rmSync(stale, { force: true });
+        }
+        pruneEmptyDirs(testsDir, testsDir);
+    }
+    // Errors in a copied local package name the user's file, as the app's do.
+    for (const copy of options.vendored?.values() ?? []) {
+        if (copy.local)
+            originals.set(`${copy.dir}${path.sep}`, `${copy.source}${path.sep}`);
+    }
+    // The string tables, compiled beside the package (not a source of it).
+    const localization = compileLocalizations(app.localizations ?? [], app.locales, path.join(dir, LOCALIZATION_DIR));
+    return { dir, originals, previewsStripped, localizations: localization.dirs, localizationWarnings: localization.warnings };
+}
+/** The staged file of a model's generated class: `<Class>.mlmodel.swift`, a name no app source has. */
+export function modelSourceName(model) {
+    return `${model.className}.mlmodel.swift`;
+}
+/** Compiles each Core ML model of the app (coreml.ts); two models may not make the same class. */
+export function compileModels(files) {
+    const models = files.map((file) => compileModel(file));
+    const byClass = new Map();
+    for (const model of models) {
+        const other = byClass.get(model.className);
+        if (other)
+            throw new ModelError(`two Core ML models would generate the class ${model.className}:\n  ${other}\n  ${model.file}`);
+        byClass.set(model.className, model.file);
+    }
+    return models;
 }
 function pruneEmptyDirs(dir, root) {
     for (const entry of readdirSync(dir, { withFileTypes: true })) {