@12-apps/ui 6.54.1 → 6.56.0

package/dist/user-avatar.js

@@ -1,40 +1,40 @@
 import {
   UserAvatar,
   UserMenu
-} from "./chunk-WOP2DRMC.js";
+} from "./chunk-I6ESCBY3.js";
 import "./chunk-UDQSIRAP.js";
-import "./chunk-EMEXXAQI.js";
-import "./chunk-Y6C4MYZE.js";
-import "./chunk-MTEQEPNY.js";
-import "./chunk-6ZZGK5DT.js";
+import "./chunk-G76BNXWE.js";
 import "./chunk-3ZVUNSFF.js";
+import "./chunk-GYDUXL3D.js";
+import "./chunk-6ZZGK5DT.js";
+import "./chunk-MTEQEPNY.js";
 import "./chunk-VUHLNYAE.js";
 import "./chunk-2GSIEDGN.js";
-import "./chunk-WN5PNP6F.js";
+import "./chunk-J2QIICWP.js";
+import "./chunk-W2TCSYLI.js";
 import "./chunk-FKUYRQSP.js";
-import "./chunk-76X6JRVI.js";
-import "./chunk-JH7EEJEQ.js";
+import "./chunk-HDBP55R3.js";
 import "./chunk-BA4RHQ3B.js";
-import "./chunk-RIZRF5XR.js";
-import "./chunk-LTE2QHBH.js";
-import "./chunk-LN46DSMF.js";
+import "./chunk-JE6FNSQV.js";
+import "./chunk-T2UP4XJF.js";
+import "./chunk-G2FUZALJ.js";
 import "./chunk-TAMIZE4Q.js";
-import "./chunk-MKLIMY3D.js";
-import "./chunk-PAT2BQOQ.js";
+import "./chunk-AJBRO76D.js";
+import "./chunk-36VXZCJT.js";
 import "./chunk-TYJR4GOF.js";
-import "./chunk-2TZ6X265.js";
-import "./chunk-7FDU3FIN.js";
-import "./chunk-EPEJMTCQ.js";
+import "./chunk-RGVNXES5.js";
 import "./chunk-GDN2LUTZ.js";
-import "./chunk-YFODI4KT.js";
+import "./chunk-7ZADLRLP.js";
+import "./chunk-3NGE6NE6.js";
+import "./chunk-2FBGDSGC.js";
 import "./chunk-VBP46YP4.js";
-import "./chunk-2BYKTBDL.js";
+import "./chunk-44BD7SFH.js";
 import "./chunk-AG66JBNH.js";
 import "./chunk-FZXKH2ZT.js";
 import "./chunk-26X4CZVR.js";
 import "./chunk-O6MJWHU5.js";
-import "./chunk-FQ6UW7IY.js";
-import "./chunk-6JAIFIPW.js";
+import "./chunk-SSX5ITPM.js";
+import "./chunk-F5H2ZXST.js";
 import "./chunk-N3GAFIXG.js";
 import "./chunk-YKCAJ2TN.js";
 import "./chunk-PZ5AY32C.js";

package/dist/utility/AnimatedIcon.js

@@ -1,12 +1,12 @@
 import "../chunk-H2PTB6FD.js";
 import {
   AnimatedIcon
-} from "../chunk-75CGLX6Q.js";
-import "../chunk-XEWMY4ZM.js";
+} from "../chunk-6K2A4PY5.js";
+import "../chunk-FJKHDKCV.js";
 import "../chunk-KM3Y5TCG.js";
 import "../chunk-HPK33ACY.js";
-import "../chunk-FQ6UW7IY.js";
-import "../chunk-6JAIFIPW.js";
+import "../chunk-SSX5ITPM.js";
+import "../chunk-F5H2ZXST.js";
 import "../chunk-N3GAFIXG.js";
 import "../chunk-YKCAJ2TN.js";
 import "../chunk-PZ5AY32C.js";

package/dist/utility/InstallPrompt.js

@@ -1,7 +1,8 @@
 import "../chunk-3QQVEYOR.js";
 import {
   InstallPrompt
-} from "../chunk-JE6RZ5L6.js";
+} from "../chunk-5ZOJLYD2.js";
+import "../chunk-GY62N32G.js";
 import {
   usePwaInstall
 } from "../chunk-5GMHJ7Y5.js";
@@ -13,7 +14,6 @@ import {
   readPwaInstallStash,
   resetPwaInstallStash
 } from "../chunk-UUL44SUX.js";
-import "../chunk-GY62N32G.js";
 import "../chunk-PZ5AY32C.js";
 export {
   InstallPrompt,

package/dist/utility/WorkflowStep.js

@@ -1,30 +1,31 @@
 import "../chunk-IO36MEBD.js";
 import {
   WorkflowStep
-} from "../chunk-LOLR2BWW.js";
-import "../chunk-LV4WSWQZ.js";
-import "../chunk-KNWG77FB.js";
-import "../chunk-TM5QQJTF.js";
-import "../chunk-3IPPMWUA.js";
-import "../chunk-DH6J64PS.js";
+} from "../chunk-KRT4WGV5.js";
+import "../chunk-NM65DY2A.js";
+import "../chunk-7PK5IENM.js";
+import "../chunk-ZJGDD54X.js";
+import "../chunk-B7ZHEOQQ.js";
+import "../chunk-BRHRK7BK.js";
 import "../chunk-25MSGLNU.js";
 import "../chunk-GAXHYRX6.js";
 import "../chunk-NP6SHLQ3.js";
+import "../chunk-TZ23DNKY.js";
 import "../chunk-7ZPUN7TV.js";
 import "../chunk-PT6TCWIW.js";
-import "../chunk-2TZ6X265.js";
-import "../chunk-7FDU3FIN.js";
-import "../chunk-EPEJMTCQ.js";
+import "../chunk-RGVNXES5.js";
 import "../chunk-GDN2LUTZ.js";
-import "../chunk-YFODI4KT.js";
+import "../chunk-7ZADLRLP.js";
+import "../chunk-3NGE6NE6.js";
+import "../chunk-2FBGDSGC.js";
 import "../chunk-VBP46YP4.js";
-import "../chunk-2BYKTBDL.js";
+import "../chunk-44BD7SFH.js";
 import "../chunk-AG66JBNH.js";
 import "../chunk-FZXKH2ZT.js";
 import "../chunk-26X4CZVR.js";
 import "../chunk-O6MJWHU5.js";
-import "../chunk-FQ6UW7IY.js";
-import "../chunk-6JAIFIPW.js";
+import "../chunk-SSX5ITPM.js";
+import "../chunk-F5H2ZXST.js";
 import "../chunk-N3GAFIXG.js";
 import "../chunk-YKCAJ2TN.js";
 import "../chunk-PZ5AY32C.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/ui",
-  "version": "6.54.1",
+  "version": "6.56.0",
   "license": "MIT",
   "packageManager": "pnpm@10.34.5",
   "type": "module",
@@ -707,6 +707,14 @@
     "./locales": {
       "types": "./dist/types/locales.d.ts",
       "default": "./dist/locales.js"
+    },
+    "./layout/Screen": {
+      "react-native": {
+        "types": "./dist/types-native/components/layout/Screen/index.native.d.ts",
+        "default": "./dist/native/layout/Screen.js"
+      },
+      "types": "./dist/types/components/layout/Screen/index.d.ts",
+      "default": "./dist/layout/Screen.js"
     }
   },
   "typesVersions": {
@@ -779,7 +787,8 @@
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
     "react-native": ">=0.79.0",
-    "react-native-svg": ">=15.0.0"
+    "react-native-svg": ">=15.0.0",
+    "react-native-safe-area-context": ">=5.0.0"
   },
   "dependencies": {
     "@12-apps/forms-core": "^1.21.0",
@@ -834,7 +843,8 @@
     "typescript": "^5.8.2",
     "vite": "^6.4.1",
     "vite-plugin-istanbul": "^7.2.1",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "react-native-safe-area-context": "5.7.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -868,6 +878,9 @@
     },
     "react-native-svg": {
       "optional": true
+    },
+    "react-native-safe-area-context": {
+      "optional": true
     }
   }
 }

package/src/components/layout/Screen/NATIVE-NOTES.md

@@ -0,0 +1,2 @@
+- Keyboard geometry uses React Native KeyboardAvoidingView; react-native-web unit/story lanes verify its wiring, not a real Android/iOS keyboard. Device keyboard/rotation QA remains explicit.
+- Web safe-area values come from CSS environment variables; native values come from the existing navigator or an internal safe-area provider. Browser keyboard resizing remains browser-managed.

package/src/components/layout/Screen/Screen.base.ts

@@ -0,0 +1,20 @@
+import type { BoxBaseProps } from '../Box/Box.base';
+
+/** Physical screen edges, independent of a native dependency. */
+export type ScreenEdge = 'top' | 'right' | 'bottom' | 'left';
+export const SCREEN_EDGES: readonly ScreenEdge[] = ['top', 'right', 'bottom', 'left'];
+
+/** Padding and gap apply to the content, inside the selected safe-area edges. */
+export interface ScreenBaseProps extends Pick<
+  BoxBaseProps,
+  'children' | 'p' | 'px' | 'py' | 'pt' | 'pr' | 'pb' | 'pl' | 'gap' | 'bg' | 'testID' | 'dataTestId'
+> {
+  /** Vertical scrolling; turn off when a child owns scrolling. Default true. */
+  scroll?: boolean;
+  /** Omit bottom when a navigator's tab bar already owns that inset. */
+  safeAreaEdges?: readonly ScreenEdge[];
+  /** Lift the native viewport above the soft keyboard. Default true. */
+  keyboardAvoiding?: boolean;
+  /** Native distance from the window top to the screen's parent, in dp. */
+  keyboardVerticalOffset?: number;
+}

package/src/components/layout/Screen/Screen.md

@@ -0,0 +1,71 @@
+# Screen
+
+`@12-apps/ui/layout/Screen` is a bounded page viewport on web, Android and iOS.
+It combines safe-area edges, vertical scrolling and native keyboard avoidance.
+It renders existing Box/Stack/form components without consumer imports from a
+visual platform library. It is for ordinary screens, not virtualized lists.
+
+```tsx
+import { Screen } from '@12-apps/ui/layout/Screen';
+import { Text } from '@12-apps/ui/typography/Text';
+
+<Screen p={2} gap={2} safeAreaEdges={['top', 'left', 'right']}>
+  <Text>Content above a navigator-owned bottom tab bar</Text>
+</Screen>
+```
+
+## Props
+
+- `children`: screen content
+- `scroll` (true): a vertical scrolling viewport; use false if a child owns scrolling
+- `safeAreaEdges` (all four): physical edges; use an empty array when an ancestor
+  already owns every inset. Exclude bottom when a tab bar owns that edge
+- `p`, `px`, `py`, `pt`, `pr`, `pb`, `pl`, `gap`: content spacing in theme units,
+  inside the safe area; side overrides axis, axis overrides shorthand
+- `bg` (`default`): the same surface/palette role as Box
+- `keyboardAvoiding` (true): native keyboard lift; disable if a parent owns it
+- `keyboardVerticalOffset` (0): native distance from the window top to the
+  screen's parent, in dp; set for a non-overlay navigation header
+- `testID` / `dataTestId`: outer screen id; scroll viewport also has `<id>-viewport`
+- Native: View accessibility props, `style`, `contentContainerStyle`,
+  `scrollViewProps` for scroll callbacks and indicators
+- Web: div accessibility props, `sx`, `contentSx`, `style`
+- Ref: native outer View / web outer div
+
+## Native setup
+
+Install the optional peer `react-native-safe-area-context` (5+) using the version
+supported by your Expo/RN app. A web-only consumer does not need this peer. Screen
+reuses the navigator's safe-area context. Without one it creates a provider
+outside the scroll viewport. Do not wrap Screen in another safe-area view;
+select the edges the screen actually owns instead.
+
+The safe-area view wraps React Native's KeyboardAvoidingView, which uses padding
+on iOS and height on Android. Its measured viewport already excludes the bottom
+safe area, so the home-indicator inset is not added again above the keyboard.
+ScrollView automatic keyboard and content insets are off so those owners do not
+also apply the same lift/insets. Handled child taps remain usable with the
+keyboard open; dragging dismisses it. `scrollViewProps` can change tap/dismiss
+policy, but cannot override the viewport geometry or automatic inset ownership.
+
+## Layout and accessibility
+
+The parent must give Screen a bounded height (a navigator does this). On the web,
+the ancestor chain must carry a definite height/flex size; Screen grows within it.
+Content has a minimum viewport height, so short screens fill the available area
+and long screens scroll. No app-specific padding, colors, header or footer are
+invented. Use a meaningful accessibility label where the screen needs one;
+children retain their own focus and accessibility semantics.
+
+The web uses CSS `env(safe-area-inset-*)`; set viewport-fit=cover when deploying
+edge-to-edge. Browser keyboard/visual-viewport behavior belongs to the browser;
+the native keyboard props are accepted but not forwarded to the DOM.
+
+## Verification boundary
+
+Shared Storybook tests prove bounded scrolling and text entry on both browser
+renderers. Native unit tests exercise safe-area/keyboard/scroll ownership and
+rerenders, but react-native-web does not simulate a device keyboard. Device QA
+must cover both OSes, a notched screen, bottom tabs, keyboard show/hide/resize,
+last-field reachability, rotation and Android back dismissal before claiming
+that those device behaviors have been observed.

package/src/components/layout/Screen/Screen.native.tsx

@@ -0,0 +1,56 @@
+import * as React from 'react';
+import { KeyboardAvoidingView, Platform, ScrollView, StyleSheet, View } from 'react-native';
+import { SafeAreaInsetsContext, SafeAreaProvider, SafeAreaView } from 'react-native-safe-area-context';
+
+import { SCREEN_EDGES } from './Screen.base';
+import type { ScreenProps } from './Screen.types.native';
+import { resolveBoxLayout, splitBoxProps } from '../Box/box-layout';
+import { resolveTestId } from '../../../platform/test-id';
+import { useUiTheme } from '../../../provider/use-ui-theme.native';
+
+const styles = StyleSheet.create({ fill: { flex: 1 }, content: { flexGrow: 1 } });
+
+function keyboardBehavior(enabled: boolean): 'padding' | 'height' | undefined {
+  if (!enabled) return undefined;
+  return Platform.OS === 'ios' ? 'padding' : 'height';
+}
+
+/** Reuse a navigator's context, or own one outside the scrolling view. */
+function ScreenBoundary({ children }: { children: React.ReactNode }): React.JSX.Element {
+  const insets = React.useContext(SafeAreaInsetsContext);
+  return insets === null
+    ? <SafeAreaProvider style={styles.fill}>{children}</SafeAreaProvider>
+    : <>{children}</>;
+}
+
+export const Screen = React.forwardRef<View, ScreenProps>(({
+  children, scroll = true, safeAreaEdges = SCREEN_EDGES,
+  keyboardAvoiding = true, keyboardVerticalOffset = 0, bg = 'default',
+  style, contentContainerStyle, scrollViewProps, ...props
+}, ref) => {
+  const theme = useUiTheme();
+  const { layout, rest } = splitBoxProps(props);
+  const testID = resolveTestId(layout);
+  const contentStyle = [styles.content, resolveBoxLayout({ ...layout, direction: 'column' }, theme), contentContainerStyle];
+  return (
+    <ScreenBoundary>
+      <View ref={ref} testID={testID} {...rest} style={[styles.fill, resolveBoxLayout({ bg }, theme), style]}>
+        <SafeAreaView edges={safeAreaEdges} style={styles.fill}>
+          <KeyboardAvoidingView style={styles.fill} enabled={keyboardAvoiding}
+            behavior={keyboardBehavior(keyboardAvoiding)} keyboardVerticalOffset={keyboardVerticalOffset}>
+            {scroll ? (
+              <ScrollView keyboardShouldPersistTaps="handled" keyboardDismissMode="on-drag" {...scrollViewProps}
+                testID={scrollViewProps?.testID ?? (testID ? `${testID}-viewport` : undefined)}
+                style={styles.fill} contentContainerStyle={contentStyle}
+                horizontal={false} automaticallyAdjustKeyboardInsets={false}
+                automaticallyAdjustContentInsets={false} contentInsetAdjustmentBehavior="never">
+                {children}
+              </ScrollView>
+            ) : <View style={[styles.fill, contentStyle]}>{children}</View>}
+          </KeyboardAvoidingView>
+        </SafeAreaView>
+      </View>
+    </ScreenBoundary>
+  );
+});
+Screen.displayName = 'Screen';

package/src/components/layout/Screen/Screen.tsx

@@ -0,0 +1,41 @@
+import MuiBox from '@mui/material/Box/index.js';
+import * as React from 'react';
+
+import { SCREEN_EDGES } from './Screen.base';
+import type { ScreenProps } from './Screen.types';
+import { Box } from '../Box/Box';
+import { splitBoxProps } from '../Box/box-layout';
+import { resolveTestId, withoutTestIdProps } from '../../../platform/test-id';
+
+function sxEntries(sx: ScreenProps['sx']) {
+  if (sx === undefined) return [];
+  return Array.isArray(sx) ? sx : [sx];
+}
+
+/** A bounded page viewport; browser keyboards remain the browser's responsibility. */
+export const Screen = React.forwardRef<HTMLDivElement, ScreenProps>(({
+  children, scroll = true, safeAreaEdges = SCREEN_EDGES,
+  keyboardAvoiding: _keyboardAvoiding = true, keyboardVerticalOffset: _keyboardVerticalOffset = 0,
+  bg = 'default', sx, contentSx, ...props
+}, ref) => {
+  const { layout, rest } = splitBoxProps(props);
+  const testID = resolveTestId(layout);
+  const safeArea = Object.fromEntries(SCREEN_EDGES.map((edge) => [
+    `padding${edge[0]!.toUpperCase()}${edge.slice(1)}`,
+    safeAreaEdges.includes(edge) ? `env(safe-area-inset-${edge}, 0px)` : 0,
+  ]));
+  return (
+    <Box ref={ref} bg={bg} dataTestId={testID} {...rest}
+      sx={[{ display: 'flex', flexDirection: 'column', flex: 1, minHeight: 0, minWidth: 0, overflow: 'hidden', ...safeArea },
+        ...sxEntries(sx)]}>
+      <MuiBox data-testid={testID ? `${testID}-viewport` : undefined}
+        sx={{ display: 'flex', flexDirection: 'column', flex: 1, minHeight: 0, overflowY: scroll ? 'auto' : 'hidden' }}>
+        <Box {...withoutTestIdProps(layout)} direction="column"
+          sx={[scroll ? { flexGrow: 1, flexShrink: 0 } : { flex: 1, minHeight: 0, minWidth: 0 }, ...sxEntries(contentSx)]}>
+          {children}
+        </Box>
+      </MuiBox>
+    </Box>
+  );
+});
+Screen.displayName = 'Screen';

package/src/components/layout/Screen/Screen.types.native.ts

@@ -0,0 +1,13 @@
+import type { ScrollViewProps, StyleProp, ViewProps, ViewStyle } from 'react-native';
+
+import type { ScreenBaseProps } from './Screen.base';
+
+export type { ScreenBaseProps, ScreenEdge } from './Screen.base';
+export type ScreenProps = ScreenBaseProps & Omit<ViewProps, keyof ScreenBaseProps> & {
+  contentContainerStyle?: StyleProp<ViewStyle>;
+  /** Scroll events/indicators; Screen owns orientation, size and keyboard insets. */
+  scrollViewProps?: Omit<ScrollViewProps,
+    'children' | 'style' | 'contentContainerStyle' | 'horizontal' | 'scrollEnabled' |
+    'automaticallyAdjustKeyboardInsets' | 'automaticallyAdjustContentInsets' | 'contentInsetAdjustmentBehavior'
+  >;
+};

package/src/components/layout/Screen/Screen.types.ts

@@ -0,0 +1,10 @@
+import type { SxProps, Theme } from '@mui/material/styles/index.js';
+import type * as React from 'react';
+
+import type { ScreenBaseProps } from './Screen.base';
+
+export type { ScreenBaseProps, ScreenEdge } from './Screen.base';
+export type ScreenProps = ScreenBaseProps & Omit<React.HTMLAttributes<HTMLDivElement>, keyof ScreenBaseProps> & {
+  sx?: SxProps<Theme>;
+  contentSx?: SxProps<Theme>;
+};

package/src/components/layout/Screen/index.native.ts

@@ -0,0 +1,2 @@
+export { Screen } from './Screen.native';
+export type { ScreenProps, ScreenBaseProps, ScreenEdge } from './Screen.types.native';

package/src/components/layout/Screen/index.ts

@@ -0,0 +1,2 @@
+export { Screen } from './Screen';
+export type { ScreenProps, ScreenBaseProps, ScreenEdge } from './Screen.types';

package/src/components/layout/Screen/tests.md

@@ -0,0 +1,64 @@
+# Screen test status
+
+## Passed locally
+
+- Package build: all 147 web exports and 28 native exports, declarations and export checks (35.4 s)
+- Package check-types: web, native source and native test programs
+- Package lint: zero lint errors; existing ESLintEnvWarning notices in Dialog/Toast stories
+- Native parity and icon generation: 28/147 subpaths, 625 shared stories, 46 glyphs
+- Web unit suite: 188 files, 2,388 tests, zero skipped (121.3 s)
+- Native unit suite: 29 files, 369 tests, zero skipped (16.3 s)
+- Focused Screen/icon tests: 12 web and 15 native cases
+- Full-source consumer candidate: 84 cases across 10 native suites, zero skipped,
+  including theme propagation under Android and iOS configurations; typecheck passed
+
+## Coverage
+
+Shared stories: Default, LongContent, TabBarOwnsBottom, ChildOwnsScroll, Empty,
+KeyboardForm. Shared play tests: BoundedOverflow, InputRemainsInteractive,
+EmptyScreen, ChildViewportStaysBounded.
+
+Positive: theme spacing/color, root accessibility/ref, selected safe-area edges,
+keyboard offsets, native scroll callbacks, existing-provider reuse and unseeded
+provider fallback. Negative/repeated: disable scrolling/keyboard lift, zero
+edges, repeated policy changes, avoid duplicate automatic insets, and prevent
+native props leaking to the DOM. Browser geometry, final hosted CI are tracked on PR #736. Final-source unit/type checks and
+`pnpm quality` passed at 0fee5e6; the keyboard-disable negative control failed
+exactly 2 of 7 tests, and the unchanged positive source passed all 369 native tests.
+
+Device keyboard/rotation/notch QA has not run; no device was available. Neither
+react-native-web nor mocked platform tests constitute an observed device keyboard.
+
+## Failures and recovery
+
+- The default package-store path was not writable; explicit workspace paths fixed it
+- Temporary storage filled during initial setup. Only task-generated caches were removed
+- Two pinned-pnpm dependency resolution/download attempts ended with exit 137.
+  The environment's available pnpm 11.19.0 bootstrapped the unchanged frozen
+  lockfile in 31.3 s; verification commands use repository-pinned pnpm 10.34.5
+- First native focused run used an unsupported Vitest spy helper; using Vitest's
+  getter spy fixed both failing platform cases
+- Adding Screen required the intentional public-export count assertion to move
+  from 146 to 147; the full web suite then passed
+- Aggregate complexity flagged the initial render functions; extracting small
+  style/keyboard helpers preserves behavior and brings them under the limit
+- A first experimental consumer tarball overlaid only Screen/icons on an older
+  published build. This duplicated UiThemeContext and failed dark-theme propagation.
+  It was rejected. Rebuilding every entry together fixed the candidate and passed
+  the consumer's regression. Release artifacts must always use the full build
+
+## Hosted verification (2026-09-30 17:30 BRT)
+
+Run https://github.com/12-apps/shared-packages/actions/runs/36772172767 passed
+Build, Lint, Type Check, Unit Tests, Static Gates (including knip), web Storybook,
+Consumer Verification and Native Harness. Every dispatched job used ubuntu-latest
+in the GitHub Actions runner group. The native Storybook lane caught four new
+play tests querying before the unseeded safe-area provider's initial effect.
+The tests now await the actual elements with findByTestId; no assertion is removed
+and runtime code is unchanged. The other 630 native story cases passed (two
+pre-existing web-only cases were skipped). Final retry and release status live at
+https://github.com/12-apps/shared-packages/pull/736.
+
+Local native Storybook build passed; browser execution was blocked by the
+execution environment's Chromium Unix-socket restriction, including the supported
+escalation attempt. Hosted browser evidence is authoritative for this lane.

package/src/components/layout/Screen/track.md

@@ -0,0 +1,26 @@
+# Screen
+
+A cross-platform bounded screen with safe-area edges, scrolling and keyboard lift.
+See Screen.md for every prop and tests.md for the evidence and failures.
+
+## Lint / Type Errors
+Package lint and all three check-types programs pass. The guidelines mention
+`check:component`, but that command/script is absent; current package scripts apply.
+
+## Testing Scenarios
+Shared play tests cover real overflow, child-owned scrolling, form interaction
+and empty content. Unit tests cover inset ownership and repeated native policy
+changes. Device keyboard/notch/rotation QA is not claimed.
+
+## Current
+2026-09-30 17:30 BRT: Source review addressed safe-area/keyboard nesting,
+child-owned viewport sizing, Android avoidance disabling and stale initial inset
+metrics on remount. The optional native peer does not affect web-only consumers.
+Screen and three generated tab glyphs are additive; existing component contracts
+are unchanged. Refreshed onto main dd971d29 after the concurrent color-role merge.
+
+Full build, final-source package suites/types, lint, parity and aggregate quality
+passed locally. Source/packaging review approved 0fee5e6. Hosted web/native harness
+checks passed; native play tests now await safe-area initialization. Final hosted
+retry and release status are recorded on PR #736. Normal
+reviewed CI/CD publishes after merge; no manual package version or publish.

package/src/icons/glyphs.json

@@ -22,6 +22,9 @@
   "ExpandLess",
   "ExpandMore",
   "FilterList",
+  "FitnessCenter",
+  "History",
+  "Home",
   "IndeterminateCheckBox",
   "Info",
   "InfoOutlined",

package/src/icons/paths.generated.ts

@@ -30,6 +30,9 @@ export const ICON_PATHS = {
   ExpandLess: ["m12 8-6 6 1.41 1.41L12 10.83l4.59 4.58L18 14z"],
   ExpandMore: ["M16.59 8.59 12 13.17 7.41 8.59 6 10l6 6 6-6z"],
   FilterList: ["M10 18h4v-2h-4zM3 6v2h18V6zm3 7h12v-2H6z"],
+  FitnessCenter: ["M20.57 14.86 22 13.43 20.57 12 17 15.57 8.43 7 12 3.43 10.57 2 9.14 3.43 7.71 2 5.57 4.14 4.14 2.71 2.71 4.14l1.43 1.43L2 7.71l1.43 1.43L2 10.57 3.43 12 7 8.43 15.57 17 12 20.57 13.43 22l1.43-1.43L16.29 22l2.14-2.14 1.43 1.43 1.43-1.43-1.43-1.43L22 16.29z"],
+  History: ["M13 3c-4.97 0-9 4.03-9 9H1l3.89 3.89.07.14L9 12H6c0-3.87 3.13-7 7-7s7 3.13 7 7-3.13 7-7 7c-1.93 0-3.68-.79-4.94-2.06l-1.42 1.42C8.27 19.99 10.51 21 13 21c4.97 0 9-4.03 9-9s-4.03-9-9-9m-1 5v5l4.28 2.54.72-1.21-3.5-2.08V8z"],
+  Home: ["M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z"],
   IndeterminateCheckBox: ["M19 3H5c-1.1 0-2 .9-2 2v14c0 1.1.9 2 2 2h14c1.1 0 2-.9 2-2V5c0-1.1-.9-2-2-2m-2 10H7v-2h10z"],
   Info: ["M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2m1 15h-2v-6h2zm0-8h-2V7h2z"],
   InfoOutlined: ["M11 7h2v2h-2zm0 4h2v6h-2zm1-9C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2m0 18c-4.41 0-8-3.59-8-8s3.59-8 8-8 8 3.59 8 8-3.59 8-8 8"],

package/src/tokens/color.ts

@@ -157,6 +157,27 @@ export function lighten(color: string, coefficient: number): string {
   return recomposeColor({ type: decomposed.type, values });
 }
 
+/**
+ * `overlay` laid over `background` at `opacity` (0 to 1), flattened to one
+ * OPAQUE `rgb()` — the colour a translucent wash actually shows, as a colour
+ * that stays that colour whatever it is later painted on.
+ *
+ * MUI's `blend` at its default gamma, rounding each channel as it does. One
+ * deliberate difference: an `hsl()` input is converted to rgb first, where
+ * MUI's reads hue, saturation and lightness as if they were red, green and
+ * blue. Any alpha on either input is ignored, as in MUI.
+ */
+export function blend(background: string, overlay: string, opacity: number): string {
+  const rgbOf = (color: string): number[] =>
+    decomposeColor(color.startsWith('hsl') ? hslToRgb(color) : color).values;
+  const base = rgbOf(background);
+  const top = rgbOf(overlay);
+  const amount = clamp(opacity);
+  const channel = (index: number): number =>
+    Math.round((base[index] ?? 0) * (1 - amount) + (top[index] ?? 0) * amount);
+  return recomposeColor({ type: 'rgb', values: [channel(0), channel(1), channel(2)] });
+}
+
 /** Darken a light colour or lighten a dark one, by `coefficient`. */
 export function emphasize(color: string, coefficient = 0.15): string {
   return getLuminance(color) > 0.5 ? darken(color, coefficient) : lighten(color, coefficient);

package/src/tokens/ink.ts

@@ -29,7 +29,10 @@ import {
  * - the NEUTRAL tones, over the grey ramp, named by what they do rather than by
  *   their step, so a host that re-greys the ramp re-greys every one;
  * - `uiInk(theme)`, the colours with no palette role at all (`./ink.core.ts`),
- *   which a host can replace through `theme.uiInk`.
+ *   which a host can replace through `theme.uiInk`;
+ * - `surfaces(theme)` and `softSignal(theme, signal)` (`./surfaces.ts`), the
+ *   grounds a board and its cards sit on and a signal's soft background,
+ *   which a host can replace through `theme.uiSurfaces` / `theme.uiSoftSignal`.
  *
  * Every default is the value the component drew before, so moving a component
  * onto these changed nothing on screen. `scripts/ui-tokens-gate.mjs` refuses a

package/src/tokens/scales.ts

@@ -19,6 +19,8 @@ export { rem, rems, remPx, resetRootFontCache, sxRem } from './relative';
 // Every colour by role (FUT-2593): ink roles, neutral tones, the named sets.
 export * from './ink';
 export * from './ink.core';
+// The surface and soft-signal roles (FUT-3098): `surfaces`, `softSignal`.
+export * from './surfaces';
 export { DEFAULT_FIELD_RADIUS, fieldRadius, fieldRadiusOverrides, fieldRadiusPx, fieldRootStyles } from './field-radius';
 export {
   asFieldSize,