@caperjs/core 0.7.3 → 0.7.4

package/build/index.mjs

@@ -92,7 +92,7 @@ function caperPluginList({ assets = {}, pwa } = {}) {
     // place that knows a project overrode it.
     caperConfigPlugin(true, manifestUrl),
     caperDevHelperPlugin(),
-    ...(effectivePwa ? caperPwaPlugins(effectivePwa) : []),
+    ...(effectivePwa ? caperPwaPlugins(effectivePwa, { orientation: buildFlags.orientation }) : []),
   ];
 }
 

package/build/internal/buildFlags.mjs

@@ -1,14 +1,15 @@
 /**
- * Boolean build flags read out of `caper.config.ts` before anything can execute
- * it. See the comment on `readCaperBuildFlags` for why this is an AST parse.
+ * Build flags read out of `caper.config.ts` before anything can execute it. See
+ * the comment on `readCaperBuildFlags` for why this is an AST parse.
  */
 import fs from 'node:fs';
 import path from 'node:path';
 import { AST_NODE_TYPES, findConfigObject, parse } from './ast.mjs';
+import { resolveOrientation } from '../../src/utils/orientation.js';
 import { cwd } from './util.mjs';
 
 export function readCaperBuildFlags() {
-  const flags = { useWasm: false };
+  const flags = { useWasm: false, orientation: undefined };
   const configPath = path.resolve(cwd, 'caper.config.ts');
   if (!fs.existsSync(configPath)) return flags;
 
@@ -22,6 +23,14 @@ export function readCaperBuildFlags() {
 
   for (const prop of configObject.properties) {
     if (prop.type !== AST_NODE_TYPES.Property || prop.key?.type !== AST_NODE_TYPES.Identifier) continue;
+    if (prop.key.name === 'orientation') {
+      try {
+        flags.orientation = readOrientationLock(prop.value);
+      } catch {
+        // silent here, like every other build flag; the schema reports it
+      }
+      continue;
+    }
     if (!(prop.key.name in flags)) continue;
     if (prop.value?.type === AST_NODE_TYPES.Literal && typeof prop.value.value === 'boolean') {
       flags[prop.key.name] = prop.value.value;
@@ -30,21 +39,57 @@ export function readCaperBuildFlags() {
   return flags;
 }
 
+/** A property's value node when it is a string literal, else `undefined`. */
+function stringLiteral(node) {
+  return node?.type === AST_NODE_TYPES.Literal && typeof node.value === 'string' ? node.value : undefined;
+}
+
 /**
- * Cross-reference validation over discovered scenes/plugins/popups/entities
- * + the parsed `caper.config.ts` AST + the assetpack manifest. Emits
- * warnings via the project logger; in dev mode also forwards warnings to
- * the browser error overlay as info so they're impossible to miss.
- *
- * Checks:
- *  1. Scene `assets.preload.bundles` / `assets.background.bundles` entries
- *     exist in the assetpack manifest.
- *  2. Plugin IDs in `caper.config.ts` match a discovered plugin
- *     (npm `@caperjs/plugin-*` OR local `src/plugins/*`).
- *  3. `defaultScene` in `caper.config.ts` matches a discovered scene ID.
- *  4. No duplicate scene / plugin / popup / entity IDs across discovery.
+ * The lock out of an `orientation` value node: the string literal itself, or
+ * the `lock` string literal of an object literal (`overlay` is never read: it
+ * may hold a function). Normalized and validated by `resolveOrientation`.
+ */
+function readOrientationLock(node) {
+  if (node?.type === AST_NODE_TYPES.ObjectExpression) {
+    const lockProp = node.properties.find(
+      (p) => p.type === AST_NODE_TYPES.Property && p.key?.type === AST_NODE_TYPES.Identifier && p.key.name === 'lock',
+    );
+    if (!lockProp) throw new Error("orientation needs a lock: { lock: 'portrait' | 'landscape' }");
+    const lock = stringLiteral(lockProp.value);
+    if (lock === undefined) throw new Error("orientation.lock must be written as a string literal, 'portrait' or 'landscape'");
+    return resolveOrientation({ lock }).lock;
+  }
+  const value = stringLiteral(node);
+  if (value === undefined) {
+    throw new Error("orientation must be written as a string literal ('portrait' or 'landscape') or { lock: '...' }");
+  }
+  return resolveOrientation(value).lock;
+}
+
+/**
+ * The orientation lock from `<root>/caper.config.ts`, for the native CLI
+ * commands and `caper doctor`: `orientation: 'portrait'` or
+ * `orientation: { lock: 'portrait', ... }`. Same AST parse as
+ * `readCaperBuildFlags`, so nothing is executed and no DOM stub is needed, but
+ * strict where that one is silent: it throws when the file does not parse,
+ * when no `defineConfig({...})` object literal is found, or when the lock is
+ * not `'portrait'` / `'landscape'` written as a string literal. Callers turn
+ * the throw into a warning.
  *
- * All issues are warnings, not errors — they shouldn't fail the build
- * (typos are a dev-time problem; the runtime will still start, just with
- * broken references the user needs to see).
+ * @param {string} root
+ * @returns {'portrait' | 'landscape' | undefined} undefined when there is no config file or no `orientation` key
  */
+export function readConfigOrientation(root) {
+  const configPath = path.resolve(root, 'caper.config.ts');
+  if (!fs.existsSync(configPath)) return undefined;
+
+  const configObject = findConfigObject(parse(fs.readFileSync(configPath, 'utf-8')));
+  if (configObject?.type !== AST_NODE_TYPES.ObjectExpression) {
+    throw new Error('no defineConfig({ ... }) object literal found');
+  }
+
+  const prop = configObject.properties.find(
+    (p) => p.type === AST_NODE_TYPES.Property && p.key?.type === AST_NODE_TYPES.Identifier && p.key.name === 'orientation',
+  );
+  return prop ? readOrientationLock(prop.value) : undefined;
+}

package/build/internal/schema.mjs

@@ -17,6 +17,55 @@ export const pluginConfigSchema = z.union([
   ]),
 ]);
 
+const ORIENTATION_LOCK_MESSAGE = "orientation must be 'portrait', 'landscape', or { lock: 'portrait' | 'landscape', overlay? }";
+
+const orientationLockSchema = z.enum(['portrait', 'landscape'], { error: ORIENTATION_LOCK_MESSAGE });
+
+const orientationObjectSchema = z.strictObject(
+  {
+    lock: z.enum(['portrait', 'landscape'], {
+      error: (issue) =>
+        issue.input === undefined
+          ? "orientation.lock is required: 'portrait' or 'landscape'"
+          : "orientation.lock must be 'portrait' or 'landscape'",
+    }),
+    overlay: z
+      .union(
+        [
+          z.literal(false),
+          z.strictObject({
+            text: z.string().optional(),
+            background: z.string().optional(),
+            color: z.string().optional(),
+            fontFamily: z.string().optional(),
+            className: z.string().optional(),
+            element: z.function().optional(),
+          }),
+        ],
+        {
+          error:
+            'orientation.overlay must be false or an object of text, background, color, fontFamily, className (strings) and element (a function)',
+        },
+      )
+      .optional(),
+  },
+  { error: (issue) => (issue.code === 'unrecognized_keys' ? `orientation only takes lock and overlay (got ${issue.keys.join(', ')})` : undefined) },
+);
+
+/**
+ * `orientation` is a string shorthand or `{ lock, overlay? }`. Validated by
+ * picking the branch from the value's type rather than with a `z.union`, whose
+ * single "Invalid input" would hide the object branch's precise messages.
+ */
+const orientationSchema = z.any().superRefine((value, ctx) => {
+  const schema = value !== null && typeof value === 'object' ? orientationObjectSchema : orientationLockSchema;
+  const result = schema.safeParse(value);
+  if (result.success) return;
+  for (const issue of result.error.issues) {
+    ctx.addIssue({ code: 'custom', message: issue.message, path: issue.path });
+  }
+});
+
 export const caperConfigSchema = z
   .object({
     id: z.string().min(1).optional(),
@@ -50,6 +99,10 @@ export const caperConfigSchema = z
     useHash: z.boolean().optional(),
     // Build-time only — read by readCaperBuildFlags(), no runtime effect.
     useWasm: z.boolean().optional(),
+    // `'portrait' | 'landscape' | { lock, overlay? }`. Read by the native CLI
+    // (`caper native init|android`), the PWA manifest default, and at runtime by
+    // the `orientation` plugin.
+    orientation: orientationSchema.optional(),
     showStats: z.boolean().optional(),
     showSceneDebugMenu: z.boolean().optional(),
     resizeToContainer: z.boolean().optional(),

package/build/plugins/pwa.mjs

@@ -129,8 +129,12 @@ function defaultWorkbox() {
   };
 }
 
-/** Caper's vite-plugin-pwa defaults. */
-export function defaultPwaOptions() {
+/**
+ * Caper's vite-plugin-pwa defaults.
+ *
+ * @param {{ orientation?: 'portrait' | 'landscape' }} [caperConfig] `orientation` from caper.config.ts, if set
+ */
+export function defaultPwaOptions({ orientation } = {}) {
   const app = readAppIdentity();
 
   return {
@@ -162,7 +166,7 @@ export function defaultPwaOptions() {
       background_color: '#000000',
       display: 'fullscreen',
       display_override: ['fullscreen', 'standalone', 'minimal-ui'],
-      orientation: 'any',
+      orientation: orientation ?? 'any',
       categories: ['games', 'entertainment'],
     },
     workbox: defaultWorkbox(),
@@ -204,10 +208,11 @@ function caperPwaDefaultsPlugin(options, projectSetIcons) {
  * defaults, producing the options vite-plugin-pwa is given.
  *
  * @param {object} pwa Project options, merged over `defaultPwaOptions()`.
+ * @param {{ orientation?: 'portrait' | 'landscape' }} [caperConfig] build flags read out of caper.config.ts
  */
-export function resolvePwaOptions(pwa) {
+export function resolvePwaOptions(pwa, caperConfig = {}) {
   const { autoRegister: _autoRegister, update = 'prompt', ...projectOptions } = pwa;
-  const options = deepMerge(defaultPwaOptions(), projectOptions);
+  const options = deepMerge(defaultPwaOptions(caperConfig), projectOptions);
 
   // `update` is caper's plain-language spelling of registerType. 'prompt' and
   // 'manual' both wait for the user — they differ only in who draws the UI, which
@@ -222,10 +227,11 @@ export function resolvePwaOptions(pwa) {
 
 /**
  * @param {object} pwa Project options, merged over `defaultPwaOptions()`.
+ * @param {{ orientation?: 'portrait' | 'landscape' }} [caperConfig] build flags read out of caper.config.ts
  * @returns {import('vite').PluginOption[]}
  */
-export function caperPwaPlugins(pwa) {
-  const { options, projectSetIcons } = resolvePwaOptions(pwa);
+export function caperPwaPlugins(pwa, caperConfig = {}) {
+  const { options, projectSetIcons } = resolvePwaOptions(pwa, caperConfig);
 
   return [caperPwaDefaultsPlugin(options, projectSetIcons), VitePWA(options)];
 }

package/cli/doctor.mjs

@@ -7,7 +7,17 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { ANDROID_RUST_TARGETS, findMainActivity, missingRustTargets, resolveAndroidEnv, TAURI_PLUGIN_PERMISSIONS } from './native.mjs';
+import {
+  ANDROID_MANIFEST,
+  ANDROID_RUST_TARGETS,
+  ANDROID_SCREEN_ORIENTATION,
+  findMainActivity,
+  missingRustTargets,
+  readManifestOrientation,
+  readOrientation,
+  resolveAndroidEnv,
+  TAURI_PLUGIN_PERMISSIONS,
+} from './native.mjs';
 
 /**
  * `caper doctor` — one-shot health report for a Caper app.
@@ -203,7 +213,14 @@ const resolveEffectiveCompilerOptions = (configFile, ancestors = new Set(), dept
 
 export async function runChecks(
   cwd,
-  { online = true, run = defaultDoctorRun, platform = process.platform, env = process.env, homedir = os.homedir() } = {},
+  {
+    online = true,
+    run = defaultDoctorRun,
+    platform = process.platform,
+    env = process.env,
+    homedir = os.homedir(),
+    loadConfig = undefined,
+  } = {},
 ) {
   const checks = [];
   const installedVersion = readInstalledVersion();
@@ -497,6 +514,40 @@ export async function runChecks(
       } else {
         push(checks, 'native-android-bars', 'warn', 'MainActivity does not hide the system bars', 'caper native android');
       }
+
+      const { orientation, warning: orientationWarning } = await readOrientation(cwd, loadConfig);
+      let manifest = '';
+      try {
+        manifest = fs.readFileSync(path.join(srcTauriDir, ANDROID_MANIFEST), 'utf-8');
+      } catch {
+        // no lock found; compared below
+      }
+      const locked = readManifestOrientation(manifest);
+      const expected = ANDROID_SCREEN_ORIENTATION[orientation];
+      if (orientationWarning) {
+        push(checks, 'native-android-orientation', 'warn', 'could not read caper.config.ts orientation', "write it as orientation: 'portrait' or 'landscape'");
+      } else if (!expected && !locked) {
+        push(checks, 'native-android-orientation', 'ok', 'no orientation lock');
+      } else if (expected === locked) {
+        push(checks, 'native-android-orientation', 'ok', `orientation ${orientation} (AndroidManifest ${locked})`);
+      } else if (!expected) {
+        // `caper native android` leaves the manifest alone when orientation is unset, so it is not the fix here.
+        push(
+          checks,
+          'native-android-orientation',
+          'warn',
+          `AndroidManifest locks orientation to ${locked}, caper.config.ts sets none`,
+          'set orientation in caper.config.ts, or remove android:screenOrientation from AndroidManifest.xml',
+        );
+      } else {
+        push(
+          checks,
+          'native-android-orientation',
+          'warn',
+          `caper.config.ts orientation ${orientation}, AndroidManifest ${locked ? `locks ${locked}` : 'has no lock'}`,
+          'caper native android',
+        );
+      }
     }
   }
 

package/cli/doctor.test.mjs

@@ -712,8 +712,9 @@ describe('runChecks native-android rows', () => {
 
   const allTargets = 'aarch64-linux-android\narmv7-linux-androideabi\ni686-linux-android\nx86_64-linux-android\n';
 
-  function check(cwd, env, responses = { 'rustup target list --installed': allTargets }) {
+  function check(cwd, env, responses = { 'rustup target list --installed': allTargets }, loadConfig = () => ({})) {
     return runChecks(cwd, {
+      loadConfig,
       online: false,
       platform: 'linux',
       env,
@@ -814,4 +815,82 @@ describe('runChecks native-android rows', () => {
     expect(pageSize.hint).toMatch(/caper native android/);
     expect(find(checks, 'native-android-bars').status).toBe('warn');
   });
+
+  describe('native-android-orientation', () => {
+    const MANIFEST = '<manifest>\n  <application>\n    <activity\n      android:name=".MainActivity"\n      android:exported="true">\n    </activity>\n  </application>\n</manifest>\n';
+    const manifestPath = (cwd) => path.join(cwd, 'src-tauri/gen/android/app/src/main/AndroidManifest.xml');
+    const writeManifest = (cwd, value) =>
+      fs.writeFileSync(
+        manifestPath(cwd),
+        value ? MANIFEST.replace('android:name=".MainActivity"', `android:name=".MainActivity"\n      android:screenOrientation="${value}"`) : MANIFEST,
+        'utf-8',
+      );
+
+    async function orientationRow(cwd, loadConfig) {
+      const { bin, ndk, java } = fs.existsSync(path.join(cwd, 'bin')) ? { bin: path.join(cwd, 'bin'), ndk: path.join(cwd, 'ndk'), java: path.join(cwd, 'java') } : scaffoldAndroid(cwd);
+      return find(await check(cwd, { PATH: bin, NDK_HOME: ndk, JAVA_HOME: java }, undefined, loadConfig), 'native-android-orientation');
+    }
+
+    it('is absent when src-tauri/gen/android does not exist', async () => {
+      const cwd = makeTempDir();
+      writeTauriConf(cwd);
+      writeTauriCli(cwd, '2.11.4');
+      const checks = await check(cwd, {}, undefined, () => ({ orientation: 'portrait' }));
+      expect(find(checks, 'native-android-orientation')).toBeUndefined();
+    });
+
+    it('is ok with no orientation lock when neither side sets one', async () => {
+      const cwd = makeTempDir();
+      scaffoldAndroid(cwd);
+      writeManifest(cwd);
+      const row = await orientationRow(cwd, () => ({}));
+      expect(row.status).toBe('ok');
+      expect(row.label).toMatch(/no orientation lock/);
+    });
+
+    it('is ok when the manifest matches caper.config', async () => {
+      const cwd = makeTempDir();
+      scaffoldAndroid(cwd);
+      writeManifest(cwd, 'sensorLandscape');
+      expect((await orientationRow(cwd, () => ({ orientation: 'landscape' }))).status).toBe('ok');
+    });
+
+    it('warns with the caper native android hint on a mismatch', async () => {
+      const cwd = makeTempDir();
+      scaffoldAndroid(cwd);
+      writeManifest(cwd, 'portrait');
+      const row = await orientationRow(cwd, () => ({ orientation: 'landscape' }));
+      expect(row.status).toBe('warn');
+      expect(row.hint).toBe('caper native android');
+    });
+
+    it('warns when caper.config sets an orientation the manifest lacks', async () => {
+      const cwd = makeTempDir();
+      scaffoldAndroid(cwd);
+      writeManifest(cwd);
+      const row = await orientationRow(cwd, () => ({ orientation: 'portrait' }));
+      expect(row.status).toBe('warn');
+      expect(row.hint).toBe('caper native android');
+    });
+
+    it('warns when the manifest has a lock but caper.config sets none', async () => {
+      const cwd = makeTempDir();
+      scaffoldAndroid(cwd);
+      writeManifest(cwd, 'portrait');
+      const row = await orientationRow(cwd, () => ({}));
+      expect(row.status).toBe('warn');
+      expect(row.hint).toMatch(/caper\.config\.ts/);
+    });
+
+    it('warns when caper.config orientation cannot be read', async () => {
+      const cwd = makeTempDir();
+      scaffoldAndroid(cwd);
+      writeManifest(cwd);
+      const row = await orientationRow(cwd, () => {
+        throw new Error('boom');
+      });
+      expect(row.status).toBe('warn');
+      expect(row.label).toMatch(/could not read caper\.config\.ts orientation/);
+    });
+  });
 });

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,
@@ -130,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,
@@ -208,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.');
@@ -268,9 +297,13 @@ 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);
 
   // 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.
@@ -281,7 +314,7 @@ export async function initNative(cwd, opts = {}, { run = defaultRun } = {}) {
     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 };
 }
 
 /**
@@ -541,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 ?? {}) };
@@ -572,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,
@@ -591,6 +658,7 @@ export async function androidNative(
     homedir = os.homedir(),
     exists = fs.existsSync,
     listDir = defaultListDir,
+    loadConfig = defaultLoadConfig,
   } = {},
 ) {
   const pkgPath = path.join(cwd, 'package.json');
@@ -650,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);
@@ -661,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,
@@ -739,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.`);
 }
@@ -783,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}`));