craft-native 0.0.75 → 0.0.77

package/dist/cli.js

@@ -22,9 +22,12 @@ var exports_package = {};
 __export(exports_package, {
   windowsExecutableName: () => windowsExecutableName,
   windowsArchitecture: () => windowsArchitecture,
+  urlTypesEntry: () => urlTypesEntry,
   shouldRetryHdiutil: () => shouldRetryHdiutil,
   renderWixSource: () => renderWixSource,
   productbuildArguments: () => productbuildArguments,
+  pkgbuildComponentPlist: () => pkgbuildComponentPlist,
+  pkgbuildArguments: () => pkgbuildArguments,
   packageApp: () => packageApp,
   pack: () => pack,
   notarytoolArguments: () => notarytoolArguments,
@@ -162,6 +165,7 @@ async function packageMacOS(config, outDir) {
     category: opts.category,
     minimumSystemVersion: opts.minimumSystemVersion,
     menuBarOnly: opts.menuBarOnly,
+    urlSchemes: opts.urlSchemes,
     binaryPath: config.binaryPath,
     iconPath: config.iconPath,
     provisioningProfile: opts.provisioningProfile,
@@ -358,6 +362,36 @@ async function packageLinux(config, outDir) {
   }
   return results;
 }
+function urlTypesEntry(bundleId, schemes) {
+  const seen = new Set;
+  const unique = [];
+  for (const scheme of schemes) {
+    if (!URL_SCHEME.test(scheme))
+      throw new Error(`Invalid URL scheme ${JSON.stringify(scheme)}: must start with a letter and contain only letters, digits, "+", "-" or "."`);
+    const key = scheme.toLowerCase();
+    if (seen.has(key))
+      continue;
+    seen.add(key);
+    unique.push(scheme);
+  }
+  if (unique.length === 0)
+    return null;
+  const list = unique.map((scheme) => `          <string>${xml(scheme)}</string>`).join(`
+`);
+  return `    <key>CFBundleURLTypes</key>
+    <array>
+      <dict>
+        <key>CFBundleURLName</key>
+        <string>${xml(bundleId)}</string>
+        <key>CFBundleTypeRole</key>
+        <string>Viewer</string>
+        <key>CFBundleURLSchemes</key>
+        <array>
+${list}
+        </array>
+      </dict>
+    </array>`;
+}
 function macOSInfoPlist(metadata) {
   const entries = [
     ["CFBundleExecutable", metadata.name],
@@ -376,9 +410,12 @@ function macOSInfoPlist(metadata) {
     entries.push(["LSMinimumSystemVersion", metadata.minimumSystemVersion]);
   if (metadata.menuBarOnly)
     entries.push(["LSUIElement", true]);
-  const body = entries.map(([key, value]) => `    <key>${xml(key)}</key>
+  const scalars = entries.map(([key, value]) => `    <key>${xml(key)}</key>
 ${value === true ? "    <true/>" : `    <string>${xml(value)}</string>`}`).join(`
 `);
+  const urlTypes = urlTypesEntry(metadata.bundleId, metadata.urlSchemes || []);
+  const body = urlTypes ? `${scalars}
+${urlTypes}` : scalars;
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -528,6 +565,43 @@ async function createDMG(opts) {
   return { success: false, error: failures.join(`
 `) };
 }
+function pkgbuildComponentPlist(rootRelativeBundlePath) {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<array>
+    <dict>
+        <key>BundleHasStrictIdentifier</key>
+        <true/>
+        <key>BundleIsRelocatable</key>
+        <false/>
+        <key>BundleIsVersionChecked</key>
+        <false/>
+        <key>BundleOverwriteAction</key>
+        <string>upgrade</string>
+        <key>RootRelativeBundlePath</key>
+        <string>${xml(rootRelativeBundlePath)}</string>
+    </dict>
+</array>
+</plist>
+`;
+}
+function pkgbuildArguments(opts) {
+  return [
+    "--root",
+    opts.root,
+    "--component-plist",
+    opts.componentPlistPath,
+    "--identifier",
+    opts.identifier,
+    "--version",
+    opts.version,
+    "--install-location",
+    "/",
+    ...opts.installerIdentity ? ["--sign", opts.installerIdentity] : [],
+    opts.outputPath
+  ];
+}
 async function createPKG(opts) {
   if (!/^[a-zA-Z0-9._-]+$/.test(opts.identifier) || !opts.identifier.includes("."))
     return { success: false, error: `Invalid pkg identifier "${opts.identifier}"; expected reverse-DNS like com.example.app` };
@@ -545,21 +619,22 @@ async function createPKG(opts) {
   }
   const tempDir = mkdtempSync(join(tmpdir(), "craft-pkg-"));
   try {
-    const appsDir = join(tempDir, "Applications");
-    mkdirSync(appsDir, { recursive: true });
-    cpSync(opts.appBundlePath, join(appsDir, basename(opts.appBundlePath)), { recursive: true });
-    const built = await runTool("pkgbuild", [
-      "--root",
-      tempDir,
-      "--identifier",
-      opts.identifier,
-      "--version",
-      opts.version,
-      "--install-location",
-      "/",
-      ...opts.installerIdentity ? ["--sign", opts.installerIdentity] : [],
-      opts.outputPath
-    ]);
+    const root = join(tempDir, "root");
+    const appsDir = join(root, "Applications");
+    mkdirSync(appsDir, { recursive: true, mode: 493 });
+    chmodSync(root, 493);
+    const bundleName = basename(opts.appBundlePath);
+    cpSync(opts.appBundlePath, join(appsDir, bundleName), { recursive: true });
+    const componentPlistPath = join(tempDir, "component.plist");
+    writeFileSync(componentPlistPath, pkgbuildComponentPlist(`Applications/${bundleName}`));
+    const built = await runTool("pkgbuild", pkgbuildArguments({
+      root,
+      componentPlistPath,
+      identifier: opts.identifier,
+      version: opts.version,
+      outputPath: opts.outputPath,
+      installerIdentity: opts.installerIdentity
+    }));
     return built.success ? { success: true, outputPath: opts.outputPath } : { success: false, error: built.error };
   } finally {
     rmSync(tempDir, { recursive: true, force: true });
@@ -956,7 +1031,7 @@ async function pack(options) {
     platforms: [detectPlatform()]
   });
 }
-var CRC32_TABLE, MEBIBYTE, HDIUTIL_MAX_ATTEMPTS = 3, runHdiutil = (args) => runTool("hdiutil", args);
+var CRC32_TABLE, URL_SCHEME, MEBIBYTE, HDIUTIL_MAX_ATTEMPTS = 3, runHdiutil = (args) => runTool("hdiutil", args);
 var init_package = __esm(() => {
   CRC32_TABLE = (() => {
     const table = new Uint32Array(256);
@@ -968,6 +1043,7 @@ var init_package = __esm(() => {
     }
     return table;
   })();
+  URL_SCHEME = /^[a-z][a-z0-9+.-]*$/i;
   MEBIBYTE = 1024 * 1024;
 });
 
@@ -2124,90 +2200,6 @@ class Telemetry {
   }
 }
 var telemetry = new Telemetry;
-function parseArgv(argv, opts = {}) {
-  const result = { _: [] };
-  const alias = opts.alias || {};
-  const booleans = new Set(opts.boolean || []);
-  const aliasOf = {};
-  for (const key of Object.keys(alias)) {
-    for (const a of alias[key]) {
-      aliasOf[a] = key;
-    }
-  }
-  for (const b of booleans) {
-    if (alias[b]) {
-      for (const a of alias[b])
-        booleans.add(a);
-    }
-  }
-  function setKey(key, value) {
-    const canonical = aliasOf[key] || key;
-    result[canonical] = value;
-    if (alias[canonical]) {
-      for (const a of alias[canonical])
-        result[a] = value;
-    }
-    if (aliasOf[key] && alias[aliasOf[key]]) {
-      for (const a of alias[aliasOf[key]])
-        result[a] = value;
-    }
-    result[key] = value;
-  }
-  for (let i = 0;i < argv.length; i++) {
-    const arg = argv[i];
-    if (arg === "--") {
-      result._.push(...argv.slice(i + 1));
-      break;
-    }
-    if (arg.startsWith("--")) {
-      const eqIdx = arg.indexOf("=");
-      if (eqIdx !== -1) {
-        const key = arg.slice(2, eqIdx);
-        const value = arg.slice(eqIdx + 1);
-        setKey(key, value);
-      } else {
-        const key = arg.slice(2);
-        if (key.startsWith("no-")) {
-          const actualKey = key.slice(3);
-          setKey(actualKey, false);
-          continue;
-        }
-        const canonical = aliasOf[key] || key;
-        if (booleans.has(canonical) || booleans.has(key)) {
-          setKey(key, true);
-        } else {
-          const next = argv[i + 1];
-          if (next !== undefined && !next.startsWith("-")) {
-            setKey(key, next);
-            i++;
-          } else {
-            setKey(key, true);
-          }
-        }
-      }
-    } else if (arg.startsWith("-") && arg.length > 1) {
-      const chars = arg.slice(1);
-      for (let j = 0;j < chars.length; j++) {
-        const ch = chars[j];
-        const canonical = aliasOf[ch] || ch;
-        if (j === chars.length - 1 && !booleans.has(canonical) && !booleans.has(ch)) {
-          const next = argv[i + 1];
-          if (next !== undefined && !next.startsWith("-")) {
-            setKey(ch, next);
-            i++;
-          } else {
-            setKey(ch, true);
-          }
-        } else {
-          setKey(ch, true);
-        }
-      }
-    } else {
-      result._.push(arg);
-    }
-  }
-  return result;
-}
 function removeBrackets(v) {
   return v.replace(/[<[].+/, "").trim();
 }
@@ -2304,9 +2296,13 @@ function camelcaseOptionName(name) {
 class ClappError extends Error {
   exitCode = 2;
   isUsageError = true;
-  constructor(message) {
+  usage;
+  constructor(message, usage) {
     super(message);
     this.name = this.constructor.name;
+    if (usage !== undefined) {
+      this.usage = usage;
+    }
     if (typeof Error.captureStackTrace === "function") {
       Error.captureStackTrace(this, this.constructor);
     } else {
@@ -2323,6 +2319,12 @@ ${this.stack}`;
     return this.message;
   }
 }
+function isClappError(err) {
+  if (err instanceof ClappError) {
+    return true;
+  }
+  return !!err && typeof err === "object" && err.name === "ClappError" && typeof err.message === "string";
+}
 function isUnicodeSupported() {
   const { env } = process22;
   const { TERM, TERM_PROGRAM } = env;
@@ -2404,6 +2406,99 @@ function levenshteinDistance(a, b) {
 function findSimilarCommands(input, commands, maxDistance = 2, maxSuggestions = 3) {
   return commands.map((cmd) => ({ cmd, distance: levenshteinDistance(input, cmd) })).filter(({ distance }) => distance <= maxDistance).sort((a, b) => a.distance - b.distance).slice(0, maxSuggestions).map(({ cmd }) => cmd);
 }
+function parseArgv(argv, opts = {}) {
+  const result = { _: [] };
+  const alias = opts.alias || {};
+  const booleans = new Set(opts.boolean || []);
+  const aliasOf = {};
+  for (const key of Object.keys(alias)) {
+    for (const a of alias[key]) {
+      aliasOf[a] = key;
+    }
+  }
+  for (const b of booleans) {
+    if (alias[b]) {
+      for (const a of alias[b])
+        booleans.add(a);
+    }
+  }
+  function merge(existing, value) {
+    if (existing === undefined)
+      return value;
+    if (typeof value === "boolean")
+      return value;
+    return Array.isArray(existing) ? [...existing, value] : [existing, value];
+  }
+  function setKey(key, value) {
+    const canonical = aliasOf[key] || key;
+    const merged = merge(result[canonical], value);
+    result[canonical] = merged;
+    if (alias[canonical]) {
+      for (const a of alias[canonical])
+        result[a] = merged;
+    }
+    if (aliasOf[key] && alias[aliasOf[key]]) {
+      for (const a of alias[aliasOf[key]])
+        result[a] = merged;
+    }
+    result[key] = merged;
+  }
+  for (let i = 0;i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--") {
+      result._.push(...argv.slice(i + 1));
+      break;
+    }
+    if (arg.startsWith("--")) {
+      const eqIdx = arg.indexOf("=");
+      if (eqIdx !== -1) {
+        const key = camelcase(arg.slice(2, eqIdx));
+        const value = arg.slice(eqIdx + 1);
+        setKey(key, value);
+      } else {
+        const rawKey = arg.slice(2);
+        if (rawKey.startsWith("no-")) {
+          const actualKey = camelcase(rawKey.slice(3));
+          setKey(actualKey, false);
+          continue;
+        }
+        const key = camelcase(rawKey);
+        const canonical = aliasOf[key] || key;
+        if (booleans.has(canonical) || booleans.has(key)) {
+          setKey(key, true);
+        } else {
+          const next = argv[i + 1];
+          if (next !== undefined && !next.startsWith("-")) {
+            setKey(key, next);
+            i++;
+          } else {
+            setKey(key, true);
+          }
+        }
+      }
+    } else if (arg.startsWith("-") && arg.length > 1) {
+      const chars = arg.slice(1);
+      for (let j = 0;j < chars.length; j++) {
+        const ch = chars[j];
+        const canonical = aliasOf[ch] || ch;
+        if (j === chars.length - 1 && !booleans.has(canonical) && !booleans.has(ch)) {
+          const next = argv[i + 1];
+          if (next !== undefined && !next.startsWith("-")) {
+            setKey(ch, next);
+            i++;
+          } else {
+            setKey(ch, true);
+          }
+        } else {
+          setKey(ch, true);
+        }
+      }
+    } else {
+      result._.push(arg);
+    }
+  }
+  return result;
+}
 
 class Option {
   rawName;
@@ -2551,9 +2646,9 @@ class Command {
     return this.namespace ? `${this.namespace}:${this.name}` : this.name;
   }
   hasOption(name) {
-    name = name.split(".")[0];
+    const normalized = camelcaseOptionName(name.split(".")[0]);
     return !!this.options.find((option) => {
-      return option.names.includes(name);
+      return option.names.some((optionName) => camelcaseOptionName(optionName) === normalized);
     });
   }
   outputHelp() {
@@ -2588,6 +2683,7 @@ class Command {
         }
       }
       let commandBody = "";
+      noNamespaceCommands.sort((a, b) => a.rawName < b.rawName ? -1 : a.rawName > b.rawName ? 1 : 0);
       if (noNamespaceCommands.length > 0) {
         commandBody += noNamespaceCommands.map((command) => {
           return `  ${padRight(command.rawName, longestCommandName.length)}  ${command.description}`;
@@ -2614,12 +2710,14 @@ class Command {
         body: commandBody
       });
       sections.push({
-        title: `For more info, run any command with the \`--help\` flag`,
-        body: commands.map((command) => `  $ ${name}${command.displayName === "" ? "" : ` ${command.displayName}`} --help`).join(`
-`)
+        body: `Run \`${name} <command> --help\` for command details.`
       });
     }
-    let options = this.isGlobalCommand ? globalOptions : [...this.options, ...globalOptions || []];
+    const localOptionNames = new Set(this.options.flatMap((option) => option.names));
+    let options = this.isGlobalCommand ? globalOptions : [
+      ...this.options,
+      ...(globalOptions || []).filter((option) => !option.names.some((name2) => localOptionNames.has(name2)))
+    ];
     if (!this.isGlobalCommand && !this.isDefaultCommand) {
       options = options.filter((option) => option.name !== "version");
     }
@@ -2663,6 +2761,9 @@ ${section.body}` : section.body;
       console.log(`${name}/${versionNumber} ${platformInfo3}`);
     }
   }
+  get usageLine() {
+    return `$ ${this.cli.name} ${this.usageText || this.rawName}`;
+  }
   checkRequiredArgs() {
     const minimalArgsCount = this.args.filter((arg) => arg.required).length;
     if (this.cli.args.length < minimalArgsCount) {
@@ -2671,7 +2772,7 @@ ${section.body}` : section.body;
       const argNames = missingArgs.map((arg) => `<${arg.value}>`).join(" ");
       throw new ClappError(`Missing required argument${missingArgs.length > 1 ? "s" : ""}: ${argNames}
 
-` + `Run \`${this.cli.name} ${this.rawName} --help\` for usage information.`);
+` + `Run \`${this.cli.name} ${this.rawName} --help\` for usage information.`, this.usageLine);
     }
   }
   checkUnknownOptions() {
@@ -2681,8 +2782,9 @@ ${section.body}` : section.body;
         if (name !== "--" && !this.hasOption(name) && !globalCommand.hasOption(name)) {
           const allOptions = [...globalCommand.options, ...this.options];
           const allOptionNames = allOptions.flatMap((opt) => opt.names);
+          const normalizedName = camelcaseOptionName(name.split(".")[0]);
           const optionFlag = name.length > 1 ? `--${name}` : `-${name}`;
-          const suggestions = findSimilarCommands(name, allOptionNames);
+          const suggestions = findSimilarCommands(normalizedName, allOptionNames);
           let errorMsg = `Unknown option \`${optionFlag}\``;
           if (suggestions.length > 0) {
             errorMsg += `
@@ -2697,7 +2799,7 @@ Did you mean one of these?`;
           errorMsg += `
 
 Run \`${this.cli.name} ${this.rawName} --help\` to see available options.`;
-          throw new ClappError(errorMsg);
+          throw new ClappError(errorMsg, this.usageLine);
         }
       }
     }
@@ -2712,7 +2814,7 @@ Run \`${this.cli.name} ${this.rawName} --help\` to see available options.`;
         if (value === true || value === false && !hasNegated) {
           throw new ClappError(`Option \`${option.rawName}\` requires a value.
 
-` + `Example: ${this.cli.name} ${this.rawName} ${option.rawName} <value>`);
+` + `Example: ${this.cli.name} ${this.rawName} ${option.rawName} <value>`, this.usageLine);
         }
       }
     }
@@ -3018,6 +3120,25 @@ Received ${signal}, cleaning up...`);
           break;
         }
       }
+      if (shouldParse) {
+        const nextToken = slicedArgv[1];
+        if (nextToken && !nextToken.startsWith("-")) {
+          const joinedName = `${candidateName}:${nextToken}`;
+          for (const command of this.commands) {
+            if (command.isMatched(joinedName)) {
+              const parsed = this.mri(slicedArgv, command);
+              shouldParse = false;
+              const parsedInfo = {
+                ...parsed,
+                args: parsed.args.slice(2)
+              };
+              this.setParsedInfo(parsedInfo, command, joinedName);
+              this.emit(`command:${joinedName}`, command);
+              break;
+            }
+          }
+        }
+      }
     }
     if (shouldParse) {
       for (const command of this.commands) {
@@ -3043,7 +3164,7 @@ Received ${signal}, cleaning up...`);
     if (this.options.debug) {
       this.isDebug = true;
     }
-    if (this.options.noInteraction) {
+    if (this.options.noInteraction || this.options.interaction === false) {
       this.isNoInteraction = true;
     }
     if (this.options.env) {
@@ -3055,14 +3176,14 @@ Received ${signal}, cleaning up...`);
     if (this.options.force) {
       this.isForce = true;
     }
-    if (this.options.noEmoji !== undefined) {
-      this.useEmoji = !this.options.noEmoji;
+    if (this.options.noEmoji || this.options.emoji === false) {
+      this.useEmoji = false;
     }
     if (this.options.theme) {
       this.theme = String(this.options.theme);
     }
-    if (this.options.noCache !== undefined) {
-      this.isNoCache = Boolean(this.options.noCache);
+    if (this.options.noCache || this.options.cache === false) {
+      this.isNoCache = true;
     }
     if (this.options.help && this.showHelpOnExit) {
       this.outputHelp();
@@ -3143,18 +3264,16 @@ Received ${signal}, cleaning up...`);
     return this.parse(argv, { run: true, exitOnError: true });
   }
   handleUsageError(err) {
-    const isClappError = !!err && typeof err === "object" && err.name === "ClappError";
-    const isUsage = isClappError && err.isUsageError !== false;
-    if (!isUsage)
+    if (!isClappError(err) || err.isUsageError === false)
       return;
-    const e = err;
-    const raw = e.message ?? "command-line error";
+    const raw = err.message || "command-line error";
     const label = this.name ? `${this.name}: ` : "";
-    const suffix = /--help/.test(raw) ? "" : `
+    const suffix = /--help/.test(raw) ? "" : err.usage ? `
+Usage: ${err.usage}` : `
 Run \`${this.name ?? "cli"} --help\` for usage.`;
     process5.stderr.write(`${label}${raw}${suffix}
 `);
-    process5.exit(e.exitCode ?? 2);
+    process5.exit(err.exitCode ?? 2);
   }
   async runMatchedCommand() {
     const { args, options, matchedCommand: command } = this;
@@ -4072,7 +4191,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.75";
+var version = "0.0.77";
 
 // bin/cli.ts
 var spawnedFrom = process6.env[CRAFT_CLI_SPAWN_MARKER];

package/dist/index.cjs

@@ -425,6 +425,7 @@ async function packageMacOS(config, outDir) {
     category: opts.category,
     minimumSystemVersion: opts.minimumSystemVersion,
     menuBarOnly: opts.menuBarOnly,
+    urlSchemes: opts.urlSchemes,
     binaryPath: config.binaryPath,
     iconPath: config.iconPath,
     provisioningProfile: opts.provisioningProfile,
@@ -621,6 +622,37 @@ async function packageLinux(config, outDir) {
   }
   return results;
 }
+var URL_SCHEME = /^[a-z][a-z0-9+.-]*$/i;
+function urlTypesEntry(bundleId, schemes) {
+  const seen = new Set;
+  const unique = [];
+  for (const scheme of schemes) {
+    if (!URL_SCHEME.test(scheme))
+      throw new Error(`Invalid URL scheme ${JSON.stringify(scheme)}: must start with a letter and contain only letters, digits, "+", "-" or "."`);
+    const key = scheme.toLowerCase();
+    if (seen.has(key))
+      continue;
+    seen.add(key);
+    unique.push(scheme);
+  }
+  if (unique.length === 0)
+    return null;
+  const list = unique.map((scheme) => `          <string>${xml(scheme)}</string>`).join(`
+`);
+  return `    <key>CFBundleURLTypes</key>
+    <array>
+      <dict>
+        <key>CFBundleURLName</key>
+        <string>${xml(bundleId)}</string>
+        <key>CFBundleTypeRole</key>
+        <string>Viewer</string>
+        <key>CFBundleURLSchemes</key>
+        <array>
+${list}
+        </array>
+      </dict>
+    </array>`;
+}
 function macOSInfoPlist(metadata) {
   const entries = [
     ["CFBundleExecutable", metadata.name],
@@ -639,9 +671,12 @@ function macOSInfoPlist(metadata) {
     entries.push(["LSMinimumSystemVersion", metadata.minimumSystemVersion]);
   if (metadata.menuBarOnly)
     entries.push(["LSUIElement", true]);
-  const body = entries.map(([key, value]) => `    <key>${xml(key)}</key>
+  const scalars = entries.map(([key, value]) => `    <key>${xml(key)}</key>
 ${value === true ? "    <true/>" : `    <string>${xml(value)}</string>`}`).join(`
 `);
+  const urlTypes = urlTypesEntry(metadata.bundleId, metadata.urlSchemes || []);
+  const body = urlTypes ? `${scalars}
+${urlTypes}` : scalars;
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -794,6 +829,43 @@ async function createDMG(opts) {
   return { success: false, error: failures.join(`
 `) };
 }
+function pkgbuildComponentPlist(rootRelativeBundlePath) {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<array>
+    <dict>
+        <key>BundleHasStrictIdentifier</key>
+        <true/>
+        <key>BundleIsRelocatable</key>
+        <false/>
+        <key>BundleIsVersionChecked</key>
+        <false/>
+        <key>BundleOverwriteAction</key>
+        <string>upgrade</string>
+        <key>RootRelativeBundlePath</key>
+        <string>${xml(rootRelativeBundlePath)}</string>
+    </dict>
+</array>
+</plist>
+`;
+}
+function pkgbuildArguments(opts) {
+  return [
+    "--root",
+    opts.root,
+    "--component-plist",
+    opts.componentPlistPath,
+    "--identifier",
+    opts.identifier,
+    "--version",
+    opts.version,
+    "--install-location",
+    "/",
+    ...opts.installerIdentity ? ["--sign", opts.installerIdentity] : [],
+    opts.outputPath
+  ];
+}
 async function createPKG(opts) {
   if (!/^[a-zA-Z0-9._-]+$/.test(opts.identifier) || !opts.identifier.includes("."))
     return { success: false, error: `Invalid pkg identifier "${opts.identifier}"; expected reverse-DNS like com.example.app` };
@@ -811,21 +883,22 @@ async function createPKG(opts) {
   }
   const tempDir = import_fs.mkdtempSync(import_path.join(import_os.tmpdir(), "craft-pkg-"));
   try {
-    const appsDir = import_path.join(tempDir, "Applications");
-    import_fs.mkdirSync(appsDir, { recursive: true });
-    import_fs.cpSync(opts.appBundlePath, import_path.join(appsDir, import_path.basename(opts.appBundlePath)), { recursive: true });
-    const built = await runTool("pkgbuild", [
-      "--root",
-      tempDir,
-      "--identifier",
-      opts.identifier,
-      "--version",
-      opts.version,
-      "--install-location",
-      "/",
-      ...opts.installerIdentity ? ["--sign", opts.installerIdentity] : [],
-      opts.outputPath
-    ]);
+    const root = import_path.join(tempDir, "root");
+    const appsDir = import_path.join(root, "Applications");
+    import_fs.mkdirSync(appsDir, { recursive: true, mode: 493 });
+    import_fs.chmodSync(root, 493);
+    const bundleName = import_path.basename(opts.appBundlePath);
+    import_fs.cpSync(opts.appBundlePath, import_path.join(appsDir, bundleName), { recursive: true });
+    const componentPlistPath = import_path.join(tempDir, "component.plist");
+    import_fs.writeFileSync(componentPlistPath, pkgbuildComponentPlist(`Applications/${bundleName}`));
+    const built = await runTool("pkgbuild", pkgbuildArguments({
+      root,
+      componentPlistPath,
+      identifier: opts.identifier,
+      version: opts.version,
+      outputPath: opts.outputPath,
+      installerIdentity: opts.installerIdentity
+    }));
     return built.success ? { success: true, outputPath: opts.outputPath } : { success: false, error: built.error };
   } finally {
     import_fs.rmSync(tempDir, { recursive: true, force: true });
@@ -10624,7 +10697,9 @@ class CraftApp {
   }
   buildArgs() {
     const args = [];
-    const { window: window3, html, url } = this.config;
+    const { window: window3, html, url, appName } = this.config;
+    if (appName)
+      args.push("--app-name", appName);
     if (!window3?.menubarOnly) {
       if (url) {
         args.push("--url", url);
@@ -10658,6 +10733,8 @@ class CraftApp {
       args.push("--hot-reload");
     if (window3?.devTools === false)
       args.push("--no-devtools");
+    else if (window3?.devTools === true)
+      args.push("--dev-tools");
     if (window3?.systemTray)
       args.push("--system-tray");
     if (window3?.hideDockIcon)
@@ -10666,6 +10743,8 @@ class CraftApp {
       args.push("--menubar-only");
     if (window3?.titlebarHidden)
       args.push("--titlebar-hidden");
+    if (window3?.headless)
+      args.push("--headless");
     if (window3?.webSidebarMaterial) {
       args.push("--web-sidebar-material");
       if (window3?.webSidebarWidth)
@@ -10675,6 +10754,8 @@ class CraftApp {
     }
     if (window3?.icon)
       args.push("--icon", window3.icon);
+    if (window3?.frameAutosave)
+      args.push("--frame-autosave", window3.frameAutosave);
     if (window3?.nativeSidebar) {
       args.push("--native-sidebar");
       if (window3?.sidebarWidth)

package/dist/index.d.cts

@@ -59,4 +59,4 @@ export declare function show(html: string, options?: WindowOptions): Promise<voi
  * Quick helper to load a URL
  */
 export declare function loadURL(url: string, options?: WindowOptions): Promise<void>;
-export type { WindowOptions, CraftSidebarAPI, AppConfig, CraftTrayAPI, CraftWindowAPI, CraftAppAPI, CraftBridgeAPI, Permission, HapticType, CameraOptions, PhotoPickerOptions, CraftMobileAPI, CraftFileSystemAPI, CraftDatabaseAPI, CraftHttpAPI, CraftCryptoAPI, CraftEventType, CraftEventMap, CraftEventHandler, CraftEventEmitter, IOSConfig, AndroidConfig, MacOSConfig, WindowsConfig, LinuxConfig, CraftAppConfig, } from './types.js';
+export type { WindowOptions, CraftSidebarAPI, AppConfig, CraftTrayAPI, CraftWindowAPI, CraftAppAPI, CraftBridgeAPI, Permission, HapticType, CameraOptions, PhotoPickerOptions, CraftMobileAPI, CraftFileSystemAPI, CraftDatabaseAPI, CraftHttpAPI, CraftCryptoAPI, CraftCapabilities, CapabilityNamespace, CapabilityNamespaceStatus, CapabilityAction, CraftPreferencesAPI, CraftPreferencesInfo, CraftSettingsAPI, PreferenceValue, CraftEventType, CraftEventMap, CraftEventHandler, CraftEventEmitter, IOSConfig, AndroidConfig, MacOSConfig, WindowsConfig, LinuxConfig, CraftAppConfig, } from './types.js';

package/dist/index.d.ts

@@ -59,4 +59,4 @@ export declare function show(html: string, options?: WindowOptions): Promise<voi
  * Quick helper to load a URL
  */
 export declare function loadURL(url: string, options?: WindowOptions): Promise<void>;
-export type { WindowOptions, CraftSidebarAPI, AppConfig, CraftTrayAPI, CraftWindowAPI, CraftAppAPI, CraftBridgeAPI, Permission, HapticType, CameraOptions, PhotoPickerOptions, CraftMobileAPI, CraftFileSystemAPI, CraftDatabaseAPI, CraftHttpAPI, CraftCryptoAPI, CraftEventType, CraftEventMap, CraftEventHandler, CraftEventEmitter, IOSConfig, AndroidConfig, MacOSConfig, WindowsConfig, LinuxConfig, CraftAppConfig, } from './types.js';
+export type { WindowOptions, CraftSidebarAPI, AppConfig, CraftTrayAPI, CraftWindowAPI, CraftAppAPI, CraftBridgeAPI, Permission, HapticType, CameraOptions, PhotoPickerOptions, CraftMobileAPI, CraftFileSystemAPI, CraftDatabaseAPI, CraftHttpAPI, CraftCryptoAPI, CraftCapabilities, CapabilityNamespace, CapabilityNamespaceStatus, CapabilityAction, CraftPreferencesAPI, CraftPreferencesInfo, CraftSettingsAPI, PreferenceValue, CraftEventType, CraftEventMap, CraftEventHandler, CraftEventEmitter, IOSConfig, AndroidConfig, MacOSConfig, WindowsConfig, LinuxConfig, CraftAppConfig, } from './types.js';

package/dist/index.js

@@ -195,6 +195,7 @@ async function packageMacOS(config, outDir) {
     category: opts.category,
     minimumSystemVersion: opts.minimumSystemVersion,
     menuBarOnly: opts.menuBarOnly,
+    urlSchemes: opts.urlSchemes,
     binaryPath: config.binaryPath,
     iconPath: config.iconPath,
     provisioningProfile: opts.provisioningProfile,
@@ -391,6 +392,37 @@ async function packageLinux(config, outDir) {
   }
   return results;
 }
+var URL_SCHEME = /^[a-z][a-z0-9+.-]*$/i;
+function urlTypesEntry(bundleId, schemes) {
+  const seen = new Set;
+  const unique = [];
+  for (const scheme of schemes) {
+    if (!URL_SCHEME.test(scheme))
+      throw new Error(`Invalid URL scheme ${JSON.stringify(scheme)}: must start with a letter and contain only letters, digits, "+", "-" or "."`);
+    const key = scheme.toLowerCase();
+    if (seen.has(key))
+      continue;
+    seen.add(key);
+    unique.push(scheme);
+  }
+  if (unique.length === 0)
+    return null;
+  const list = unique.map((scheme) => `          <string>${xml(scheme)}</string>`).join(`
+`);
+  return `    <key>CFBundleURLTypes</key>
+    <array>
+      <dict>
+        <key>CFBundleURLName</key>
+        <string>${xml(bundleId)}</string>
+        <key>CFBundleTypeRole</key>
+        <string>Viewer</string>
+        <key>CFBundleURLSchemes</key>
+        <array>
+${list}
+        </array>
+      </dict>
+    </array>`;
+}
 function macOSInfoPlist(metadata) {
   const entries = [
     ["CFBundleExecutable", metadata.name],
@@ -409,9 +441,12 @@ function macOSInfoPlist(metadata) {
     entries.push(["LSMinimumSystemVersion", metadata.minimumSystemVersion]);
   if (metadata.menuBarOnly)
     entries.push(["LSUIElement", true]);
-  const body = entries.map(([key, value]) => `    <key>${xml(key)}</key>
+  const scalars = entries.map(([key, value]) => `    <key>${xml(key)}</key>
 ${value === true ? "    <true/>" : `    <string>${xml(value)}</string>`}`).join(`
 `);
+  const urlTypes = urlTypesEntry(metadata.bundleId, metadata.urlSchemes || []);
+  const body = urlTypes ? `${scalars}
+${urlTypes}` : scalars;
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -564,6 +599,43 @@ async function createDMG(opts) {
   return { success: false, error: failures.join(`
 `) };
 }
+function pkgbuildComponentPlist(rootRelativeBundlePath) {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<array>
+    <dict>
+        <key>BundleHasStrictIdentifier</key>
+        <true/>
+        <key>BundleIsRelocatable</key>
+        <false/>
+        <key>BundleIsVersionChecked</key>
+        <false/>
+        <key>BundleOverwriteAction</key>
+        <string>upgrade</string>
+        <key>RootRelativeBundlePath</key>
+        <string>${xml(rootRelativeBundlePath)}</string>
+    </dict>
+</array>
+</plist>
+`;
+}
+function pkgbuildArguments(opts) {
+  return [
+    "--root",
+    opts.root,
+    "--component-plist",
+    opts.componentPlistPath,
+    "--identifier",
+    opts.identifier,
+    "--version",
+    opts.version,
+    "--install-location",
+    "/",
+    ...opts.installerIdentity ? ["--sign", opts.installerIdentity] : [],
+    opts.outputPath
+  ];
+}
 async function createPKG(opts) {
   if (!/^[a-zA-Z0-9._-]+$/.test(opts.identifier) || !opts.identifier.includes("."))
     return { success: false, error: `Invalid pkg identifier "${opts.identifier}"; expected reverse-DNS like com.example.app` };
@@ -581,21 +653,22 @@ async function createPKG(opts) {
   }
   const tempDir = mkdtempSync(join(tmpdir(), "craft-pkg-"));
   try {
-    const appsDir = join(tempDir, "Applications");
-    mkdirSync(appsDir, { recursive: true });
-    cpSync(opts.appBundlePath, join(appsDir, basename(opts.appBundlePath)), { recursive: true });
-    const built = await runTool("pkgbuild", [
-      "--root",
-      tempDir,
-      "--identifier",
-      opts.identifier,
-      "--version",
-      opts.version,
-      "--install-location",
-      "/",
-      ...opts.installerIdentity ? ["--sign", opts.installerIdentity] : [],
-      opts.outputPath
-    ]);
+    const root = join(tempDir, "root");
+    const appsDir = join(root, "Applications");
+    mkdirSync(appsDir, { recursive: true, mode: 493 });
+    chmodSync(root, 493);
+    const bundleName = basename(opts.appBundlePath);
+    cpSync(opts.appBundlePath, join(appsDir, bundleName), { recursive: true });
+    const componentPlistPath = join(tempDir, "component.plist");
+    writeFileSync(componentPlistPath, pkgbuildComponentPlist(`Applications/${bundleName}`));
+    const built = await runTool("pkgbuild", pkgbuildArguments({
+      root,
+      componentPlistPath,
+      identifier: opts.identifier,
+      version: opts.version,
+      outputPath: opts.outputPath,
+      installerIdentity: opts.installerIdentity
+    }));
     return built.success ? { success: true, outputPath: opts.outputPath } : { success: false, error: built.error };
   } finally {
     rmSync(tempDir, { recursive: true, force: true });
@@ -10394,7 +10467,9 @@ class CraftApp {
   }
   buildArgs() {
     const args = [];
-    const { window: window3, html, url } = this.config;
+    const { window: window3, html, url, appName } = this.config;
+    if (appName)
+      args.push("--app-name", appName);
     if (!window3?.menubarOnly) {
       if (url) {
         args.push("--url", url);
@@ -10428,6 +10503,8 @@ class CraftApp {
       args.push("--hot-reload");
     if (window3?.devTools === false)
       args.push("--no-devtools");
+    else if (window3?.devTools === true)
+      args.push("--dev-tools");
     if (window3?.systemTray)
       args.push("--system-tray");
     if (window3?.hideDockIcon)
@@ -10436,6 +10513,8 @@ class CraftApp {
       args.push("--menubar-only");
     if (window3?.titlebarHidden)
       args.push("--titlebar-hidden");
+    if (window3?.headless)
+      args.push("--headless");
     if (window3?.webSidebarMaterial) {
       args.push("--web-sidebar-material");
       if (window3?.webSidebarWidth)
@@ -10445,6 +10524,8 @@ class CraftApp {
     }
     if (window3?.icon)
       args.push("--icon", window3.icon);
+    if (window3?.frameAutosave)
+      args.push("--frame-autosave", window3.frameAutosave);
     if (window3?.nativeSidebar) {
       args.push("--native-sidebar");
       if (window3?.sidebarWidth)

package/dist/package.d.ts

@@ -74,6 +74,20 @@ export interface PackageConfig {
          * the helper lands next to `process.execPath`.
          */
         additionalExecutables?: string[];
+        /**
+         * URL schemes the app registers as a handler for — `['myapp']` makes
+         * `myapp://…` open it.
+         *
+         * Emitted as `CFBundleURLTypes`. Without this key macOS never dispatches
+         * a URL to the app at all, so Craft's receive path (the `kAEGetURL`
+         * AppleEvent handler behind `craft.deepLink`) can be fully working and
+         * still never hear anything.
+         *
+         * Schemes are matched case-insensitively by LaunchServices and are
+         * global to the machine: pick something specific to the app, not `app`
+         * or `open`.
+         */
+        urlSchemes?: string[];
     };
     /** Windows-specific options */
     windows?: {
@@ -138,7 +152,18 @@ export interface MacOSBundleMetadata {
     minimumSystemVersion?: string;
     /** Sets `LSUIElement` — no Dock icon, no app switcher entry */
     menuBarOnly?: boolean;
+    /** URL schemes the app handles, emitted as `CFBundleURLTypes` */
+    urlSchemes?: string[];
 }
+/**
+ * `CFBundleURLTypes` for the schemes an app handles, or `null` if it handles
+ * none.
+ *
+ * All the schemes go in one URL type. They are alternatives for reaching the
+ * same app, not different kinds of document, so splitting them across several
+ * dicts would only invent distinctions LaunchServices does not care about.
+ */
+export declare function urlTypesEntry(bundleId: string, schemes: readonly string[]): string | null;
 /**
  * Render `Contents/Info.plist` for a macOS app bundle.
  *
@@ -178,6 +203,50 @@ export declare function dmgCreateArguments(opts: {
     volumeName: string;
 }, contentBytes: number): string[];
 export declare function shouldRetryHdiutil(error: string, attempt: number, maxAttempts?: number): boolean;
+/**
+ * Helper: Create PKG from app bundle
+ *
+ * Two flavours share this entry point:
+ * - a plain `pkgbuild` installer for direct distribution, and
+ * - a signed `productbuild` submission package for the Mac App Store, which is
+ *   the only form App Store Connect accepts.
+ */
+/**
+ * The component property list `pkgbuild` is given for the app bundle.
+ *
+ * Written out rather than left to `pkgbuild`'s inference, because its default
+ * for a bundle is `BundleIsRelocatable = true`, which puts this in the package:
+ *
+ *     <relocate><bundle id="dev.example.app"/></relocate>
+ *
+ * That directive tells `installer` the payload path is only a suggestion: it
+ * looks the bundle identifier up on the target volume and, if the system has a
+ * copy of that bundle registered anywhere, writes the payload over *that* copy
+ * instead — and exits 0. The user sees "The install was successful" and finds
+ * nothing at /Applications.
+ *
+ * It is intermittent by nature, since it turns on whether the system has
+ * indexed some other copy yet, which is exactly how it behaved: the native
+ * lifecycle workflow's macOS legs failed only on slow runs, on both
+ * architectures, with `installer` reporting success and the app absent.
+ *
+ * `BundleIsVersionChecked` is off for a related reason — with it on, installing
+ * an *older* version over a newer one is skipped, which silently turns a
+ * rollback into a no-op.
+ *
+ * The `pkg-info` attribute `relocatable="false"` that appears either way is not
+ * this setting and does not govern it; only the `<relocate>` element does.
+ */
+export declare function pkgbuildComponentPlist(rootRelativeBundlePath: string): string;
+/** Build the `pkgbuild` argument list for a non-App-Store package. */
+export declare function pkgbuildArguments(opts: {
+    root: string;
+    componentPlistPath: string;
+    identifier: string;
+    version: string;
+    outputPath: string;
+    installerIdentity?: string;
+}): string[];
 export declare function windowsArchitecture(architecture: string): 'x86' | 'x64' | 'arm64';
 export declare function renderWixSource(opts: Pick<MSIOptions, 'name' | 'version' | 'manufacturer' | 'architecture'>, sourceName: string): string;
 export declare function windowsExecutableName(name: string): string;

package/dist/types.d.ts

@@ -55,6 +55,39 @@ export interface WindowOptions {
      * Window title
      */
     title?: string;
+    /**
+     * Build the window without ever putting it on screen (macOS).
+     *
+     * The page loads and runs JavaScript exactly as it would visibly, and it
+     * remains capturable — a snapshot taken after script has mutated the DOM
+     * reflects the mutation.
+     *
+     * **It does not animate.** An unshown window does not drive the compositor,
+     * so `requestAnimationFrame` stops after one frame and page timers fall to
+     * roughly 1Hz. Anything that advances itself — CSS or canvas animation, a
+     * charting library redrawing on rAF, "wait until the spinner stops" — sees
+     * the first frame forever. Drive the page with explicit calls and take
+     * readiness from load completion, not from a polling loop inside the page.
+     *
+     * Contradicts `menubarOnly`, which has no window to hide; passing both is an
+     * error rather than a silent no-op.
+     */
+    headless?: boolean;
+    /**
+     * Remember this window's size and position across launches, under this name
+     * (macOS).
+     *
+     * `width`/`height`/`x`/`y` become **first-launch defaults**: they are what
+     * the window opens at until there is a saved frame to restore, and the saved
+     * frame wins from then on. Without this the window forgets its geometry
+     * every launch, and an app that wants the standard behaviour has to wire
+     * `onResize`/`onMove` to its own storage and reimplement what AppKit does in
+     * one call.
+     *
+     * The name is the key AppKit stores under, so it must be stable across
+     * launches and distinct per window.
+     */
+    frameAutosave?: string;
     /**
      * Window width in pixels
      * @default 800
@@ -454,6 +487,19 @@ export interface AppConfig {
      * Window options
      */
     window?: WindowOptions;
+    /**
+     * The name macOS shows for the app: the App menu title, and the
+     * "About X" / "Hide X" / "Quit X" items.
+     *
+     * Without it those read the executable's name, so every app launched
+     * through the shared `craft` binary calls itself "craft" in the menu bar.
+     * A packaged `.app` gets this from `CFBundleName` instead; this is what
+     * gives a dev-mode app its identity back without a packaging step.
+     *
+     * Not the name `ps` and Activity Monitor show — that comes from the
+     * executable and cannot be changed from inside the process.
+     */
+    appName?: string;
     /**
      * Path to Craft binary (auto-detected if not provided)
      */
@@ -923,6 +969,254 @@ export interface CraftBridgeAPI {
      * Screen-sharing and screen-recording detection (macOS)
      */
     screenSharing?: CraftScreenSharingAPI;
+    /**
+     * System-wide hotkeys (macOS).
+     *
+     * Absent in effect on Linux and Windows: the calls exist, and every
+     * registration is refused, because Craft has no implementation there and a
+     * shortcut that can never fire is worse than one that was never accepted.
+     */
+    shortcuts?: CraftGlobalShortcutsAPI;
+    /**
+     * A small scalar preference store (macOS: CFPreferences).
+     */
+    prefs?: CraftPreferencesAPI;
+    /**
+     * The Cmd+, convention: where the App menu's Settings… item arrives.
+     */
+    settings?: CraftSettingsAPI;
+    /**
+     * What the native side actually serves.
+     *
+     * Always present: it is how you find out whether anything else here is.
+     */
+    capabilities?: () => Promise<CraftCapabilities>;
+    /** The last capabilities answer, or null if nothing has asked yet. */
+    capabilitiesSync?: () => CraftCapabilities | null;
+    /**
+     * Whether one surface is known to work — `craft.supports('tray.destroy')`.
+     *
+     * Fails **open**: returns true before capabilities have been fetched, and
+     * true for a namespace craft has not audited. A feature-detection mechanism
+     * that breaks working code when it cannot see itself would be worse than the
+     * gaps it describes.
+     */
+    supports?: (path: string) => boolean;
+}
+/**
+ * How much craft is willing to claim about a namespace.
+ *
+ * - `declared` — audited: the action list below is complete and enforced by a
+ *   conformance test against the dispatch chain.
+ * - `undeclared` — routed, but not audited. Craft claims nothing either way;
+ *   treat it as "try it and handle failure", not as "missing".
+ * - `unavailable` — reachable and known not to work. `reason` says why.
+ * - `unrouted` — implemented natively but absent from the dispatcher, so no
+ *   message can reach it.
+ */
+export type CapabilityNamespaceStatus = 'declared' | 'undeclared' | 'unavailable' | 'unrouted';
+export interface CapabilityAction {
+    status: 'live' | 'unavailable';
+    /** Whether native sends a reply the caller is waiting on. */
+    reply: 'none' | 'result';
+    /** Present when the action is unavailable. */
+    reason?: string;
+}
+export interface CapabilityNamespace {
+    status: CapabilityNamespaceStatus;
+    reason?: string;
+    /** Present only for `declared` namespaces. */
+    actions?: Record<string, CapabilityAction>;
+}
+/**
+ * What the native binary behind this page actually serves.
+ *
+ * The injected bridge script is one blob, the same in every build, so the
+ * presence of `window.craft.x` has never been evidence that anything is behind
+ * it. This is the evidence.
+ */
+export interface CraftCapabilities {
+    namespaces: Record<string, CapabilityNamespace>;
+    /**
+     * Every `craft:*` event channel, and whether anything native emits on it.
+     *
+     * A `false` here means subscribing would work and never fire — which cannot
+     * be derived from the action tables, so it is tracked separately by the
+     * emitters themselves.
+     */
+    channels: Record<string, boolean>;
+}
+/**
+ * The only value types `craft.prefs` stores.
+ *
+ * Anything else is refused in the page, before it can reach native. That is
+ * deliberate rather than a limitation dodged: the preferences API raises an
+ * Objective-C exception for a value that is not a property-list type, and Zig
+ * cannot catch one — so refusing containers here is what makes that crash
+ * unreachable. Serialise structure yourself:
+ * `prefs.set(k, JSON.stringify(v))`.
+ */
+export type PreferenceValue = string | number | boolean;
+export interface CraftPreferencesInfo {
+    /**
+     * The preferences domain in use — the bundle identifier inside a packaged
+     * `.app`, the executable's name otherwise.
+     */
+    domain: string;
+    /** The key prefix craft namespaces its own preferences under. */
+    prefix: string;
+    /** How many keys the app currently has stored. */
+    count: number;
+    /** A copy-pasteable command that prints the domain. */
+    readCommand: string;
+}
+/**
+ * A small preference store over the platform's own mechanism, so `defaults
+ * read` and a native settings pane both see what the app wrote.
+ *
+ * macOS only. Values are stored as native property-list types under a reserved
+ * key prefix, so clearing craft's preferences cannot disturb the AppKit and
+ * WebKit keys that share the same domain.
+ */
+export interface CraftPreferencesAPI {
+    /**
+     * Read a preference.
+     *
+     * `fallback` is returned when the key is absent — and also when what is
+     * stored is of a different type from the fallback, which is how a value left
+     * behind by an older build of the app degrades to the default rather than to
+     * a surprise. Call `get(key)` with no fallback to read whatever is stored.
+     *
+     * Rejects with `code: 'PREFS_FOREIGN_VALUE'` if something outside craft
+     * wrote a value craft cannot represent, rather than coercing it away.
+     */
+    get: <T extends PreferenceValue>(key: string, fallback?: T) => Promise<T | undefined>;
+    /**
+     * Write a preference. Resolves once the value is on disk, not merely once
+     * the message was posted.
+     *
+     * Rejects with `code: 'PREFS_UNSUPPORTED_VALUE'` for anything that is not a
+     * string, number or boolean; `'PREFS_NON_FINITE'` for NaN or Infinity;
+     * `'PREFS_VALUE_TOO_LARGE'` past 8 KiB; `'PREFS_BAD_KEY'` for a key outside
+     * `/^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/`.
+     */
+    set: (key: string, value: PreferenceValue) => Promise<void>;
+    /** Remove a preference. Resolves to whether it was there to begin with. */
+    delete: (key: string) => Promise<boolean>;
+    /**
+     * Remove every preference this app has set, and nothing else. Resolves to
+     * how many were removed.
+     */
+    clear: () => Promise<number>;
+    /** Every key this app has set, sorted. */
+    keys: () => Promise<string[]>;
+    /**
+     * Which domain the preferences are actually landing in.
+     *
+     * Worth having: an unbundled dev-mode binary writes to a domain named after
+     * the executable while a packaged `.app` writes to its bundle identifier, so
+     * preferences set during development can appear to vanish once the app is
+     * packaged.
+     */
+    info: () => Promise<CraftPreferencesInfo>;
+}
+/**
+ * The Cmd+, convention.
+ *
+ * craft's default App menu ships a `Settings…` item, and this is where its
+ * click arrives. An app that replaces the whole menu bar with
+ * `craft.menu.set()` loses the default item, and can declare
+ * `{ id: 'settings', role: 'settings', label: 'Settings…', shortcut: 'cmd+,' }`
+ * to get it back — the same handler answers either way.
+ */
+export interface CraftSettingsAPI {
+    /** Subscribe to Settings being opened. Returns an unsubscribe function. */
+    onOpen: (handler: (event: {
+        source: string;
+    }) => void) => () => void;
+    /**
+     * Open settings from the app's own UI — a gear button, say — so it lands in
+     * the same handler as Cmd+, rather than needing a second code path. Purely
+     * page-local; nothing crosses the bridge.
+     */
+    open: (source?: string) => Promise<void>;
+}
+/** A global hotkey, as `craft.shortcuts.list()` reports it. */
+export interface GlobalShortcut {
+    /** The id the app registered it under. */
+    id: string;
+    /**
+     * Craft's canonical spelling of the combination — `Cmd+Delete`, whatever
+     * the app originally wrote — so it can be passed straight back to
+     * `register()`.
+     */
+    accelerator: string;
+    /** The key alone, canonically named. */
+    key: string;
+    /** False while `disable()` has the key released back to the system. */
+    enabled: boolean;
+}
+/** Why a registration was refused. */
+export interface GlobalShortcutError {
+    /** The id from the payload that failed, or `''` if it had none. */
+    id: string;
+    /** Craft's error code, e.g. `NATIVE_CALL_FAILED`, `INVALID_PARAMETER`. */
+    code: string;
+    message: string;
+}
+/**
+ * System-wide hotkeys: they fire whether or not the app is frontmost.
+ *
+ * Accelerators are `+`-separated and case-insensitive — `'Cmd+Shift+H'`. The
+ * last component is the key, everything before it a modifier (`Cmd`/`Command`/
+ * `Meta`, `Ctrl`/`Control`, `Alt`/`Option`, `Shift`, or `CmdOrCtrl` for the
+ * platform's own). Keys are named by position on the keyboard, not by the
+ * character they produce, so a binding survives a layout change.
+ *
+ * At least one of Command, Control or Option is required, except on the
+ * function keys: a bare global hotkey on `H` would mean no application on the
+ * system ever saw the user type an h again.
+ */
+export interface CraftGlobalShortcutsAPI {
+    /**
+     * Reserve a combination system-wide. Registering an `id` twice replaces the
+     * first binding.
+     *
+     * The promise resolves once the message is posted, **not** once the key is
+     * reserved — so a combination that belongs to another app or to the system
+     * resolves here and reports on {@link CraftGlobalShortcutsAPI.onError}.
+     */
+    register: (id: string, accelerator: string) => Promise<void>;
+    /** Give the key back to the system and forget the shortcut. */
+    unregister: (id: string) => Promise<void>;
+    /** The same, for every shortcut this app holds. */
+    unregisterAll: () => Promise<void>;
+    /**
+     * Stop firing *and release the key*, so other apps can use it again. The
+     * shortcut stays listed. Holding a reservation while dropping the event
+     * would make the combination dead in every other app for as long as Craft
+     * ran.
+     */
+    disable: (id: string) => Promise<void>;
+    /**
+     * Take the key back. Can fail if something else claimed it while it was
+     * released, which reports on {@link CraftGlobalShortcutsAPI.onError}.
+     */
+    enable: (id: string) => Promise<void>;
+    /** Whether the id is known — enabled or not. */
+    isRegistered: (id: string) => Promise<boolean>;
+    list: () => Promise<GlobalShortcut[]>;
+    /** Every press of a registered, enabled shortcut. Returns an unsubscribe. */
+    on: (handler: (event: {
+        id: string;
+        accelerator: string;
+    }) => void) => () => void;
+    /**
+     * Where every fire-and-forget call reports its failure — `register`,
+     * `enable`, `disable`, `unregister`. (`isRegistered` and `list` are
+     * requests and reject their own promise instead.) Returns an unsubscribe.
+     */
+    onError: (handler: (error: GlobalShortcutError) => void) => () => void;
 }
 /**
  * Focus / Do Not Disturb authorization state, mirroring

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "craft-native",
-  "version": "0.0.75",
+  "version": "0.0.77",
   "type": "module",
   "description": "Build desktop apps with web languages - TypeScript SDK for Craft",
   "author": "Chris Breuer <chris@stacksjs.org>",