Merge remote-tracking branch 'origin/master' into feat/scrollbar-tokens

packages/client/ui-settings/src/client/SettingsRoot.tsx

@@ -10,7 +10,7 @@
 import { useCallback, useEffect, useId, useRef, useState } from 'react'
 import clsx from 'clsx'
 import { IconCloseOutline16, IconDataOutline16, IconSettingsOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
-import type { SettingsRootComponentProps } from './contract/slots.ts'
+import type { SettingsRootComponentProps, SettingsSectionRow } from './contract/slots.ts'
 import css from './SettingsRoot.module.css'
 
 /** Nav glyph by section id; unknown ids fall back to the settings gear. */
@@ -20,7 +20,7 @@ function navIcon(id: string) {
 }
 
 type PanelProps = {
-  rows: ReturnType<SettingsRootComponentProps['sections']>
+  rows: readonly SettingsSectionRow[]
   renderSlot: SettingsRootComponentProps['renderSlot']
   onClose: () => void
 }
@@ -92,20 +92,14 @@ function SettingsPanel({ rows, renderSlot, onClose }: PanelProps) {
  * @returns the settings shell element tree.
  */
 export function SettingsRoot(props: SettingsRootComponentProps) {
-  const { wide, subscribeSections, sectionsVersion, sections, renderSlot } = props
+  const { wide, useSections, renderSlot } = props
   const [open, setOpen] = useState(false)
   const close = useCallback(() => { setOpen(false) }, [])
 
   // The ledger tick keeps the nav rows fresh: registrants re-register with
   // freshly localized text on locale change, and the trigger/header/close
   // seats re-render through their own outlets' subscriptions.
-  // State = ledger version: same-version notifications dedupe to no render.
-  const [, setSectionsRev] = useState(() => sectionsVersion())
-  useEffect(
-    () => subscribeSections(() => { setSectionsRev(sectionsVersion()) }),
-    [subscribeSections, sectionsVersion],
-  )
-  const rows = sections()
+  const rows = useSections(s => s)
 
   return (
     <>

packages/client/ui-settings/src/client/contract/slots.ts

@@ -7,7 +7,7 @@
  * setting never means editing the shell; copy that belongs to no single
  * feature (chrome, the General section) is owned by ui-settings-general.
  */
-import type { PropsRenderSlots, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import type { HostObservable, InjectFace, PropsRenderSlots, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
 // Type-only: pulls ui-sidebar's SlotMap merge (the 'sidebar.settings' entry)
 // into every program that sees this contract.
 import type {} from '@deepseek-ai/dsh-client-ui-sidebar/client'
@@ -72,26 +72,32 @@ export interface SettingsSectionOwnerProps {
   children?: never
 }
 
+/** One nav row projected from a settings.section registration's options. */
+export interface SettingsSectionRow {
+  id: string
+  order: number
+  label: string
+}
+
 /**
  * Registrant-private injected share of the settings shell (assembled in
- * apply): ledger projections only — the shell reads no locale state.
+ * apply): the ledger's nav-row projection as a hooks-compartment source —
+ * the shell reads no locale state and subscribes through the bound hook.
  */
 export type SettingsRootInjected = {
-  /** Read the settings.section ledger version (nav invalidation). */
-  sectionsVersion: () => number
-  /** Subscribe to settings.section ledger changes. */
-  subscribeSections: (listener: () => void) => () => void
-  /** Project the settings.section ledger into nav rows (id/order/label). */
-  sections: () => readonly { id: string; order: number; label: string }[]
+  hooks: {
+    /** settings.section ledger projected into ordered nav rows. */
+    sections: HostObservable<readonly SettingsSectionRow[]>
+  }
 }
 
 /**
  * Full component props of the settings shell root: the sidebar owner share
- * (wide/rail state) plus the declared render shares and the injected face.
- * No store is registered — modal open state and active section id are
- * component-local viewing state.
+ * (wide/rail state) plus the declared render shares and the injected face
+ * (hooks compartment bound to useSections). No store is registered — modal
+ * open state and active section id are component-local viewing state.
  */
 export type SettingsRootComponentProps =
   PropsRuntime<'sidebar.settings'>
   & PropsRenderSlots<'settings.trigger' | 'settings.header' | 'settings.close' | 'settings.section'>
-  & SettingsRootInjected
+  & InjectFace<SettingsRootInjected>

packages/client/ui-settings/src/client/index.ts

@@ -10,12 +10,12 @@
  */
 import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
 import { deferRegistration } from '@deepseek-ai/dsh-client-ui-slots'
-import type { SettingsRootInjected } from './contract/slots.ts'
+import type { SettingsRootInjected, SettingsSectionRow } from './contract/slots.ts'
 import { SettingsRoot } from './SettingsRoot.tsx'
 
 export type {
   SettingsHeaderOwnerProps, SettingsRootComponentProps, SettingsRootInjected,
-  SettingsSectionOwnerProps, SettingsTriggerOwnerProps,
+  SettingsSectionOwnerProps, SettingsSectionRow, SettingsTriggerOwnerProps,
 } from './contract/slots.ts'
 
 /**
@@ -32,17 +32,31 @@ export const inject = ['slots']
  * @param ctx - client root context.
  */
 export function apply(ctx: ClientContext): void {
+  // Ledger → nav-row projection as an observable source (uSES contract:
+  // getSnapshot returns the cached rows until the ledger version moves).
+  let rowsVersion = -1
+  let rows: readonly SettingsSectionRow[] = []
   const injected = (): SettingsRootInjected => ({
-    sectionsVersion: () => ctx.slots.getVersion('settings.section'),
-    subscribeSections: listener => ctx.slots.subscribe('settings.section', listener),
-    sections: () => ctx.slots.entries('settings.section')
-      .map(e => ({
-        /* v8 ignore next -- list-slot registration requires id (SlotCore rejects an entry without one) */
-        id: e.options.id ?? '',
-        order: e.options.order ?? 0,
-        label: e.options.label ?? '',
-      }))
-      .sort((a, b) => a.order - b.order),
+    hooks: {
+      sections: {
+        getSnapshot: () => {
+          const version = ctx.slots.getVersion('settings.section')
+          if (version !== rowsVersion) {
+            rowsVersion = version
+            rows = ctx.slots.entries('settings.section')
+              .map(e => ({
+                /* v8 ignore next -- list-slot registration requires id (SlotCore rejects an entry without one) */
+                id: e.options.id ?? '',
+                order: e.options.order ?? 0,
+                label: e.options.label ?? '',
+              }))
+              .sort((a, b) => a.order - b.order)
+          }
+          return rows
+        },
+        subscribe: listener => ctx.slots.subscribe('settings.section', listener),
+      },
+    },
   })
   ctx.effect(() => {
     const deferred = deferRegistration(ctx.slots, 'sidebar.settings', SettingsRoot, () =>

packages/client/ui-settings/tests/apply.spec.ts

@@ -60,22 +60,25 @@ describe('ui-settings apply', () => {
     const b = await bench()
     declare(b.slots)
     await b.ctx.plugin({ inject: [...inject], apply }).await()
-    const injected = injectedOf(b.slots)
+    const { sections } = injectedOf(b.slots).hooks
     // The shell ships no sections of its own — registrants fill the ledger.
-    expect(injected.sections()).toEqual([])
+    expect(sections.getSnapshot()).toEqual([])
     b.slots.register({ name: 'settings.section', id: 'z', order: 20, label: 'Z' } as never, () => null)
     // No order and no label: both projection defaults apply.
     b.slots.register({ name: 'settings.section', id: 'a' } as never, () => null)
-    expect(injected.sections()).toEqual([
+    const rows = sections.getSnapshot()
+    expect(rows).toEqual([
       { id: 'a', order: 0, label: '' },
       { id: 'z', order: 20, label: 'Z' },
     ])
-    expect(injected.sectionsVersion()).toBe(b.slots.getVersion('settings.section'))
+    // Snapshot identity is stable until the ledger moves (uSES contract).
+    expect(sections.getSnapshot()).toBe(rows)
     const listener = vi.fn()
-    const off = injected.subscribeSections(listener)
+    const off = sections.subscribe(listener)
     b.slots.register({ name: 'settings.section', id: 'b', order: 1, label: 'B' } as never, () => null)
     await Promise.resolve()
     expect(listener).toHaveBeenCalled()
+    expect(sections.getSnapshot()).not.toBe(rows)
     off()
   })
 

packages/client/ui-settings/tests/settings-root.spec.tsx

@@ -1,5 +1,6 @@
 // @vitest-environment jsdom
 import { afterEach, describe, expect, it, vi } from 'vitest'
+import { useEffect, useState } from 'react'
 import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
 import type { SettingsRootComponentProps } from '../src/client/contract/slots.ts'
 import { SettingsRoot } from '../src/client/SettingsRoot.tsx'
@@ -22,9 +23,9 @@ function mount({
     { id: 'models', order: 10, label: 'Models' },
   ],
 }: { wide?: boolean; rows?: Row[] } = {}) {
-  // Mutable row store standing in for the ledger; bump() plays a change.
+  // Mutable row source standing in for the bound useSections hook; bump()
+  // plays a ledger change through the same observable contract.
   let current = rows
-  let version = 0
   const listeners = new Set<() => void>()
   const renderSlot = vi.fn(
     ((key: string, _owner: unknown, opts?: { only?: string }) => {
@@ -38,19 +39,21 @@ function mount({
     useSessions: unusedHook,
     useWorkspaces: unusedHook,
     wide,
-    sectionsVersion: () => version,
-    subscribeSections: (listener) => {
-      listeners.add(listener)
-      return () => { listeners.delete(listener) }
+    useSections: (select) => {
+      const [, force] = useState(0)
+      useEffect(() => {
+        const listener = () => { force(n => n + 1) }
+        listeners.add(listener)
+        return () => { listeners.delete(listener) }
+      }, [])
+      return select(current)
     },
-    sections: () => current,
     renderSlot,
   }
   const view = render(<SettingsRoot {...props} />)
   const bump = (next: Row[]) => {
     act(() => {
       current = next
-      version += 1
       for (const fn of [...listeners]) fn()
     })
   }