craft-native 0.0.86 → 0.0.88

package/README.md

@@ -314,6 +314,77 @@ import { orbstackStyles, renderOrbStackSidebar, orbstackDemoData } from 'craft-n
 const html = renderOrbStackSidebar(orbstackDemoData)
 ```
 
+## Auto-Updating
+
+`AutoUpdater` fetches a manifest, verifies the download, replaces the app bundle,
+and relaunches.
+
+```ts
+import { AutoUpdater } from 'craft-native'
+
+const updater = new AutoUpdater({
+  updateUrl: 'https://github.com/you/app/releases/latest/download/update.json',
+  currentVersion: '1.0.0',
+  appPath: '/Applications/MyApp.app',
+  autoDownload: false,
+  macos: { teamId: 'ABCDE12345' },
+})
+
+updater.on('update-available', info => console.log('available:', info.version))
+updater.on('download-progress', p => console.log(`${p.percent}%`))
+
+if (await updater.checkForUpdates()) {
+  await updater.downloadUpdate()
+  await updater.installUpdate()
+}
+```
+
+### macOS trust
+
+The manifest's SHA-256 proves the download matches what the manifest asked for. It
+says nothing about *who published it* — whoever can rewrite the manifest can rewrite
+the hash with it. So on macOS the staged bundle is also put through the checks
+Gatekeeper runs at launch, before anything is swapped:
+
+- `codesign --verify --deep --strict` — the signature covers the bytes on disk
+- `spctl -a -t exec` — Apple has notarized this build
+- `TeamIdentifier` equals `macos.teamId` — *you* published it
+
+Pin `teamId`. Without it an updater accepts any notarized bundle, and notarization is
+available to every Apple developer account there is. `@stacksjs/desktop`'s
+`createSelfUpdater` fills it in from the signature on the running copy, which is the
+version most apps want.
+
+### Replacing the bundle
+
+The swap is deliberately not `rm -rf app && cp -R new app`:
+
+- **`ditto`, not `cp -R`.** `cp` and `fs.cpSync` drop the extended attributes and ACLs
+  a code signature is computed over, so a byte-identical copy fails `codesign --verify`.
+- **Two renames, not a delete.** The new bundle lands on the destination volume first,
+  then the old one is renamed aside and the new one renamed in. Both are atomic within
+  a directory, so there is no window in which an interrupted update leaves the user
+  with no app.
+- **Quarantine last.** The flag is cleared only after verification passes — clearing it
+  first is how an updater becomes a way to install anything at all.
+
+These are exported on their own for installers and CI: `verifyBundleTrust`,
+`readBundleIdentity`, `extractBundle`, `extractBundleFromDmg`, `extractBundleFromZip`,
+`swapBundle`, `dittoBundle`, `clearQuarantine`, `canReplaceBundle`.
+
+### Relaunching
+
+`restartApp` opens the bundle and exits. Pass `relaunch` when the updater does not run
+in the process the user launched — an agent behind a webview that calls
+`process.exit(0)` kills a child, leaves the window on a dead server, and relaunches
+nothing.
+
+### Deltas
+
+Delta updates are used only when `bspatch` or `xdelta3` is on the machine. Neither
+ships with macOS or a default Linux install, so a manifest that offers a delta falls
+back to the full bundle rather than failing.
+
 ## Examples
 
 See the [examples directory](../examples-ts) for more:

package/dist/api/window.d.ts

@@ -97,8 +97,10 @@ export interface WindowCreateOptions {
     webSidebarMaterial?: boolean;
     /** Width of the native material backdrop behind a web-rendered sidebar */
     webSidebarWidth?: number;
-    /** White/dark tint opacity over the native material backdrop */
+    /** White/dark tint opacity over the native material backdrop (sidebar span only) */
     webSidebarMaterialOpacity?: number;
+    /** Draw that material behind the whole web view instead of a leading strip */
+    webWindowMaterial?: boolean;
     /** Titlebar style (macOS) */
     titlebarStyle?: 'default' | 'hidden' | 'hiddenInset' | 'customButtonsOnHover';
     /** Vibrancy effect (macOS) */
@@ -332,6 +334,15 @@ export declare class Window {
      * Set vibrancy effect (macOS)
      */
     setVibrancy(vibrancy: WindowCreateOptions['vibrancy'] | null): Promise<void>;
+    /**
+     * Pin the window to light or dark, or hand it back to the OS (macOS).
+     *
+     * Everything native around the page — a material backdrop, a vibrancy view,
+     * the window buttons — resolves against the *window's* appearance. An app
+     * with its own light/dark control is the only thing that knows which it
+     * picked, so it has to say, or the page and its window disagree.
+     */
+    setAppearance(appearance: 'light' | 'dark' | 'system'): Promise<void>;
     /**
      * Where the platform's window buttons are — read, not written.
      *
@@ -454,6 +465,8 @@ declare class WindowManager {
     setBackgroundColor: (color: string) => Promise<void>;
     /** Set current window vibrancy (macOS) */
     setVibrancy: (vibrancy: WindowCreateOptions['vibrancy'] | null) => Promise<void>;
+    /** Pin the current window to light or dark, or follow the OS (macOS) */
+    setAppearance: (appearance: 'light' | 'dark' | 'system') => Promise<void>;
     /** Set current window resizable */
     setResizable: (resizable: boolean) => Promise<void>;
     /** Start moving current window from a native pointer event */

package/dist/cli.js

@@ -1053,9 +1053,11 @@ __export(exports_src, {
   syncWebAssets: () => syncWebAssets,
   showSimulator: () => showSimulator,
   run: () => run,
+  resolveRuntimeDir: () => resolveRuntimeDir,
   renderWatchEntitlements: () => renderWatchEntitlements,
   renderUsageDescriptions: () => renderUsageDescriptions,
   renderUrlTypes: () => renderUrlTypes,
+  renderRuntimeSettings: () => renderRuntimeSettings,
   renderPrivacyManifest: () => renderPrivacyManifest,
   renderOrientations: () => renderOrientations,
   renderEntitlements: () => renderEntitlements,
@@ -1064,6 +1066,7 @@ __export(exports_src, {
   pickSimulator: () => pickSimulator,
   orderSimulators: () => orderSimulators,
   open: () => open,
+  installRuntime: () => installRuntime,
   init: () => init,
   build: () => build,
   bootSimulator: () => bootSimulator
@@ -1193,6 +1196,14 @@ ${appGroups}</dict>
 </plist>
 `;
 }
+function renderRuntimeSettings() {
+  return [
+    '      LIBRARY_SEARCH_PATHS[sdk=iphoneos*]: "$(PROJECT_DIR)/Runtime/device"',
+    '      LIBRARY_SEARCH_PATHS[sdk=iphonesimulator*]: "$(PROJECT_DIR)/Runtime/simulator"',
+    '      OTHER_LDFLAGS: "-lcraft-ios -Wl,-u,_craft_ios_handle_action -Wl,-u,_craft_ios_set_webview ' + '-Wl,-u,_craft_ios_deliver_result -Wl,-u,_craft_ios_deliver_error"'
+  ].join(`
+`);
+}
 function renderPrivacyManifest(config) {
   const privacy = config.privacy ?? {};
   const collected = privacy.collectedDataTypes ?? [];
@@ -1296,6 +1307,55 @@ function syncWebAssets(source, output) {
     throw new Error(`Web asset directory must contain index.html: ${source}`);
   }
 }
+function resolveRuntimeDir(override) {
+  if (override === null)
+    return null;
+  const dir = override ?? process.env.CRAFT_IOS_RUNTIME;
+  if (!dir)
+    return null;
+  if (!existsSync4(dir)) {
+    const source = override === undefined ? "CRAFT_IOS_RUNTIME points at" : "runtimeDir is";
+    throw new Error(`${source} ${dir}, which does not exist.`);
+  }
+  return dir;
+}
+async function installRuntime(output, runtimeDir) {
+  const resolved = Object.entries(RUNTIME_ARCHIVES).map(([sdk, archives]) => {
+    const present = archives.filter((a) => existsSync4(join2(runtimeDir, a)));
+    if (present.length === 0) {
+      throw new Error(`${runtimeDir} has none of ${archives.join(", ")}. ` + `Run \`zig build build-ios-all\` in packages/zig and point at its zig-out/lib.`);
+    }
+    return { sdk, archives, present };
+  });
+  const dest = join2(output, "Runtime");
+  rmSync2(dest, { recursive: true, force: true });
+  for (const { sdk, archives, present } of resolved) {
+    const sdkDir = join2(dest, sdk);
+    mkdirSync2(sdkDir, { recursive: true });
+    const target = join2(sdkDir, "libcraft-ios.a");
+    if (present.length === 1) {
+      const missing = archives.filter((a) => !present.includes(a));
+      if (missing.length > 0) {
+        console.warn(`   \u26A0 ${sdk}: only ${present[0]} was found; ${missing.join(", ")} is missing. ` + `The generated project will not link on the other architecture.`);
+      }
+      cpSync2(join2(runtimeDir, present[0]), target);
+    } else {
+      await $`lipo -create ${present.map((a) => join2(runtimeDir, a))} -output ${target}`.quiet();
+    }
+  }
+  return true;
+}
+async function refreshRuntime(output, override) {
+  if (!existsSync4(join2(output, "Runtime")))
+    return;
+  const dir = resolveRuntimeDir(override);
+  if (!dir) {
+    console.log("   Keeping the Zig runtime installed at init (no runtime directory configured)");
+    return;
+  }
+  await installRuntime(output, dir);
+  console.log("   Refreshed the Zig runtime from", dir);
+}
 async function init(options) {
   const { name, bundleId, teamId, output } = options;
   console.log(`
@@ -1368,7 +1428,14 @@ async function init(options) {
       SWIFT_VERSION: "5.0"
       SKIP_INSTALL: YES`);
   }
-  const projectYml = projectYmlTemplate.replace(/\{\{APP_NAME\}\}/g, name).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId).replace(/\{\{BUNDLE_ID_PREFIX\}\}/g, bundleIdPrefix).replace(/\{\{VERSION\}\}/g, config.version || "1.0.0").replace(/\{\{BUILD_NUMBER\}\}/g, config.buildNumber || "1").replace(/\{\{IOS_VERSION\}\}/g, config.iosVersion || "15.0").replace(/\{\{DEVICE_FAMILIES\}\}/g, renderDeviceFamilies(config)).replace(/\{\{TEAM_ID\}\}/g, teamId || "").replace(/\{\{NATIVE_DEPENDENCIES\}\}/g, nativeDependencies.length ? `    dependencies:
+  const runtimeDir = resolveRuntimeDir(options.runtimeDir);
+  const hasRuntime = runtimeDir ? await installRuntime(output, runtimeDir) : false;
+  if (hasRuntime) {
+    console.log("   Linked the Zig runtime from", runtimeDir);
+  } else {
+    rmSync2(join2(output, "Runtime"), { recursive: true, force: true });
+  }
+  const projectYml = projectYmlTemplate.replace(/\{\{CRAFT_RUNTIME_SETTINGS\}\}/g, hasRuntime ? renderRuntimeSettings() : "").replace(/\{\{APP_NAME\}\}/g, name).replace(/\{\{BUNDLE_ID\}\}/g, finalBundleId).replace(/\{\{BUNDLE_ID_PREFIX\}\}/g, bundleIdPrefix).replace(/\{\{VERSION\}\}/g, config.version || "1.0.0").replace(/\{\{BUILD_NUMBER\}\}/g, config.buildNumber || "1").replace(/\{\{IOS_VERSION\}\}/g, config.iosVersion || "15.0").replace(/\{\{DEVICE_FAMILIES\}\}/g, renderDeviceFamilies(config)).replace(/\{\{TEAM_ID\}\}/g, teamId || "").replace(/\{\{NATIVE_DEPENDENCIES\}\}/g, nativeDependencies.length ? `    dependencies:
 ${nativeDependencies.join(`
 `)}` : "").replace(/\{\{NATIVE_TARGETS\}\}/g, nativeTargets.join(`
 `));
@@ -1459,6 +1526,7 @@ async function build(options) {
     syncWebAssets(htmlPath, output);
     console.log(`   Synced: ${htmlPath} \u2192 dist/`);
   }
+  await refreshRuntime(output, options.runtimeDir);
   if (!generateProject)
     return;
   try {
@@ -1580,7 +1648,7 @@ async function run(options) {
     console.log("  4. Click Run (\u25B6\uFE0F)");
   }
 }
-var $, TEMPLATES_DIR, DEFAULT_CONFIG;
+var $, TEMPLATES_DIR, DEFAULT_CONFIG, RUNTIME_ARCHIVES;
 var init_src = __esm(() => {
   ({ $ } = globalThis.Bun);
   TEMPLATES_DIR = join2(dirname(import.meta.dir), "templates");
@@ -1633,6 +1701,10 @@ var init_src = __esm(() => {
     orientations: ["portrait"],
     deviceFamilies: ["iphone", "ipad"]
   };
+  RUNTIME_ARCHIVES = {
+    device: ["libcraft-ios.a"],
+    simulator: ["libcraft-ios-simulator-arm64.a", "libcraft-ios-simulator-x64.a"]
+  };
 });
 
 // dist/android/src/index.js
@@ -4191,7 +4263,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.86";
+var version = "0.0.88";
 
 // bin/cli.ts
 var spawnedFrom = process6.env[CRAFT_CLI_SPAWN_MARKER];