craft-native 0.0.396 → 0.0.408

package/dist/ios/templates/CraftNativeScreen.swift

@@ -7629,6 +7629,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         appearance.configureWithOpaqueBackground()
         appearance.backgroundColor = screenBackgroundColor ?? config.resolvedBackgroundColor
         appearance.shadowColor = .clear
+        CraftChromeFonts.apply(to: appearance)
         navigationItem.standardAppearance = appearance
         navigationItem.scrollEdgeAppearance = appearance
         navigationItem.compactAppearance = appearance

package/dist/ios/templates/CraftNativeUI.swift

@@ -517,6 +517,95 @@ enum CraftSymbols {
 /// controller, which offers no way to say which style it wants, so the first
 /// call teaches that controller's class to answer from here. Only that exact
 /// class is touched, and only once.
+/// The app's typefaces on UIKit's own chrome. A screen's text follows the
+/// stx tree's `fontFamily`; the navigation bar, the tab bar and bar button
+/// labels are UIKit's, outside that tree, so a branded app drew them in the
+/// system face beside screens in its own. `fontFamily` / `headingFontFamily`
+/// (CSS stacks, as the screens use) put the same faces there, through the
+/// appearance proxies every bar starts from.
+enum CraftChromeFonts {
+    /// The packaged family a body or heading stack resolved to; nil keeps the system face.
+    private(set) static var body: String?
+    private(set) static var heading: String?
+
+    /// The first family of a CSS stack the app can draw. A generic family
+    /// ahead of any packaged one means the system face: nil.
+    static func family(_ stack: String?) -> String? {
+        guard let stack else { return nil }
+        for part in stack.split(separator: ",") {
+            let name = part.trimmingCharacters(in: .whitespacesAndNewlines).trimmingCharacters(in: CharacterSet(charactersIn: "\"'"))
+            switch name.lowercased() {
+            case "": continue
+            case "sans-serif", "ui-sans-serif", "system-ui", "-apple-system", "serif", "ui-serif", "monospace", "ui-monospace": return nil
+            default: if UIFont(name: name, size: 12) != nil { return name }
+            }
+        }
+        return nil
+    }
+
+    /// `family` at a chrome size, bold for a heavy weight and scaled with Dynamic Type.
+    static func font(_ family: String?, size: CGFloat, weight: UIFont.Weight, textStyle: UIFont.TextStyle) -> UIFont? {
+        guard let family, let custom = UIFont(name: family, size: size) else { return nil }
+        var traits = custom.fontDescriptor.symbolicTraits
+        if weight >= .semibold { traits.insert(.traitBold) }
+        let descriptor = custom.fontDescriptor.withSymbolicTraits(traits) ?? custom.fontDescriptor
+        return UIFontMetrics(forTextStyle: textStyle).scaledFont(for: UIFont(descriptor: descriptor, size: size))
+    }
+
+    static var titleFont: UIFont? { font(heading, size: 17, weight: .semibold, textStyle: .headline) }
+    static var largeTitleFont: UIFont? { font(heading, size: 34, weight: .bold, textStyle: .largeTitle) }
+    static var tabLabelFont: UIFont? { font(body, size: 10, weight: .medium, textStyle: .caption2) }
+    static var barButtonFont: UIFont? { font(body, size: 17, weight: .regular, textStyle: .body) }
+
+    static func configure(_ config: CraftConfig) {
+        body = family(config.fontFamily)
+        heading = family(config.headingFontFamily) ?? body
+        if let title = titleFont, let large = largeTitleFont {
+            let bar = UINavigationBar.appearance()
+            bar.titleTextAttributes = [.font: title]
+            bar.largeTitleTextAttributes = [.font: large]
+        }
+        if let label = tabLabelFont {
+            for state in [UIControl.State.normal, .selected] {
+                UITabBarItem.appearance().setTitleTextAttributes([.font: label], for: state)
+            }
+        }
+        if let button = barButtonFont {
+            for state in [UIControl.State.normal, .highlighted, .disabled] {
+                UIBarButtonItem.appearance().setTitleTextAttributes([.font: button], for: state)
+            }
+        }
+    }
+
+    /// The label face on a tab bar. The Liquid Glass bar reads its labels from
+    /// its own appearance and ignores UITabBarItem's proxy, so the face goes on
+    /// a copy of the bar's appearance, which keeps its material untouched.
+    static func apply(to tabBar: UITabBar) {
+        guard let label = tabLabelFont else { return }
+        func labelled(_ appearance: UITabBarAppearance) -> UITabBarAppearance {
+            let copy = appearance.copy()
+            for layout in [copy.stackedLayoutAppearance, copy.inlineLayoutAppearance, copy.compactInlineLayoutAppearance] {
+                for state in [layout.normal, layout.selected, layout.focused, layout.disabled] {
+                    state.titleTextAttributes[.font] = label
+                }
+            }
+            return copy
+        }
+        tabBar.standardAppearance = labelled(tabBar.standardAppearance)
+        if let edge = tabBar.scrollEdgeAppearance { tabBar.scrollEdgeAppearance = labelled(edge) }
+    }
+
+    /// The title faces on a bar appearance a screen builds itself (an opaque bar).
+    static func apply(to appearance: UINavigationBarAppearance) {
+        if let title = titleFont { appearance.titleTextAttributes[.font] = title }
+        if let large = largeTitleFont { appearance.largeTitleTextAttributes[.font] = large }
+        if let button = barButtonFont {
+            appearance.buttonAppearance.normal.titleTextAttributes[.font] = button
+            appearance.doneButtonAppearance.normal.titleTextAttributes[.font] = button
+        }
+    }
+}
+
 enum CraftStatusBar {
     static var style: UIStatusBarStyle = .default
     private static var taught = Set<ObjectIdentifier>()

package/dist/ios/templates/testing/DriverTests.swift.template

@@ -17,7 +17,7 @@ import Darwin
 ///   openurl <url>         opens a link through the system, answering "Open in the app?"
 ///   universallink <https-url> waits up to 60s for an OS-verified link; never opens a browser
 ///   shot <name>           screenshot → shots/<name>.png
-///   tree <name>           accessibility tree → shots/<name>.txt
+///   tree <name>           accessibility tree + identified snapshot values → shots/<name>.txt / <name>-values.json
 ///   tap <text>            first hittable element whose label contains text
 ///   tapif <text>          tap it when it is on screen, else carry on (the big timer's "Show the controls")
 ///   tapid <identifier>
@@ -367,6 +367,22 @@ final class DriverTests: XCTestCase {
             post("/save?name=\(arg).png", shot.pngRepresentation)
         case "tree":
             post("/save?name=\(arg).txt", Data(app.debugDescription.utf8))
+            // debugDescription abbreviates values further than the snapshot.
+            // Retain snapshot values separately; long receipts chunk themselves.
+            do {
+                var values: [[String: String]] = []
+                func collect(_ node: XCUIElementSnapshot) {
+                    if !node.identifier.isEmpty, let value = node.value as? String {
+                        values.append(["id": node.identifier, "label": node.label, "value": value])
+                    }
+                    for child in node.children { collect(child) }
+                }
+                collect(try app.snapshot())
+                let data = try JSONSerialization.data(withJSONObject: values, options: [.sortedKeys])
+                post("/save?name=\(arg)-values.json", data)
+            } catch {
+                XCTFail("Could not retain accessibility values: \(error)")
+            }
         case "tap":
             if let target = waitFor(arg, 10) { press(target); note("tap \(arg): ok") }
             else { XCTFail("Element not found"); note("FAIL tap \(arg): NOT FOUND") }

package/dist/macos/src/index.d.ts

@@ -1,15 +1,26 @@
+export { macosToolchain, pantryExecutable, resolveMacOSToolchain, resolveZig, toolchainCacheDir } from './toolchain.js';
+export type { MacOSToolchain } from './toolchain.js';
 export interface MacOSNativeBuildOptions {
     outdir: string;
     /** A compiled stx native route bundle, never HTML. */
     nativeBundle: string;
+    /** Defaults to the pinned compiler, installed by Pantry (see `resolveMacOSToolchain`). */
     zig?: string;
-    /** zig-js checkout and its public static archive. No system JSC fallback. */
-    zigJS: {
+    /** zig-js checkout and its public static archive. Default: the pinned revision, fetched and built once. No system JSC fallback. */
+    zigJS?: {
         source: string;
         library: string;
     };
+    /** Where the toolchain is cached; default `~/.cache/craft/toolchain`. */
+    toolchainDir?: string;
+    /**
+     * Link WebKit so screens can show web pages in a `<WebView tab="...">` and drive
+     * tabs through `craft.web` (a browser, a help viewer). Off by default: the host
+     * then links no WebKit at all, and `WebView` reports itself unsupported.
+     */
+    webkit?: boolean;
 }
-/** Compile Craft's AppKit host and the shared Zig layout core. No WebKit. */
+/** Compile Craft's AppKit host and the shared Zig layout core. No WebKit unless `webkit` is set. */
 export declare function buildMacOSNative(options: MacOSNativeBuildOptions): Promise<{
     executable: string;
     bundle: string;

package/dist/macos/src/index.js

@@ -1,18 +1,109 @@
 // @bun
 // ../macos/src/index.ts
 import { cp, mkdir } from "fs/promises";
-import { existsSync } from "fs";
-import { join, resolve } from "path";
+import { existsSync as existsSync2 } from "fs";
+import { join as join2, resolve } from "path";
+import process2 from "process";
+
+// ../macos/src/toolchain.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
 import process from "process";
+var macosToolchain = {
+  zig: "0.18.0-dev.252+86dc5ce25",
+  sources: {
+    "zig-js": { repository: "zig-utils/zig-js", revision: "f0072c95780712d1bb789280e08e7e390e83ab94", paths: ["src", "include", "tests", "tools", "docs", "bench", "conformance"] },
+    "zig-regex": { repository: "zig-utils/zig-regex", revision: "fdd9c2e333ea6ac2fd06d080d939ef7f11d61b1b", paths: ["src"] },
+    "zig-gc": { repository: "zig-utils/zig-gc", revision: "0285ef801dd221a4ae8e88b31a09ae31627657a3", paths: ["src"] }
+  }
+};
+var defaultRun = async (args, cwd) => {
+  const child = Bun.spawn(args, { cwd, stdout: "pipe", stderr: "pipe" });
+  const [exitCode, stdout, stderr] = await Promise.all([child.exited, new Response(child.stdout).text(), new Response(child.stderr).text()]);
+  return { exitCode, stdout, stderr };
+};
+function toolchainCacheDir(env = process.env) {
+  return env.CRAFT_TOOLCHAIN_DIR || join(env.XDG_CACHE_HOME || join(env.HOME || homedir(), ".cache"), "craft", "toolchain");
+}
+function pantryExecutable(env = process.env, exists = existsSync) {
+  const home = env.HOME || homedir();
+  return [env.PANTRY_BIN, join(process.cwd(), "pantry/.bin/pantry"), join(home, ".local/bin/pantry")].find((path) => path && exists(path)) ?? "pantry";
+}
+async function resolveZig(options = {}) {
+  const env = options.env ?? process.env;
+  if (env.CRAFT_ZIG)
+    return env.CRAFT_ZIG;
+  const cache = options.cacheDir ?? toolchainCacheDir(env);
+  const zig = join(cache, "pantry/ziglang.org", `v${macosToolchain.zig}`, "bin/zig");
+  if (existsSync(zig))
+    return zig;
+  const run = options.run ?? defaultRun;
+  mkdirSync(cache, { recursive: true });
+  options.log?.(`Installing Zig ${macosToolchain.zig} with Pantry`);
+  const result = await run([pantryExecutable(env), "install", `ziglang.org@${macosToolchain.zig}`, "--no-save", "--ignore-scripts"], cache);
+  if (result.exitCode !== 0 || !existsSync(zig))
+    throw new Error(`Pantry could not install ziglang.org@${macosToolchain.zig} into ${cache}: ${result.stderr?.trim().slice(-400) ?? ""}. Install Pantry (https://pantry.dev) or set CRAFT_ZIG.`);
+  return zig;
+}
+async function fetchSource(name, cache, run, log) {
+  const pin = macosToolchain.sources[name];
+  const directory = join(cache, "sources", name);
+  const git = async (args) => {
+    const result = await run(["git", ...args], directory);
+    if (result.exitCode !== 0)
+      throw new Error(`git ${args.join(" ")} failed in ${directory}: ${result.stderr?.trim() ?? ""}`);
+    return result.stdout.trim();
+  };
+  mkdirSync(directory, { recursive: true });
+  if (!existsSync(join(directory, ".git"))) {
+    await git(["init", "--quiet"]);
+    await git(["remote", "add", "origin", `https://github.com/${pin.repository}.git`]);
+    await git(["sparse-checkout", "set", ...pin.paths]);
+  }
+  const head = await run(["git", "rev-parse", "HEAD"], directory);
+  if (head.exitCode !== 0 || head.stdout.trim() !== pin.revision) {
+    log?.(`Fetching ${name} ${pin.revision.slice(0, 8)}`);
+    await git(["fetch", "--quiet", "--filter=blob:none", "--depth=1", "origin", pin.revision]);
+    await git(["checkout", "--quiet", "--detach", "FETCH_HEAD"]);
+  }
+  return directory;
+}
+async function resolveMacOSToolchain(options = {}) {
+  const env = options.env ?? process.env;
+  const run = options.run ?? defaultRun;
+  const cache = options.cacheDir ?? toolchainCacheDir(env);
+  const zig = await resolveZig({ ...options, cacheDir: cache });
+  const source = await fetchSource("zig-js", cache, run, options.log);
+  await fetchSource("zig-regex", cache, run, options.log);
+  await fetchSource("zig-gc", cache, run, options.log);
+  const library = join(source, "zig-out/lib/libzig-js.a");
+  const stamp = join(source, "zig-out/.craft-toolchain");
+  const wanted = `${macosToolchain.zig}
+${macosToolchain.sources["zig-js"].revision}
+${macosToolchain.sources["zig-regex"].revision}
+${macosToolchain.sources["zig-gc"].revision}
+`;
+  if (!existsSync(library) || !existsSync(stamp) || readFileSync(stamp, "utf8") !== wanted) {
+    options.log?.("Building the zig-js engine");
+    const result = await run([zig, "build", "home-tool-bootstrap", "-Doptimize=ReleaseFast"], source);
+    if (result.exitCode !== 0 || !existsSync(library))
+      throw new Error(`zig-js did not build (${library}): ${result.stderr?.trim() ?? ""}`);
+    writeFileSync(stamp, wanted);
+  }
+  return { zig, zigJS: { source, library } };
+}
+
+// ../macos/src/index.ts
 async function buildMacOSNative(options) {
-  if (process.platform !== "darwin")
+  if (process2.platform !== "darwin")
     throw new Error("The AppKit host must be built on macOS.");
   const outdir = resolve(options.outdir);
-  const templates = join(import.meta.dir, "../templates");
-  const sourceRoot = join(import.meta.dir, "../..");
-  const layout = existsSync(join(sourceRoot, "zig/src/native_layout.zig")) ? join(sourceRoot, "zig/src/native_layout.zig") : join(templates, "native_layout.zig");
-  const mutation = existsSync(join(sourceRoot, "ios/templates/CraftNativeMutation.swift")) ? join(sourceRoot, "ios/templates/CraftNativeMutation.swift") : join(templates, "CraftNativeMutation.swift");
-  if (!existsSync(options.nativeBundle))
+  const templates = join2(import.meta.dir, "../templates");
+  const sourceRoot = join2(import.meta.dir, "../..");
+  const layout = existsSync2(join2(sourceRoot, "zig/src/native_layout.zig")) ? join2(sourceRoot, "zig/src/native_layout.zig") : join2(templates, "native_layout.zig");
+  const mutation = existsSync2(join2(sourceRoot, "ios/templates/CraftNativeMutation.swift")) ? join2(sourceRoot, "ios/templates/CraftNativeMutation.swift") : join2(templates, "CraftNativeMutation.swift");
+  if (!existsSync2(options.nativeBundle))
     throw new Error(`Native STX bundle not found: ${options.nativeBundle}`);
   await mkdir(outdir, { recursive: true });
   async function run(args) {
@@ -20,38 +111,39 @@ async function buildMacOSNative(options) {
     if (await child.exited !== 0)
       throw new Error(`Native build failed: ${args[0]}`);
   }
-  const zig = options.zig || process.env.CRAFT_ZIG || Bun.which("zig");
-  if (!zig)
-    throw new Error("Install the pinned Craft Zig toolchain or set CRAFT_ZIG.");
-  const layoutLibrary = join(outdir, "libcraft-layout.a");
+  const toolchain = options.zig && options.zigJS ? undefined : await resolveMacOSToolchain({ cacheDir: options.toolchainDir, log: (line) => console.log(line) });
+  const zig = options.zig || toolchain.zig;
+  const layoutLibrary = join2(outdir, "libcraft-layout.a");
   await run([zig, "build-lib", layout, "-O", "ReleaseSafe", "-static", "-lc", `-femit-bin=${layoutLibrary}`]);
-  const executable = join(outdir, "craft-native-macos");
-  const engine = options.zigJS;
-  if (!existsSync(engine.library))
+  const executable = join2(outdir, "craft-native-macos");
+  const engine = options.zigJS || toolchain.zigJS;
+  if (!existsSync2(engine.library))
     throw new Error(`Build zig-js first: ${engine.library}`);
-  if (!existsSync(join(engine.source, "include/module.modulemap")))
+  if (!existsSync2(join2(engine.source, "include/module.modulemap")))
     throw new Error("zig-js must expose its owned ZigJS Swift module.");
-  const bridge = join(outdir, "zig-js-objc.o");
-  const dispatch = join(outdir, "zig-js-dispatch.o");
-  const assembly = join(engine.source, `src/objc_abi_${process.arch === "arm64" ? "aarch64" : "x86_64"}.S`);
-  await run(["xcrun", "clang", "-fobjc-arc", "-fblocks", "-Wno-incomplete-implementation", "-I", join(engine.source, "include"), "-include", join(engine.source, "include/ZigJS.h"), "-c", join(engine.source, "src/objc_bridge.m"), "-o", bridge]);
-  await run([zig, "build-obj", join(engine.source, "src/objc_abi_dispatch.zig"), assembly, "-O", "ReleaseFast", `-femit-bin=${dispatch}`]);
+  const bridge = join2(outdir, "zig-js-objc.o");
+  const dispatch = join2(outdir, "zig-js-dispatch.o");
+  const assembly = join2(engine.source, `src/objc_abi_${process2.arch === "arm64" ? "aarch64" : "x86_64"}.S`);
+  await run(["xcrun", "clang", "-fobjc-arc", "-fblocks", "-Wno-incomplete-implementation", "-I", join2(engine.source, "include"), "-include", join2(engine.source, "include/ZigJS.h"), "-c", join2(engine.source, "src/objc_bridge.m"), "-o", bridge]);
+  await run([zig, "build-obj", join2(engine.source, "src/objc_abi_dispatch.zig"), assembly, "-O", "ReleaseFast", `-femit-bin=${dispatch}`]);
+  const web = options.webkit ? ["-D", "CRAFT_WEBKIT", "-framework", "WebKit", join2(templates, "CraftMacWebView.swift")] : [];
   await run([
     "swiftc",
     "-O",
     "-swift-version",
     "5",
     "-I",
-    join(engine.source, "include"),
+    join2(engine.source, "include"),
     "-framework",
     "Cocoa",
     "-framework",
     "AVKit",
     "-framework",
     "UserNotifications",
-    join(templates, "CraftMacRuntime.swift"),
-    join(templates, "CraftMacRenderer.swift"),
-    join(templates, "CraftMacApplication.swift"),
+    ...web,
+    join2(templates, "CraftMacRuntime.swift"),
+    join2(templates, "CraftMacRenderer.swift"),
+    join2(templates, "CraftMacApplication.swift"),
     mutation,
     bridge,
     dispatch,
@@ -65,11 +157,16 @@ async function buildMacOSNative(options) {
     "-o",
     executable
   ]);
-  const bundle = join(outdir, "native-screen.js");
+  const bundle = join2(outdir, "native-screen.js");
   if (resolve(options.nativeBundle) !== bundle)
     await cp(options.nativeBundle, bundle);
   return { executable, bundle };
 }
 export {
-  buildMacOSNative
+  buildMacOSNative,
+  macosToolchain,
+  pantryExecutable,
+  resolveMacOSToolchain,
+  resolveZig,
+  toolchainCacheDir
 };

package/dist/macos/src/toolchain.d.ts

@@ -0,0 +1,56 @@
+/**
+ * What the AppKit host is built with. Pinned here, beside the Swift that needs
+ * it, so an app never copies a lock file of its own: the Zig compiler (installed
+ * by Pantry, which mirrors Zig dev builds) and the zig-js engine with the two
+ * libraries it builds against (fetched at an exact revision).
+ */
+export declare const macosToolchain: {
+    readonly zig: '0.18.0-dev.252+86dc5ce25';
+    readonly sources: {
+        readonly 'zig-js': {
+            readonly repository: 'zig-utils/zig-js';
+            readonly revision: 'f0072c95780712d1bb789280e08e7e390e83ab94';
+            readonly paths: readonly ['src', 'include', 'tests', 'tools', 'docs', 'bench', 'conformance'];
+        };
+        readonly 'zig-regex': {
+            readonly repository: 'zig-utils/zig-regex';
+            readonly revision: 'fdd9c2e333ea6ac2fd06d080d939ef7f11d61b1b';
+            readonly paths: readonly ['src'];
+        };
+        readonly 'zig-gc': {
+            readonly repository: 'zig-utils/zig-gc';
+            readonly revision: '0285ef801dd221a4ae8e88b31a09ae31627657a3';
+            readonly paths: readonly ['src'];
+        };
+    };
+};
+export interface MacOSToolchain {
+    zig: string;
+    zigJS: {
+        source: string;
+        library: string;
+    };
+}
+export type ToolchainRunner = (args: string[], cwd?: string) => Promise<{
+    exitCode: number;
+    stdout: string;
+    stderr?: string;
+}>;
+export interface ResolveToolchainOptions {
+    /** Where the compiler and sources are kept. Default: `$CRAFT_TOOLCHAIN_DIR`, else `~/.cache/craft/toolchain`. */
+    cacheDir?: string;
+    env?: Record<string, string | undefined>;
+    run?: ToolchainRunner;
+    log?: (line: string) => void;
+}
+export declare function toolchainCacheDir(env?: Record<string, string | undefined>): string;
+/** The Pantry executable: PANTRY_BIN, the project's own, the user's, else `pantry` on PATH. */
+export declare function pantryExecutable(env?: Record<string, string | undefined>, exists?: (path: string) => boolean): string;
+/**
+ * The pinned Zig compiler. `CRAFT_ZIG` wins when set (a deliberate override,
+ * e.g. CI); otherwise Pantry installs exactly the pinned version into the
+ * cache. Zig is never taken from PATH: the wrong snapshot builds nothing.
+ */
+export declare function resolveZig(options?: ResolveToolchainOptions): Promise<string>;
+/** Zig, the zig-js checkout at its pinned revision and its built static library; everything missing is fetched and built once. */
+export declare function resolveMacOSToolchain(options?: ResolveToolchainOptions): Promise<MacOSToolchain>;

package/dist/macos/templates/CraftMacApplication.swift

@@ -4,6 +4,13 @@ import CoreImage
 import UserNotifications
 import UniformTypeIdentifiers
 
+/// A window that tells its screen when Escape reaches it unhandled: the screen hears it as the desktop
+/// command `escape` (close the open item, dismiss a sheet).
+final class CraftMacWindow: NSWindow {
+    weak var runtime: CraftMacRuntime?
+    override func cancelOperation(_ sender: Any?) { runtime?.send("CRAFT_EVENT", ["event": "craftDesktopCommand", "detail": ["id": "escape"]]) }
+}
+
 final class CraftMacScene: NSObject, NSWindowDelegate {
     let name: String
     let window: NSWindow
@@ -14,7 +21,10 @@ final class CraftMacScene: NSObject, NSWindowDelegate {
         runtime = CraftMacRuntime(route: route, params: options["params"] as? [String: Any] ?? [:], network: application.network)
         renderer = CraftMacRenderer(runtime: runtime)
         let width = number(options["width"]) ?? 1120, height = number(options["height"]) ?? 740
-        window = NSWindow(contentRect: CGRect(x: 0, y: 0, width: width, height: height), styleMask: [.titled, .closable, .resizable, .miniaturizable], backing: .buffered, defer: false)
+        let transparent = (options["titlebarStyle"] as? String ?? application.titlebarStyle) == "transparent"
+        let panel = CraftMacWindow(contentRect: CGRect(x: 0, y: 0, width: width, height: height), styleMask: transparent ? [.titled, .closable, .resizable, .miniaturizable, .fullSizeContentView] : [.titled, .closable, .resizable, .miniaturizable], backing: .buffered, defer: false)
+        panel.runtime = runtime
+        window = panel
         super.init()
         runtime.scene = self; renderer.window = window
         window.title = options["title"] as? String ?? application.appName
@@ -54,6 +64,10 @@ final class CraftMacApplication: NSObject, NSApplicationDelegate, UNUserNotifica
     var bundle = ""
     var initialRoute = "Main"
     var titlebarStyle = "standard"
+    /// Apps that ship their own agent (Attic) hand out a session cookie at
+    /// `/native/session`. An app that talks to a hosted API has no such
+    /// endpoint and starts with `--no-session`.
+    var requiresSession = true
     var mainWindowOptions: [String: Any] = [:]
     var network: CraftMacNetwork!
     var scenes: [String: CraftMacScene] = [:]
@@ -70,6 +84,11 @@ final class CraftMacApplication: NSObject, NSApplicationDelegate, UNUserNotifica
             DispatchQueue.main.async { self?.appearanceChanged() }
         }
         NSApp.activate(ignoringOtherApps: true)
+        if !requiresSession {
+            open(name: "main", route: initialRoute, options: mainWindowOptions.merging(["title": appName]) { _, new in new })
+            startTestDriver()
+            return
+        }
         // The agent issues an HttpOnly cookie. It stays in URLSession, shared
         // by native windows, and is never handed to the JavaScript context.
         let request = URLRequest(url: network.base.appendingPathComponent("native/session"))
@@ -174,7 +193,11 @@ final class CraftMacApplication: NSObject, NSApplicationDelegate, UNUserNotifica
                 if let old = bar.items.first(where: { $0.title == title }) { bar.removeItem(old) }
                 let menu = NSMenu(title: title); menu.autoenablesItems = false
                 for item in raw["items"] as? [[String: Any]] ?? [] { menu.addItem(menuItem(item, target: self, action: #selector(command(_:)))) }
-                addMenu(menu, to: bar)
+                let item = NSMenuItem(title: menu.title, action: nil, keyEquivalent: ""); item.submenu = menu
+                // A File menu is the first after the app menu; the others sit
+                // between Edit and Window, where a Mac app's own menus belong.
+                let index = title == "File" ? 1 : (bar.items.firstIndex(where: { $0.title == "Window" }) ?? bar.items.count)
+                bar.insertItem(item, at: min(index, bar.items.count))
             }; reply(true)
         case "contextMenu":
             let target = CraftMacMenuTarget(), menu = NSMenu(); menu.autoenablesItems = false
@@ -298,6 +321,16 @@ final class CraftMacApplication: NSObject, NSApplicationDelegate, UNUserNotifica
         guard box.window?.isVisible == true, !box.isHidden, box.frame.width > 0, box.frame.height > 0 else { return ["ok": false, "error": "Control is not visible"] }
         if let control = box.control as? NSControl, !control.isEnabled { return ["ok": false, "error": "Control is disabled"] }
         switch kind {
+        case "key":
+            // Return, Tab, Escape and the arrows, as the field editor receives them: they reach the same delegate commands a keystroke does.
+            let commands = ["return": #selector(NSResponder.insertNewline(_:)), "tab": #selector(NSResponder.insertTab(_:)), "escape": #selector(NSResponder.cancelOperation(_:)),
+                            "up": #selector(NSResponder.moveUp(_:)), "down": #selector(NSResponder.moveDown(_:)), "backspace": #selector(NSResponder.deleteBackward(_:))]
+            guard let name = action["value"] as? String, let command = commands[name] else { return ["ok": false, "error": "Unknown key"] }
+            let target: NSView? = (box.control as? NSScrollView)?.documentView ?? box.control
+            guard let target, scene.window.makeFirstResponder(target) else { return ["ok": false, "error": "Control cannot take focus"] }
+            let editor = (target as? NSTextField)?.currentEditor() as? NSTextView ?? target as? NSTextView
+            guard let editor else { return ["ok": false, "error": "Not a text input"] }
+            editor.doCommand(by: command)
         case "click": if let button = box.control as? NSButton { button.performClick(nil) } else { box.pressed() }
         case "fill":
             let value = action["value"] as? String ?? ""
@@ -343,18 +376,30 @@ final class CraftMacApplication: NSObject, NSApplicationDelegate, UNUserNotifica
 
 @main struct CraftMacMain {
     static func main() throws {
-        func argument(_ flag: String, fallback: String = "") -> String { guard let index = CommandLine.arguments.firstIndex(of: flag), CommandLine.arguments.indices.contains(index + 1) else { return fallback }; return CommandLine.arguments[index + 1] }
+        // A bundled app is launched by Finder with no arguments: its settings are
+        // `Contents/Resources/craft-app.json`, written by the build. A flag on the
+        // command line still wins, so a development run can point elsewhere.
+        let packaged = Bundle.main.url(forResource: "craft-app", withExtension: "json")
+            .flatMap { try? Data(contentsOf: $0) }
+            .flatMap { try? JSONSerialization.jsonObject(with: $0) as? [String: Any] } ?? [:]
+        func argument(_ flag: String, key: String? = nil, fallback: String = "") -> String {
+            if let index = CommandLine.arguments.firstIndex(of: flag), CommandLine.arguments.indices.contains(index + 1) { return CommandLine.arguments[index + 1] }
+            if let key, let value = packaged[key] { return String(describing: value) }
+            return fallback
+        }
         let application = CraftMacApplication.shared
         if CommandLine.arguments.contains("--version") { print("craft native macOS renderer 0.0.172 (zig-js)"); return }
-        guard let api = URL(string: argument("--api-url")), ["http", "https"].contains(api.scheme ?? ""), api.host != nil else { throw NSError(domain: "Craft", code: 1, userInfo: [NSLocalizedDescriptionKey: "--api-url must name the application's HTTP agent"] ) }
-        let bundlePath = argument("--native-bundle")
+        guard let api = URL(string: argument("--api-url", key: "apiUrl")), ["http", "https"].contains(api.scheme ?? ""), api.host != nil else { throw NSError(domain: "Craft", code: 1, userInfo: [NSLocalizedDescriptionKey: "--api-url must name the application's HTTP agent"] ) }
+        let bundledScreens = Bundle.main.path(forResource: "native-screen", ofType: "js") ?? ""
+        let bundlePath = argument("--native-bundle", fallback: bundledScreens)
         guard !bundlePath.isEmpty else { throw NSError(domain: "Craft", code: 2, userInfo: [NSLocalizedDescriptionKey: "--native-bundle must name a compiled STX bundle"] ) }
         application.bundle = try String(contentsOfFile: bundlePath, encoding: .utf8)
-        application.appName = argument("--title", fallback: "Craft")
-        application.initialRoute = argument("--route", fallback: "Main")
-        application.titlebarStyle = argument("--titlebar-style", fallback: "standard")
+        application.appName = argument("--title", key: "title", fallback: "Craft")
+        application.initialRoute = argument("--route", key: "route", fallback: "Main")
+        application.titlebarStyle = argument("--titlebar-style", key: "titlebarStyle", fallback: "standard")
+        application.requiresSession = !CommandLine.arguments.contains("--no-session") && packaged["session"] as? Bool != false
         for (flag, key) in [("--width", "width"), ("--height", "height"), ("--min-width", "minWidth"), ("--min-height", "minHeight")] {
-            if let value = Double(argument(flag)), value.isFinite, value > 0 { application.mainWindowOptions[key] = value }
+            if let value = Double(argument(flag, key: key)), value.isFinite, value > 0 { application.mainWindowOptions[key] = value }
         }
         application.network = CraftMacNetwork(base: api)
         let testDirectory = argument("--test-dir")