fix: Announce the workspace to VoiceOver via a focus target node

packages/blockly/core/css.ts

@@ -527,6 +527,7 @@ input[type=number] {
 .blocklyActiveFocus:is(
   .blocklyFlyout,
   .blocklyWorkspace,
+  .blocklyWorkspaceSelectionRing,
   .blocklyField,
   .blocklyPath,
   .blocklyHighlightedConnectionPath,
@@ -650,14 +651,25 @@ input[type=number] {
   stroke-width: calc(var(--blockly-selection-width) * 2);
 }
 
-/* The workspace itself is the active node. */
+/* The region itself is the active node (e.g. focused by clicking the
+   background). */
 .blocklyKeyboardNavigation
   .blocklyWorkspace.blocklyActiveFocus
-  .blocklyWorkspaceSelectionRing {
+  .blocklyWorkspaceSelectionRing,
+/* The selection ring itself is the active node (it doubles as the workspace's
+   keyboard focus target). */
+.blocklyKeyboardNavigation
+  .blocklyWorkspaceSelectionRing.blocklyActiveFocus {
   stroke: var(--blockly-active-node-color);
   stroke-width: var(--blockly-selection-width);
 }
 
+/* The selection ring is a decorative highlight that can also be the workspace's
+   focus target; either way it should never intercept pointer events. */
+.blocklyWorkspaceSelectionRing {
+  pointer-events: none;
+}
+
 /* The workspace itself is the active node. */
 .blocklyKeyboardNavigation
   .blocklyBubble.blocklyActiveFocus

packages/blockly/core/keyboard_nav/navigation_policies/workspace_focus_target_navigation_policy.ts

@@ -0,0 +1,89 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {IFocusableNode} from '../../interfaces/i_focusable_node.js';
+import type {INavigationPolicy} from '../../interfaces/i_navigation_policy.js';
+import {WorkspaceFocusTarget} from '../../workspace_focus_target.js';
+
+/**
+ * Set of rules controlling keyboard navigation from the workspace focus target.
+ *
+ * The focus target represents the workspace as a whole (reached via the focus
+ * workspace shortcut or when first entering the workspace), so navigating into
+ * it should mirror navigating into the workspace itself.
+ */
+export class WorkspaceFocusTargetNavigationPolicy implements INavigationPolicy<WorkspaceFocusTarget> {
+  /**
+   * Returns the first child of the focus target's workspace.
+   *
+   * @param current The focus target to return the first child of.
+   * @returns The top block of the first block stack, if any.
+   */
+  getFirstChild(current: WorkspaceFocusTarget): IFocusableNode | null {
+    const blocks = current.getWorkspace().getTopBlocks(true);
+    return blocks.length ? blocks[0] : null;
+  }
+
+  /**
+   * Returns the parent of the given focus target.
+   *
+   * @param _current The focus target to return the parent of.
+   * @returns Null.
+   */
+  getParent(_current: WorkspaceFocusTarget): IFocusableNode | null {
+    return null;
+  }
+
+  /**
+   * Returns the next sibling of the given focus target.
+   *
+   * @param _current The focus target to return the next sibling of.
+   * @returns Null.
+   */
+  getNextSibling(_current: WorkspaceFocusTarget): IFocusableNode | null {
+    return null;
+  }
+
+  /**
+   * Returns the previous sibling of the given focus target.
+   *
+   * @param _current The focus target to return the previous sibling of.
+   * @returns Null.
+   */
+  getPreviousSibling(_current: WorkspaceFocusTarget): IFocusableNode | null {
+    return null;
+  }
+
+  /**
+   * Returns the row ID of the given focus target.
+   *
+   * @param current The focus target to retrieve the row ID of.
+   * @returns The row ID of the focus target's workspace.
+   */
+  getRowId(current: WorkspaceFocusTarget): string {
+    return current.getWorkspace().id;
+  }
+
+  /**
+   * Returns whether or not the given focus target can be navigated to.
+   *
+   * @param current The instance to check for navigability.
+   * @returns True if the given focus target can be focused.
+   */
+  isNavigable(current: WorkspaceFocusTarget): boolean {
+    return current.canBeFocused();
+  }
+
+  /**
+   * Returns whether the given object can be navigated from by this policy.
+   *
+   * @param current The object to check if this policy applies to.
+   * @returns True if the object is a WorkspaceFocusTarget.
+   */
+  isApplicable(current: any): current is WorkspaceFocusTarget {
+    return current instanceof WorkspaceFocusTarget;
+  }
+}

packages/blockly/core/keyboard_nav/navigators/navigator.ts

@@ -20,6 +20,7 @@ import {ConnectionNavigationPolicy} from '../navigation_policies/connection_navi
 import {FieldNavigationPolicy} from '../navigation_policies/field_navigation_policy.js';
 import {IconNavigationPolicy} from '../navigation_policies/icon_navigation_policy.js';
 import {WorkspaceCommentNavigationPolicy} from '../navigation_policies/workspace_comment_navigation_policy.js';
+import {WorkspaceFocusTargetNavigationPolicy} from '../navigation_policies/workspace_focus_target_navigation_policy.js';
 import {WorkspaceNavigationPolicy} from '../navigation_policies/workspace_navigation_policy.js';
 
 type RuleList<T> = INavigationPolicy<T>[];
@@ -48,6 +49,7 @@ export class Navigator {
     new FieldNavigationPolicy(),
     new ConnectionNavigationPolicy(),
     new WorkspaceNavigationPolicy(),
+    new WorkspaceFocusTargetNavigationPolicy(),
     new IconNavigationPolicy(),
     new WorkspaceCommentNavigationPolicy(),
     new CommentBarButtonNavigationPolicy(),

packages/blockly/core/shortcut_items.ts

@@ -774,7 +774,12 @@ export function registerFocusWorkspace() {
     preconditionFn: (workspace) => !workspace.isDragging(),
     callback: (workspace) => {
       keyboardNavigationController.setIsActive(true);
-      getFocusManager().focusNode(resolveWorkspace(workspace));
+      // Focus the focus target (which announces the stack count) rather than the
+      // workspace region, falling back to the region if there's no focus target.
+      const rootWorkspace = resolveWorkspace(workspace);
+      getFocusManager().focusNode(
+        rootWorkspace.getWorkspaceFocusTarget() ?? rootWorkspace,
+      );
       return true;
     },
     keyCodes: [KeyCodes.W],

packages/blockly/core/workspace_focus_target.ts

@@ -0,0 +1,64 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {IFocusableNode} from './interfaces/i_focusable_node.js';
+import type {IFocusableTree} from './interfaces/i_focusable_tree.js';
+import type {WorkspaceSvg} from './workspace_svg.js';
+
+/**
+ * A focusable element representing the workspace as a whole.
+ *
+ * Focus on the workspace itself (i.e. not on any block, comment, or other
+ * content) lands here rather than on the workspace's region element. VoiceOver
+ * does not announce a region when focus moves into it from a node already
+ * inside that region, so focusing the region directly (e.g. after pressing "W"
+ * from a block) would be silent. This is an ordinary focusable node, so moving
+ * to it is announced. It carries the stack count and a "workspace" role
+ * description; the enclosing region keeps a short, stable label
+ * ("Blocks workspace.").
+ */
+export class WorkspaceFocusTarget implements IFocusableNode {
+  /**
+   * @param workspace The workspace this focus target represents.
+   * @param element The SVG element that receives focus for the workspace.
+   */
+  constructor(
+    private readonly workspace: WorkspaceSvg,
+    private readonly element: SVGElement,
+  ) {}
+
+  /** See IFocusableNode.getFocusableElement. */
+  getFocusableElement(): SVGElement {
+    return this.element;
+  }
+
+  /** See IFocusableNode.getFocusableTree. */
+  getFocusableTree(): IFocusableTree {
+    return this.workspace;
+  }
+
+  /** See IFocusableNode.onNodeFocus. */
+  onNodeFocus(): void {
+    this.workspace.handleWorkspaceFocusTargetFocus();
+  }
+
+  /** See IFocusableNode.onNodeBlur. */
+  onNodeBlur(): void {}
+
+  /** See IFocusableNode.canBeFocused. */
+  canBeFocused(): boolean {
+    return true;
+  }
+
+  /**
+   * Returns the workspace this focus target represents.
+   *
+   * @returns The workspace this focus target represents.
+   */
+  getWorkspace(): WorkspaceSvg {
+    return this.workspace;
+  }
+}