@moldable-ai/ui 0.2.26 → 0.2.31

package/dist/lib/theme.js

@@ -2,6 +2,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useCallback, useContext, useEffect, useState, } from 'react';
 import { TooltipProvider } from '../components/ui/tooltip.js';
+import { resolvePlatformPack } from '../tokens/contracts.js';
 const ThemeContext = createContext(null);
 const STORAGE_KEY = 'moldable-theme';
 function getSystemTheme() {
@@ -22,14 +23,16 @@ function getUrlTheme() {
     }
     return null;
 }
-function getStoredTheme() {
+function getStoredTheme(storageKey = STORAGE_KEY) {
     if (typeof window === 'undefined')
         return 'system';
     // URL parameter takes precedence (for iframe embedding)
     const urlTheme = getUrlTheme();
     if (urlTheme)
         return urlTheme;
-    const stored = localStorage.getItem(STORAGE_KEY);
+    if (!storageKey)
+        return 'system';
+    const stored = localStorage.getItem(storageKey);
     if (stored === 'light' || stored === 'dark' || stored === 'system') {
         return stored;
     }
@@ -41,36 +44,109 @@ function resolveTheme(theme) {
     }
     return theme;
 }
-export function ThemeProvider({ children }) {
-    const [theme, setThemeState] = useState(() => getStoredTheme());
-    const [resolvedTheme, setResolvedTheme] = useState(() => resolveTheme(theme));
-    const setTheme = useCallback((newTheme) => {
-        setThemeState(newTheme);
-        localStorage.setItem(STORAGE_KEY, newTheme);
+export function ThemeProvider({ children, platform = 'macos', platformVersion = '27', uiTheme: uiThemeProp = 'moldable', sidebarStyle: sidebarStyleProp, appearance: appearanceProp, controlSize: controlSizeProp = 'medium', materialContext: materialContextProp = 'content', preferences = {}, storageKey = STORAGE_KEY, }) {
+    const [platformSelection, setPlatformSelection] = useState(platform);
+    const [platformVersionSelection, setPlatformVersionSelection] = useState(platformVersion);
+    const platformPack = resolvePlatformPack(platformSelection, platformVersionSelection);
+    const [uiTheme, setUIThemeState] = useState(uiThemeProp);
+    const [sidebarStyle, setSidebarStyle] = useState(() => sidebarStyleProp ?? 'edge-to-edge');
+    const [appearance, setAppearanceState] = useState(() => appearanceProp ?? getStoredTheme(storageKey));
+    const [resolvedAppearance, setResolvedAppearance] = useState(() => resolveTheme(appearance));
+    const [controlSize, setControlSize] = useState(controlSizeProp);
+    const [materialContext, setMaterialContext] = useState(materialContextProp);
+    const setAppearance = useCallback((newAppearance) => {
+        setAppearanceState(newAppearance);
+        if (storageKey && typeof window !== 'undefined') {
+            localStorage.setItem(storageKey, newAppearance);
+        }
+    }, [storageKey]);
+    const setPlatformPack = useCallback((nextPlatform, nextVersion) => {
+        setPlatformSelection(nextPlatform);
+        setPlatformVersionSelection(nextVersion);
     }, []);
-    // Apply theme to document
+    const setUITheme = useCallback((nextTheme) => {
+        setUIThemeState(nextTheme);
+        if (sidebarStyleProp === undefined) {
+            setSidebarStyle('edge-to-edge');
+        }
+    }, [sidebarStyleProp]);
+    useEffect(() => setPlatformSelection(platform), [platform]);
+    useEffect(() => setPlatformVersionSelection(platformVersion), [platformVersion]);
+    useEffect(() => {
+        setUIThemeState(uiThemeProp);
+        setSidebarStyle(sidebarStyleProp ?? 'edge-to-edge');
+    }, [sidebarStyleProp, uiThemeProp]);
     useEffect(() => {
-        const resolved = resolveTheme(theme);
-        setResolvedTheme(resolved);
+        if (appearanceProp)
+            setAppearanceState(appearanceProp);
+    }, [appearanceProp]);
+    useEffect(() => setControlSize(controlSizeProp), [controlSizeProp]);
+    useEffect(() => setMaterialContext(materialContextProp), [materialContextProp]);
+    useEffect(() => {
+        const resolved = resolveTheme(appearance);
+        setResolvedAppearance(resolved);
         const root = document.documentElement;
         root.classList.remove('light', 'dark');
         root.classList.add(resolved);
-    }, [theme]);
-    // Listen for system theme changes
+        root.dataset.uiTheme = uiTheme;
+        root.dataset.uiPlatform = platformPack.platform;
+        root.dataset.uiPlatformVersion = platformPack.version;
+        root.dataset.uiPlatformPack = platformPack.id;
+        root.dataset.uiSidebarStyle = sidebarStyle;
+        root.dataset.uiAppearance = resolved;
+        root.dataset.controlSize = controlSize;
+        root.dataset.materialContext = materialContext;
+        root.dataset.contrast = preferences.contrast ?? 'system';
+        root.dataset.transparency = preferences.transparency ?? 'system';
+        root.dataset.motion = preferences.motion ?? 'system';
+    }, [
+        appearance,
+        controlSize,
+        materialContext,
+        preferences.contrast,
+        preferences.motion,
+        preferences.transparency,
+        platformPack.id,
+        platformPack.platform,
+        platformPack.version,
+        sidebarStyle,
+        uiTheme,
+    ]);
     useEffect(() => {
-        if (theme !== 'system')
+        if (appearance !== 'system')
             return;
         const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
         const handleChange = () => {
             const resolved = getSystemTheme();
-            setResolvedTheme(resolved);
+            setResolvedAppearance(resolved);
             document.documentElement.classList.remove('light', 'dark');
             document.documentElement.classList.add(resolved);
+            document.documentElement.dataset.uiAppearance = resolved;
         };
         mediaQuery.addEventListener('change', handleChange);
         return () => mediaQuery.removeEventListener('change', handleChange);
-    }, [theme]);
-    return (_jsx(ThemeContext.Provider, { value: { theme, resolvedTheme, setTheme }, children: _jsx(TooltipProvider, { children: children }) }));
+    }, [appearance]);
+    return (_jsx(ThemeContext.Provider, { value: {
+            uiTheme,
+            setUITheme,
+            platform: platformPack.platform,
+            platformVersion: platformPack.version,
+            platformPack,
+            setPlatformPack,
+            sidebarStyle,
+            setSidebarStyle,
+            appearance,
+            resolvedAppearance,
+            setAppearance,
+            controlSize,
+            setControlSize,
+            materialContext,
+            setMaterialContext,
+            preferences,
+            theme: appearance,
+            resolvedTheme: resolvedAppearance,
+            setTheme: setAppearance,
+        }, children: _jsx(TooltipProvider, { children: children }) }));
 }
 export function useTheme() {
     const context = useContext(ThemeContext);
@@ -79,6 +155,10 @@ export function useTheme() {
     }
     return context;
 }
+/** Internal-friendly optional access for components that also work standalone. */
+export function useOptionalTheme() {
+    return useContext(ThemeContext);
+}
 /**
  * Inline script to prevent theme flash on page load.
  * Add this to your <head> in layout.tsx:
@@ -100,5 +180,13 @@ export const themeScript = `
     theme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
   }
   document.documentElement.classList.add(theme);
+  document.documentElement.dataset.uiTheme = 'moldable';
+  document.documentElement.dataset.uiPlatform = 'macos';
+  document.documentElement.dataset.uiPlatformVersion = '27';
+  document.documentElement.dataset.uiPlatformPack = 'macos-27';
+  document.documentElement.dataset.uiSidebarStyle = 'edge-to-edge';
+  document.documentElement.dataset.uiAppearance = theme;
+  document.documentElement.dataset.controlSize = 'medium';
+  document.documentElement.dataset.materialContext = 'content';
 })();
 `;

package/dist/tokens/contracts.d.ts

@@ -0,0 +1,79 @@
+export type UITheme = 'platform' | 'moldable';
+export type UIPlatform = 'macos' | 'windows' | 'web';
+export type UIPlatformVersion = string;
+/**
+ * A component recipe can intentionally come from a different versioned
+ * platform source than the application's base platform pack.
+ *
+ * Public names describe the anatomy an app is choosing. The registry below
+ * records which immutable platform source defines each recipe.
+ */
+export type UISidebarStyle = 'platform' | 'floating' | 'edge-to-edge';
+export type PlatformPackId = `${UIPlatform}-${string}`;
+export interface UIPlatformPack {
+    id: PlatformPackId;
+    platform: UIPlatform;
+    version: UIPlatformVersion;
+    capabilities: {
+        nativeMaterials: boolean;
+        nativeWindowChrome: boolean;
+        overlayScrollbars: boolean;
+    };
+}
+export type UIAppearance = 'light' | 'dark' | 'system';
+export type ResolvedUIAppearance = Exclude<UIAppearance, 'system'>;
+export type ControlSize = 'mini' | 'small' | 'medium' | 'large' | 'xl';
+export type LayoutDensity = 'compact' | 'regular' | 'comfortable';
+export type MaterialThickness = 'ultra-thick' | 'thick' | 'medium' | 'thin' | 'ultra-thin';
+export type MaterialContext = 'content' | 'over-glass';
+export type ContrastPreference = 'system' | 'standard' | 'increased';
+export type TransparencyPreference = 'system' | 'standard' | 'reduced';
+export type MotionPreference = 'system' | 'standard' | 'reduced';
+export interface UIPreferences {
+    contrast?: ContrastPreference;
+    transparency?: TransparencyPreference;
+    motion?: MotionPreference;
+}
+export declare const CONTROL_SIZES: readonly ["mini", "small", "medium", "large", "xl"];
+export declare const MATERIAL_THICKNESSES: readonly ["ultra-thick", "thick", "medium", "thin", "ultra-thin"];
+export declare const SIDEBAR_STYLES: {
+    readonly platform: {
+        readonly id: "platform";
+        readonly sourcePlatform: null;
+        readonly sourceVersion: null;
+    };
+    readonly floating: {
+        readonly id: "floating";
+        readonly sourcePlatform: "macos";
+        readonly sourceVersion: "26";
+    };
+    readonly 'edge-to-edge': {
+        readonly id: "edge-to-edge";
+        readonly sourcePlatform: "macos";
+        readonly sourceVersion: "27";
+    };
+};
+export declare const PLATFORM_PACKS: {
+    readonly 'macos-27': {
+        readonly id: "macos-27";
+        readonly platform: "macos";
+        readonly version: "27";
+        readonly capabilities: {
+            readonly nativeMaterials: true;
+            readonly nativeWindowChrome: true;
+            readonly overlayScrollbars: true;
+        };
+    };
+    readonly 'web-default': {
+        readonly id: "web-default";
+        readonly platform: "web";
+        readonly version: "default";
+        readonly capabilities: {
+            readonly nativeMaterials: false;
+            readonly nativeWindowChrome: false;
+            readonly overlayScrollbars: false;
+        };
+    };
+};
+export declare function resolvePlatformPack(platform: UIPlatform, version: UIPlatformVersion): UIPlatformPack;
+//# sourceMappingURL=contracts.d.ts.map

package/dist/tokens/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../../src/tokens/contracts.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,OAAO,GAAG,UAAU,GAAG,UAAU,CAAA;AAE7C,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,SAAS,GAAG,KAAK,CAAA;AAEpD,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAA;AAEtC;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,UAAU,GAAG,cAAc,CAAA;AAErE,MAAM,MAAM,cAAc,GAAG,GAAG,UAAU,IAAI,MAAM,EAAE,CAAA;AAEtD,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,cAAc,CAAA;IAClB,QAAQ,EAAE,UAAU,CAAA;IACpB,OAAO,EAAE,iBAAiB,CAAA;IAC1B,YAAY,EAAE;QACZ,eAAe,EAAE,OAAO,CAAA;QACxB,kBAAkB,EAAE,OAAO,CAAA;QAC3B,iBAAiB,EAAE,OAAO,CAAA;KAC3B,CAAA;CACF;AAED,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAA;AAEtD,MAAM,MAAM,oBAAoB,GAAG,OAAO,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAA;AAElE,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,IAAI,CAAA;AAEtE,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,CAAA;AAEjE,MAAM,MAAM,iBAAiB,GACzB,aAAa,GACb,OAAO,GACP,QAAQ,GACR,MAAM,GACN,YAAY,CAAA;AAEhB,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,YAAY,CAAA;AAEtD,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,UAAU,GAAG,WAAW,CAAA;AAEpE,MAAM,MAAM,sBAAsB,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAA;AAEtE,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAA;AAEhE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,kBAAkB,CAAA;IAC7B,YAAY,CAAC,EAAE,sBAAsB,CAAA;IACrC,MAAM,CAAC,EAAE,gBAAgB,CAAA;CAC1B;AAED,eAAO,MAAM,aAAa,qDAMiB,CAAA;AAE3C,eAAO,MAAM,oBAAoB,mEAMgB,CAAA;AAEjD,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;CAuB1B,CAAA;AAED,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;CAqBwB,CAAA;AAEnD,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,UAAU,EACpB,OAAO,EAAE,iBAAiB,GACzB,cAAc,CAMhB"}

package/dist/tokens/contracts.js

@@ -0,0 +1,57 @@
+export const CONTROL_SIZES = [
+    'mini',
+    'small',
+    'medium',
+    'large',
+    'xl',
+];
+export const MATERIAL_THICKNESSES = [
+    'ultra-thick',
+    'thick',
+    'medium',
+    'thin',
+    'ultra-thin',
+];
+export const SIDEBAR_STYLES = {
+    platform: {
+        id: 'platform',
+        sourcePlatform: null,
+        sourceVersion: null,
+    },
+    floating: {
+        id: 'floating',
+        sourcePlatform: 'macos',
+        sourceVersion: '26',
+    },
+    'edge-to-edge': {
+        id: 'edge-to-edge',
+        sourcePlatform: 'macos',
+        sourceVersion: '27',
+    },
+};
+export const PLATFORM_PACKS = {
+    'macos-27': {
+        id: 'macos-27',
+        platform: 'macos',
+        version: '27',
+        capabilities: {
+            nativeMaterials: true,
+            nativeWindowChrome: true,
+            overlayScrollbars: true,
+        },
+    },
+    'web-default': {
+        id: 'web-default',
+        platform: 'web',
+        version: 'default',
+        capabilities: {
+            nativeMaterials: false,
+            nativeWindowChrome: false,
+            overlayScrollbars: false,
+        },
+    },
+};
+export function resolvePlatformPack(platform, version) {
+    const exact = Object.values(PLATFORM_PACKS).find((pack) => pack.platform === platform && pack.version === version);
+    return exact ?? PLATFORM_PACKS['web-default'];
+}

package/dist/tokens/index.d.ts

@@ -0,0 +1,2 @@
+export { CONTROL_SIZES, MATERIAL_THICKNESSES, PLATFORM_PACKS, SIDEBAR_STYLES, resolvePlatformPack, type ContrastPreference, type ControlSize, type LayoutDensity, type MaterialContext, type MaterialThickness, type MotionPreference, type PlatformPackId, type ResolvedUIAppearance, type TransparencyPreference, type UIAppearance, type UIPlatform, type UIPlatformPack, type UIPlatformVersion, type UIPreferences, type UISidebarStyle, type UITheme, } from './contracts.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tokens/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tokens/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,OAAO,GACb,MAAM,aAAa,CAAA"}

package/dist/tokens/index.js

@@ -0,0 +1 @@
+export { CONTROL_SIZES, MATERIAL_THICKNESSES, PLATFORM_PACKS, SIDEBAR_STYLES, resolvePlatformPack, } from './contracts.js';

package/docs/README.md

@@ -8,6 +8,8 @@ feels at home on macOS without imitating private platform implementation.
 
 - [Foundations](./foundations.md)
 - [Design tokens](./design-tokens.md)
+- [Platform architecture](./platform-architecture.md)
+- [macOS design audit](./macos-design-audit.md)
 - [Adaptive materials](./adaptive-materials.md)
 - [App anatomy](./app-anatomy.md)
 - [Standalone app windows](./standalone-app-windows.md)

package/docs/adaptive-materials.md

@@ -6,14 +6,15 @@ not replace content surfaces.
 
 ## Roles
 
-Use `regular` material for normal toolbar and window chrome, grouped controls,
-menus, and temporary control overlays. It provides enough frosting for text
-and icons to remain stable as content moves behind it.
+Choose `ultra-thick`, `thick`, `medium`, `thin`, or `ultra-thin` according to
+the surface hierarchy. Medium material is the normal choice for window chrome,
+grouped controls, menus, and temporary control overlays.
 
-Use `clear` material only for compact controls floating over photos, maps,
+Use ultra-thin material only for compact controls floating over photos, maps,
 video, or another richly colored canvas. Check the control against the
 lightest, darkest, and busiest content it can cover. If contrast is not stable,
-use `regular`.
+use medium. The `regular` and `clear` names remain compatibility aliases for
+`medium` and `ultra-thin`, respectively.
 
 Documents, calendars, tables, forms, cards, sheets, inspectors, and primary
 working canvases remain opaque. Do not stack translucent content cards to
@@ -24,7 +25,7 @@ create hierarchy.
 `Material` applies one adaptive surface:
 
 ```tsx
-<Material asChild variant="clear" shape="circle" interactive>
+<Material asChild variant="ultra-thin" shape="circle" interactive>
   <IconButton label="Center map" variant="ghost">
     <Locate />
   </IconButton>
@@ -34,7 +35,7 @@ create hierarchy.
 `MaterialGroup` applies one sampled layer to a related cluster:
 
 ```tsx
-<MaterialGroup variant="regular" shape="capsule" spacing="compact">
+<MaterialGroup variant="medium" shape="capsule" spacing="compact">
   <IconButton label="Previous" variant="ghost">
     <ChevronLeft />
   </IconButton>
@@ -75,5 +76,9 @@ sampled layers and avoid nesting them.
 CSS material samples content inside the app renderer. It cannot sample the
 desktop behind a native window. Native behind-window material, window
 transparency, active-window appearance, and energy policy remain host-owned
-capabilities. Apps should use the same semantic variants regardless of which
-adapter renders them.
+capabilities. Apps should use the same thickness roles regardless of which
+adapter renders them. Apps opt into native regions per window through
+`moldable.json`; renderer-owned background and sidebar surfaces additionally
+opt in through `AppFrame`. Full-window background material uses a frosted,
+tinted host surface rather than uncovered transparency. Content that needs a
+stable reading surface can remain opaque above it.

package/docs/design-tokens.md

@@ -114,8 +114,9 @@ disabled, and invalid states. Disabled wins over pointer states. Focus remains
 visible when combined with selected or invalid. Selection is durable state;
 hover is not a substitute for it.
 
-Focus rings use the neutral translucent `--ring` token at one pixel. Never use
-plain `focus:` ring utilities or accent colors for keyboard focus.
+Focus rings use the shared `--ring` token and the width defined by each
+component recipe. Never use plain `focus:` ring utilities or invent a
+component-local focus color.
 
 Do not use state-layer colors as arbitrary fills. Prefer the shared component
 when one exists.
@@ -141,11 +142,14 @@ stay theme-aware and do not inherit Moldable's legacy brand orange. Apps may
 override the complete series palette at a theme boundary, but chart
 components and stories should never embed raw series colors.
 
-Adaptive material has two semantic variants. Each includes fill, fallback,
-border, highlight, blur, and saturation tokens:
+Adaptive material has five standard thickness variants: `ultra-thick`,
+`thick`, `medium`, `thin`, and `ultra-thin`. Each includes fill, fallback,
+border, highlight, blur, and saturation tokens. `regular` remains a
+compatibility alias for `medium`, and `clear` remains a compatibility alias
+for `ultra-thin`.
 
-- `--material-regular-*` supports normal toolbar and control chrome.
-- `--material-clear-*` supports compact controls over media or a richly
+- Medium material supports normal toolbar and control chrome.
+- Ultra-thin material supports compact controls over media or a richly
   colored canvas.
 - `shadow-panel`, `shadow-overlay`, `shadow-dialog`, and `shadow-window`
   provide elevation independently from translucency.

package/docs/foundations.md

@@ -22,9 +22,9 @@ Status color communicates status only; it is not decoration.
 - Preserve usable pointer targets even when the visible control is small.
 - Prefer separators, background shifts, and whitespace over nested cards.
 - Working panes own scrolling. The window shell should not accidentally scroll.
-- Set `data-density="compact"`, `"default"`, or `"comfortable"` at a
-  composition boundary. Components should consume density tokens rather than
-  inventing per-screen heights.
+- Set `data-density="compact"` or `"comfortable"` at a composition boundary;
+  omit it for regular/default density. Components should consume density
+  tokens rather than inventing per-screen heights.
 
 ## Surfaces
 

package/docs/macos-design-audit.md

@@ -0,0 +1,144 @@
+# macOS design audit for Moldable UI
+
+Status: active  
+Target: macOS desktop apps rendered in Moldable-owned Tauri windows  
+Scope: `@moldable-ai/ui`, app-owned titlebars, and the Moldable UI catalog
+
+This audit treats macOS AppKit and SwiftUI behavior as the semantic reference
+while allowing a React implementation. The goal is not to copy source pixels.
+The goal is to preserve macOS hierarchy, density, control roles, window
+behavior, input behavior, and accessibility expectations.
+
+## Reference baseline
+
+- Foundations: Typography — Ensuring legibility, Conveying hierarchy, Using
+  system fonts, Platform considerations/macOS
+- Foundations: Layout — Visual hierarchy, Adaptability, Platform
+  considerations/macOS
+- Foundations: Materials — Liquid Glass, Standard materials, Platform
+  considerations/macOS
+- Foundations: Color — Best practices, Inclusive color, System colors
+- Foundations: Dark Mode — Best practices, Platform considerations/macOS
+- Foundations: Accessibility — Vision, Mobility, Cognitive
+- Foundations: Icons — Best practices, Platform considerations/macOS
+- Foundations: Motion — Best practices, Providing feedback
+- Platforms: Designing for macOS — Best practices
+- Layout: Sidebars, Split views, Windows, Lists and tables
+- Menus: Toolbars — Titles, Navigation, Actions, Item groupings,
+  Platform considerations/macOS
+- Menus: Buttons — Style, Content, Role, Platform considerations/macOS
+- Controls: Toggles, Segmented controls, Text fields
+- Search: Search fields — Best practices, Platform considerations/iPadOS,
+  macOS
+
+## Severity-ranked findings
+
+### P0 — window and navigation semantics
+
+1. App-owned titlebars must preserve the native traffic-light exclusion area,
+   a draggable noninteractive region, double-click window behavior, and usable
+   interactive controls. `Toolbar`, the desktop host, and window metadata must
+   be tested together; CSS alone cannot guarantee this contract.
+2. Toolbar titles must identify the current view or document, not repeat the
+   application name. App identity belongs to the window and system surfaces.
+3. Back controls must call Moldable navigation and expose the same action to
+   keyboard and menu commands. A decorative chevron is not navigation.
+
+### P1 — hierarchy and control roles
+
+1. Use a sidebar or tab view for top-level destinations. A segmented control is
+   for a small set of closely related modes that affect one view, not primary
+   app navigation.
+2. Keep only frequent actions in a toolbar. Put infrequent actions in a More
+   menu and mirror every command in the macOS menu bar.
+3. Group only controls that are logically related. Standalone navigation
+   controls should usually be quiet; groups may own one shared capsule.
+4. Use the system appearance by default. An appearance selector is appropriate
+   in a component test harness, but not as persistent application chrome.
+5. Prefer compact macOS typography: 13 px body, 15–16 px titles, 18 px section
+   headings, and 24 px display headings. Avoid web-dashboard hero sizing in
+   ordinary desktop panes.
+6. Prefer flat content hierarchy, separators, and selection fills over nested
+   bordered cards and repeated shadows. Materials belong to navigation and
+   transient controls, not every content surface.
+7. Use switches for immediate, emphasized binary settings. Use checkboxes for
+   ordinary grouped preferences and radio buttons for mutually exclusive
+   choices.
+
+### P2 — desktop completeness
+
+1. Extend the existing resizable `SplitView` with a documented collapsible
+   recipe, restoration, and automatic narrow-window collapse.
+2. Add table column resizing, sorting, optional alternating row backgrounds,
+   keyboard range selection, and state restoration.
+3. Extend command metadata so toolbar items, menus, keyboard shortcuts,
+   accessibility labels, and disabled state can share one source of truth.
+4. Separate semantic action roles from visual button variants and cover
+   default, cancel, destructive, help, disclosure, toolbar, and icon-only
+   actions.
+5. Validate at increased contrast, reduced transparency, reduced motion,
+   keyboard-only input, 200% zoom, and light/dark appearances.
+
+## Current conformance
+
+The shared package already provides:
+
+- semantic light and dark colors instead of raw app-specific grays;
+- a system-font stack and compact macOS-oriented type tokens;
+- labeled icon buttons with visible keyboard focus;
+- reduced-motion and reduced-transparency fallbacks;
+- explicit status text in addition to color;
+- titlebar insets and window drag handlers for app-owned top toolbars;
+- compact, regular, and comfortable density tokens;
+- a distinct accent-colored `prominent` button role for the single key action
+  in a view, without changing the appearance of existing default buttons.
+
+The Moldable UI catalog now demonstrates:
+
+- top-level source-list navigation in the sidebar;
+- current-view toolbar titles;
+- quiet standalone toolbar navigation;
+- preview-only appearance and accessibility controls;
+- flatter stages, fewer shadows, and smaller radii;
+- package typography tokens instead of oversized page-specific values.
+
+## Component acceptance criteria
+
+### Toolbar
+
+- Uses the current view or document title.
+- Preserves native window-control clearance in app-owned windows.
+- Dragging works from every noninteractive toolbar region.
+- Interactive descendants never initiate a window drag.
+- Frequent actions are visible; rare actions are in More.
+- Related actions share a group; unrelated actions do not.
+- Commands have labels, tooltips when helpful, shortcuts, menu equivalents,
+  disabled states, and tests.
+
+### Sidebar and split view
+
+- Selection is persistent and visually unambiguous.
+- Search filters the sidebar content it sits above.
+- Sidebar width is resizable within reasonable minimum and maximum values.
+- The sidebar can collapse automatically in a narrow window and manually at
+  any size.
+- The divider remains subtle and the sidebar doesn’t compete with content.
+
+### Controls
+
+- Labels describe outcomes, not implementation.
+- The default action is visually prominent only when the context needs one.
+- Destructive actions are explicit and separated from routine actions.
+- Icons use familiar system metaphors and never carry meaning without an
+  accessible label.
+- Controls remain operable with keyboard, pointer, VoiceOver, increased
+  contrast, reduced transparency, and reduced motion.
+
+## Review policy
+
+Every new public visual primitive must include catalog stories for light and
+dark appearance, compact and regular density, wide and narrow viewport,
+rest/focus/disabled/invalid states where applicable, and accessible naming.
+Every window-chrome change must be verified in a real Moldable-owned macOS
+window because embedded browser rendering cannot validate traffic-light
+placement or native dragging.

package/docs/native-integration.md

@@ -16,10 +16,10 @@ Do not create UI-only no-op stubs for native menus, share sheets, or date
 pickers. First define ownership, cancellation, errors, replay/reconnect
 behavior, and platform fallbacks.
 
-`DateField` is the portable renderer baseline. A future system date picker,
-share sheet, or native menu must only be selected after the host advertises the
-service through a versioned context. Requests must remain bound to the
-originating app window and user activation.
+`DateField`, renderer menus, and browser file/share controls remain the
+portable baselines. The package currently exposes host-advertised date/time
+picker, share, native-menu, and file-dialog services with renderer fallbacks.
+Requests remain bound to the originating app window and user activation.
 
 Standalone windows should remain host-owned surfaces around an app frame. Do
 not load arbitrary app URLs directly into a privileged native webview merely to