@multiplatform.one/cli 6.1.0 → 6.3.0

package/templates/universal/AGENTS.md

@@ -0,0 +1,142 @@
+# AGENTS.md — multiplatform.one conventions
+
+Machine-readable house rules for humans and coding agents. Prefer this file over
+reconstructing conventions from meeting notes. Detailed standards live under
+`agent-os/standards/`; the living UX rulebook is linked below.
+
+## Workspace layout
+
+| Path               | Role                                                                |
+| ------------------ | ------------------------------------------------------------------- |
+| `apps/<name>/`     | Private applications (not published)                                |
+| `features/<name>/` | Feature modules for the matching app (screens, stories, playground) |
+| `packages/`        | Private app-integration packages (`@package/*`)                     |
+| `public/`          | Published `@multiplatform.one/*` packages                           |
+
+**App ↔ features twin:** every product app `apps/<name>` MUST have `features/<name>`.
+Platform/tooling shells (frappe, keycloak, storybook\*, vocs, vscode, webext, chain
+shells) are exempt in the convention linter; consumer apps from `mpo init --app`
+are not. Prefer feature code in `features/`, thin wiring in `apps/`.
+
+**Internal deps:** monorepo packages use `workspace:*`. Consumer / app-only
+templates use semver ranges from npm (`@multiplatform.one/*`).
+
+## Package boundaries
+
+| Package                         | Owns                                                 | Must not                               |
+| ------------------------------- | ---------------------------------------------------- | -------------------------------------- |
+| `@multiplatform.one/theme`      | Knobs, presets, intents, recipes, `useResolvedKnobs` | App screens                            |
+| `@multiplatform.one/components` | Catalog UI (layouts, surfaces, feedback, …)          | Frappe/API assumptions                 |
+| `@multiplatform.one/forms`      | Fields, Form, InputParts, field contracts            | Table chrome / Frappe fetch            |
+| `@multiplatform.one/table`      | DataTable, cells, filters, URL table state           | Frappe/API assumptions                 |
+| `@multiplatform.one/frappe-ui`  | Frappe adapters (`FrappeTable`, field registry)      | Re-implementing table/forms primitives |
+| `@multiplatform.one/frappe`     | Frappe client / live query                           | UI                                     |
+
+Dependency direction: `frappe-ui` → `table` / `forms` / `components` / `theme`.
+`table` and `forms` do not depend on `frappe-ui` or `frappe`.
+
+### Import rules (enforced)
+
+1. **No raw `tamagui` outside `public/`** — apps, features, and packages import
+   `@multiplatform.one/components`, `@multiplatform.one/forms`, or
+   `@multiplatform.one/theme` instead.
+2. **Apps never relative-import `public/`** — use package names
+   (`@multiplatform.one/…`), never `../../../public/…`.
+3. **No `.css` files in `apps/*`** (except ignored bench/vendor trees) — styling
+   goes through Tamagui + knobs.
+4. **No hex color literals in `features/**`** — use theme tokens (`$color10`,
+   semantic ramps, knob recipes).
+
+Run: `pnpm lint` (oxlint + `scripts/lint-conventions.mjs`).
+
+## Knobs system (canonical)
+
+Structural styling (radius, space, elevation, typography, animation) is independent
+of Tamagui color themes. Full standard: `agent-os/standards/frontend/knobs-system.md`.
+
+```tsx
+const { knobProps, control, text, elevation } = useResolvedKnobs({
+  intent, // "error" | "accent" | "warning" | "success"
+  component: "Button",
+  compact,
+});
+
+<View
+  {...knobProps.surface}
+  {...knobProps.borderRadius}
+  {...knobProps.panelPadding}
+  {...knobProps.gap}
+  {...knobProps.body}
+  hoverStyle={{ ...control.hoverKnobProps }}
+  pressStyle={{ ...control.pressKnobProps }}
+  focusVisibleStyle={{ ...control.focusVisibleKnobProps }}
+/>;
+```
+
+Rules:
+
+- Always spread complete `knobProps.*` fragments — never cherry-pick resolved tokens.
+- `resolveKnobs()` is the only canonical mapping from abstract knobs → Tamagui props.
+- Consumer `{...props}` come last (explicit eject), not internal defaults that fight recipes.
+- Presets cascade (`<Preset preset="…" theme="…">`); nested `overrides` merge by key.
+- One knob flip restyles the screen (LC-18 KNOB-TOTALITY), or the knob is broken.
+
+## Forms contract
+
+Standard refs: `agent-os/standards/frontend/field-architecture.md`,
+`field-layout.md`, `form-colors.md`, `input-parts.md`.
+
+- Initialize with `useFormField()` + `useResolvedValidators()`.
+- Three-branch render: skeleton → standalone → form-integrated (`<Field>`).
+- Canonical change prop is `onChange(value)` (LC-14). Deprecated aliases may fire
+  but must not be the only path.
+- Field slot order: Label → Hint → Error → Control; error replaces helper in one slot.
+- Use form color ramps from `shared/colorRamps.ts` — no hardcoded color tokens.
+- Fields auto-detect `useIsInTableCell()` and render chromeless inside cells.
+- Capability surfaces (camera, geo, …) MUST preflight before mount (LC-19).
+
+## Table contract
+
+Standard ref: `public/table/README.md` (package boundaries), cell/editor anatomy in
+the living rulebook.
+
+- `@multiplatform.one/table` is framework-agnostic display/filter/sort/paginate.
+- Cell editors larger than the anchor use popover (web) / sheet (native) — never
+  grow the row (LC-06). Editor popups dismiss only on dismissal intent (LC-21).
+- Frappe integration belongs in `@multiplatform.one/frappe-ui` (`FrappeTable`,
+  registry adapters), not in `table`.
+- Child-table / TableInput follow the same field `onChange` contract as forms.
+
+## Living rulebook
+
+**Normative UX + composition rules (LC-\* and recipe taxonomy):**
+
+→ [`docs/theme-propagation-spec.md`](./docs/theme-propagation-spec.md)
+
+That document is the living rulebook: every owner-reported spacing/UX issue is
+adjudicated there in-session as VIOLATION or GAP (new LC-\* rule + VERIFY). Agents
+changing catalog components MUST read it first; a contradicting change updates the
+spec in the same change. Companion docs:
+
+- Catalog guidelines: `docs/design-guidelines.md` + `docs/design-guidelines-blueprint.md`
+- Click-matrix / VERIFY arm: `docs/storybook-knob-edge-cases.md`
+- Agent OS standards index: `agent-os/standards/index.yml`
+
+## Tooling
+
+| Command                 | Purpose                                                        |
+| ----------------------- | -------------------------------------------------------------- |
+| `pnpm lint`             | oxlint (incl. convention rules) + structural convention checks |
+| `pnpm lint:conventions` | Structural checks only (css twin, features twin)               |
+| `pnpm format`           | oxfmt                                                          |
+| `pnpm ci:local`         | format + lint + typecheck + build + test + tree-clean          |
+
+Use **oxlint / oxfmt**, not ESLint / Prettier
+(`agent-os/standards/global/linting-formatting.md`).
+
+## Coding defaults
+
+- Named exports only; cut dead/legacy aliases unless a task explicitly needs them.
+- Cross-platform: shared code first; `.native.tsx` / `.web.tsx` only when required.
+- Stories and tests live next to the component / feature they cover.
+- Deeper style rules: `agent-os/standards/global/coding-style.md`.

package/templates/universal/README.md

@@ -0,0 +1,97 @@
+# **NAME**
+
+Universal multiplatform.one project scaffolded by
+[`@multiplatform.one/cli`](https://www.npmjs.com/package/@multiplatform.one/cli)
+(`mpo init`). One codebase serves **web (SSR)**, **iOS**, and **Android** through
+the [`one`](https://onestack.dev) framework.
+
+This is **not** a fork of the multiplatform.one monorepo. Framework packages come
+from npm at semver ranges (`@multiplatform.one/*`: `__MPO_VERSION__`), never
+`workspace:*`.
+
+## Layout
+
+| Path                 | Role                                                                |
+| -------------------- | ------------------------------------------------------------------- |
+| `apps/__NAME__/`     | Universal app shell: file-based routes, providers, vite/expo config |
+| `features/__NAME__/` | Feature screens / UI — import from here, not from `apps/`           |
+| `packages/config/`   | Shared app config (`@package/config`)                               |
+| `packages/i18n/`     | Translations (`@package/i18n`)                                      |
+| `packages/themes/`   | Tamagui theme config (`@package/themes`)                            |
+
+Convention: every `apps/<name>` has a matching `features/<name>`.
+
+## Commands
+
+```bash
+pnpm install
+
+# web
+pnpm dev        # dev server (web + native bundles) on :3456
+pnpm build      # production web build (one build)
+pnpm serve      # serve the production build
+
+# native (Expo dev client via one)
+pnpm native     # generate ios/ + android/ projects (one prebuild)
+pnpm ios        # build & run on iOS simulator/device (one run:ios)
+pnpm android    # build & run on Android emulator/device (one run:android)
+
+# quality
+pnpm test       # vitest (features)
+pnpm lint       # oxlint
+pnpm typecheck  # tsc across workspace packages
+```
+
+Native flow: `pnpm ios` / `pnpm android` builds a dev client and connects it to
+the dev server started by `pnpm dev`. Run `pnpm dev` in another terminal first.
+
+## Routing
+
+Routes are files in `apps/__NAME__/routes/`:
+
+- `routes/index.tsx` → `/` (`HomeScreen`)
+- `routes/about.tsx` → `/about` (`AboutScreen`)
+- `routes/_layout.tsx` / `_layout.web.tsx` — root layout, providers, i18n
+
+Navigate with `Link` / `useRouter` / `usePathname` from `one` — the same
+pattern the framework's own layouts use.
+
+## Starter screens
+
+- `HomeScreen` — theme/knob-wired welcome card (`useResolvedKnobs`) + navigation
+- `AboutScreen` — router navigation demo
+- `ContactForm` — `@multiplatform.one/forms` fields (`Input`, `TextArea`, `Button`)
+
+## i18n
+
+Translations live in `packages/i18n/<lng>/common.json`. Add a language by adding
+a folder + `common.json` and listing it in `packages/i18n/index.ts`. Use
+`useTranslation()` from `react-i18next` in screens.
+
+## Dependencies
+
+Framework packages come from npm at semver ranges, for example:
+
+```json
+{
+  "@multiplatform.one/components": "__MPO_VERSION__",
+  "@multiplatform.one/forms": "__MPO_VERSION__",
+  "@multiplatform.one/router": "__MPO_VERSION__",
+  "@multiplatform.one/theme": "__MPO_VERSION__"
+}
+```
+
+Upgrade with `pnpm update "@multiplatform.one/*"`.
+
+## Conventions
+
+See [`AGENTS.md`](./AGENTS.md) for package boundaries, the apps ↔ features twin,
+import rules (no raw `tamagui` outside framework packages, no hex literals in
+features), and knobs/forms/table contracts.
+
+## Next steps
+
+1. Replace the starter screens in `features/__NAME__/src/`.
+2. Add routes under `apps/__NAME__/routes/` that re-export feature screens.
+3. Adjust the theme in `packages/themes/index.ts` (`createDefaultThemeConfig`).
+4. Do **not** copy `public/` from the framework monorepo into this project.

package/templates/universal/apps/__NAME__/app.config.js

@@ -0,0 +1,31 @@
+// Expo config consumed by `one prebuild` / `one run:ios` / `one run:android`.
+// Evaluated through @expo/config's CJS pipeline, so CommonJS is required here.
+const { public: publicConfigKeys } = require("../../packages/config/config.json");
+
+const publicConfig = publicConfigKeys.reduce((acc, key) => {
+  if (process.env[key]) acc[key] = process.env[key];
+  return acc;
+}, {});
+
+module.exports = {
+  expo: {
+    name: "__NAME_PASCAL__",
+    slug: "__NAME__",
+    scheme: "__NAME__",
+    version: "1.0.0",
+    orientation: "portrait",
+    userInterfaceStyle: "automatic",
+    platforms: ["ios", "android"],
+    ios: {
+      bundleIdentifier: "com.__NAME_APPID__.app",
+      supportsTablet: true,
+    },
+    android: {
+      package: "com.__NAME_APPID__.app",
+    },
+    extra: {
+      ...publicConfig,
+    },
+    plugins: ["vxrn/expo-plugin"],
+  },
+};

package/templates/universal/apps/__NAME__/config/tamagui.config.ts

@@ -0,0 +1,4 @@
+import { config } from "@package/themes/tamagui.config";
+export type { AppConfig as Conf } from "@package/themes/tamagui.config";
+export { config };
+export default config;

package/templates/universal/apps/__NAME__/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@app/__NAME__",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "one dev --port 3456",
+    "build": "one build",
+    "serve": "one serve",
+    "typecheck": "tsc --noEmit",
+    "prebuild:native": "one prebuild",
+    "prebuild:ios": "one prebuild --platform ios",
+    "prebuild:android": "one prebuild --platform android",
+    "ios": "one run:ios",
+    "android": "one run:android"
+  },
+  "dependencies": {
+    "@features/__NAME__": "workspace:*",
+    "@multiplatform.one/components": "__MPO_VERSION__",
+    "@multiplatform.one/core": "__MPO_VERSION__",
+    "@multiplatform.one/frappe": "__MPO_VERSION__",
+    "@multiplatform.one/frappe-ui": "__MPO_VERSION__",
+    "@multiplatform.one/i18n": "__MPO_VERSION__",
+    "@multiplatform.one/keycloak": "__MPO_VERSION__",
+    "@multiplatform.one/platform": "__MPO_VERSION__",
+    "@multiplatform.one/theme": "__MPO_VERSION__",
+    "@package/config": "workspace:*",
+    "@package/i18n": "workspace:*",
+    "@package/themes": "workspace:*",
+    "@react-navigation/native": "~7.2.2",
+    "@tamagui/core": "2.0.0-rc.41",
+    "@tanstack/react-query": "^5.100.7",
+    "@tanstack/react-query-devtools": "^5.100.7",
+    "@tanstack/react-virtual": "^3.13.24",
+    "expo": "~55.0.26",
+    "i18next": "^25.10.10",
+    "one": "1.16.5",
+    "react": "19.2.5",
+    "react-dom": "19.2.5",
+    "react-i18next": "^16.6.6",
+    "react-native": "0.83.2",
+    "react-native-gesture-handler": "~2.31.1",
+    "react-native-reanimated": "~4.3.0",
+    "react-native-safe-area-context": "~5.7.0",
+    "react-native-screens": "^4.24.0",
+    "react-native-svg": "15.15.4",
+    "react-native-web": "^0.21.2",
+    "react-native-worklets": "~0.7.4",
+    "shiki": "^4.0.2",
+    "tamagui": "2.0.0-rc.41",
+    "text-encoding-utf-8": "^1.0.2"
+  },
+  "devDependencies": {
+    "@multiplatform.one/config": "__MPO_VERSION__",
+    "@react-native-community/cli": "^20.1.3",
+    "@types/react": "~19.2.14",
+    "@vitejs/plugin-react": "^6.0.2",
+    "typescript": "~5.9.3",
+    "vite": "^8.0.10"
+  }
+}

package/templates/universal/apps/__NAME__/polyfills.native.ts

@@ -0,0 +1,23 @@
+// Hermes (React Native) ships without the WHATWG TextEncoder/TextDecoder
+// globals. Install them as the first side-effect of the native root layout,
+// before any provider mounts.
+import { TextDecoder, TextEncoder } from "text-encoding-utf-8";
+
+const globals = globalThis as Record<string, unknown>;
+if (typeof globals.TextEncoder === "undefined") globals.TextEncoder = TextEncoder;
+if (typeof globals.TextDecoder === "undefined") globals.TextDecoder = TextDecoder;
+
+// React Native's built-in URL exposes protocol/pathname/search/hash as
+// GETTER-ONLY. expo-asset's getManifestBaseUrl() assigns to those properties at
+// module init, which throws in strict mode and takes down the native root
+// layout at boot. Install tolerant no-op setters so the assignment silently
+// no-ops. Guarded so a future spec-complete URL polyfill is never overwritten.
+const urlProto = (globals.URL as { prototype?: object } | undefined)?.prototype;
+if (urlProto) {
+  for (const prop of ["protocol", "pathname", "search", "hash"]) {
+    const desc = Object.getOwnPropertyDescriptor(urlProto, prop);
+    if (desc && typeof desc.get === "function" && typeof desc.set !== "function") {
+      Object.defineProperty(urlProto, prop, { ...desc, set() {} });
+    }
+  }
+}

package/templates/universal/apps/__NAME__/polyfills.ts

@@ -0,0 +1,3 @@
+// Web has native TextEncoder/TextDecoder — no polyfill needed. This no-op is the
+// web/default resolution of `./polyfills`; the native variant does the work.
+export {};

package/templates/universal/apps/__NAME__/routes/_layout.tsx

@@ -0,0 +1,22 @@
+import "../polyfills"; // installs TextEncoder/TextDecoder before any provider mounts (Hermes lacks them)
+import { AppLayout } from "@features/__NAME__";
+import { createRootLayout } from "@multiplatform.one/core";
+import { defaultLanguage, defaultNamespace, languages, namespaces } from "@package/i18n";
+import { resources } from "@package/i18n/resources";
+import { importFonts } from "@package/themes/fonts";
+import { AppProvider } from "../src/app";
+
+// Native root layout (web resolves _layout.web.tsx). Translations are imported
+// statically here; web loads them through the vite i18next loader.
+export default createRootLayout({
+  AppProvider,
+  RootLayout: AppLayout,
+  fonts: importFonts(),
+  i18n: {
+    languages,
+    namespaces,
+    defaultLanguage,
+    defaultNamespace,
+    resources,
+  },
+});

package/templates/universal/apps/__NAME__/routes/_layout.web.tsx

@@ -0,0 +1,21 @@
+import "@tamagui/core/reset.css";
+import "../tamagui.css";
+import resources from "virtual:i18next-loader";
+import { AppLayout } from "@features/__NAME__";
+import { createRootLayout } from "@multiplatform.one/core";
+import { defaultLanguage, defaultNamespace, languages, namespaces } from "@package/i18n";
+import { AppProvider } from "../src/app";
+
+// Web root layout (native resolves _layout.tsx). Translations come from the
+// vite i18next loader (packages/i18n) so they hot-reload in dev.
+export default createRootLayout({
+  AppProvider,
+  RootLayout: AppLayout,
+  i18n: {
+    languages,
+    namespaces,
+    defaultLanguage,
+    defaultNamespace,
+    resources,
+  },
+});

package/templates/universal/apps/__NAME__/routes/about.tsx

@@ -0,0 +1,3 @@
+import { AboutScreen } from "@features/__NAME__";
+
+export default AboutScreen;

package/templates/universal/apps/__NAME__/routes/index.tsx

@@ -0,0 +1,3 @@
+import { HomeScreen } from "@features/__NAME__";
+
+export default HomeScreen;

package/templates/universal/apps/__NAME__/src/app.ts

@@ -0,0 +1,10 @@
+import { createApp } from "@multiplatform.one/core";
+import { themeConfig } from "@package/themes";
+
+/**
+ * App-wide provider stack. Add keycloak / frappe / tanstack / web3 here as the
+ * app grows — see CreateAppConfig in @multiplatform.one/core.
+ */
+export const { AppProvider, useAppConfig, withApp } = createApp({
+  theme: themeConfig,
+});

package/templates/universal/apps/__NAME__/tamagui.css

@@ -0,0 +1,3 @@
+/* Generated by @tamagui/vite-plugin (outputCSS). This stub keeps the
+   `import "../tamagui.css"` in routes/_layout.web.tsx resolvable on a fresh
+   scaffold; dev/build regenerate it. */

package/templates/universal/apps/__NAME__/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "types": ["vite/client"]
+  },
+  "include": ["./config/**/*", "./routes/**/*", "./src/**/*", "./*.ts", "./types.d.ts"],
+  "exclude": ["**/node_modules/**", "dist/**", "ios/**", "android/**"]
+}

package/templates/universal/apps/__NAME__/types.d.ts

@@ -0,0 +1,9 @@
+/// <reference types="../../packages/i18n/i18n.d.ts" />
+/// <reference types="@multiplatform.one/platform/rnw-overrides" />
+
+declare module "virtual:*";
+
+// Published core@6.1.0 sources carry a type skew against published
+// frappe-ui@6.1.0 (FrappeProvider auth.token). The app never imports
+// frappe-ui directly; treat it as untyped until fixed packages publish.
+declare module "@multiplatform.one/frappe-ui";

package/templates/universal/apps/__NAME__/vite.config.ts

@@ -0,0 +1,66 @@
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { createViteConfig } from "@multiplatform.one/config/vite";
+import { one } from "one/vite";
+import type { Plugin } from "vite";
+import { public as publicConfigKeys } from "../../packages/config/config.json";
+
+const require = createRequire(import.meta.url);
+
+/**
+ * Some @multiplatform.one packages at 6.1.0 publish web export targets that
+ * don't exist in their tarballs (exports say dist/esm/…/index.js; the build
+ * emitted index.mjs), which breaks resolution for anything importing them —
+ * e.g. forms → router and frappe-ui → frappe. Resolve those bare imports to
+ * the real web builds. Native is unaffected (vxrn's native resolver uses the
+ * packages' valid react-native export condition). Remove this plugin once
+ * fixed packages are published.
+ */
+const BROKEN_PUBLISHED_ENTRIES: Record<string, { pkg: string; entry: string }> = {
+  "@multiplatform.one/router": {
+    pkg: "@multiplatform.one/router",
+    entry: "dist/esm/index.mjs",
+  },
+  "@multiplatform.one/frappe": {
+    pkg: "@multiplatform.one/frappe",
+    entry: "dist/esm/index.mjs",
+  },
+  "@multiplatform.one/frappe/devtools": {
+    pkg: "@multiplatform.one/frappe",
+    entry: "dist/esm/devtools/index.mjs",
+  },
+};
+
+function fixPublishedEsmEntries(): Plugin {
+  return {
+    name: "fix-multiplatform-published-esm-entries",
+    enforce: "pre",
+    resolveId(id) {
+      const broken = BROKEN_PUBLISHED_ENTRIES[id];
+      if (!broken) return null;
+      try {
+        const pkgJson = require.resolve(`${broken.pkg}/package.json`);
+        const entry = pkgJson.replace(/package\.json$/, broken.entry);
+        return existsSync(entry) ? entry : null;
+      } catch {
+        return null;
+      }
+    },
+  };
+}
+
+export default createViteConfig({
+  publicConfigKeys,
+  one: true,
+  tamagui: { config: "./config/tamagui.config.ts", outputCSS: "./tamagui.css" },
+  i18n: { paths: ["../../packages/i18n"] },
+  plugins: [
+    one({
+      router: { root: "routes" },
+      web: { deploy: "node", defaultRenderMode: "ssr" },
+      react: { compiler: true },
+      native: { key: "__NAME_PASCAL__" },
+    }),
+    fixPublishedEsmEntries(),
+  ],
+});

package/templates/universal/features/__NAME__/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@features/__NAME__",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@multiplatform.one/components": "__MPO_VERSION__",
+    "@multiplatform.one/forms": "__MPO_VERSION__",
+    "@multiplatform.one/theme": "__MPO_VERSION__",
+    "@package/config": "workspace:*",
+    "one": "1.16.5",
+    "react": "19.2.5",
+    "react-i18next": "^16.6.6"
+  },
+  "devDependencies": {
+    "@multiplatform.one/config": "__MPO_VERSION__",
+    "@multiplatform.one/test-utils": "__MPO_VERSION__",
+    "@types/react": "~19.2.14",
+    "jsdom": "^26.0.0",
+    "typescript": "~5.9.3",
+    "vitest": "^4.1.5"
+  },
+  "peerDependencies": {
+    "react": "^19.1.0"
+  }
+}

package/templates/universal/features/__NAME__/src/AboutScreen.tsx

@@ -0,0 +1,27 @@
+import { Button, H2, Paragraph, Screen, YStack } from "@multiplatform.one/components";
+import { useRouter } from "one";
+import { useTranslation } from "react-i18next";
+
+/**
+ * About screen (route: /about) — demonstrates programmatic navigation with
+ * the router hooks from `one` (same pattern as the framework's own layouts).
+ */
+export function AboutScreen() {
+  const { t } = useTranslation();
+  const router = useRouter();
+
+  return (
+    <Screen>
+      <YStack gap="$3" alignItems="flex-start">
+        <H2>{t("screens.about.title", "About")}</H2>
+        <Paragraph color="$color11">
+          {t(
+            "screens.about.message",
+            "This screen lives in features/__NAME__ and is wired to the /about route by apps/__NAME__/routes/about.tsx.",
+          )}
+        </Paragraph>
+        <Button onPress={() => router.navigate("/")}>{t("screens.about.back", "Back home")}</Button>
+      </YStack>
+    </Screen>
+  );
+}

package/templates/universal/features/__NAME__/src/AppLayout.tsx

@@ -0,0 +1,50 @@
+import { Button, SizableText, XStack, YStack } from "@multiplatform.one/components";
+import { usePathname, useRouter } from "one";
+import type { PropsWithChildren } from "react";
+import { useTranslation } from "react-i18next";
+
+/**
+ * Root layout: top navigation + content. Wired into the router by
+ * apps/__NAME__/routes/_layout(.web).tsx via createRootLayout. Uses router
+ * hooks (not window.location) so it works on native as well as web.
+ */
+export function AppLayout({ children }: PropsWithChildren) {
+  const { t } = useTranslation();
+  const router = useRouter();
+  const path = usePathname() || "/";
+
+  const items = [
+    { label: t("nav.home", "Home"), href: "/", active: path === "/" },
+    { label: t("nav.about", "About"), href: "/about", active: path.startsWith("/about") },
+  ];
+
+  return (
+    <YStack flex={1} backgroundColor="$background">
+      <XStack
+        alignItems="center"
+        gap="$4"
+        paddingHorizontal="$4"
+        paddingVertical="$3"
+        borderBottomWidth={1}
+        borderBottomColor="$borderColor"
+      >
+        <SizableText fontWeight="700" size="$5">
+          {t("app.name", "__NAME_PASCAL__")}
+        </SizableText>
+        <XStack gap="$2" marginLeft="auto">
+          {items.map((item) => (
+            <Button
+              key={item.href}
+              size="$3"
+              chromeless={!item.active}
+              onPress={() => router.navigate(item.href)}
+            >
+              {item.label}
+            </Button>
+          ))}
+        </XStack>
+      </XStack>
+      {children}
+    </YStack>
+  );
+}