@caperjs/core 0.7.2 → 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/);
+    });
+  });
 });