@akanjs/devkit 3.0.0-beta.9 → 3.0.0

package/mobile/nativeConfig.ts

@@ -0,0 +1,294 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import type { AkanNativeConfig } from "@akanjs/native/config";
+import type { AkanNativeTarget, AkanNativeValue, AkanPluginNativeConfig, NativeEnv, NativePermission } from "akanjs";
+import type { DesktopServerBundle } from "./desktopServerStage";
+import { type NativePlatform, resolveAppId } from "./mobileTarget";
+import type { NativePluginFolder } from "./nativePluginFolders";
+import { toIosInfoPlistUsageDescriptions } from "./usageDescriptions";
+
+export interface NativeConfigInput {
+  /** The app folder; every relative path in the target resolves against it. */
+  appPath: string;
+  target: AkanNativeTarget;
+  /** The assembled web root the app loads. */
+  webDir: string;
+  /** What the app's and its libs' plugins declare. */
+  contributions: AkanPluginNativeConfig[];
+  locales: readonly string[];
+  /** The backend the binary talks to; an updates channel left unnamed follows it. */
+  env?: NativeEnv;
+  platform: NativePlatform;
+  /** A desktop build that carries its server (the target's `desktop.server`). */
+  desktopServer?: DesktopServerBundle;
+  /** The plugins in the app's and its libs' `native/` folders. */
+  nativePlugins?: NativePluginFolder[];
+  /** A desktop build's staged `bin` executables (DesktopBin). */
+  desktopBin?: string;
+}
+
+export interface NativeConfigResult {
+  config: AkanNativeConfig;
+  warnings: string[];
+}
+
+type NativeIos = NonNullable<NonNullable<AkanNativeConfig["native"]>["ios"]>;
+
+export class NativeConfig {
+  //* What every akanjs page may call: routing, lifecycle, links, storage, the device facts the runtime reads, and the
+  //* system sheet useCamera asks camera-or-library with.
+  static readonly basePlugins = [
+    "app",
+    "app-state",
+    "browser",
+    "opener",
+    "auth-session",
+    "device",
+    "dialog",
+    "keyboard",
+    "preferences",
+    "secure-storage",
+    "haptics",
+  ] as const;
+  //* Used when no plugin of the app or its libs claims the permission; speech has no native plugin yet.
+  static readonly builtinContributions: { [permission in NativePermission]: AkanPluginNativeConfig } = {
+    camera: {
+      permission: "camera",
+      plugins: ["camera"],
+      usageDescriptions: {
+        cameraUsageDescription: "$(PRODUCT_NAME) requires access to the camera to take photos.",
+        photoAddUsageDescription: "$(PRODUCT_NAME) requires access to the photo library to take photos.",
+        photoUsageDescription: "$(PRODUCT_NAME) requires access to the photo library to take photos.",
+      },
+    },
+    contacts: {
+      permission: "contacts",
+      plugins: ["contacts"],
+      usageDescriptions: {
+        contactsUsageDescription: "$(PRODUCT_NAME) requires access to the contacts to find people you know.",
+      },
+    },
+    location: {
+      permission: "location",
+      plugins: ["geolocation"],
+      usageDescriptions: {
+        locationAlwaysUsageDescription: "$(PRODUCT_NAME) requires access to the location to get the user's location.",
+        locationWhenInUseUsageDescription:
+          "$(PRODUCT_NAME) requires access to the location to get the user's location.",
+      },
+    },
+    push: { permission: "push", plugins: ["push"] },
+    speech: { permission: "speech" },
+  };
+
+  static build({
+    appPath,
+    target,
+    webDir,
+    contributions,
+    locales,
+    env,
+    platform,
+    desktopServer,
+    nativePlugins = [],
+    desktopBin,
+  }: NativeConfigInput): NativeConfigResult {
+    const warnings: string[] = [];
+    const applied = (target.permissions ?? []).flatMap((permission) => {
+      const claimed = contributions.filter((contribution) => contribution.permission === permission);
+      const used = claimed.length ? claimed : [NativeConfig.builtinContributions[permission]];
+      if (!used.some((contribution) => contribution.plugins?.length))
+        warnings.push(`Permission '${permission}' has no native plugin yet; the app ships without it.`);
+      return used;
+    });
+    const abs = (relative: string) => path.resolve(appPath, relative);
+    const updates = NativeConfig.#updates(target, env);
+    const folders = new Set(nativePlugins.map((plugin) => path.resolve(plugin.dir)));
+    const folderIds = new Set(nativePlugins.map((plugin) => plugin.id));
+    //? A `native/<id>` folder ships by itself; listed again, by path or by id, it would reach the runtime twice.
+    const listed = (target.plugins ?? []).filter((spec) =>
+      NativeConfig.#isId(spec) ? !folderIds.has(spec) : !folders.has(path.resolve(appPath, spec)),
+    );
+    const plugins = [
+      ...new Set([
+        ...NativeConfig.basePlugins,
+        //? Windows and Linux open a link by starting the app again; without the hand-over it runs as a second app and
+        //? the instance whose auth-session start() waits for the callback never hears it.
+        ...(target.deepLinks?.schemes?.length ? ["single-instance"] : []),
+        ...applied.flatMap((contribution) => contribution.plugins ?? []),
+        //? A second copy of the app would start a second server on the same data.
+        ...(desktopServer ? ["single-instance"] : []),
+        ...(updates ? ["updates"] : []),
+        ...listed,
+        ...nativePlugins.map((plugin) => plugin.dir),
+      ]),
+    ];
+    const pluginIds = plugins.map(
+      (spec) => nativePlugins.find((plugin) => plugin.dir === spec)?.id ?? NativeConfig.#pluginId(appPath, spec),
+    );
+    const usageDescriptions = Object.fromEntries(
+      Object.entries(
+        toIosInfoPlistUsageDescriptions(
+          Object.assign({}, ...applied.map((contribution) => contribution.usageDescriptions ?? {})),
+        ),
+      ).map(([key, text]) => [key, text.replaceAll("$(PRODUCT_NAME)", target.appName)]),
+    );
+    const ios = NativeConfig.#compact<NativeIos>({
+      infoPlist: NativeConfig.#merged(
+        applied.map((c) => c.infoPlist),
+        target.ios?.infoPlist,
+      ),
+      entitlements: NativeConfig.#merged(
+        applied.map((c) => c.entitlements),
+        target.ios?.entitlements,
+      ),
+    });
+    const manifest = [
+      ...[...new Set(applied.flatMap((c) => c.androidPermissions ?? []))].map(
+        (name) => `<uses-permission android:name="android.permission.${name}" />`,
+      ),
+      ...[...new Set(applied.flatMap((c) => c.androidFeatures ?? []))].map(
+        (name) => `<uses-feature android:name="${name}" android:required="false" />`,
+      ),
+      ...(target.android?.manifest ?? []),
+    ];
+    const android = NativeConfig.#compact({
+      manifest,
+      application: target.android?.application ?? [],
+      activity: target.android?.activity ?? [],
+    });
+    const resources = [
+      ...Object.entries(target.ios?.files ?? {}).map(([to, from]) => ({ from: abs(from), to: `ios/${to}` })),
+      ...Object.entries(target.android?.files ?? {}).map(([to, from]) => ({ from: abs(from), to: `android/${to}` })),
+    ];
+    const macos = NativeConfig.#compact({ entitlements: target.desktop?.entitlements });
+    const native = NativeConfig.#compact({ ios, macos, android, resources });
+    const googleServices = target.android?.googleServices;
+    const pushAndroid = target.android?.push;
+    const desktop = NativeConfig.#compact<NonNullable<AkanNativeConfig["desktop"]>>({
+      recovery: target.desktop?.recovery,
+      screenCapture: target.desktop?.screenCapture,
+      window: NativeConfig.#compact({ ...target.desktop?.window }),
+      server: desktopServer,
+      bin: desktopBin,
+    });
+    const config: AkanNativeConfig = {
+      app: {
+        id: resolveAppId(target.appId, platform),
+        name: target.appName,
+        fileName: target.fileName ?? NativeConfig.fileNameOf(path.basename(appPath)),
+        version: target.version,
+        build: target.buildNum,
+      },
+      web: { dir: webDir },
+      plugins,
+      //? PL-11: named, not implied: every plugin with its own default permissions, which is what a build without
+      //? capabilities grants too, so a release states what it allows.
+      capabilities: [
+        {
+          identifier: "app",
+          description: `The plugins ${target.appName} ships, each with its default permissions`,
+          permissions: pluginIds.map((id) => `${id}:default`),
+        },
+      ],
+      ...(Object.keys(usageDescriptions).length ? { usageDescriptions } : {}),
+      ...(target.deepLinks?.schemes?.length || target.deepLinks?.domains?.length
+        ? { deepLinks: NativeConfig.#deepLinks(target, locales) }
+        : {}),
+      ...(native ? { native } : {}),
+      ...(updates ? { updates } : {}),
+      ...(pushAndroid
+        ? {
+            push: {
+              android: { ...pushAndroid, ...(pushAndroid.smallIcon ? { smallIcon: abs(pushAndroid.smallIcon) } : {}) },
+            },
+          }
+        : {}),
+      ...(target.ios?.privacy ? { privacy: target.ios.privacy } : {}),
+      //? assetlinks.json vouches for `<appId>.debug` outside main, the suffix a debug build installs under.
+      android: {
+        debugAppIdSuffix: ".debug",
+        ...(googleServices ? { googleServices: abs(googleServices) } : {}),
+        ...(target.android?.autoplay ? { autoplay: true } : {}),
+      },
+      keyboard: { resize: "none" },
+      ...(desktop ? { desktop } : {}),
+      ...(target.icon ? { icon: NativeConfig.#icon(target.icon, abs) } : {}),
+      ...(target.splash ? { splash: NativeConfig.#splash(target.splash, abs) } : {}),
+    };
+    return { config, warnings };
+  }
+
+  static #icon(
+    icon: NonNullable<AkanNativeTarget["icon"]>,
+    abs: (relative: string) => string,
+  ): NonNullable<AkanNativeConfig["icon"]> {
+    return typeof icon === "string" ? abs(icon) : { ...icon, image: abs(icon.image) };
+  }
+
+  static #splash(
+    splash: NonNullable<AkanNativeTarget["splash"]>,
+    abs: (relative: string) => string,
+  ): NonNullable<AkanNativeConfig["splash"]> {
+    if (typeof splash === "string") return { image: abs(splash) };
+    return { ...splash, ...(splash.image ? { image: abs(splash.image) } : {}) };
+  }
+
+  //? akanConfig refuses a target whose merged updates lack url or publicKey; the type still has them optional.
+  static #updates(target: AkanNativeTarget, env?: NativeEnv): NonNullable<AkanNativeConfig["updates"]> | undefined {
+    const { url, publicKey, channel = env, ...rest } = target.updates ?? {};
+    return url && publicKey ? { ...rest, url, publicKey, ...(channel ? { channel } : {}) } : undefined;
+  }
+
+  /** Letters, digits, `.`, `_` and `-` only; the folder name of an akan app already is one almost always. */
+  static fileNameOf(name: string) {
+    return name.replace(/[^A-Za-z0-9._-]/g, "-").replace(/^[-.]+|[-.]+$/g, "") || "app";
+  }
+
+  //? A permission names a plugin by its id, and a plugin given by folder is named in its manifest; a spec the runtime
+  //? cannot read is left as it is for the runtime to report.
+  static #pluginId(appPath: string, spec: string) {
+    if (NativeConfig.#isId(spec)) return spec;
+    try {
+      const { id } = JSON.parse(readFileSync(path.join(path.resolve(appPath, spec), "native-plugin.json"), "utf8"));
+      return typeof id === "string" ? id : spec;
+    } catch {
+      return spec;
+    }
+  }
+
+  static #isId(spec: string) {
+    return !spec.startsWith(".") && !path.isAbsolute(spec);
+  }
+
+  /** Drops empty arrays and objects, and answers undefined when nothing is left. */
+  static #compact<T extends object>(value: { [key: string]: unknown }): T | undefined {
+    const kept = Object.entries(value).filter(([, entry]) =>
+      Array.isArray(entry)
+        ? entry.length > 0
+        : entry && typeof entry === "object"
+          ? Object.keys(entry).length > 0
+          : entry !== undefined,
+    );
+    return kept.length ? (Object.fromEntries(kept) as T) : undefined;
+  }
+
+  static #merged(
+    contributed: (Record<string, AkanNativeValue> | undefined)[],
+    own: Record<string, AkanNativeValue> | undefined,
+  ): Record<string, AkanNativeValue> {
+    return Object.assign({}, ...contributed, own);
+  }
+
+  //* Every route sits under /:lang, so an app link limited to a basePath lists it once per locale.
+  static #deepLinks(target: AkanNativeTarget, locales: readonly string[]) {
+    const basePath = target.basePath?.replace(/^\/+|\/+$/g, "");
+    const pathPrefixes = basePath ? locales.map((locale) => `/${locale}/${basePath}`) : undefined;
+    return {
+      ...(target.deepLinks?.schemes?.length ? { schemes: target.deepLinks.schemes } : {}),
+      ...(target.deepLinks?.domains?.length
+        ? { domains: target.deepLinks.domains.map((host) => (pathPrefixes ? { host, pathPrefixes } : host)) }
+        : {}),
+    };
+  }
+}

package/mobile/nativePluginFolders.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, test } from "bun:test";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import type { App } from "../commandDecorators";
+import { tempDirs } from "../testHelpers";
+import { NativePluginFolders } from "./nativePluginFolders";
+
+const makeTempRoot = tempDirs("akan-native-plugin-folders-");
+
+const writePlugin = async (root: string, folder: string, id: unknown = folder) => {
+  const dir = path.join(root, "native", folder);
+  await mkdir(dir, { recursive: true });
+  await writeFile(path.join(dir, "native-plugin.json"), JSON.stringify({ id, apiVersion: 1, methods: [] }));
+  return dir;
+};
+
+const fakeApp = (root: string, libs: string[]) =>
+  ({
+    name: "board",
+    cwdPath: path.join(root, "apps", "board"),
+    workspace: { workspaceRoot: root },
+    getScanInfo: () => ({ getLibs: () => libs }),
+  }) as unknown as App;
+
+describe("NativePluginFolders", () => {
+  test("finds each plugin folder in native/, by name", async () => {
+    const root = await makeTempRoot();
+    const kiosk = await writePlugin(root, "kiosk");
+    const audio = await writePlugin(root, "audio-output");
+    await writeFile(path.join(root, "native", "README.md"), "notes");
+
+    expect(await NativePluginFolders.in(root, "apps/board")).toEqual([
+      { id: "audio-output", dir: audio, owner: "apps/board" },
+      { id: "kiosk", dir: kiosk, owner: "apps/board" },
+    ]);
+  });
+
+  test("answers nothing for an app with no native folder", async () => {
+    expect(await NativePluginFolders.in(await makeTempRoot(), "apps/board")).toEqual([]);
+  });
+
+  test("refuses a folder without a manifest, or one named apart from its id", async () => {
+    const root = await makeTempRoot();
+    await mkdir(path.join(root, "native", "helpers"), { recursive: true });
+    await expect(NativePluginFolders.in(root, "apps/board")).rejects.toThrow(
+      "apps/board/native/helpers has no native-plugin.json",
+    );
+
+    const other = await makeTempRoot();
+    await writePlugin(other, "kiosk-tools", "kiosk");
+    await expect(NativePluginFolders.in(other, "libs/kiosk")).rejects.toThrow(
+      'libs/kiosk/native/kiosk-tools/native-plugin.json has id "kiosk"; name the folder after its id.',
+    );
+  });
+
+  test("the app's own plugin wins an id, and two libs may not both hold one", () => {
+    const app = { id: "kiosk", dir: "/w/apps/board/native/kiosk", owner: "apps/board" };
+    const libKiosk = { id: "kiosk", dir: "/w/libs/signage/native/kiosk", owner: "libs/signage" };
+    const libAudio = { id: "audio", dir: "/w/libs/signage/native/audio", owner: "libs/signage" };
+
+    expect(NativePluginFolders.select([app], [libKiosk, libAudio])).toEqual([app, libAudio]);
+    expect(() =>
+      NativePluginFolders.select(
+        [],
+        [libKiosk, { ...libKiosk, dir: "/w/libs/venue/native/kiosk", owner: "libs/venue" }],
+      ),
+    ).toThrow('libs/signage and libs/venue both hold native plugin "kiosk"; give the app its own native/kiosk');
+  });
+
+  test("an app ships its own plugins and those of the libs it depends on, not of other libs", async () => {
+    const root = await makeTempRoot();
+    const own = await writePlugin(path.join(root, "apps", "board"), "kiosk");
+    const used = await writePlugin(path.join(root, "libs", "signage"), "audio");
+    await writePlugin(path.join(root, "libs", "unused"), "camera-rig");
+
+    expect(await NativePluginFolders.of(fakeApp(root, ["signage"]))).toEqual([
+      { id: "kiosk", dir: own, owner: "apps/board" },
+      { id: "audio", dir: used, owner: "libs/signage" },
+    ]);
+  });
+});

package/mobile/nativePluginFolders.ts

@@ -0,0 +1,60 @@
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+import type { App } from "../commandDecorators";
+
+export interface NativePluginFolder {
+  id: string;
+  /** Absolute: the native build takes a plugin that is not builtin by its folder. */
+  dir: string;
+  /** Whose `native/` holds it: `apps/<app>` or `libs/<lib>`. */
+  owner: string;
+}
+
+//* An app's and its libs' own native plugins, each in `native/<id>/` beside its `native-plugin.json`. Every mobile and
+//* desktop target of the app ships them (the manifest says per platform what runs there); a lib's reach only the apps
+//* that depend on it.
+export class NativePluginFolders {
+  static readonly folder = "native";
+
+  static async in(root: string, owner: string): Promise<NativePluginFolder[]> {
+    const base = path.join(root, NativePluginFolders.folder);
+    const entries = await readdir(base, { withFileTypes: true }).catch(() => []);
+    const folders = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    return await Promise.all(
+      folders.sort().map(async (name) => {
+        const where = `${owner}/${NativePluginFolders.folder}/${name}`;
+        const manifest = Bun.file(path.join(base, name, "native-plugin.json"));
+        if (!(await manifest.exists()))
+          throw new Error(`${where} has no native-plugin.json; a folder in native/ is one native plugin.`);
+        const { id } = (await manifest.json()) as { id?: unknown };
+        if (id !== name)
+          throw new Error(`${where}/native-plugin.json has id ${JSON.stringify(id)}; name the folder after its id.`);
+        return { id, dir: path.join(base, name), owner };
+      }),
+    );
+  }
+
+  /** The app's own plugin wins an id; two libs may not both claim one. */
+  static select(own: NativePluginFolder[], fromLibs: NativePluginFolder[]): NativePluginFolder[] {
+    const chosen = new Map(own.map((plugin) => [plugin.id, plugin]));
+    for (const plugin of fromLibs) {
+      const held = chosen.get(plugin.id);
+      if (!held) chosen.set(plugin.id, plugin);
+      else if (held.owner.startsWith("libs/"))
+        throw new Error(
+          `${held.owner} and ${plugin.owner} both hold native plugin "${plugin.id}"; give the app its own native/${plugin.id} to pick one.`,
+        );
+    }
+    return [...chosen.values()];
+  }
+
+  static async of(app: App): Promise<NativePluginFolder[]> {
+    const scanInfo = app.getScanInfo({ allowEmpty: true }) ?? (await app.scan({ write: false }));
+    const root = app.workspace.workspaceRoot;
+    const [own, ...fromLibs] = await Promise.all([
+      NativePluginFolders.in(app.cwdPath, `apps/${app.name}`),
+      ...scanInfo.getLibs().map((lib) => NativePluginFolders.in(path.join(root, "libs", lib), `libs/${lib}`)),
+    ]);
+    return NativePluginFolders.select(own ?? [], fromLibs.flat());
+  }
+}

package/mobile/nativeWebDir.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, test } from "bun:test";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import type { AkanNativeTarget } from "../akanConfig";
+import { tempDirs } from "../testHelpers";
+import { NativeWebDir } from "./nativeWebDir";
+
+const makeTempRoot = tempDirs("akan-native-web-");
+
+const target: AkanNativeTarget = {
+  name: "admin",
+  basePath: "/admin/",
+  indexPath: "/home",
+  appName: "Portal",
+  appId: "com.portal.admin",
+  version: "1.0.0",
+  buildNum: 1,
+};
+
+const write = async (file: string, content: string) => {
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(file, content);
+};
+
+describe("NativeWebDir", () => {
+  test("injects the target global once, first in <head>, even when the inlined bundle names it", () => {
+    const bundle = '<script type="module">if(!window.__AKAN_MOBILE_TARGET__)boot("</head>")</script>';
+    const html = NativeWebDir.injectTarget(`<html><HEAD lang="en">${bundle}</head><body></body></html>`, target);
+
+    expect(html).toBe(
+      `<html><HEAD lang="en">\n<script>window.__AKAN_MOBILE_TARGET__={"name":"admin","basePath":"admin","indexPath":"/home"};</script>${bundle}</head><body></body></html>`,
+    );
+    expect(NativeWebDir.injectTarget(html, target)).toBe(html);
+  });
+
+  test("assembles the page, the pruned public folder and the fonts, from scratch every time", async () => {
+    const root = await makeTempRoot();
+    await write(path.join(root, "dist/csr/admin.html"), "<html><head></head><body>app</body></html>");
+    await write(path.join(root, "dist/public/images/logo.png"), "png");
+    await write(path.join(root, "dist/public/index.html"), "stale page from public");
+    await write(path.join(root, "dist/.akan/artifact/fonts/pretendard/400.woff2"), "font");
+    const web = new NativeWebDir(path.join(root, "web"));
+    await write(path.join(root, "web/leftover.txt"), "from the last build");
+
+    const files = await web.assemble(target, {
+      html: path.join(root, "dist/csr/admin.html"),
+      publicDir: path.join(root, "dist/public"),
+      fontsDir: path.join(root, "dist/.akan/artifact/fonts"),
+    });
+
+    expect(files).toEqual(["_akan/fonts/pretendard/400.woff2", "images/logo.png", "index.html"]);
+    expect(await Bun.file(path.join(root, "web/index.html")).text()).toContain("window.__AKAN_MOBILE_TARGET__");
+  });
+
+  test("builds without a public folder or fonts", async () => {
+    const root = await makeTempRoot();
+    await write(path.join(root, "index.html"), "<html><head></head></html>");
+
+    const files = await new NativeWebDir(path.join(root, "web")).assemble(target, {
+      html: path.join(root, "index.html"),
+      publicDir: path.join(root, "missing-public"),
+    });
+
+    expect(files).toEqual(["index.html"]);
+  });
+
+  test("refuses a missing bundle and a public folder that takes the runtime's reserved path", async () => {
+    const root = await makeTempRoot();
+    const web = new NativeWebDir(path.join(root, "web"));
+    await expect(web.assemble(target, { html: path.join(root, "none.html") })).rejects.toThrow(
+      "CSR html for native target 'admin' not found",
+    );
+
+    await write(path.join(root, "index.html"), "<html><head></head></html>");
+    await write(path.join(root, "public/__akan_native/x.js"), "x");
+    await expect(
+      web.assemble(target, { html: path.join(root, "index.html"), publicDir: path.join(root, "public") }),
+    ).rejects.toThrow("public/__akan_native is reserved for the native runtime");
+  });
+});

package/mobile/nativeWebDir.ts

@@ -0,0 +1,66 @@
+import { cp, mkdir, rm, stat } from "node:fs/promises";
+import path from "node:path";
+import type { AkanNativeTarget } from "akanjs";
+
+export interface NativeWebDirSources {
+  /** The target's CSR bundle: one HTML file with its scripts and styles inlined. */
+  html: string;
+  /** The build's own copy of `public/`, already pruned of fonts nothing reads. */
+  publicDir?: string;
+  /** Subset fonts, served from `/_akan/fonts` as the page's `<FontFace>` names them. */
+  fontsDir?: string;
+}
+
+export class NativeWebDir {
+  //* The runtime serves its bridge from this prefix and refuses a web root that has one of its own.
+  static readonly reservedEntry = "__akan_native";
+
+  constructor(readonly dir: string) {}
+
+  //* The bundle is inlined into this page and its own code names the global, so only the tag marks an injection;
+  //* it goes first in <head>, ahead of every script, because the page reads it as it boots.
+  static injectTarget(html: string, target: Pick<AkanNativeTarget, "name" | "basePath" | "indexPath">) {
+    if (html.includes(NativeWebDir.#targetTag)) return html;
+    const basePath = target.basePath?.replace(/^\/+|\/+$/g, "") ?? "";
+    const script = `${NativeWebDir.#targetTag}${JSON.stringify({
+      name: target.name,
+      basePath,
+      indexPath: target.indexPath,
+    })};</script>`;
+    const head = /<head(?:\s[^>]*)?>/i.exec(html);
+    if (!head) return `${script}\n${html}`;
+    const at = head.index + head[0].length;
+    return `${html.slice(0, at)}\n${script}${html.slice(at)}`;
+  }
+  static readonly #targetTag = "<script>window.__AKAN_MOBILE_TARGET__=";
+
+  async clear() {
+    await rm(this.dir, { recursive: true, force: true });
+    await mkdir(this.dir, { recursive: true });
+  }
+
+  /** Rebuilds the folder from scratch and answers its files as web paths: relative, `/`-separated and sorted. */
+  async assemble(target: AkanNativeTarget, { html, publicDir, fontsDir }: NativeWebDirSources) {
+    if (!(await Bun.file(html).exists()))
+      throw new Error(`CSR html for native target '${target.name}' not found: ${html}`);
+    await this.clear();
+    if (publicDir && (await NativeWebDir.#isDir(publicDir))) await cp(publicDir, this.dir, { recursive: true });
+    if (fontsDir && (await NativeWebDir.#isDir(fontsDir)))
+      await cp(fontsDir, path.join(this.dir, "_akan", "fonts"), { recursive: true });
+    if (await NativeWebDir.#isDir(path.join(this.dir, NativeWebDir.reservedEntry)))
+      throw new Error(`public/${NativeWebDir.reservedEntry} is reserved for the native runtime.`);
+    await Bun.write(path.join(this.dir, "index.html"), NativeWebDir.injectTarget(await Bun.file(html).text(), target));
+    const files = await Array.fromAsync(new Bun.Glob("**/*").scan({ cwd: this.dir, onlyFiles: true, dot: true }));
+    //? Bun.Glob answers with the platform's separator, so a Windows scan reads `_akan\fonts\…`.
+    return files.map((file) => file.split(path.sep).join("/")).sort();
+  }
+
+  static async #isDir(dir: string) {
+    try {
+      return (await stat(dir)).isDirectory();
+    } catch {
+      // A missing folder is a source the build did not produce, not an error.
+      return false;
+    }
+  }
+}

package/mobile/placeholderAppId.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, test } from "bun:test";
+import { isPlaceholderAppId } from "./placeholderAppId";
+
+describe("isPlaceholderAppId", () => {
+  test("flags placeholder bundle identifiers that Apple's portal already claims", () => {
+    for (const appId of ["com.myapp.app", "com.myorg.myapp", "com.example.foo", "com.changeme.app", ""]) {
+      expect(isPlaceholderAppId(appId)).toBe(true);
+    }
+    for (const appId of ["com.minimal.app", "com.nearthlab.leadingflight", "io.akanjs.demo"]) {
+      expect(isPlaceholderAppId(appId)).toBe(false);
+    }
+  });
+});

package/mobile/placeholderAppId.ts

@@ -0,0 +1,16 @@
+// Placeholder bundle IDs are already claimed on Apple's portal, so device signing fails with "cannot be registered
+// to your development team".
+export const PLACEHOLDER_APP_IDS = [
+  "com.myapp.app",
+  "com.myorg.myapp",
+  "com.example.app",
+  "com.example.myapp",
+] as const;
+const placeholderAppIdSegment = /^(example|examples|myorg|myapp|mycompany|myorganization|changeme|todo|sample|test)$/;
+
+export const isPlaceholderAppId = (appId: string | null | undefined): boolean => {
+  const normalized = appId?.trim().toLowerCase() ?? "";
+  if (!normalized) return true;
+  if ((PLACEHOLDER_APP_IDS as readonly string[]).includes(normalized)) return true;
+  return normalized.split(".").some((segment) => placeholderAppIdSegment.test(segment));
+};

package/mobile/usageDescriptions.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, test } from "bun:test";
+import { toIosInfoPlistUsageDescriptions } from "./usageDescriptions";
+
+describe("toIosInfoPlistUsageDescriptions", () => {
+  test("writes Apple's real Info.plist keys, not NS + the description name", () => {
+    expect(
+      toIosInfoPlistUsageDescriptions({
+        cameraUsageDescription: "camera",
+        photoAddUsageDescription: "add",
+        photoUsageDescription: "read",
+        locationAlwaysUsageDescription: "always",
+      }),
+    ).toEqual({
+      NSCameraUsageDescription: "camera",
+      NSPhotoLibraryAddUsageDescription: "add",
+      NSPhotoLibraryUsageDescription: "read",
+      NSLocationAlwaysAndWhenInUseUsageDescription: "always",
+      NSLocationAlwaysUsageDescription: "always",
+    });
+  });
+
+  test("keeps the NS prefix convention for a key it does not know", () => {
+    expect(toIosInfoPlistUsageDescriptions({ bluetoothAlwaysUsageDescription: "ble" })).toEqual({
+      NSBluetoothAlwaysUsageDescription: "ble",
+    });
+  });
+});

package/mobile/usageDescriptions.ts

@@ -0,0 +1,24 @@
+import { capitalize } from "akanjs/common";
+
+//* Apple's Info.plist keys do not follow the description names (photo → NSPhotoLibrary…), so each one is spelled out.
+const iosUsageDescriptionKeys = {
+  cameraUsageDescription: ["NSCameraUsageDescription"],
+  photoAddUsageDescription: ["NSPhotoLibraryAddUsageDescription"],
+  photoUsageDescription: ["NSPhotoLibraryUsageDescription"],
+  contactsUsageDescription: ["NSContactsUsageDescription"],
+  //? iOS 11+ reads the AlwaysAndWhenInUse key; the Always key only serves iOS 10 and below.
+  locationAlwaysUsageDescription: ["NSLocationAlwaysAndWhenInUseUsageDescription", "NSLocationAlwaysUsageDescription"],
+  locationWhenInUseUsageDescription: ["NSLocationWhenInUseUsageDescription"],
+  microphoneUsageDescription: ["NSMicrophoneUsageDescription"],
+  speechRecognitionUsageDescription: ["NSSpeechRecognitionUsageDescription"],
+} as const;
+
+export const toIosInfoPlistUsageDescriptions = (descriptions: { [key: string]: string }) =>
+  Object.fromEntries(
+    Object.entries(descriptions).flatMap(([key, value]) => {
+      const plistKeys: readonly string[] = Object.hasOwn(iosUsageDescriptionKeys, key)
+        ? iosUsageDescriptionKeys[key as keyof typeof iosUsageDescriptionKeys]
+        : [`NS${capitalize(key)}`];
+      return plistKeys.map((plistKey) => [plistKey, value]);
+    }),
+  );