@caperjs/core 0.7.2 → 0.7.4

package/cli/native.mjs

@@ -6,6 +6,8 @@ import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
 
+import { resolveOrientation } from '../src/utils/orientation.js';
+
 /**
  * `caper native init` — one-shot Tauri v2 scaffolding for a Caper app: adds
  * `@tauri-apps/cli`, runs `tauri init --ci` with a pinned identifier/port,
@@ -18,6 +20,16 @@ const IDENTIFIER_RE = /^[a-z][a-z0-9]*(\.[a-z][a-z0-9-]*)+$/;
 const PLACEHOLDER_IDENTIFIER = 'com.tauri.dev';
 const DEFAULT_IDENTIFIER_PREFIX = 'dev.caper.';
 
+/** A window/app title from a package name: strip an npm scope, split on `-`/`_`/`.`, capitalize each word. */
+export function displayTitle(packageName) {
+  return String(packageName ?? '')
+    .replace(/^@[^/]+\//, '')
+    .split(/[-_.\s]+/)
+    .filter(Boolean)
+    .map((word) => word[0].toUpperCase() + word.slice(1))
+    .join(' ');
+}
+
 /** Strip an npm scope, lowercase, collapse non `[a-z0-9]` runs to `-`, trim `-`. */
 export function appSlug(packageName) {
   return String(packageName ?? '')
@@ -120,10 +132,37 @@ function renderCommand({ cmd, args }) {
   return [cmd, ...args].join(' ');
 }
 
+/** The `caper.config.ts` orientation values, and the `android:screenOrientation` each one becomes. */
+export const ANDROID_SCREEN_ORIENTATION = Object.freeze({ portrait: 'portrait', landscape: 'sensorLandscape' });
+
+/** The default injectable `loadConfig`: the subset of `caper.config.ts` the native commands read. */
+async function defaultLoadConfig(cwd) {
+  // Imported lazily: build/ pulls in the oxc parser and vite, which only these commands need.
+  const { readConfigOrientation } = await import('../build/internal/buildFlags.mjs');
+  return { orientation: readConfigOrientation(cwd) };
+}
+
+/**
+ * The orientation lock from `caper.config.ts` through `loadConfig` (either form
+ * of `orientation`, normalized by `resolveOrientation`), or a warning when it
+ * can't be read: a broken or unusual config must never stop a native command.
+ *
+ * @returns {Promise<{ orientation?: 'portrait' | 'landscape', warning?: string }>}
+ */
+export async function readOrientation(cwd, loadConfig = defaultLoadConfig) {
+  try {
+    return { orientation: resolveOrientation((await loadConfig(cwd))?.orientation)?.lock };
+  } catch (err) {
+    return { warning: `could not read caper.config.ts orientation (${err.message}), so orientation was skipped.` };
+  }
+}
+
 /** Returns a new tauri.conf.json: sets `identifier` and window 0's title/size; leaves the rest untouched. */
-export function patchTauriConfig(conf, { identifier, title }) {
+export function patchTauriConfig(conf, { identifier, title, orientation }) {
   const windows = Array.isArray(conf.app?.windows) ? [...conf.app.windows] : [];
-  windows[0] = { ...(windows[0] ?? {}), title, width: 1280, height: 720 };
+  // 450x800 keeps a portrait window, title bar included, on a 13" laptop screen.
+  const size = orientation === 'portrait' ? { width: 450, height: 800 } : { width: 1280, height: 720 };
+  windows[0] = { ...(windows[0] ?? {}), title, ...size };
 
   return {
     ...conf,
@@ -198,9 +237,9 @@ function writeJson(file, data, indent) {
  *
  * @param {string} cwd
  * @param {{ identifier?: string, port?: number, icon?: string }} [opts]
- * @param {{ run?: typeof defaultRun }} [deps]
+ * @param {{ run?: typeof defaultRun, loadConfig?: typeof defaultLoadConfig }} [deps]
  */
-export async function initNative(cwd, opts = {}, { run = defaultRun } = {}) {
+export async function initNative(cwd, opts = {}, { run = defaultRun, loadConfig = defaultLoadConfig } = {}) {
   const pkgPath = path.join(cwd, 'package.json');
   if (!fs.existsSync(pkgPath)) {
     throw new Error('no package.json found in this directory.');
@@ -219,7 +258,7 @@ export async function initNative(cwd, opts = {}, { run = defaultRun } = {}) {
   // vars can instead reflect an unrelated ancestor process (e.g. a monorepo
   // task runner). Read the name straight from the package.json we already have.
   const name = pkg.name ?? 'app';
-  const title = opts.title ?? name;
+  const title = opts.title ?? displayTitle(name);
   const slug = appSlug(pkg.name ?? name);
 
   const identifier = opts.identifier ?? defaultIdentifier(slug);
@@ -244,7 +283,7 @@ export async function initNative(cwd, opts = {}, { run = defaultRun } = {}) {
     'init',
     '--ci',
     '--app-name',
-    name,
+    title,
     '--window-title',
     title,
     '--frontend-dist',
@@ -258,17 +297,24 @@ export async function initNative(cwd, opts = {}, { run = defaultRun } = {}) {
   ];
   run(EXEC_RUNNER[pm], initArgs, { cwd });
 
+  const warnings = [];
+  const { orientation, warning } = await readOrientation(cwd, loadConfig);
+  if (warning) warnings.push(warning);
+
   const tauriConfPath = path.join(srcTauriDir, 'tauri.conf.json');
   const tauriConf = JSON.parse(fs.readFileSync(tauriConfPath, 'utf-8'));
-  writeJson(tauriConfPath, patchTauriConfig(tauriConf, { identifier, title }), 2);
+  writeJson(tauriConfPath, patchTauriConfig(tauriConf, { identifier, title, orientation }), 2);
 
-  writeJson(pkgPath, patchPackageScripts(pkg), detectIndent(pkgRaw));
+  // Re-read: the package manager rewrote package.json when it added @tauri-apps/cli,
+  // and patching the copy read above would silently drop that devDependency.
+  const freshPkgRaw = fs.readFileSync(pkgPath, 'utf-8');
+  writeJson(pkgPath, patchPackageScripts(JSON.parse(freshPkgRaw)), detectIndent(freshPkgRaw));
 
   if (opts.icon) {
     run(EXEC_RUNNER[pm], ['tauri', 'icon', opts.icon], { cwd });
   }
 
-  return { status: 'ok', name, title, identifier, port, pm };
+  return { status: 'ok', name, title, identifier, port, pm, orientation, warnings };
 }
 
 /**
@@ -528,6 +574,38 @@ export function findMainActivity(genAndroidDir) {
   return walk(path.join(genAndroidDir, 'app/src/main/java'));
 }
 
+/** Where `tauri android init` writes the app manifest, relative to `src-tauri/`. */
+export const ANDROID_MANIFEST = 'gen/android/app/src/main/AndroidManifest.xml';
+
+const MAIN_ACTIVITY_TAG_RE = /<activity\b[^>]*\bandroid:name="\.MainActivity"[^>]*>/;
+const SCREEN_ORIENTATION_RE = /(\bandroid:screenOrientation=")([^"]*)(")/;
+
+/** The MainActivity's `android:screenOrientation` in an AndroidManifest.xml, or `undefined`. */
+export function readManifestOrientation(xml) {
+  return String(xml ?? '').match(MAIN_ACTIVITY_TAG_RE)?.[0].match(SCREEN_ORIENTATION_RE)?.[2];
+}
+
+/**
+ * Sets `android:screenOrientation` on the `.MainActivity` element for a
+ * `caper.config.ts` orientation (see `ANDROID_SCREEN_ORIENTATION`), replacing a
+ * different value or adding the attribute under `android:name` with its
+ * indentation. Returns `xml` itself when nothing changes, including when
+ * `orientation` is unset or there is no MainActivity element.
+ */
+export function patchManifestOrientation(xml, orientation) {
+  const value = ANDROID_SCREEN_ORIENTATION[orientation];
+  const tag = value ? xml.match(MAIN_ACTIVITY_TAG_RE)?.[0] : undefined;
+  if (!tag) return xml;
+
+  let patched;
+  if (SCREEN_ORIENTATION_RE.test(tag)) {
+    patched = tag.replace(SCREEN_ORIENTATION_RE, `$1${value}$3`);
+  } else {
+    patched = tag.replace(/(\s+)(android:name="\.MainActivity")/, `$1$2$1android:screenOrientation="${value}"`);
+  }
+  return patched === tag ? xml : xml.replace(tag, patched);
+}
+
 /** Returns a new package.json: adds `native:android:dev`/`native:android:build` scripts only where absent. */
 export function patchAndroidScripts(pkg) {
   const scripts = { ...(pkg.scripts ?? {}) };
@@ -559,13 +637,15 @@ const ANDROID_MISSING_HELP = {
  * The I/O core of `caper native android`: the Android steps from
  * docs/wiki/native-tauri.md: installs the Rust targets, runs
  * `tauri android init --ci`, adds the 16 KB page-alignment link arg to
- * `build.rs`, hides the system bars in `MainActivity.kt`, and adds
- * `native:android:*` scripts. No console output; the CLI wrapper below owns
- * presentation. Idempotent: a second run makes zero `run` calls and zero writes.
+ * `build.rs`, hides the system bars in `MainActivity.kt`, locks the
+ * MainActivity to `caper.config.ts`'s `orientation` in `AndroidManifest.xml`
+ * (only when it is set), and adds `native:android:*` scripts. No console
+ * output; the CLI wrapper below owns presentation. Idempotent: a second run
+ * makes zero `run` calls and zero writes.
  *
  * @param {string} cwd
  * @param {object} [opts] unused today; kept for symmetry with `initNative`
- * @param {{ run?: typeof defaultRun, exec?: typeof defaultExec, env?: Record<string, string>, platform?: string, homedir?: string, exists?: (p: string) => boolean, listDir?: (p: string) => string[] }} [deps]
+ * @param {{ run?: typeof defaultRun, exec?: typeof defaultExec, env?: Record<string, string>, platform?: string, homedir?: string, exists?: (p: string) => boolean, listDir?: (p: string) => string[], loadConfig?: typeof defaultLoadConfig }} [deps]
  */
 export async function androidNative(
   cwd,
@@ -578,6 +658,7 @@ export async function androidNative(
     homedir = os.homedir(),
     exists = fs.existsSync,
     listDir = defaultListDir,
+    loadConfig = defaultLoadConfig,
   } = {},
 ) {
   const pkgPath = path.join(cwd, 'package.json');
@@ -637,6 +718,24 @@ export async function androidNative(
     }
   }
 
+  // Unset means no lock: the manifest is left alone, never rewritten to "unspecified".
+  let orientationPatched = false;
+  const { orientation, warning: orientationWarning } = await readOrientation(cwd, loadConfig);
+  if (orientationWarning) warnings.push(orientationWarning);
+  if (orientation) {
+    const manifestPath = path.join(srcTauriDir, ANDROID_MANIFEST);
+    const xml = fs.existsSync(manifestPath) ? fs.readFileSync(manifestPath, 'utf-8') : null;
+    const patched = xml === null ? null : patchManifestOrientation(xml, orientation);
+    if (patched === null || readManifestOrientation(patched) !== ANDROID_SCREEN_ORIENTATION[orientation]) {
+      warnings.push(
+        `could not find the MainActivity in src-tauri/${ANDROID_MANIFEST}, so the ${orientation} orientation was not applied. Set android:screenOrientation="${ANDROID_SCREEN_ORIENTATION[orientation]}" on it by hand.`,
+      );
+    } else if (patched !== xml) {
+      fs.writeFileSync(manifestPath, patched, 'utf-8');
+      orientationPatched = true;
+    }
+  }
+
   const pkgRaw = fs.readFileSync(pkgPath, 'utf-8');
   const pkg = JSON.parse(pkgRaw);
   const patchedPkg = patchAndroidScripts(pkg);
@@ -648,11 +747,14 @@ export async function androidNative(
   const buildRsPatched = buildRsPlan === 'write';
   return {
     status: 'ok',
-    changed: addedTargets.length > 0 || ranAndroidInit || buildRsPatched || mainActivityPatched || addedScripts.length > 0,
+    changed:
+      addedTargets.length > 0 || ranAndroidInit || buildRsPatched || mainActivityPatched || orientationPatched || addedScripts.length > 0,
     addedTargets,
     ranAndroidInit,
     buildRsPatched,
     mainActivityPatched,
+    orientation,
+    orientationPatched,
     addedScripts,
     env: {
       ANDROID_HOME: resolved.env.ANDROID_HOME,
@@ -666,7 +768,7 @@ export async function androidNative(
 }
 
 function printUsage() {
-  console.error(red('Usage: caper native init [--identifier <id>] [--port <n>] [--icon <png>]'));
+  console.error(red('Usage: caper native init [--title <name>] [--identifier <id>] [--port <n>] [--icon <png>]'));
   console.error(red('       caper native plugin'));
   console.error(red('       caper native android'));
 }
@@ -687,6 +789,10 @@ function parseInitArgs(args) {
       const next = args[++i];
       if (!next) throw new Error('Missing value for --icon');
       opts.icon = next;
+    } else if (arg === '--title') {
+      const next = args[++i];
+      if (!next) throw new Error('Missing value for --title');
+      opts.title = next;
     } else {
       throw new Error(`Unknown option: ${arg}`);
     }
@@ -722,6 +828,8 @@ async function runInit(args) {
   console.log(`  ${yellow('identifier:')} ${result.identifier}${result.identifier.startsWith(DEFAULT_IDENTIFIER_PREFIX) ? dim(' (placeholder — change before shipping)') : ''}`);
   console.log(`  ${yellow('dev port:')}   ${result.port}`);
   console.log(`  ${yellow('scripts:')}    native:dev, native:build`);
+  if (result.orientation) console.log(`  ${yellow('window:')}     ${result.orientation === 'portrait' ? '450x800' : '1280x720'} (${result.orientation}, from caper.config.ts)`);
+  for (const warning of result.warnings) console.log(yellow(`  ⚠ ${warning}`));
   console.log(`\n  Run ${cyan('npx caper doctor')} to check your native toolchain.`);
   console.log(`  The first ${cyan('native:build')} compiles Rust — expect a few minutes.`);
 }
@@ -766,6 +874,9 @@ async function runAndroid() {
     if (result.ranAndroidInit) console.log(`  ${yellow('ran:')} tauri android init --ci`);
     if (result.buildRsPatched) console.log(`  ${yellow('build.rs:')} 16 KB page alignment added to src-tauri/build.rs`);
     if (result.mainActivityPatched) console.log(`  ${yellow('MainActivity.kt:')} system bars hidden`);
+    if (result.orientationPatched) {
+      console.log(`  ${yellow('AndroidManifest.xml:')} ${result.orientation} orientation (android:screenOrientation="${ANDROID_SCREEN_ORIENTATION[result.orientation]}")`);
+    }
     if (result.addedScripts.length) console.log(`  ${yellow('scripts:')} ${result.addedScripts.join(', ')}`);
   }
   for (const warning of result.warnings) console.log(yellow(`  ⚠ ${warning}`));

package/cli/native.test.mjs

@@ -4,6 +4,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { afterEach, describe, expect, it } from 'vitest';
 
 import {
@@ -14,6 +15,7 @@ import {
   commandsFor,
   defaultIdentifier,
   defaultPort,
+  displayTitle,
   findMainActivity,
   initNative,
   isValidIdentifier,
@@ -23,15 +25,23 @@ import {
   parsePort,
   patchAndroidScripts,
   patchCapabilities,
+  patchManifestOrientation,
   patchPackageScripts,
   patchTauriConfig,
   planBuildRs,
   planMainActivity,
+  readManifestOrientation,
   renderMainActivity,
   resolveAndroidEnv,
   TAURI_PLUGIN_PERMISSIONS,
 } from './native.mjs';
 
+// A copy of the manifest `tauri android init` generated for kitchen-sink.
+const MANIFEST_FIXTURE = fs.readFileSync(
+  path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../test/fixtures/android/AndroidManifest.xml'),
+  'utf-8',
+);
+
 let tempDir = null;
 
 afterEach(() => {
@@ -46,6 +56,14 @@ function makeTempDir() {
   return tempDir;
 }
 
+describe('displayTitle', () => {
+  it('title-cases a package name into a window title', () => {
+    expect(displayTitle('rhodora')).toBe('Rhodora');
+    expect(displayTitle('my-game')).toBe('My Game');
+    expect(displayTitle('@studio/space_rocks')).toBe('Space Rocks');
+  });
+});
+
 describe('appSlug', () => {
   it('strips a scope, lowercases, and collapses non-alnum runs to a hyphen', () => {
     expect(appSlug('@acme/My Game')).toBe('my-game');
@@ -244,6 +262,16 @@ describe('patchTauriConfig', () => {
     expect(patched.app.windows[0].resizable).toBe(true);
   });
 
+  it('uses a 450x800 window for a portrait game', () => {
+    const patched = patchTauriConfig(conf, { identifier: 'dev.caper.my-game', title: 'My Game', orientation: 'portrait' });
+    expect(patched.app.windows[0]).toMatchObject({ width: 450, height: 800 });
+  });
+
+  it('keeps 1280x720 for a landscape game', () => {
+    const patched = patchTauriConfig(conf, { identifier: 'dev.caper.my-game', title: 'My Game', orientation: 'landscape' });
+    expect(patched.app.windows[0]).toMatchObject({ width: 1280, height: 720 });
+  });
+
   it('does not mutate the original object', () => {
     patchTauriConfig(conf, { identifier: 'dev.caper.my-game', title: 'My Game' });
     expect(conf.identifier).toBe('com.tauri.dev');
@@ -315,6 +343,56 @@ describe('initNative', () => {
     };
   }
 
+  it('keeps the @tauri-apps/cli devDependency the package manager just added', async () => {
+    const dir = makeTempDir();
+    scaffoldApp(dir);
+    const calls = [];
+    const tauriRun = stubbedRun(calls);
+    // Like a real `pnpm add -D`, write the devDependency into package.json.
+    const run = (cmd, args, opts) => {
+      if (args[0] === 'add') {
+        const pkgPath = path.join(opts.cwd, 'package.json');
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        pkg.devDependencies = { ...pkg.devDependencies, '@tauri-apps/cli': '^2.12.1' };
+        fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
+      }
+      return tauriRun(cmd, args, opts);
+    };
+
+    await initNative(dir, {}, { run });
+
+    const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf-8'));
+    expect(pkg.devDependencies['@tauri-apps/cli']).toBe('^2.12.1');
+    expect(pkg.scripts['native:build']).toBe('tauri build');
+  });
+
+  it('sizes the window from caper.config orientation', async () => {
+    const dir = makeTempDir();
+    scaffoldApp(dir);
+
+    const result = await initNative(dir, {}, { run: stubbedRun([]), loadConfig: () => ({ orientation: 'portrait' }) });
+
+    expect(result.warnings).toEqual([]);
+    const conf = JSON.parse(fs.readFileSync(path.join(dir, 'src-tauri/tauri.conf.json'), 'utf-8'));
+    expect(conf.app.windows[0]).toMatchObject({ width: 450, height: 800 });
+  });
+
+  it('warns and keeps 1280x720 when caper.config orientation cannot be read', async () => {
+    const dir = makeTempDir();
+    scaffoldApp(dir);
+    const loadConfig = () => {
+      throw new Error('boom');
+    };
+
+    const result = await initNative(dir, {}, { run: stubbedRun([]), loadConfig });
+
+    expect(result.status).toBe('ok');
+    expect(result.warnings).toHaveLength(1);
+    expect(result.warnings[0]).toMatch(/could not read caper\.config\.ts orientation/);
+    const conf = JSON.parse(fs.readFileSync(path.join(dir, 'src-tauri/tauri.conf.json'), 'utf-8'));
+    expect(conf.app.windows[0]).toMatchObject({ width: 1280, height: 720 });
+  });
+
   it('does nothing and makes zero run calls when src-tauri already exists', async () => {
     const dir = makeTempDir();
     scaffoldApp(dir);
@@ -360,9 +438,9 @@ describe('initNative', () => {
       'init',
       '--ci',
       '--app-name',
-      'my-game',
+      'My Game',
       '--window-title',
-      'my-game',
+      'My Game',
       '--frontend-dist',
       '../dist',
       '--dev-url',
@@ -375,7 +453,7 @@ describe('initNative', () => {
 
     const conf = JSON.parse(fs.readFileSync(path.join(dir, 'src-tauri/tauri.conf.json'), 'utf-8'));
     expect(conf.identifier).toBe('dev.caper.mygame');
-    expect(conf.app.windows[0]).toMatchObject({ title: 'my-game', width: 1280, height: 720 });
+    expect(conf.app.windows[0]).toMatchObject({ title: 'My Game', width: 1280, height: 720 });
     expect(conf.app.security.csp).toBeNull();
     expect(conf.bundle).toEqual({ active: true, targets: ['app'] });
 
@@ -891,6 +969,7 @@ describe('androidNative', () => {
           const dir = path.join(opts.cwd, 'src-tauri/gen/android/app/src/main/java/x/y/z');
           fs.mkdirSync(dir, { recursive: true });
           fs.writeFileSync(path.join(dir, 'MainActivity.kt'), STOCK_MAIN_ACTIVITY, 'utf-8');
+          fs.writeFileSync(path.join(opts.cwd, 'src-tauri/gen/android/app/src/main/AndroidManifest.xml'), MANIFEST_FIXTURE, 'utf-8');
         } else {
           throw new Error(`unstubbed run: ${cmd} ${args.join(' ')}`);
         }
@@ -989,6 +1068,103 @@ describe('androidNative', () => {
     expect(snapshot(dir)).toEqual(before);
   });
 
+  const manifestPath = (dir) => path.join(dir, 'src-tauri/gen/android/app/src/main/AndroidManifest.xml');
+
+  it('leaves AndroidManifest.xml alone when caper.config sets no orientation', async () => {
+    const dir = makeTempDir();
+    const deps = scaffoldAndroidApp(dir);
+
+    const result = await androidNative(dir, {}, { ...stubs({ installed: [] }, []), ...deps, loadConfig: () => ({}) });
+
+    expect(result.orientation).toBeUndefined();
+    expect(result.orientationPatched).toBe(false);
+    expect(result.warnings).toEqual([]);
+    expect(fs.readFileSync(manifestPath(dir), 'utf-8')).toBe(MANIFEST_FIXTURE);
+  });
+
+  it('locks MainActivity to caper.config orientation', async () => {
+    const dir = makeTempDir();
+    const deps = scaffoldAndroidApp(dir);
+
+    const result = await androidNative(dir, {}, { ...stubs({ installed: [] }, []), ...deps, loadConfig: () => ({ orientation: 'portrait' }) });
+
+    expect(result.orientation).toBe('portrait');
+    expect(result.orientationPatched).toBe(true);
+    expect(readManifestOrientation(fs.readFileSync(manifestPath(dir), 'utf-8'))).toBe('portrait');
+  });
+
+  it('applies a changed orientation on the next run, then makes zero writes', async () => {
+    const dir = makeTempDir();
+    const deps = scaffoldAndroidApp(dir);
+    const state = { installed: [] };
+    await androidNative(dir, {}, { ...stubs(state, []), ...deps, loadConfig: () => ({ orientation: 'portrait' }) });
+
+    const landscape = { ...deps, loadConfig: () => ({ orientation: 'landscape' }) };
+    const changed = await androidNative(dir, {}, { ...stubs(state, []), ...landscape });
+    expect(changed.changed).toBe(true);
+    expect(changed.orientationPatched).toBe(true);
+    expect(readManifestOrientation(fs.readFileSync(manifestPath(dir), 'utf-8'))).toBe('sensorLandscape');
+
+    const before = snapshot(dir);
+    const calls = [];
+    const again = await androidNative(dir, {}, { ...stubs(state, calls), ...landscape });
+    expect(calls.filter((c) => c.kind === 'run')).toHaveLength(0);
+    expect(again.changed).toBe(false);
+    expect(again.orientationPatched).toBe(false);
+    expect(snapshot(dir)).toEqual(before);
+  });
+
+  it('reads the lock from the object form of orientation', async () => {
+    const dir = makeTempDir();
+    const deps = scaffoldAndroidApp(dir);
+    const loadConfig = () => ({ orientation: { lock: 'landscape', overlay: false } });
+
+    const result = await androidNative(dir, {}, { ...stubs({ installed: [] }, []), ...deps, loadConfig });
+
+    expect(result.orientation).toBe('landscape');
+    expect(readManifestOrientation(fs.readFileSync(manifestPath(dir), 'utf-8'))).toBe('sensorLandscape');
+  });
+
+  it('warns and skips orientation when caper.config orientation is invalid', async () => {
+    const dir = makeTempDir();
+    const deps = scaffoldAndroidApp(dir);
+
+    const result = await androidNative(dir, {}, { ...stubs({ installed: [] }, []), ...deps, loadConfig: () => ({ orientation: { lock: 'any' } }) });
+
+    expect(result.orientationPatched).toBe(false);
+    expect(result.warnings[0]).toMatch(/could not read caper\.config\.ts orientation/);
+    expect(fs.readFileSync(manifestPath(dir), 'utf-8')).toBe(MANIFEST_FIXTURE);
+  });
+
+  it('warns and skips orientation when caper.config cannot be read', async () => {
+    const dir = makeTempDir();
+    const deps = scaffoldAndroidApp(dir);
+    const loadConfig = () => {
+      throw new Error('boom');
+    };
+
+    const result = await androidNative(dir, {}, { ...stubs({ installed: [] }, []), ...deps, loadConfig });
+
+    expect(result.status).toBe('ok');
+    expect(result.orientationPatched).toBe(false);
+    expect(result.warnings).toHaveLength(1);
+    expect(result.warnings[0]).toMatch(/could not read caper\.config\.ts orientation/);
+    expect(fs.readFileSync(manifestPath(dir), 'utf-8')).toBe(MANIFEST_FIXTURE);
+  });
+
+  it('warns when orientation is set but AndroidManifest.xml is missing', async () => {
+    const dir = makeTempDir();
+    const deps = scaffoldAndroidApp(dir);
+    await androidNative(dir, {}, { ...stubs({ installed: [] }, []), ...deps, loadConfig: () => ({}) });
+    fs.rmSync(manifestPath(dir));
+
+    const result = await androidNative(dir, {}, { ...stubs({ installed: [...ANDROID_RUST_TARGETS] }, []), ...deps, loadConfig: () => ({ orientation: 'portrait' }) });
+
+    expect(result.orientationPatched).toBe(false);
+    expect(result.warnings).toHaveLength(1);
+    expect(result.warnings[0]).toMatch(/AndroidManifest\.xml/);
+  });
+
   it('writes the build.rs template when build.rs is missing', async () => {
     const dir = makeTempDir();
     const deps = scaffoldAndroidApp(dir);
@@ -1023,6 +1199,46 @@ describe('androidNative', () => {
   });
 });
 
+describe('patchManifestOrientation', () => {
+  const withAttr = (value) => MANIFEST_FIXTURE.replace('android:name=".MainActivity"', `android:name=".MainActivity"\n            android:screenOrientation="${value}"`);
+
+  it('reads no orientation from the stock manifest', () => {
+    expect(readManifestOrientation(MANIFEST_FIXTURE)).toBeUndefined();
+  });
+
+  it('adds android:screenOrientation under android:name, matching its indentation', () => {
+    const patched = patchManifestOrientation(MANIFEST_FIXTURE, 'portrait');
+    expect(patched).toBe(withAttr('portrait'));
+    expect(readManifestOrientation(patched)).toBe('portrait');
+  });
+
+  it('maps landscape to sensorLandscape', () => {
+    expect(patchManifestOrientation(MANIFEST_FIXTURE, 'landscape')).toBe(withAttr('sensorLandscape'));
+  });
+
+  it('returns the same string when the value already matches', () => {
+    const xml = withAttr('portrait');
+    expect(patchManifestOrientation(xml, 'portrait')).toBe(xml);
+  });
+
+  it('replaces a different existing value', () => {
+    expect(patchManifestOrientation(withAttr('landscape'), 'portrait')).toBe(withAttr('portrait'));
+    expect(patchManifestOrientation(withAttr('portrait'), 'landscape')).toBe(withAttr('sensorLandscape'));
+  });
+
+  it('returns the same string when orientation is unset', () => {
+    const xml = withAttr('portrait');
+    expect(patchManifestOrientation(xml, undefined)).toBe(xml);
+  });
+
+  it('only touches the MainActivity element', () => {
+    const xml = MANIFEST_FIXTURE.replace('<provider', '<activity android:name=".Other" />\n\n        <provider');
+    const patched = patchManifestOrientation(xml, 'portrait');
+    expect(patched).toContain('<activity android:name=".Other" />');
+    expect(patched.match(/screenOrientation/g)).toHaveLength(1);
+  });
+});
+
 describe('findMainActivity', () => {
   it('finds MainActivity.kt anywhere under the java source root', () => {
     const dir = makeTempDir();

package/extras/llms.txt

@@ -219,9 +219,9 @@ subcommands run from the app root.
 | `caper doctor [--offline] [--json]` | One-screen health check: installed vs latest caper, npm vs linked engine (and whether the linked build is stale), generated types present/fresh, asset manifest, agent pointers, peer deps, caches. Exit 1 on any ✗. |
 | `caper agent init [--dir <skillsDir>]` | Install the shipped `caper` agent skill (default `.claude/skills/caper/SKILL.md`) and upsert a pointer block into `AGENTS.md`/`CLAUDE.md`. Re-run after upgrading caper. |
 | `caper agent probe <url> [--action n[=json]]… [--until "<js predicate>"] [--wait ms] [--screenshot p] [--headed] [--json]` | Drive a **running** app headlessly through the automation bridge (§17) in a Chromium you own: boots, sends actions, waits on state, returns context/state/log/errors (+ screenshot). Needs `playwright` in the app's devDependencies. |
-| `caper native init [--identifier <id>] [--port <n>] [--icon <png>]` | One-shot Tauri v2 scaffolding: adds `@tauri-apps/cli`, runs `tauri init --ci`, pins a `dev.caper.*`-style identifier + a stable non-3000 dev port, adds `native:dev`/`native:build` scripts. No-ops with "already initialized" if `src-tauri/` exists. |
+| `caper native init [--title <name>] [--identifier <id>] [--port <n>] [--icon <png>]` | One-shot Tauri v2 scaffolding: adds `@tauri-apps/cli`, runs `tauri init --ci`, names the app and window after the package (title-cased: `my-game` → "My Game"; `--title` overrides), pins a `dev.caper.*`-style identifier + a stable non-3000 dev port, opens a 1280x720 window (450x800 when `caper.config.ts` sets `orientation: 'portrait'`), adds `native:dev`/`native:build` scripts. No-ops with "already initialized" if `src-tauri/` exists. |
 | `caper native plugin` | Wires an already-`native init`'d app up for `@caperjs/plugin-tauri`: adds its JS deps, runs `tauri add store`, and patches the window permissions it needs into `capabilities/default.json`. Fails with "run `caper native init` first" if `src-tauri/` is missing; idempotent otherwise. |
-| `caper native android` | Sets an already-`native init`'d app up for Android: finds the SDK/NDK/JDK/rustup, adds the four Android Rust targets, runs `tauri android init --ci`, adds 16 KB page alignment to `build.rs`, hides the system bars in `MainActivity.kt`, adds `native:android:dev`/`native:android:build` scripts. Idempotent; warns instead of overwriting files you changed. |
+| `caper native android` | Sets an already-`native init`'d app up for Android: finds the SDK/NDK/JDK/rustup, adds the four Android Rust targets, runs `tauri android init --ci`, adds 16 KB page alignment to `build.rs`, hides the system bars in `MainActivity.kt`, locks the activity to `caper.config.ts`'s `orientation` (if set; re-run after changing it), adds `native:android:dev`/`native:android:build` scripts. Idempotent; warns instead of overwriting files you changed. |
 | `caper update` | Update Caper to latest. |
 | `caper install` | Install peer deps (rarely needed; normally automatic). |
 | `caper vo generate [inputDir] [outputDir]` | Voiceover CSV generation from locales. Defaults: `./src/locales` → `./src/assets/audio/vo/csv`. |
@@ -236,7 +236,10 @@ exists. For Android, run `caper native android` once, then
 `pnpm native:android:dev` (device or emulator) or
 `pnpm native:android:build --debug --apk --target aarch64`, with `NDK_HOME` and
 `JAVA_HOME` exported; doctor adds `native-android-*` rows (Rust targets, NDK,
-JDK, 16 KB alignment, hidden system bars) once `src-tauri/gen/android/` exists. Under the Tauri CLI (detected via `TAURI_ENV_PLATFORM`), the preset
+JDK, 16 KB alignment, hidden system bars, and orientation matching `caper.config.ts`) once `src-tauri/gen/android/` exists.
+Set `orientation: 'portrait' | 'landscape'` in `caper.config.ts` rather than editing
+`AndroidManifest.xml` by hand: `caper native android` writes it there (`portrait` or
+`sensorLandscape`) and doctor flags a mismatch. Under the Tauri CLI (detected via `TAURI_ENV_PLATFORM`), the preset
 configures the dev server for you — no extra `vite.config.ts` needed — and
 disables the PWA plugin, since service workers don't work on the `tauri://`
 origin. Check `isTauri` (exported from `@caperjs/core`, alongside
@@ -480,9 +483,29 @@ Every allowed key in `caper.config.ts`. Defer shape details to
 | `resolution?: number` | DPI scale factor. |
 | `splash?: SplashOptions` | Splash screen config. |
 | `logger?: LoggerMode` | Verbosity. |
+| `orientation?: 'portrait' \| 'landscape' \| { lock, overlay? }` | Lock the game to one orientation on every target. Unset means no lock. The string is shorthand for `{ lock: '...' }`. Write the lock as a string literal (the build and CLI read it by parsing the file). `caper native android` writes it into `AndroidManifest.xml`, `caper native init` opens a 450x800 window for portrait, the PWA manifest's `orientation` defaults to it, and in a mobile browser (not desktop, not Tauri) a "rotate your device" overlay covers and pauses the game while the device is held the wrong way. |
+| `orientation.overlay?: false \| { text?, background?, color?, fontFamily?, className?, element? }` | Restyle that overlay; `element: () => HTMLElement` replaces it, `false` turns off the overlay and its pause (`app.orientation.onMismatchChanged` / `app.orientation.mismatched` still report). |
 
 Plus all standard PixiJS `ApplicationOptions` (`antialias`, `width`, `height`, etc.).
 
+Orientation overlay, customized or replaced:
+
+```ts
+// shorthand: lock to portrait with the default overlay
+export default defineConfig({ id: 'my-game', orientation: 'portrait' });
+
+// object form: same lock, custom overlay
+export default defineConfig({
+  id: 'my-game',
+  orientation: { lock: 'portrait', overlay: { text: 'Hold your phone upright to play' } },
+  // also: background, color, fontFamily, className (style it in your CSS),
+  // element: () => myOwnElement, or overlay: false to draw nothing and react yourself
+});
+
+// with overlay: false
+app.orientation.onMismatchChanged.connect((mismatched) => (mismatched ? app.pause() : app.resume()));
+```
+
 Screen viewport debugging is available through the built-in `screenDebug` overlay.
 Open the game URL in a normal browser tab with `?caper-screen-debug=1` to enable it.
 Then relaunch the installed PWA; the same-origin setting persists without an address bar.
@@ -834,6 +857,15 @@ then push toasts to it. Also available as `app.popups.toast(...)`.
 
 A FlexContainer preset for app-size-bound HUDs. Use as the root of in-game UI.
 
+It pads by the device safe-area insets (notch, camera hole, gesture bar) by
+default. `useSafeArea: false` turns that off; `{ top: false }` turns off one
+edge, e.g. to let corner buttons sit in a punch-hole phone's camera strip:
+
+```ts
+import { isAndroid, isTauri } from '@caperjs/core';
+const hud = this.add.uiCanvas({ useAppSize: true, useSafeArea: isTauri && isAndroid ? { top: false } : true });
+```
+
 ### 7.6 `Joystick` — virtual stick
 
 For touch input. Wires into the `controls.touch.joystick` bindings set via