crossbind 2.0.0-beta.69 → 2.0.0-beta.72

package/src/utils/appExtensions.js

@@ -3,12 +3,13 @@ import { createRequire } from 'node:module';
 import path from 'node:path';
 import { carriedPath, isOutside } from './appFiles.js';
 import {
-    NAME, checkedCommands, checkedInstaller, checkedPublisher,
+    NAME, checkedCommands, checkedInstaller, checkedPackageSource, checkedPublisher,
 } from './extensionSteps.js';
 import { checkedActivityTypes, checkedFileTypes, checkedLinks, checkedShortcutItems } from './appLaunches.js';
 import { checkedPrivacy, checkedUrlSchemes } from './appOptions.js';
 import { checkedTargetKind, checkedTargetOptions, isHeader } from './appTargets.js';
 import { isUnderBase } from './replaceBasePathForDocker.js';
+import { printable } from './printableText.js';
 
 // What an app extension compiles with on every platform, and on each: its sources, the folders of its own their
 // includes are found in, and the macros they are compiled with.
@@ -41,7 +42,7 @@ const LINK_NAME = /^[A-Za-z0-9][A-Za-z0-9_.+-]*$/;
 // A class in a package, which the activity's package can name.
 const JAVA_CLASS = /^[A-Za-z_$][\w$]*(\.[A-Za-z_$][\w$]*)+$/;
 
-export { PUBLISH_PLATFORMS, checkedInstaller, checkedPublisher } from './extensionSteps.js';
+export { PUBLISH_PLATFORMS, checkedInstaller, checkedPackageSource, checkedPublisher } from './extensionSteps.js';
 
 const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
 const isEntitlement = (value) => typeof value === 'boolean' || typeof value === 'string'
@@ -338,6 +339,9 @@ export function checkedExtension(extension, root, where) {
             },
         }),
         ...(extension.commands === undefined ? {} : { commands: checkedCommands(extension.commands, `${where}'s commands`) }),
+        ...(extension.packageSource === undefined ? {} : {
+            packageSource: checkedPackageSource(extension.packageSource, `${where}'s packageSource`, extension.name),
+        }),
         ...(extension.fromApp === undefined ? {} : { fromApp: extension.fromApp.bind(extension) }),
         ...checkedOwnKeys(extension, where),
     };
@@ -352,11 +356,14 @@ export function checkedExtension(extension, root, where) {
 // extension written for any of them builds. A minor version that adds to the contract raises the newest, and a major
 // version that breaks it the oldest.
 export const OLDEST_EXTENSION_CONTRACT = 1;
-export const EXTENSION_CONTRACT = 1;
+export const EXTENSION_CONTRACT = 2;
+// What a later version added to an extension, by the version that did.
+const ADDED_IN = { packageSource: 2 };
 
 // The contract an extension is written for, or the several it is written for alike, is one this crossbind takes: one
-// written for others alone stops the build, naming what to update.
-function checkedContract({ contract }, where, update) {
+// written for others alone stops the build, naming what to update, as one that gives what its contract has not.
+function checkedContract(extension, where, update) {
+    const { contract } = extension;
     if (contract === undefined) {
         throw new Error(`crossbind: ${where} names no contract, the version of crossbind's extension contract it is written for, as contract: ${EXTENSION_CONTRACT} is for this crossbind: ${update}.`);
     }
@@ -364,8 +371,12 @@ function checkedContract({ contract }, where, update) {
     if (versions.length === 0 || versions.some((version) => !Number.isInteger(version) || version < 1) || new Set(versions).size !== versions.length) {
         throw new Error(`crossbind: ${where}'s contract ${JSON.stringify(contract)} is no version of crossbind's extension contract, as 1 or [1, 2] is.`);
     }
-    if (versions.some((version) => version >= OLDEST_EXTENSION_CONTRACT && version <= EXTENSION_CONTRACT)) return;
     const named = versions.join(' and ');
+    const early = Object.entries(ADDED_IN).find(([key, since]) => extension[key] !== undefined && versions.some((version) => version < since));
+    if (early) {
+        throw new Error(`crossbind: ${where} gives a ${early[0]}, which crossbind's extension contract has from its version ${early[1]} on, and is written for ${named}: name contract: ${early[1]}.`);
+    }
+    if (versions.some((version) => version >= OLDEST_EXTENSION_CONTRACT && version <= EXTENSION_CONTRACT)) return;
     if (versions.every((version) => version > EXTENSION_CONTRACT)) {
         throw new Error(`crossbind: ${where} is written for crossbind's extension contract ${named}, newer than this crossbind's ${EXTENSION_CONTRACT}: update crossbind.`);
     }
@@ -407,7 +418,7 @@ export function extensionPackage(root, base) {
 
 // What an extension of crossbind's build once hooked into, which no build runs.
 const OLD_HOOKS = ['loadConfig', 'buildWasm', 'createLib'];
-const LISTED_KEYS = ['name', 'contract', 'root', 'app', 'options', 'fromApp', 'publisher', 'installer', 'commands', 'replaces'];
+const LISTED_KEYS = ['name', 'contract', 'root', 'app', 'options', 'fromApp', 'publisher', 'installer', 'commands', 'packageSource', 'replaces'];
 
 // An extension crossbind.config.js lists, as its package's crossbind.extension.js gives it: its name, the folder its
 // files are in, which a build sees under the project's base alone, and what it adds to an app.
@@ -433,10 +444,27 @@ export function listedExtension(extension, where, base) {
 
 const OWN_PACKAGE = /^@crossbind\/extension-(.+)$/;
 
-// The names of the extension packages among the host's dependencies.
+// The names of the extension packages among a package's dependencies: the host's, or crossbind's own.
 export const ownPackages = (appHostRoot) => Object.keys(JSON.parse(fs.readFileSync(path.join(appHostRoot, 'package.json'), 'utf8')).dependencies ?? {})
     .filter((name) => OWN_PACKAGE.test(name)).sort();
 
+// One of those packages, as its crossbind.extension.js gives it, named as its package. `fix` is what brings it in step
+// with crossbind.
+export function broughtExtension(load, name, fix) {
+    const where = `${name}'s crossbind.extension.js`;
+    let extension;
+    try {
+        extension = load(`${name}/crossbind.extension.js`).default();
+    } catch (error) {
+        throw new Error(`crossbind: cannot read ${where}: ${error.message}: install the project's packages, or ${fix}.`, { cause: error });
+    }
+    checkedContract(extension ?? {}, where, fix);
+    const checked = checkedExtension(extension, extension?.root, where);
+    const expected = OWN_PACKAGE.exec(name)[1];
+    if (checked.name !== expected) throw new Error(`crossbind: ${where} names the extension ${checked.name}, not ${expected} as its package.`);
+    return checked;
+}
+
 // crossbind's own extensions: the extension packages among the host's dependencies, which an app has by having the host,
 // each named as its package. crossbind finds them as it finds the embind runtime, through the host, as pnpm shows them to
 // it alone.
@@ -444,20 +472,7 @@ export function ownExtensions(appHostRoot) {
     const load = createRequire(path.join(appHostRoot, 'package.json'));
     const packages = ownPackages(appHostRoot);
     if (packages.length === 0) throw new Error(`crossbind: the app host at ${appHostRoot} brings no extensions: update @crossbind/core-app-host to match crossbind.`);
-    return packages.map((name) => {
-        const where = `${name}'s crossbind.extension.js`;
-        let extension;
-        try {
-            extension = load(`${name}/crossbind.extension.js`).default();
-        } catch (error) {
-            throw new Error(`crossbind: cannot read ${where}: ${error.message}: install the project's packages, or update @crossbind/core-app-host to match crossbind.`, { cause: error });
-        }
-        checkedContract(extension ?? {}, where, 'update @crossbind/core-app-host to match crossbind');
-        const checked = checkedExtension(extension, extension?.root, where);
-        const expected = OWN_PACKAGE.exec(name)[1];
-        if (checked.name !== expected) throw new Error(`crossbind: ${where} names the extension ${checked.name}, not ${expected} as its package.`);
-        return checked;
-    });
+    return packages.map((name) => broughtExtension(load, name, 'update @crossbind/core-app-host to match crossbind'));
 }
 
 // Whether an option of the app's config asks for anything, as false, null and an empty list or object do not.
@@ -482,9 +497,10 @@ export function withoutNamed(own, app = {}) {
     return own.filter((extension) => !left.includes(extension));
 }
 
-// A failure of an extension's step: crossbind's own message as it is, else one that names the extension and the step.
-const stepFailure = (name, which, error) => (error instanceof Error && error.message.startsWith('crossbind:') ? error
-    : new Error(`crossbind: ${name}'s ${which} failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error }));
+// A failure of an extension's step: crossbind's own message as it is, else one that names the extension and the step,
+// without the control characters a file or a tool's output it quotes may hold.
+export const stepFailure = (name, which, error) => (error instanceof Error && error.message.startsWith('crossbind:') ? error
+    : new Error(`crossbind: ${name}'s ${which} failed: ${printable(error instanceof Error ? error.message : String(error))}`, { cause: error }));
 
 // A step of an extension's publisher or installer, whose failure stops the run.
 export async function extensionStep(name, which, run) {
@@ -515,10 +531,10 @@ export const withFromApp = (extensions, apiOf) => extensions.flatMap((extension)
     return options === null ? [] : [{ ...extension, options }];
 });
 
-// The extensions crossbind.config.js lists that add to an app: all but those that give a publisher or an installer
-// alone, which leave the host's own of their name as it is.
+// The extensions crossbind.config.js lists that add to an app: all but those that give a publisher, an installer or a
+// package source alone, which leave the host's own of their name as it is.
 export const appExtensionsOf = (listed) => listed
-    .filter((extension) => (!extension.publisher && !extension.installer) || Object.keys(extension.app).length > 0);
+    .filter((extension) => (!extension.publisher && !extension.installer && !extension.packageSource) || Object.keys(extension.app).length > 0);
 
 // The host's own extensions an app has, then those crossbind.config.js lists, each with the roles it holds, its own name
 // where it says nothing else: a role a listed one replaces leaves the host's that held it, which the app leaves out once

package/src/utils/appOptions.js

@@ -2,7 +2,8 @@
 // its page opens files.
 import { carriedPath } from './appFiles.js';
 
-const WINDOW_DEFAULTS = { width: 1024, height: 768, minWidth: 0, minHeight: 0, maxWidth: 0, maxHeight: 0, resizable: true, fullscreen: false, backgroundColor: null };
+const WINDOW_DEFAULTS = { width: 1024, height: 768, minWidth: 0, minHeight: 0, maxWidth: 0, maxHeight: 0, resizable: true, fullscreen: false, backgroundColor: null, titleBar: 'visible' };
+const TITLE_BARS = ['visible', 'hidden'];
 // Larger than any display, and far within the int a host takes a size as.
 const MAX_WINDOW_SIZE = 16384;
 // Windows keeps each of a file version's four numbers in 16 bits.
@@ -82,8 +83,9 @@ export function appCategory(config) {
     return { darwin: `public.app-category.${category}`, linux: APP_CATEGORIES[category] };
 }
 
-// The desktop window: the size of its page, the least it shrinks to and the most it grows to, whether it resizes and
-// whether it opens full screen. Its backgroundColor, which a phone takes as well, is appBackgroundColor's.
+// The desktop window: the size of its page, the least it shrinks to and the most it grows to, whether it resizes,
+// whether it opens full screen and whether a macOS page lies under its title bar. Its backgroundColor, which a phone
+// takes as well, is appBackgroundColor's.
 export function appWindow(config) {
     const window = config.app.window ?? {};
     const keys = Object.keys(WINDOW_DEFAULTS).join(', ');
@@ -102,6 +104,9 @@ export function appWindow(config) {
     ['resizable', 'fullscreen'].forEach((key) => {
         if (typeof options[key] !== 'boolean') throw new Error(`crossbind: app.window.${key} ${JSON.stringify(options[key])} is no boolean: set it to true or false.`);
     });
+    if (!TITLE_BARS.includes(options.titleBar)) {
+        throw new Error(`crossbind: app.window.titleBar ${JSON.stringify(options.titleBar)} is neither 'visible' nor 'hidden': 'hidden' lays a macOS app's page under its title bar, whose buttons stay.`);
+    }
     if (!options.resizable && (options.minWidth || options.minHeight || options.maxWidth || options.maxHeight)) {
         throw new Error('crossbind: app.window.minWidth, minHeight, maxWidth and maxHeight limit a window that resizes: drop them, or set app.window.resizable to true.');
     }
@@ -117,16 +122,29 @@ export function appWindow(config) {
     return options;
 }
 
-// The color an app shows until its page paints, and behind a page without a background of its own, on iOS and Android as
-// well: app.window.backgroundColor, else null, which leaves the system's.
-export function appBackgroundColor(config) {
+const COLOR = /^#[0-9A-Fa-f]{6}$/;
+
+// The colors an app shows until its page paints, and behind a page without a background of its own, on iOS and Android as
+// well: app.window.backgroundColor, one color, or { light, dark }, the one while the system is light and the one while
+// it is dark, which a phone follows; else null, which leaves the system's.
+function backgroundColors(config) {
     const color = config.app.window?.backgroundColor ?? null;
-    if (color !== null && (typeof color !== 'string' || !/^#[0-9A-Fa-f]{6}$/.test(color))) {
-        throw new Error(`crossbind: app.window.backgroundColor ${JSON.stringify(color)} is no color of the form #rrggbb, as #1e1e1e is.`);
+    if (color === null) return null;
+    if (typeof color === 'string' && COLOR.test(color)) return { light: color, dark: null };
+    const isPair = typeof color === 'object' && !Array.isArray(color) && Object.keys(color).sort().join() === 'dark,light'
+        && [color.light, color.dark].every((one) => typeof one === 'string' && COLOR.test(one));
+    if (!isPair) {
+        throw new Error(`crossbind: app.window.backgroundColor ${JSON.stringify(color)} is no color of the form #rrggbb, as #1e1e1e is, nor { light, dark } of two, as { light: '#f2f2f2', dark: '#1e1e1e' } is.`);
     }
     return color;
 }
 
+// The color, or the light one of the two, which a desktop shows whatever its system's appearance.
+export const appBackgroundColor = (config) => backgroundColors(config)?.light ?? null;
+
+// The color an iOS or Android app shows while its system is dark, where app.window.backgroundColor gives one.
+export const appDarkBackgroundColor = (config) => backgroundColors(config)?.dark ?? null;
+
 const PERMISSIONS = ['camera', 'microphone', 'location'];
 
 // The devices the page may use, each with the reason for it, which macOS and iOS read from the Info.plist:
@@ -313,8 +331,8 @@ export function appInstallers(config) {
     return installers;
 }
 
-// A desktop host's window: its page's size and limits, whether it resizes and whether it opens full screen. A maximum of
-// one side alone leaves the other as large as any display.
+// A desktop host's window: its page's size and limits, whether it resizes, whether it opens full screen and whether its
+// page lies under its title bar. A maximum of one side alone leaves the other as large as any display.
 function windowDefines(window) {
     const most = window.maxWidth || window.maxHeight ? [
         `#define CROSSBIND_APP_WINDOW_MAX_WIDTH ${window.maxWidth || MAX_WINDOW_SIZE}`,
@@ -328,6 +346,7 @@ function windowDefines(window) {
         `#define CROSSBIND_APP_WINDOW_RESIZABLE ${window.resizable ? 1 : 0}`,
         ...most,
         ...(window.fullscreen ? ['#define CROSSBIND_APP_WINDOW_FULLSCREEN 1'] : []),
+        ...(window.titleBar === 'hidden' ? ['#define CROSSBIND_APP_WINDOW_TITLE_BAR_HIDDEN 1'] : []),
     ];
 }
 
@@ -339,10 +358,12 @@ export function appHeader(config, platform, appGroup = null) {
     const id = `#define CROSSBIND_APP_ID "${platform === 'android' ? androidAppId(config) : appId(config)}"`;
     const name = `#define CROSSBIND_APP_NAME "${appDisplayName(config)}"`;
     const color = appBackgroundColor(config);
+    const dark = platform === 'ios' ? appDarkBackgroundColor(config) : null;
     const permissions = appPermissions(config);
     // An Android app's activity takes the color and the permissions from its Gradle project.
     const page = platform === 'android' ? [] : [
         ...(color ? [`#define CROSSBIND_APP_BACKGROUND_COLOR 0x${color.slice(1).toLowerCase()}`] : []),
+        ...(dark ? [`#define CROSSBIND_APP_BACKGROUND_COLOR_DARK 0x${dark.slice(1).toLowerCase()}`] : []),
         ...PERMISSIONS.map((name) => `#define CROSSBIND_APP_PERMISSION_${name.toUpperCase()} ${name in permissions ? 1 : 0}`),
     ];
     const windows = platform === 'ios' && iosMultipleWindows(config) ? ['#define CROSSBIND_APP_IOS_MULTIPLE_WINDOWS 1'] : [];

package/src/utils/appRustCrates.js

@@ -23,9 +23,9 @@ export default function buildAppRustCrates(target, cacheDir, cargoDependencies =
         .map((e) => e.name);
 
     // Prune bridges whose source of truth is gone. An app-local surface whose .rs was deleted
-    // breaks cargo on the missing #[path] target; a crate_ bridge whose cargoDependencies entry
+    // breaks cargo on the missing #[path] target; a crate_ bridge whose packages.cargo entry
     // was removed silently keeps dead registrations in every later binary. crate_ pruning only
-    // runs when the caller passes the current cargoDependencies - null means "don't judge".
+    // runs when the caller passes the crates declared now - null means "don't judge".
     crates = crates.filter((name) => {
         const dir = `${root}/${name}`;
         const libRs = `${dir}/src/lib.rs`;

package/src/utils/bridgeTools.js

@@ -15,8 +15,13 @@ const require = createRequire(import.meta.url);
 
 export const usesBridgeTools = (target, host = process.platform) => host === 'darwin' && target?.platform !== 'android';
 
-export function missingToolsMessage(error, version = require('../../package.json').version) {
+export function missingToolsMessage(error, version = require('../../package.json').version, node = process.versions.node) {
     if (error?.code === 'MODULE_NOT_FOUND') {
+        // A package manager leaves out an optional dependency whose engines the Node it runs on does not meet.
+        const needed = Number(require('../../package.json').engines.node.match(/\d+/)[0]);
+        if (Number(node.split('.')[0]) < needed) {
+            return `crossbind: bridges on a Mac need ${PACKAGE}, which needs Node ${needed} or later, as crossbind does: under Node ${node} the package manager leaves it out. Install again with Node ${needed} or later.`;
+        }
         return `crossbind: bridges on a Mac need ${PACKAGE}, which installs with crossbind there unless optional dependencies are left out: npm install --save-dev ${PACKAGE}@${version}`;
     }
     if (error?.code === 'ENOENT') {

package/src/utils/cppDts.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { stripComments } from './swigInterface.js';
 import writeIfChanged from './writeIfChanged.js';
-import { conanImportOfHeader, conanStageDir } from './conanImport.js';
+import { sourceImportOfHeader, sourceStageDir } from './packageSourceImport.js';
 
 // Best-effort .d.ts for `.h` imports, the C++ analog of the Rust emitDts: parse the
 // binding-rules surface (classes, public methods, primitives/string/shared_ptr), skip
@@ -256,20 +256,20 @@ function declarationsOf(headerFile, exportNames, dtsMode, log) {
 
 // Mirror the declaration under <cache>/types/<project-relative>.d.ts - never next to the
 // user's header. Package headers are skipped: their types ship with the package itself, and a
-// header staged from Conan is typed by its conan: module instead.
-export function writeHeaderDts({ headerFile, exportsFile, projectPath, cacheDir, dtsMode = 'sync', log = () => {} }) {
+// header staged from a package source is typed by its module instead, as conan:zlib/zlib.h is.
+export function writeHeaderDts({ headerFile, exportsFile, projectPath, cacheDir, sources = [], dtsMode = 'sync', log = () => {} }) {
     const relative = path.relative(projectPath, headerFile);
-    if (relative.startsWith('..') || headerFile.startsWith(`${conanStageDir(cacheDir)}/`)) return;
+    if (relative.startsWith('..') || sources.some((source) => headerFile.startsWith(`${sourceStageDir(cacheDir, source)}/`))) return;
     const exportNames = readExportNames(exportsFile, log);
     if (!exportNames) return;
     writeIfChanged(`${cacheDir}/types/${relative}.d.ts`, declarationsOf(headerFile, exportNames, dtsMode, log));
 }
 
-// A conan: specifier names no file the editor could map, so it is typed by an ambient module that
-// @crossbind/typescript-config includes. `declare` is an error inside one (TS1038).
-export function writeConanImportDts({ headerFile, exportsFile, declarationsFile = exportsFile, cacheDir, dtsMode = 'sync', log = () => {} }) {
-    const conanImport = conanImportOfHeader(headerFile, cacheDir);
-    const declared = conanImport && readExportNames(declarationsFile, log);
+// A specifier such as conan:zlib/zlib.h names no file the editor could map, so it is typed by an ambient
+// module, which @crossbind/typescript-config includes for conan. `declare` is an error inside one (TS1038).
+export function writeSourceImportDts({ headerFile, exportsFile, declarationsFile = exportsFile, cacheDir, sources = [], dtsMode = 'sync', log = () => {} }) {
+    const sourceImport = sourceImportOfHeader(headerFile, cacheDir, sources);
+    const declared = sourceImport && readExportNames(declarationsFile, log);
     if (!declared) return;
     // The bridge also binds macros and variadic functions the app imports, which the whole header's SWIG run skips.
     const exportNames = [...new Set([...declared, ...(readExportNames(exportsFile, log) ?? [])])];
@@ -279,7 +279,7 @@ export function writeConanImportDts({ headerFile, exportsFile, declarationsFile
         .map((line) => (line ? `    ${line}` : line))
         .join('\n');
     writeIfChanged(
-        `${conanStageDir(cacheDir)}/types/${conanImport.name}/${conanImport.header}.d.ts`,
-        `declare module 'conan:${conanImport.name}/${conanImport.header}' {\n${body}\n}\n`,
+        `${sourceStageDir(cacheDir, sourceImport.source)}/types/${sourceImport.name}/${sourceImport.header}.d.ts`,
+        `declare module '${sourceImport.source}:${sourceImport.name}/${sourceImport.header}' {\n${body}\n}\n`,
     );
 }

package/src/utils/extensionSteps.js

@@ -1,4 +1,4 @@
-// What a publisher, an installer and a command of an extension's give, as crossbind takes them.
+// What a publisher, an installer, a package source and a command of an extension's give, as crossbind takes them.
 
 // A name prefixes the extension's functions and names its C++ entry, crossbind_extension_<name>.
 export const NAME = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
@@ -110,6 +110,43 @@ export function checkedInstaller(installer, where) {
     return { platforms, ...(installer.isLast ? { isLast: true } : {}), ...Object.fromEntries(steps) };
 }
 
+const PACKAGE_SOURCE_STEPS = ['check', 'inputs', 'install'];
+const PACKAGE_SOURCE_KEYS = ['storeUnits', ...PACKAGE_SOURCE_STEPS];
+// A package source's name starts its imports, its key in crossbind.config.js and its folders beside crossbind's own:
+// one word, and none that means something there already: an import scheme of a bundler or a runtime, a folder of
+// crossbind's, or a device's name, which Windows gives no folder.
+const SOURCE_NAME = /^[a-z][a-z0-9]*$/;
+const KEPT_SOURCE_NAMES = [
+    'cargo', 'node', 'file', 'data', 'http', 'https', 'npm', 'virtual', 'blob', 'bun', 'deno', 'jsr', 'cloudflare', 'workerd',
+    'all', 'android', 'build', 'config', 'deps', 'hermes', 'keys', 'secrets', 'sysroots', 'types',
+    'con', 'prn', 'aux', 'nul',
+];
+const STORE_SEGMENT = /^[A-Za-z0-9_-][A-Za-z0-9_.-]*$/;
+// Folders of a source's store that never change once written, as p/*/p names one in each folder of p.
+const isStoreUnit = (unit) => typeof unit === 'string'
+    && unit.split('/').every((segment) => segment === '*' || STORE_SEGMENT.test(segment))
+    && unit.split('/').includes('*');
+
+// A package source as crossbind runs it, under its extension's name: the folders of its store a remote runner sends
+// back, and its steps, which keep the object as their this.
+export function checkedPackageSource(packageSource, where, name) {
+    if (!isObject(packageSource)) throw new Error(`crossbind: ${where} is no object.`);
+    const unknown = Object.keys(packageSource).find((key) => !PACKAGE_SOURCE_KEYS.includes(key));
+    if (unknown) throw new Error(`crossbind: ${where} takes ${PACKAGE_SOURCE_KEYS.join(', ')}; ${unknown} is none of them.`);
+    if (!SOURCE_NAME.test(name) || KEPT_SOURCE_NAMES.includes(name)) {
+        throw new Error(`crossbind: ${where} makes ${name} the name of a package source, which starts its imports, as ${name}:<package>/<header>: one word of lowercase letters and digits, and none of ${KEPT_SOURCE_NAMES.join(', ')}.`);
+    }
+    const storeUnits = packageSource.storeUnits ?? [];
+    if (!Array.isArray(storeUnits) || !storeUnits.every(isStoreUnit)) {
+        throw new Error(`crossbind: ${where}.storeUnits is no list of the folders of its store that never change once written, each a path with a * for a folder's name, as 'p/*/p'.`);
+    }
+    assertSteps(where, packageSource, PACKAGE_SOURCE_STEPS);
+    if (!packageSource.check) throw new Error(`crossbind: ${where} has no check, the step that takes the project's packages.${name}.`);
+    if (!packageSource.install) throw new Error(`crossbind: ${where} has no install, the step that installs a target's packages.`);
+    const steps = PACKAGE_SOURCE_STEPS.filter((step) => packageSource[step]).map((step) => [step, packageSource[step].bind(packageSource)]);
+    return { storeUnits: [...storeUnits], ...Object.fromEntries(steps) };
+}
+
 const COMMAND_KEYS = ['help', 'options', 'run'];
 
 // The commands an extension adds under crossbind app, by their names: each its line of help, the options it takes, as a

package/src/utils/nativeImports.js

@@ -11,9 +11,16 @@ export function findImportSpecifiers(text) {
 
 export const nativeExtensions = ({ header, module }) => [...header, ...module, 'rs'];
 
-export const nativeSpecifierTest = (ext) => {
+// Whether a specifier opens with one of the schemes an import names a store by, as cargo: and conan: are.
+export const schemeTest = (schemes) => {
+    const scheme = new RegExp(`^(${schemes.join('|')}):`);
+    return (specifier) => scheme.test(specifier);
+};
+
+export const nativeSpecifierTest = (ext, schemes) => {
     const extension = new RegExp(`\\.(${nativeExtensions(ext).join('|')})$`);
-    return (specifier) => /^(cargo|conan):/.test(specifier) || extension.test(specifier);
+    const hasScheme = schemeTest(schemes);
+    return (specifier) => hasScheme(specifier) || extension.test(specifier);
 };
 
 export function findNativeImportsIn(projectDir, isNative) {

package/src/utils/nodeDevBuild.js

@@ -6,6 +6,7 @@ import loadJson from './loadJson.js';
 import { computeInputStamp } from './inputStamp.js';
 import { findHeaderImportsIn } from './headerImports.js';
 import { findNativeImportsIn, nativeSpecifierTest } from './nativeImports.js';
+import { importSchemesOf } from './packageSources.js';
 
 // Set on the build a dev start runs: that build is a Node process too, which NODE_OPTIONS may hand the dev hooks again.
 export const DEV_BUILD_ENV = 'CROSSBIND_DEV_BUILD';
@@ -49,7 +50,7 @@ export function devFormatOf(project) {
 export function nativeInputsFingerprint(config) {
     const { project, native, header, module: modules } = config.paths;
     const relativeTo = (importer) => upath.relative(project, importer);
-    const imports = findNativeImportsIn(project, nativeSpecifierTest(config.ext))
+    const imports = findNativeImportsIn(project, nativeSpecifierTest(config.ext, importSchemesOf(config)))
         .map(({ importer, specifier }) => ({ importer: relativeTo(importer), specifier }));
     const names = findHeaderImportsIn(project, config.ext.header)
         .map(({ importer, specifier, names: taken }) => JSON.stringify([relativeTo(importer), specifier, taken]));

package/src/utils/packageSourceApi.js

@@ -0,0 +1,87 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import writeIfChanged from './writeIfChanged.js';
+import logger from './logger.js';
+import runPackageSource, { runProbe } from './runPackageSource.js';
+import { printable } from './printableText.js';
+
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+// Enough of a failed build's log to reach the error the tool ends it with.
+const LOG_TAIL_LINES = 60;
+
+const isText = (value) => typeof value === 'string' && !value.includes('\0');
+
+// A file the tool left in the work directory, as text, or null where there is none. Recipes write there too, so
+// a link, which could name any file the machine's user reads, is refused, as is a path that leaves the directory.
+function readOwn(name, dir, segments) {
+    const root = fs.realpathSync(dir);
+    const relative = segments.every(isText) ? path.relative(root, path.join(root, ...segments)) : '';
+    const file = path.join(root, relative);
+    const isInside = relative !== '' && relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+    if (isInside && !fs.existsSync(file)) return null;
+    if (!isInside || fs.realpathSync(file) !== file || !fs.statSync(file).isFile()) {
+        throw new Error(`crossbind: ${name} reads ${printable(segments.join('/'))} from its work directory, which is no file of its own there: a link, a folder, or a path that leaves the directory.`);
+    }
+    return fs.readFileSync(file, 'utf8');
+}
+
+function assertRun(name, command, env) {
+    if (!Array.isArray(command) || command.length === 0 || !command.every(isText)) {
+        throw new Error(`crossbind: ${name}'s run takes a program and its arguments as a list of strings.`);
+    }
+    const isEnv = env !== null && typeof env === 'object' && !Array.isArray(env)
+        && Object.entries(env).every(([key, value]) => ENV_NAME.test(key) && isText(value));
+    if (!isEnv) throw new Error(`crossbind: ${name}'s run takes env as variable names with their text.`);
+}
+
+function runFailure(name, step, target, program, result, logFile) {
+    if (result.error && result.error.code !== 'ENOBUFS') {
+        return new Error(`crossbind: could not run ${program} for ${target.path} (${result.error.message}).`);
+    }
+    let ending = `failed (exit code ${result.status})`;
+    if (result.error) ending = 'was stopped: it printed more than crossbind reads';
+    else if (result.signal) ending = `was stopped by ${result.signal}`;
+    // A tool that says why on stdout alone would end the message with nothing.
+    const printed = `${result.stderr ?? ''}`.trim() ? result.stderr : result.stdout;
+    const tail = printable(`${printed ?? ''}`).trim().split('\n').slice(-LOG_TAIL_LINES).join('\n');
+    return new Error(`crossbind: ${name} ${step} for ${target.path} ${ending}.${logFile ? ` Its whole log is in ${logFile}.` : ''}\n${tail}`);
+}
+
+// What a package source's steps get of crossbind. In install, with a log file, `run` runs the source's tool
+// where the target's packages build (its image, a remote runner, or the host where isLocal says so), in the
+// run's work directory, and what the tool writes to stderr is the install's log. In inputs the work directory
+// is the source's probe directory and only a tool of the host can be asked.
+export default function packageSourceApi({
+    source, config, target, work, logFile = null,
+}) {
+    const { name } = source;
+    const isLocal = work.runner === 'LOCAL';
+    const step = logFile ? 'install' : 'inputs';
+    const log = [];
+
+    function run(command, { env = {} } = {}) {
+        assertRun(name, command, env);
+        if (!logFile && !isLocal) {
+            throw new Error(`crossbind: ${name}'s inputs runs ${command[0]}, which it can where api.isLocal is true alone: elsewhere the image says what runs.`);
+        }
+        const result = logFile ? runPackageSource(command, {
+            source, config, target, work, env,
+        }) : runProbe(command, { work, env });
+        if (logFile) {
+            log.push(`${result.stderr ?? ''}`);
+            writeIfChanged(logFile, log.join(''));
+        }
+        if (result.error || result.status !== 0) throw runFailure(name, step, target, command[0], result, logFile);
+        return Object.freeze({ stdout: `${result.stdout ?? ''}`, stderr: `${result.stderr ?? ''}` });
+    }
+
+    return Object.freeze({
+        name,
+        isLocal,
+        logFile,
+        work: Object.freeze({ dir: work.dir, path: work.toolPath, read: (...segments) => readOwn(name, work.dir, segments) }),
+        store: Object.freeze({ dir: work.store, path: work.storePath }),
+        log: (text) => logger.info(text),
+        run,
+    });
+}

package/src/utils/packageSourceImport.js

@@ -0,0 +1,69 @@
+import fs from 'node:fs';
+
+// A package of a source, as an import and a folder name it. Lower-case, as Conan's are: a file system that
+// ignores case holds one folder for two names that differ in case alone.
+export const PACKAGE_NAME = /^[a-z0-9_][a-z0-9_+.-]*$/;
+// No leading dot, so neither '.' nor '..' can climb out of the include directory.
+const HEADER_SEGMENT = /^[A-Za-z0-9_+-][A-Za-z0-9_.+-]*$/;
+
+export const sourceStageDir = (cacheDir, source) => `${cacheDir}/${source}`;
+// Apart from the stage's own files, so no package name can land on one of them.
+export const sourcePackageDir = (stageDir, name) => `${stageDir}/packages/${name}`;
+
+// A source's name is its scheme and names all that is its own: packages.<name> in the config, <name>.lock and
+// .crossbind/<name>. Where a project declares its packages, as a message names it, and what it declares there.
+export const declarationOf = (source) => `packages.${source}`;
+export const dependenciesOf = (config, source) => config.packages?.[source] ?? {};
+// The crates a project declares: cargo is the core's own, declared beside the sources' packages.
+export const cratesOf = (config) => dependenciesOf(config, 'cargo');
+
+// The source whose scheme a specifier opens with, as conan:zlib/zlib.h names conan.
+export const sourceOfImport = (config, specifier) => (config.packageSources ?? []).find(({ name }) => specifier.startsWith(`${name}:`));
+
+export function parseSourceImport(source, specifier, headerExtensions) {
+    const [name, ...headerPath] = specifier.slice(source.length + 1).split('/');
+    if (!PACKAGE_NAME.test(name)) {
+        throw new Error(`crossbind: '${specifier}' - '${name}' is not a ${source} package name; write ${source}:<package>/<header>.`);
+    }
+    if (headerPath.length === 0) {
+        throw new Error(`crossbind: '${specifier}' names no header - import one of the package's headers as ${source}:${name}/<header>.`);
+    }
+    const bad = headerPath.find((segment) => !HEADER_SEGMENT.test(segment));
+    if (bad !== undefined) {
+        throw new Error(`crossbind: '${specifier}' - '${bad}' is not a header path segment.`);
+    }
+    const header = headerPath.join('/');
+    const extension = header.includes('.') ? header.split('.').at(-1) : '';
+    if (!headerExtensions.includes(extension)) {
+        throw new Error(`crossbind: '${specifier}' - a ${source}: import names a header (${headerExtensions.map((e) => `.${e}`).join(', ')}).`);
+    }
+    return { name, header };
+}
+
+// The inverse of resolveSourceHeader, for the editor types of a staged header.
+export function sourceImportOfHeader(file, cacheDir, sources) {
+    const prefixOf = (source) => sourcePackageDir(sourceStageDir(cacheDir, source), '');
+    const source = sources.find((name) => file.startsWith(prefixOf(name)));
+    if (!source) return null;
+    const match = file.slice(prefixOf(source).length).match(/^([^/]+)\/dist\/prebuilt\/[^/]+\/include\/(.+)$/);
+    // Both end up in the module name of the generated types.
+    if (!match || !PACKAGE_NAME.test(match[1]) || !match[2].split('/').every((segment) => HEADER_SEGMENT.test(segment))) return null;
+    return { source, name: match[1], header: match[2] };
+}
+
+// Only declared packages are importable, as with cargo:; a package pulled in by another links but stays hidden.
+export function resolveSourceHeader(config, source, specifier, target) {
+    const { name, header } = parseSourceImport(source, specifier, config.ext.header);
+    if (!Object.hasOwn(dependenciesOf(config, source), name)) {
+        throw new Error(`crossbind: '${specifier}' is not declared - add '${name}' to ${declarationOf(source)} in crossbind.config.`);
+    }
+    const dependency = config.allDependencies.find(({ general }) => general.packageSource?.name === source && general.packageSource.package.name === name);
+    if (!dependency) {
+        throw new Error(`crossbind: '${specifier}' - ${name} is declared in ${declarationOf(source)} but not installed; crossbind installs ${source} packages when a build starts.`);
+    }
+    const tried = [...new Set([target.releasePath, target.path].filter(Boolean))]
+        .map((targetPath) => `${dependency.paths.output}/prebuilt/${targetPath}/include/${header}`);
+    const found = tried.find((file) => fs.existsSync(file));
+    if (found) return found;
+    throw new Error(`crossbind: '${specifier}' - ${name} has no ${header}. Tried:\n${tried.map((file) => `  - ${file}`).join('\n')}`);
+}