@akanjs/devkit 3.0.0-beta.2 → 3.0.0-beta.21

package/mobile/nativeApp.ts

@@ -0,0 +1,210 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import type { AkanNativeConfig } from "@akanjs/native/config";
+import type { App } from "../commandDecorators";
+import {
+  type DesktopPlatform,
+  type MobilePlatform,
+  type NativePlatform,
+  type ResolvedMobileTarget,
+  targetHtmlFilename,
+} from "./mobileTarget";
+import { NativeApi, type NativeBuildApiModule } from "./nativeApi";
+import { NativeConfig } from "./nativeConfig";
+import { NativeWebDir } from "./nativeWebDir";
+
+type TaskOptions = Parameters<NativeBuildApiModule["build"]>[0];
+type DeviceSelector = NonNullable<Parameters<NativeBuildApiModule["run"]>[0]["device"]>;
+type ReleaseOptions = Parameters<NativeBuildApiModule["release"]>[0];
+type AndroidSigning = Extract<ReleaseOptions, { platform: "android" }>["signing"];
+
+export interface NativeRunOptions {
+  device?: DeviceSelector;
+  /** Narrows the iPhone signing to one Apple team. */
+  teamId?: string;
+}
+
+export interface NativeDevOptions extends NativeRunOptions {
+  /** The akan dev server the gateway proxies. */
+  upstream: string;
+  lang: string;
+}
+
+/** One mobile target of an app on the native runtime (a phone, or this computer as a desktop app): where it builds,
+ * what it ships, and the calls into the API. */
+export class NativeApp {
+  readonly targetRoot: string;
+  readonly web: NativeWebDir;
+
+  constructor(
+    readonly app: App,
+    readonly target: ResolvedMobileTarget,
+  ) {
+    this.targetRoot = path.join(app.cwdPath, ".akan", "mobile", target.name);
+    this.web = new NativeWebDir(path.join(this.targetRoot, "web"));
+  }
+
+  outDir(platform: NativePlatform) {
+    return path.join(this.targetRoot, "native", platform);
+  }
+
+  /** The web root, from the production build the mobile commands run first. */
+  async assembleWeb() {
+    const dist = this.app.dist.cwdPath;
+    return await this.web.assemble(this.target.config, {
+      html: path.join(dist, "csr", targetHtmlFilename(this.target.config)),
+      publicDir: path.join(dist, "public"),
+      fontsDir: path.join(dist, ".akan", "artifact", "fonts"),
+    });
+  }
+
+  async config() {
+    const [appConfig, plugins] = await Promise.all([this.app.getConfig(), this.app.collectPlugins()]);
+    return NativeConfig.build({
+      appPath: this.app.cwdPath,
+      target: this.target.config,
+      webDir: this.web.dir,
+      contributions: plugins.flatMap((plugin) => (plugin.native ? [plugin.native] : [])),
+      locales: appConfig.i18n.locales,
+    });
+  }
+
+  /** The API and the config it is about to build, refused here when the runtime would refuse it later. */
+  async prepare() {
+    const [api, { config, warnings }] = await Promise.all([NativeApi.load(this.app.cwdPath), this.config()]);
+    for (const warning of warnings) this.app.logger.warn(warning);
+    const problems = api.validateConfig(config, { appDir: this.app.cwdPath });
+    if (problems.length)
+      throw new Error(
+        `Mobile target '${this.target.name}' makes an invalid native config:\n- ${problems.join("\n- ")}`,
+      );
+    return { api, config };
+  }
+
+  //? The app's own output: its console (mirrored by a dev build), the simulator log stream or logcat.
+  #appLine = (line: string) => {
+    this.app.logger.info(`[${this.target.name}] ${line}`);
+  };
+
+  //* `AKAN_PUBLIC_*` is already inlined into the CSR bundle, so the runtime reads no .env file of its own.
+  #task(platform: NativePlatform, config: AkanNativeConfig): TaskOptions {
+    return {
+      appDir: this.app.cwdPath,
+      config,
+      platform,
+      outDir: this.outDir(platform),
+      envFiles: false,
+      skipWebBuild: true,
+      log: (event) => {
+        if (event.level === "error") this.app.logger.error(event.message);
+        else if (event.level === "warn") this.app.logger.warn(event.message);
+        else if (event.level === "tool") this.app.logger.verbose(event.message);
+        else this.app.logger.info(event.message);
+      },
+    };
+  }
+
+  async build(platform: NativePlatform, { profile = "release" }: { profile?: "debug" | "release" } = {}) {
+    await this.assembleWeb();
+    const { api, config } = await this.prepare();
+    return await api.build({ ...this.#task(platform, config), profile });
+  }
+
+  async run(
+    platform: NativePlatform,
+    { device, teamId, profile = "debug" }: NativeRunOptions & { profile?: "debug" | "release" } = {},
+  ) {
+    await this.assembleWeb();
+    const { api, config } = await this.prepare();
+    return await api.run({
+      ...this.#task(platform, config),
+      profile,
+      onLine: this.#appLine,
+      ...(device ? { device } : {}),
+      ...(teamId ? { ios: { signing: { teamId } } } : {}),
+    });
+  }
+
+  //* The gateway serves the page and its HMR socket on the app origin; API calls go to the dev server itself (baseEnv),
+  //* which an Android device reaches through the reversed port.
+  async dev(platform: NativePlatform, { upstream, lang, device, teamId }: NativeDevOptions) {
+    await mkdir(this.web.dir, { recursive: true });
+    const [{ api, config }, { api: routes }] = await Promise.all([this.prepare(), this.app.getConfig()]);
+    return await api.dev({
+      ...this.#task(platform, config),
+      upstream,
+      hmrPath: "/_akan/hmr",
+      //? A dev page calls its own origin (akanjs baseEnv), so the gateway relays the socket it opens for the API too.
+      wsPaths: [`${routes.prefix}${routes.websocketPrefix}`],
+      onLine: this.#appLine,
+      startPath: this.startPath(lang),
+      ...(device ? { device } : {}),
+      ...(teamId ? { ios: { signing: { teamId } } } : {}),
+    });
+  }
+
+  async releaseIos({ teamId, adHoc = false }: { teamId?: string; adHoc?: boolean } = {}) {
+    await this.assembleWeb();
+    const { api, config } = await this.prepare();
+    return await api.release({
+      ...this.#task("ios", config),
+      platform: "ios",
+      signing: { ...(teamId ? { teamId } : {}), ...(adHoc ? { distribution: "ad-hoc" as const } : {}) },
+    });
+  }
+
+  async releaseAndroid({ formats = ["aab"] }: { formats?: ("aab" | "apk")[] } = {}) {
+    const signing = NativeApp.androidSigning();
+    await this.assembleWeb();
+    const { api, config } = await this.prepare();
+    return await api.release({ ...this.#task("android", config), platform: "android", signing, formats });
+  }
+
+  //* The names the Gradle build read, so a CI that already holds these secrets keeps working.
+  static androidSigning(env: Record<string, string | undefined> = process.env): AndroidSigning {
+    const keystore = env.MYAPP_RELEASE_STORE_FILE;
+    const storePassword = env.MYAPP_RELEASE_STORE_PASSWORD;
+    const alias = env.MYAPP_RELEASE_KEY_ALIAS;
+    const keyPassword = env.MYAPP_RELEASE_KEY_PASSWORD;
+    if (!keystore || !storePassword || !alias) {
+      const missing = Object.entries({
+        MYAPP_RELEASE_STORE_FILE: keystore,
+        MYAPP_RELEASE_STORE_PASSWORD: storePassword,
+        MYAPP_RELEASE_KEY_ALIAS: alias,
+      }).flatMap(([key, value]) => (value ? [] : [key]));
+      throw new Error(
+        `An Android release is signed with the upload key; set ${missing.join(", ")} in the environment.`,
+      );
+    }
+    return { keystore, storePassword, alias, ...(keyPassword ? { keyPassword } : {}) };
+  }
+
+  /** The first page of a dev build, the target's home as a release bundle opens it; the dev server answers the CSR
+   * shell only for `?csr=true`. */
+  startPath(lang: string) {
+    const basePath = this.target.config.basePath?.replace(/^\/+|\/+$/g, "");
+    const params = new URLSearchParams({ csr: "true", akanMobileTarget: this.target.name });
+    if (basePath) params.set("akanMobileBasePath", basePath);
+    if (this.target.config.indexPath) params.set("akanMobileIndexPath", this.target.config.indexPath);
+    const home = [lang, basePath, this.target.config.indexPath]
+      .flatMap((part) => (part ?? "").split("/"))
+      .filter((segment) => segment.length > 0);
+    return `/${home.join("/")}?${params}`;
+  }
+
+  //* A desktop app builds only on its own OS, so the platform is this computer's.
+  static desktopPlatform(host: NodeJS.Platform = process.platform): DesktopPlatform {
+    if (host === "darwin") return "macos";
+    if (host === "win32") return "windows";
+    if (host === "linux") return "linux";
+    throw new Error(`A desktop app builds on macOS, Windows or Linux, not on ${host}.`);
+  }
+
+  static async devices(appDir: string, platform: MobilePlatform) {
+    return await (await NativeApi.load(appDir)).devices({ platform });
+  }
+
+  static async doctor(appDir: string, platforms: NativePlatform[]) {
+    return await (await NativeApi.load(appDir)).doctor({ platforms });
+  }
+}

package/mobile/nativeConfig.test.ts

@@ -0,0 +1,199 @@
+import { describe, expect, test } from "bun:test";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import type { AkanMobileTargetConfig } from "../akanConfig";
+import { tempDirs } from "../testHelpers";
+import { NativeApi } from "./nativeApi";
+import { NativeConfig } from "./nativeConfig";
+
+const makeTempRoot = tempDirs("akan-native-config-");
+const repoApp = path.resolve(import.meta.dir, "../../../../apps/minimal");
+
+const minimalTarget: AkanMobileTargetConfig = {
+  name: "default",
+  indexPath: "/explore",
+  appName: "minimal",
+  appId: "com.minimal.dev.app",
+  version: "0.0.1",
+  buildNum: 1,
+  permissions: ["push"],
+  native: { android: { googleServices: "secrets/google-services.json" } },
+  deepLinks: {
+    schemes: ["minimal"],
+    domains: ["example.com"],
+    ios: { teamId: "TEAMID" },
+    android: { sha256CertFingerprints: ["00:11"] },
+  },
+};
+
+const adminTarget: AkanMobileTargetConfig = {
+  name: "admin",
+  basePath: "admin",
+  appName: "Portal Admin",
+  appId: "com.portal.admin",
+  fileName: "portal-admin",
+  version: "2.1.0",
+  buildNum: 42,
+  assets: { icon: "assets/icon.png", splash: "assets/splash.png" },
+  permissions: ["camera", "location", "contacts"],
+  deepLinks: { domains: ["portal.example"] },
+  files: { "android/res/raw/chime.mp3": "assets/chime.mp3" },
+  native: {
+    plugins: ["iap"],
+    ios: { infoPlist: { ITSAppUsesNonExemptEncryption: false } },
+    android: { manifest: ['<queries><package android:name="com.kakao.talk" /></queries>'] },
+  },
+};
+
+describe("NativeConfig.build", () => {
+  test("turns the minimal app's push target into the runtime's config", () => {
+    const { config, warnings } = NativeConfig.build({
+      appPath: "/repo/apps/minimal",
+      target: minimalTarget,
+      webDir: "/repo/apps/minimal/.akan/mobile/default/web",
+      contributions: [{ permission: "push", plugins: ["push"] }],
+      locales: ["en", "ko"],
+    });
+
+    expect(warnings).toEqual([]);
+    expect(config).toEqual({
+      app: { id: "com.minimal.dev.app", name: "minimal", fileName: "minimal", version: "0.0.1", build: 1 },
+      web: { dir: "/repo/apps/minimal/.akan/mobile/default/web" },
+      plugins: [...NativeConfig.basePlugins, "push"],
+      capabilities: [
+        {
+          identifier: "app",
+          description: "The plugins minimal ships, each with its default permissions",
+          permissions: [...NativeConfig.basePlugins, "push"].map((plugin) => `${plugin}:default`),
+        },
+      ],
+      deepLinks: { schemes: ["minimal"], domains: ["example.com"] },
+      android: {
+        debugAppIdSuffix: ".debug",
+        googleServices: path.resolve("/repo/apps/minimal", "secrets/google-services.json"),
+      },
+      keyboard: { resize: "none" },
+    });
+  });
+
+  test("falls back to the builtin permission plugins, names the app in their texts, and lists basePath links per locale", () => {
+    const { config, warnings } = NativeConfig.build({
+      appPath: "/repo/apps/portal",
+      target: adminTarget,
+      webDir: "/repo/apps/portal/.akan/mobile/admin/web",
+      contributions: [],
+      locales: ["en", "ko"],
+    });
+
+    expect(warnings).toEqual(["Permission 'contacts' has no native plugin yet; the app ships without it."]);
+    expect(config).toEqual({
+      app: { id: "com.portal.admin", name: "Portal Admin", fileName: "portal-admin", version: "2.1.0", build: 42 },
+      web: { dir: "/repo/apps/portal/.akan/mobile/admin/web" },
+      plugins: [...NativeConfig.basePlugins, "camera", "geolocation", "iap"],
+      capabilities: [
+        {
+          identifier: "app",
+          description: "The plugins Portal Admin ships, each with its default permissions",
+          permissions: [...NativeConfig.basePlugins, "camera", "geolocation", "iap"].map(
+            (plugin) => `${plugin}:default`,
+          ),
+        },
+      ],
+      usageDescriptions: {
+        NSCameraUsageDescription: "Portal Admin requires access to the camera to take photos.",
+        NSPhotoLibraryAddUsageDescription: "Portal Admin requires access to the photo library to take photos.",
+        NSPhotoLibraryUsageDescription: "Portal Admin requires access to the photo library to take photos.",
+        NSLocationAlwaysAndWhenInUseUsageDescription:
+          "Portal Admin requires access to the location to get the user's location.",
+        NSLocationAlwaysUsageDescription: "Portal Admin requires access to the location to get the user's location.",
+        NSLocationWhenInUseUsageDescription: "Portal Admin requires access to the location to get the user's location.",
+      },
+      deepLinks: { domains: [{ host: "portal.example", pathPrefixes: ["/en/admin", "/ko/admin"] }] },
+      native: {
+        ios: { infoPlist: { ITSAppUsesNonExemptEncryption: false } },
+        android: { manifest: ['<queries><package android:name="com.kakao.talk" /></queries>'] },
+        resources: [{ from: path.resolve("/repo/apps/portal", "assets/chime.mp3"), to: "android/res/raw/chime.mp3" }],
+      },
+      android: { debugAppIdSuffix: ".debug" },
+      keyboard: { resize: "none" },
+      icon: path.resolve("/repo/apps/portal", "assets/icon.png"),
+      splash: { image: path.resolve("/repo/apps/portal", "assets/splash.png") },
+    });
+  });
+
+  test("a plugin that claims a permission replaces the builtin one and adds its Android entries", () => {
+    const { config } = NativeConfig.build({
+      appPath: "/repo/apps/portal",
+      target: { ...adminTarget, permissions: ["camera"], native: undefined, files: undefined, assets: undefined },
+      webDir: "/web",
+      contributions: [
+        {
+          permission: "camera",
+          plugins: ["camera"],
+          usageDescriptions: { cameraUsageDescription: "Scan receipts with $(PRODUCT_NAME)." },
+          androidPermissions: ["CAMERA"],
+          androidFeatures: ["android.hardware.camera"],
+        },
+        { permission: "push", plugins: ["push"] },
+      ],
+      locales: ["en"],
+    });
+
+    expect(config.plugins).toEqual([...NativeConfig.basePlugins, "camera"]);
+    expect(config.usageDescriptions).toEqual({ NSCameraUsageDescription: "Scan receipts with Portal Admin." });
+    expect(config.native).toEqual({
+      android: {
+        manifest: [
+          '<uses-permission android:name="android.permission.CAMERA" />',
+          '<uses-feature android:name="android.hardware.camera" android:required="false" />',
+        ],
+      },
+    });
+  });
+
+  test("the runtime accepts both configs as they are", async () => {
+    const root = await makeTempRoot();
+    for (const file of ["secrets/google-services.json", "assets/chime.mp3"])
+      await mkdir(path.dirname(path.join(root, file)), { recursive: true }).then(() =>
+        writeFile(path.join(root, file), file.endsWith(".json") ? googleServicesJson : "x"),
+      );
+    for (const image of ["assets/icon.png", "assets/splash.png"])
+      await writeFile(path.join(root, image), Buffer.from(onePixelPng, "base64"));
+    await mkdir(path.join(root, "web"), { recursive: true });
+    await writeFile(path.join(root, "web/index.html"), "<html><head></head><body></body></html>");
+    const api = await NativeApi.load(repoApp);
+
+    for (const target of [minimalTarget, adminTarget]) {
+      const { config } = NativeConfig.build({
+        appPath: root,
+        target,
+        webDir: path.join(root, "web"),
+        contributions: [],
+        locales: ["en", "ko"],
+      });
+      expect(api.validateConfig(config, { appDir: root })).toEqual([]);
+    }
+  });
+
+  test("keeps a file name the runtime accepts", () => {
+    expect(NativeConfig.fileNameOf("minimal")).toBe("minimal");
+    expect(NativeConfig.fileNameOf("my app!")).toBe("my-app");
+    expect(NativeConfig.fileNameOf("...")).toBe("app");
+  });
+});
+
+const onePixelPng = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg==";
+
+const googleServicesJson = JSON.stringify({
+  project_info: { project_number: "1", project_id: "demo", storage_bucket: "demo.appspot.com" },
+  client: [
+    {
+      client_info: { mobilesdk_app_id: "1:1:android:1", android_client_info: { package_name: "com.minimal.dev.app" } },
+      api_key: [{ current_key: "demo-key" }],
+    },
+    {
+      client_info: { mobilesdk_app_id: "1:1:android:2", android_client_info: { package_name: "com.portal.admin" } },
+      api_key: [{ current_key: "demo-key" }],
+    },
+  ],
+});

package/mobile/nativeConfig.ts

@@ -0,0 +1,184 @@
+import path from "node:path";
+import type { AkanNativeConfig } from "@akanjs/native/config";
+import type { AkanMobileTargetConfig, AkanNativeValue, AkanPluginNativeConfig, MobilePermission } from "akanjs";
+import { toIosInfoPlistUsageDescriptions } from "./usageDescriptions";
+
+export interface NativeConfigInput {
+  /** The app folder; every relative path in the target resolves against it. */
+  appPath: string;
+  target: AkanMobileTargetConfig;
+  /** The assembled web root the app loads. */
+  webDir: string;
+  /** What the app's and its libs' plugins declare. */
+  contributions: AkanPluginNativeConfig[];
+  locales: readonly 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; contacts and speech have no native plugin yet.
+  static readonly builtinContributions: { [permission in MobilePermission]: 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" },
+    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 }: 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 plugins = [
+      ...new Set([
+        ...NativeConfig.basePlugins,
+        ...applied.flatMap((contribution) => contribution.plugins ?? []),
+        ...(target.native?.plugins ?? []),
+      ]),
+    ];
+    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.native?.ios?.infoPlist,
+      ),
+      entitlements: NativeConfig.#merged(
+        applied.map((c) => c.entitlements),
+        target.native?.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.native?.android?.manifest ?? []),
+    ];
+    const android = NativeConfig.#compact({
+      manifest,
+      application: target.native?.android?.application ?? [],
+      activity: target.native?.android?.activity ?? [],
+    });
+    const resources = Object.entries(target.files ?? {}).map(([to, from]) => ({ from: abs(from), to }));
+    const native = NativeConfig.#compact({ ios, android, resources });
+    const googleServices = target.native?.android?.googleServices;
+    const config: AkanNativeConfig = {
+      app: {
+        id: target.appId,
+        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: plugins.map((plugin) => `${plugin}:default`),
+        },
+      ],
+      ...(Object.keys(usageDescriptions).length ? { usageDescriptions } : {}),
+      ...(target.deepLinks?.schemes?.length || target.deepLinks?.domains?.length
+        ? { deepLinks: NativeConfig.#deepLinks(target, locales) }
+        : {}),
+      ...(native ? { native } : {}),
+      //? assetlinks.json vouches for `<appId>.debug` outside main, the suffix a debug build installs under.
+      android: { debugAppIdSuffix: ".debug", ...(googleServices ? { googleServices: abs(googleServices) } : {}) },
+      keyboard: { resize: "none" },
+      ...(target.assets?.icon ? { icon: abs(target.assets.icon) } : {}),
+      ...(target.assets?.splash ? { splash: { image: abs(target.assets.splash) } } : {}),
+    };
+    return { config, warnings };
+  }
+
+  /** 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";
+  }
+
+  /** 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: AkanMobileTargetConfig, 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/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 { AkanMobileTargetConfig } from "../akanConfig";
+import { tempDirs } from "../testHelpers";
+import { NativeWebDir } from "./nativeWebDir";
+
+const makeTempRoot = tempDirs("akan-native-web-");
+
+const target: AkanMobileTargetConfig = {
+  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 mobile 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");
+  });
+});