akanjs 3.0.0-beta.20 → 3.0.0-beta.21

package/vendor/@akanjs/native/packages/cli/src/lib/png.ts

@@ -0,0 +1,240 @@
+
+
+import { deflateSync, inflateSync } from "node:zlib";
+
+/** 8-bit RGBA, not premultiplied, rows top to bottom. */
+export interface Image {
+  width: number;
+  height: number;
+  data: Uint8Array;
+}
+
+const SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+const CHANNELS: Record<number, number> = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 };
+const DEPTHS: Record<number, number[]> = { 0: [1, 2, 4, 8, 16], 2: [8, 16], 3: [1, 2, 4, 8], 4: [8, 16], 6: [8, 16] };
+
+export class PngError extends Error {}
+
+function crc(type: Uint8Array, data: Uint8Array): number {
+  const both = new Uint8Array(type.length + data.length);
+  both.set(type);
+  both.set(data, type.length);
+  return Bun.hash.crc32(both) >>> 0;
+}
+
+function paeth(a: number, b: number, c: number): number {
+  const p = a + b - c;
+  const pa = Math.abs(p - a);
+  const pb = Math.abs(p - b);
+  const pc = Math.abs(p - c);
+  return pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+}
+
+export function decodePng(bytes: Uint8Array): Image {
+  if (bytes.length < 8 || SIGNATURE.some((b, i) => bytes[i] !== b)) throw new PngError("not a PNG file");
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  let width = 0;
+  let height = 0;
+  let depth = 0;
+  let colorType = -1;
+  let palette: Uint8Array | null = null;
+  let trns: Uint8Array | null = null;
+  const idat: Uint8Array[] = [];
+  let p = 8;
+  for (;;) {
+    if (p + 12 > bytes.length) throw new PngError("truncated PNG (no IEND chunk)");
+    const length = view.getUint32(p);
+    const type = bytes.subarray(p + 4, p + 8);
+    const name = String.fromCharCode(...type);
+    if (p + 12 + length > bytes.length) throw new PngError(`truncated PNG (${name} chunk)`);
+    const data = bytes.subarray(p + 8, p + 8 + length);
+    if (view.getUint32(p + 8 + length) !== crc(type, data)) throw new PngError(`corrupt PNG (bad CRC in ${name})`);
+    p += 12 + length;
+    if (name === "IHDR") {
+      const h = new DataView(data.buffer, data.byteOffset, data.byteLength);
+      width = h.getUint32(0);
+      height = h.getUint32(4);
+      depth = data[8]!;
+      colorType = data[9]!;
+      if (!(colorType in CHANNELS) || !DEPTHS[colorType]!.includes(depth))
+        throw new PngError(`invalid PNG color type ${colorType} with bit depth ${depth}`);
+      if (data[12] !== 0)
+        throw new PngError("interlaced PNGs are not supported: save the image without interlacing (Adam7)");
+      if (!width || !height || width > 16384 || height > 16384)
+        throw new PngError(`unsupported PNG size ${width}×${height}`);
+    } else if (name === "PLTE") palette = data;
+    else if (name === "tRNS") trns = data;
+    else if (name === "IDAT") idat.push(data);
+    else if (name === "IEND") break;
+  }
+  if (!width) throw new PngError("PNG has no IHDR chunk");
+  if (colorType === 3 && !palette) throw new PngError("palette PNG without a PLTE chunk");
+
+  const compressed = new Uint8Array(idat.reduce((n, c) => n + c.length, 0));
+  let o = 0;
+  for (const chunk of idat) {
+    compressed.set(chunk, o);
+    o += chunk.length;
+  }
+  let raw: Uint8Array;
+  try {
+    raw = new Uint8Array(inflateSync(compressed));
+  } catch (error) {
+    throw new PngError(`corrupt PNG image data: ${(error as Error).message}`);
+  }
+
+  const channels = CHANNELS[colorType]!;
+  const bitsPerPixel = channels * depth;
+  const bpp = Math.max(1, bitsPerPixel >> 3); 
+  const stride = Math.ceil((width * bitsPerPixel) / 8);
+  if (raw.length < height * (stride + 1)) throw new PngError("PNG image data is shorter than its size");
+
+  const rows = new Uint8Array(height * stride);
+  for (let y = 0; y < height; y++) {
+    const filter = raw[y * (stride + 1)]!;
+    const src = y * (stride + 1) + 1;
+    const dst = y * stride;
+    const up = dst - stride;
+    for (let x = 0; x < stride; x++) {
+      const v = raw[src + x]!;
+      const a = x >= bpp ? rows[dst + x - bpp]! : 0;
+      const b = y > 0 ? rows[up + x]! : 0;
+      const c = x >= bpp && y > 0 ? rows[up + x - bpp]! : 0;
+      let out: number;
+      switch (filter) {
+        case 0:
+          out = v;
+          break;
+        case 1:
+          out = v + a;
+          break;
+        case 2:
+          out = v + b;
+          break;
+        case 3:
+          out = v + ((a + b) >> 1);
+          break;
+        case 4:
+          out = v + paeth(a, b, c);
+          break;
+        default:
+          throw new PngError(`corrupt PNG (filter type ${filter})`);
+      }
+      rows[dst + x] = out & 0xff;
+    }
+  }
+
+  const sample = (row: number, index: number): number => {
+    if (depth === 8) return rows[row + index]!;
+    if (depth === 16) return (rows[row + index * 2]! << 8) | rows[row + index * 2 + 1]!;
+    const bit = index * depth;
+    return (rows[row + (bit >> 3)]! >> (8 - depth - (bit & 7))) & ((1 << depth) - 1);
+  };
+  const max = (1 << depth) - 1;
+  const to8 = (v: number) => (depth === 8 ? v : depth === 16 ? v >> 8 : Math.round((v * 255) / max));
+  const key =
+    trns && colorType !== 3
+      ? Array.from({ length: trns.length >> 1 }, (_, i) => (trns![i * 2]! << 8) | trns![i * 2 + 1]!)
+      : null;
+  const out = new Uint8Array(width * height * 4);
+  for (let y = 0; y < height; y++) {
+    const row = y * stride;
+    for (let x = 0; x < width; x++) {
+      const q = (y * width + x) * 4;
+      if (colorType === 3) {
+        const i = sample(row, x);
+        if (i * 3 + 2 >= palette!.length) throw new PngError(`palette index ${i} out of range`);
+        out[q] = palette![i * 3]!;
+        out[q + 1] = palette![i * 3 + 1]!;
+        out[q + 2] = palette![i * 3 + 2]!;
+        out[q + 3] = trns && i < trns.length ? trns[i]! : 255;
+      } else if (colorType === 0 || colorType === 4) {
+        const g = sample(row, x * channels);
+        out[q] = out[q + 1] = out[q + 2] = to8(g);
+        out[q + 3] = colorType === 4 ? to8(sample(row, x * 2 + 1)) : key && g === key[0] ? 0 : 255;
+      } else {
+        const r = sample(row, x * channels);
+        const g = sample(row, x * channels + 1);
+        const b = sample(row, x * channels + 2);
+        out[q] = to8(r);
+        out[q + 1] = to8(g);
+        out[q + 2] = to8(b);
+        out[q + 3] =
+          colorType === 6 ? to8(sample(row, x * 4 + 3)) : key && r === key[0] && g === key[1] && b === key[2] ? 0 : 255;
+      }
+    }
+  }
+  return { width, height, data: out };
+}
+
+function chunk(name: string, data: Uint8Array): Uint8Array {
+  const type = new TextEncoder().encode(name);
+  const out = new Uint8Array(12 + data.length);
+  const view = new DataView(out.buffer);
+  view.setUint32(0, data.length);
+  out.set(type, 4);
+  out.set(data, 8);
+  view.setUint32(8 + data.length, crc(type, data));
+  return out;
+}
+
+/** 8-bit RGBA PNG (RGB when fully opaque). Each row gets the filter with the smallest sum of |bytes|. */
+export function encodePng(image: Image): Uint8Array {
+  const { width, height, data } = image;
+  if (data.length !== width * height * 4) throw new PngError("image data does not match its size");
+  let opaque = true;
+  for (let i = 3; i < data.length && opaque; i += 4) opaque = data[i] === 255;
+  const channels = opaque ? 3 : 4;
+  const stride = width * channels;
+  const pixels = new Uint8Array(height * stride);
+  for (let i = 0, j = 0; i < data.length; i += 4) {
+    pixels[j++] = data[i]!;
+    pixels[j++] = data[i + 1]!;
+    pixels[j++] = data[i + 2]!;
+    if (!opaque) pixels[j++] = data[i + 3]!;
+  }
+  const raw = new Uint8Array(height * (stride + 1));
+  const candidate = new Uint8Array(stride);
+  for (let y = 0; y < height; y++) {
+    const row = y * stride;
+    let best = Infinity;
+    for (let filter = 0; filter < 5; filter++) {
+      let score = 0;
+      for (let x = 0; x < stride; x++) {
+        const v = pixels[row + x]!;
+        const a = x >= channels ? pixels[row + x - channels]! : 0;
+        const b = y > 0 ? pixels[row - stride + x]! : 0;
+        const c = x >= channels && y > 0 ? pixels[row - stride + x - channels]! : 0;
+        const predicted =
+          filter === 0 ? 0 : filter === 1 ? a : filter === 2 ? b : filter === 3 ? (a + b) >> 1 : paeth(a, b, c);
+        const f = (v - predicted) & 0xff;
+        candidate[x] = f;
+        score += f < 128 ? f : 256 - f;
+      }
+      if (score < best) {
+        best = score;
+        raw[y * (stride + 1)] = filter;
+        raw.set(candidate, y * (stride + 1) + 1);
+      }
+    }
+  }
+  const ihdr = new Uint8Array(13);
+  const h = new DataView(ihdr.buffer);
+  h.setUint32(0, width);
+  h.setUint32(4, height);
+  ihdr[8] = 8;
+  ihdr[9] = opaque ? 2 : 6;
+  const parts = [
+    new Uint8Array(SIGNATURE),
+    chunk("IHDR", ihdr),
+    chunk("IDAT", new Uint8Array(deflateSync(raw, { level: 9 }))),
+    chunk("IEND", new Uint8Array(0)),
+  ];
+  const out = new Uint8Array(parts.reduce((n, c) => n + c.length, 0));
+  let o = 0;
+  for (const part of parts) {
+    out.set(part, o);
+    o += part.length;
+  }
+  return out;
+}

package/vendor/@akanjs/native/packages/cli/src/lib/prepare.ts

@@ -0,0 +1,290 @@
+
+
+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import type { Platform } from "../../../core/src/index.ts";
+import { aclWarnings, resolveAcl } from "./acl.ts";
+import { buildCsp, hasCspMeta, injectCspMeta } from "./csp.ts";
+import { ENV_TYPES_FILE, loadEnv, writeEnvTypes } from "./env.ts";
+import { exec } from "./exec.ts";
+import { findExternalScripts, injectEarlyErrors, injectInitScript } from "./html.ts";
+import { CliError, dim, log } from "./log.ts";
+import { buildNumberProblem, ConfigError, dependencyProblems, type Project } from "./project.ts";
+
+/**
+ * debug: inspectable webview, dev signing, runtime env overrides, the dev server (akan-native run, dev,
+ * test). release: none of that (akan-native build, update publish). Independent of `mode`, which only
+ * picks the .env files, so a staging build is still a release build.
+ */
+export type BuildProfile = "debug" | "release";
+
+/** The bundled page of a dev build without a built SPA (its pages come from the dev server). */
+const DEV_SERVER_PAGE = `<!doctype html>
+<html>
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Dev server</title></head>
+<body style="font: 16px system-ui; padding: 24px"><p>This development build loads its pages from the dev server, which is not reachable. Start it, then reload.</p></body>
+</html>
+`;
+
+export interface BuildOptions {
+  mode: string;
+  profile: BuildProfile;
+  /** Skip `web.build` and use what is already in web.dir. */
+  skipWebBuild: boolean;
+  /**
+   * `akan-native dev --hmr`: the dev gateway the native host fetches pages from instead of its bundled
+   * files (lib/hmr.ts). Ignored by release builds, which never contain it.
+   */
+  devServer?: string;
+  /** Default <app>/.akan/native/build/<platform>. */
+  outDir?: string;
+  /**
+   * Dev builds: the path and query of the first page (akanjs readiness O4-5), e.g.
+   * "/en/?csr=true&akanMobileTarget=default". Release builds always start at "/".
+   */
+  startPath?: string;
+  /** false: no .env files (docs/api.md envFiles). Default true. */
+  envFiles?: boolean;
+  /** PUBLIC_ values above every other source (docs/api.md env). */
+  env?: Record<string, string>;
+  /**
+   * Called through the programmatic API (docs/api.md): nothing is written into the app folder (no
+   * akan-native-env.d.ts), and signing comes only from the options, never from AKAN_NATIVE_ANDROID_* or
+   * AKAN_NATIVE_IOS_* variables.
+   */
+  api?: boolean;
+  /** Android release output (akanjs readiness O1-5). */
+  android?: AndroidRelease;
+  /** iOS devices (akanjs readiness O1-2, O1-3). */
+  ios?: IosBuild;
+}
+
+/** Which identity and profile an iOS device build signs with; unset: found in the keychain and Xcode's profiles. */
+export interface IosSigning {
+  /** A certificate name ("Apple Development: …") or its SHA-1. Default: found (docs/api.md §3). */
+  identity?: string;
+  /** A .mobileprovision file. Default: the fitting local profile (docs/api.md §3). */
+  provisioningProfile?: string;
+  /** Only this team's profiles (when several teams have one for the app). */
+  teamId?: string;
+  /** Release builds: an App Store profile (default) or, only when asked for, an ad hoc one. */
+  distribution?: "app-store" | "ad-hoc";
+}
+
+/** What an iPhone build was signed with (BuildResult.signing), for the caller to show. */
+export interface IosSigningResult {
+  identity: string;
+  identitySha1: string;
+  profile: string;
+  profileUuid: string;
+  teamId: string;
+  kind: string;
+  /** ISO date. */
+  expires: string;
+}
+
+export interface IosBuild {
+  /** An iPhone build (iphoneos, signed with a certificate and a profile) instead of the simulator's. Release builds also get an .ipa. */
+  device?: boolean;
+  signing?: IosSigning;
+  /** The iPhone this build is installed on (run, dev): a development or ad hoc profile must list its UDID. */
+  target?: { udid: string; name?: string };
+}
+
+/** An upload or release key in a keystore (JKS or PKCS12). The passwords never reach a command line. */
+export interface AndroidSigning {
+  keystore: string;
+  alias: string;
+  storePassword: string;
+  /** Default the store password (PKCS12 keystores have one password). */
+  keyPassword?: string;
+}
+
+export interface AndroidRelease {
+  /** Release builds only; without it they are signed with ~/.akan/native/debug.keystore (with a warning). */
+  signing?: AndroidSigning;
+  /** Also build an App Bundle (.aab), signed with the same key. */
+  bundle?: boolean;
+}
+
+/** The release key is missing or does not sign (AkanNativeError SIGNING_FAILED). */
+/** Signing failed; `problems`: the candidates, or why each profile did not fit. */
+export class SigningError extends CliError {
+  constructor(
+    message: string,
+    readonly problems: string[] = [],
+  ) {
+    super(problems.length ? `${message}\n  - ${problems.join("\n  - ")}` : message);
+  }
+}
+
+export interface BuildContext {
+  project: Project;
+  platform: Platform;
+  mode: string;
+  profile: BuildProfile;
+  /** profile === "debug" */
+  dev: boolean;
+  /** <app>/.akan/native/build/<platform> */
+  outDir: string;
+  /** Absolute web.dir */
+  webDir: string;
+  /** index.html with the init script injected */
+  html: string;
+  env: Record<string, string>;
+  /** Dev builds only: see BuildOptions.devServer. The native builders write it to shell.json. */
+  devServer?: string;
+  /** Dev builds only: see BuildOptions.startPath. */
+  startPath?: string;
+  android?: AndroidRelease;
+  ios?: IosBuild;
+  /** Artifacts besides the one the builder returns (an .aab next to the .apk). */
+  artifacts: { kind: "aab" | "ipa"; path: string }[];
+  /** What the builder signed with, when it signs (Android: the app's release key or the debug key). */
+  signedAs?: "debug" | "development" | "distribution";
+  /** Called through the API (BuildOptions.api). */
+  api: boolean;
+  /** Android builds with pinned libraries: the license notices file written next to the app (BuildResult.licenses). */
+  licenses?: string;
+  /** iPhone builds: the identity and profile they were signed with. */
+  iosSigning?: IosSigningResult;
+}
+
+/** A dev start path: a path on the app's origin, not one of akan-native's (/__akan_native/*). */
+export function checkStartPath(path: string): string {
+  if (!path.startsWith("/") || path.startsWith("//") || /^\/__akan_native(\/|$|\?)/.test(path) || /\s/.test(path)) {
+    throw new CliError(
+      `the start path must be a path on the app's origin like "/en/?csr=true" (got ${JSON.stringify(path)})`,
+    );
+  }
+  return path;
+}
+
+/** The app's own web build failed (AkanNativeError WEB_BUILD_FAILED). */
+export class WebBuildError extends CliError {}
+/** web.dir cannot be used as it is (AkanNativeError WEB_INPUT_INVALID). */
+export class WebInputError extends CliError {}
+
+export async function prepare(project: Project, platform: Platform, options: BuildOptions): Promise<BuildContext> {
+  const { appDir, config } = project;
+  const webDir = resolve(appDir, config.web.dir);
+  const buildProblem = buildNumberProblem(config.app.build, platform);
+  if (buildProblem) throw new ConfigError("the build number", [buildProblem]);
+  const needs = dependencyProblems(project.plugins, platform);
+  if (needs.length) throw new CliError(`plugin dependencies on ${platform}:\n  - ${needs.join("\n  - ")}`);
+
+  if (config.web.build && !options.skipWebBuild) {
+    log.step(`web build: ${config.web.build}`);
+    
+    const shell =
+      process.platform === "win32"
+        ? ["cmd.exe", "/d", "/s", "/c", config.web.build]
+        : ["/bin/sh", "-c", config.web.build];
+    const { code } = await exec(shell, {
+      cwd: appDir,
+      echo: false,
+      inherit: true,
+      tool: "web-build",
+      env: { AKAN_NATIVE_PLATFORM: platform, AKAN_NATIVE_MODE: options.mode, AKAN_NATIVE_PROFILE: options.profile },
+    });
+    if (code !== 0) throw new WebBuildError(`web build failed with exit code ${code}`);
+  }
+
+  const outDir = options.outDir ? resolve(options.outDir) : join(appDir, ".akan", "native", "build", platform);
+  const indexPath = join(webDir, "index.html");
+  let pageDir = webDir;
+  let source: string;
+  if (existsSync(indexPath)) source = readFileSync(indexPath, "utf8");
+  else if (options.devServer && options.profile === "debug") {
+
+    pageDir = `${outDir}.dev-web`;
+    rmSync(pageDir, { recursive: true, force: true });
+    mkdirSync(pageDir, { recursive: true });
+    source = DEV_SERVER_PAGE;
+    log.info(dim(`web: no ${config.web.dir}/index.html; pages come from the dev server`));
+  } else throw new WebInputError(`${relative(process.cwd(), indexPath)} not found (web.dir = ${config.web.dir})`);
+  if (existsSync(join(webDir, "__akan_native")))
+    throw new WebInputError(`${config.web.dir}/__akan_native is reserved for akan-native`);
+
+  const external = findExternalScripts(source);
+  if (external.length) {
+    log.warn(`index.html loads external scripts (the single-file rule expects inlined JS): ${external.join(", ")}`);
+  }
+  let html = injectInitScript(source, platform === "web" ? config.web.base : "/");
+  if (options.profile === "debug" && platform !== "web") html = injectEarlyErrors(html);
+  const csp = config.security?.csp;
+  if (csp !== undefined) {
+    
+    const built = buildCsp(csp, html);
+    html = injectCspMeta(html, built.policy);
+    for (const warning of built.warnings) log.warn(warning);
+    log.info(
+      dim(
+        `csp: ${csp === "strict" ? "strict" : "custom"} policy, ${built.scripts} inline script / ${built.styles} style hashes`,
+      ),
+    );
+  } else if (options.profile === "release" && !hasCspMeta(html)) {
+    log.info(dim('csp: none (set security.csp, e.g. "strict", to add a Content-Security-Policy)'));
+  }
+
+  if (options.profile === "release" && config.updates && !secureUpdateUrl(config.updates.url)) {
+
+    throw new CliError(
+      `updates.url must be https in a release build (http only for this machine): ${config.updates.url}`,
+    );
+  }
+  for (const warning of aclWarnings(resolveAcl(config.capabilities, project.plugins, platform), project.plugins))
+    log.warn(warning);
+  if (options.profile === "release" && config.capabilities === undefined && project.plugins.length) {
+    
+    log.warn(
+      "no capabilities in akan-native.config: every plugin runs with its default permissions; list the permissions the app uses",
+    );
+  }
+
+  const envResult = loadEnv(appDir, options.mode, platform, config.env, {
+    files: options.envFiles ?? true,
+    overrides: options.env ?? {},
+  });
+  if (envResult.dropped.length) {
+    log.warn(`env keys without the PUBLIC_ prefix are not passed to the app: ${envResult.dropped.join(", ")}`);
+  }
+  log.info(
+    dim(
+      `env: ${Object.keys(envResult.env).length} keys from ${["akan-native.config", ...envResult.files].join(" < ")} (mode ${options.mode}, ${options.profile} build)`,
+    ),
+  );
+  if (!options.api && writeEnvTypes(appDir, config.env)) log.info(dim(`env types: wrote ${ENV_TYPES_FILE}`));
+
+  return {
+    project,
+    platform,
+    mode: options.mode,
+    profile: options.profile,
+    dev: options.profile === "debug",
+    outDir,
+    webDir: pageDir,
+    api: options.api ?? false,
+    html,
+    env: envResult.env,
+    ...(options.profile === "debug" && options.devServer ? { devServer: options.devServer } : {}),
+    ...(options.profile === "debug" && options.startPath ? { startPath: checkStartPath(options.startPath) } : {}),
+    ...(options.android ? { android: options.android } : {}),
+    ...(options.ios ? { ios: options.ios } : {}),
+    artifacts: [],
+  };
+}
+
+/** https, or http to this machine (a local test server, `akan-native update serve`). */
+export function secureUpdateUrl(url: string): boolean {
+  try {
+    const u = new URL(url);
+    return (
+      u.protocol === "https:" ||
+      (u.protocol === "http:" &&
+        (u.hostname === "localhost" || u.hostname === "[::1]" || /^127\.\d+\.\d+\.\d+$/.test(u.hostname)))
+    );
+  } catch {
+    return false;
+  }
+}

package/vendor/@akanjs/native/packages/cli/src/lib/privacy.ts

@@ -0,0 +1,64 @@
+
+
+import type { AkanNativeConfig } from "../config.ts";
+import type { PlistValue } from "./plist.ts";
+
+/** The categories Apple lists, without the NSPrivacyAccessedAPICategory prefix. */
+export const PRIVACY_API_CATEGORIES = [
+  "FileTimestamp",
+  "SystemBootTime",
+  "DiskSpace",
+  "ActiveKeyboards",
+  "UserDefaults",
+] as const;
+const REASON = /^[0-9A-F]{4}\.\d$/;
+
+export interface PrivacySource {
+  /** Who declares it, for error messages ("plugin filesystem", "the app"). */
+  who: string;
+  apis: Record<string, string[]> | undefined;
+}
+
+/** Problems with a category → reasons map. */
+export function privacyApiProblems({ who, apis }: PrivacySource): string[] {
+  if (apis === undefined) return [];
+  if (!apis || typeof apis !== "object" || Array.isArray(apis))
+    return [`${who}: privacy APIs must be an object like { "UserDefaults": ["CA92.1"] }`];
+  const problems: string[] = [];
+  for (const [category, reasons] of Object.entries(apis)) {
+    if (!(PRIVACY_API_CATEGORIES as readonly string[]).includes(category))
+      problems.push(
+        `${who}: unknown Required Reason API category ${JSON.stringify(category)} (${PRIVACY_API_CATEGORIES.join(", ")})`,
+      );
+    if (!Array.isArray(reasons) || !reasons.length || !reasons.every((r) => typeof r === "string" && REASON.test(r))) {
+      problems.push(`${who}: ${category} needs reason codes like "CA92.1"`);
+    }
+  }
+  return problems;
+}
+
+/** PrivacyInfo.xcprivacy's root dictionary: every declared category once, reasons merged and sorted. */
+export function privacyManifest(
+  sources: PrivacySource[],
+  privacy: AkanNativeConfig["privacy"] = {},
+): Record<string, PlistValue> {
+  const merged = new Map<string, Set<string>>();
+  for (const { apis } of [...sources, { who: "the app", apis: privacy.accessedApis }]) {
+    for (const [category, reasons] of Object.entries(apis ?? {})) {
+      const set = merged.get(category) ?? new Set<string>();
+      for (const r of reasons) set.add(r);
+      merged.set(category, set);
+    }
+  }
+  return {
+    NSPrivacyTracking: privacy.tracking ?? false,
+    NSPrivacyTrackingDomains: privacy.trackingDomains ?? [],
+    NSPrivacyCollectedDataTypes: (privacy.collectedDataTypes ?? []) as PlistValue[],
+    NSPrivacyAccessedAPITypes: [...merged]
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([category, reasons]) => ({
+        NSPrivacyAccessedAPIType: `NSPrivacyAccessedAPICategory${category}`,
+        NSPrivacyAccessedAPITypeReasons: [...reasons].sort(),
+      })),
+  };
+}