@agent-native/core 0.132.1 → 0.132.2

package/corpus/README.md

@@ -30,4 +30,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 - core files: 1645
 - toolkit files: 168
-- template files: 7235
+- template files: 7237

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @agent-native/core
 
+## 0.132.2
+
+### Patch Changes
+
+- 3aa3c49: Keep each resource's agent chat to itself instead of showing one chat everywhere.
+
+  A chat thread's `scope` carried two meanings at once: "general chat, visible in
+  every resource" and "nobody has told the server this thread's scope yet". Because
+  those were indistinguishable, a thread that lost its scope silently became a
+  permanent global chat — it followed the user into every design/deck/form, and
+  because an unscoped chat is allowed to stay visible, no per-resource chat was ever
+  started.
+
+  Two paths dropped the scope. The server created the row on the first message
+  without one (`persistSubmittedUserMessage`), even though the client already sends
+  it and `production-agent` had already normalized it onto
+  `RequestRunContext.chatScope` — nothing read that field. The client then asserted
+  `scope: null` on every save for any thread missing from its local list, which the
+  `PUT` applies unconditionally, cementing the null.
+
+  Now the run's scope is used when the row is created, a thread with no scope adopts
+  the scope of the resource it is used in (`resolveRunThreadScope`, which never
+  retags or clears an already-scoped thread), and the client only mirrors a scope it
+  actually knows. Adoption also heals threads already stored with `scope: null`, and
+  claims the row with a compare-and-set on the unscoped state so two workers racing
+  to adopt the same legacy thread cannot retag it to the wrong resource.
+
+  Scope now rides only on thread creation: a periodic save no longer sends it, so a
+  stale client guess cannot move an existing thread between resources, and
+  `detachThread` is the only client path that clears one. A restored active-chat
+  pointer is checked against the thread's real scope on a direct mount as well as
+  when moving between resources — and because the thread list is one page, a pointer
+  naming a thread the page did not reach is resolved by id rather than assumed to be
+  a never-messaged local tab.
+
+  Genuinely general chats are unaffected until they are used inside a resource.
+
 ## 0.132.1
 
 ### Patch Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.132.1",
+  "version": "0.132.2",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {

package/corpus/core/src/chat-threads/store.ts

@@ -766,6 +766,48 @@ export async function searchThreads(
     .filter((r): r is ChatThreadSummary => r !== null);
 }
 
+/**
+ * Scope a thread should carry after a run inside a resource: adopt when it has
+ * none, otherwise keep what it has. An unscoped thread reads as general, and a
+ * general chat renders inside every resource — so never retag, never clear.
+ */
+export function resolveRunThreadScope(
+  existing: ChatThreadScope | null,
+  incoming: ChatThreadScope | null | undefined,
+): ChatThreadScope | null {
+  if (existing) return existing;
+  return incoming ?? null;
+}
+
+/**
+ * Claim an unscoped thread for `scope`, returning the scope it actually ends up
+ * with. `withThreadDataLock` only serializes one process, so two workers can
+ * both read the same unscoped row; the `scope_type IS NULL` guard makes the
+ * first writer win and the loser reports the winner instead of retagging.
+ */
+export async function adoptThreadScopeIfUnscoped(
+  id: string,
+  scope: ChatThreadScope,
+): Promise<ChatThreadScope | null> {
+  await ensureTable();
+  const client = getDbExec();
+  const result = await client.execute({
+    sql: `UPDATE chat_threads SET scope_type = ?, scope_id = ?, scope_label = ?, updated_at = ? WHERE id = ? AND scope_type IS NULL`,
+    args: [
+      scope.type,
+      scope.id,
+      scope.label ?? null,
+      Math.max(Date.now(), 1),
+      id,
+    ],
+  });
+  if (result.rowsAffected > 0) {
+    emitChatThreadChange(id);
+    return scope;
+  }
+  return (await getThread(id))?.scope ?? null;
+}
+
 /**
  * Detach or rebind a chat's scope. Used by the UI's "Detach from <resource>"
  * action and by templates that need to retag a chat after a rename. Pass

package/corpus/core/src/client/use-chat-threads.ts

@@ -91,6 +91,25 @@ async function fetchThreadListPage(
   });
 }
 
+/**
+ * Look up one thread the list page did not carry. Distinguishes the three states
+ * the caller must not collapse: the thread (found), `null` (the server denies it
+ * exists), and `undefined` (unreachable — nothing was learned).
+ */
+async function fetchThreadById(
+  apiUrl: string,
+  id: string,
+): Promise<ChatThreadSummary | null | undefined> {
+  try {
+    const res = await fetch(`${apiUrl}/threads/${encodeURIComponent(id)}`);
+    if (res.status === 404) return null;
+    if (!res.ok) return undefined;
+    return (await res.json()) as ChatThreadSummary;
+  } catch {
+    return undefined;
+  }
+}
+
 function emitThreadsUpdated() {
   if (typeof window === "undefined") return;
   window.dispatchEvent(new CustomEvent(THREADS_UPDATED_EVENT));
@@ -411,6 +430,17 @@ export function useChatThreads(
       } catch {
         nextActiveThreadId = null;
       }
+      // Only a known mismatch disqualifies the pointer — an unresolved scope
+      // must not be read as "belongs here".
+      if (nextActiveThreadId) {
+        const savedScope = readKnownThreadScope(nextActiveThreadId);
+        if (
+          savedScope !== undefined &&
+          !threadCanStayVisibleInScope(savedScope, scopeRef.current)
+        ) {
+          nextActiveThreadId = null;
+        }
+      }
       if (!nextActiveThreadId && autoCreate) {
         nextActiveThreadId = createLocalThreadId();
         newlyCreatedRef.current.add(nextActiveThreadId);
@@ -583,7 +613,7 @@ export function useChatThreads(
 
     (async () => {
       const loadedThreads = await fetchThreads();
-      const savedId = activeThreadIdRef.current;
+      const restoredId = activeThreadIdRef.current;
       if (loadedThreads === undefined) {
         // Thread-list fetch failed. Do not reclassify a saved id as a new
         // optimistic tab; AssistantChat should still get a chance to restore
@@ -591,8 +621,40 @@ export function useChatThreads(
         setIsLoading(false);
         return;
       }
+      // Exempts route-owned threads (the URL names what the user asked for) and
+      // ids this client generated, which have never reached the server.
+      const lookupRestored = Boolean(
+        restoredId &&
+        !routeControlsActiveThread &&
+        !newlyCreatedRef.current.has(restoredId),
+      );
+      const restoredOnPage = restoredId
+        ? loadedThreads.find((t) => t.id === restoredId)
+        : undefined;
+      // One page, so absence from it is not absence from the server — this is what
+      // separates an older real thread from the ghost tab reclassified below.
+      const restoredThread =
+        lookupRestored && !restoredOnPage
+          ? await fetchThreadById(apiUrl, restoredId!)
+          : restoredOnPage;
+      if (restoredThread === undefined && lookupRestored && !restoredOnPage) {
+        // Lookup unreachable. Reclassifying now would stamp this thread with the
+        // current scope on a guess; leave it untouched for the next mount.
+        setIsLoading(false);
+        return;
+      }
+      const restoredBelongsElsewhere = Boolean(
+        restoredThread &&
+        !threadCanStayVisibleInScope(
+          restoredThread.scope ?? null,
+          scopeRef.current,
+        ),
+      );
+      if (restoredBelongsElsewhere) setActiveThreadId(null);
+      const savedId = restoredBelongsElsewhere ? null : restoredId;
       const loadedHasSavedId = Boolean(
-        savedId && loadedThreads.some((t) => t.id === savedId),
+        savedId &&
+        (restoredThread || loadedThreads.some((t) => t.id === savedId)),
       );
       const savedIdCameFromRoute =
         Boolean(savedId) &&
@@ -646,6 +708,7 @@ export function useChatThreads(
       setIsLoading(false);
     })();
   }, [
+    apiUrl,
     fetchThreads,
     addOptimisticThread,
     autoCreate,
@@ -948,12 +1011,9 @@ export function useChatThreads(
     [apiUrl, clearUserRenamedThread, createThread],
   );
 
-  // Ref to look up the latest scope of a known thread inside
-  // saveThreadData without making the callback re-create on every
-  // setThreads. The thread's scope is owned by createThread /
-  // detachThread / fetchThreads — saveThreadData just mirrors it on
-  // every save so the server eventually catches up after
-  // persistSubmittedUserMessage creates the row sans scope.
+  // Reads scope through refs so this callback survives every setThreads. Scope
+  // rides only on creation: a periodic save must never move an existing thread
+  // between resources, however stale this client's guess is.
   const saveThreadData = useCallback(
     async (
       id: string,
@@ -968,7 +1028,7 @@ export function useChatThreads(
       try {
         const { titleSource, ...threadDataPayload } = data;
         const localThread = threadsRef.current.find((t) => t.id === id);
-        const localScope = localThread?.scope ?? null;
+        const knownScope = readKnownThreadScope(id) ?? null;
         const preserveUserTitle = userRenamedThreadIdsRef.current.has(id);
         const title = nextThreadTitle(
           localThread?.title,
@@ -977,11 +1037,7 @@ export function useChatThreads(
           titleSource,
           { preserveUserTitle },
         );
-        const payload = {
-          ...threadDataPayload,
-          title,
-          scope: localScope,
-        };
+        const payload = { ...threadDataPayload, title };
         let response = await fetch(
           `${apiUrl}/threads/${encodeURIComponent(id)}`,
           {
@@ -997,7 +1053,11 @@ export function useChatThreads(
           const created = await fetch(`${apiUrl}/threads`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ id, title, scope: localScope }),
+            body: JSON.stringify({
+              id,
+              title,
+              ...(knownScope ? { scope: knownScope } : {}),
+            }),
           });
           if (!created.ok) return;
           response = await fetch(
@@ -1059,7 +1119,7 @@ export function useChatThreads(
         });
       } catch {}
     },
-    [apiUrl],
+    [apiUrl, readKnownThreadScope],
   );
 
   const generateTitle = useCallback(

package/corpus/core/src/server/agent-chat-plugin.ts

@@ -107,10 +107,12 @@ import type {
 import { readAppStateForCurrentTab } from "../application-state/script-helpers.js";
 import { runChatThreadDataMigrations } from "../chat-threads/migrations.js";
 import {
+  adoptThreadScopeIfUnscoped,
   createThread,
   forkThread,
   getThread,
   registerChatThreadsShareable,
+  resolveRunThreadScope,
   resolveThreadAccess,
   listThreads,
   searchThreads,
@@ -2538,11 +2540,16 @@ export function createAgentChatPlugin(
           getRequestRunContext()?.owner ?? getRequestUserEmail();
         if (!ownerEmail) return;
 
+        const runScope = getRequestRunContext()?.chatScope ?? null;
+
         await withThreadDataLock(threadId, async () => {
           let thread = await getThread(threadId);
           if (!thread) {
             try {
-              thread = await createThread(ownerEmail, { id: threadId });
+              thread = await createThread(ownerEmail, {
+                id: threadId,
+                scope: runScope,
+              });
             } catch {
               thread = await getThread(threadId);
             }
@@ -2566,6 +2573,14 @@ export function createAgentChatPlugin(
             });
           }
 
+          const nextScope = resolveRunThreadScope(thread.scope, runScope);
+          if (nextScope && nextScope !== thread.scope) {
+            thread = {
+              ...thread,
+              scope: await adoptThreadScopeIfUnscoped(threadId, nextScope),
+            };
+          }
+
           let repo: any;
           try {
             repo = JSON.parse(thread.threadData || "{}");

package/corpus/templates/clips/changelog/2026-07-30-meeting-microphone-transcription-works-reliably-from-the-fir.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-30
+---
+
+Meeting microphone transcription works reliably from the first start.

package/corpus/templates/clips/desktop/src-tauri/src/native_screen/custom_capture.rs

@@ -2743,6 +2743,19 @@ fn extract_interleaved_stereo(
     Some((out, pts_seconds))
 }
 
+pub(crate) fn extract_mono_audio(
+    sample: &screencapturekit::cm::CMSampleBuffer,
+    label: &str,
+) -> Option<Vec<f32>> {
+    let (interleaved, _) = extract_interleaved_stereo(sample, label)?;
+    Some(
+        interleaved
+            .chunks_exact(2)
+            .map(|channels| (channels[0] + channels[1]) * 0.5)
+            .collect(),
+    )
+}
+
 /// Record whether decoded source PCM contains a real signal before it reaches
 /// the timeline mixer. This distinguishes capture/format failures from mixer
 /// or writer failures without persisting any audio content.

package/corpus/templates/clips/desktop/src-tauri/src/native_screen.rs

@@ -128,6 +128,8 @@ const NATIVE_CAPTURE_FPS: u32 = 24;
 #[cfg(target_os = "macos")]
 mod custom_capture;
 #[cfg(target_os = "macos")]
+pub(crate) use custom_capture::extract_mono_audio;
+#[cfg(target_os = "macos")]
 use custom_capture::{
     prepare_clip_sink, start_custom_screencapturekit_backend_at, ClosedSegmentFile,
     CustomCaptureResume, CustomScreenCaptureWriter, PreparedClipSink, SegmentFence,

package/corpus/templates/clips/desktop/src-tauri/src/system_audio.rs

@@ -11,8 +11,8 @@
 //! renderer's `LiveTranscript` tagged `source: "system"`.
 //!
 //! Uses the safe `screencapturekit` Rust crate. Its `SCStreamOutputTrait`
-//! callback hands us a `CMSampleBuffer` per audio frame; SCK delivers stereo
-//! 48 kHz float, which we mono-mix on the way out.
+//! callback hands us a `CMSampleBuffer` per audio frame; each source is decoded
+//! from its advertised format, normalized to 48 kHz, and mono-mixed.
 //!
 //! ## Tauri commands
 //!
@@ -163,9 +163,6 @@ pub(crate) mod macos {
     use std::sync::Arc;
     use std::time::Duration;
 
-    use objc2::rc::Retained;
-    use objc2::AnyThread;
-    use objc2_avf_audio::{AVAudioFormat, AVAudioPCMBuffer};
     use objc2_foundation::NSProcessInfo;
     use serde::Serialize;
     use tauri::{AppHandle, Emitter};
@@ -260,7 +257,6 @@ pub(crate) mod macos {
     // ----------------------------------------------------------------------
     struct RawAudioForwarder {
         on_samples: Arc<dyn Fn(&[f32]) + Send + Sync>,
-        speech_format: Retained<AVAudioFormat>,
         app: AppHandle,
         cancelled: Arc<AtomicBool>,
         level_tick: Arc<AtomicU32>,
@@ -268,10 +264,8 @@ pub(crate) mod macos {
         source: &'static str,
     }
 
-    // SAFETY: `Retained<SFSpeech*>` and `Retained<AVAudioFormat>` wrap
-    // refcounted ObjC objects that Apple documents as message-thread-safe.
-    // SCK calls our handler from its own dispatch queue; we never alias
-    // these via `&` across threads.
+    // SAFETY: SCK calls this handler from its dispatch queue; all shared
+    // fields are immutable handles or atomics.
     unsafe impl Send for RawAudioForwarder {}
     unsafe impl Sync for RawAudioForwarder {}
 
@@ -287,30 +281,30 @@ pub(crate) mod macos {
             if self.cancelled.load(Ordering::SeqCst) {
                 return;
             }
-            let Some(buf) = build_pcm_buffer_from_sample(&sample_buffer, &self.speech_format)
+            let Some(samples) =
+                crate::native_screen::extract_mono_audio(&sample_buffer, self.source)
             else {
                 return;
             };
-            // Hand channel 0 (mono mix) to the callback continuously — no level
-            // gate, so the Whisper buffer stays a contiguous stream.
-            let frames = unsafe { buf.frameLength() } as usize;
-            if frames > 0 {
-                let ch_ptr = unsafe { buf.floatChannelData() };
-                if !ch_ptr.is_null() {
-                    let slice = unsafe { std::slice::from_raw_parts((*ch_ptr).as_ptr(), frames) };
-                    (self.on_samples)(slice);
-                }
-                let n = self.level_tick.fetch_add(1, Ordering::Relaxed);
-                if n % 3 == 0 {
-                    let level = crate::native_speech::macos::peak_level_for_pcm(&buf);
-                    let _ = self.app.emit(
-                        "voice:audio-level",
-                        AudioLevelPayload {
-                            level,
-                            source: self.source,
-                        },
-                    );
-                }
+            if samples.is_empty() {
+                return;
+            }
+            (self.on_samples)(&samples);
+            let n = self.level_tick.fetch_add(1, Ordering::Relaxed);
+            if n % 3 == 0 {
+                let level = samples
+                    .iter()
+                    .copied()
+                    .map(f32::abs)
+                    .fold(0.0_f32, f32::max)
+                    .min(1.0);
+                let _ = self.app.emit(
+                    "voice:audio-level",
+                    AudioLevelPayload {
+                        level,
+                        source: self.source,
+                    },
+                );
             }
         }
     }
@@ -448,19 +442,11 @@ pub(crate) mod macos {
             );
         }
 
-        // Mono float32 @ 48 kHz destination format for the mono-mix.
-        let speech_format = unsafe {
-            let allocated = AVAudioFormat::alloc();
-            AVAudioFormat::initStandardFormatWithSampleRate_channels(allocated, 48000.0, 1)
-        }
-        .ok_or_else(|| "AVAudioFormat init failed for raw system capture".to_string())?;
-
         let cancelled = Arc::new(AtomicBool::new(false));
         let mut stream = SCStream::new(&filter, &config);
         if let Some(on_samples) = on_system_samples {
             let forwarder = RawAudioForwarder {
                 on_samples,
-                speech_format: speech_format.clone(),
                 app: app.clone(),
                 cancelled: cancelled.clone(),
                 level_tick: Arc::new(AtomicU32::new(0)),
@@ -472,7 +458,6 @@ pub(crate) mod macos {
         if let Some(on_samples) = on_mic_samples {
             let forwarder = RawAudioForwarder {
                 on_samples,
-                speech_format,
                 app: app.clone(),
                 cancelled: cancelled.clone(),
                 level_tick: Arc::new(AtomicU32::new(0)),
@@ -495,96 +480,4 @@ pub(crate) mod macos {
         level: f32,
         source: &'static str,
     }
-
-    /// Pull the PCM bytes out of a SCK CMSampleBuffer and copy them into a
-    /// freshly-allocated AVAudioPCMBuffer matching `speech_format`
-    /// (single-channel float32 at the SCK sample rate). SCK delivers stereo
-    /// non-interleaved float32 by default — we mono-mix by averaging the
-    /// two channels. Returns `None` if the sample buffer's audio layout
-    /// can't be interpreted (rare; only happens if SCK changes its output
-    /// shape mid-stream).
-    fn build_pcm_buffer_from_sample(
-        sample: &CMSampleBuffer,
-        speech_format: &AVAudioFormat,
-    ) -> Option<Retained<AVAudioPCMBuffer>> {
-        let num_samples = sample.num_samples();
-        if num_samples == 0 {
-            return None;
-        }
-        let abl = sample.audio_buffer_list()?;
-        let n_buffers = abl.num_buffers();
-        if n_buffers == 0 {
-            return None;
-        }
-
-        // Allocate the destination buffer.
-        // SAFETY: standard AVAudioPCMBuffer init; we control the format and
-        // capacity.
-        #[allow(clippy::cast_possible_truncation)]
-        let frame_capacity = num_samples as u32;
-        let allocated = AVAudioPCMBuffer::alloc();
-        let dest = unsafe {
-            AVAudioPCMBuffer::initWithPCMFormat_frameCapacity(
-                allocated,
-                speech_format,
-                frame_capacity,
-            )
-        }?;
-        unsafe { dest.setFrameLength(frame_capacity) };
-
-        // SAFETY: the format is the one we constructed below — float, mono,
-        // non-interleaved — so `floatChannelData` is non-null and points at
-        // `channelCount=1` pointers, each to `frame_capacity` floats.
-        let dest_ch_ptr = unsafe { dest.floatChannelData() };
-        if dest_ch_ptr.is_null() {
-            return None;
-        }
-        let dest_slice =
-            unsafe { std::slice::from_raw_parts_mut((*dest_ch_ptr).as_ptr(), num_samples) };
-
-        if n_buffers >= 2 {
-            // Stereo non-interleaved — average the two channels.
-            let l = abl.get(0)?;
-            let r = abl.get(1)?;
-            let l_bytes = l.data();
-            let r_bytes = r.data();
-            // Treat as f32 little-endian (host byte order on every Apple
-            // platform we ship).
-            let l_floats = bytes_as_f32(l_bytes);
-            let r_floats = bytes_as_f32(r_bytes);
-            let n = num_samples.min(l_floats.len()).min(r_floats.len());
-            for i in 0..n {
-                dest_slice[i] = 0.5 * (l_floats[i] + r_floats[i]);
-            }
-            for v in dest_slice.iter_mut().take(num_samples).skip(n) {
-                *v = 0.0;
-            }
-        } else {
-            // Mono — just copy.
-            let only = abl.get(0)?;
-            let src = bytes_as_f32(only.data());
-            let n = num_samples.min(src.len());
-            dest_slice[..n].copy_from_slice(&src[..n]);
-            for v in dest_slice.iter_mut().take(num_samples).skip(n) {
-                *v = 0.0;
-            }
-        }
-
-        Some(dest)
-    }
-
-    /// Reinterpret a `&[u8]` as `&[f32]`. Length is rounded down to the
-    /// nearest multiple of 4. Safe because `f32` has no invalid
-    /// bit-patterns and the caller only uses the elements they're
-    /// indexing into.
-    fn bytes_as_f32(b: &[u8]) -> &[f32] {
-        let n = b.len() / 4;
-        if n == 0 {
-            return &[];
-        }
-        // SAFETY: `f32` is plain old data with alignment 4; CoreAudio's
-        // AudioBuffer pointers are 16-byte aligned in practice. We cap the
-        // length at `n` so we never read past the end.
-        unsafe { std::slice::from_raw_parts(b.as_ptr().cast::<f32>(), n) }
-    }
 }

package/corpus/templates/design/.generated/bridge/editor-chrome.generated.ts

@@ -3808,7 +3808,12 @@ export const editorChromeBridgeScript: string = `"use strict";
         'input, textarea, select, [contenteditable], [role="textbox"], [data-agent-native-text-editing]'
       );
     }
+    function isShowShortcutsChord(e) {
+      if (!(e.metaKey || e.ctrlKey) || !e.shiftKey || e.altKey) return false;
+      return e.key === "?" || e.key === "/";
+    }
     function shouldForwardDesignHotkey(e) {
+      if (isShowShortcutsChord(e)) return true;
       if (readOnly) return false;
       if (activeTextEditEl || isEditorTypingTarget(e.target) || e.isComposing)
         return false;

package/corpus/templates/design/app/components/design/KeyboardShortcutsPanel.tsx

@@ -25,6 +25,7 @@ import {
 } from "@/components/design/keyboard-shortcuts";
 import { Button } from "@/components/ui/button";
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
+import { isApplePlatform } from "@/hooks/useDesignHotkeys";
 
 interface KeyboardShortcutsPanelProps {
   onClose: () => void;
@@ -113,9 +114,10 @@ function KeycapGroup({
 
 function ShortcutBindings({ bindings }: { bindings: readonly string[] }) {
   const t = useT();
-  const applePlatform =
-    typeof navigator !== "undefined" &&
-    /Mac|iPhone|iPad/.test(navigator.platform);
+  // Shared with the hotkey matcher: navigator.platform alone is deprecated and
+  // blank in some browsers, which labelled Ctrl on Macs that the hotkey layer
+  // already treated as Apple.
+  const applePlatform = isApplePlatform();
   const accessibleBindings = bindings.map((binding) =>
     binding
       .split("+")

package/corpus/templates/design/app/components/design/bridge/editor-chrome.bridge.ts

@@ -5101,7 +5101,23 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
     );
   }
 
+  function isShowShortcutsChord(e) {
+    if (!(e.metaKey || e.ctrlKey) || !e.shiftKey || e.altKey) return false;
+    // macOS delivers Control+Shift+/ as "/" — Control suppresses the shifted
+    // character — while Windows sends "?". Match both; see
+    // isShowKeyboardShortcutsHotkey in useDesignHotkeys.ts.
+    return e.key === "?" || e.key === "/";
+  }
+
   function shouldForwardDesignHotkey(e) {
+    // Shortcut help is not an editing affordance, so it forwards ahead of the
+    // read-only and typing guards below — the host matcher is deliberately
+    // global for the same reason. Without this the chord never escapes the
+    // canvas iframe, which is where focus lands the moment you click a frame.
+    // Not reached during a live text-edit session: that block returns before
+    // this function runs, deliberately — see the activeTextEditEl guard in
+    // the keydown listener.
+    if (isShowShortcutsChord(e)) return true;
     // Read-only surfaces (e.g. background/inactive board screens) must never
     // forward edit hotkeys or preventDefault() native browser shortcuts —
     // Escape/Enter/Tab/Delete/arrow-key/undo-redo forwarding is an editing
@@ -11092,6 +11108,13 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
         }
         // While a live session exists, never forward hotkeys to the host
         // (matches shouldForwardDesignHotkey's activeTextEditEl guard).
+        // The shortcut-help chord is deliberately included in that exclusion:
+        // the panel lives in the parent document, so opening it moves focus
+        // out of the iframe, blurs the editable and commits the in-progress
+        // edit. Ending someone's text entry to show help is a worse trade
+        // than help being unavailable for the duration of a typing session;
+        // it stays available everywhere else, including while a text layer is
+        // merely selected.
         return;
       }
       if (!shouldForwardDesignHotkey(e)) return;

package/corpus/templates/design/app/components/design/keyboard-shortcuts.ts

@@ -49,6 +49,9 @@ export const DESIGN_SHORTCUTS: readonly DesignShortcutDefinition[] = [
   shortcut({
     id: "show-shortcuts",
     category: "essential",
+    // Literal ctrl, not $mod: on macOS ⌘⇧? is the system Help-menu shortcut and
+    // the browser consumes it before the page sees it, so ⌃⇧? is the only
+    // pressable binding there. Do not "fix" this to $mod.
     bindings: ["ctrl+shift+?"],
     labelKey: "designEditor.keyboardShortcuts.commands.showShortcuts",
     handler: "onShowKeyboardShortcuts",