From 2be748ef10cab961d2e418af576b60f74088fc4b Mon Sep 17 00:00:00 2001
From: Matt Hillsdon <matt.hillsdon@microbit.org>
Date: Wed, 8 Jul 2026 11:07:52 +0100
Subject: [PATCH] Add screen reader mode support, deprecate keyboard controls
 toggle

Adds MakeCodeFrameDriver.toggleScreenReaderMode() sending the new
"togglescreenreadermode" action and an optional screenReaderMode field
on the info response, both supported by the next MakeCode release.
toggleKeyboardControls() remains for API compatibility but is
deprecated as current MakeCode versions keep keyboard controls always
enabled, so it does nothing.

The storybook toolbar button now exercises the screen reader toggle,
and the editor stories' version control gains a "local" option pointing
at a locally running pxt-microbit dev server for testing unreleased
editor changes.
---
 src/stories/MakeCodeToolbar.tsx                 |  4 ++--
 src/stories/config.ts                           | 17 +++++++++++++++++
 src/stories/react/MakeCodeFrame.stories.tsx     | 17 ++++++++++++-----
 .../vanilla/makecode-frame-driver.stories.tsx   |  7 +++++--
 src/vanilla/makecode-frame-driver.ts            | 11 +++++++++++
 src/vanilla/pxt.ts                              |  2 ++
 6 files changed, 49 insertions(+), 9 deletions(-)

diff --git a/src/stories/MakeCodeToolbar.tsx b/src/stories/MakeCodeToolbar.tsx
index 076e6c0..cc38314 100644
--- a/src/stories/MakeCodeToolbar.tsx
+++ b/src/stories/MakeCodeToolbar.tsx
@@ -104,8 +104,8 @@ const MakeCodeToolbar = ({
         <button onClick={() => driver.current!.toggleDebugSloMo()}>
           Toggle debug slow mo
         </button>
-        <button onClick={() => driver.current!.toggleKeyboardControls()}>
-          Keyboard controls
+        <button onClick={() => driver.current!.toggleScreenReaderMode()}>
+          Screen reader mode
         </button>
         <button onClick={() => driver.current!.toggleGreenScreen()}>
           Green screen
diff --git a/src/stories/config.ts b/src/stories/config.ts
index 52712ec..895afb4 100644
--- a/src/stories/config.ts
+++ b/src/stories/config.ts
@@ -1 +1,18 @@
 export const controllerId = 'MicrobitStorybook';
+
+// A locally running pxt-microbit dev server (`pxt serve`), selectable via the
+// "version" control in the editor stories for testing unreleased editor changes.
+// We point at /index.html because the dev server's redirect from / drops the
+// query string, losing controller=1 and leaving the editor in sandbox layout.
+export const localPxtBaseUrl = 'http://localhost:3232/index.html';
+
+/**
+ * Maps the story "version" control value ('default' | 'beta' | 'local') to
+ * baseUrl/version values understood by the frame driver.
+ */
+export const editorVersionArgs = (
+  version: string | undefined
+): { baseUrl?: string; version?: string } =>
+  version === 'local'
+    ? { baseUrl: localPxtBaseUrl }
+    : { version: version === 'default' ? undefined : version };
diff --git a/src/stories/react/MakeCodeFrame.stories.tsx b/src/stories/react/MakeCodeFrame.stories.tsx
index e41b196..769fc58 100644
--- a/src/stories/react/MakeCodeFrame.stories.tsx
+++ b/src/stories/react/MakeCodeFrame.stories.tsx
@@ -7,7 +7,11 @@ import {
   MakeCodeFrameProps,
 } from '../../react/MakeCodeFrame.js';
 import { MakeCodeProject } from '../../vanilla/pxt.js';
-import { controllerId } from '../config.js';
+import {
+  controllerId,
+  editorVersionArgs,
+  localPxtBaseUrl,
+} from '../config.js';
 import StoryWrapper from '../StoryWrapper.js';
 import MakeCodeToolbar from '../MakeCodeToolbar.js';
 
@@ -16,10 +20,13 @@ const meta: Meta<typeof MakeCodeFrame> = {
   component: MakeCodeFrame,
   argTypes: {
     version: {
-      options: ['default', 'beta'],
+      options: ['default', 'beta', 'local'],
       defaultValue: undefined,
       name: 'version',
-      control: { type: 'radio' },
+      control: {
+        type: 'radio',
+        labels: { local: `local (${localPxtBaseUrl})` },
+      },
     },
   },
 };
@@ -73,7 +80,7 @@ export const MakeCodeEditorWithControlsStory: Story = {
     return (
       <StoryWrapper>
         <MakeCodeEditorWithControls
-          version={version === 'default' ? undefined : version}
+          {...editorVersionArgs(version)}
           // TODO: make this an argument and perhaps a real prop
           queryParams={{ hideMenu: '' }}
         />
@@ -94,7 +101,7 @@ export const MakeCodeEditorControllerAppModeStory: Story = {
         <MakeCodeEditorWithControls
           controller={2}
           controllerId={controllerId}
-          version={version === 'default' ? undefined : version}
+          {...editorVersionArgs(version)}
           // App specific events
           onDownload={(download) => console.log('download', download)}
           onSave={(save) => console.log('save', save)}
diff --git a/src/stories/vanilla/makecode-frame-driver.stories.tsx b/src/stories/vanilla/makecode-frame-driver.stories.tsx
index 1dac623..fc8666a 100644
--- a/src/stories/vanilla/makecode-frame-driver.stories.tsx
+++ b/src/stories/vanilla/makecode-frame-driver.stories.tsx
@@ -7,6 +7,7 @@ import {
   Options,
 } from '../../vanilla/makecode-frame-driver.js';
 import { MakeCodeProject } from '../../vanilla/pxt.js';
+import { editorVersionArgs } from '../config.js';
 import MakeCodeToolbar from '../MakeCodeToolbar.js';
 import StoryWrapper from '../StoryWrapper.js';
 
@@ -39,9 +40,11 @@ const renderEditor = (args: StoryArgs) => {
     // Create an iframe element.
     const iframe = document.createElement('iframe');
     iframe.allow = 'usb; autoplay; camera; microphone;';
+    const { baseUrl = 'https://makecode.microbit.org', version } =
+      editorVersionArgs(args.options?.version);
     iframe.src = createMakeCodeURL(
-      'https://makecode.microbit.org',
-      args.options?.version === 'default' ? undefined : args.options?.version,
+      baseUrl,
+      version,
       args.options?.lang,
       args.options?.controller ?? 1,
       args.options?.queryParams
diff --git a/src/vanilla/makecode-frame-driver.ts b/src/vanilla/makecode-frame-driver.ts
index 64a7550..acd5445 100644
--- a/src/vanilla/makecode-frame-driver.ts
+++ b/src/vanilla/makecode-frame-driver.ts
@@ -756,6 +756,10 @@ export class MakeCodeFrameDriver {
     } as EditorMessageSetHighContrastRequest);
   }
 
+  /**
+   * @deprecated Keyboard controls are always enabled in current MakeCode
+   * versions so this does nothing.
+   */
   async toggleKeyboardControls(): Promise<void> {
     await this.sendRequest({
       type: 'pxteditor',
@@ -763,6 +767,13 @@ export class MakeCodeFrameDriver {
     });
   }
 
+  async toggleScreenReaderMode(): Promise<void> {
+    await this.sendRequest({
+      type: 'pxteditor',
+      action: 'togglescreenreadermode',
+    });
+  }
+
   async toggleGreenScreen(): Promise<void> {
     await this.sendRequest({
       type: 'pxteditor',
diff --git a/src/vanilla/pxt.ts b/src/vanilla/pxt.ts
index 85719d9..65cb5ac 100644
--- a/src/vanilla/pxt.ts
+++ b/src/vanilla/pxt.ts
@@ -185,6 +185,7 @@ export interface EditorMessageRequest extends EditorMessage {
     | 'sethighcontrast' // EditorMessageSetHighContrastRequest
     | 'togglegreenscreen'
     | 'togglekeyboardcontrols'
+    | 'togglescreenreadermode'
     | 'settracestate' //
     | 'setsimulatorfullscreen' // EditorMessageSimulatorFullScreenRequest
     | 'print' // print code
@@ -545,6 +546,7 @@ export interface InfoMessage {
   locale: string;
   availableLocales?: string[];
   keyboardControls: boolean;
+  screenReaderMode?: boolean;
 }
 
 export interface PackageExtensionData {