@stigmer/react 3.12.1 → 3.12.3

package/src/session/useSessionPanel.ts

@@ -58,6 +58,37 @@ export interface UseSessionPanelOptions {
    * @default "files"
    */
   readonly defaultView?: string;
+  /**
+   * Controlled open state. When provided, the host owns whether the panel is
+   * expanded: internal open intents (the chip toggle, a file/artifact/plan
+   * open, plan auto-open) no longer flip state themselves — they surface
+   * through {@link UseSessionPanelOptions.onOpenChange} and the panel follows
+   * this value. Leave `undefined` for the self-managing default.
+   */
+  readonly open?: boolean;
+  /**
+   * Initial open state in uncontrolled mode. Ignored when
+   * {@link UseSessionPanelOptions.open} is provided.
+   *
+   * @default false
+   */
+  readonly defaultOpen?: boolean;
+  /**
+   * Called on every effective open/close transition — in BOTH modes, unlike
+   * `useDetailTabs`'s DD-T05A-001 convention of swallowing the callback when
+   * uncontrolled. The difference is principled, not stylistic: tabs change
+   * only through user clicks, so an uncontrolled host loses nothing by not
+   * hearing about them — but this panel opens ITSELF (`openFile`,
+   * `openArtifact`, `openPlanDocument`, and the plan-key auto-open all expand
+   * a collapsed panel), and an embedding host that must react to those
+   * moments (widen a dock, make room for a streaming plan) has no other seam.
+   * Passing only this callback observes the panel without controlling it.
+   *
+   * In controlled mode this fires once per open/close REQUEST (the host may
+   * decline by not updating `open` — a later identical request re-fires); in
+   * uncontrolled mode it fires once per actual transition.
+   */
+  readonly onOpenChange?: (open: boolean) => void;
 }
 
 /**
@@ -81,7 +112,11 @@ export interface UseSessionPanelOptions {
 export interface SessionPanelController {
   /** The open-editor group store; subscribe with `useWorkspaceEditors`. */
   readonly editorsStore: WorkspaceEditorsStore;
-  /** Whether the panel is expanded (chat narrow) or collapsed to the chip. */
+  /**
+   * Whether the panel is expanded (chat narrow) or collapsed to the chip.
+   * In controlled mode ({@link UseSessionPanelOptions.open}) this mirrors
+   * the host's value.
+   */
   readonly isOpen: boolean;
   /** The active rail view id (`"files"`, `"search"`, or an injected facet). */
   readonly view: string;
@@ -149,9 +184,49 @@ export function useSessionPanel({
   hasChanges,
   planKey = null,
   defaultView = "files",
+  open,
+  defaultOpen = false,
+  onOpenChange,
 }: UseSessionPanelOptions): SessionPanelController {
   const editorsStore = useWorkspaceEditorsStoreRef();
-  const [isOpen, setIsOpen] = useState(false);
+
+  // Uncontrolled-by-default / controlled-when-`open`-is-provided (React's own
+  // value/defaultValue convention — presence of the value prop decides, so an
+  // observe-only host can pass just `onOpenChange`). Everything below reads
+  // the EFFECTIVE value: the render-adjust triggers (first write-back) and
+  // the returned controller must agree with the host's state, never a stale
+  // internal one.
+  const isControlled = open !== undefined;
+  const [internalIsOpen, setInternalIsOpen] = useState(defaultOpen);
+  const isOpen = isControlled ? open : internalIsOpen;
+
+  // Latest-ref idiom (see YamlEditor's onChangeRef): the host's callback and
+  // the mode/value mirrors live in refs so `requestOpenChange` — and every
+  // action callback built on it — stays referentially stable regardless of
+  // how the host authored `onOpenChange` (DD-010: an inline lambda must not
+  // churn the memoized controller and re-render the panel subtree).
+  const onOpenChangeRef = useRef(onOpenChange);
+  onOpenChangeRef.current = onOpenChange;
+  const isControlledRef = useRef(isControlled);
+  isControlledRef.current = isControlled;
+  const isOpenRef = useRef(isOpen);
+  isOpenRef.current = isOpen;
+
+  // The single seam every open/close intent routes through — the chip
+  // toggle, file/artifact/plan opens, the surface's collapse affordance, and
+  // the plan-key auto-open. Uncontrolled: apply + notify (the ref is updated
+  // eagerly so two same-tick intents produce one notification). Controlled:
+  // notify only — the host owns the state, and the panel follows the `open`
+  // prop; the ref is NOT updated, so a declined request stays re-fireable.
+  const requestOpenChange = useCallback((next: boolean) => {
+    if (isOpenRef.current === next) return;
+    if (!isControlledRef.current) {
+      isOpenRef.current = next;
+      setInternalIsOpen(next);
+    }
+    onOpenChangeRef.current?.(next);
+  }, []);
+
   const [view, setViewState] = useState(defaultView);
 
   // Sticky explicit pick (rail click) — auto-switching yields to it until a
@@ -184,8 +259,8 @@ export function useSessionPanel({
 
   const openPlanDocument = useCallback(() => {
     editorsStore.openPinned(PLAN_DOCUMENT_ENTRY_ID, PLAN_DOCUMENT_PATH);
-    setIsOpen(true);
-  }, [editorsStore]);
+    requestOpenChange(true);
+  }, [editorsStore, requestOpenChange]);
 
   // A new plan arrived (first plan, or a refinement superseding it) → open the
   // plan document tab, expanding a collapsed panel (see the planKey option doc
@@ -204,9 +279,15 @@ export function useSessionPanel({
     }
   }, [planKey, openPlanDocument]);
 
-  const openPanel = useCallback(() => setIsOpen(true), []);
+  const openPanel = useCallback(
+    () => requestOpenChange(true),
+    [requestOpenChange],
+  );
 
-  const closePanel = useCallback(() => setIsOpen(false), []);
+  const closePanel = useCallback(
+    () => requestOpenChange(false),
+    [requestOpenChange],
+  );
 
   const setView = useCallback((viewId: string) => {
     userPickedViewRef.current = true;
@@ -216,17 +297,17 @@ export function useSessionPanel({
   const openFile = useCallback(
     (entryId: string, path: string, options?: OpenFileOptions) => {
       editorsStore.openPreview(entryId, path, options);
-      setIsOpen(true);
+      requestOpenChange(true);
     },
-    [editorsStore],
+    [editorsStore, requestOpenChange],
   );
 
   const openArtifact = useCallback(
     (artifact: ExecutionArtifact) => {
       editorsStore.openPreview(ARTIFACT_DOCUMENT_ENTRY_ID, artifactKey(artifact));
-      setIsOpen(true);
+      requestOpenChange(true);
     },
-    [editorsStore],
+    [editorsStore, requestOpenChange],
   );
 
   const pinArtifact = useCallback(

package/src/settings/ApiKeysSection.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, useRef, useState } from "react";
+import { useCallback, useId, useRef, useState } from "react";
 import type { ApiKey } from "@stigmer/protos/ai/stigmer/iam/apikey/v1/api_pb";
 import { ApiKeyListPanel } from "../api-key/ApiKeyListPanel.js";
 import { CreateApiKeyForm } from "../api-key/CreateApiKeyForm.js";
@@ -16,6 +16,7 @@ type FlowState =
 
 /** Settings section for listing and creating organization API keys. */
 export function ApiKeysSection() {
+  const headingId = useId();
   const org = useActiveOrgSlug();
   const apiKeysAvailable = useResourceAvailable(ApiResourceKind.api_key);
   const [flow, setFlow] = useState<FlowState>({ phase: "idle" });
@@ -37,10 +38,10 @@ export function ApiKeysSection() {
   }, []);
 
   return (
-    <section aria-labelledby="api-keys-heading">
+    <section aria-labelledby={headingId}>
       <div className="stg:mb-3 stg:flex stg:items-center stg:justify-between">
         <h2
-          id="api-keys-heading"
+          id={headingId}
           className="stg:text-foreground stg:text-sm stg:font-semibold"
         >
           API Keys

package/src/settings/ChannelAppsSection.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, useRef, useState } from "react";
+import { useCallback, useId, useRef, useState } from "react";
 import type { ChannelApp } from "@stigmer/protos/ai/stigmer/agentic/channelapp/v1/api_pb";
 import { ChannelAppListPanel } from "../channel-app/ChannelAppListPanel.js";
 import {
@@ -38,6 +38,7 @@ type FlowState =
  * Channels tab offers it as the serving app.
  */
 export function ChannelAppsSection() {
+  const headingId = useId();
   const org = useActiveOrgSlug();
   // Channel installs (the consumer of these credentials) are cloud-only;
   // gate the whole section the way the Channels tab gates connects.
@@ -72,10 +73,10 @@ export function ChannelAppsSection() {
   }, []);
 
   return (
-    <section aria-labelledby="channel-apps-heading">
+    <section aria-labelledby={headingId}>
       <div className="stg:mb-3 stg:flex stg:items-center stg:justify-between">
         <h2
-          id="channel-apps-heading"
+          id={headingId}
           className="stg:text-foreground stg:text-sm stg:font-semibold"
         >
           Channel Apps

package/src/settings/EnvironmentsSection.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useId, useRef, useState } from "react";
 import { getUserMessage } from "@stigmer/sdk";
 import { usePersonalEnvironment } from "../environment/usePersonalEnvironment.js";
 import { EnvironmentVariableEditor } from "../environment/EnvironmentVariableEditor.js";
@@ -47,12 +47,13 @@ function PersonalEnvironmentCard({ org }: { org: string }) {
   }, [org, isLoading, environment, getOrCreate]);
 
   const environmentId = environment?.metadata?.id;
+  const headingId = useId();
 
   return (
-    <section aria-labelledby="personal-env-heading">
+    <section aria-labelledby={headingId}>
       <div className="stg:mb-3 stg:flex stg:items-baseline stg:gap-2">
         <h2
-          id="personal-env-heading"
+          id={headingId}
           className="stg:text-foreground stg:text-sm stg:font-semibold"
         >
           Personal Environment
@@ -97,11 +98,13 @@ function EnvironmentsCard({ org }: { org: string }) {
     listRefetchRef.current?.();
   }, []);
 
+  const headingId = useId();
+
   return (
-    <section aria-labelledby="org-env-heading">
+    <section aria-labelledby={headingId}>
       <div className="stg:mb-3 stg:flex stg:items-center stg:justify-between">
         <h2
-          id="org-env-heading"
+          id={headingId}
           className="stg:text-foreground stg:text-sm stg:font-semibold"
         >
           Environments

package/src/settings/IdentityProvidersSection.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, useRef, useState } from "react";
+import { useCallback, useId, useRef, useState } from "react";
 import type { IdentityProvider } from "@stigmer/protos/ai/stigmer/iam/identityprovider/v1/api_pb";
 import { IdentityProviderListPanel } from "../identity-provider/IdentityProviderListPanel.js";
 import { IdentityProviderWizard } from "../identity-provider/IdentityProviderWizard.js";
@@ -28,6 +28,7 @@ type FlowState =
 export function IdentityProvidersSection({
   ssoLoginBaseUrl,
 }: IdentityProvidersSectionProps = {}) {
+  const headingId = useId();
   const { activeOrg } = useOrg();
   const idpAvailable = useResourceAvailable(ApiResourceKind.identity_provider);
   const orgSlug = activeOrg?.metadata?.slug ?? "";
@@ -54,10 +55,10 @@ export function IdentityProvidersSection({
     (typeof window !== "undefined" ? window.location.origin : "");
 
   return (
-    <section aria-labelledby="identity-providers-heading">
+    <section aria-labelledby={headingId}>
       <div className="stg:mb-3 stg:flex stg:items-center stg:justify-between">
         <h2
-          id="identity-providers-heading"
+          id={headingId}
           className="stg:text-foreground stg:text-sm stg:font-semibold"
         >
           Identity Providers

package/src/settings/InvitationsSection.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { useId } from "react";
 import { InvitationManager } from "../invitation/InvitationManager.js";
 import { useResourceAvailable, ApiResourceKind } from "../deployment-mode.js";
 import { CloudFeatureNotice } from "../internal/CloudFeatureNotice.js";
@@ -7,14 +8,15 @@ import { useActiveOrgSlug } from "../organization/OrgProvider.js";
 
 /** Settings section for creating and managing organization invitations. */
 export function InvitationsSection() {
+  const headingId = useId();
   const org = useActiveOrgSlug();
   const invitationsAvailable = useResourceAvailable(ApiResourceKind.invitation);
 
   return (
-    <section aria-labelledby="invitations-heading">
+    <section aria-labelledby={headingId}>
       <div className="stg:mb-3">
         <h2
-          id="invitations-heading"
+          id={headingId}
           className="stg:text-foreground stg:text-sm stg:font-semibold"
         >
           Invitations

package/src/settings/MembersSection.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { useId } from "react";
 import { OrgMembersPanel } from "../iam-policy/OrgMembersPanel.js";
 import { useResourceAvailable, ApiResourceKind } from "../deployment-mode.js";
 import { CloudFeatureNotice } from "../internal/CloudFeatureNotice.js";
@@ -8,6 +9,7 @@ import { useIdentityProviderList } from "../identity-provider/useIdentityProvide
 
 /** Settings section for organization membership and role management. */
 export function MembersSection() {
+  const headingId = useId();
   const { activeOrg } = useOrg();
   const membersAvailable = useResourceAvailable(ApiResourceKind.iam_policy);
   const idpAvailable = useResourceAvailable(ApiResourceKind.identity_provider);
@@ -23,9 +25,9 @@ export function MembersSection() {
   );
 
   return (
-    <section aria-labelledby="members-heading">
+    <section aria-labelledby={headingId}>
       <h2
-        id="members-heading"
+        id={headingId}
         className="stg:text-foreground stg:mb-1 stg:text-sm stg:font-semibold"
       >
         Members

package/src/settings/OAuthAppsSection.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, useRef, useState } from "react";
+import { useCallback, useId, useRef, useState } from "react";
 import type { OAuthApp } from "@stigmer/protos/ai/stigmer/iam/oauthapp/v1/api_pb";
 import { OAuthAppListPanel } from "../oauth-app/OAuthAppListPanel.js";
 import { CreateOAuthAppForm } from "../oauth-app/CreateOAuthAppForm.js";
@@ -16,6 +16,7 @@ type FlowState =
 
 /** Settings section for organization OAuth app credentials. */
 export function OAuthAppsSection() {
+  const headingId = useId();
   const org = useActiveOrgSlug();
   const oauthAppsAvailable = useResourceAvailable(ApiResourceKind.oauth_app);
 
@@ -42,10 +43,10 @@ export function OAuthAppsSection() {
   }, []);
 
   return (
-    <section aria-labelledby="oauth-apps-heading">
+    <section aria-labelledby={headingId}>
       <div className="stg:mb-3 stg:flex stg:items-center stg:justify-between">
         <h2
-          id="oauth-apps-heading"
+          id={headingId}
           className="stg:text-foreground stg:text-sm stg:font-semibold"
         >
           OAuth Apps

package/src/settings/OrgProfileSection.tsx

@@ -1,12 +1,13 @@
 "use client";
 
-import { useCallback } from "react";
+import { useCallback, useId } from "react";
 import type { Organization } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/api_pb";
 import { OrgProfilePanel } from "../organization/OrgProfilePanel.js";
 import { useOrg } from "../organization/OrgProvider.js";
 
 /** Settings section for editing the active organization profile. */
 export function OrgProfileSection() {
+  const headingId = useId();
   const { activeOrg, refresh } = useOrg();
   const orgId = activeOrg?.metadata?.id ?? "";
 
@@ -18,9 +19,9 @@ export function OrgProfileSection() {
   );
 
   return (
-    <section aria-labelledby="org-profile-heading">
+    <section aria-labelledby={headingId}>
       <h2
-        id="org-profile-heading"
+        id={headingId}
         className="stg:text-foreground stg:mb-1 stg:text-sm stg:font-semibold"
       >
         Organization Profile

package/src/settings/PlatformClientsSection.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, useRef, useState } from "react";
+import { useCallback, useId, useRef, useState } from "react";
 import type { PlatformClient } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/api_pb";
 import type { PlatformClientCreateResponse } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/io_pb";
 import { PlatformClientListPanel } from "../platform-client/PlatformClientListPanel.js";
@@ -24,6 +24,7 @@ type FlowState =
 
 /** Settings section for creating and maintaining platform clients. */
 export function PlatformClientsSection() {
+  const headingId = useId();
   const org = useActiveOrgSlug();
   const pcAvailable = useResourceAvailable(ApiResourceKind.platform_client);
 
@@ -71,10 +72,10 @@ export function PlatformClientsSection() {
   }, []);
 
   return (
-    <section aria-labelledby="platform-clients-heading">
+    <section aria-labelledby={headingId}>
       <div className="stg:mb-3 stg:flex stg:items-center stg:justify-between">
         <h2
-          id="platform-clients-heading"
+          id={headingId}
           className="stg:text-foreground stg:text-sm stg:font-semibold"
         >
           Platform Clients

package/src/settings/UsageSection.tsx

@@ -1,17 +1,19 @@
 "use client";
 
+import { useId } from "react";
 import { OrgUsagePanel } from "../usage/OrgUsagePanel.js";
 import { useOrg } from "../organization/OrgProvider.js";
 
 /** Settings section for organization usage and cost reporting. */
 export function UsageSection() {
+  const headingId = useId();
   const { activeOrg } = useOrg();
   const orgId = activeOrg?.metadata?.id ?? "";
 
   return (
-    <section aria-labelledby="usage-heading">
+    <section aria-labelledby={headingId}>
       <h2
-        id="usage-heading"
+        id={headingId}
         className="stg:text-foreground stg:mb-1 stg:text-sm stg:font-semibold"
       >
         Usage

package/src/sharing/ShareAgentDialog.tsx

@@ -1,7 +1,8 @@
 "use client";
 
-import { useCallback, useMemo, useRef, useState, type FormEvent } from "react";
+import { useCallback, useId, useMemo, useRef, useState, type FormEvent } from "react";
 import { cn } from "@stigmer/theme";
+import { DialogShell } from "../internal/DialogShell.js";
 import {
   MAX_ALLOWED_ORIGINS,
   StigmerError,
@@ -137,40 +138,23 @@ export function ShareAgentDialog({
   onSharingChanged,
   modal = true,
 }: ShareAgentDialogProps) {
-  const dialogRef = useRef<HTMLDialogElement>(null);
+  // Instance-scoped title id (oss#593): a reusable component must not
+  // hardcode DOM ids — hosts legitimately mount this dialog more than once
+  // per page (e.g. zone-cached detail pages), and duplicate ids break the
+  // aria-labelledby association for every copy after the first.
+  const titleId = useId();
 
   const handleClose = useCallback(() => {
-    dialogRef.current?.close();
     onOpenChange(false);
   }, [onOpenChange]);
 
-  // Sync native dialog open state (matches the SDK dialog convention).
-  // Non-modal hosts pass `open` as a plain attribute instead — the dialog
-  // renders in-flow with no top layer to manage.
-  const prevOpenRef = useRef(false);
-  if (modal && open !== prevOpenRef.current) {
-    prevOpenRef.current = open;
-    if (open) {
-      requestAnimationFrame(() => {
-        if (dialogRef.current && !dialogRef.current.open) {
-          dialogRef.current.showModal();
-        }
-      });
-    } else if (dialogRef.current?.open) {
-      dialogRef.current.close();
-    }
-  }
-
   return (
-    <dialog
-      ref={dialogRef}
-      open={modal ? undefined : open}
-      onClose={handleClose}
-      className={cn(
-        "stg:w-full stg:max-w-lg stg:rounded-xl stg:border stg:border-border stg:bg-popover stg:p-0 stg:shadow-xl",
-        modal ? "stg:fixed stg:inset-0 stg:m-auto stg:backdrop:bg-black/50" : "stg:relative",
-      )}
-      aria-labelledby="share-agent-title"
+    <DialogShell
+      open={open}
+      onOpenChange={onOpenChange}
+      modal={modal}
+      width="lg"
+      aria-labelledby={titleId}
     >
       {/* Body mounts only while open so its draft state resets per
           session — reopening the dialog never shows a stale draft. */}
@@ -182,9 +166,10 @@ export function ShareAgentDialog({
           buildShareUrl={buildShareUrl}
           onSharingChanged={onSharingChanged}
           onClose={handleClose}
+          titleId={titleId}
         />
       )}
-    </dialog>
+    </DialogShell>
   );
 }
 
@@ -207,6 +192,7 @@ function ShareAgentDialogBody({
   buildShareUrl,
   onSharingChanged,
   onClose,
+  titleId,
 }: {
   readonly agent: Agent;
   readonly share: AgentShare | null;
@@ -214,6 +200,8 @@ function ShareAgentDialogBody({
   readonly buildShareUrl?: (org: string, slug: string) => string;
   readonly onSharingChanged?: () => void;
   readonly onClose: () => void;
+  /** Heading id minted by the outer dialog for its aria-labelledby. */
+  readonly titleId: string;
 }) {
   const [created, setCreated] = useState<AgentShare | null>(null);
   const activeShare = share ?? created;
@@ -229,7 +217,7 @@ function ShareAgentDialogBody({
       <div className="stg:flex stg:items-start stg:justify-between stg:border-b stg:border-border stg:px-6 stg:py-4">
         <div className="stg:min-w-0">
           <h2
-            id="share-agent-title"
+            id={titleId}
             className="stg:text-base stg:font-semibold stg:text-foreground"
           >
             {isCreating ? "Create share" : "Share"}
@@ -322,6 +310,11 @@ function CreateShareForm({
   const agentName = agent.metadata?.name || (agent.metadata?.slug ?? "");
   const isCrossOrg = shareOrg !== (agent.metadata?.org ?? "");
 
+  // Instance-scoped field ids (oss#593) — see the outer dialog's titleId.
+  const baseId = useId();
+  const nameId = `${baseId}-name`;
+  const slugId = `${baseId}-slug`;
+
   const [name, setName] = useState(agentName);
   const [slug, setSlug] = useState(agent.metadata?.slug ?? "");
   // Once the user manually edits the slug field, stop auto-deriving.
@@ -421,13 +414,13 @@ function CreateShareForm({
       {/* ---- Name ---- */}
       <div className="stg:space-y-1">
         <label
-          htmlFor="stgm-new-share-name"
+          htmlFor={nameId}
           className="stg:text-xs stg:font-medium stg:text-foreground"
         >
           Name
         </label>
         <input
-          id="stgm-new-share-name"
+          id={nameId}
           type="text"
           value={name}
           onChange={(e) => handleNameChange(e.target.value)}
@@ -457,13 +450,13 @@ function CreateShareForm({
       {/* ---- Slug ---- */}
       <div className="stg:space-y-1">
         <label
-          htmlFor="stgm-new-share-slug"
+          htmlFor={slugId}
           className="stg:text-xs stg:font-medium stg:text-foreground"
         >
           Slug
         </label>
         <input
-          id="stgm-new-share-slug"
+          id={slugId}
           type="text"
           value={slug}
           onChange={(e) => handleSlugChange(e.target.value)}
@@ -533,6 +526,9 @@ function ShareAgentForm({
 }) {
   const agentName = agent.metadata?.name || (agent.metadata?.slug ?? "");
 
+  // Instance-scoped label id (oss#593) — see the outer dialog's titleId.
+  const enabledLabelId = useId();
+
   // The latest server share is the single baseline: the draft, the link
   // token, and the share id for rotation all derive from it.
   const [share, setShare] = useState<AgentShare>(initialShare);
@@ -644,7 +640,7 @@ function ShareAgentForm({
         <div className="stg:flex stg:items-start stg:justify-between stg:gap-4">
           <div className="stg:min-w-0">
             <span
-              id="share-enabled-label"
+              id={enabledLabelId}
               className="stg:text-sm stg:font-medium stg:text-foreground"
             >
               {isOrgAudience
@@ -657,7 +653,7 @@ function ShareAgentForm({
             checked={draft.enabled}
             onCheckedChange={handleToggle}
             disabled={isPending}
-            aria-labelledby="share-enabled-label"
+            aria-labelledby={enabledLabelId}
           />
         </div>
         {!isCrossOrg && (

package/src/sidebar/__tests__/WorkspaceSidebar.test.tsx

@@ -274,7 +274,10 @@ describe("WorkspaceSidebar — chrome", () => {
     expect(screen.getByTestId("footer-slot")).toBeTruthy();
     const toggle = screen.getByLabelText("Collapse sidebar");
     expect(toggle.getAttribute("aria-expanded")).toBe("false");
-    expect(toggle.getAttribute("aria-controls")).toBe("sidebar");
+    // The nav id is minted per mount; assert the association, not the value.
+    const controlsId = toggle.getAttribute("aria-controls");
+    expect(controlsId).toBeTruthy();
+    expect(document.getElementById(controlsId!)?.tagName).toBe("NAV");
   });
 
   it("resolves the org switcher from the mocked transport", async () => {

package/src/sidebar/chrome.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import type { ReactNode } from "react";
+import { useId, type ReactNode } from "react";
 import { PanelLeft } from "lucide-react";
 import { cn } from "@stigmer/theme";
 import type { Organization } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/api_pb";
@@ -46,9 +46,8 @@ export interface SidebarChromeProps {
 /**
  * Outer sidebar frame: `<nav>` container, top row, content, footer band.
  *
- * The `id="sidebar"` / `aria-controls` pairing matches the console's DOM
- * contract (the app shell's floating "Open sidebar" button targets it);
- * only one sidebar renders at a time, so the id cannot collide.
+ * The nav id exists solely for the collapse toggle's `aria-controls`
+ * association; it is minted per mount like every SDK DOM id.
  */
 export function SidebarChrome({
   ariaLabel,
@@ -58,9 +57,10 @@ export function SidebarChrome({
   footer,
   children,
 }: SidebarChromeProps) {
+  const navId = useId();
   return (
     <nav
-      id="sidebar"
+      id={navId}
       aria-label={ariaLabel}
       className="stg:bg-sidebar stg:text-sidebar-foreground stg:flex stg:h-full stg:flex-col"
     >
@@ -70,7 +70,7 @@ export function SidebarChrome({
           type="button"
           onClick={onCollapse}
           aria-expanded={isOpen}
-          aria-controls="sidebar"
+          aria-controls={navId}
           aria-label="Collapse sidebar"
           className={cn(
             "stg:inline-flex stg:size-7 stg:shrink-0 stg:items-center stg:justify-center stg:rounded-md",