feat: add URL deep-linking for DataGrids

- Add PageUrlState utility for URL ↔ state serialization
- Add column `id` field for unique column identification in URLs
- Update idSelector to return String for URL compatibility
- All DataGrid pages now support URL params: search, sort, order, id
- Browser URL updates via replaceState (no GoRouter rebuilds)
- Add FilterPanelSemantics for filter panel semantic IDs
- Add TESTING.md documentation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

CHANGELOG.md

@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-01-05
+
+### Added
+- **URL deep-linking for DataGrids** - State is now reflected in URL query parameters
+  - `?search=` - DataGrid search query
+  - `?sort=` - Column ID for sorting
+  - `?order=desc` - Sort direction
+  - `?id=` - Opened document ID (proxy hosts page)
+- `PageUrlState` utility class (`lib/routing/url_state.dart`) for URL ↔ state serialization
+- Browser URL updates via `replaceState` without triggering GoRouter rebuilds
+- `id` field added to `DataGridColumn` for unique column identification in URLs
+- `FilterPanelSemantics` class for filter panel semantic IDs
+- TESTING.md documentation for semantic widgets and automation testing
+
+### Changed
+- `idSelector` in DataGridController now returns `String` (was `Object`) for URL compatibility
+- All DataGrid pages now support URL deep-linking:
+  - Containers list (`/control-room/containers`)
+  - Proxy hosts (`/control-room/proxy-hosts`)
+  - Users (`/security/users`)
+  - Groups (`/security/groups`)
+- Router passes `GoRouterState` to pages for query parameter access
+
+## [1.2.0] - 2026-01-05
+
+### Added
+- **Semantic labels for UI automation** (`lib/core/semantics/`)
+  - `semantic_ids.dart` - Centralized semantic identifier constants
+  - `semantic_widget.dart` - Helper widget and extension for adding semantics
+  - Enables browser automation tools (Puppeteer, WebDriver) via accessibility tree
+- Semantic IDs added to:
+  - Profile dropdown button and menu items (theme options, settings, logout)
+  - Room navigation tabs (Front Hall, Control Room, Security, Parlor)
+  - NavPanel items (sidebar navigation)
+- `SemanticsBinding.instance.ensureSemantics()` enabled on web builds
+
 ## [1.1.16] - 2026-01-05
 
 ### Fixed

docs/ARCHITECTURE.md

@@ -20,6 +20,7 @@ lib/
 │   ├── auth/                     # Authentik OIDC integration
 │   ├── config/                   # Environment configuration
 │   ├── error/                    # Error types and handling
+│   ├── semantics/                # Semantic IDs for automation
 │   └── theme/                    # Material 3 theming
 ├── routing/                      # go_router configuration
 ├── shared/                       # Reusable components
@@ -544,3 +545,28 @@ import 'package:tatlock_ui/features/containers/domain/entities/container.dart';
 // Bad - importing model in presentation
 import '../data/models/container_model.dart'; // Don't do this
 ```
+
+## Semantic Identifiers for Automation
+
+All interactive widgets should have semantic identifiers for UI automation. This enables reliable testing with Puppeteer, Appium, and other automation tools.
+
+### Quick Reference
+
+```dart
+import 'package:tatlock_ui/core/semantics/semantic_ids.dart';
+
+// Wrap interactive widgets with Semantics
+Semantics(
+  identifier: DataGridSemantics.row(item.id),
+  label: 'Select ${item.name}',
+  child: MyRowWidget(item: item),
+)
+```
+
+### Key Points
+
+1. **Central ID Registry** - All IDs defined in `lib/core/semantics/semantic_ids.dart`
+2. **Naming Convention** - `{area}_{component}_{identifier}` (e.g., `dataGrid_row_abc123`)
+3. **Web Enabled** - Semantics tree exposed via `SemanticsBinding.instance.ensureSemantics()` in `main.dart`
+
+For complete documentation on semantic patterns, automation queries, and best practices, see **[TESTING.md](./TESTING.md)**.

docs/TESTING.md

@@ -0,0 +1,368 @@
+# Testing & Automation Guide
+
+This document covers automated testing patterns for Tatlock UI, focusing on semantic identifiers that enable reliable UI automation.
+
+## Overview
+
+Tatlock UI uses Flutter's **Semantics tree** to expose stable identifiers for automated testing. These identifiers are accessible to:
+
+- **Puppeteer** (via Chrome DevTools accessibility API)
+- **Appium** (via accessibility labels)
+- **WebDriver** (via ARIA attributes)
+- **Flutter integration tests**
+
+The semantics system is enabled on web in `main.dart`:
+
+```dart
+if (kIsWeb) {
+  SemanticsBinding.instance.ensureSemantics();
+}
+```
+
+## Semantic Identifiers
+
+All semantic IDs are centralized in `lib/core/semantics/semantic_ids.dart`. This provides:
+
+1. **Stable selectors** - IDs don't change with UI refactoring
+2. **Type safety** - Compile-time verification of ID usage
+3. **Discoverability** - Single source of truth for automation targets
+
+### Available ID Classes
+
+| Class | Purpose | Example IDs |
+|-------|---------|-------------|
+| `ProfileSemantics` | User profile dropdown | `profile_button`, `profile_menu_settings` |
+| `RoomTabSemantics` | Main navigation tabs | `roomTab_frontHall`, `roomTab_controlRoom` |
+| `NavSemantics` | Side navigation panel | `nav_panel`, `nav_item_{id}` |
+| `DataGridSemantics` | Data tables | `dataGrid_row_{id}`, `dataGrid_search` |
+| `DialogSemantics` | Modal dialogs | `dialog_confirm`, `dialog_cancel` |
+| `SettingsSemantics` | Settings page | `settings_theme`, `settings_defaultRoom` |
+| `StateSemantics` | Loading/error states | `state_auth_loading`, `snackbar_{type}` |
+
+### ID Naming Convention
+
+```
+{area}_{component}_{identifier}
+```
+
+- **area**: Feature or section (e.g., `profile`, `nav`, `dataGrid`)
+- **component**: Widget type (e.g., `menu`, `button`, `row`)
+- **identifier**: Specific item (e.g., `light`, `settings`, `selectAll`)
+
+Examples:
+- `profile_menu_theme_dark` - Dark theme option in profile menu
+- `dataGrid_row_abc123` - Row with ID "abc123" in data grid
+- `nav_item_containers` - Containers nav item
+
+## Adding Semantics to Widgets
+
+### Method 1: Direct Semantics Widget
+
+Use Flutter's `Semantics` widget with the `identifier` property:
+
+```dart
+import 'package:tatlock_ui/core/semantics/semantic_ids.dart';
+
+Semantics(
+  identifier: ProfileSemantics.button,
+  label: 'Open profile menu',
+  button: true,
+  child: IconButton(
+    icon: Icon(Icons.person),
+    onPressed: () => ...,
+  ),
+)
+```
+
+### Method 2: SemanticWidget Wrapper
+
+Use the convenience wrapper from `lib/core/semantics/semantic_widget.dart`:
+
+```dart
+import 'package:tatlock_ui/core/semantics/semantic_ids.dart';
+import 'package:tatlock_ui/core/semantics/semantic_widget.dart';
+
+SemanticWidget(
+  id: DataGridSemantics.search,
+  label: 'Search data grid',
+  textField: true,
+  child: TextField(
+    decoration: InputDecoration(hintText: 'Search...'),
+  ),
+)
+```
+
+### Method 3: Extension Method
+
+Use the `withSemantics` extension for inline wrapping:
+
+```dart
+TextField(
+  decoration: InputDecoration(hintText: 'Search...'),
+).withSemantics(
+  id: DataGridSemantics.search,
+  label: 'Search data grid',
+)
+```
+
+### Dynamic IDs
+
+For lists and grids, use the generator methods:
+
+```dart
+// Row in a data grid
+Semantics(
+  identifier: DataGridSemantics.row(item.id),  // "dataGrid_row_abc123"
+  child: DataGridRow(item: item),
+)
+
+// Navigation item
+Semantics(
+  identifier: NavSemantics.item(route.id),  // "nav_item_containers"
+  child: NavItem(route: route),
+)
+
+// Bulk action button
+Semantics(
+  identifier: DataGridSemantics.bulkAction('delete'),  // "dataGrid_bulk_delete"
+  child: IconButton(icon: Icon(Icons.delete), ...),
+)
+```
+
+## Querying from Puppeteer
+
+Puppeteer can query semantic identifiers via Chrome's accessibility tree:
+
+```javascript
+// Connect to Chrome with DevTools protocol
+const browser = await puppeteer.connect({
+  browserURL: 'http://localhost:9222'
+});
+const page = await browser.newPage();
+
+// Get accessibility snapshot
+const snapshot = await page.accessibility.snapshot({ interestingOnly: false });
+
+// Find element by semantic identifier
+function findBySemanticId(node, id) {
+  if (node.name === id || node.description === id) {
+    return node;
+  }
+  for (const child of node.children || []) {
+    const found = findBySemanticId(child, id);
+    if (found) return found;
+  }
+  return null;
+}
+
+// Example: Find profile button
+const profileButton = findBySemanticId(snapshot, 'profile_button');
+
+// Example: Find a specific data grid row
+const row = findBySemanticId(snapshot, 'dataGrid_row_abc123');
+```
+
+### Using Chrome DevTools MCP
+
+With the Chrome DevTools MCP server, you can query semantics directly:
+
+```javascript
+// Take a snapshot (returns accessibility tree)
+const snapshot = await mcp__chrome_devtools__take_snapshot();
+
+// Click by semantic ID (uid in snapshot)
+await mcp__chrome_devtools__click({ uid: 'profile_button' });
+
+// Fill input by semantic ID
+await mcp__chrome_devtools__fill({
+  uid: 'dataGrid_search',
+  value: 'my search query'
+});
+```
+
+## Best Practices
+
+### 1. Add Semantics to Interactive Elements
+
+Every clickable, tappable, or input element should have a semantic identifier:
+
+```dart
+// Buttons
+Semantics(
+  identifier: 'myFeature_submit',
+  button: true,
+  label: 'Submit form',
+  child: ElevatedButton(...),
+)
+
+// Text fields
+Semantics(
+  identifier: 'myFeature_email',
+  textField: true,
+  label: 'Email address',
+  child: TextField(...),
+)
+
+// Checkboxes
+Semantics(
+  identifier: 'myFeature_rememberMe',
+  checked: isChecked,
+  label: 'Remember me',
+  child: Checkbox(...),
+)
+```
+
+### 2. Use Meaningful Labels
+
+Labels help both accessibility tools and test debugging:
+
+```dart
+// Good - descriptive label
+Semantics(
+  identifier: DataGridSemantics.rowAction(item.id, 'delete'),
+  label: 'Delete ${item.name}',
+  button: true,
+  child: ...,
+)
+
+// Bad - no context
+Semantics(
+  identifier: 'btn1',
+  child: ...,
+)
+```
+
+### 3. Register New IDs Centrally
+
+Always add new semantic IDs to `semantic_ids.dart`:
+
+```dart
+/// My new feature IDs.
+abstract class MyFeatureSemantics {
+  static const submitButton = 'myFeature_submit';
+  static const cancelButton = 'myFeature_cancel';
+  static const nameField = 'myFeature_name';
+
+  /// Generate ID for a list item.
+  static String item(String id) => 'myFeature_item_$id';
+}
+```
+
+### 4. Test ID Stability
+
+Semantic IDs should remain stable across releases. When refactoring:
+
+- Keep existing IDs unchanged
+- Add deprecation comments if IDs must change
+- Update automation tests when IDs change
+
+### 5. Exclude Decorative Elements
+
+Don't add semantic IDs to purely decorative elements:
+
+```dart
+// Decorative icon - no semantics needed
+Icon(Icons.star, color: Colors.yellow)
+
+// Interactive icon - needs semantics
+Semantics(
+  identifier: 'rating_star_3',
+  button: true,
+  label: 'Rate 3 stars',
+  child: IconButton(
+    icon: Icon(Icons.star),
+    onPressed: () => rate(3),
+  ),
+)
+```
+
+## DataGrid Semantic Patterns
+
+The DataGrid component has comprehensive semantic coverage:
+
+```
+dataGrid                     - The grid container
+dataGrid_search              - Search input field
+dataGrid_search_clear        - Clear search button
+dataGrid_selectAll           - Select all checkbox
+dataGrid_header_{columnId}   - Column header (sortable)
+dataGrid_row_{itemId}        - Row container
+dataGrid_row_{itemId}_checkbox    - Row selection checkbox
+dataGrid_row_{itemId}_actions     - Row actions menu trigger
+dataGrid_row_{itemId}_action_{actionId}  - Specific row action
+dataGrid_bulk_{actionId}     - Bulk action button
+dataGrid_bulk_clear          - Clear selection button
+dataGrid_loading             - Loading indicator
+dataGrid_empty               - Empty state message
+dataGrid_error               - Error state message
+dataGrid_refresh             - Refresh button
+```
+
+### Example: Automating DataGrid Selection
+
+```javascript
+// Select all rows
+await click('dataGrid_selectAll');
+
+// Select specific row
+await click('dataGrid_row_abc123_checkbox');
+
+// Perform bulk delete
+await click('dataGrid_bulk_delete');
+
+// Confirm in dialog
+await click('dialog_confirm');
+```
+
+## Debugging Semantics
+
+### Flutter DevTools
+
+1. Open Flutter DevTools
+2. Go to "Inspector" tab
+3. Enable "Semantics" overlay
+4. Click widgets to see their semantic properties
+
+### Chrome DevTools
+
+1. Open DevTools (F12)
+2. Go to "Accessibility" tab
+3. Inspect the accessibility tree
+4. Search for semantic identifiers
+
+### Programmatic Inspection
+
+```dart
+// In a test, dump the semantics tree
+debugDumpSemanticsTree();
+
+// Check if semantics are enabled
+print('Semantics enabled: ${SemanticsBinding.instance.semanticsEnabled}');
+```
+
+## Integration with URL Routing
+
+For deep-linkable test scenarios, semantic IDs work with URL query parameters:
+
+```
+/control-room/containers?selected=abc123
+```
+
+Automation can:
+1. Navigate to URL with query params
+2. Verify selection state via `dataGrid_row_abc123_checkbox` (checked: true)
+3. Interact with selected rows via semantic IDs
+
+See [URL Routing](#url-routing) section for query parameter patterns.
+
+## Checklist for New Features
+
+When adding a new feature, ensure semantic coverage:
+
+- [ ] Add semantic ID class to `semantic_ids.dart`
+- [ ] Wrap all buttons with `Semantics` + `identifier`
+- [ ] Wrap all inputs with `Semantics` + `identifier`
+- [ ] Wrap list/grid items with dynamic IDs
+- [ ] Add labels for accessibility
+- [ ] Test that IDs appear in accessibility snapshot
+- [ ] Document IDs in this file if they establish new patterns

lib/core/semantics/semantic_ids.dart

@@ -0,0 +1,125 @@
+/// Semantic identifiers for UI automation and accessibility.
+///
+/// These IDs are exposed via Flutter's Semantics tree, making widgets
+/// discoverable by automation tools (Appium, WebDriver, Puppeteer with
+/// accessibility enabled).
+///
+/// Naming convention: `{area}_{component}_{identifier}`
+/// - area: room or feature area (e.g., profile, nav, dataGrid)
+/// - component: widget type (e.g., menu, button, row)
+/// - identifier: specific item (e.g., light, containers, selectAll)
+library;
+
+/// Profile dropdown menu IDs.
+abstract class ProfileSemantics {
+  static const button = 'profile_button';
+  static const menu = 'profile_menu';
+  static const settings = 'profile_menu_settings';
+  static const themeSystem = 'profile_menu_theme_system';
+  static const themeLight = 'profile_menu_theme_light';
+  static const themeDark = 'profile_menu_theme_dark';
+  static const logout = 'profile_menu_logout';
+}
+
+/// Room tab navigation IDs.
+abstract class RoomTabSemantics {
+  static const frontHall = 'roomTab_frontHall';
+  static const controlRoom = 'roomTab_controlRoom';
+  static const security = 'roomTab_security';
+  static const parlor = 'roomTab_parlor';
+
+  /// Get semantic ID for room index.
+  static String forIndex(int index) => switch (index) {
+        0 => frontHall,
+        1 => controlRoom,
+        2 => security,
+        3 => parlor,
+        _ => 'roomTab_$index',
+      };
+}
+
+/// Navigation panel IDs.
+abstract class NavSemantics {
+  static const panel = 'nav_panel';
+  static const refresh = 'nav_refresh';
+
+  /// Generate ID for a nav item.
+  static String item(String id) => 'nav_item_$id';
+
+  /// Generate ID for a nav section.
+  static String section(String id) => 'nav_section_$id';
+}
+
+/// DataGrid component IDs.
+abstract class DataGridSemantics {
+  static const grid = 'dataGrid';
+  static const search = 'dataGrid_search';
+  static const searchClear = 'dataGrid_search_clear';
+  static const selectAll = 'dataGrid_selectAll';
+  static const loading = 'dataGrid_loading';
+  static const empty = 'dataGrid_empty';
+  static const error = 'dataGrid_error';
+  static const refresh = 'dataGrid_refresh';
+
+  /// Generate ID for a column header.
+  static String header(String columnId) => 'dataGrid_header_$columnId';
+
+  /// Generate ID for a row.
+  static String row(String itemId) => 'dataGrid_row_$itemId';
+
+  /// Generate ID for a row checkbox.
+  static String rowCheckbox(String itemId) => 'dataGrid_row_${itemId}_checkbox';
+
+  /// Generate ID for a row actions menu.
+  static String rowActions(String itemId) => 'dataGrid_row_${itemId}_actions';
+
+  /// Generate ID for a row action.
+  static String rowAction(String itemId, String actionId) =>
+      'dataGrid_row_${itemId}_action_$actionId';
+
+  /// Generate ID for a bulk action button.
+  static String bulkAction(String actionId) => 'dataGrid_bulk_$actionId';
+
+  static const bulkClear = 'dataGrid_bulk_clear';
+}
+
+/// Dialog/modal IDs.
+abstract class DialogSemantics {
+  static const confirm = 'dialog_confirm';
+  static const cancel = 'dialog_cancel';
+  static const close = 'dialog_close';
+
+  /// Generate ID for a named dialog.
+  static String named(String name) => 'dialog_$name';
+
+  /// Generate ID for a dialog action button.
+  static String action(String dialogName, String actionId) =>
+      'dialog_${dialogName}_$actionId';
+}
+
+/// Settings page IDs.
+abstract class SettingsSemantics {
+  static const themeDropdown = 'settings_theme';
+  static const defaultRoomDropdown = 'settings_defaultRoom';
+}
+
+/// Filter panel IDs.
+abstract class FilterPanelSemantics {
+  static const panel = 'filterPanel';
+  static const search = 'filterPanel_search';
+  static const searchClear = 'filterPanel_search_clear';
+  static const refresh = 'filterPanel_refresh';
+
+  /// Generate ID for a filter item.
+  static String item(String id) => 'filterPanel_item_$id';
+}
+
+/// Loading/state indicator IDs.
+abstract class StateSemantics {
+  static const authLoading = 'state_auth_loading';
+  static const authError = 'state_auth_error';
+  static const pageLoading = 'state_page_loading';
+
+  /// Generate ID for a snackbar.
+  static String snackbar(String type) => 'snackbar_$type';
+}

lib/core/semantics/semantic_widget.dart

@@ -0,0 +1,118 @@
+import 'package:flutter/material.dart';
+
+/// Wraps a widget with semantic information for accessibility and automation.
+///
+/// Usage:
+/// ```dart
+/// SemanticWidget(
+///   id: ProfileSemantics.button,
+///   label: 'Open profile menu',
+///   child: IconButton(...),
+/// )
+/// ```
+///
+/// For buttons, use `button: true`. For other interactive elements,
+/// set the appropriate semantic properties.
+class SemanticWidget extends StatelessWidget {
+  const SemanticWidget({
+    super.key,
+    required this.id,
+    required this.child,
+    this.label,
+    this.hint,
+    this.button = false,
+    this.link = false,
+    this.header = false,
+    this.textField = false,
+    this.enabled = true,
+    this.selected,
+    this.checked,
+    this.value,
+    this.excludeSemantics = false,
+  });
+
+  /// Unique identifier for this widget, exposed via [SemanticsProperties.identifier].
+  final String id;
+
+  /// The widget to wrap.
+  final Widget child;
+
+  /// Accessibility label describing the widget.
+  final String? label;
+
+  /// Hint text for screen readers.
+  final String? hint;
+
+  /// Whether this widget represents a button.
+  final bool button;
+
+  /// Whether this widget represents a link.
+  final bool link;
+
+  /// Whether this widget represents a header.
+  final bool header;
+
+  /// Whether this widget represents a text field.
+  final bool textField;
+
+  /// Whether the widget is enabled.
+  final bool enabled;
+
+  /// Whether the widget is selected (for toggle buttons, tabs).
+  final bool? selected;
+
+  /// Whether the widget is checked (for checkboxes).
+  final bool? checked;
+
+  /// Current value (for sliders, progress indicators).
+  final String? value;
+
+  /// Whether to exclude child semantics.
+  final bool excludeSemantics;
+
+  @override
+  Widget build(BuildContext context) {
+    return Semantics(
+      identifier: id,
+      label: label,
+      hint: hint,
+      button: button,
+      link: link,
+      header: header,
+      textField: textField,
+      enabled: enabled,
+      selected: selected,
+      checked: checked,
+      value: value,
+      excludeSemantics: excludeSemantics,
+      child: child,
+    );
+  }
+}
+
+/// Extension to easily wrap any widget with semantic info.
+extension SemanticExtension on Widget {
+  /// Wraps this widget with a semantic identifier.
+  Widget withSemantics({
+    required String id,
+    String? label,
+    String? hint,
+    bool button = false,
+    bool link = false,
+    bool enabled = true,
+    bool? selected,
+    bool? checked,
+  }) {
+    return SemanticWidget(
+      id: id,
+      label: label,
+      hint: hint,
+      button: button,
+      link: link,
+      enabled: enabled,
+      selected: selected,
+      checked: checked,
+      child: this,
+    );
+  }
+}

lib/features/control_room/containers/presentation/pages/containers_list_page.dart

@@ -1,9 +1,13 @@
+import 'dart:async';
+
 import 'package:flutter/material.dart' hide Container;
 import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:go_router/go_router.dart';
 import 'package:tatlock_ui/core/api/api_client.dart';
 import 'package:tatlock_ui/features/control_room/containers/presentation/providers/containers_provider.dart';
 import 'package:tatlock_ui/features/control_room/containers/presentation/widgets/container_logs_viewer.dart';
 import 'package:tatlock_ui/features/control_room/containers/presentation/widgets/container_status_badge.dart';
+import 'package:tatlock_ui/routing/url_state.dart';
 import 'package:tatlock_ui/shared/components/data_grid/adapters/core_api_source.dart';
 import 'package:tatlock_ui/shared/components/data_grid/data_grid_exports.dart';
 
@@ -101,7 +105,10 @@ class ContainerPort {
 
 /// Page displaying the list of containers using DataGrid.
 class ContainersListPage extends ConsumerStatefulWidget {
-  const ContainersListPage({super.key});
+  const ContainersListPage({super.key, this.routerState});
+
+  /// Router state for URL deep-linking.
+  final GoRouterState? routerState;
 
   @override
   ConsumerState<ContainersListPage> createState() => _ContainersListPageState();
@@ -110,10 +117,18 @@ class ContainersListPage extends ConsumerStatefulWidget {
 class _ContainersListPageState extends ConsumerState<ContainersListPage> {
   late final StateNotifierProvider<DataGridController<ContainerData>,
       DataGridState<ContainerData>> _gridProvider;
+  late PageUrlState _urlState;
+  Timer? _urlSyncTimer;
 
   @override
   void initState() {
     super.initState();
+
+    // Parse URL state
+    _urlState = PageUrlState.fromQueryParams(
+      widget.routerState?.uri.queryParameters ?? {},
+    );
+
     final dio = ref.read(coreApiClientProvider);
     final source = CoreApiDataSource<ContainerData>(
       dio: dio,
@@ -121,17 +136,68 @@ class _ContainersListPageState extends ConsumerState<ContainersListPage> {
       fromJson: ContainerData.fromJson,
     );
 
+    // Initialize grid with URL state
     _gridProvider = dataGridProvider<ContainerData>(
       source: source,
       config: _buildConfig(),
       idSelector: (c) => c.id,
+      initialSearch: _urlState.search,
+      initialSortColumnIndex: _columnIndexForId(_urlState.sortColumn),
+      initialSortDescending: _urlState.sortDescending,
     );
   }
 
+  @override
+  void dispose() {
+    _urlSyncTimer?.cancel();
+    super.dispose();
+  }
+
+  /// Find column index by column ID.
+  int? _columnIndexForId(String? columnId) {
+    if (columnId == null) return null;
+    final columns = _buildConfig().columns;
+    for (var i = 0; i < columns.length; i++) {
+      if (columns[i].id == columnId) return i;
+    }
+    return null;
+  }
+
+  /// Get column ID by index.
+  String? _columnIdForIndex(int index) {
+    final columns = _buildConfig().columns;
+    if (index >= 0 && index < columns.length) {
+      return columns[index].id;
+    }
+    return null;
+  }
+
+  /// Schedule URL sync with debounce.
+  void _scheduleUrlSync() {
+    _urlSyncTimer?.cancel();
+    _urlSyncTimer = Timer(const Duration(milliseconds: 500), _syncUrlParams);
+  }
+
+  /// Sync current state to URL.
+  void _syncUrlParams() {
+    final state = ref.read(_gridProvider);
+
+    final params = PageUrlState(
+      search: state.searchQuery.isEmpty ? null : state.searchQuery,
+      sortColumn: state.sortColumnIndex != null
+          ? _columnIdForIndex(state.sortColumnIndex!)
+          : null,
+      sortDescending: state.sortDescending,
+    ).toQueryParams();
+
+    updateBrowserUrlParams(params);
+  }
+
   DataGridConfig<ContainerData> _buildConfig() {
     return DataGridConfig<ContainerData>(
       columns: [
         DataGridColumn<ContainerData>(
+          id: 'container',
           header: 'Container',
           valueBuilder: (c) => '${c.name} ${c.image}',
           sortable: true,
@@ -140,12 +206,14 @@ class _ContainersListPageState extends ConsumerState<ContainersListPage> {
           cellBuilder: (context, c) => _ContainerCell(container: c),
         ),
         DataGridColumn<ContainerData>(
+          id: 'ports',
           header: 'Ports',
           valueBuilder: (c) => c.ports.map((p) => p.formatted).join(', '),
           width: const DataGridColumnWidth.flex(1),
           cellBuilder: (context, c) => _PortsCell(ports: c.ports),
         ),
         DataGridColumn<ContainerData>(
+          id: 'status',
           header: 'Status',
           valueBuilder: (c) => c.displayStatus,
           width: const DataGridColumnWidth.fixed(160),
@@ -211,6 +279,15 @@ class _ContainersListPageState extends ConsumerState<ContainersListPage> {
   Widget build(BuildContext context) {
     final colorScheme = Theme.of(context).colorScheme;
 
+    // Listen for grid state changes to sync URL
+    ref.listen(_gridProvider, (previous, next) {
+      if (previous?.searchQuery != next.searchQuery ||
+          previous?.sortColumnIndex != next.sortColumnIndex ||
+          previous?.sortDescending != next.sortDescending) {
+        _scheduleUrlSync();
+      }
+    });
+
     // Listen for container action results to show snackbars
     ref.listen<AsyncValue<void>>(containerActionsProvider, (previous, next) {
       if (previous?.isLoading == true && !next.isLoading) {

lib/features/control_room/npm/presentation/pages/proxy_hosts_page.dart

@@ -1,8 +1,12 @@
+import 'dart:async';
+
 import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:go_router/go_router.dart';
 import 'package:tatlock_ui/core/api/api_client.dart';
 import 'package:tatlock_ui/features/control_room/npm/presentation/pages/proxy_host_page.dart';
 import 'package:tatlock_ui/features/control_room/npm/presentation/providers/proxy_hosts_provider.dart';
+import 'package:tatlock_ui/routing/url_state.dart';
 import 'package:tatlock_ui/shared/components/data_grid/adapters/core_api_source.dart';
 import 'package:tatlock_ui/shared/components/data_grid/data_grid_exports.dart';
 
@@ -33,7 +37,10 @@ class DomainData {
 
 /// Page displaying the list of proxy hosts (domains) from NPM.
 class ProxyHostsPage extends ConsumerStatefulWidget {
-  const ProxyHostsPage({super.key});
+  const ProxyHostsPage({super.key, this.routerState});
+
+  /// Router state for URL deep-linking.
+  final GoRouterState? routerState;
 
   @override
   ConsumerState<ProxyHostsPage> createState() => _ProxyHostsPageState();
@@ -42,10 +49,18 @@ class ProxyHostsPage extends ConsumerStatefulWidget {
 class _ProxyHostsPageState extends ConsumerState<ProxyHostsPage> {
   late final StateNotifierProvider<DataGridController<DomainData>,
       DataGridState<DomainData>> _gridProvider;
+  late PageUrlState _urlState;
+  Timer? _urlSyncTimer;
 
   @override
   void initState() {
     super.initState();
+
+    // Parse URL state
+    _urlState = PageUrlState.fromQueryParams(
+      widget.routerState?.uri.queryParameters ?? {},
+    );
+
     final dio = ref.read(coreApiClientProvider);
     final source = CoreApiDataSource<DomainData>(
       dio: dio,
@@ -53,17 +68,80 @@ class _ProxyHostsPageState extends ConsumerState<ProxyHostsPage> {
       fromJson: DomainData.fromJson,
     );
 
+    // Initialize grid with URL state
     _gridProvider = dataGridProvider<DomainData>(
       source: source,
       config: _buildConfig(),
       idSelector: (d) => d.proxyHostId.toString(),
+      initialSearch: _urlState.search,
+      initialSortColumnIndex: _columnIndexForId(_urlState.sortColumn),
+      initialSortDescending: _urlState.sortDescending,
     );
+
+    // Open document from URL if id present
+    if (_urlState.id != null) {
+      final id = int.tryParse(_urlState.id!);
+      if (id != null) {
+        WidgetsBinding.instance.addPostFrameCallback((_) {
+          ref.read(selectedProxyHostProvider.notifier).select(id);
+        });
+      }
+    }
+  }
+
+  @override
+  void dispose() {
+    _urlSyncTimer?.cancel();
+    super.dispose();
+  }
+
+  /// Find column index by column ID.
+  int? _columnIndexForId(String? columnId) {
+    if (columnId == null) return null;
+    final columns = _buildConfig().columns;
+    for (var i = 0; i < columns.length; i++) {
+      if (columns[i].id == columnId) return i;
+    }
+    return null;
+  }
+
+  /// Get column ID by index.
+  String? _columnIdForIndex(int index) {
+    final columns = _buildConfig().columns;
+    if (index >= 0 && index < columns.length) {
+      return columns[index].id;
+    }
+    return null;
+  }
+
+  /// Schedule URL sync with debounce.
+  void _scheduleUrlSync() {
+    _urlSyncTimer?.cancel();
+    _urlSyncTimer = Timer(const Duration(milliseconds: 500), _syncUrlParams);
+  }
+
+  /// Sync current state to URL.
+  void _syncUrlParams() {
+    final state = ref.read(_gridProvider);
+    final selectedId = ref.read(selectedProxyHostProvider);
+
+    final params = PageUrlState(
+      id: selectedId?.toString(),
+      search: state.searchQuery.isEmpty ? null : state.searchQuery,
+      sortColumn: state.sortColumnIndex != null
+          ? _columnIdForIndex(state.sortColumnIndex!)
+          : null,
+      sortDescending: state.sortDescending,
+    ).toQueryParams();
+
+    updateBrowserUrlParams(params);
   }
 
   DataGridConfig<DomainData> _buildConfig() {
     return DataGridConfig<DomainData>(
       columns: [
         DataGridColumn<DomainData>(
+          id: 'domain',
           header: 'Domain',
           valueBuilder: (d) => d.domain,
           sortable: true,
@@ -72,12 +150,14 @@ class _ProxyHostsPageState extends ConsumerState<ProxyHostsPage> {
           cellBuilder: (context, d) => _DomainCell(domain: d),
         ),
         DataGridColumn<DomainData>(
+          id: 'service',
           header: 'Service',
           valueBuilder: (d) => d.service,
           width: const DataGridColumnWidth.flex(1),
           cellBuilder: (context, d) => _ServiceCell(service: d.service),
         ),
         DataGridColumn<DomainData>(
+          id: 'ssl',
           header: 'SSL',
           valueBuilder: (d) => d.sslEnabled ? 'Enabled' : 'Disabled',
           width: const DataGridColumnWidth.fixed(100),
@@ -101,6 +181,8 @@ class _ProxyHostsPageState extends ConsumerState<ProxyHostsPage> {
 
   void _viewDomain(DomainData domain) {
     ref.read(selectedProxyHostProvider.notifier).select(domain.proxyHostId);
+    // Navigate with id to enable back button
+    context.go('/control-room/proxy-hosts?id=${domain.proxyHostId}');
   }
 
   void _createNew() {
@@ -112,6 +194,15 @@ class _ProxyHostsPageState extends ConsumerState<ProxyHostsPage> {
     final selectedId = ref.watch(selectedProxyHostProvider);
     final isCreating = ref.watch(creatingProxyHostProvider);
 
+    // Listen for grid state changes to sync URL
+    ref.listen(_gridProvider, (previous, next) {
+      if (previous?.searchQuery != next.searchQuery ||
+          previous?.sortColumnIndex != next.sortColumnIndex ||
+          previous?.sortDescending != next.sortDescending) {
+        _scheduleUrlSync();
+      }
+    });
+
     // Show create page if creating new
     if (isCreating) {
       return ProxyHostPage.create(
@@ -128,6 +219,8 @@ class _ProxyHostsPageState extends ConsumerState<ProxyHostsPage> {
         proxyHostId: selectedId,
         onClose: () {
           ref.read(selectedProxyHostProvider.notifier).clear();
+          // Clear id from URL
+          context.go('/control-room/proxy-hosts');
           ref.read(_gridProvider.notifier).refresh();
         },
       );

lib/features/control_room/presentation/pages/control_room_page.dart

@@ -17,11 +17,15 @@ class ControlRoomPage extends ConsumerWidget {
   const ControlRoomPage({
     super.key,
     this.nav = ControlRoomNav.containers,
+    this.routerState,
   });
 
   /// The current nav item to display.
   final ControlRoomNav nav;
 
+  /// Router state for URL deep-linking (query params).
+  final GoRouterState? routerState;
+
   @override
   Widget build(BuildContext context, WidgetRef ref) {
     final colorScheme = Theme.of(context).colorScheme;
@@ -53,7 +57,7 @@ class ControlRoomPage extends ConsumerWidget {
           ),
           // Section content
           Expanded(
-            child: _SectionContent(nav: nav),
+            child: _SectionContent(nav: nav, routerState: routerState),
           ),
         ],
       ),
@@ -63,15 +67,16 @@ class ControlRoomPage extends ConsumerWidget {
 
 /// Renders content for the selected nav item.
 class _SectionContent extends ConsumerWidget {
-  const _SectionContent({required this.nav});
+  const _SectionContent({required this.nav, this.routerState});
 
   final ControlRoomNav nav;
+  final GoRouterState? routerState;
 
   @override
   Widget build(BuildContext context, WidgetRef ref) {
     return switch (nav) {
-      ControlRoomNav.containers => const _ContainersSection(),
-      ControlRoomNav.proxyHosts => const ProxyHostsPage(),
+      ControlRoomNav.containers => _ContainersSection(routerState: routerState),
+      ControlRoomNav.proxyHosts => ProxyHostsPage(routerState: routerState),
       _ => _PlaceholderSection(nav: nav),
     };
   }
@@ -119,7 +124,9 @@ class _PlaceholderSection extends StatelessWidget {
 
 /// Containers section with optional stack filter.
 class _ContainersSection extends ConsumerWidget {
-  const _ContainersSection();
+  const _ContainersSection({this.routerState});
+
+  final GoRouterState? routerState;
 
   @override
   Widget build(BuildContext context, WidgetRef ref) {
@@ -129,7 +136,7 @@ class _ContainersSection extends ConsumerWidget {
     return Row(
       children: [
         // Stacks filter panel
-        const _StacksFilterPanel(),
+        _StacksFilterPanel(routerState: routerState),
         // Divider
         VerticalDivider(
           width: 1,
@@ -139,7 +146,7 @@ class _ContainersSection extends ConsumerWidget {
         // Main content - containers list or stack detail
         Expanded(
           child: selectedStack == null
-              ? const ContainersListPage()
+              ? ContainersListPage(routerState: routerState)
               : StackDetailPage(stackId: selectedStack),
         ),
       ],
@@ -149,7 +156,9 @@ class _ContainersSection extends ConsumerWidget {
 
 /// Stacks filter panel for Containers section (includes "All Containers" option).
 class _StacksFilterPanel extends ConsumerWidget {
-  const _StacksFilterPanel();
+  const _StacksFilterPanel({this.routerState});
+
+  final GoRouterState? routerState;
 
   @override
   Widget build(BuildContext context, WidgetRef ref) {
@@ -207,6 +216,7 @@ class _StacksFilterPanel extends ConsumerWidget {
               data: (stacks) => _StacksList(
                 stacks: stacks,
                 selectedStackId: selectedStack,
+                routerState: routerState,
                 onStackSelected: (id) =>
                     ref.read(selectedStackProvider.notifier).select(id),
                 onStackAction: (id, action) =>
@@ -281,12 +291,14 @@ class _StacksList extends StatefulWidget {
     required this.selectedStackId,
     required this.onStackSelected,
     required this.onStackAction,
+    this.routerState,
   });
 
   final List<Stack> stacks;
   final String? selectedStackId;
   final void Function(String) onStackSelected;
   final void Function(String, String) onStackAction;
+  final GoRouterState? routerState;
 
   @override
   State<_StacksList> createState() => _StacksListState();

lib/features/control_room/router.dart

@@ -63,8 +63,11 @@ List<RouteBase> controlRoomRoutes() {
       GoRoute(
         path: nav.path,
         name: 'controlRoom${_capitalize(nav.id.replaceAll('-', '_'))}',
-        pageBuilder: (context, state) =>
-            noTransitionPage(context, state, ControlRoomPage(nav: nav)),
+        pageBuilder: (context, state) => noTransitionPage(
+          context,
+          state,
+          ControlRoomPage(nav: nav, routerState: state),
+        ),
       ),
   ];
 }

lib/features/security/groups/groups_list_page.dart

@@ -1,6 +1,10 @@
+import 'dart:async';
+
 import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:go_router/go_router.dart';
 import 'package:tatlock_ui/core/api/api_client.dart';
+import 'package:tatlock_ui/routing/url_state.dart';
 import 'package:tatlock_ui/shared/components/data_grid/adapters/core_api_source.dart';
 import 'package:tatlock_ui/shared/components/data_grid/data_grid_exports.dart';
 
@@ -31,7 +35,10 @@ class GroupData {
 
 /// Groups list page using the shared DataGrid component.
 class GroupsListPage extends ConsumerStatefulWidget {
-  const GroupsListPage({super.key});
+  const GroupsListPage({super.key, this.routerState});
+
+  /// Router state for URL deep-linking.
+  final GoRouterState? routerState;
 
   @override
   ConsumerState<GroupsListPage> createState() => _GroupsListPageState();
@@ -40,11 +47,19 @@ class GroupsListPage extends ConsumerStatefulWidget {
 class _GroupsListPageState extends ConsumerState<GroupsListPage> {
   late final StateNotifierProvider<DataGridController<GroupData>,
       DataGridState<GroupData>> _gridProvider;
+  late PageUrlState _urlState;
+  Timer? _urlSyncTimer;
   bool _isSyncing = false;
 
   @override
   void initState() {
     super.initState();
+
+    // Parse URL state
+    _urlState = PageUrlState.fromQueryParams(
+      widget.routerState?.uri.queryParameters ?? {},
+    );
+
     // Create provider in initState to ensure stable reference
     final dio = ref.read(coreApiClientProvider);
     final source = CoreApiDataSource<GroupData>(
@@ -53,13 +68,63 @@ class _GroupsListPageState extends ConsumerState<GroupsListPage> {
       fromJson: GroupData.fromJson,
     );
 
+    // Initialize grid with URL state
     _gridProvider = dataGridProvider<GroupData>(
       source: source,
       config: _buildConfig(),
       idSelector: (g) => g.id,
+      initialSearch: _urlState.search,
+      initialSortColumnIndex: _columnIndexForId(_urlState.sortColumn),
+      initialSortDescending: _urlState.sortDescending,
     );
   }
 
+  @override
+  void dispose() {
+    _urlSyncTimer?.cancel();
+    super.dispose();
+  }
+
+  /// Find column index by column ID.
+  int? _columnIndexForId(String? columnId) {
+    if (columnId == null) return null;
+    final columns = _buildConfig().columns;
+    for (var i = 0; i < columns.length; i++) {
+      if (columns[i].id == columnId) return i;
+    }
+    return null;
+  }
+
+  /// Get column ID by index.
+  String? _columnIdForIndex(int index) {
+    final columns = _buildConfig().columns;
+    if (index >= 0 && index < columns.length) {
+      return columns[index].id;
+    }
+    return null;
+  }
+
+  /// Schedule URL sync with debounce.
+  void _scheduleUrlSync() {
+    _urlSyncTimer?.cancel();
+    _urlSyncTimer = Timer(const Duration(milliseconds: 500), _syncUrlParams);
+  }
+
+  /// Sync current state to URL.
+  void _syncUrlParams() {
+    final state = ref.read(_gridProvider);
+
+    final params = PageUrlState(
+      search: state.searchQuery.isEmpty ? null : state.searchQuery,
+      sortColumn: state.sortColumnIndex != null
+          ? _columnIdForIndex(state.sortColumnIndex!)
+          : null,
+      sortDescending: state.sortDescending,
+    ).toQueryParams();
+
+    updateBrowserUrlParams(params);
+  }
+
   Future<void> _syncFromAuthentik() async {
     if (_isSyncing) return;
     setState(() => _isSyncing = true);
@@ -96,6 +161,7 @@ class _GroupsListPageState extends ConsumerState<GroupsListPage> {
     return DataGridConfig<GroupData>(
       columns: [
         DataGridColumn<GroupData>(
+          id: 'name',
           header: 'Name',
           valueBuilder: (g) => g.name,
           sortable: true,
@@ -103,18 +169,21 @@ class _GroupsListPageState extends ConsumerState<GroupsListPage> {
           width: const DataGridColumnWidth.flex(2),
         ),
         DataGridColumn<GroupData>(
+          id: 'members',
           header: 'Members',
           valueBuilder: (g) => g.memberCount.toString(),
           width: const DataGridColumnWidth.fixed(100),
           alignment: DataGridColumnAlignment.end,
         ),
         DataGridColumn<GroupData>(
+          id: 'type',
           header: 'Type',
           valueBuilder: (g) => g.isSuperuser ? 'Superuser' : 'Standard',
           cellBuilder: (context, g) => _GroupTypeBadge(isSuperuser: g.isSuperuser),
           width: const DataGridColumnWidth.fixed(120),
         ),
         DataGridColumn<GroupData>(
+          id: 'parent',
           header: 'Parent',
           valueBuilder: (g) => g.parentName ?? '-',
           width: const DataGridColumnWidth.flex(1),
@@ -129,6 +198,15 @@ class _GroupsListPageState extends ConsumerState<GroupsListPage> {
 
   @override
   Widget build(BuildContext context) {
+    // Listen for grid state changes to sync URL
+    ref.listen(_gridProvider, (previous, next) {
+      if (previous?.searchQuery != next.searchQuery ||
+          previous?.sortColumnIndex != next.sortColumnIndex ||
+          previous?.sortDescending != next.sortDescending) {
+        _scheduleUrlSync();
+      }
+    });
+
     return DataGrid<GroupData>(
       provider: _gridProvider,
       config: _buildConfig(),

lib/features/security/presentation/pages/security_page.dart

@@ -11,11 +11,15 @@ class SecurityPage extends ConsumerWidget {
   const SecurityPage({
     super.key,
     this.nav = SecurityNav.users,
+    this.routerState,
   });
 
   /// The current nav item to display.
   final SecurityNav nav;
 
+  /// Router state for URL deep-linking (query params).
+  final GoRouterState? routerState;
+
   @override
   Widget build(BuildContext context, WidgetRef ref) {
     final colorScheme = Theme.of(context).colorScheme;
@@ -45,7 +49,7 @@ class SecurityPage extends ConsumerWidget {
           ),
           // Section content
           Expanded(
-            child: _SectionContent(nav: nav),
+            child: _SectionContent(nav: nav, routerState: routerState),
           ),
         ],
       ),
@@ -55,17 +59,18 @@ class SecurityPage extends ConsumerWidget {
 
 /// Renders content for the selected nav item.
 class _SectionContent extends StatelessWidget {
-  const _SectionContent({required this.nav});
+  const _SectionContent({required this.nav, this.routerState});
 
   final SecurityNav nav;
+  final GoRouterState? routerState;
 
   @override
   Widget build(BuildContext context) {
     switch (nav) {
       case SecurityNav.users:
-        return const UsersListPage();
+        return UsersListPage(routerState: routerState);
       case SecurityNav.groups:
-        return const GroupsListPage();
+        return GroupsListPage(routerState: routerState);
       default:
         return _PlaceholderSection(nav: nav);
     }

lib/features/security/router.dart

@@ -61,8 +61,11 @@ List<RouteBase> securityRoutes() {
       GoRoute(
         path: nav.path,
         name: 'security${_capitalize(nav.id.replaceAll('-', '_'))}',
-        pageBuilder: (context, state) =>
-            noTransitionPage(context, state, SecurityPage(nav: nav)),
+        pageBuilder: (context, state) => noTransitionPage(
+          context,
+          state,
+          SecurityPage(nav: nav, routerState: state),
+        ),
       ),
   ];
 }

lib/features/security/users/users_list_page.dart

@@ -1,6 +1,10 @@
+import 'dart:async';
+
 import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:go_router/go_router.dart';
 import 'package:tatlock_ui/core/api/api_client.dart';
+import 'package:tatlock_ui/routing/url_state.dart';
 import 'package:tatlock_ui/shared/components/data_grid/adapters/core_api_source.dart';
 import 'package:tatlock_ui/shared/components/data_grid/data_grid_exports.dart';
 
@@ -61,7 +65,10 @@ class UserData {
 
 /// Users list page using the shared DataGrid component.
 class UsersListPage extends ConsumerStatefulWidget {
-  const UsersListPage({super.key});
+  const UsersListPage({super.key, this.routerState});
+
+  /// Router state for URL deep-linking.
+  final GoRouterState? routerState;
 
   @override
   ConsumerState<UsersListPage> createState() => _UsersListPageState();
@@ -70,11 +77,19 @@ class UsersListPage extends ConsumerStatefulWidget {
 class _UsersListPageState extends ConsumerState<UsersListPage> {
   late final StateNotifierProvider<DataGridController<UserData>,
       DataGridState<UserData>> _gridProvider;
+  late PageUrlState _urlState;
+  Timer? _urlSyncTimer;
   bool _isSyncing = false;
 
   @override
   void initState() {
     super.initState();
+
+    // Parse URL state
+    _urlState = PageUrlState.fromQueryParams(
+      widget.routerState?.uri.queryParameters ?? {},
+    );
+
     final dio = ref.read(coreApiClientProvider);
     final source = CoreApiDataSource<UserData>(
       dio: dio,
@@ -82,13 +97,63 @@ class _UsersListPageState extends ConsumerState<UsersListPage> {
       fromJson: UserData.fromJson,
     );
 
+    // Initialize grid with URL state
     _gridProvider = dataGridProvider<UserData>(
       source: source,
       config: _buildConfig(),
       idSelector: (u) => u.id,
+      initialSearch: _urlState.search,
+      initialSortColumnIndex: _columnIndexForId(_urlState.sortColumn),
+      initialSortDescending: _urlState.sortDescending,
     );
   }
 
+  @override
+  void dispose() {
+    _urlSyncTimer?.cancel();
+    super.dispose();
+  }
+
+  /// Find column index by column ID.
+  int? _columnIndexForId(String? columnId) {
+    if (columnId == null) return null;
+    final columns = _buildConfig().columns;
+    for (var i = 0; i < columns.length; i++) {
+      if (columns[i].id == columnId) return i;
+    }
+    return null;
+  }
+
+  /// Get column ID by index.
+  String? _columnIdForIndex(int index) {
+    final columns = _buildConfig().columns;
+    if (index >= 0 && index < columns.length) {
+      return columns[index].id;
+    }
+    return null;
+  }
+
+  /// Schedule URL sync with debounce.
+  void _scheduleUrlSync() {
+    _urlSyncTimer?.cancel();
+    _urlSyncTimer = Timer(const Duration(milliseconds: 500), _syncUrlParams);
+  }
+
+  /// Sync current state to URL.
+  void _syncUrlParams() {
+    final state = ref.read(_gridProvider);
+
+    final params = PageUrlState(
+      search: state.searchQuery.isEmpty ? null : state.searchQuery,
+      sortColumn: state.sortColumnIndex != null
+          ? _columnIdForIndex(state.sortColumnIndex!)
+          : null,
+      sortDescending: state.sortDescending,
+    ).toQueryParams();
+
+    updateBrowserUrlParams(params);
+  }
+
   Future<void> _syncFromAuthentik() async {
     if (_isSyncing) return;
     setState(() => _isSyncing = true);
@@ -125,6 +190,7 @@ class _UsersListPageState extends ConsumerState<UsersListPage> {
     return DataGridConfig<UserData>(
       columns: [
         DataGridColumn<UserData>(
+          id: 'user',
           header: 'User',
           valueBuilder: (u) => u.name,
           sortable: true,
@@ -133,12 +199,14 @@ class _UsersListPageState extends ConsumerState<UsersListPage> {
           cellBuilder: (context, u) => _UserCell(user: u),
         ),
         DataGridColumn<UserData>(
+          id: 'roles',
           header: 'Roles',
           valueBuilder: (u) => u.roles.join(', '),
           width: const DataGridColumnWidth.flex(1),
           cellBuilder: (context, u) => _RolesCell(roles: u.roles),
         ),
         DataGridColumn<UserData>(
+          id: 'lastLogin',
           header: 'Last Login',
           valueBuilder: (u) => u.lastLoginFormatted,
           width: const DataGridColumnWidth.fixed(120),
@@ -154,6 +222,15 @@ class _UsersListPageState extends ConsumerState<UsersListPage> {
 
   @override
   Widget build(BuildContext context) {
+    // Listen for grid state changes to sync URL
+    ref.listen(_gridProvider, (previous, next) {
+      if (previous?.searchQuery != next.searchQuery ||
+          previous?.sortColumnIndex != next.sortColumnIndex ||
+          previous?.sortDescending != next.sortDescending) {
+        _scheduleUrlSync();
+      }
+    });
+
     return DataGrid<UserData>(
       provider: _gridProvider,
       config: _buildConfig(),

lib/main.dart

@@ -1,6 +1,8 @@
 import 'dart:developer' as developer;
 
+import 'package:flutter/foundation.dart' show kIsWeb;
 import 'package:flutter/material.dart';
+import 'package:flutter/rendering.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 
 import 'app.dart';
@@ -11,6 +13,12 @@ import 'version.g.dart';
 void main() async {
   WidgetsFlutterBinding.ensureInitialized();
 
+  // Enable semantics tree on web for accessibility and automation tools.
+  // This exposes widget identifiers to browser automation (Puppeteer, etc.)
+  if (kIsWeb) {
+    SemanticsBinding.instance.ensureSemantics();
+  }
+
   // Use path-based URLs on web (no-op on mobile/desktop)
   configureUrlStrategy();
 

lib/routing/url_state.dart

@@ -0,0 +1,98 @@
+import 'package:flutter/foundation.dart' show kIsWeb;
+
+// Conditional import for web-only functionality
+import 'url_state_stub.dart' if (dart.library.js_interop) 'url_state_web.dart'
+    as platform;
+
+/// Parses and builds URL query parameters for page state.
+///
+/// Used to enable deep-linking for DataGrid and filter panel state.
+/// Query params are read once on page load and updated via browser
+/// replaceState to avoid GoRouter rebuild loops.
+class PageUrlState {
+  const PageUrlState({
+    this.id,
+    this.filter,
+    this.search,
+    this.sortColumn,
+    this.sortDescending = false,
+  });
+
+  /// Opened document ID (view/edit mode).
+  final String? id;
+
+  /// Filter panel search value.
+  final String? filter;
+
+  /// DataGrid search value.
+  final String? search;
+
+  /// Column ID for sorting.
+  final String? sortColumn;
+
+  /// Sort direction (true = descending).
+  final bool sortDescending;
+
+  /// Parse from query parameters map.
+  factory PageUrlState.fromQueryParams(Map<String, String> params) {
+    return PageUrlState(
+      id: params['id'],
+      filter: params['filter'],
+      search: params['search'],
+      sortColumn: params['sort'],
+      sortDescending: params['order'] == 'desc',
+    );
+  }
+
+  /// Convert to query parameter map (omits empty/default values).
+  Map<String, String> toQueryParams() {
+    return {
+      if (id != null && id!.isNotEmpty) 'id': id!,
+      if (filter != null && filter!.isNotEmpty) 'filter': filter!,
+      if (search != null && search!.isNotEmpty) 'search': search!,
+      if (sortColumn != null && sortColumn!.isNotEmpty) 'sort': sortColumn!,
+      if (sortDescending) 'order': 'desc',
+    };
+  }
+
+  /// Create a copy with modified values.
+  PageUrlState copyWith({
+    String? id,
+    String? filter,
+    String? search,
+    String? sortColumn,
+    bool? sortDescending,
+    bool clearId = false,
+  }) {
+    return PageUrlState(
+      id: clearId ? null : (id ?? this.id),
+      filter: filter ?? this.filter,
+      search: search ?? this.search,
+      sortColumn: sortColumn ?? this.sortColumn,
+      sortDescending: sortDescending ?? this.sortDescending,
+    );
+  }
+
+  /// Whether any state is present.
+  bool get isEmpty =>
+      id == null &&
+      (filter == null || filter!.isEmpty) &&
+      (search == null || search!.isEmpty) &&
+      sortColumn == null;
+
+  @override
+  String toString() =>
+      'PageUrlState(id: $id, filter: $filter, search: $search, '
+      'sort: $sortColumn, desc: $sortDescending)';
+}
+
+/// Updates browser URL with query parameters without triggering navigation.
+///
+/// Uses browser's replaceState API on web, no-op on other platforms.
+/// This allows the URL to stay in sync for bookmarking/sharing without
+/// causing Flutter to rebuild.
+void updateBrowserUrlParams(Map<String, String> params) {
+  if (kIsWeb) {
+    platform.updateBrowserUrlParams(params);
+  }
+}

lib/routing/url_state_stub.dart

@@ -0,0 +1,4 @@
+/// Stub implementation for non-web platforms.
+void updateBrowserUrlParams(Map<String, String> params) {
+  // No-op on non-web platforms
+}

lib/routing/url_state_web.dart

@@ -0,0 +1,13 @@
+import 'package:web/web.dart' as web;
+
+/// Updates browser URL with query parameters without triggering navigation.
+///
+/// Uses browser's replaceState API to update the URL bar for bookmarking
+/// without causing Flutter/GoRouter to rebuild the page.
+void updateBrowserUrlParams(Map<String, String> params) {
+  final currentUri = Uri.parse(web.window.location.href);
+  final newUri = currentUri.replace(
+    queryParameters: params.isEmpty ? null : params,
+  );
+  web.window.history.replaceState(null, '', newUri.toString());
+}

lib/shared/components/data_grid/data_grid_column.dart

@@ -45,6 +45,7 @@ enum DataGridColumnAlignment {
 /// Column definition for DataGrid.
 class DataGridColumn<T> {
   const DataGridColumn({
+    required this.id,
     required this.header,
     required this.valueBuilder,
     this.cellBuilder,
@@ -58,6 +59,9 @@ class DataGridColumn<T> {
     this.tooltip,
   });
 
+  /// Unique identifier for this column (used in URL deep-linking).
+  final String id;
+
   /// Column header text.
   final String header;
 

lib/shared/components/data_grid/data_grid_provider.dart

@@ -15,9 +15,15 @@ class DataGridController<T> extends StateNotifier<DataGridState<T>> {
     required this.source,
     required this.config,
     required this.idSelector,
+    String? initialSearch,
+    int? initialSortColumnIndex,
+    bool? initialSortDescending,
   }) : super(DataGridState<T>(
-          sortColumnIndex: config.defaultSortColumn,
-          sortDescending: config.defaultSortDescending,
+          searchQuery: initialSearch ?? '',
+          sortColumnIndex:
+              initialSortColumnIndex ?? config.defaultSortColumn,
+          sortDescending:
+              initialSortDescending ?? config.defaultSortDescending,
         )) {
     // Initial load
     _load();
@@ -29,8 +35,13 @@ class DataGridController<T> extends StateNotifier<DataGridState<T>> {
   /// Grid configuration.
   final DataGridConfig<T> config;
 
-  /// Function to extract unique ID from an item.
-  final Object Function(T item) idSelector;
+  /// Function to extract unique ID from an item (used for selection and URL deep-linking).
+  ///
+  /// Returns a unique string identifier for each row. Can be:
+  /// - A simple ID field: `(item) => item.id.toString()`
+  /// - A combination of fields: `(item) => '${item.name}_${item.type}'`
+  /// - Any unique identifier suitable for URLs
+  final String Function(T item) idSelector;
 
   /// Debounce timer for search.
   Timer? _searchDebounce;
@@ -185,7 +196,7 @@ class DataGridController<T> extends StateNotifier<DataGridState<T>> {
     if (!config.rowsSelectable) return;
 
     final id = idSelector(item);
-    final newSelection = Set<Object>.from(state.selectedIds);
+    final newSelection = Set<String>.from(state.selectedIds);
 
     if (newSelection.contains(id)) {
       newSelection.remove(id);
@@ -287,17 +298,35 @@ class DataGridController<T> extends StateNotifier<DataGridState<T>> {
 ///   idSelector: (c) => c.id,
 /// );
 /// ```
+///
+/// For URL deep-linking, pass initial state from URL params:
+/// ```dart
+/// final gridProvider = dataGridProvider<Container>(
+///   source: source,
+///   config: config,
+///   idSelector: (c) => c.id,
+///   initialSearch: urlState.search,
+///   initialSortColumnIndex: _columnIndexForId(urlState.sortColumn),
+///   initialSortDescending: urlState.sortDescending,
+/// );
+/// ```
 StateNotifierProvider<DataGridController<T>, DataGridState<T>>
     dataGridProvider<T>({
   required DataGridSource<T> source,
   required DataGridConfig<T> config,
-  required Object Function(T) idSelector,
+  required String Function(T) idSelector,
+  String? initialSearch,
+  int? initialSortColumnIndex,
+  bool? initialSortDescending,
 }) {
   return StateNotifierProvider<DataGridController<T>, DataGridState<T>>(
     (ref) => DataGridController<T>(
       source: source,
       config: config,
       idSelector: idSelector,
+      initialSearch: initialSearch,
+      initialSortColumnIndex: initialSortColumnIndex,
+      initialSortDescending: initialSortDescending,
     ),
   );
 }

lib/shared/components/data_grid/data_grid_state.dart

@@ -31,7 +31,7 @@ sealed class DataGridState<T> with _$DataGridState<T> {
     @Default(false) bool sortDescending,
 
     /// Currently selected item IDs (if selectable).
-    @Default({}) Set<Object> selectedIds,
+    @Default({}) Set<String> selectedIds,
 
     /// Current page (for paginated mode).
     @Default(0) int currentPage,

lib/shared/layouts/widgets/nav_panel.dart

@@ -1,4 +1,5 @@
 import 'package:flutter/material.dart';
+import 'package:tatlock_ui/core/semantics/semantic_ids.dart';
 
 import 'panel_header.dart';
 
@@ -199,17 +200,22 @@ class _NavTile extends StatelessWidget {
     final colorScheme = Theme.of(context).colorScheme;
     final textTheme = Theme.of(context).textTheme;
 
-    return Padding(
-      padding: const EdgeInsets.symmetric(horizontal: 8, vertical: 2),
-      child: Material(
-        color: isSelected
-            ? colorScheme.primaryContainer.withValues(alpha: 0.4)
-            : Colors.transparent,
-        borderRadius: BorderRadius.circular(8),
-        child: InkWell(
-          onTap: onTap,
+    return Semantics(
+      identifier: NavSemantics.item(item.id),
+      label: item.label,
+      button: true,
+      selected: isSelected,
+      child: Padding(
+        padding: const EdgeInsets.symmetric(horizontal: 8, vertical: 2),
+        child: Material(
+          color: isSelected
+              ? colorScheme.primaryContainer.withValues(alpha: 0.4)
+              : Colors.transparent,
           borderRadius: BorderRadius.circular(8),
-          child: Padding(
+          child: InkWell(
+            onTap: onTap,
+            borderRadius: BorderRadius.circular(8),
+            child: Padding(
             padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 10),
             child: Row(
               children: [
@@ -258,6 +264,7 @@ class _NavTile extends StatelessWidget {
           ),
         ),
       ),
+      ),
     );
   }
 }

lib/shared/layouts/widgets/profile_dropdown.dart

@@ -4,6 +4,7 @@ import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:go_router/go_router.dart';
 import 'package:tatlock_ui/core/auth/auth_provider.dart';
+import 'package:tatlock_ui/core/semantics/semantic_ids.dart';
 import 'package:tatlock_ui/core/theme/theme_provider.dart';
 import 'package:tatlock_ui/routing/app_router.dart';
 
@@ -20,189 +21,209 @@ class ProfileDropdown extends ConsumerWidget {
     final colorScheme = Theme.of(context).colorScheme;
 
     return authState.when(
-      data: (auth) => PopupMenuButton<String>(
-        offset: const Offset(0, 48),
-        shape: RoundedRectangleBorder(
-          borderRadius: BorderRadius.circular(8),
-        ),
-        child: Tooltip(
-          message: auth.isAuthenticated ? auth.userName ?? 'User' : 'Guest',
-          child: CircleAvatar(
-            radius: 18,
-            backgroundColor: colorScheme.primaryContainer,
-            child: auth.isAuthenticated
-                ? Text(
-                    _getInitials(auth.userName),
-                    style: TextStyle(
+      data: (auth) => Semantics(
+        identifier: ProfileSemantics.button,
+        label: 'Profile menu',
+        button: true,
+        child: PopupMenuButton<String>(
+          offset: const Offset(0, 48),
+          shape: RoundedRectangleBorder(
+            borderRadius: BorderRadius.circular(8),
+          ),
+          child: Tooltip(
+            message: auth.isAuthenticated ? auth.userName ?? 'User' : 'Guest',
+            child: CircleAvatar(
+              radius: 18,
+              backgroundColor: colorScheme.primaryContainer,
+              child: auth.isAuthenticated
+                  ? Text(
+                      _getInitials(auth.userName),
+                      style: TextStyle(
+                        color: colorScheme.onPrimaryContainer,
+                        fontWeight: FontWeight.w500,
+                      ),
+                    )
+                  : Icon(
+                      Icons.person_outline,
+                      size: 20,
                       color: colorScheme.onPrimaryContainer,
-                      fontWeight: FontWeight.w500,
                     ),
-                  )
-                : Icon(
-                    Icons.person_outline,
-                    size: 20,
-                    color: colorScheme.onPrimaryContainer,
-                  ),
-          ),
-        ),
-        itemBuilder: (context) => [
-          // User info header (non-selectable)
-          PopupMenuItem<String>(
-            enabled: false,
-            child: Column(
-              crossAxisAlignment: CrossAxisAlignment.start,
-              children: [
-                Text(
-                  auth.isAuthenticated ? auth.userName ?? 'User' : 'Guest',
-                  style: Theme.of(context).textTheme.titleSmall,
-                ),
-                if (auth.userEmail != null)
-                  Text(
-                    auth.userEmail!,
-                    style: Theme.of(context).textTheme.bodySmall?.copyWith(
-                          color: colorScheme.onSurfaceVariant,
-                        ),
-                  ),
-              ],
             ),
           ),
-          const PopupMenuDivider(),
-
-          // Settings
-          const PopupMenuItem<String>(
-            value: 'settings',
-            child: Row(
-              children: [
-                Icon(Icons.settings_outlined, size: 20),
-                SizedBox(width: 12),
-                Text('Settings'),
-              ],
-            ),
-          ),
-
-          // Theme submenu header
-          PopupMenuItem<String>(
-            enabled: false,
-            height: 32,
-            child: Text(
-              'THEME',
-              style: Theme.of(context).textTheme.labelSmall?.copyWith(
-                    color: colorScheme.onSurfaceVariant,
-                    letterSpacing: 0.5,
-                  ),
-            ),
-          ),
-
-          // Theme: System
-          PopupMenuItem<String>(
-            value: 'theme_system',
-            height: 40,
-            child: Row(
-              children: [
-                Icon(
-                  Icons.brightness_auto,
-                  size: 18,
-                  color: currentTheme == ThemeSetting.system
-                      ? colorScheme.primary
-                      : null,
-                ),
-                const SizedBox(width: 12),
-                Text(
-                  'System',
-                  style: currentTheme == ThemeSetting.system
-                      ? TextStyle(color: colorScheme.primary)
-                      : null,
-                ),
-                const Spacer(),
-                if (currentTheme == ThemeSetting.system)
-                  Icon(Icons.check, size: 16, color: colorScheme.primary),
-              ],
-            ),
-          ),
-
-          // Theme: Light
-          PopupMenuItem<String>(
-            value: 'theme_light',
-            height: 40,
-            child: Row(
-              children: [
-                Icon(
-                  Icons.light_mode,
-                  size: 18,
-                  color: currentTheme == ThemeSetting.light
-                      ? colorScheme.primary
-                      : null,
-                ),
-                const SizedBox(width: 12),
-                Text(
-                  'Light',
-                  style: currentTheme == ThemeSetting.light
-                      ? TextStyle(color: colorScheme.primary)
-                      : null,
-                ),
-                const Spacer(),
-                if (currentTheme == ThemeSetting.light)
-                  Icon(Icons.check, size: 16, color: colorScheme.primary),
-              ],
-            ),
-          ),
-
-          // Theme: Dark
-          PopupMenuItem<String>(
-            value: 'theme_dark',
-            height: 40,
-            child: Row(
-              children: [
-                Icon(
-                  Icons.dark_mode,
-                  size: 18,
-                  color: currentTheme == ThemeSetting.dark
-                      ? colorScheme.primary
-                      : null,
-                ),
-                const SizedBox(width: 12),
-                Text(
-                  'Dark',
-                  style: currentTheme == ThemeSetting.dark
-                      ? TextStyle(color: colorScheme.primary)
-                      : null,
-                ),
-                const Spacer(),
-                if (currentTheme == ThemeSetting.dark)
-                  Icon(Icons.check, size: 16, color: colorScheme.primary),
-              ],
-            ),
-          ),
-
-          const PopupMenuDivider(),
-
-          // Logout (only if authenticated)
-          if (auth.isAuthenticated)
-            const PopupMenuItem<String>(
-              value: 'logout',
-              child: Row(
+          itemBuilder: (context) => [
+            // User info header (non-selectable)
+            PopupMenuItem<String>(
+              enabled: false,
+              child: Column(
+                crossAxisAlignment: CrossAxisAlignment.start,
                 children: [
-                  Icon(Icons.logout, size: 20),
-                  SizedBox(width: 12),
-                  Text('Logout'),
+                  Text(
+                    auth.isAuthenticated ? auth.userName ?? 'User' : 'Guest',
+                    style: Theme.of(context).textTheme.titleSmall,
+                  ),
+                  if (auth.userEmail != null)
+                    Text(
+                      auth.userEmail!,
+                      style: Theme.of(context).textTheme.bodySmall?.copyWith(
+                            color: colorScheme.onSurfaceVariant,
+                          ),
+                    ),
                 ],
               ),
             ),
-        ],
-        onSelected: (value) {
-          switch (value) {
-            case 'settings':
-              context.go(AppRoutes.settings);
-            case 'theme_system':
-              _updateTheme(ref, ThemeSetting.system);
-            case 'theme_light':
-              _updateTheme(ref, ThemeSetting.light);
-            case 'theme_dark':
-              _updateTheme(ref, ThemeSetting.dark);
-            case 'logout':
-              ref.read(authProvider.notifier).signOut();
-          }
-        },
+            const PopupMenuDivider(),
+
+            // Settings
+            PopupMenuItem<String>(
+              value: 'settings',
+              child: Semantics(
+                identifier: ProfileSemantics.settings,
+                child: const Row(
+                  children: [
+                    Icon(Icons.settings_outlined, size: 20),
+                    SizedBox(width: 12),
+                    Text('Settings'),
+                  ],
+                ),
+              ),
+            ),
+
+            // Theme submenu header
+            PopupMenuItem<String>(
+              enabled: false,
+              height: 32,
+              child: Text(
+                'THEME',
+                style: Theme.of(context).textTheme.labelSmall?.copyWith(
+                      color: colorScheme.onSurfaceVariant,
+                      letterSpacing: 0.5,
+                    ),
+              ),
+            ),
+
+            // Theme: System
+            PopupMenuItem<String>(
+              value: 'theme_system',
+              height: 40,
+              child: Semantics(
+                identifier: ProfileSemantics.themeSystem,
+                child: Row(
+                  children: [
+                    Icon(
+                      Icons.brightness_auto,
+                      size: 18,
+                      color: currentTheme == ThemeSetting.system
+                          ? colorScheme.primary
+                          : null,
+                    ),
+                    const SizedBox(width: 12),
+                    Text(
+                      'System',
+                      style: currentTheme == ThemeSetting.system
+                          ? TextStyle(color: colorScheme.primary)
+                          : null,
+                    ),
+                    const Spacer(),
+                    if (currentTheme == ThemeSetting.system)
+                      Icon(Icons.check, size: 16, color: colorScheme.primary),
+                  ],
+                ),
+              ),
+            ),
+
+            // Theme: Light
+            PopupMenuItem<String>(
+              value: 'theme_light',
+              height: 40,
+              child: Semantics(
+                identifier: ProfileSemantics.themeLight,
+                child: Row(
+                  children: [
+                    Icon(
+                      Icons.light_mode,
+                      size: 18,
+                      color: currentTheme == ThemeSetting.light
+                          ? colorScheme.primary
+                          : null,
+                    ),
+                    const SizedBox(width: 12),
+                    Text(
+                      'Light',
+                      style: currentTheme == ThemeSetting.light
+                          ? TextStyle(color: colorScheme.primary)
+                          : null,
+                    ),
+                    const Spacer(),
+                    if (currentTheme == ThemeSetting.light)
+                      Icon(Icons.check, size: 16, color: colorScheme.primary),
+                  ],
+                ),
+              ),
+            ),
+
+            // Theme: Dark
+            PopupMenuItem<String>(
+              value: 'theme_dark',
+              height: 40,
+              child: Semantics(
+                identifier: ProfileSemantics.themeDark,
+                child: Row(
+                  children: [
+                    Icon(
+                      Icons.dark_mode,
+                      size: 18,
+                      color: currentTheme == ThemeSetting.dark
+                          ? colorScheme.primary
+                          : null,
+                    ),
+                    const SizedBox(width: 12),
+                    Text(
+                      'Dark',
+                      style: currentTheme == ThemeSetting.dark
+                          ? TextStyle(color: colorScheme.primary)
+                          : null,
+                    ),
+                    const Spacer(),
+                    if (currentTheme == ThemeSetting.dark)
+                      Icon(Icons.check, size: 16, color: colorScheme.primary),
+                  ],
+                ),
+              ),
+            ),
+
+            const PopupMenuDivider(),
+
+            // Logout (only if authenticated)
+            if (auth.isAuthenticated)
+              PopupMenuItem<String>(
+                value: 'logout',
+                child: Semantics(
+                  identifier: ProfileSemantics.logout,
+                  child: const Row(
+                    children: [
+                      Icon(Icons.logout, size: 20),
+                      SizedBox(width: 12),
+                      Text('Logout'),
+                    ],
+                  ),
+                ),
+              ),
+          ],
+          onSelected: (value) {
+            switch (value) {
+              case 'settings':
+                context.go(AppRoutes.settings);
+              case 'theme_system':
+                _updateTheme(ref, ThemeSetting.system);
+              case 'theme_light':
+                _updateTheme(ref, ThemeSetting.light);
+              case 'theme_dark':
+                _updateTheme(ref, ThemeSetting.dark);
+              case 'logout':
+                ref.read(authProvider.notifier).signOut();
+            }
+          },
+        ),
       ),
       loading: () => const CircleAvatar(
         radius: 18,

lib/shared/layouts/widgets/top_header_bar.dart

@@ -1,6 +1,7 @@
 import 'dart:math';
 
 import 'package:flutter/material.dart';
+import 'package:tatlock_ui/core/semantics/semantic_ids.dart';
 
 import 'profile_dropdown.dart';
 
@@ -127,17 +128,23 @@ class TopHeaderBar extends StatelessWidget {
 
       return Padding(
         padding: const EdgeInsets.symmetric(horizontal: 4),
-        child: Tooltip(
-          message: room.label,
-          child: IconButton(
-            icon: Icon(
-              isSelected ? room.selectedIcon : room.icon,
-              color: isSelected ? colorScheme.primary : colorScheme.onSurface,
-            ),
-            onPressed: () => onRoomSelected(index),
-            style: IconButton.styleFrom(
-              backgroundColor:
-                  isSelected ? colorScheme.primaryContainer : null,
+        child: Semantics(
+          identifier: RoomTabSemantics.forIndex(index),
+          label: room.label,
+          button: true,
+          selected: isSelected,
+          child: Tooltip(
+            message: room.label,
+            child: IconButton(
+              icon: Icon(
+                isSelected ? room.selectedIcon : room.icon,
+                color: isSelected ? colorScheme.primary : colorScheme.onSurface,
+              ),
+              onPressed: () => onRoomSelected(index),
+              style: IconButton.styleFrom(
+                backgroundColor:
+                    isSelected ? colorScheme.primaryContainer : null,
+              ),
             ),
           ),
         ),

pubspec.yaml

@@ -16,7 +16,7 @@ publish_to: 'none' # Remove this line if you wish to publish to pub.dev
 # https://developer.apple.com/library/archive/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html
 # In Windows, build-name is used as the major, minor, and patch parts
 # of the product and file versions while build-number is used as the build suffix.
-version: 1.1.16+1
+version: 1.3.0+1
 
 environment:
   sdk: ^3.10.4