Improve cross-platform design documentation

platform-rules/README.md

@@ -0,0 +1,44 @@
+# Platform Rules
+
+These documents define behavior that differs across Windows, Linux, macOS, Android, iOS, and Web. Shared visual standards are defined in [`../DESIGN.md`](../DESIGN.md); shared architecture is defined in [`../ARCHITECTURE.md`](../ARCHITECTURE.md).
+
+## Architecture invariants
+
+- `go_router` owns navigation state, route restoration, browser URLs, and platform back navigation.
+- Riverpod owns application state, dependencies, and asynchronous workflows.
+- Platform rule documents must not contain business logic or duplicate feature state.
+- Shared tokens and components remain the visual source of truth.
+- Platform adapters expose capabilities such as file access, clipboard, lifecycle, and window behavior.
+- Every platform-specific behavior must have a smoke-test scenario.
+
+## Platform comparison
+
+| Platform | Primary input | Navigation concerns | Capability concerns | Release concerns |
+| --- | --- | --- | --- | --- |
+| [Windows](windows.md) | Keyboard, mouse, context menus | Desktop shell and shortcuts | Windows, file dialogs, high-DPI | Installer/package and resize smoke tests |
+| [Linux](linux.md) | Keyboard and mouse | Desktop shell and shortcuts | Window managers, file selection | Distribution packaging and environment coverage |
+| [macOS](macos.md) | Keyboard, mouse, trackpad | Command-key conventions | Permissions, file access, window lifecycle | Signing, notarization, and release validation |
+| [Android](android.md) | Touch, system back, keyboard | Back stack and route restoration | Insets, lifecycle, keyboard | APK/AAB builds and device/API coverage |
+| [iOS](ios.md) | Touch, gestures, keyboard | Route restoration and system gestures | Safe areas, lifecycle, permissions | Signing, archive, and device coverage |
+| [Web](web.md) | Mouse, keyboard, touch | URLs, refresh, history | Downloads, clipboard, browser APIs | Hosted build, deep links, and browser coverage |
+
+## Shared platform checklist
+
+For every target:
+
+- Verify the correct shell is selected for the available constraints and platform capabilities.
+- Verify loading, success, empty, and recoverable error states.
+- Verify keyboard or touch access for every primary interaction.
+- Verify visible focus and accessibility labels.
+- Verify text scaling and content that wraps at narrow widths.
+- Verify unsaved work survives resize, route changes, and supported lifecycle transitions.
+- Verify file and clipboard behavior using the platform adapter.
+- Run the target's smoke tests before release.
+
+## Adding or changing a platform rule
+
+1. Describe the platform behavior and why the shared implementation is insufficient.
+2. Keep the change in the platform adapter or shell rather than in domain logic.
+3. Add or update a smoke test scenario.
+4. Check that the change does not duplicate `go_router` or Riverpod state.
+5. Update the comparison table if capabilities or release requirements change.

platform-rules/android.md

@@ -1,5 +1,7 @@
 # Android Platform Rules
 
+## Interaction and layout
+
 - Respect safe areas, system bars, and gesture navigation.
 - Support Android back navigation through `go_router` without duplicating navigation state in Riverpod.
 - Use touch targets of at least 48 logical px where practical.
@@ -7,4 +9,25 @@
 - Prefer single-pane layouts on narrow screens.
 - Preserve editor state and scroll position during navigation.
 - Respect system text scaling and activity lifecycle events.
-- Verify keyboard, back navigation, lifecycle restoration, and safe-area behavior during smoke tests.
+
+## Capabilities and permissions
+
+- Request runtime permissions only when the user initiates the capability that needs them.
+- Use platform adapters for file selection, storage, clipboard, and lifecycle integration.
+- Handle denied, revoked, or unavailable permissions as recoverable states.
+- Restore supported editor and route state after activity recreation.
+
+## Release requirements
+
+- Validate debug, profile, and release builds as appropriate for the project.
+- Test the supported Android API/device matrix, including narrow and large screens.
+- Verify application signing, app links if used, and permission declarations.
+- Verify keyboard, back navigation, lifecycle restoration, and safe-area behavior.
+
+## Smoke-test checklist
+
+- Navigate forward and back through nested routes.
+- Open the keyboard and verify content resizes or scrolls without clipping.
+- Rotate or resize supported devices and confirm state is preserved.
+- Deny and grant file or storage permissions.
+- Background and resume the app while editing unsaved content.

platform-rules/ios.md

@@ -1,5 +1,7 @@
 # iOS Platform Rules
 
+## Interaction and layout
+
 - Respect safe areas, system gestures, and device insets.
 - Support back navigation and route restoration through `go_router` without duplicating navigation state in Riverpod.
 - Use touch targets of at least 48 logical px where practical.
@@ -7,4 +9,25 @@
 - Prefer single-pane layouts on narrow screens.
 - Preserve editor state and scroll position during navigation.
 - Respect system text scaling and app lifecycle events.
-- Verify keyboard, gesture navigation, lifecycle restoration, and safe-area behavior during smoke tests.
+
+## Capabilities and permissions
+
+- Request permissions in context, immediately before using the capability.
+- Use platform adapters for file selection, document access, clipboard, and lifecycle integration.
+- Handle denied, restricted, or unavailable permissions as recoverable states.
+- Restore supported editor and route state after app termination or restoration.
+
+## Release requirements
+
+- Validate signing, provisioning, entitlements, and archive/export configuration.
+- Test the supported iOS version and device-size matrix.
+- Verify required usage descriptions for platform permissions.
+- Verify keyboard, gesture navigation, lifecycle restoration, and safe-area behavior.
+
+## Smoke-test checklist
+
+- Navigate forward and back through nested routes.
+- Open the keyboard and verify content resizes or scrolls without clipping.
+- Test safe areas on supported device sizes.
+- Deny and grant file or clipboard permissions where applicable.
+- Background, terminate, and relaunch the app while editing unsaved content.

platform-rules/linux.md

@@ -1,9 +1,30 @@
 # Linux Platform Rules
 
+## Interaction and layout
+
 - Support window resizing without losing unsaved state.
 - Support keyboard and mouse interaction with visible focus indicators.
 - Use persistent sidebars at expanded widths.
 - Provide tooltips for unfamiliar icon-only actions.
-- Support file selection through the platform abstraction.
+- Allow panels to collapse and, where useful, resize.
+
+## Capabilities and permissions
+
+- Use the platform adapter for file selection and application directories.
 - Account for desktop packaging and distribution differences.
-- Verify common window managers, scaling behavior, and file access during smoke tests.
+- Do not assume a specific window manager, desktop environment, display server, or system theme.
+- Handle file access and unsupported capability errors as recoverable states.
+
+## Release requirements
+
+- Define the supported Linux distributions and packaging format before release.
+- Test on the supported distribution matrix and at least one common window manager configuration.
+- Verify scaling, keyboard/mouse behavior, file access, and packaged startup.
+
+## Smoke-test checklist
+
+- Resize the window while editing unsaved content.
+- Navigate primary destinations with keyboard and mouse.
+- Open, save, and cancel file-selection dialogs.
+- Verify focus indicators, tooltips, and content scaling.
+- Confirm the packaged build starts and handles unavailable capabilities gracefully.

platform-rules/macos.md

@@ -1,9 +1,30 @@
 # macOS Platform Rules
 
+## Interaction and layout
+
 - Support Command-key keyboard shortcuts and visible focus indicators.
 - Follow desktop window conventions and support resizing without losing unsaved state.
 - Support trackpad gestures where they provide a clear benefit.
-- Use native file access through the platform abstraction.
 - Use persistent sidebars at expanded widths and allow panels to collapse or resize where useful.
 - Provide tooltips for unfamiliar icon-only actions.
-- Verify permissions, file access, keyboard behavior, and window lifecycle during smoke tests.
+
+## Capabilities and permissions
+
+- Use the platform adapter for file access and application directories.
+- Handle user permission denial as a recoverable error.
+- Respect macOS menu, focus, window, and full-screen conventions.
+- Preserve editor state through app deactivation and supported lifecycle transitions.
+
+## Release requirements
+
+- Validate signing, entitlements, notarization, and the distribution format used by the project.
+- Test supported macOS versions and display scaling configurations.
+- Verify permissions, file access, keyboard behavior, trackpad behavior, and window lifecycle.
+
+## Smoke-test checklist
+
+- Resize and minimize the window while editing unsaved content.
+- Navigate primary destinations with keyboard, mouse, and trackpad.
+- Open, save, and cancel file-selection dialogs.
+- Deny and grant file permissions and verify recoverable errors.
+- Confirm the signed and packaged build launches correctly.

platform-rules/web.md

@@ -1,10 +1,33 @@
 # Web Platform Rules
 
+## Interaction and layout
+
 - Keep URLs meaningful and navigable through `go_router`.
 - Test direct loading of nested routes, refresh, browser back/forward, and history restoration.
 - Do not intercept browser-reserved keyboard shortcuts.
 - Ensure hover interactions have keyboard and touch alternatives.
 - Constrain content width on large monitors.
 - Test browser zoom, narrow viewports, and text scaling.
-- Handle downloads, clipboard access, and file selection according to browser permissions and supported APIs.
 - Do not display native desktop window title-bar UI merely because the browser viewport is wide.
+
+## Capabilities and permissions
+
+- Handle downloads, clipboard access, and file selection according to browser permissions and supported APIs.
+- Treat denied permissions, blocked pop-ups, unsupported APIs, and cancelled file selection as recoverable states.
+- Use browser-safe platform adapters rather than assuming native filesystem access.
+- Preserve route state in URLs and avoid storing navigational truth only in memory.
+
+## Release requirements
+
+- Configure hosted fallback behavior so direct nested URLs load correctly.
+- Test supported browsers and the production build, not only the development server.
+- Verify browser security policies, asset paths, service-worker behavior if used, and cache invalidation.
+- Test browser zoom, refresh, direct URLs, history, downloads, clipboard, and file selection.
+
+## Smoke-test checklist
+
+- Load every primary route directly in a new browser tab.
+- Refresh nested routes and verify the expected screen remains addressable.
+- Use browser back and forward controls.
+- Test keyboard, mouse, touch, zoom, and narrow viewport behavior.
+- Cancel and deny file, clipboard, and download actions and verify recoverable feedback.

platform-rules/windows.md

@@ -1,9 +1,31 @@
 # Windows Platform Rules
 
+## Interaction and layout
+
 - Support window resizing without losing unsaved state.
 - Use persistent sidebars at expanded widths.
 - Support keyboard navigation, visible focus indicators, mouse hover, and context menus.
 - Provide discoverable keyboard shortcuts and tooltips for unfamiliar icon-only actions.
-- Use native file dialogs through the platform abstraction.
 - Allow panels to collapse and, where useful, resize.
-- Verify high-DPI scaling, window minimum sizes, and resize behavior during smoke tests.
+- Preserve editor state when the window changes size or loses focus.
+
+## Capabilities and permissions
+
+- Use the platform adapter for native file dialogs and application directories.
+- Handle file access failures as recoverable errors.
+- Account for high-DPI scaling and Windows display scaling.
+- Avoid assuming a fixed title-bar or minimum-window size.
+
+## Release requirements
+
+- Validate the packaged installer or distribution format used by the project.
+- Test on supported Windows versions and common display scaling settings.
+- Verify keyboard shortcuts, context menus, file selection, high-DPI rendering, and resize behavior before release.
+
+## Smoke-test checklist
+
+- Resize the window repeatedly while editing unsaved content.
+- Navigate all primary destinations with keyboard and mouse.
+- Open, save, and cancel native file dialogs.
+- Confirm focus indicators and tooltips are visible.
+- Verify the packaged build starts and restores expected application state.