@lynn123411/dsh-model-submenu 0.3.5 → 0.3.10

package/src/client/ModelRow.tsx

@@ -1,51 +1,44 @@
 /**
- * One pickable model, as both surfaces render it.
+ * One pickable model in the picker.
  *
- * The menu row is one button that spans the whole width — name, favorite mark,
- * and the check for the model in use all live inside it, so hovering any part of
- * the row (including the star) highlights the row and clicking any part picks
- * the model. The picker row keeps the same shape but lifts the star out into its
- * own control, because favouriting there must not switch the model.
+ * The star is its own control, because favouriting there must not switch the
+ * model: the row button picks, the star toggles, and the check marks the model
+ * in use.
  */
 
-import type { ReactNode } from 'react'
-import { IconCheckOutlineRegular } from '@deepseek-ai/dsh-client-ui-primitives'
-import { StarIcon } from './icons.tsx'
-import css from './ModelSubmenu.module.css'
+import type { ReactNode } from 'react';
+import { IconCheckOutlineRegular } from '@deepseek-ai/dsh-client-ui-primitives';
+import { StarIcon } from './icons.tsx';
+import css from './ModelOptions.module.css';
 
-/** How one row shows its favorite mark: part of the row, or a control of its own. */
-export type StarMode = 'static' | 'interactive'
-
-/** Props shared by both row shapes. */
+/** Props of one row. */
 export interface ModelRowProps {
   /** The model's catalog name. */
-  readonly name: string
+  readonly name: string;
   /** Optional catalog badge shown beside the name. */
-  readonly badge?: ReactNode | undefined
+  readonly badge?: ReactNode | undefined;
   /** Whether this row is the model in use. */
-  readonly selected: boolean
+  readonly selected: boolean;
   /** Whether a selection is in flight, which locks the row. */
-  readonly busy: boolean
-  /** How the favorite mark behaves on this row. */
-  readonly star: StarMode
+  readonly busy: boolean;
   /** Whether the model is favorited right now. */
-  readonly favorited: boolean
-  /** The metadata line's text; undefined in the menu. */
-  readonly meta?: string | undefined
+  readonly favorited: boolean;
+  /** The metadata line's text. */
+  readonly meta?: string | undefined;
   /** Localized accessible name for the star control. */
-  readonly starLabel?: string | undefined
+  readonly starLabel?: string | undefined;
   /** Whether the star is a Tab stop right now (the picker's roving highlight). */
-  readonly starTabStop?: boolean
+  readonly starTabStop?: boolean;
   /** Tab order of the row itself; the picker keeps rows out of it so ↑/↓ own the walk. */
-  readonly rowTabIndex?: number
+  readonly rowTabIndex?: number;
   /** Pick this row. */
-  readonly onPick: () => void
+  readonly onPick: () => void;
   /** The row took the keyboard, so its star becomes reachable. */
-  readonly onFocusRow?: (() => void) | undefined
-  /** Toggle this row's favorite; absent when the star is part of the row. */
-  readonly onToggleFavorite?: (() => void) | undefined
+  readonly onFocusRow?: (() => void) | undefined;
+  /** Toggle this row's favorite. */
+  readonly onToggleFavorite: () => void;
   /** Extra row content, such as the picker's disabled reason. */
-  readonly children?: ReactNode
+  readonly children?: ReactNode;
 }
 
 /**
@@ -54,77 +47,43 @@ export interface ModelRowProps {
  * @returns the row element.
  */
 export function ModelRow({
-  name, badge, selected, busy, star, favorited, meta, starLabel,
+  name, badge, selected, busy, favorited, meta, starLabel,
   starTabStop = false, rowTabIndex, onPick, onFocusRow, onToggleFavorite, children,
 }: ModelRowProps) {
-  const copy = (
-    <>
+  return <div
+    className={css.row}
+    data-selected={selected ? '' : undefined}
+    data-favorited={favorited ? '' : undefined}
+  >
+    <button
+      type="button"
+      role="menuitemradio"
+      aria-checked={selected}
+      tabIndex={rowTabIndex}
+      className={css.rowPick}
+      title={name}
+      disabled={busy}
+      onClick={onPick}
+      onFocus={onFocusRow}
+    >
       <span className={css.rowCopy}>
         <span className={css.rowName}>{name}</span>
         {badge}
         {meta !== undefined && meta !== '' && <span className={css.rowMeta}>{meta}</span>}
       </span>
-    </>
-  )
-  const mark = favorited ? <StarIcon filled className={css.star} /> : null
-
-  // The menu's row is one target: the star and the check sit inside the button,
-  // so they inherit its hover fill and its click.
-  if (star === 'static') {
-    return (
-      <button
-        type="button"
-        role="menuitemradio"
-        aria-checked={selected}
-        tabIndex={rowTabIndex}
-        className={css.rowPick}
-        title={name}
-        disabled={busy}
-        onClick={onPick}
-        onFocus={onFocusRow}
-        data-selected={selected ? '' : undefined}
-        data-favorited={favorited ? '' : undefined}
-      >
-        {copy}
-        {mark !== null && <span className={css.starStatic} aria-hidden="true">{mark}</span>}
-        <span className={css.check} aria-hidden={!selected}>{selected ? <IconCheckOutlineRegular /> : null}</span>
-        {children}
-      </button>
-    )
-  }
-
-  return (
-    <div
-      className={css.row}
-      data-selected={selected ? '' : undefined}
-      data-favorited={favorited ? '' : undefined}
+    </button>
+    <button
+      type="button"
+      className={css.starButton}
+      aria-pressed={favorited}
+      aria-label={starLabel}
+      tabIndex={starTabStop ? 0 : -1}
+      disabled={busy}
+      onClick={onToggleFavorite}
     >
-      <button
-        type="button"
-        role="menuitemradio"
-        aria-checked={selected}
-        tabIndex={rowTabIndex}
-        className={css.rowPick}
-        title={name}
-        disabled={busy}
-        onClick={onPick}
-        onFocus={onFocusRow}
-      >
-        {copy}
-      </button>
-      <button
-        type="button"
-        className={css.starButton}
-        aria-pressed={favorited}
-        aria-label={starLabel}
-        tabIndex={starTabStop ? 0 : -1}
-        disabled={busy}
-        onClick={onToggleFavorite}
-      >
-        <StarIcon filled={favorited} className={css.star} />
-      </button>
-      <span className={css.check} aria-hidden={!selected}>{selected ? <IconCheckOutlineRegular /> : null}</span>
-      {children}
-    </div>
-  )
+      <StarIcon filled={favorited} className={css.star} />
+    </button>
+    <span className={css.check} aria-hidden={!selected}>{selected ? <IconCheckOutlineRegular /> : null}</span>
+    {children}
+  </div>;
 }

package/src/client/index.ts

@@ -1,6 +1,6 @@
 import type { Context as ClientContext } from '@deepseek-ai/cordis'
 // Type-only: `slots` and its LocaleNamespaceMap merge come from the renderer and
-// the slot package; the composer seat's SlotMap entry and owner props from
+// the slot package; the model menu's options slot and the composer overlay from
 // ui-conversation; the `modelDirectories` service and the seat's injected face
 // from ui-model-selection's browser half; `configForms` from the settings
 // provider, whose shared mirror answers the metadata line.
@@ -10,16 +10,22 @@ import type {} from '@deepseek-ai/dsh-api-remotes/client'
 import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type {} from '@deepseek-ai/dsh-client-ui-model-selection/client'
 import type {} from '@deepseek-ai/dsh-client-ui-settings/client'
-import { ModelSubmenu } from './ModelSubmenu.tsx'
+import { EffortTint } from './EffortTint.tsx'
+import { ModelMenuBridge } from './ModelMenuBridge.tsx'
+import { ModelPickerHost } from './ModelPickerHost.tsx'
+import { createPickerStore } from './picker-state.ts'
 import { createFactsSource, type DescribeFace } from './facts-source.ts'
 import { NS, en, zh } from './locales.ts'
 
-export { ModelSubmenu } from './ModelSubmenu.tsx'
+export { EffortTint } from './EffortTint.tsx'
+export { ModelMenuBridge } from './ModelMenuBridge.tsx'
+export { ModelPickerHost } from './ModelPickerHost.tsx'
+export { createPickerStore } from './picker-state.ts'
 
 /**
  * Cordis services required by the browser half. `slots` is the contribution
  * registry, `sessions` tells whether a session may select a model,
- * `modelDirectories` owns the per-session catalog snapshot this seat renders
+ * `modelDirectories` owns the per-session catalog snapshot both entries render
  * from, and `configForms` carries the settings provider's shared describe
  * mirror, which answers each model's context window and accepted modalities.
  * `remote`, `remote.llm`, and `remote.session` are declared because a service
@@ -39,9 +45,14 @@ export const inject = [
 ]
 
 /**
- * Client plugin body: register this plugin's dictionaries, then take over the
- * composer model seat below the built-in occupant's priority so this menu
- * renders in its place.
+ * Client plugin body: register this plugin's dictionaries, then contribute the
+ * bridge that turns the Host's model cell into the picker's door and its effort
+ * cell into the reasoning-level slider, the overlay that renders the picker, and
+ * the tint that keeps the collapsed trigger's effort caption on the same color.
+ *
+ * The two are separate entries because the Host unmounts the model menu the
+ * moment a row is clicked; the overlay slot stays mounted, so the dialog
+ * survives the menu's teardown.
  * @param ctx - client root context.
  */
 export function apply(ctx: ClientContext): void {
@@ -49,33 +60,59 @@ export function apply(ctx: ClientContext): void {
   ctx.inject(['slots', 'modelDirectories', 'configForms', 'remote'], (scope) => {
     const models = scope.modelDirectories
     const sessions = scope.sessions
+    const picker = createPickerStore()
     const facts = createFactsSource({
       describe: scope.configForms.describe() as DescribeFace,
       listProviders: () => scope.remote.llm.listConfigurableProviders(),
     })
     ctx.effect(() => facts.start(), 'dsh-model-submenu: model metadata')
-    scope.slots.inject('conversation.input.model', () => scope.slots.register({
-      name: 'conversation.input.model',
-      priority: -100,
+    /**
+     * Build one entry's business face for a session.
+     * @param sessionId - the slot's session scope.
+     * @returns the catalog face plus the session and store both entries need.
+     */
+    const faceOf = (sessionId: string) => {
+      // The slot's inject parameter is typed as a bare string; the service
+      // faces carry the branded SessionId of that same runtime value.
+      const key = sessionId as Parameters<typeof models.directoryFor>[0]
+      const directory = models.directoryFor(key)
+      const available = sessions.subagentAddress(key) === undefined
+      return {
+        sessionId,
+        picker,
+        available,
+        directory: directory.store,
+        factsSource: facts.source,
+        load: () => {
+          if (available) directory.load().catch(() => {})
+        },
+        resolveText: (text: Parameters<typeof ctx.locale.resolveText>[0]) => ctx.locale.resolveText(text),
+        select: (selection: Parameters<typeof directory.select>[0]) => available
+          ? directory.select(selection)
+          : Promise.resolve(undefined),
+      }
+    }
+    scope.slots.inject('conversation.input.model.options', () => scope.slots.register({
+      name: 'conversation.input.model.options',
+      id: 'model-menu-bridge',
       registrant: '@lynn123411/dsh-model-submenu',
       locale: NS,
-      inject: (sessionId) => {
-        // The seat's inject parameter is typed as a bare string; the service
-        // faces carry the branded SessionId of that same runtime value.
-        const key = sessionId as Parameters<typeof models.directoryFor>[0]
-        const directory = models.directoryFor(key)
-        const available = sessions.subagentAddress(key) === undefined
-        return {
-          available,
-          directory: directory.store,
-          factsSource: facts.source,
-          load: () => {
-            if (available) directory.load().catch(() => {})
-          },
-          resolveText: (text) => ctx.locale.resolveText(text),
-          select: (selection) => available ? directory.select(selection) : Promise.resolve(undefined),
-        }
-      },
-    }, ModelSubmenu))
+      inject: faceOf,
+    }, ModelMenuBridge))
+    scope.slots.inject('conversation.input.overlay', () => scope.slots.register({
+      name: 'conversation.input.overlay',
+      id: 'model-picker',
+      registrant: '@lynn123411/dsh-model-submenu',
+      locale: NS,
+      inject: faceOf,
+    }, ModelPickerHost))
+    // The trigger's effort caption lives outside the menu, so its tint needs an
+    // entry that stays mounted for the whole session.
+    scope.slots.inject('conversation.input.overlay', () => scope.slots.register({
+      name: 'conversation.input.overlay',
+      id: 'model-effort-tint',
+      registrant: '@lynn123411/dsh-model-submenu',
+      inject: faceOf,
+    }, EffortTint))
   })
 }

package/src/client/level-color.ts

@@ -0,0 +1,51 @@
+/**
+ * The accent one reasoning level carries.
+ *
+ * "Off" carries no accent at all — the fill and the caption stay neutral, so
+ * switching reasoning off reads as switching it off rather than as the first
+ * shade of a ramp. Every level above it walks a blue-to-violet ramp, and the
+ * highest level is the only one whose fill is a gradient.
+ */
+
+/** Off: the dimmed label tone, the same neutral the Host uses for quiet text. */
+const NEUTRAL = 'var(--dsw-alias-label-dimmed)';
+
+/** Lowest lit level: the blue the composer already uses for accents. */
+const LOW = [77, 147, 248] as const;
+
+/** Highest level: violet. */
+const HIGH = [147, 51, 234] as const;
+
+/**
+ * @param t - a point on the ramp, 0 at the lowest lit level and 1 at the top.
+ * @returns the ramp color there.
+ */
+function ramp(t: number): string {
+  const mix = (from: number, to: number): number => Math.round(from + (to - from) * t);
+  return `rgb(${mix(LOW[0], HIGH[0])}, ${mix(LOW[1], HIGH[1])}, ${mix(LOW[2], HIGH[2])})`;
+}
+
+/**
+ * @param index - the level's detent, 0 being "off".
+ * @param count - number of detents.
+ * @returns the level's color as a CSS color string.
+ */
+export function levelColor(index: number, count: number): string {
+  if (index <= 0) return NEUTRAL;
+  // The top level is always the violet end, even when it is the only lit one.
+  if (isTopLevel(index, count)) return ramp(1);
+  const span = Math.max(1, count - 2);
+  return ramp(Math.min(Math.max((index - 1) / span, 0), 1));
+}
+
+/**
+ * @param index - the level's detent.
+ * @param count - number of detents.
+ * @returns whether this level is the only one painted with a gradient.
+ */
+export function isTopLevel(index: number, count: number): boolean {
+  return count > 1 && index === count - 1;
+}
+
+/** The top level's fill: the whole ramp, ending on the color its text takes. */
+export const LEVEL_GRADIENT = `linear-gradient(90deg, ${ramp(0)}, ${ramp(1)})`;

package/src/client/locales.ts

@@ -1,20 +1,10 @@
-/** Locale bundles for the composer model menu and the picker it opens. */
+/** Locale bundles for the all-provider model picker. */
 
 /** Dictionary namespace owned by this plugin. */
 export const NS = 'modelSubmenu'
 
-/** Locale keys the menu and the picker render. */
+/** Locale keys the picker renders. */
 export type ModelSubmenuLocaleKey =
-  | 'trigger.fallback'
-  | 'trigger.loading'
-  | 'trigger.selectAria'
-  | 'trigger.aria'
-  | 'trigger.ariaEffort'
-  | 'menu.aria'
-  | 'menu.effort'
-  | 'menu.more'
-  | 'menu.hint'
-  | 'effort.providerDefault'
   | 'status.loading'
   | 'status.empty'
   | 'status.failed'
@@ -34,26 +24,19 @@ export type ModelSubmenuLocaleKey =
   | 'picker.hintClose'
   | 'meta.effort'
   | 'meta.images'
+  | 'effort.label'
+  | 'effort.providerDefault'
+  | 'effort.useDefault'
 
 declare module '@deepseek-ai/dsh-client-ui-slots' {
   interface LocaleNamespaceMap {
-    /** The composer model menu's copy. */
+    /** The all-provider model picker's copy. */
     modelSubmenu: ModelSubmenuLocaleKey
   }
 }
 
 /** Simplified Chinese dictionary (the key-set source of truth). */
 export const zh: Record<ModelSubmenuLocaleKey, string> = {
-  'trigger.fallback': '选择模型',
-  'trigger.loading': '正在加载模型…',
-  'trigger.selectAria': '选择模型',
-  'trigger.aria': '选择模型，当前 {model}',
-  'trigger.ariaEffort': '选择模型，当前 {model}，思考等级 {effort}',
-  'menu.aria': '模型与思考等级',
-  'menu.effort': '思考',
-  'menu.more': '更多模型…',
-  'menu.hint': '提示：切换模型或思考程度会使既有的提示词缓存失效。建议新建会话，避免额外的 token 消耗。',
-  'effort.providerDefault': '默认',
   'status.loading': '正在加载模型…',
   'status.empty': '没有可用的模型。',
   'status.failed': '模型列表加载失败：{message}',
@@ -73,20 +56,13 @@ export const zh: Record<ModelSubmenuLocaleKey, string> = {
   'picker.hintClose': '关闭',
   'meta.effort': '思考',
   'meta.images': '图片输入',
+  'effort.label': '推理等级',
+  'effort.providerDefault': 'Default',
+  'effort.useDefault': '切换为默认档位',
 }
 
 /** English dictionary, checked complete against the zh key set. */
 export const en: Record<ModelSubmenuLocaleKey, string> = {
-  'trigger.fallback': 'Select model',
-  'trigger.loading': 'Loading models…',
-  'trigger.selectAria': 'Select model',
-  'trigger.aria': 'Select model, current {model}',
-  'trigger.ariaEffort': 'Select model, current {model}, effort {effort}',
-  'menu.aria': 'Model and effort',
-  'menu.effort': 'Effort',
-  'menu.more': 'More models…',
-  'menu.hint': 'Changing the model or the effort invalidates the existing prompt cache. Start a new session to avoid the extra token cost.',
-  'effort.providerDefault': 'Default',
   'status.loading': 'Loading models…',
   'status.empty': 'No models available.',
   'status.failed': 'Model list failed to load: {message}',
@@ -106,4 +82,7 @@ export const en: Record<ModelSubmenuLocaleKey, string> = {
   'picker.hintClose': 'close',
   'meta.effort': 'Effort',
   'meta.images': 'Images',
+  'effort.label': 'Reasoning effort',
+  'effort.providerDefault': 'Default',
+  'effort.useDefault': 'Switch to the provider default',
 }

package/src/client/picker-state.ts

@@ -0,0 +1,55 @@
+/**
+ * Which session's picker is open.
+ *
+ * The row that asks for the picker lives inside the composer model menu, and the
+ * Host unmounts that menu the moment a row is clicked. The dialog lives in the
+ * composer's overlay slot, which stays mounted. One plugin-wide store carries the
+ * request across that unmount — the same split the Host's own command popups use
+ * between their controller and their overlay view.
+ */
+
+/** What the store publishes. */
+export interface PickerSnapshot {
+  /** Session whose picker is open, or null when none is. */
+  readonly sessionId: string | null
+}
+
+/** Open and close verbs plus the observable the overlay view subscribes to. */
+export interface PickerStore {
+  /** @returns the current request. */
+  readonly getSnapshot: () => PickerSnapshot
+  /** @param listener - called after every change. @returns the unsubscribe. */
+  readonly subscribe: (listener: () => void) => () => void
+  /** @param sessionId - open the picker for one session, replacing any other. */
+  readonly open: (sessionId: string) => void
+  /** Close whatever is open. */
+  readonly close: () => void
+}
+
+/**
+ * @returns a store that starts closed.
+ */
+export function createPickerStore(): PickerStore {
+  let snapshot: PickerSnapshot = { sessionId: null };
+  const listeners = new Set<() => void>();
+  const publish = (next: PickerSnapshot): void => {
+    if (next.sessionId === snapshot.sessionId) return;
+    snapshot = next;
+    for (const listener of listeners) listener();
+  };
+  return {
+    getSnapshot: () => snapshot,
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    open: (sessionId) => {
+      publish({ sessionId });
+    },
+    close: () => {
+      publish({ sessionId: null });
+    },
+  };
+}

package/src/client/selection.ts

@@ -9,6 +9,7 @@
  */
 
 import type { ModelReasoning } from '@deepseek-ai/dsh-api-session-controller/types'
+import type { ModelDirectoryState } from '@deepseek-ai/dsh-client-ui-model-selection/client'
 
 /** One complete selection, as the directory's `select` takes it. */
 export interface Selection {
@@ -25,26 +26,21 @@ export interface EffortChoice {
 }
 
 /**
- * Build the segments for one model's reasoning row.
+ * Build the slider's detents for one model.
+ *
+ * The provider default is deliberately absent: it is a state, not a level, and
+ * giving it a detent would read as the weakest reasoning instead of "let the
+ * provider decide". The label above the track switches to it.
  * @param reasoning - the catalog's reasoning metadata, undefined when the model has none.
- * @param providerDefaultLabel - the localized label for the "follow the provider" segment.
- * @returns the segments in catalog order; the provider-default one leads when the model declares no default.
+ * @returns one detent per advertised level, in catalog order.
  */
-export function effortChoices(
-  reasoning: ModelReasoning | undefined,
-  providerDefaultLabel: string,
-): readonly EffortChoice[] {
+export function effortChoices(reasoning: ModelReasoning | undefined): readonly EffortChoice[] {
   if (reasoning === undefined) return []
-  return [
-    ...reasoning.defaultEffort === undefined
-      ? [{ key: 'provider-default', effort: undefined, label: providerDefaultLabel }]
-      : [],
-    ...reasoning.efforts.map((level) => ({
-      key: level.id,
-      effort: level.id as string | undefined,
-      label: level.name,
-    })),
-  ]
+  return reasoning.efforts.map((level) => ({
+    key: level.id,
+    effort: level.id as string | undefined,
+    label: level.name,
+  }))
 }
 
 /**
@@ -92,6 +88,36 @@ export function planModelCommit(
   }
 }
 
+/**
+ * The reasoning metadata the catalog advertises for the model in force.
+ * @param state - the session's directory snapshot.
+ * @returns the metadata, or undefined when no model is live or it advertises none.
+ */
+export function liveReasoning(state: ModelDirectoryState): ModelReasoning | undefined {
+  const current = state.current
+  if (current === null) return undefined
+  return state.groups
+    .find((group) => group.id === current.provider)
+    ?.models.find((model) => model.id === current.model)
+    ?.reasoning
+}
+
+/**
+ * The selection in force, or null while the Host has not resolved one.
+ * @param state - the session's directory snapshot.
+ * @returns the live selection, with the effort only when one is set.
+ */
+export function selectionOf(state: ModelDirectoryState): Selection | null {
+  if (state.current === null) return null
+  return state.current.reasoningEffort === undefined
+    ? { provider: state.current.provider, model: state.current.model }
+    : {
+      provider: state.current.provider,
+      model: state.current.model,
+      reasoningEffort: state.current.reasoningEffort,
+    }
+}
+
 /**
  * @param live - one selection.
  * @param provider - the provider to compare.

package/src/client/slider.ts

@@ -0,0 +1,51 @@
+/**
+ * Geometry of the discrete effort slider.
+ *
+ * The track carries one detent per level and the knob's centre travels between
+ * two ends inset by the knob radius, so the knob never overhangs the track. A
+ * pointer position becomes the detent nearest it; a detent becomes a fraction
+ * of the track that CSS turns into the knob's centre and the filled width.
+ */
+
+/**
+ * Knob diameter in CSS pixels, and the track's height: the slider stands as tall
+ * as the row's text line. The centre stops half of it from each end of the
+ * track, so the knob never overhangs.
+ */
+export const KNOB_SIZE = 20;
+
+/**
+ * @param index - detent index.
+ * @param count - number of detents.
+ * @returns the knob centre as a fraction of the track, 0 at the first detent and 1 at the last.
+ */
+export function offsetOf(index: number, count: number): number {
+  if (count <= 1) return 0;
+  const clamped = Math.min(Math.max(index, 0), count - 1);
+  return clamped / (count - 1);
+}
+
+/**
+ * @param clientX - pointer position in viewport coordinates.
+ * @param left - the track's left edge in viewport coordinates.
+ * @param width - the track's width in pixels.
+ * @param count - number of detents.
+ * @returns the detent nearest the pointer, clamped to the two ends.
+ */
+export function stepAt(clientX: number, left: number, width: number, count: number): number {
+  if (count <= 1) return 0;
+  const usable = width - KNOB_SIZE;
+  if (usable <= 0) return 0;
+  const fraction = (clientX - left - KNOB_SIZE / 2) / usable;
+  const clamped = Math.min(Math.max(fraction, 0), 1);
+  return Math.round(clamped * (count - 1));
+}
+
+/**
+ * @param fraction - a knob position between 0 and 1.
+ * @returns the CSS length that puts the knob centre there, inset at both ends.
+ */
+export function knobOffset(fraction: number): string {
+  const clamped = Math.min(Math.max(fraction, 0), 1);
+  return `calc(${KNOB_SIZE / 2}px + ${clamped} * (100% - ${KNOB_SIZE}px))`;
+}